uShop User's Manual

uShop v1.4
Copyright (c) 1997,1998; Microburst Technologies, Inc.
http://www.uburst.com

Introduction

uShop is an on-line shopping system designed to make on-line shopping the way it should be - easy and intuitive for both the shopper AND the web page designer. uShop consists of a collection of Java 1.0 applets that plug easily into any web page thus giving the developer almost total creative freedom and the ultimate in flexibility when developing the store's web pages.

This manual describes how to setup uShop and use uShop's applets.

NOTE: uShop consists of a number of small files that end with the extention .class. When these .class files are linked onto web pages (via the .html tag &ltAPPLET...>) they are called applets. Throughout this manual, we refer to these .class files interchangably as "class files" and as "applets".

Getting Started

Upon receiving uShop, you should make a new directory for it on your desktop computer. Unzip the entire uShop .zip file into this new directory.

Once uShop is unzipped, you should make sure that you received the files Ok by opening the uShop.html page with your browser. This can be done by double-clicking on the uShop.html file or by choosing "Open File in Browser" from your browser's File menu and specifying the file "uShop.html". If you received uShop Ok, all of the uShop example stores and applets should be functioning fine (except the order applets, of course). If not, contact us at support@uburst.com

Web Page Development

So now you have the uShop example and reference pages working on your desktop computer...what's next?

If you haven't used uShop before and/or would like to get familiar with using the uShop applets in general, then we suggest you go through our brief uShop Tutorial. The tutorial instructions are located in the file "tutorial.txt". You may want to print the instructions out, or just open them in a text editor so that you can cut-n-paste from the tutorial into the tutorial's example store.

If you are already familiar with uShop, then you can start developing the web pages for yout web store.

NOTE: We recommend that before you begin, you create a new directory on your desktop computer in which all of your store's .html pages will be saved. You will also need to copy all of uShop's .class files into this directory.

While developing your store's pages, you can use any .html editor that you want and you can get as creative as you want with the layout of your pages. Many people like to use one of the example stores or the tutorial's example store as a sort of template for their own store, but you are free to use your own imagination.

Also, while developing your store's pages, don't forget about the uShop On-Line Reference. It provides a complete list of all of uShop's applets along with examples and code that you can cut-n-paste into your store's pages. Browsing the reference also helps to give ideas of which input applets to use for your store's products.

NOTE: One of the nice features of a Java-based on-line shopping system (as opposed to a CGI-based shopping system) is that you can virtually test your entire store right on your local desktop computer. That is, you can open your store's pages and test them out right on your own computer - there is no need to transfer them to your server until you are ready to open for business.

Installing Files on Your Server

When installing your pages on your server, you will also need to transfer all of the uShop .class files that you are using in your store onto your server. Put them in the same directory structure as they were on your desktop computer. That is, if you had them in the same directory as your store's .html pages, then put them in that the same directory as your .html pages on the server.

IMPORTANT: You must also transfer the uShopProducts.class and the uShopLibrary.class files to your server even though you did not use them in your pages. These files are used by the other uShop applets.

Also, the .class files are considered to be "byte code", so when transferring them to your server, you must transfer them as BINARY files (as opposed to ASCII or TEXT file transfers).

CGI Script Configuration

uShop has one CGI script that must be configured and put on your server if you are going to use any of the uShop applets that have CGI in their name. (This will apply to most people since using the CGI script is the best way to ensure secure transactions).

To configure the ushop_cgiscript, you will need to open it with any standard text editor - such as NotePad or WordPad. Answer the 13 questions at the top of the script and save the file as text. The 13 questions mostly deal with some store preferences like where you want to email the order notications, but there are also some server specific questions such as where Perl is located on your server. The script has provided suggestions of the most common settings, but you may need to ask your internet service provider if you do not know.

Also, you may need to rename the script based on the extension that your server requires to run CGI scripts. That is, some servers require that CGI scripts end with the extention .pl while other servers require the extension .cgi. If you do not know what extention your server requires to run CGI scripts, you can ask your internet service provider.

