Copyright (c) 1997 - 2001; Microburst Technologies, Inc. All Rights Reserved.
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.javaThe "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:
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:
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:
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:
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:
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:
And the "update_inventory_log" subroutine is currently setup to write the following information to the "ushop-inventory.log" file:
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. 8. Additional References and Resources Listed below are some books and URLs where you can find additional information about Java and JavaScript programming:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||