Development

4th Dimension Standard Edition | 4D Developer Edition | 4D Server Standard Edition | 4D Server Developer Edition | 4D Web 2.0 Pack

Deployment

4D Deployment Options | 4D Runtime Volume | 4D Server Application | 4D Web Server 4D Web Services Server

Solution Accelerators

4D Meetings

Customise 4D Business Kit To Fit Your Needs

Creating a Basic Store Using 4D Business Kit
Technical Note 02-19

Overview

In this tech note I will show how to setup a basic store using 4DBK. This tech note will mainly cover the HTML pages and the necessary 4DBK HTML tags that are needed to get your store online. There will be some discussion of how 4DBK is configured. I am making the assumption that the reader is familiar with the basics of 4DBK and HTML.

I picked a simple web site of a friend that is currently selling products via the Internet using Earthlink's Total Commerce Store to provide the eCommerce package and CyberCash/Verisign to provide the credit card processing. The major problem with this solution is that the store web pages cannot be configured to the detail level required so there is really two different sites, one that has the look and feel she wants to convey with her product and the other to actually order the products online. We will solve this problem by using 4DBK. You can see the existing EarthLink/CyberCash site at www.scenahair.com .

There are several sections to this tech note. First I will discuss setting up 4DBK to handle the store and its custom fields, then for each of the major HTML pages I will discuss the 4DBK HTML tags that are used to make the site work as desired. I have included the data file and all the 4DBK external files needed to get this demo running on your system. Just place the SCENA.4DD file and the SCENA_INFO folder in the same directory as your 4DBK application and startup the database using the SCENA.4DD data file (hold the option key down when starting 4DBK so you can pick the data file).

If you are planning on doing development of your 4DBK based site on a system running Mac OS X then these tips may help ease that process. First off, 4DBK v1.0 does not run under OS X, however it works just fine as a Classic application. When doing the development/testing of your web pages on a computer running OS X and 4DBK you should use a Classic mode web browser (Netscape 4.7x, IE 5.0x). It seems that you cannot cross the OS X / Classic boundary on the same system.

The example HTML pages included with this tech note are not meant to be an example of state of the art web design. They were designed to be straightforward simple pages that show the use of the 4DBK tags and not become cluttered with extra HTML tags. These pages were developed using a text editor, but you can use whatever HTML editing tool that you would normally use to design sites. All the 4DBK HMTL Tags are written as comments, arguments to HTML tags or JavaScript code.

Setting up 4DBK

There are several places that need to be configured in 4DBK. The layout/order of the menus in 4DBK is a little confusing, so I will talk about the options in the order they need to be configured, not the order that they are shown in 4DBK. This example does not use any of the built-in store templates. For this tech note I will be discussing the specific additions I made for this tech note/example database.

File/New menu:

This is where you can create a new store from scratch. Do not use the New Store Wizard unless you are loading a pre-configured store to look at its web pages. Use the Manually button to actually create your store.

File/Stores menu:

Once you have created a store this is where most of the basic information about your store is kept and configured. There can be multiple stores setup in 4DBK, each of which is configured separately.

Data/Data Models menu:

This is where any custom fields are configured for each Store. I have configured the following custom fields for this example.

Code 1 (C01) = product_id - This is set to be a unique ID of each product

Text 1 (T01)) = label - This is used as the product name

Family 1 (F01) = category - This is used to separate the products

Data/Family 1 menu:

Where you configure the various categories of products, i.e. Shampoos, Conditioners, and Styling Products.

Data/Shipping options menu:

Used to set shipping options and charges. For this site I set the shipping rate based on the order total.

Data/State Taxes menu:

Used to setup the states and tax percentages where you charge sales tax.

Data/Items menu:

This is where you add specific information about your products. Many of the configuration items that we setup previously are used within this section.

File/Preferences menu:

Here you will find the preferences for setting application wide features like the HTTP Port and most importantly the Licenses window. You can have as many stores as you'd like configured in 4DBK but only the stores that have been marked as Active will not have a time limit on their use.

4D Portal allows you to have many different portals. You may have as many portals as you want, as long as you have different domain names, machine names, or IP addresses for this machine.

