uShop User's Manual

uShop v2.0
 Copyright (c) 1997-1999; 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 <APPLET...>) they are called applets. Throughout this manual, we refer to these .class files interchangably as "class files" and as "applets".

Table of Contents

  1. Getting Started
  2. Web Page Development
  3. Installing Files on Your Server
  4. CGI Script Configuration
  5. Making Transactions Secure
  6. Troubleshooting
  7. Developer Tips
  8. Upgrading from uShop Lite
  9. Upgrading from uShop 1.2
  10. Upgrading from uShop 1.3
  11. Upgrading from uShop 1.4
  12. Frequently Asked Questions

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 your web store. Here are just a few additional notes to consider when developing your 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.

NOTE: In order to more easily maintain uShop's ever-growing collection of .class files, it may be desirable to put all of the uShop .class files in their own directory. This can be done with the use of the CODEBASE parameter. See codebase.html for a complete description of using the CODEBASE parameter with the uShop applets.

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

NOTE: Also, while developing your store's pages, don't forget about the uShop Applet 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.

NOTE: We do suggest setting up just a few .html pages at first and then testing out the whole order process before you spending too much time developing all of your store pages. This allows you to see how the whole order process will work and ensures that your server meets all of the requirements.


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: Be sure to transfer all of the required uShop .class files to your server also. The required .class files - as specified in the uShop Applet Reference (such as the uShopProducts.class, uShopLibrary.class, and the uShopMessageWindow.class) - are used by the other uShop applets even though you do not actually add them to any of your pages.

Also, the .class files are considered to be "byte code", so when transferring them to your server, you must transfer them as BINARY or RAW files (as opposed to ASCII or TEXT file transfers). If you transfer them in the wrong transfer mode, then you will usually see a "Bad Magic Number" error.


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

In order to configure the CGI script for your server, you can follow the instructions below or use our new "uShop CGI Setup Wizard" at our uShop 2.0 Reference Site. The "uShop CGI Setup Wizard" will actually generate a CGI script for your server along with customized instructions on how to download it onto your server.

If not using the "uShop CGI Setup Wizard", you will need to manually configure to CGI script. To do this, start by opening the ushop_cgiscript.pl file 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_cgiscript.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 Troubleshooting section below.

NOTE: If you have any trouble configuring the CGI script for your server, be sure to check our out "Troubleshooting" pages at our reference site - just follow the "Troubleshooting" link at our uShop 2.0 Reference Site


Making Transactions Secure

In order to keep our Secure Transaction pages as up-to-date as possible, we have moved the pages describing how to ensure secure transactions to our reference site - just follow the "Making Transactions Secure" link at our uShop 2.0 Reference Site


Troubleshooting

In order to keep our Troubleshooting pages as up-to-date as possible, we have moved the Troubleshooting pages to our on-line reference site - just follow the "Troubleshooting" link at our uShop 2.0 Reference Site


Developer Tips

Here are few tips that can help when developing your on-line store:
  1. 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 the codebase parameter is specified directly after the applet's CODE parameter. Example:

    <APPLET CODE="uShopInputStandard.class" CODEBASE="./classes/" WIDTH=450 HEIGHT=35>

    See codebase.html for a complete description of using the CODEBASE parameter with the uShop applets.

  2. Don't forget about the uShop Applet Reference. You can cut-n-paste example applet code directly from the reference into your pages.

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

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

  5. Whenever you make changes to the any of the applet parameters on a web page, clearing your browser's cache and reloading the page does not always work. Therefore, it is recommended that whenever you make a change to an applet's parameters, be sure to exit the browser and restart it - thus ensuring that the page is properly reloaded and the new parameter settings take effect.

  6. Netscape 4.6 and IE 4.72 and later work particularly well with Java applets so during development (when you are constantly exiting/restarting your browser to test) you may want to consider using one of these browsers.

  7. 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 2.0 .class files. Since the uShop CGI script that is distributed with uShop Lite (and which is also downloadable from the uShop CGI Setup Wizard) is the same as the uShop CGI script that is distributed with the full version of uShop 2.0, it is NOT necessary that you 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:
  1. Replace ALL of the uShop 1.2 .class files with then new uShop 2.0 .class files.
  2. Replace the ushop_cgiscript1p2 CGI script with the newer ushop_cgiscript. 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.
  3. The only changes that have to be made to the .html code is to set the new parameters of the uShopOrder applets. This includes changing the scriptpath parameter to match the name of the newer ushop_cgiscript and setting the countries parameter to list countries that will appear in the drop-down country list.
And that's it! You can now go back and add any of the new uShop 2.0 features/applets to your store.


Upgrading from uShop 1.3

To upgrade from uShop 1.3, there are just a couple of things that you would need to do:
  1. Replace ALL of the uShop 1.3 .class files with then new uShop 2.0 .class files.
  2. Set the new parameters of the uShopOrder applets - such as the countries parameter to list the countries that will appear in the drop-down list. See the uShop Applet Reference for a complete description of the uShopOrder applet parameters.
And that's it! You can now go back and add any of the new uShop 2.0 features/applets to your store. Note that you do NOT have to replace the ushop_cgiscript since it is backwards compatible.


Upgrading from uShop 1.4

To upgrade from uShop 1.4, there are just a couple of things that you would need to do:
  1. Replace ALL of the uShop 1.4 .class files with then new uShop 2.0 .class files.
  2. Set the new parameters of the uShopOrder applets - such as the countries parameter to list the countries that will appear in the drop-down list. See the uShop Applet Reference for a complete description of the uShopOrder applet parameters.
And that's it! You can now go back and add any of the new uShop 2.0 features/applets to your store. Note that you do NOT have to replace the ushop_cgiscript since it is backwards compatible.


Frequently Asked Questions

In order to keep our FAQ pages as up-to-date as possible, we have moved the Frequently Asked Questions pages to our on-line reference site - just follow the "Frequently Asked Questions" link at our uShop 2.0 Reference Site


For technical support, please see our Technical Support Page at: http://www.uburst.com/support.html