Last Update: May 25, 2002


Copyright (c) 1997 - 2002; Microburst Technologies, Inc.
All Rights Reserved.





USHOP PROGRAMMER'S GUIDE TECHNOLOGY SHARING AGREEMENT: Note that you may NOT resell nor redistribute any custom uShopTM Java, JavaScript, or CGI components without expressed written consent from Microburst Technologies, Inc.



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. Customizing The uShopTM CGI Script Section 6
   6.1 Custom Tax Calculations Section 6.1
   6.2 Custom Shipping Calculations Section 6.2
   6.3 Custom Handling Calculations Section 6.3
   6.4 Custom Data Recording Section 6.4
7. Additional Notes Section 7
8. Additional References and Resources Section 8






1. Introduction

What this programmer's guide does?

This programmer's guide is intended to describe how to use the uShopTM Application Program Interface (API) to create your own Java Applets and JavaScripts that can interface with the uShopTM Online Shopping System. It also documents all of uShop'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 an 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 uShopTM 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 uShopTM 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 uShop written in the newer Java 1.1 - so if you prefer to work with Java 1.1, then contact us to request the uShopTM class files for Java 1.1. The Java 1.1 Development Kit can be downloaded from the URL http://java.sun.com/products/jdk/1.1/. This programmer's guide will assume you are using the older JDK 1.0.

Linking To The uShopTM Class Files