When done configuring the ushop_cgiscript, you will need to transfer it to your server (just transfer it as a normal ASCII or TEXT file). Put it in the cgi directory on your server and, if necessary, change the permissions on the file to read and execute (chmod 755).

Remember to also create the "orders" directory on your server and give it the appropriate permissions - as specified in question 10 of the script setup.

TIP: You can test that the CGI script is setup correctly by opening up your browser and typing the full path of the script into the LOCATION box on your browser. Example: Type http://www.uburst.com/cgi-bin/ushop_cgiscript1p3.pl into the LOCATION box on your browser. If it returns a page displaying uShop's copyright notice, then the script is configured correctly. If not, then something is not setup correctly, see the Debugging section below.

Making Transactions Secure

In order to ensure that transactions are secure, uShop implements a two step process.

STEP 1: Step 1 is to securely get the order information from the customer to a file on your secure server. To do this, you must setup the uShop CGI script on your secure server and set the scriptpath parameter in the uShopOrderCGI applet to point to the CGI script on your secure server. The URL of the script on your secure server will probably start with https which indicates that all communication with the server will be encrypted with the SSL protocol. An example secure scriptpath parameter is:

&ltPARAM NAME=scriptpath VALUE="https://www.mydomain.com/cgi-bin/ushop_cgiscript1p3.pl">

Note: Whether you put your store pages on your public server or you put your store pages on your secure server, as long as you specify the scriptpath parameter to point to the uShop CGI script on your secure server the transactions will be secure. Some people, however, prefer to have their store pages on the public server and just the order form on the secure server. This allows customers to see that have been transferred to a secure server (as indicated on their browser) before actually placing the order. If you would like to set uShop up this way, you must use the uShopOrderButtonCGI applet handle transferring the data from the applets on your public server to the applets on the secure server. See the instructions below to setup the uShopOrderButttonCGI applet.

STEP 2: Step 2 is to securely get the order information from the secure server to the store owner. To do this securely, the payment information should not be emailed to the store owner since regular email is not secure. The ideal thing to do, is to have your Internet Service Provider setup PGP email for you or to use the uShopOrderReaderCGI applet that has been included with uShop.

The uShopOrderReaderCGI applet allows the storeowner to login and securely read the order and payment information from the secure server. That is, when an order is placed, the storeowner will receive an email notification of the order - containing NO sensitive payment information. The store owner would then go to a page on his secure server that contains the uShopOrderReaderCGI applet and type in the order number and his/her password in order to securely read the order and payment information from the secure server. While this is not as easy as PGP email, it is not too bad if you just bookmark your uShopOrderReaderCGI page.

In order to setup the uShopOrderReaderCGI applet for your store, just set the applet's scriptpath parameter to the same secure URL that you specified above in Step 1 (beginning with a https). Example:

&ltPARAM NAME=scriptpath VALUE="https://www.mydomain.com/cgi-bin/ushop_cgiscript1p3.pl">

Configuring the uShopOrderButtonCGI

In order to increase page performance, it may be desireable to put all of the product pages on the faster public server and only put the order form on the encrypted secure server. uShop has added the ability to do this via the uShopOrderButtonCGI applet. To use this button, you add it to your pages as you would any other uShop applet - and follow just a few more setup steps. Here is an example of how to setup the uShopOrderButtonCGI applet for use with your store. (Note that you are free to change the directory names to whatever you like.)

Make a directory called classes on your secure server.
Transfer all of uShop's .class files into that directory on your secure server.
Open the file order.template and change the codebase parameter of the applets in the order.template file to point to your classes directoryon your secure server.
After saving the changes to the order.template file, transfer that file into the classes directory on your secure server also.
Add the uShopOrderButtonCGI to your store pages and be sure to specify the order_page parameter to be "../classes/order.template"

And that should do it. Try it out!

NOTE: You can edit the order.template file as you would edit any other .html page. Feel free to change the parameters of the applets on the .template page or even add new ones. Just remember that you will have to specify the codebase parameter for each applet on this order.template file to point to the classes directory on your secure server.

A Word About The SMTP Order Applets

