uCatalog Interactive CD-ROM E-commerce System

Last Update: November 29, 2000

Table Of Contents
1. Introduction	Section 1
2. Features	Section 2
3. System Requirements	Section 3
4. Steps In Creating A CD-ROM Catalog	Section 4
5. Setting Up Directory Structure	Section 5
6. Setting Up Catalog Pages/Applets	Section 6
6.1 Input Applets	Section 6.1
6.2 JavaScripts	Section 6.2
7. Special Applets	Section 7
7.1 Initialize Applet	Section 7.1
7.2 Shopping Cart Applets	Section 7.2
7.3 Search/Browse Applets	Section 7.3
7.3.1 Data File Format	Section 7.3.1
7.3.2 Product HTML Template	Section 7.3.2
7.4 Order Button Applets	Section 7.4
8. Setting Up Order Form	Section 8
9. Setting Up Tax Rates	Section 9
10. Setting Up Shipping	Section 10
11. Setting Up Handling	Section 11
12. Installing/Customizing The CGI Script	Section 12
13. Testing	Section 13
14. Troubleshooting	Section 14
15. Creating CD-ROMs	Section 15
16. Internationalization	Section 16
17. Creating Your Own Java Applets	Section 17
18. Creating Your Own JavaScripts	Section 18
19. Other References	Section 19

1. Introduction

uCatalog^TM is a shopping system created by Microburst Technologies, Inc. and designed specifically for creating interactive catalogs on CD-ROM. uCatalog^TM consists of a series of Java applets and JavaScripts that run locally on the customer's browser and do not require any interaction with a web server....thus making it the ideal system for putting interactive catalogs on CD-ROM.

2. Features

Practical features of uCatalog^TM include:

The ability to create interactive catalogs/stores on CD-ROM.
uCatalog^TM consists of a series of Java applets and JavaScripts that run locally on the customer's browser. This makes uCatalog ideal for setting up interactive stores on CD-ROM since the system is stand-alone and does not require any interaction with a web server.

The ability to allow customers to save, print or place orders online.
uCatalog^TM makes it possible for customers to save their orders (to continue shopping or complete their order at a later time), to print out their orders (for phone, fax or mail orders) or, if connected to the internet, to place their order online.

The ability to run with most standard web browsers and operating systems.
uCatalog^TM applets run from any standard HTML page. This means that any Java-enabled browser can be used to view the CD-ROM Catalog and no additional viewing software/application needs to be installed on the customer's computer.

Complete flexibility when designing the layout/navigation of the CD-ROM Catalog.
uCatalog^TM uses a unique mechanism for maintaining data and handling communication between the various applets. This allows the uCatalog applets to be added virtually anywhere on the CD-ROM Catalog pages. The result is that no specific page layout or page navigation scheme is required - developers are free to design the catalog pages however they like!

The ability to use any HTML tools/editors to create the CD-ROM Catalog.
Since uCatalog's applets run from any standard HTML page, any standard HTML editor can be used to create the pages for the CD-ROM Catalog. This means there is virtually no learning curve associated with learning a new development tool.

The ability to add multimedia capabilities to the CD-ROM Catalog.
Since uCatalog's applets run from any standard HTML page and use any standard browser, CD-ROM catalogs can utilize all of the latest Multimedia capabilities that are supported by the browsers.

A simple API to allow developers to create their own Java Applets and JavaScripts.
uCatalog^TM offers an easy-to-use Application Programmer Interface (API) that enables developers to create their own Java Applets and JavaScripts to interface with the uCatalog^TM Applets.

The ability to put the CD-ROM Catalog Online too!
Since catalogs/stores created with uCatalog^TM consist of standard HTML components, the entire CD-ROM catalog can also be placed online.

A Powerful E-commerce System!
uCatalog^TM applets have been designed to handle a large variety of product options, prices, quantities, tax rates, shipping calculations, credit card validations, languages, and even a flat-file database that can perform searches and dynamically generate product pages!

3. System Requirements

The system requirements of uCatalog^TM are as follows:

1. System Requirements of the Store Owner/Web Developer

Any text or HTML editor.

If intending to put the interactive catalog/store on CD-ROM, then you must have your own CD-ROM Recorder and recordable CDs.

If intending to provide an online ordering option, then you must have a secure server upon which you can install Perl CGI scripts.

2. System Requirements of the Customer

Since uCatalog consists of a series of Java applets and JavaScripts, the only requirement levied on the customer is that the customer must have a browser that supports Java and Java Scripts, such as Netscape 4.x, Internet Explorer 4.x or AOL.

4. Steps In Creating A CD-ROM Catalog

Creation of an interactive CD-ROM catalog with uCatalog^TM consists of the following steps:

Setting up your directory structure on your development computer.
Creating your catalog's HTML pages and adding any number of uCatalog Input Applets to the pages as the means by which customers can add items to the shopping cart.
Creating/customizing your catalog's order form.
Setting up tax rates and shipping calculations.
Optionally, setting up the uCatalog^TM CGI script on your secure server if you want to offer an online payment option.
Testing your interactive store.
Putting your catalog on CD-ROM

Each of these steps is described in detail in the following sections of this User's Guide.

5. Setting Up Directory Structure

Typically, the root directory on the interactive CD-ROM will consist of nothing more than an "index.html" file, a main "store" directory, and possibly an additional directory for non-store related information. By keeping the contents of this root directory simple, it is easier for customers to get started by locating and opening the "index.html" file in their browser. Once they get the "index.html" file opened in their browser, you can link them to any directory/subdirectory on the CD-ROM that you want. This is illustrated in the figure below.