In order to be able to compile any new Java applets that use the uShopTM API, the JDK compiler will need to be able to find the other uShopTM class files. The easiest way to do this is to copy all of the uShopTM 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 uShop class files into this new directory. Also, copy the "example.java" source file that was included with uShopTM 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 uShopTM 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 uShopTM is the use of the uShopLibrary 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 uShopTM 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 uShopLibrary 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 uShopTM 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 uShopTM 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 (uShopLibrary.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 uShopLibrary 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 uShopLibrary 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: uShopLibrary
@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: uShopLibrary
@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: uShopLibrary
@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: uShopLibrary
@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: uShopLibrary
@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: uShopLibrary
@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: uShopLibrary
@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: uShopLibrary
@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: uShopLibrary
@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: uShopLibrary
@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: uShopLibrary
@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: uShopLibrary
@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: uShopLibrary
@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: uShopLibrary
@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: uShopLibrary
@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: uShopLibrary
@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: uShopLibrary
@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 uShopTM 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 uShopTM, however, you will need the uShopTM class files. In particular, JavaScripts must use the uShop JavaScript Interface Applet as the means by which to call uShop's Java foundation classes.

The uShop JavaScript Interface Applet

In order for JavaScripts to be able to call a uShopTM Java method, they must go through a special JavaScript Interface Applet. This special applet is called "uShopJSI" and must be added to each HTML page that has a JavaScript on it that interface's with uShopTM. You only need one instance of the "uShopJSI" 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 "uShopJSI" applet to your page is similar to adding any other Java Applet to your page. An example is shown below: 

<APPLET CODE="uShopJSI.class" CODEBASE="../classes/" NAME="uShopJSI" WIDTH="2" HEIGHT="2">
</APPLET>
By doing this, JavaScripts can access the uShopJSI methods by using the syntax: 
document.uShopJSI.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 uShopTM, the key to developing a JavaScript that will interface with uShopTM 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 uShopTM 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 uShopJSI 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 uShopTM 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 uShopTM 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.uShopJSI.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 uShopJSI class and which may be useful when developing your own custom JavaScripts.

1. clearCart()

Method to clear the current contents of the shopping cart.

Prototype: void clearCart();
Class: uShopJSI


2. formatMoney()

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

Prototype: String formatMoney(float value);
Class: uShopJSI
@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.


3. formatTaxRate()

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

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


4. getDiscountRate()

Method to get the current discount rate.

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


5. getSubtotal()

Method to get the current subtotal.

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


6. getTotalQuantity()

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

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


7. setDiscountRate()

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

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


6. Customizing The uShopTM CGI Script
This section describes how to customize the ushop.pl Perl CGI script to perform your own custom tax, shipping, handling calculations and data recording functions. Note that it will be assumed that the reader already has some previous knowledge of Perl/CGI programming.


6.1 Custom Tax Calculations
In case none of the tax options as described in the uShopTM User's Guide fit the needs of your online store, we have provided the ability to write your own custom tax calculations. To do this, you must first set the "Default Tax Rate" parameter in the General Settings section of the uShopTM control panel to "CUSTOM". This will cause uShopTM to call the subroutine "custom_tax_rate" whenever it is time to determine an order's tax rate. Thus, you can customize the "custom_tax_rate" subroutine that is located in the "ushop.pl" file to perform any calculation you want in order to determine an order's tax rate. In order to assist with calculations, variables to access the following information have been documented at the top of the "custom_tax_rate" subroutine:
  • The current billing state.

  • The current billing country.

  • The current billing zip code.

  • The current shipping state.

  • The current shipping country.

  • The current shipping zip code.

  • The subtotal of the items in the shopping cart (before any discounts).

  • The subtotal of the items in the shopping cart (after any discounts).

  • The total weight of the items in the shopping cart.

  • The total quantity of items in the shopping cart.
Note that upon performing your tax rate calculations, your "custom_tax_rate" subroutine should return the tax rate as a string with the percent sign, such as: "6.0%" or "7.75%".


6.2 Custom Shipping Calculations
In case none of the shipping options as described in the uShopTM User's Guide fit the needs of your online store, we have provided the ability to write your own custom shipping calculations. To do this, you must first set the "Calculation Type" of the desired shipping option in the General Settings section of the uShopTM control panel to "CUSTOM". This will cause uShopTM to call the subroutine "custom_shipping" in order to determine an order's shipping charges. Thus, you can customize the "custom_shipping" subroutine that is located in the "ushop.pl" file to perform any calculation you want in order to determine an order's shipping charge. In order to assist with calculations, variables to access the following information have been documented at the top of the "custom_shipping" subroutine:
  • The name of the currently selected shipping method.

  • The table/value of the currently selected shipping method.

  • The current billing state.

  • The current billing country.

  • The current billing zip code.

  • The current shipping state.

  • The current shipping country.

  • The current shipping zip code.

  • The subtotal of the items in the shopping cart (before any discounts).

  • The subtotal of the items in the shopping cart (after any discounts).

  • The total weight of the items in the shopping cart.

  • The total quantity of items in the shopping cart.
Note that upon performing your custom shipping calculations, your "custom_shipping" subroutine should return the desired shipping charge.


6.3 Custom Handling Calculations
In case none of the handling options as described in the uShopTM User's Guide fit the needs of your online store, we have provided the ability to write your own custom handling calculations. To do this, you must first set the "Default Handling Fee" parameter in the General Settings section of the uShopTM control panel to "CUSTOM". This will cause uShopTM to call the subroutine "custom_handling" in order to determine an order's handling fee. Thus, you can customize the "custom_handling" subroutine that is located in the "ushop.pl" file to perform any calculation you want in order to determine an order's handling fee. In order to assist with calculations, variables to access the following information have been documented at the top of the "custom_handling" subroutine:
  • The current billing state.

  • The current billing country.

  • The current billing zip code.

  • The current shipping state.

  • The current shipping country.

  • The current shipping zip code.

  • The subtotal of the items in the shopping cart (before any discounts).

  • The subtotal of the items in the shopping cart (after any discounts).

  • The total weight of the items in the shopping cart.

  • The total quantity of items in the shopping cart.

  • The name of the currently selected shipping method.

  • The current shipping charge.
Note that upon performing your custom handling calculations, your "custom_handling" subroutine should return the desired handling fee.


6.4 Custom Data Recording
Currently there are two subroutines in the ushop.pl script that handle recording data, the "update_customer_log" subroutine and the "update_inventory_log" subroutine. As documented in the uShopTM User's Guide, the "update_customer_log" subroutine is currently setup to write the following information to the "ushop-customers.log" file:
  • Order Number

  • Order Date

  • Subtotal

  • Total

  • Billing Last Name

  • Billing First Name

  • Billing Company Name

  • Billing Customer ID

  • Billing Street Address

  • Billing City

  • Billing State

  • Billing Zip

  • Billing Country

  • Billing Phone

  • Billing Fax

  • Billing Email

  • Billing URL

And the "update_inventory_log" subroutine is currently setup to write the following information to the "ushop-inventory.log" file:
  • Order Number

  • Order Date

  • Product ID

  • Product Name

  • Product Quantity

  • Product Price


You may modify either of these subroutines (located in the "ushop.pl" file) in order to meet your own custom data recording needs.


7. 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.


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