 Chapter 7 |
 Table ofContents |
|---|
MiniVend keeps track of who is ordering what by including in the URL a session id: a random string which is different for each customer browsing the catalog.
So that the session id can be included in URL's within catalog pages, every page in the catalog is served up by MiniVend running as a cgi-bin program. Here is an example of such a URL:
An explanation of each part:
Once the customer has finished, the completed order is emailed to the vendor.
The product code must be the first field in the line.
Here is an example of a products file:
IMPORTANT NOTE: The items must be separated by a single tab character. The items are lined up for your reading convenience.
This version of MiniVend implements the database in either GDBM, DB_File, or in-memory format. If you use DBM, large catalogs can be used without using too much memory; or slowing down performance in static mode. The DBM files are built automatically at MiniVend startup from the products file -- if it has not changed they are not built. If the only DBM type on your system is NDBM, an in-memory product database will be used. Catalogs of more than, say, 5,000 items will use large amounts of memory.
IMPORTANT NOTE: The field names must be on the first line of the products.asc file. These field names must match exactly the field names of the [in_field] tags in your catalog pages, or the MiniVend server will stop with an error.
When the products.asc file changes after import or edit, the DBM database is re-built upon the next server start.
The first page displayed in the catalog, if no argument is supplied to the vlink or svend cgi-bin program, is "catalog.html". This page will contain links to other catalog pages with the [page] element. Individual products can be ordered by the [order<item-code>] element, which brings up the order page "order.html". The order page contains input boxes for the customer to type in their name and address. Once the order has been sent the "confirmation.html" page is displayed.
If you use the the vendpage manpage utility, you will be able to write the pages in normal HTML, then convert them en masse to the Vend format. MiniVend tags (the ones in square brackets) can be passed in as HTML comments -- see the vendpage manpage for details.
You will normally not want to include regular hypertext links to pages outside of the catalog. Such links will not include the session id, which means that if the customer follows an external link back to the catalog the list of products ordered so far will have been lost.
Inline images, on the other hand, are served in the normal fashion. You should include a regular<IMG SRC="URL"> element, where the URL refers to a graphic image.
The following elements can be used in catalog pages:
Also allows specification of secure pages if the target ends with the string __secure (which will be stripped). If so specified, the page will be called with SecureURL instead of VendURL .
If frames are enabled, this will expand to:
If frames are not enabled, this will expand to:
Two types of searching are available. The default is a text-based search of the products.asc file. An optional Glimpse search is enabled by placing the command specification for Glimpse in the directive Glimpse .
To use the Glimpse search, you must build the Glimpse index based on files in your ProductDir . If you installed MiniVend in the default /usr/local/lib/minivend, the command line to build the index would be:
You could easily structure files such that they returned matches only for certain words or fields. One method that works well for large products.asc files is to split the products.asc file into small index files (in the example, 100 lines) with the split(1) UNIX command, then index it with glimpse:
This will dramatically increase search speeds for large catalogs, at least if the search term is relatively unique. If it is common string, you will be better off to use the text-based search.
If the Glimpse executable is not found at MiniVend startup, the Glimpse search will be disabled and the regular text-based search used instead.
In particular, all of the item tags described under order page are active. The most useful one might be [item_link], which if properly used, can allow the user to search the catalog for an item, then click a link to go to detailed catalog page for the item. See the sample search.html page for an example.
Use in conjunction with the [more] element to place pointers to additional pages of matches.
The current page will not be a hyperlink. Every time the new link is pressed, the list is re-built to correspond to the current page. If there is no Next or Previous page, that link will not be shown.
See the fr_resul.html or search.html files for examples. Make sure you insert this item between a [more_list] and [/more_list] element pair.
Choose a name for this input field such as "email" for an email address. Set the name attribute to the name you have chosen.
The value attribute specifies the default value to give the field when the page is displayed. Because the customer may enter information on the order page, return to browsing, and come back to the order page, you want the default value to be what was entered the first time. This is done with the [value] element, which returns the last value of an input field. Thus,
will evaluate to the name entered on the previous order screen, such as:
which will be displayed by the browser.
The size attributes specifies how many characters wide the input field should be on the browser. You do not need to set this to fit the longest possible value since the browser will scroll the field, but you should set it large enough to be comfortable for the customer.
These special fields all begin with mv_, and include:
Any input field from the order page can be included using the dollar sign notation.
To prevent a value from being included in the order report, just add it to the ReportIgnore configuration directive.
MiniVend defines some values for use in the search form -- they begin with 'mv_' and are automatically ignored.
This being done, MiniVend assumes the presence of a file salestax.asc, which contains a database with the percentages. Each line of salestax.asc should be a code (again, usually a five-digit zip or a two letter state) followed by a tab, then a percentage. Example:
Based on the user's entry of information in the order form, MiniVend will look up (for our example SalesTax directive) first the zip, then the state, and apply the percentage to the SUBTOTAL of the order (not including shipping). It will add the percentage, then make that available with the [salestax] tag for display on the order form. If no match is found, the entry 'default' is applied -- that is normally 0, but can be anything.
If business is being done on a national basis, it is now common to have to collect sales tax for multiple states. If you are doing so, it is possible to subscribe to a service which issues regular updates of the sales tax percentages -- usually by quarterly or monthly subscription. Such a database can easily be converted to MiniVend format.
The shipping cost database is a tab-separated ASCII file with six fields -- code, text description, criteria (quantity or weight, for example), minimum number, maximum number, and cost. None of the fields are case-sensitive.
The cost is calcluated like this:
An example would be this (the columns are lined up for your reading convenience, the actual entries should have ONE tab between fields!):
If the user selected UPS Blue (code UPSB), and the quantity on the order was 3, the cost of 12.00 from upsb1 would be applied. If the quantity were 7, the next entry from upsb2 would be selected, for a cost of 17.00. If the quantity were 15, upsb3 would be selected, and the quantity of 15 multiplied by 1.60, for a total cost of 24.00.
If a default shipping mode other than 'default' is desired, enter it into the DefaultShipping directive:
This will make the<INPUT TYPE=RADIO NAME=mv_shipmode VALUE=upsg> entry on the order form checked by default when the user starts the order process.
The Tracking directive must be a non-blank value to enable tracking. In addition, if the tracking database is not yet initialized, the Tracking directive is used to initialize the first order number to be placed in the tracking database. After that initialization, the value of the next order number is kept in the database (under the key mv_next_order) and incremented when an order is placed. The incrementation is alpha-numeric, so it is important to have leading zeros in any string value -- i.e., an initial value of Order00009 will be incremented to Order00010, while an initial value of Order9 will be incremented to Ordes0. Also, any non-alphanumeric characters will be stripped -- Order_00000 becomes Order00000.
The tracking is done by entering information in the DBM database tracking in the product directory ( ProductDir ). Orders are tracked under two keys, the actual key (started by the Tracking Directive) and a key that prepends the string "Backend" to the actual key. The entry in the actual key is a facsimile of the emailed order report -- the Backend key is the values selected in the BackendOrder directive, combined with the actual ordered item codes and quantities, separated by NUL characters (ASCII code 0).
To illustrate, take a MiniVend system that has tracking enabled with these two configuration directives in the minivend.cfg file:
When the user places an order for quantity 2 of item number P-133, the tracking database will have two keys/values added:
If the customer left a credit card number with the SSL account information form (see Order Security ), the credit card number and its associated expiration date will be placed in two additional fields:
The scheme allows a history of orders to be kept (the Order00001 key) and a list of unentered orders (the BackendOrder00001 key, along with the CcOrder00001 and ExpOrder00001 keys). An external program can read the tracking database and submit the orders to an order-entry system, removing (or undefining) the BackendOrder, CcOrder, and ExpOrder keys when finished. An rudimentary example script which displays the tracking database is supplied as 'trackrpt' in the bin/ directory. This script could be easily modified to actually perform batch order entry.
Page popularity is simply tracked by storing a count of accesses, with the page name as the key. No additional information is stored. It is designed to give the catalog designer an idea of which features, pages, and menus are popular, and which are rarely used. Since individual page accesses are tracked, it might also give marketing or sales an idea of problems with product perception -- if an item were frequently looked at, but rarely bought, it might be appropriate to re-write the catalog page.
IMPORTANT NOTE: MiniVend attempts to perform operations securely, but no guarantees or warrantees of any kind are made! Since MiniVend comes with Perl source, it is possible to modify the program to create bad security problems. One way to minimize this possibility is to record digital signatures, using MD5 or PGP, of minivend.pl, minivend.cfg, and all modules included in minivend.pl (standard ones are Vend/Server.pm, Vend/Imagemap.pm, Vend/Http.pm, Vend/lock.pm, and possibly Des). Check them on a regular basis to ensure they have not been changed.
MiniVend uses the SecureURL directive to set the base URL for secure transactions, and the VendURL directive for normal non-secure transactions. Secure URLs can be enabled for forms through the [process_target action secure] element, pages through the [pagetarget page frame__secure] element, and access to the secure account information form is available through the [secure_order] element.
MiniVend incorporates additional security for credit card numbers. Any field on the order form which has credit_card in its name will not be written to disk unless it is encrypted. Either an external encryption program, such as crypt(1) or des(1), can be used, or for internal encryption, the Perl Des module can be used. The Des module can be defined at program configuration time, or can be inserted in the minivend.pl configuration section as the line:
The Des module is available at the same sites as Perl Version 5 . It also requires a functional libdes library, which will be harder to obtain.
To accept credit_card fields, you need to define several things in minivend.cfg (or with MAT). First, the directive CreditCards needs to be set to yes. Also, Tracking needs to be enabled, to provide a place to store the credit card numbers as well as a place to store your access password. EncryptProgram also needs to be defined with at least some value. If using the internal Des support, the entries should look something like:
If you wish to use an external encryption program, recognize that this is not nearly as secure as using the internal Des option, for the design of most encryption programs prevents secure transmission of the password. The password has to be sent on the command line, and though MiniVend tries to hide it, not all operating systems will prevent access to the password through the ps(1) command. If you decide this is acceptable, here is an example EncryptProgram definition that will work for many des(1) implementations:
The %p parameter indicates the location where the password will be placed
in the command line, and %f is the placeholder for the input file name.
Consult your des(1) manual page for details on how the command line should be
constructed.
If your encryption program allows the password to be placed on the first line of the text to be encrypted, omit the %p specification. MiniVend will send the password, followed by a newline, before sending the text to be encrypted. This is much more secure than a command line password, but your encryption program may not allow this mode of operation.
If the CreditCards , EncryptProgram and Tracking directives are defined at program startup, MiniVend will prompt for a password before starting the server. This password is checked against a password previously stored in the tracking database (if it exists), otherwise MiniVend prompts for a second entry to verify a new password, which is then stored in the tracking database. Three tries can be made before MiniVend gives up.
If encryption is not enabled, MiniVend will silently overwrite any fields in the order form(s) with X characters. This prevents non-authorized startups from saving any sensitive information to disk.
Frames are accessed by adding a TARGET element to a HREF, naming the frame that the referenced URL should be placed in. MiniVend produces targets with the pagetarget and areatarget elements, which send target tags if frames are enabled (by a [frames_on] element. Any frame name can be used, including the special frames of _top, _blank, _parent, and _self.
As shown in the demo pages, the best way to accommodate both types of browsers is by having an index.html page that sets the beginning frame set. The<FRAMESET> and<FRAME> tags will be ignored by standard browsers, which will read the HTML between the<NOFRAMES> and</NOFRAMES> tags below.
The format of the first set of URLs passed to the frames is important - only ONE MiniVend link must be called. That sets the session ID for the user. If two URLs were called, MiniVend would assign two session IDs to the user, scrambling the context of their navigation. From this single access, all further references to MiniVend are made, though after the first access multiple frame targets can be referenced.
This first MiniVend page that is accessed (with a frame browser) should contain a [frames_on] element. It is the only page that need (or should) contain a [frames_on], which is persistent throughout the session. This page should never be seen by a non-frame browser.
Subsequent accesses to MiniVend URLs will now contain the proper session information, and as long as pagetarget or page elements are used to pass the URLs, context will be maintained.
The [pagetarget page frame] element is used to pass target tags in hyperlinks. The [areatarget page frame] element is used to pass target tags in imagemaps. The [frames_on] and [frames_off] elements enable and disable frame operation. The [framebase frame] element sets a base target for a page.
See the demo pages:
The [body n] element selects a color scheme -- numbered from 1 to 15 -- that is set by the Mv_Background, Mv_TextColor, Mv_BgColor, Mv_LinkColor, and Mv_VlinkColor directives. Each can contain up to 15 parameters, after an opening BEGIN. Here is an example:
The above sequence (set in the minivend.cfg file, or through MAT) defines three color schemes, accessed with [body 1], [body 2], and [body 3] elements in MiniVend pages. The first scheme uses the file /images/blue_pap.gif as the background pattern, and keeps the user's default colors for everything else. It is called by a [body 1] element, which when expanded becomes<BODY BACKGROUND="/images/blue_pap.gif>.
The second scheme defines no background pattern (there is only one file in the Mv_Background directive), but defines a background color of 'steelblue', with a text color of white, a link color of light green, and a visited link color of orange. It is accessed by the [body 2] element, which when expanded becomes<BODY BGCOLOR="steelblue" TEXT="white" LINK="ltgreen" VLINK="orange">.
The third color scheme is similar to the second, except defines white-black-blue-purple for the four colors. It is accessed with a [body 3] element.
If there is no defined scheme for a body element (as there wouldn't be if you put [body 4] in a page with the above schemes defined) MiniVend simply outputs a standard<BODY> tag.
The user can also define their own colors if the Mv_customcolors variable is set (upon a form submission). See the supplied control.html page for an example of how to set custom colors.
Image maps can be supplied and similarly controlled with the [buttonbar n] series of tags. They are defined with the ButtonBars directive (also set in minivend.cfg or with MAT), and take the form of a series of file names in MiniVend format -- i.e., relative to the PageDir and without a .html extension. To use the buttonbars, create a file with an IMG directive set with the USEMAP element and an associated client-side image map (defined with<MAP></MAP>. The [areatarget] or [area] tags are used to set the URLs. An example:
If the above were saved in the file PageDir/bars/artbar0.html (where PageDir is your MiniVend pages directory), you would be able to access this imagemap in your pages with a [buttonbar 0] tag, at least after MiniVend read this line in the configuration file:
The above entry allows you to define three imagemaps and access them in your pages simply as [buttonbar 0], [buttonbar 1], and [buttonbar 2]. The advantage of this scheme is central definition of a series of button bars with only a few tags -- if you change your page colors or mapping, you need only change one file and the change will roll over to all of your catalog pages. Since some installations can number in the thousands of catalog pages, using the pre-defined buttonbars can save a lot of editing. (Server-side includes cannot be used to achieve the same thing with MiniVend, since they wouldn't have the proper URLs.)
Imagemaps can also be defined on forms, with the special form variable mv_todo.map. A series of map actions can be defined -- the action specified in the default entry will be applied if none of the other coordinates match. The image is specified with a standard HTML 2.0 form field of type IMAGE. Here is an example:
All of the actions will be combined together into one image map with NCSA-style functionality -- see the NCSA imagemap documentation for details -- except that MiniVend form actions are defined instead of URLs. The standard actions are:
The [random] element, in conjunction with the Random directive in the minivend.cfg file (or set with MAT), is similar to the buttonbar tag, except it displays random messages or images. It can be used to place a random tip, hint, ad, or message, and can be any legal HTML construct. It cannot contain MiniVend elements.
The [help tag] element, in conjunction with the Help directive in the minivend.cfg file (or, of course, set with MAT), is similar to the buttonbar tag, except it displays help messages or images, and is keyed by item name. The help can be contained in any of a series of files defined in the Help directive. It can contain most MiniVend elements. The user can turn off help through a form -- see the control.html file for an example.
|
Chapter 7 |
Table ofContents |
|---|