Figure 5.1 The Root Directory Of The CD-ROM

An important thing to remember when developing an interactive catalog for a CD-ROM is that all directory paths for links, images, class files, etc., must be specified relative to the current directory. You obviously can not refer to links/images via a full URL (since the customer may not be connected to the internet), but also you can not assume that a customer's CD-ROM will be his or her D: Drive or E: Drive.

Furthermore, because uCatalog^TM is Java-based and because various browsers handle caching Java Applets differently, there is a specific directory structure that should be used for your interactive CD-ROM catalog. This recommended directory structure is based on experience in dealing with Java and the various browser differences and is illustrated in the figure below.

Figure 5.2 The Store Directory Structure

As shown in figure 5.2, you should make a "classes" subdirectory in your store directory. In this "classes" directory you should put ALL of the ".class" files that came with uCatalog, the ucatalog_javascript.js file, and the 8 or so ucatalog template files. This way, any HTML pages located in any of the "html" directories can refer to the items in the classes directory via the relative codebase "../classes/". (The codebase will be discussed further in the next section.)

Note: You can make as many "html" directories for your store as you like, however, it is important that they are all on the same directory level. That is, put all "html" directories on the same directory level as your "classes" directory.

So to sum up what you need to do to create the necessary directory structure for your CD-ROM store, on your development computer:

Create your main store directory. You can actually call this directory anything you want - but we will refer to it as your "store" directory.

Create a directory called "classes" as a subdirectory of your main store directory. Initially, you should have the following files located in this directory:
- Approximately 40 .class files
- ucatalog_javascript.js
- ucatalog_message.html
- ucatalog_online.html
- ucatalog_order.html
- ucatalog_print.html
- ucatalog_product.html
- ucatalog_review.html
- ucatalog_search.html
- ucatalog_template.html
You may not actually need all of these files, but initially they should all be put in this directory.

Create at least one "html" subdirectory. This is the main html directory that will be linked to when the customer wants to begin the interactive shopping experience.

Create an "images" directory as a subdirectory of your main store directory. This directory will be used as a common directory for image files. It is not required, but will make referring to/referencing images easier.

6. Setting Up Catalog Pages/Applets

Upon setting up your directory structure on your local computer, you can begin creating your catalog pages. This process simply involves using any text or HTML editor to create your product pages. The pages should be standard HTML pages (located in any of your "html" directories) and can utilize any multimedia capabilities that are supported by the browsers you intend to support. The beauty of a CD-ROM catalog is that you don't really have to worry about file sizes and download time because everything will be read locally from the CD-ROM....So don't be afraid to utilized images, sounds files, animations, movies, and any other multimedia capabilities to enhance your products pages and the customer's interactive shopping experience.

In addition to putting product descriptions and multimedia capabilities on your catalog's HTML pages, you will also need to have a way to allow customers to select items that they want to purchase and add them to their virtual shopping cart. This is done via the use of uCatalog's Input Applets and Input JavaScripts. The uCatalog^TM Input Applets and JavaScripts are described in the following two sections.

6.1 Input Applets

uCatalog^TM comes with a variety of Input Applets that can be used to "Add" or "Input" items into the shopping cart. These applets have been designed to plug easily onto any web page, thus giving you almost total creative freedom when designing your web pages. That is, you can put any product descriptions, images and/or sounds on your pages - using regular HTML - and then add any of the various uCatalog^TM Input Applets onto the pages as the means for adding the items to the shopping cart.

The uCatalog^TM applets are added to your HTML pages via the standard <APPLET> HTML tags and configured via some easy-to-use parameters. The figure below shows an example applet and the HTML used to create the applet.

Figure 6.1.1 Example Applet and HTML

uCatalog^TM comes with a large variety of Input Applets for handling various options, prices, and more! Check out the uCatalog^TM Applet Reference for a complete list of all of the applets included with uCatalog^TM as well as complete descriptions and examples of each of the applets.

Note: If you have never used Java applets before and/or would like to see how to utilize the uCatalog^TM applets, it is recommended that you try the uCatalog^TM Tutorial.

Need To Create Your Own Custom Input Applets?

In order to further increase uCatalog's flexibility, we have released the Java API for the uCatalog^TM Input Applets. This allows you to create your own custom Input Applets. See the uCatalog^TM Programmer's Guide for more information about creating your own custom Input Applets.

An Important Note About The "codebase" Parameter

When adding the uCatalog applets to your store pages, you must use the special "codebase" parameter to specify where the Java "class" files are located. As was shown in Figure 6.1.1 above, the "codebase" parameter is specified on the same line as the <APPLET> tag. The value of this parameter should be the relative path to your "classes" directory and must be set to the exact same value for all of your uCatalog applets. So in other words, just remember to set the codebase of ALL of your applets to codebase="../classes/".

6.2 JavaScripts

uCatalog^TM has also provided a special JavaScript Interface Applet and an "Add Product" API (Application Program Interface) that allows you to create your own JavaScripts to interface with uCatalog^TM. Like the uCatalog^TM Input Applets, the JavaScripts can plug onto any web page. Observe the example in the figure below.

Figure 6.2.1 Example Input JavaScript