We have provided a series of uShopOrderSMTP applets with uShop that do not require the use of any CGI script. These applets, however, send the orders via regular SMTP mail so orders placed with these SMTP applets are not necessarily secure. To ensure secure transactions you should use the uShopOrderCGI applets in correlation with the ushop_cgiscript and the uShopOrderReaderCGI applet. We thought about not including them with uShop, however, they can come in handy if you just wanted to give customers a way to contact you or give them other options besides payment by credit card (e.g. payment by check, money order, or a previously configured account).

In any case, not everyone can use the SMTP order applets with their server. That is, in order to be able to use the SMTP order applets, your web server must also be a mail server that uses port 25 to send SMTP mail. To determine if you can use the SMTP applets you can go ahead and try them out on your server or:

Open a Dos Window.
Type: telnet yourserver 25 (where yourserver is the ip address or domain name your web server - ie. www.mystore.com).
If it connects and the domain name that appears in the telnet window is your own, then you can probably use the uShopOrderSMTP applets.

If you try using the SMTP applet on your server and you get a "Connection Error" message, then you cannot use the SMTP order applets.

Debugging

Here is a list of some common problems/solutions that developers have come across when developing with uShop.

Problem: None of my applets load - I just get an exception error.
Solution: This is usually caused by not having both the uShopProducts.class and the uShopLibrary.class transferred to your server. Although you don't actually add them to any of your store's pages, they are required by the other uShop applets.

Problem: Some of my applets load, but some do not - they just give a "string index out of range" error.
Solution: This most commonly occurs with the uShopInputMenu applet or one of the uShopOrder applets. In the uShopInputMenu applet, it is caused by having an extra comma (,) after the price of the last product in the "products" parameter list - there should not be a comma after the last product in the list. In the uShopOrder applets, it is caused by having a semicolon (;)after the last shipping option - there should not be a semicolon after the last shipping option.

Problem: The background color of my applets is always white - even though I am specifying an RGB value for the "background" parameter.
Solution: This is caused when you try to specify the RGB value using hexadecimal numbers. When specifying the background color as an RGB value, you must use three decimal numbers ranging from 0 to 255 (where 0 = 0 hex, ...., 255 = FF hex). You can also choose one of the standard colors such as "blue","red",... see the description of the background parameter in the uShop On-Line Reference.

Problem: I get a "Server Error" when I try to send an order.
Solution: Usually if you get a "Server Error" it will be because of one of these four things:

The script doesn't have execute permissions. (use chmod 755)
The path to Perl is incorrect. It should be something like this: #!/usr/bin/perl - Ask your internet service provider if you are not sure of the location.
The path to sendmail is incorrect (UNIX servers only). The path should be something like this: $sendmail_path = "/usr/lib/sendmail"; - Ask your internet service provider if you are not sure of the location.
You didn't include the "\" character in your email address. This is required by Perl scripts. It should be something like this: $store_email = "sales\@uburst.com";

Problem: I'm still getting a "Server Error".
Solution: If you are still getting a server error, here are some more things to check.

Make sure you created the orders directory and that this directory has the appropriate permissions.
Make sure that the email address that you are trying to send orders to is a valid email address of yours.
Make sure that the extension on your ushop_cgiscript is correct for your server. Some servers require that the file ends with the .pl extension while other servers require that the file ends with the .cgi extension. Ask your internet service provider if you do not know what the extention of your CGI scripts should be.

Problem: If I type the script path directly into the LOCATION box on my browser, I correctly get the uShop copyright page, But when I try to place an order with one of the uShopOrder applets, I get a "Server Error".
Solution: This will usually be caused by one of two things:

Check that you created the "orders" directory and that you gave it the appropriate permissions as described in step 10 of the script setup.
If using a UNIX server, verify that the sendmail_path that you specified in step 3 of the script setup is correct for your server.

Problem: When using the CGI script, I get a receipt page, but I never get an email notification of the order.
Solution: If the receipt page is being generated ok, but you are not getting any email notification of the order, there are a couple things to check.

Make sure that the email address that you specified in step 6 of the script setup is the email address you want to send the order notification to.
If using an NT server, you may need to change the SOCK_STREAM setting in step 5 of the script setup. Try using: $SOCK_STREAM = 2;