4DBK HTML Tags

Once all the 4DBK options have been set its time to begin editing your web pages to include the 4DBK HTML tags that will populate your pages when served by 4DBK. The 4DBK HTML tags are very similar to many of the 4D HTML tags. If you have used 4D to serve pages in non-contextual mode before then many tags in 4DBK should be familiar. If you haven't done so, then the following will help explain the concepts.

All 4DBK HTML tags are written as HTML comments:

Where xxx is the 4DBK command. 4DBK tags can also be used as arguments to standard HTML tags

or included in JavaScript code. We will show all of these methods of using 4DBK Tags in the following example pages.

All form input validation is done via JavaScript. The reason for this is that 4DBK is a compiled application and there is no way to modify the 4D code to handle this aspect of the site. 4DBK includes several JavaScript libraries, which makes the coding of common functions (formatting values, checking for blank values, etc.) much easier.

The Example Web Pages

In the following sections we will look at each of the HTML pages that make up this site. We will be focusing on the 4DBK tags and what they do, rather than the HTML functions.

Information Pages

index.htm
miscQA.htm
miscTestimonals.htm
miscAbout.htm
miscOther.htm

These pages are pretty much static pages with the exception that they each have a couple of 4DBKInclude/xx tags which insert a standard HTML header and footer when the page is served.

Common Header/Footer pages

stdHeader.htm

stdFooter.htm

These two pages are inserted into each HTML page so that we can keep a consistent look and feel to the web site.

The stdHeader.htm page has the following section of 4DBK Tags included in it. This code checks to see if there is a current shopping cart for the user and if so it shows the running total of the shopping cart.

<hr width="450">

<a href="orderLogin.htm">Shopping Cart - </a>

<a href="orderCart.htm">Shopping Cart - </a>

The first line of this section on HTML code is very important. Since 4DBK can serve multiple stores from the same database, it's important to tell 4DBK which store is currently being referenced on each page that uses 4DBK HTML page.

The next couple of lines checks to see if there is a current shopping cart started. If there is then the tag 4DBKField/PrItemsEXV will contain the subtotal of the shopping cart. If that value is not zero, we then check to see if the user has already logged in to the store with the line:

Depending on whether or not they are logged in we show either the order total with tax and shipping or just the subtotal of all the products prices.

Products pages

prodShampoos.htm

prodConditioners.htm

prodStylingProducts.htm

There are three product pages that each correspond one of the three Product Categories or Family 1 values. Each page is almost identical with the exception of the .jpg file and the selection of which Product Family to load.

The relevant piece of HTML code from one of the pages looks like this:

Here is an analysis of the code:

We need to start any section of code that works with records in the database by referencing which store we are working with by using the 4DBKStoreSet tag.

We then tell 4DBK which Selection Set we are going to use, in this case set 1. There are 5 sets available plus a specialised set for the shopping basket, which is set B.

We then perform a Query for all products that are in the Family (field L01) of "Shampoos".

Next we specify which field is used to sort the selection of records. In this case we specify the product_id (field C01).

The actual sort is done here.

We then set current record of the selection to the first record.

The following four lines loop through all the selected records (L01 equal "Shampoos") and insert the HTML page stdDetail.htm for each record. We will describe the contents of stdDetail.htm in a moment. The structure of this code is very similar to a FOR/END FOR loop in 4D code. The variable VL01 is a generic Longint variable that can be used in your HTML code, there are 20 each of VLxx (longint), VRxx (real) and VTxx (text) variables.

stdDetail.htm

This page is the where we define the HTML for each individual product to be included in the list. This section of HTML code is inserted into the pages above once for each product in the selection.

<tr>
<td width="55"> </td>
<td width="450"><b></b><br>
<br>
<br>
<table border="0" cellpadding="0" cellspacing="2" width="450">
<tr>
<td></td>
<td align="right">
retail price:
</td>
</tr>
<tr>
<td> </td>
<td align="right">
<a href="4DBKExecute:4DBKStoreSet/SCEN;4DBKQuantitySet/
+1;4DBKBasketSet/!4DBKField/C01">Add to Shopping Cart</a>
</td>
</tr>
</table>
</td>
<td width="55"> </td>
</tr>
#4DBKSelectionSize)-->
<tr>
<td width="55"> </td>
<td width="450"><hr></td>
<td width="55"> </td>
</tr>