Note in this example that the quantity entry box and the "Add To Cart" button are just standard HTML <FORM> components. In fact, all components of this example are standard HTML and JavaScript components - with the exception of the call to the "addProduct()" function. The addProduct() function provides the means to add an item to uCatalog's shopping cart. This means that you can create any custom HTML/JavaScripts that you want and interface them with uCatalog^TM by calling the addProduct() function. The parameters of the addProduct() function include the Product's ID, Name, Description, Weight, Quantity, Individual Price, Any Special Price Modifiers, the Classification, Any Shipping Modifier, and an indication of whether the product is Taxable or not. See the uCatalog^TM Programmer's Guide for a complete description of these parameters as well as other special uCatalog^TM JavaScript functions.

One Important Note to remember about using any of uCatalog's JavaScript functions/API, is that you must add the special uCatalog^TM JavaScript Interface Applet to any page that will be using the JavaScript API. This uCatalogJSI applet is a special JavaScript Interface Applet that provides the means by which JavaScripts can call Java functions. Only one instance of this applet needs to be added to each page that will be using the uCatalog^TM JavaScript API, And typically, the applet is added at the very bottom of the page (just before the closing </BODY> tag) with a WIDTH of 2 and HEIGHT of 2 ... to make it virtually invisible. The HTML to add this applet to your pages is shown in the figure below.

Figure 6.2.2 Example HTML For The JavaScript Interface Applet

Five JavaScript Input Examples have been included in the uCatalog^TM Applet Reference. See the uCatalog^TM Programmer's Guide for more information about creating your own custom JavaScripts to interface with uCatalog^TM.

7. Special Applets

In addition to the various Input Applets that were described in the previous section, uCatalog^TM also provides a variety of other applets that can be used for configuring general store preferences (such as tax and shipping calculations), displaying the contents of the shopping cart, performing searches, and initiating the order process. A brief overview of these applets is provided in the following sections.

For a complete description of all of uCatalog's applets, see the uCatalog^TM Applet Reference.

7.1 Initialize Applet

The uCatalogInitialize applet provides the means by which you can configure tax rates, shipping rates, handling fees, and many other general settings for your store. In addition, it handles reading in your order template files and loading some of the fundamental uCatalog^TM class files.

Although not required, ideally this applet should be placed on one of your store's main entrance pages (Similar to what we have done for the uCatalog^TM Demonstration Store). By putting this applet on one of the initial HTML pages of your store, it ensures that all of the general settings are applied as soon as possible. Furthermore, it gets time consuming initialization operations such as reading the order template file and loading the foundation uCatalog^TM class files, over with immediately. This allows the rest of the shopping experience to be uninterrupted and perform better.

To find out more about the parameters of the uCatalogInitialize applet, see the uCatalog^TM Applet Reference.

Note that setting up tax, shipping and handling preferences with the uCatalogInitialize applet will be discussed further below in the sections on setting up the order form and setting up the tax, shipping and handling.

7.2 Shopping Cart Applets

The uCatalogCart applets provide the means by which you can allow customers to view/modify the current contents of their virtual shopping cart. uCatalog^TM currently has three different "Cart" applets that provide options ranging from showing the full details of each item that has been added to the shopping cart - down to an option to just show the current quantity, subtotal, or total of items in the shopping cart.

When setting up your CD-ROM catalog/store, it is recommended that you create at least one HTML page that can be used as a "View Cart" page. On this page, you should put a large version of the uCatalogCart1 applet so that customers can go to this page at anytime to view the full details of the items currently in his/her virtual shopping cart.

If using a "FRAMES" layout for your CD-ROM catalog/store, you may also want to put a smaller version of the cart - perhaps the uCatalogCart2 applet - in one of the frames. This way, customers can immediately see items get added to their shopping cart when they press the product's "Add" button.

See the uCatalog^TM Demonstration Store for a working example of a main "View Cart" page and a working example of a small cart applet in a navigation frame.

To find out more about the uCatalogCart applets and their parameters, see the uCatalog^TM Applet Reference.

7.3 Search/Browse Applets

As an alternative to adding all of your store products to static HTML pages, uCatalog provides several "search" and "browse" applets that read the product information from flat-text files and then dynamically generate the product pages. For complete descriptions of these applets and their parameters, see the uCatalog^TM Applet Reference. For specific examples of how each applet is intended to be used, see uCatalogSearch1, uCatalogSearch2, uCatalogBrowse1, and uCatalogBrowse2.

The sections below focus on describing the format of the data files used by these applets and on how to create templates for the product pages that are dynamically generated by these applets.

7.3.1 Format Of Data Files

The data files used by the uCatalogSearch and uCatalogBrowse applets are standard bar-delimited text files. Each product in the file is listed on a separate line and each line in the file is separated into 15 bar-delimited fields. The table below describes each of the 15 fields associated with each product in the file.

	Field	Description