Problem: I am using the uShopOrderButtonCGI applet to transfer to the secure server when the customer is ready to checkout, but the shopping cart on the secure server keeps coming up empty.
Solution: This is usually caused if the initial line of the order applet on your order.template is seperated over two lines. That is, the first line of the order applet must be kept on one single line:
&ltAPPLET CODE = "uShopOrder2CGI.class" ..... WIDTH=450 HEIGHT=750>

Problem: Sometimes my applets show up and sometimes they don't.
Solution: This problem only seems to occur when all of the following conditions are met: 1)Using the Microsoft Internet Explorer 4.0, 2) Using the uShopInputMenu applet, and 3)Using a table to position the applet. For some reason, the Internet Explorer 4.0 does not always refresh applets when they are in tables. And since this only seems to affect the uShopInputMenu applet, if you are using the uShopInputMenu applet, it would be best not to put it in an .html table. Note that this seems to occur only after returning to a page that was already loaded. Note also that this problems has been fixed in later versions of IE.

Still having a problem? Feel free to email us at support@uburst.com.

Developer Tips

Here are few tips that can help when developing your on-line store:

For organizational purposes, you may want to keep all of the uShop .class files in a directory separate from your .html code. You can do this via the applet's codebase parameter. That is, the codebase parameter can be used to point to any directory in which you have placed the .class files. For example, if you made a subdirectory called "classes" and placed all of uShop's .class files in that directory, then you would specify the codebase parameter as: codebase="./classes/". Note that codebase parameter would be located directly after the applet's CODE parameter. Example:
&ltAPPLET CODE="uShopInputStandard.class" CODEBASE="./classes/" WIDTH=450 HEIGHT=35>
Don't forget about the uShop On-Line Reference. You can cut-n-paste example applet code directly from the reference into your pages.
When setting the WIDTH and HEIGHT of each applet, leave a little extra space - particularly in the WIDTH - than is needed. This is because while Java runs on all platforms, the windowing systems of different platforms are slightly different. UNIX systems, for instance, tend to stretch the applets out a little more than on Windows systems.
Remember that your pages will be viewed with monitors that have different resolutions - so you may want to design your pages for the more common low resolutions of 640x480 or 800x600.
Test your store using different browsers. For the most part, your store pages will look the same on all browsers, however, there may be some slight differences that you may or may not like.

Upgrading from uShop Lite

To upgrade from the working trial version of uShop - uShop Lite - all you have to do is replace ALL of uShop Lite's .class files with the new uShop 1.4 .class files. We made no changes to the ushop_cgiscript1p3 script, so you do NOT have to replace the CGI script.

Upgrading from uShop 1.2

To upgrade from uShop 1.2, there are just a few things that you would need to do:

Replace ALL of the uShop 1.2 .class files with then new uShop 1.4 .class files.
Replace the ushop_cgiscript with the new ushop_cgiscript1p3. This requires answering the questions at the top of the script again - but you can get the answers to most of these configuration questions by looking at the current ushop_cgiscript that you are using.
The only change that you have to make to the .html code is to the scriptpath parameter in your uShopOrderCGI and uShopOrderReaderCGI applets. Change the name of the script that is executed to the newer ushop_cgiscript1p3.

And that's it! You can now go back and add any of the new uShop 1.4 features/applets to your store.

Upgrading from uShop 1.3

To upgrade from uShop 1.3, all you have to do is replace ALL of the uShop 1.3 .class files with the new uShop 1.4 .class files. We made no changes to the ushop_cgiscript1p3 script, so you do NOT have to replace the CGI script.

Frequently Asked Questions

Q) What is uShop?
A) uShop is a Java-based on-line shopping system designed to make on-line shopping easy and intuitive for both the shopper and the web page designer.

Q) Who should use uShop?
A) uShop is ideal for small to medium sized on-line stores.

Q) How does uShop work?
A) uShop is a collection of Java applets and one CGI script that together create a powerful and extremely flexible On-Line Shopping System. The applets serve as a Java frontend to the CGI script and can be easily plugged into any web page - Thus, offering the ultimate in flexibility when designing your web pages.