The various #4DBKField/xxx lines are putting data from the database into the page based on the current record in the loop. For the fields that contain price information we are formatting the data using the .USD,$###,##0.00 addition to the tag.

The code in the line:

<a href="4DBKExecute:4DBKStoreSet/SCEN;4DBKQuantitySet/
+1;4DBKBasketSet/!4DBKField/C01 ">Add to Shopping Cart</a>

is where we actually add a product to the shopping cart. In this case we are using a 4DBKExecute command, which is a self-contained code statement. When using 4DBKExecute we must use 4DBKStoreSet/xxxx first before any other command, in this case we then tell it to add one of the records referenced by C01 (product_id) to the current shopping cart. If there is no current shopping cart (i.e. this is the first product selected) then a new shopping cart is created automatically. Note that a semicolon separates each 4DBK command. We also use a ! in front of the 4DBKField/C01 command. This tells the browser to use the actual value of the variable when 4DBK inserts the tag into the page and not when the user clicks the link.

The last bit of 4DBK code is the line:

This is where we check to see if this is the last record in the selection, if it is the last record then we skip the HTML code, which puts a line after each product detail record. VL01 is the loop counter from the prodxxx.htm page that this section of code is being inserted into.

Login and Account page

Once the user has selected the products they wish to purchase we need to give them a way to enter their Billing and Shipping information as well as see all the products in their current shopping cart. If they have not already logged in, then when they click the Shopping Cart link at the top of the page they will be taken to the orderLogin.htm page. At this point they can login with a valid Login/Password or create a new account. We will take a look at the order Account.htm page first then come back to the orderLogin.htm page.

- orderAccount.htm

On this page we actually need to enter data into a form and check for valid or missing entries. All error checking is done using JavaScript. Since this is a relatively large section of code, I am not going to reproduce it all here. For the complete code see the example database and HTML files included with this tech note. There are three pieces to that we are concerned with on this page.

The actual HTML form where the user enters their data.
The validation JavaScript used to check the entries.
The JavaScript that submits the completed form to 4DBK

The HTML form for entering data is pretty straightforward. We use this form for adding records as well as modifying them so we use the value attribute of the Input tags. The only non-trivial part of this form is the form tag itself.

In this tag we call the JavaScript method CheckCustomerForm when submitting the form. This allows us to check for all the required fields, etc. It does the checks by using some JavaScript Libraries that are included with 4DBK. These JavaScript Libraries can be used as is, you can open them and modify them as needed or you can replace them with your own JavaScript libraries.

Once the form is properly completed then we use the JavaScript function WriteCustomerForm to actually send the data to 4DBK. This JavaScript code bundles all the data into a 4DBK Execute statement, which then actually updates the database. If this completes correctly then the user is redirected to the orderCart.htm page where they can continue with their order. At this point 4DBK keeps track of the user and they will not have to sign in again unless they are idle for a user definable period of time, they logout, or they close their browser window.

It should be noted that 4DBK will not save a shopping cart past the idle time out. Only once they have successfully completed an order will their order be stored in the database and their shopping cart cleared for the next round of purchases. The timeout function is set under the File/Stores menu item for each individual store.

- orderLogin.htm

This where the end-user signs-in to complete their shopping cart. The user must login before they can continue past this point.

Once again this page is pretty straightforward. Here are the interesting sections.

The JavaScript at the top of the page:

The form statement:

And towards the end of the page the error display section:

You did not enter a login...
You did not enter a password...
Your customer account has been frozen...
This password is invalid...
This login is invalid...