1	ID	The product's ID. Can be any combination of letters/numbers.
2	Name	The product's Name. Can be any text string.
3	Full Description	A full description of the product. This description will be displayed on the dynamically generated product page. It can be a text string of any length and may contain any number of HTML tags. Note: Do NOT include any bar (\|) characters in this description since the bar (\|) is a special character that is used as the field delimiter in the file.
4	Brief Description	A brief description of the product. This brief description will be used when the item has been added to the shopping cart. It can be any text string, but is usually under 50 characters. You should not use any HTML tags in this parameter.
5	Option 1	The first set of options for the product - if any. The options must be comma-delimited and may contain price modifiers as described in the reference for the option parameter. If the product does not have any options, then leave this field blank.
6	Option 2	The second set of options for the product - if any. The options must be comma-delimited and may contain price modifiers as described in the reference for the option parameter. If the product does not have any options, then leave this field blank.
7	Option 3	The third set of options for the product - if any. The options must be comma-delimited and may contain price modifiers as described in the reference for the option parameter. If the product does not have any options, then leave this field blank.
8	Weight	The weight of one unit of the item.
9	Quantity	The default quantity of the item.
10	Price	The price of the product. The price may be specified as a specific value or as a price table as described in the reference for the price parameter.
11	Classification	The classification of the product. This field may be left blank or used in correlation with a price table as described in the reference for the price parameter.
12	Shipping Modifier	Any shipping charge modifier associated with the product.
13	Taxable	An indication of whether the product is taxable or not. If the product is taxable, set this field to "YES". Otherwise, set this field to "NO".
14	Keywords	A list of keywords that may be used to identify the product in searches. Can be any number of keywords, each separated by a comma.
15	Image	The name of the image that is associated with the product. Note that you do not need to specify the directory path of the images, since that is specified by the "search" or "browse" applet's "image_directory" parameter. Note that if the product does not have an image, then leave this field blank.

Table 7.3.1 Product Data File Fields

To see an example data file, Click Here.

7.3.2 Product HTML Template

The format of the product pages that are dynamically generated by the uCatalog^TM "search" and "browse" applets is controlled by the "ucatalog_product.html" file (located in the "classes" directory). This file is nothing more than a standard HTML file with some special keywords used to indicate where the product fields will be inserted. Feel free to modify the "ucatalog_product.html" file to satisfy your preferences. To assist, a table describing the 6 keywords has been provided below.

	Keyword	Description
1	UCATALOG_ID	This keyword will be replaced by the product's ID.
2	UCATALOG_NAME	This keyword will be replaced by the product's Name.
3	UCATALOG_DESCRIPTION	This keyword will be replaced by the product's full description.
4	UCATALOG_PRICE	This keyword will be replaced by the product's price.
5	UCATALOG_IMAGE	This keyword will be replaced by the product's image.
6	UCATALOG_APPLET	This keyword will be replaced by the product's input applet.

Table 7.3.2 Product Template Keywords

7.4 Order Button Applets

The uCatalogOrderButton1 or uCatalogOrderButton2 applets are used to configure such order process preferences as the ordering instructions, whether to provide a print order option, whether you want to provide a save order option, and whether to provide an online order option. In addition, the uCatalogOrderButton applets provide the means by which the customer can initiate the order process. It is recommended that this applet (a.k.a. "Order Button") be placed on a "Place Order" page - possibly with instructions on how the order process works. As an example, see the "Place Order" page in the uCatalog^TM Demonstration Store. (In that demo, the uCatalogOrderButton1 applet is actually configured to be displayed as the "Step 1" image.)

To find out more about the parameters of the uCatalogInitialize applet, see the uCatalog^TM Applet Reference.

8. Setting Up Order Form

Setting up the order form for your CD-ROM catalog consists of nothing more than creating a standard HTML form with some pre-defined field names. That is, you can make your order form look however you like and contain any fields that you like by simply creating a standard HTML form and naming the fields of the form after some predefined uCatalog^TM order form field names. The table below contains a complete list of the predefined order form field names. For each of the fields in the table, there is also an indication of the type of <FORM> element each field can be - such as a "text" form element, a "textarea" form element, or a "selection" form element. Note that all of the fields in the table do not have to be used on your order form - just use the one's you want.

	Predefined Field Name	Valid Form Element Types
1	billing_first_name	text
2	billing_last_name	text
3	billing_company	text,select
4	billing_customer_id	text,select
5	billing_street1	text,textarea
6	billing_street2	text,textarea
7	billing_city	text
8	billing_state	text,select
9	billing_zip_code	text
10	billing_country	text,select
11	billing_phone	text
12	billing_fax	text
13	billing_email	text
14	billing_url	text
15	billing_extra1	text,textarea,select
16	billing_extra2	text,textarea,select
17	billing_extra3	text,textarea,select
18	billing_extra4	text,textarea,select
19	billing_extra5	text,textarea,select
20	billing_tax_rate	text,select
21	billing_comments	text,textarea
22	shipping_first_name	text
23	shipping_last_name	text
24	shipping_company	text,select
25	shipping_customer_id	text,select
26	shipping_street1	text,textarea
27	shipping_street2	text,textarea
28	shipping_city	text
29	shipping_state	text,select
30	shipping_zip_code	text
31	shipping_country	text,select
32	shipping_phone	text
33	shipping_fax	text
34	shipping_email	text
35	shipping_url	text
36	shipping_extra1	text,textarea,select
37	shipping_extra2	text,textarea,select
38	shipping_extra3	text,textarea,select
39	shipping_extra4	text,textarea,select
40	shipping_extra5	text,textarea,select
41	shipping_method	text,select
42	payment_method	text,select
43	cc_name_on_card	text
44	cc_number	text
45	cc_expiration	text,select
46	cc_issue	text
47	echeck_bank_name	text
48	echeck_bank_address	text,textarea
49	echeck_name_on_check	text
50	echeck_check_number	text
51	echeck_account_number	text
52	echeck_routing_number	text
53	echeck_transit_code	text

Table 8.1 Order Form Field Names/Types