Q) Is there a tool to help setup uShop applets?
A) Not yet. For now you just have to add the applet calls directly into your .html pages.

Q) Where is the data for your products stored?
A)Right now, the data for each of your products is stored in the .html page itself. You specify the product information in the parameters of each input applet. If you want to change the price, for instance, then you just have to edit the .html page to change the price.

Q) Is there a way to enter the product information into a data file and have uShop create the input applets for you?
A) Not yet. But we are working on serveral options that will allow the store owner to control product information from a data file - without having to edit the .html code at all.

Q) Is there an option to interface uShop with a database?
A) Not yet. But we are looking into providing that ability in the future.

Q) Is uShop a stand alone system or are their monthly service fees?
A) uShop is a complete, stand-alone system. When you buy uShop, you get the complete collection of uShop applets and you can put these applets on whatever server you choose to host the web pages of your on-line store.

Q) What are the system requirements of the store owner?
A) The server on which the store owner is going to host the on-line store pages must be either a UNIX server or an NT server. It must also be able to run Perl CGI scripts.

Q) Do you provide a CGI hosting service?
A) YES! For a low month rate, we do offer the use of our Secure Server to host your uShop CGI script. This means that the store owner can setup and have control over all of his/her product pages on his/her public server, and then just link to our secure server when the customer is ready to checkout. This eliminates the requirement of the storeowner needing to be able to run CGI scripts.

Q) What are the system requirements of the customers?
A) The only requirement of the customers is that they have a Java-enabled browser. We have successfully tested uShop on the most common browsers (Netscape 3.x and later, IE 3.x and later) running on the most common operating systems (Windows, NT, Unix, and Mac).

Q) Do you have to use Frames?
A) No. You can use virtually any page layout scheme for your store that you want. Just plug the uShop applet's into the .html pages and uShop will do the rest.

Q) Can I configure different tax rates for customers from different states?
A) YES! (English version only). You can use the "taxtable" parameter to specify different tax rates for different states. Use the "taxrate" parameter to specify the default tax rate.

Q) Can I configure different tax rates for customers from different cities of different states?
A) Not yet.

Q) Can I configure different tax rates for customers from different countries?
A) YES! (International versions only). You can use the "taxtable" parameter to specify different tax rates for different countries. Use the "taxrate" parameter to specify the default tax rate.

Q) Can I configure the shipping charges?
A) YES! uShop provides the ability to calculate shipping based on 1)Total Weight, 2) Subtotal, or 3)As a Flat Fee. See the description of the "shipping" parameter in the order applets for more information.

Q) Can I configure the handling fee?
A) YES! The "handling" parameter of the order applets allow you to specify a default handling fee that will be charged on all orders.

Q) Can I configure the handling fee based on where the customer lives?
A) YES! uShop provides the ability to set different handling fees for customers from different countries. See the description of the "handlingtable" parameter in the order applets for more information.

Q) Can uShop validate credit card numbers?
A) YES! Just set the "validate" parameter in the order applets to "yes".

Q) How does uShop validate credit card numbers?
A) Based on the selected credit card, uShop 1) Checks the number's prefix, 2) Verifies the number of digits in the number, and 3) Performs a MOD 10 checksum on the number. No external resource/service is required for this functionality.

Q) What if I don't accept credit card orders?
A) No problem. The "payment" parameter of the order applets allow you to list only those payment methods that you accept.

Q) Is there a way to request no payment information at all?
A) YES! We have added the uShopOrderContact applets which do not request any payment information at all.

Q) Is there a way to keep all of the store's product pages on the faster public server and then just put the uShopOrder form on the encrypted secure server?
A) YES! We have added the uShopOrderButtonCGI applet which will handle transferring the product information to a uShopOrder applet on your secure server.

Q) Is there a way to have the customer print out the order and just fax it to the store owner?
A) YES! Since not all browsers allow you to print Java applets, we provided the uShopPrintButtonCGI applet and the uShopPrintFormCGI applet, which allows you to generate a printout via a CGI-generated .html page.

If you have additional questions or comments about uShop, feel free to email us at: support@uburst.com

uShop User's Manual

Introduction

Table of Contents