The first section of JavaScript just tells the browser to load whichever page is sent to it from the <form…> function. If the user logs in correctly they are directed to the orderCart.htm page or else they are asked to retry their login again at orderLogin.htm. If they have problems logging in, the 4DBKCaseOf section of HTML code shows the appropriate error message. This command behaves very similar to the CASE OF/END CASE statements in 4D. The form statement is another 4DBKExecute statement that bundles the form data (code/password) together and submits it to the database for verification using the 4DBKCustomerLogin command. Depending on whether or not the user put in a valid code/password combination, they are either taken to the next page, orderCart.htm, or returned to the orderLogin.htm page to retry their login.

Shopping Cart page

orderCart.htm

This page allows the user to modify their Bill To or Ship To information as well as add or delete products to their shopping cart. As in the orderAccount.htm page there is a JavaScript handler to check for correct data entry and to format the data. There is also a JavaScript handler to save the data about the Bill To and Ship To Address fields. There is a loop to show all the items in the shopping basket and a couple of links to Add or Remove items to the basket. You can also modify the basic information about the account or logout and start the process all over. Note that in this example, if you logout, any items in your shopping basket are still stored in the cart, it's just not attached to a particular user until they log in again from the same computer or it times out. One note, we are now using the command #4DBKSelectionSet/B in order to show the user's shopping cart items.

Credit Card page

- orderPayment.htm

The user can enter their credit card information on this page. Once again there is a couple of JavaScript functions, one to check to make sure all the fields are entered appropriately and one to do the actual submission to the database. This last function, ValidateOrder, has several interesting items. First of all it collects the data to be stored in the database in a similar fashion as the other pages we've looked at. Next it sends an email to the user with their order details included in it. An email is sent to the user using the HTML page orderEMail.htm file. Then the order is completed using the 4DBKOrderValidate command. This closes the order and commits it to the database so that it shows up under the Data/Orders menu section. Once this command is executed the order is committed to the database and there is no way to modify it or change the order from the end users perspective, it has been completed at this point. In this JavaScript function you may want to actually charge the users credit card at this point and not just store it for later processing. In that case, before the 4DBKOrderValidate is issued you would need to send a 4DBKCreditCardProcess command to do the actual processing.

- orderEMail.htm

If the credit card information is entered correctly the database will send an email to the customer. This email can be used as the receipt for the customer and can contain any of the tags that are valid for that order. The emails are sent using HTML formatting.

Confirmation page

orderOK.htm

If the order is completed correctly then the orderOK.html page is shown, otherwise it returns to the orderPayment.htm page and show the reason the order was not completed. At this point the order is actually stored in the 4DBK data file and the shopping cart is automatically cleared for the next order. You can use this page to thank the customer or return an order number for future reference.

Conclusions

This is a simple example of how to setup and configure 4DBK. There are many more options that will be explored in future technical notes.

Other resources for information about 4DBK:

The 4DBK Advanced Technical Manual covers three main areas; Importing/Exporting your data, Credit Card Payment options, and details about the 4DBK Component. PDF format only

The 4DBK Language Reference covers all aspects of the HTML tags that are available. This is the main source of information about how the tags works and their parameters and examples of how to use them. This file is included in both PDF format and HTML format.

4DBK User Reference is primarily a guide to all the features of the 4DBK application. It has sections on setting up SSL, hosting options, etc. PDF format only.

4DBK QuickStart is the only printed manual that describes the basic operation and lets you get a demo site up very quickly. It is very little help in designing/debugging your custom site. PDF and printed formats.

Sebastian Frey wrote TN 02-7, "The 4DBK IP Component", in which he discusses the issues of transferring information from your existing 4D application into the 4DBK application using the IP component that comes with 4DBK. He also includes information on setting up the credit card transaction features of4DBK. PDF and example database

Summary

This tech note shows how to setup a basic store using 4DBK. This tech note will mainly cover the HTML pages and the necessary 4DBK HTML tags that are needed to get your store online.

Extra

Minimum System

Windows
Pentium II minimum
800 X 600 monitor resolution
Windows 2000, Windows XP.
256 MB RAM minimum

MacOS:
G3 or better processor
800 X 600 monitor resolution
Mac OS X v10.2.8 or later
256 MB RAM minimum

When the solution matters

International Sites

Product Lines

Solutions

Corporate

Support

Purchase