In addition to creating a <FORM> with the field names listed in Table 8.1, there are also a few special tags that you must add to your order form page. These special tags are listed/described in the table below.

	Special Tag	Description
1	orderform	This is the predefined NAME that must be given to your HTML <FORM>. That is, when starting your HTML <FORM>, you should specify the name for it as "orderform". For example: <FORM NAME="orderform">
2	<UCATALOG INSTRUCTIONS>	This special tag (with the < and > signs around it) will be replaced during runtime by the "order", "review", and "print" instructions that you configure in the uCatalogOrderButton applet. You should add this special <UCATALOG INSTRUCTIONS> tag somewhere on your order template (typically centered at the top).
3	<UCATALOG FOOTER>	This special tag (with the < and > signs around it) will be replaced during runtime by the navigation buttons and the shopping cart data. You must add this special <UCATALOG FOOTER> tag somewhere on your order template (typically centered at the bottom).

Table 8.2 Special Order Form Tags

Additional Notes About Setting Up The Order Form

The name of your order form template file should be "ucatalog_template.html" and this file must be located in your "classes" directory.

See the "ucatalog_template.html" file that was included with uCatalog^TM as an example of how to create an order form.

If you want to make any of the fields on your order form "required" fields (ie. fields that must be filled in by the user), see the reference for the uCatalogInitialize applet.

The billing_state, billing_country, billing_tax_rate, shipping_state, shipping_country, and shipping_method fields are related to the tax, shipping, and handling settings - as will be discussed in the following sections.

A Note About Gathering Payment Information On The Order Form

There are two philosophies when it comes to collecting payment information from the customer. One philosophy is that the customer should fill in all order information at one time...including the payment details. This means that all of the necessary information has been collected and is available by the time the customer chooses to "print" the order or "place the order online". The other philosophy is that if the customer plans on placing the order online, he or she would not want to enter the payment information until after he or she has been transferred to the server and can see the indication that the server is secure. Both of these philosophies result in a secure online transaction, therefore, uCatalog^TM has been designed to handle both. That is, the ucatalog.pl script that has been included with uCatalog^TM will perform a check whenever it processes an online order. If at the time of the online order, the payment information has not already been collected, it will create forms for accepting the credit card or electronic payment information online. Otherwise, if the ucatalog.pl script detects that the order information was already collected, then it simply processes the order. The ucatalog.pl script will be discussed further in Section 12.

9. Setting Up Tax Rates

The uCatalogInitialize applet has 6 parameters that are used to setup the tax rates/preferences for your store. Each of these parameters is described in the table below:

Parameter	Description
tax_rate_default	The default tax rate. Valid values are "0.0%", "6.0%", etc. (Be sure to specify the % sign). As an example, suppose you wanted to charge all customers a tax rate of 7.0%. To do this, just set this value to "7.0%". Often, this tax_rate_default parameter will be used in correlation with one or more of the tax table parameters below. The default value is "0.0%".
tax_table	This parameter allows you to specify specific states and/or countries that don't go by the default tax rate. Typically this parameter would be used by in correlation with a tax selection menu on your order form. As an example, suppose you want to charge a default tax rate of "0.0%" for everyone except for customers from Florida. To do this, you would set the "tax_rate_default" (see above) to "0.0%" and you would set this "tax_table" parameter to "FL,FLORIDA". On you order form, you could put a note that "Customers from Florida must select the tax rate for their area." This "tax_table" parameter would then make sure that customers from "FL" or "FLORIDA" select a tax rate other than the "tax_rate_default". The default value for this parameter is "NONE".
tax_state_table	This parameter allows you to automatically assign a specific tax rate based on what state the customer lives. The format of this parameter is STATE=TAXRATE, where STATE is the state and TAXRATE is the tax rate that will be assigned to customers from that state. You can specify as many STATE=TAXRATE combinations as you like, just be sure to separate each combination with a comma. As an example, suppose you wanted to automatically charge customers in Florida a tax rate of 6.0% and customers in Texas a tax rate of 7.0%. You would then set this parameter to "FL=6.0%,FLORIDA=6.0%,TX=7.0%,TEXAS=7.0%". (All other customers will be charged the tax_rate_default) The default value for this parameter is "NONE".
tax_country_table	This parameter allows you to automatically assign a specific tax rate based on what country the customer lives. The format of this parameter is COUNTRY=TAXRATE, where COUNTRY is the country and TAXRATE is the tax rate that will be assigned to customers from that country. You can specify as many COUNTRY=TAXRATE combinations as you like, just be sure to separate each combination with a comma. As an example, suppose you wanted to automatically charge customers in France a tax rate of 16.0% and customers in Germany a tax rate of 18.0%. You would then set this parameter to "FRANCE=16.0%,GERMANY=18.0%". (All other customers will be charged the tax_rate_default) The default value for this parameter is "NONE".
tax_shipping	This parameter allows you to specify whether to tax the shipping charge. Valid values are "YES" or "NO". The default value is "NO".
tax_on_destination	This parameter allows you to specify whether to base the tax rate on the destination address of the order or the billing address of the order. The default value of "YES" is to base the tax rate on the destination address of the order. Otherwise, set this value to "NO" in order to always determine the tax rate based on the billing address.

Table 9.1 Tax Rate Parameters

10. Setting Up Shipping

Various shipping calculations can be setup via the uCatalogInitialize applet's "shipping_table" parameter. The format of this parameter is:

