General purpose shopping cart and ordering programs

demo page 1 | demo page 2

Read this entire document for the description, usage, features, and installation instructions for use of these programs. The source code is available here, but be warned that development is in progress. Please indicate unoffical and official versions (i.e., versions not released by me and versions released by me) by prefixing a `U' or an 'O' before the version number. I'd appreciate it if you could notify me of any modifications you may make so I can incorporate them into the official version. You, the user, are responsible for everything the program does.

Description

These two programs (referred to as shopper and order) will let users (customers) shop in an interactive manner on your www site. The program uses the notion of cookies to accomplish this goal, so it needs to be used with a browser (Netscape Navigator, Internet Explorer) and server combination that understand cookies. You yourself don't really need to understand much about cookies to use this program.

You can test this demo by clicking on one of the two pages above which are almost identical except for the items listed on the page. The purpose of this is to show how this program works across pages with different options. Here's a brief description of things you can do:

• By clicking on the "add to cart" button next to an item, you can add any of the items in each page.
• In some cases, the shopper program may re-direct to you a new page, or may refresh the page. This can be controlled at whim (see below).
• You can search the entire catalog and select items that are displayed from the results of your search.
• You can add items to the cart via the use of a form
• At any point, you can list the items you've ordered, empty your cart, or check out from the menu above.
• Upon check out, you will be presented with an order form that will let you modify the quantities and change your choices (simply by deleting the quantity).
• The order form interfaces with my order program (which is separate).

All this is done in relation to my band's products. Please DO NOT submit your order (you can test it) unless you're interested in ordering.

Usage

The general purpose shopping cart and ordering programs support the following commands and features. For the purposes of this example, the CGI scripts are assumed to be named shopper, order, and form_cookie. Literal characters (i.e., characters you should type in as is) are indicated in a fixed-width font. Variable characters are in italics. See the source code of the demo pages for real uses of program.

shopper?list

will list the items currently in the shopping cart.

shopper?item_name+quantity+relative_url

will add item_name to the shopping cart with the specified quantity and re-direct the browser to the page specified by relative_url.

shopper?clear+relative_url

will empty the shopping cart and re-direct the browser to the page specified by relative_url.

shopper?catalog

will list the entire catalog in checkout mode

shopper in GET mode

same as shopper?list

shopper in POST mode

will search the items in the catalog that match the string entered in the POST operation.

The order program interfaces with the results of shopper program. You can also use it directly if you wish, as shown here.

The form_cookie program is a way to add multiple items to the order cookie at the same time. This has two advantages: for long lists, the POST function is used, and you can order multiple items at once. See the second demo page for an example of its use.

The item list file that specifies the items and their prices (and an optional description) has the following format:

product_name low_quantity high_quantity price_per_item shipping_price_per_item | description_of_item

For example,

tatp_tshirt 1       1 10.00 3.00 | Traversing a Twisted Path T-shirt
tatp_tshirt 2   10000 10.00 3.00 | Traversing a Twisted Path T-shirts

The first line has the item tatp_tshirt, the quantity range for this description is 1 through 1, with a price $10.00 per item, with a shipping charge of $3.00 per item (this can be disabled by using a 0.00). The description of the item (in plain English) is indicated by a '|' followed by a text string. If this isn't present, the item name will be used as the description. Comments can be inserted using lines whose first character is a '#'. Here is the item list file I've used in this demo.

Features

There are no bugs. Here is a list of caveats and features you should be aware (beware?) of.

• Not all browsers support cookies. Thus, you can use the command shopper?catalog to list the entire items file in check out mode.
• You can use the "add to cookie" feature via a form (using the program form_cookie included in this distribution). See the demo page 2 for details on this.
• For URL redirection, you have the option of reloading the same page (page 1), redirecting users to a new document (the "empty cart" option), which could be "/cgi-bin/shopper" (or "/cgi-bin/shopper?list") to list the items ordered thusfar (page 2).
• relative_url above must must be a relative URL according to the DEFAULT_URL defined in the cgi_defines.h header file. That is, relative_url will be concatenated with DEFAULT_URL to create the redirect url.
• Once the order form has been displayed, it can be interfaced with any order-handling program. In the current demo, it interfaces with the order program which uses the same file for the item descriptions, but you could just have a simple script that mails the results of the form to some address.
• Items that have been added to the cart can be removed in the end through the order form (simply deleting the entry in the field should cause it to be ignored).
• A long string is built up that keeps track of the order (just the name and quantity) which takes on the form item_name-quantity separated by '|'. This string should not exceed 4096 characters in length, so choose your item names wisely (even though 4 KB is a lot). If, on average, you have 5 characters per item_name, and a single digit quantity, you can have up to 512 different items!
• To distinguish singular and plural forms of items, simply use two item descriptions with the same item name but different quantities (see above for example). This is just to make things slicker.
• Note that cookies are supposed to last until the date specified in the Expires/Max Age directive, but my experience is that they may not depending on the browser. It's best to assume cookies last only until the user agent doesn't exit.
• Don't have a item name in the form that starts with uppercase 'X'. They will be used for special processing instructions in the program.
• I think tables are best used in this program instead of pre-formatted text. Much as I didn't wish to change (the initial versions used pre-formatted text), I decided it presented the most elegant result.

Installation instructions

To install the program, you need a C compiler. Edit the defines in cgi_defines.h and sc_defines.h (explained in detail there) and the Makefile appropriately, and type in `make' at the prompt; it should install without a fuss (at least on an Unix system). The programs generally are referred to as shopper and order, but in this demo, they're called thshopper and thorder, to distinguish them from other shopping and ordering programs. This is configurable in the Makefile.