Quick Setup Guide for Perl-Online Ordering System (POOS)

This document is provided to users of Biz Net Technologies POOS system for the purpose of allowing them to produce their own phtml files as described herein. This was done to allow our clients to save money on setup and maintenance of their own shops. We support this effort by offering further assistance at the current consulting rates.

If you read this documentation and provide to us at least a partially correct POOS file system to which we have to make corrections (charged) you have still saved yourself money. We would recommend that you send us sample phtml with a minimal number of items included so that we can check them (charged) and make recommendations before you do a lot of incorrect work.

Technical Contact:	Korey S. Mercier	kmercier@bnt.com
Sales/Marketing:	Biz Net Technologies	biznet@bnt.com

last revision: June 1, 1995

COPYRIGHT NOTICE:

The material in this document is proprietary information of Biz Net Technologies and is not to be redistributed without first obtaining written permission from Biz Net Technologies. The POOS system programs are copyright (C) 1994 by Biz Net Technologies.

INTENDED AUDIENCE:

Those vendors who wish to write their own (p)html source for use with the Perl Online Ordering System (POOS).

INTRODUCTION:

The Perl Online Ordering System is a system of scripts for implementing online ordering on the World-Wide-Web. The system is designed to be flexible so that each individual shop can take on its own look and feel. Essentially what it does is provide stateful html sessions, including tracking orders and other attributes for each user accessing the system.

PHTML FILES

The source for each shop will be set up using html files with a couple of extensions. We call these PHTML files to differentiate them from standard HTML files for the sake of this discussion. These files are _not_ read directly by the httpd server, but are processed by a CGI script in the POOS system which makes substitutions allowing for stateful sessions. The PHTML files can reside anywhere on the filesystem, though any standard HTML files, images, or other files to be served must reside in a subdirectory of the DocumentRoot directory as setup in the srm.conf file of the httpd server, or in a user's public_html directory. For those clients leasing space from Biz Net Technologies, your phtml files should reside in your public_html directory.

IMPORTANT: If your PHTML files link to html files without the PHTML extensions, the state information for the user MAY BE LOST! Therefore it is best not to link to other html documents from within your catalog. You may opt however to have html files with introductory information about your business, etc, and then a link to the catalog from there. This link will be

<A HREF="/htbin/client/menu">

where client is replaced with an identifier unique to that client. (Contact Biz Net Technologies for that assignment). Optionally, your entire PHTML tree will be linked to from the Biz Net home page using such a link. Links to gif files will be in the standard format, NOT using the special syntax presented below.

eg. <IMG SRC="/~client/file.gif">

PHTML FORMAT and SUBSTITUTIONS

The following strings will be globally replaced in your PHTML files by the menu script for your catalog:

	%u - replaced with the URL to the client's menu script
	%o - replaced with the URL to the client's order script (see
	     LINKS TO THE VIEW ORDER PAGE below)
	%c - replaced with the user COOKIE, which is how each user
	     accessing the catalog is identified and differentiated
	     from other users.
	%% - replaced with a single '%' character

Therefore each link within your PHTML files which points to another PHTML file in your tree will be in the following format:

<A HREF="%u/file.phtml?%c">link name</A>

This format should be followed exactly, with only the filename being different (and of course the link name). (Note that the .phtml filename extension is not required, you can name your files as you like, this just makes the illustration clear.) The path to file.phtml is relative to your CatalogRoot directory (this is configured in the menu script, usually ~client/public_html). You may have subdirectories off of this directory so that file.phtml becomes subdir/file.phtml

LINKS TO THE "VIEW ORDER" PAGE

You will need to provide the user link(s) to a second script which will show them everything they have ordered thus far. This should at least be provided from the main catalog index. This link will be in the following format:

<A HREF="%o/back.phtml?%c">link to show order</A>

where back.phtml is a link to whichever page you want the user to come back to when they click on the back href from the show order page. Again, the path to this file is relative to your CatalogRoot directory (usually ~user/public_html).

LINKS FOR ORDERING ITEMS

This will be the most difficult and time consuming part for you to set up, the forms for ordering items from your catalog. If your inventory is tremendously large, Biz Net may be able to provide you with script(s) to produce phtml files from a database of your inventory. Any such work will be entirely billable on a per-hour basis at Biz Net's current consulting rate. This option may be attractive if your inventory or prices change often, though it may restrict the flexibility of your catalog's look and feel to some degree.

Forms for ordering items may appear in any of your phtml files and may each list up to 620 items. Also, it is possible to have more than one form per page, this is entirely up to you. It is a good idea to provide the user with some simple instructions on how to use the form (i.g. reminding them to click the "submit" button before leaving the page).

Each listed item has at least three attributes: item-identifier, item-price, and quantity. There may also be an unlimited number of other attributes, for example, size, color, or other options. The quantity attribute may have a unit attached to it (i.g grams, ounces). Form elements can consist of checkboxes, textfields, select lists (but not multiple selection select lists), radio buttons, and hidden elements. If there is no quantity attribute for an item-identifier that is selected, the quantity will default to one. The price may be selected in one of two ways: using a hidden field with the name of 'price' or in an attribute field's value which contains a string in the form $dd.dd (this enables the use of a select list to choose between options that may have different prices, see examples at the end of this document).

Each item listed has a required two digit* prefix used for each of its attribute names, to distinguish these attribute names from other items in the same form. These numbers need not appear in any particular order, but must be unique on a per item, per form basis. For example the form elements for item number 5 in a form will have names like:

	05Price		-item price (usually a hidden field)
	05Qty		-quantity selected (defaults to 1 if not present)
	05Item		-item number and/or description
	05Size		-(optional attributes - name as you wish)
	05Color		-   "       "              "       "

* Shopkeeper's requests to have more than 100 items listed per page prompted us to extend the two-digit code, you can now use a digit and an alphabetic as a unique identifier (upper and lowercase are distinct).

The script which processes order submission performs all matches as case insensitive. The three basic attributes (price, item, and quantity) are matched by these expressions: (not including the required two digit prefix)

	quantity:	/^(quan|qty)/i
	price:		/^price/i
	   or		/\$(\d+(\.\d\d)?)/   (mathches VALUE part, NOT name)
	item:		/^item/i

If these are meaningless to you just use qty, price, and item as the form element names.

The item is considered "ordered" if and only if the two digit number followed by the string "item" is present in the name part of the name=value pairs of the submitted form. However if the quantity field (if there is one) for the item is blank or zero, the item is NOT ordered. The price field defaults to 0.00, so unless you really mean for it to be free, don't forget to include a price attribute for each item. Please keep these very important facts in mind as you write your catalog pages.

Form Headers

The form method is POST and the action is "%u/file.phtml" resulting in a form header like this:

<FORM METHOD="POST" ACTION="%u/file.phtml">

where file.phtml is the phtml file to send after the form has been posted. It can point to the same phtml file, the master catalog index, whatever you wish.

EVERY form you use MUST contain the following hidden element to enable state to be maintained:

<INPUT TYPE="hidden" NAME="cookie" VALUE="%c">

Examples

I realize that you are probably very confused by now, so it is best to take a look at a few samples.