"SHIPPING NAME1,CALCULATION TYPE,VALUE;
SHIPPING NAME2,CALCULATION TYPE,VALUE;
SHIPPING NAME3,CALCULATION TYPE,VALUE;
and so on...."

Where the SHIPPING NAME is the name of the shipping method, CALCULATION TYPE is the method by which the shipping charge will be calculated, and VALUE is the value (or values) that correspond to the calculation type.

Note that you can configure as many different shipping methods/types as you like, just be sure to separate each shipping method with a semicolon (;).

Note also that the SHIPPING NAME can be any text string you like - such as "UPS" or "Fed Ex" or "Hello World" - just be sure that the names match those names configured in the shipping selection of your order form. (Ie. the names should match any names listed in the "shipping_method" option list of your "ucatalog_template.html" file.)

Note also that the CALCULATION TYPE and VALUE(S) of each shipping method are dependent on each other and are described in detail in each of the shipping sections below.

And finally, don't forget about the "shipping_modifier" parameter that can be associated with each item. This "shipping_modifier" can be used to add additional shipping charges for specific items. See the "shipping_modifier" parameter of each input applet in the uCatalog^TM Applet Reference for more information.

10.1 FLAT_FEE Shipping Calculation

The FLAT_FEE shipping calculation type allows you to setup the shipping charge as a flat fee. To charge a flat fee, simply set the VALUE to the fee that you want to charge. For example, if you want to charge a $5.00 fee for shipping, then set the shipping parameter to:

"My Shipping Name,FLAT_FEE,$5.00"

Or if you want shipping to be free (i.e., a charge of $0.00), then set the parameter to:

"My Shipping Name,FLAT_FEE,$0.00"

10.2 SUBTOTAL_LOOKUP Shipping Calculation

The SUBTOTAL_LOOKUP shipping calculation type allows you to setup the shipping charge to be based on a subtotal lookup table. The subtotal lookup table should be a series of subtotal=charge ranges with a format such as "subtotal1=charge1,subtotal2=charge2,subtotal3=charge3,subtotal4=charge4,...." and so on.... where the subtotal=charge combinations are interpreted as:

if (subtotal1 <= ORDER SUBTOTAL) and (ORDER SUBTOTAL < subtotal2),
then SHIPPING = charge1
if (subtotal2 <= ORDER SUBTOTAL) and (ORDER SUBTOTAL < subtotal3),
then SHIPPING = charge2
if (subtotal3 <= ORDER SUBTOTAL) and (ORDER SUBTOTAL < subtotal4),
then SHIPPING = charge3
if (subtotal4 <= ORDER SUBTOTAL),
then SHIPPING = charge4

Note that you can list as many subtotal=charge combinations as you like - each one separated by a comma.

Note also that the subtotal=charge combinations should be in increasing subtotal order - with the first subtotal being zero.

As an example, suppose you wanted to charge shipping based on the following table:

SUBTOTAL          SHIPPING CHARGE
$0 - $49.99       $10.00
$50 - $99.99      $8.00
$100 - $199.99    $5.00
$200 and over     $0.00

Then you would set the shipping parameter to:

"My Shipping Name, SUBTOTAL_LOOKUP,$0=$10.00,$50=$8.00,$100=$5.00,$200=$0.00"

10.3 SUBTOTAL_FORMULA Shipping Calculation

The SUBTOTAL_FORMULA shipping calculation type allows you to setup the shipping charge to be based on the formula:

Shipping Charge = ORDER SUBTOTAL * VALUE
So as an example, if you wanted to charge $0.25 for each dollar of the subtotal, then you would set the shipping parameter to:

"My Shipping Name,SUBTOTAL_FORMULA,$0.25"

10.4 WEIGHT_LOOKUP Shipping Calculation

The WEIGHT_LOOKUP shipping calculation type allows you to setup the shipping charge to be based on a weight lookup table. The weight lookup table should be a series of weight=charge ranges with a format such as "weight1=charge1,weight2=charge2,weight3=charge3,weight4=charge4,...." and so on.... where the weight=charge combinations are interpreted as:

if (weight1 <= ORDER WEIGHT) and (ORDER WEIGHT < weight2),
then SHIPPING = charge1
if (weight2 <= ORDER WEIGHT) and (ORDER WEIGHT < weight3),
then SHIPPING = charge2
if (weight3 <= ORDER WEIGHT) and (ORDER WEIGHT < weight4),
then SHIPPING = charge3
if (weight4 <= ORDER WEIGHT),
then SHIPPING = charge4

Note that you can list as many weight=charge combinations as you like - each one separated by a comma.

Note also that the weight=charge combinations should be in increasing weight order - with the first weight being zero.

As an example, suppose you wanted to charge shipping based on the following table:

WEIGHT            SHIPPING CHARGE
0 - 9.999         $5.00
10 - 19.999       $6.00
20 - 29.999       $7.00
30 and over       $9.00

Then you would set the shipping parameter to:

"My Shipping Name,WEIGHT_LOOKUP,0=$5.00,10=$6.00,20=$7.00,30=$9.00"

10.5 WEIGHT_FORMULA Shipping Calculation

The WEIGHT_FORMULA shipping calculation type allows you to setup the shipping charge to be based on the formula:

Shipping Charge = ORDER WEIGHT * VALUE
So as an example, if you wanted to charge $1.00 for each pound an order weights, then you would set the shipping parameter to:

