Last Update: April 12, 2000


Copyright (c) 1999 - 2000; Microburst Technologies, Inc.
All Rights Reserved.





Table Of Contents
1. Introduction Section 1
2. Creating Java Applets Section 2
   2.1 Setting Up Your Programming Environment Section 2.1
   2.2 addProduct() API Section 2.2
   2.3 Example Section 2.3
3. Additional Java Methods Section 3
4. Creating JavaScripts Section 4
   4.1 Setting Up Your Programming Environment Section 4.1
   4.2 addProduct() API Section 4.2
   4.3 Example Section 4.3
5. Additional JavaScript Functions Section 5
6. Additional Notes Section 6
7. Additional References and Resources Section 7






1. Introduction

What this programmer's guide does?

This programmer's guide is intended to describe how to use the uCatalogTM Application Program Interface (API) to create your own Java Applets and JavaScripts that can interface with the uCatalogTM Interactive CD-ROM E-Commerce System. It also documents all of uCatalog's public API's that may be useful when developing your own Java Applets and JavaScripts.

What this programmer's guide doesn't do?

This programmer's guide is not intended to be a introduction or tutorial into how to write Java or JavaScript programs. It will be assumed that the reader has some previous knowledge of programming Java Applets and JavaScripts.



2. Creating Java Applets
This section describes how to create your own custom Input Applets that can be used to add items to the uCatalogTM virtual shopping cart. This includes instructions on how to setup your development environment, a description of how to use the addProduct() API, and the complete source code for an example Input Applet.


2.1 Setting Up Your Programming Environment

Java Compiler

The uCatalogTM applets and classes are written in Java 1.0 (for maximum browser compatibility), therefore you should begin by downloading the Java 1.0 Development Kit (JDK 1.0) from the Sun website.

The current version (which as of April 12, 2000 is JDK 1.0.2) can be downloaded from:

http://java.sun.com/products/jdk/1.0.2/

NOTE: We also have a version of uCatalog written in the newer Java 1.1 - so if you prefer to work with Java 1.1, then contact us to request the uCatalogTM class files for Java 1.1. This programmer's guide will assume you are using the older JDK 1.0.

Linking To The uCatalogTM Class Files

In order to be able to compile any new Java applets that use the uCatalogTM API, the JDK compiler will need to be able to find the other uCatalogTM class files. The easiest way to do this is to copy all of the uCatalogTM class files into the same directory where you will be creating your Java source files.

As a test/example, try creating a new directory on your development computer. Copy ALL of the uCatalog class files into this new directory. Also, copy the "example.java" source file that was included with uCatalogTM into this directory. (You can find the "example.java" file - along with a test html page - in the "java" directory that was created when you installed/unzipped uCatalogTM on your computer). Try to compile the "example.java" file by typing: 

javac example.java
The "example.java" file should successfully compile without error. This is the same procedure that you will use to compile any new Java applets that you develop.


2.2 addProduct() API
The key to developing a Java Applet that will interface with uCatalogTM is the use of the uCatalogLibrary method addProduct(). That is, you can program any kind of logic or interface you want into your applets, providing that when you finally want to add an item to the uCatalogTM virtual shopping cart, your applet calls the addProduct() method. This section provides a detailed description of the addProduct() method and its parameters.

The addProduct() method is a static function of the uCatalogLibrary class and has the following prototype: 
public static synchronized int addProduct(String pId,
                                          String pName,
                                          String pDescription,
                                          String pWeight,
                                          String pQuantity,
                                          String pPrice,
                                          float  pPriceModifier,
                                          String pClassification,
                                          String pShippingModifier,
                                          String pTaxable);
Note that the method has 10 parameters, each of which is described in the table below:


  Parameter Name Description