"My Shipping Name,WEIGHT_FORMULA,$1.00"

10.6 QUANTITY_LOOKUP Shipping Calculation

The QUANTITY_LOOKUP shipping calculation type allows you to setup the shipping charge to be based on a quantity lookup table. The quantity lookup table should be a series of quantity=charge ranges with a format such as "quantity1=charge1,quantity2=charge2,quantity3=charge3,quantity4=charge4,...." and so on.... where the quantity=charge combinations are interpreted as:

if (quantity1 <= ORDER QUANTITY) and (ORDER QUANTITY < quantity2),
then SHIPPING = charge1
if (quantity2 <= ORDER QUANTITY) and (ORDER QUANTITY < quantity3),
then SHIPPING = charge2
if (quantity3 <= ORDER QUANTITY) and (ORDER QUANTITY < quantity4),
then SHIPPING = charge3
if (quantity4 <= ORDER QUANTITY),
then SHIPPING = charge4

Note that you can list as many quantity=charge combinations as you like - each one separated by a comma.

Note also that the quantity=charge combinations should be in increasing quantity order - with the first quantity being zero.

As an example, suppose you wanted to charge shipping based on the following table:

QUANTITY          SHIPPING CHARGE
1 - 4             $6.00
5 - 9             $8.00
10 - 19           $10.00
20 and over       $15.00

Then you would set the shipping parameter to:

"My Shipping Name,QUANTITY_LOOKUP,0=$6.00,5=$8.00,10=$10.00,20=$15.00"

10.7 QUANTITY_FORMULA Shipping Calculation

The QUANTITY_FORMULA shipping calculation type allows you to setup the shipping charge to be based on the formula:

Shipping Charge = ORDER QUANTITY * VALUE
So as an example, if you wanted to charge $0.50 for each item, then you would set the shipping parameter to:

"My Shipping Name,QUANTITY_FORMULA,$0.50"

10.8 CUSTOM Shipping Calculation

If none of the above shipping tables/formulas fit your shipping calculation needs, we have provided a "CUSTOM" shipping option in which you can actually modify the JavaScript in the ucatalog_javascript.js file in order to manually program your specific shipping calculation. To do this, first set the shipping parameter to something like:

"My Shipping Name,CUSTOM,$0.00"

And then use any text editor to open up the "ucatalog_javascript.js" file that is located in your "classes" directory.

*Note that this shipping method is for advanced users only and thus some knowledge of JavaScript programming is assumed.

The very first function in the "ucatalog_javascript.js" file is called "calculateShipping" and is currently set to just call the "validateShipping()" method - which is the method that calculates/sets the shipping charge by using one of the pre-defined shipping calculations described above. The code for that function looks like this:

function calculateShipping()
{
   // This function can be over-ridden for your own custom needs.
   // See the uCatalog Programmer's Guide for more information.
   return document.uCatalogJSI.validateShipping();
}

To use your own custom shipping calculation here, you will want to rewrite this function to perform your own calculation and set the shipping charge yourself via the setShipping() function. Other useful functions that may come in handy for programming your own shipping calculations are:

getShippingMethodName() - which returns the name of the currently selected shipping option.

getSubtotal() - which returns the current subtotal of the order.

getTotalWeight() - which returns the current total weight of the order.

getTotalQuantity() - which returns the current total quantity of the order.

Note also that upon a successful calculation of the shipping charge, the calculateShipping() method should return the string "VALID" - indicating that the shipping was successfully calculated.

So putting all of this together, lets give an example. Say we wanted to override the calculate shipping function so that for each item we charge $1.00 for shipping...but if the quantity is 10 or greater, then the shipping is free. To do this, the code for the calculateShipping() function would be something like this:

function calculateShipping()
{
   var currentShippingName = document.uCatalogJSI.getShippingMethodName();

   if (currentShippingName == "My Custom Shipping")
   {
      var currentQuantity = document.uCatalogJSI.getTotalQuantity();
      var customShippingCharge = currentQuantity * 1.00;
      if (currentQuantity >= 10)
      {
         customShippingCharge = 0.0;
      }
         
      document.uCatalogJSI.setShipping("" + customShippingCharge);
      return "VALID";
   }
   else
   {
      // The shipping type selected was one of the standard methods.
      return document.uCatalogJSI.validateShipping();
   }
}

10.9 NONE Shipping Calculation

One final shipping calculation that is available is the "NONE" calculation type. This can be used if you don't want to use shipping at all. To set shipping to NONE, set the shipping parameter to something like:

"NONE,NONE,$0.00"

Or since this is the default value, don't specify the shipping parameter at all.

11. Setting Up Handling

The uCatalogInitialize applet has 3 parameters that are used to setup the handling fees/preferences for your store. Each of these parameters is described in the table below:

Parameter	Description
handling_fee_default	This parameter allows you to specify the default handling fee that all customers will be charged. The format of this parameter is simply the fee that you want to charge such as "$5.00" or "$2.00". As an example, suppose you wanted to charge all customers a handling fee of $1.00. To do this, just set this parameter to "$1.00". Often this parameter will be used in correlation with one of the handling table parameters below. The default value for this parameter is "$0.00".
handling_state_table	This parameter allows you to specify specific handling fees for customers from specific states. The format of this parameter is STATE=HANDLINGFEE, where STATE is the state and HANDLINGFEE is the handling fee that will be charged to customers from that state. You can specify as many STATE=HANDLINGFEE combinations as you like, just be sure to separate each combination with a comma. As an example, suppose you wanted to charge customers in California a handling fee of $2.00 and customers in New York a handling fee of $3.00. You would then set this parameter to "CA=$2.00,CALIFORNIA=$2.00,NY=$3.00,NEW YORK=$3.00". (All other customers will be charged the handling_fee_default) The default value for this parameter is "NONE".
handling_country_table	This parameter allows you to specify specific handling fees for customers from specific countries. The format of this parameter is COUNTRY=HANDLINGFEE, where COUNTRY is the country and HANDLINGFEE is the handling fee that will be charged to customers from that country. You can specify as many COUNTRY=HANDLINGFEE combinations as you like, just be sure to separate each combination with a comma. As an example, suppose you wanted to charge customers in Canada a handling fee of $2.00 and customers in England a handling fee of $3.00. You would then set this parameter to "CANADA=$2.00,ENGLAND=$3.00". (All other customers will be charged the handling_fee_default) The default value for this parameter is "NONE".

Table 11.1 Handling Fee Parameters

12. Installing/Customizing The CGI Script

The ucatalog.pl script is a basic Perl Script that included with uCatalog^TM. It is designed to provide only the basic functionality needed to securely process and read online orders. Since most companies have their own database/payment processing system for processing orders, the main purpose of the ucatalog.pl script is to serve as a "how to" illustration of how to access the data that gets passed to the script from the uCatalog^TM CD-ROM store. Feel free to modify the ucatalog.pl script - or use it as a model for your own script - in order to handle your specific database/payment processing system needs.

Installing The ucatalog.pl Script

Below are some brief instructions on how to configure and install the ucatalog.pl script on your server. Note that it is assumed that you have some knowledge of installing/executing Perl CGI scripts on your server.

Open the "ucatalog.pl" file with any text editor (such as Note Pad or Word Pad).

Answer the 18 configuration questions at the top of the script. The questions should be self-explanatory.

After answering the questions, save the file (as text, if prompted).

Transfer the script to your server in ASCII or TEXT mode (as opposed to BINARY or RAW mode).

Give the script read and execute permissions (chmod 755).

If you haven't created it yet, create a "data" directory to hold your order files (as was described in question #7 of the script configuration questions).

Test the script by going to the FULL URL of the script on your server. You should get the "Login" form....similar to when you go to the URL of the script on our server:

https://www.uburst.com/cgi-bin/ucatalog/ucatalog.pl

If you have any trouble configuring the script, refer to the troubleshooting section on our online reference site:

http://www.uburst.com/uCatalog/reference.html

13. Testing

Throughout the development of your CD-ROM catalog - and especially before you start burning CD-ROMs for your catalog - it is very important to test out your CD-ROM store. Try adding items to the cart and then try placing test orders. Check that your order form is functioning properly and that the tax, shipping, and handling calculations are performing as you expect. Also, check your CD-ROM catalog pages with different browsers. There are slight differences in the way different browsers display Java applets so make sure their appearance is acceptable on the various browsers that you intend to support.

If you run into any problems, refer to the troubleshooting section on our online reference site:

http://www.uburst.com/uCatalog/reference.html

14. Troubleshooting

In order to keep the troubleshooting tips as up to date as possible, we have moved the troubleshooting section to our online reference site at:

http://www.uburst.com/uCatalog/reference.html

15. Creating CD-ROMs

After you have sufficiently tested your catalog/store by running it directly off of your development computer, you are ready to put your catalog on CD-ROM. Putting your catalog actually on a CD-ROM, does not take much. Simply use the standard software that came with your Writable CD-ROM drive to transfer the same directory structure (and files) from your development computer onto the CD-ROM. As shown in the figure below, you may want to come up with your own "index.html" page that will be located in the root directory of your CD-ROM and which will handle linking customers to your store directory.

Figure 15.1 The Root Directory Of The CD-ROM

By setting up such an index file, instructions to use your CD-ROM catalog could be as simple as:

Put the CD in your CD-ROM drive.

Start your Netscape or Internet Explorer browser.

Use your browser to open the file index.html located on the CD-ROM.

And once they get the index.html file open in their browser, browsing the rest of the CD/Catalog will be as easy as surfing the web.

16. Internationalization

All of uCatalog's language specific settings (such as default button labels, messages, currency symbols, etc.) have been centralized into one uCatalogInternational class file. This means that you can create catalogs to support various countries/languages by simply replacing the uCatalogInternational module with the one for the language that you want to support. We are currently working on uCatalogInternational modules for Danish, Dutch, Finnish, French, German, Italian, Norwegian, Portuguese, Spanish, and Swedish.

Contact us for details.

17. Creating Your Own Java Applets

In case you can't find the applet you need in the uCatalog^TM Applet Reference, we have released the Java API for the uCatalog^TM Input Applets. This allows you to create your own custom Input Applets. See the uCatalog^TM Programmer's Guide for more information about creating your own custom Input Applets.

18. Creating Your Own JavaScripts

To further increase uCatalog's flexibility, we have provided the means by which you can create your own JavaScripts to interface with uCatalog^TM. See the uCatalog^TM Programmer's Guide for more information about creating your own custom JavaScripts.

19. Other References

Additional references and resources can be found at:

The uCatalog^TM Applet Reference

The uCatalog^TM Programmer's Guide

The uCatalog^TM Tutorial

The uCatalog^TM Reference Site