1 ID A String representing a unique identifier for the product. (The product's ID).
2 Name A String representing the name of the product as it will appear in the shopping cart.
3 Description A String representing the description of the product as it will appear in the shopping cart. This description String should also include any options or text that the customer selected for this product (such as colors, sizes, monograms, etc.).
4 Weight A String representing the weight of a single unit of the product. This weight should NOT already be adjusted based on the quantity. It should just be the weight of one single unit of the product.
5 Quantity A String representing the quantity of the product as specified by the customer. Use "1" if not used.
6 Price A String indicating the price of a single unit of the product. This price should NOT already be modified based on the quantity nor should this price include any price modifiers. It should just be the price of one single unit of the product. **Note that it is acceptable to pass an entire price table as this parameter - such as "1 @ $50.00,2 @ $45.00, 3 @ $40.00". In this case, the base price would then be assumed to be the first value in the table.
7 Price Modifier A floating point (float) value indicating the value of any modifiers to the base price of the product. This value would usually be calculated based on any options that were selected by the customer. Set to (float)0.0 if not used.
8 Classification Any String used to indicate a classification for the product. Use "" or "NONE" if not used.
9 Shipping Modifier A String representation of any special shipping fee to be added with this product. The shipping total will be adjusted by this value multiplied by the quantity of this product - so this fee should NOT already be modified based on the quantity. Set to "0.00" or "" or "NONE" if not used.
10 Taxable A String indicating whether the product is taxable or not. Set to "YES" if the product is taxable, otherwise set to "NO".

Table 2.2.1 addProduct() API Parameters


The addProduct() method also has an int return value to indicate whether the product was successfully added to the virtual shopping cart or not. If the product was successfully added to the shopping cart, then a value greater than 0 is returned. Otherwise, a value of 0 is returned to indicate that the item was not added to the cart.

See the example in the next section for an example call to the addProduct() method.


2.3 Example
The "example.java" file that is included with uCatalogTM contains the complete source code for an example input applet. You can find this "example.java" file - along with a test html page - in the "java" directory that was created when you installed/unzipped uCatalogTM on your computer. Take a look at the source code of this Java 1.0 applet. Note how the action event handler for the "Add" button is setup to call the addProduct() API: 
if (uCatalogLibrary.addProduct(pId,
                               pName,
                               pDescription + "; " + choiceOption1.getSelectedItem(),
                               pWeight,
                               "" + currentQuantity,
                               pPrice,
                               currentPriceModifier,
                               pClassification,
                               pShippingModifier,
                               pTaxable) > 0)
{
   // The product was successfully added.
}
else
{
   // The product was NOT successfully added.
}

Feel free to modify this example or use it as a model to create your own custom applets.

Note that throughout the example, you will see calls to various other uCatalogLibrary methods. Those methods, and others, have been documented in the next section and may be useful when developing your own custom applets.


3. Additional Java Methods
This section lists some of the other public methods contained in the uCatalogLibrary class and which may be useful when developing your own custom Java applets.

1. atof()

Method to convert a string to a floating point value.

Prototype: float atof(String pString);
Class: uCatalogLibrary
@param pString - The string to be converted.
@return Returns the float representation of the string.


2. atoi()

Method to convert a string to an integer value.

Prototype: int atoi(String pString);
Class: uCatalogLibrary
@param pString - The string to be converted.
@return Returns the int representation of the string.


3. compareStrings()

Method to compare two strings (without case-sensitivity).

Prototype: boolean compareStrings(String s1,String s2);
Class: uCatalogLibrary
@param s1 - The first string to compare.
@param s2 - The second string to compare.
@return Returns true if the strings are equal.


4. createChoiceItems()

Method to parse a specified comma-delimited string and add each item to a new Choice object.

Prototype: Choice createChoiceItems(String pString);
Class: uCatalogLibrary
@param pString - The string containing the comma-delimited items that are to be added to the Choice object.
@return Returns a new Choice object with the specified items added.


5. createChoicePriceItems()

Method to parse a specified comma-delimited string and add each item to a new Choice object. The items delimited by commas are option=price pairs.

Prototype: Choice createChoicePriceItems(String parseString,int fWidth);
Class: uCatalogLibrary
@param parseString - The string containing the comma-delimited items that are to be added to the Choice object. Each item is of the format option=price. For example: "optionA=5.00, optionB=10.00,optionC=15.00".
@param fWidth - The number of characters to pad the option field.
@return Returns a new Choice object with the specified items added.


6. formatTaxRate()

Method to format a tax rate string from a floating-point value.

Prototype: String formatTaxRate(float fvalue);
Class: uCatalogLibrary
@param fvalue - The floating point tax rate to be formatted.
@return Returns a String representation of the tax rate percentage.


7. formatMoney()

Method to format a money string from a floating-point value.

Prototype: String formatMoney(float fvalue);
Class: uCatalogLibrary
@param fvalue - The floating point value to be formatted.
@return Returns a String representation of the floating-point value with two digits to the right of the decimal.


8. getColor()

Method to get a Color object based on a text string.

Prototype: Color getColor(String colorString);
Class: uCatalogLibrary
@param colorString - A string containing a color name or rgb value.
@return Returns a new Color object with the specified color.


9. getElement()

Method to search a specified delimited string and return the Nth element.

Prototype: String getElement(String src, int n, char delimiter);
Class: uCatalogLibrary
@param src - The string to search.
@param n - The Nth element in the string (beginning at 0).
@param delimiter - The delimiter character by which to separate the string.
@return Returns the Nth element as a string or returns null if the element at the specified index does not exist.


10. getOptionModifierPrice()

Method to check a string for and "+" or "-" indicators and then return the value of the modifier as a float. (for use when determining if options have price modifiers)

Prototype: float getOptionModifierPrice(String pString);
Class: uCatalogLibrary
@param pString - The string to be checked.
@return Returns the float value of the string's modifier (or 0.0 if none).


11. getPriceFromTable()

Method to return the current price based on quantity from a price table.

Prototype: float getPriceFromTable(int quantity, float basePrice, String priceTable);
Class: uCatalogLibrary
@param quantity - The total quantity to be looked up in the table.
@param basePrice - The default price.
@param priceTable - The price table in the form of quantity@price, etc.
@return Returns a float representing the price that was looked up.


12. gotoUrl()

Method to goto (i.e., link) the specified page.

Prototype: void gotoUrl(Applet parent,String nextPage,String target);
Class: uCatalogLibrary
@param parent - A reference to the parent applet that called this method.
@param nextPage - The page to go to.
@param target - The target frame for the new page.


13. padString()

Method to pad a string with spaces such that the String length is as specified. Note: If the string length is greater than the specified length, the string is truncated.

Prototype: String padString(String pString,int length);
Class: uCatalogLibrary
@param pString - The string to be padded/truncated.
@param length - The length to make the padded string.
@return Returns the new String of the desired size.


14. readFile()

Method to read a file.

Prototype: String readFile(Applet parent,String file);
Class: uCatalogLibrary
@param parent - A reference to the parent applet that is reading the file.
@param file - The file to read.
@return Returns a String containing contents of the file.


15. replace()

Method to replace all occurrences of a specified string with a new string. The search is not case-sensitive.

Prototype: String replace(String src, String rstring, String nstring);
Class: uCatalogLibrary
@param src - The source string to be searched.
@param rstring - The string to be replaced in src.
@param nstring - The new string to replace the rstring.
@return Returns the modified src string.


16. replaceSection()

Method to replace the first occurrence of a section containing a specified start string, ending with a specified end string, and containing a specified middle string with a new string. The search is not case-sensitive.

Prototype: String replaceSection(String src, String startString, String endString, String middleString, String nstring);
Class: uCatalogLibrary
@param src - The source string to be searched.
@param startString - The start string of the section.
@param endString - The end string of the section.
@param middleString - The middle string of the section.
@param nstring - The new string to replace the section.
@return Returns the modified src string.


17. stripLetters()

Method to strip all non-numeric characters from a specified String.

Prototype: String stripLetters(String pString);
Class: uCatalogLibrary
@param pString - The string to have the letters stripped.
@return Returns a new String with no non-numeric characters.



4. Creating JavaScripts
This section describes how to create your own custom JavaScripts for adding items to the uCatalogTM virtual shopping cart. This includes instructions on how to setup your development environment, a description of how to use the addProduct() JavaScript API, and the source code for an example JavaScript.


4.1 Setting Up Your Programming Environment
Since the source code of JavaScripts is added as part of the HTML on web pages, no compiler is needed to compile JavaScripts. To use JavaScripts with uCatalogTM, however, you will need the uCatalogTM class files. In particular, JavaScripts must use the uCatalog JavaScript Interface Applet as the means by which to call uCatalog's Java foundation classes.

The uCatalog JavaScript Interface Applet

In order for JavaScripts to be able to call a uCatalogTM Java method, they must go through a special JavaScript Interface Applet. This special applet is called "uCatalogJSI" and must be added to each HTML page that has a JavaScript on it that interface's with uCatalogTM. You only need one instance of the "uCatalogJSI" applet on each page that uses a JavaScript....and usually the applet is hidden near the bottom of the HTML page. The syntax for adding the "uCatalogJSI" applet to your page is similar to adding any other Java Applet to your page. An example is shown below: 

<APPLET CODE="uCatalogJSI.class" CODEBASE="../classes/" NAME="uCatalogJSI" WIDTH="2" HEIGHT="2">
</APPLET>
By doing this, JavaScripts can access the uCatalogJSI methods by using the syntax: 
document.uCatalogJSI.METHODNAME
...where METHODNAME is the name of the method you want to call. See the next two sections for more information.


4.2 addProduct() API
Similar to developing Java Applets to interface with uCatalogTM, the key to developing a JavaScript that will interface with uCatalogTM is the use of the addProduct() API. That is, you can program any kind of logic or interface you want into your JavaScripts, providing that when you finally want to add an item to the uCatalogTM virtual shopping cart, your JavaScript calls the addProduct() method. This section provides a detailed description of the addProduct() method and it's parameters.

The addProduct() method used by JavaScripts is a public method of the uCatalogJSI class and has the following prototype: 
public int addProduct(String pId,
                      String pName,
                      String pDescription,
                      String pWeight,
                      String pQuantity,
                      String pPrice,
                      String pPriceModifier,
                      String pClassification,
                      String pShippingModifier,
                      String pTaxable);
Note that the method has 10 String parameters, each of which is described in the table below:


  Parameter Name Description
1 ID A String representing a unique identifier for the product. (The product's ID).
2 Name A String representing the name of the product as it will appear in the shopping cart.
3 Description A String representing the description of the product as it will appear in the shopping cart. This description String should also include any options or text that the customer selected for this product (such as colors, sizes, monograms, etc.).
4 Weight A String representing the weight of a single unit of the product. This weight should NOT already be adjusted based on the quantity. It should just be the weight of one single unit of the product.
5 Quantity A String representing the quantity of the product as specified by the customer. Use "1" if not used.
6 Price A String indicating the price of a single unit of the product. This price should NOT already be modified based on the quantity nor should this price include any price modifiers. It should just be the price of one single unit of the product. **Note that it is acceptable to pass an entire price table as this parameter - such as "1 @ $50.00,2 @ $45.00, 3 @ $40.00". In this case, the base price would then be assumed to be the first value in the table.
7 Price Modifier A String representation of the value of any modifiers to the base price of the product. This value would usually be calculated based on any options that were selected by the customer. Set to "0.0" if not used.
8 Classification Any String used to indicate a classification for the product. Use "" or "NONE" if not used.
9 Shipping Modifier A String representation of any special shipping fee to be added with this product. The shipping total will be adjusted by this value multiplied by the quantity of this product - so this fee should NOT already be modified based on the quantity. Set to "0.00" or "" or "NONE" if not used.
10 Taxable A String indicating whether the product is taxable or not. Set to "YES" if the product is taxable, otherwise set to "NO".

Table 4.2.1 addProduct() JavaScript API Parameters


The addProduct() method also has an int return value to indicate whether the product was successfully added to the virtual shopping cart or not. If the product was successfully added to the shopping cart, then a value greater than 0 is returned. Otherwise, a value of 0 is returned to indicate that the item was not added to the cart.

See the example in the next section for an example call to the addProduct() method.


4.3 Example
The "example_javascript.html" file that is included with uCatalogTM contains the complete source code for an example JavaScript. You can find this "example_javascript.html" file in the "javascripts" directory that was created when you installed/unzipped uCatalogTM on your computer. Take a look at the source code of this example and notice how the addProduct() API is initiated when the "button" is clicked. The actual call looks like this: 
document.uCatalogJSI.addProduct(
   "P12345",                          <!-- Product ID -->
   "Sunglasses",                      <!-- Product Name -->
   "" +                               <!-- Product Description and Option -->
   document.P12345.color.options[document.P12345.color.selectedIndex].value,
   "1",                               <!-- Product Weight -->
   document.P12345.quantity.value,    <!-- Product Quantity -->
   "$25.00",                          <!-- Product Price (Each) -->
   "$0.00",                           <!-- Extra Price Modifiers -->
   "$0.00",                           <!-- Product Classification -->
   "$0.00",                           <!-- Product Shipping Modifier -->
   "YES");                            <!-- Taxable? -->

Feel free to modify the example or use is as a model to create your own custom JavaScripts.


5. Additional JavaScript Functions
This section lists some of the additional methods contained in the uCatalogJSI class and which may be useful when developing your own custom JavaScripts.

1. formatMoney()

Method to format a money string from a floating-point value.

Prototype: String formatMoney(float value);
Class: uCatalogJSI
@param value - The floating point value to be formatted.
@return Returns a String representation of the floating-point value with two digits to the right of the decimal.


2. formatTaxRate()

Method to format a tax rate string from a floating-point value.

Prototype: String formatTaxRate(float taxRate);
Class: uCatalogJSI
@param taxRate - The floating point tax rate to be formatted.
@return Returns a String representation of the tax rate percentage.


3. getDiscountRate()

Method to get the current discount rate.

Prototype: float getDiscountRate();
Class: uCatalogJSI
@return Returns the float value of the current discount rate.


4. getSubtotal()

Method to get the current subtotal.

Prototype: float getSubtotal();
Class: uCatalogJSI
@return Returns the float value of the current subtotal.


5. getTotalQuantity()

Method to get the total quantity of items in the cart.

Prototype: int getTotalQuantity();
Class: uCatalogJSI
@return Returns the int value of the total quantity.


6. setDiscountRate()

Method to set the current discount rate. (Useful if creating your own discount JavaScripts.

Prototype: void setDiscountRate(String newValue)
Class: uCatalogJSI
@param newValue - A string representation of the new discount rate.


6. Additional Notes
This section contains some additional notes that may be helpful when developing your own Java Applets and Java Scripts.

  • Don't Forget To Test! It is essential that you test any new applets or JavaScripts that you create. Test them with different browsers....and if possible, on different operating systems. This is because there are slight differences in the way different browsers and different operating systems run and display Java applets. So the more testing you can do, the better.


    7. Additional References and Resources
    Listed below are some books and URLs where you can find additional information about Java and JavaScript programming: