Version

DESCRIPTION

MiniVend plugs into a system with an SSL (Secure Sockets Layer) server, allowing encrypted transmission of sensitive customer data. This capability makes the entry of credit card numbers practical and secure.

Many different catalogs can be run from the same MiniVend server, allowing an ISP to serve many different customers from one or just a few MiniVend server processes.

Multiple servers can be run to serve the same set of catalogs, and searches are forked. This ensures fast response while searching the catalog.

OVERVIEW OF MINIVEND

How MiniVend Manages Sessions

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:

machine.company.com

Internet address of server

cgi-bin

Informs server that the requested page will be generated by a program.

vlink

Name of the program to run

shirts

Page of the catalog to display

WehUkATn;;1

The session id

Catalog pages are written in regular HTML with extensions to support catalog ordering. Pages are delivered through the following steps:

The HTTPD server receives a request for a catalog page.

The server is already running as a daemon, and the request

causes a small C program called vlink. The vlink program communicates with the MiniVend program via a UNIX-domain socket.

MiniVend reads the HTML source page from the catalog pages directory,

and interprets the catalog ordering extensions in the file. If the page doesn't exist, and corresponds to a part number in the database, it is built ``on the fly'' using the template page flypage.html.

The page, which is now entirely in regular HTML, is delivered to

the HTTPD server, which returns it to the browser.

Where to Download MiniVend

If you are on a Solaris, or another UNIX which does not have native and complete flock() support, you must also obtain the File::Lock module at the same place that Perl is available from.

Perl

You can download the latest Perl 5 from any CPAN (Comprehensive Perl Archive Network) site. Here are some of the many:

NORTH AMERICA

EUROPE

AUSTRALASIA

ASIA

AFRICA

Setup for HTTP Servers

MiniVend uses a server running in the background, with a small C program called vlink that communicates with MiniVend via a UNIX-domain socket.

To improve security, MiniVend normally runs with the socket file having 0600 permissions (rw-------), which mandates that the CGI program and the server run as the same user ID. This means that the vlink program must be SUID to the same user ID as the server executes under. (Or that CGIWRAP is used on a single catalog system).

With MiniVend 2.0 multiple catalog capability, the permissions situation gets a bit tricky. MiniVend comes with a program, makecat, which configures catalogs for a multiple catalog system. It should properly set up ownership and permissions if run as the superuser.

QUICK START

If you plan on building multiple catalogs, you will probably want separate directories to hold the catalog pages and databases. The makecat program supplied with MiniVend will make those for you.

Decompress and untar the distribution:

If you have GNU tar, you can combine these steps:

Before installing, check the site where you obtained MiniVend for any patches that might have been issued since the release.

Run the configure script with:

If you have trouble with ./configure, try this:

Replace the 'perl' and '/usr/bin/perl' with the proper paths to your Perl 5 binary.

The process should be self-explanatory. If you discover any problems, refer to the section If something goes wrong . Otherwise, MiniVend should be installed at the completion of the script. It is strongly suggested that you install the demo catalogs as a starting point for your own catalog -- the configuration script will give you the opportunity to do so.

IMPORTANT NOTE: One point that is to be emphasized -- only your base html pages go in the document space of your http server. Any pages with MiniVend elements/tags go in the directory set by the PageDir directive (the default is VendRoot/pages). For the demos supplied with MiniVend, this means that only a few pages will be copied to your HTML directory, with the remainder of the pages staying in the directory defined as PageDir .

Setting up multiple catalogs

minivend.cfg

This file is located in the main MiniVend directory, and has only a few server-wide configuration parameters. The most important is the Catalog directive, which sets up the catalog configuration. The sample minivend.cfg supplied with the distribution defines two catalogs:

Catalog sample /home/catalogs/sample /cgi-bin/simple Catalog simple /home/catalogs/simple /cgi-bin/sample

Additional parameters set up multi-server capability and search parameters.

catalog.cfg

Located in the directory where the individual catalog resides, this file has most of the parameters which define the catalog.

The steps to set up the multiple server capability are:

1. Install the MiniVend software. Use the supplied makecat program to install the demo catalogs, 'sample' and 'simple'.

2. Check the makecat.cfg file in the MiniVend bin directory and make sure it fits your system. It is especially important to have the MiniVendUser and MiniVendGroup directives correct if you will have multiple users configuring and running catalogs.

3. Select a name for your new catalog. The name will be the default name for the HTML directory to be used, the vlink executable, but it can be changed at configuration time. For this example, our name is 'real'.

4. Run the makecat program: bin/makecat real

5. Answer the prompts, which should have much of the right information by default if you have edited the makedemo.cfg file properly. Reply yes when the makecat program asks if you wish to place the catalog in minivend.cfg.

If something goes wrong

http://www.iac.net/~mikeh/mvend.html

Second, double check that you have the following things:

1. The vlink program is SUID, or you have made appropriate changes in the ReadPermission and WritePermission directives. Unless the files are world-writable, the vlink program and the MiniVend server must run as the same user ID!

2. That you have proper file permissions. The program files can be owned by anyone, but any databases, error logs, and the directory that holds them must be writable by the proper user ID.

3. The vlink CGI program is being executed on a machine that has the socket file etc/socket on a directly attached disk. UNIX-domain sockets will not work on NFS-mounted filesystems! That means the server minivend.pl and the CGI program vlink must be executing on the same machine.

If you have a problem you are not able to correct, you can send email to:

Please include your operating system name and version, your Perl version the DBM library in use, the minivend.cfg file, the catalog.cfg file(s), and a directory listing of the MiniVend directory (and its etc directory) after the attempt to run. This can be done by leaving a message at the MiniVend bug reporting station:

MiniVend is an ambitious and complex program, and is not presented as being easy to use, easy to install, or bug-free. The configuration scripts were done to try and make a very painful process only slightly painful. Some people install in one pass. Others never make it, especially when they are running on an ISP. Determined and thoughtful users almost always make MiniVend work.

SETTING UP YOUR CATALOG

In order to set up a custom catalog, there are a number of steps.

You will need to become familiar with the MiniVend tags and directives to make your own catalog. The demo catalogs are a good starting point -- in particular we suggest you pay attention to the order and search pages.

Start with a database

Some other things you might put in:

image

A database field giving the name of an image file to display the product. Alternatively, you can keep images in files that are named for the product code -- then display them if they exist (use the [if file file.gif] TAG [/if] construct).

nontaxable

This field should be present if you have items that do not have sales tax calculated for them.

category

If you wish to do one-click category searches to build product directories, you might use this field to select on.

related

Items related to the item in the record. Using MiniVend's [loop item] tag, you could build product subclasses and accessory sets.

On-the-fly pages, static, or both?

If you have a large catalog, you will almost certainly want to use the on-the-fly page for most products. But if you want to mix in a few extra-special pages, perhaps for your best sellers, you can do so. Just build the pages and place them in files corresponding to the part number (in the MiniVend pages directory, of course -- not your HTML directory). They will take precedence over the on-the-fly page.

If you have only a small number of products, hard coded pages are just fine. Build them just about like normal HTML pages, except for the MiniVend tags to order the item. Place them whereever they can be reached -- if you are using searches, you will want to name the file by the part number, or at least make a link to it.

Some other things you might put in:

Images

You can easily place a thumbnail image (even with a link to a blowup) only for those items that have them.

Accessories

The accessories database allows you to pre-define additional products to offer with a main product.

Reviews/Testimonials

You can key the placement on the existence of a file in a certain directory.

Use the demo catalogs

Tree design

CATALOG PAGES

NOTE: As of MiniVend 1.03, there are no real distinctions between order pages and other pages -- all may access the [item_list] tag.

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.

Unless you are using the ``cookie'' support, 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.

Cookies

NOTE: In the descriptions, parameters marked with an asterisk* are optional.

MiniVend Tags

[page pg]

Insert a hyperlink to the specified catalog page pg. For example, [page shirts] will expand into < a href=``http://machine.company.com/cgi-bin/vlink/shirts?WehUkATn;;1''>. The catalog page displayed will come from ``shirts.html'' in the pages directory.

[pagetarget pg frame]

Same as the page element above, except it specifies an output frame to target if frames are turned on. The name is case-sensitive, and if it doesn't exist a new window will be popped up. This is the same as the [page ...] tag if frames are not activated. For example, [pagetarget shirts main] will expand into a link like <a href=``http://machine.company.com/cgi-bin/vlink/shirts?WehUkATn;;1'' TARGET=``main''>. The catalog page displayed will come from ``shirts.html'' in the pages directory, and be output to the 'main' frame. Be careful, frame names are case-sensitive.

This option 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 .

[areatarget pg frame]

Inserts a Vend URL in a format to provide a targeted reference for a client-side imagemap. You set up the <AREA> tag with:

<AREA COORDS="220,0,270,20" HREF="[areatarget page frame]">

If frames are enabled, this will expand to:

<AREA COORDS="220,0,270,20" HREF="http://machine.company.com/vlink/page?ErTxVV8l;;38" TARGET="frame">

If frames are not enabled, this will expand to:

<AREA COORDS="220,0,270,20" HREF="http://machine.company.com/vlink/page?ErTxVV8l;;38">

[area pg]

Like the areatarget element, except it will never yield a frame target.

[/page], [/pagetarget]

Expands into </a>. Used with the page or pagetarget elements, such as: [page shirts]Our shirt collection[/page] or [pagetarget pants main] Our pants collection[/pagetarget]. They are syntactically the same, so you can use either one to terminate an anchor -- the two different ones are provided for consistency.

[frames_on]

Turns on the frames processing option, which is disabled by default. The proper way to use this is to put it ONLY in a page which is loaded by frame-based browsers, as part of the initial frame load. It is persistent for the entire session, or until counteracted with a [frames_off] tag.

[frames_off]

Turns off the frames processing option. This can be used to disable frames, perhaps as a clickable option for users. It is persistent for the entire session, or until counteracted with a [frames_on] tag.

[finish_order page*]

This element is used to give the customer, while browsing, a way to go to the order page (or optional checkout page) after they have ordered something. If they haven't ordered anything yet [finish_order] does not appear at all on the displayed page. If they have ordered an item, the element will expand into something like:

<a href="http://machine.company.com/cgi-bin/vlink/order;WehUkATn;;1"> Finish Incomplete Order</a>

If the optional page is supplied, that will be the order page used to finish the order.

[order code page*]

Expands into a hypertext link which will include the specified code in the list of products to order and display the order page. code should be a product code listed in the ``products'' database.

[/order]

Expands into </a>. Used with the order element, such as: Buy a [order TK112]Toaster[/order] today.

[price code]

Expands into the price of the product identified by code as found in the products database.

[description code]

Expands into the description of code as found in the products database.

[accessories code]

Expands into the value of the accessories database entry for the product identified by code as found in the products database.

[field name code]

Expands into the value of the field name for the product identified by code as found in the products database. IMPORTANT: If the field name is not a field in the database, the MiniVend server will stop with an error.

[static /html/path] static-area [/static]

Defines an area (usually an item, loop, or search list) that will be built with HREFs to regular pages instead of to the MiniVend server. Search, scan, and order URLs will still be made to go to the CGI. Use in conjunction with Cookies and StaticPath to allow access to static page trees from MiniVend. This can increase system capacity on heavily-trafficked systems.

[body n]

Selects from the predefined color schemes and/or backgrounds, and just becomes a <BODY> tag if none are defined. See Controlling Page Appearance.

[buttonbar n]

Selects from the predefined buttonbars, and is stripped if it doesn't exist. See Controlling Page Appearance.

[random]

Selects from the predefined random messages, and is stripped if none exist. See Controlling Page Appearance.

[item_list]

Places an iterative list of the items in the shopping cart. See The Order Page for a description.

[/item_list]

Terminates the [item_list] tag.

[shipping_description]

The text description of the shipping mode currently selected.

[row nn]

Formats text in tables. Intended for use in reports or <PRE></PRE> HTML areas. The parameter nn gives the number of columns to use. Inside the row tag, [col param=value ...] tags may be used.

[/row]

Terminates a [row nn] element.

[col width=nn wrap=yes|no gutter=n align=left|right|input spacing=n]

Sets up a column for use in a [row]. This parameter can only be contained inside a [row nn] [/row] tag pair. Any number of columns (that fit within the size of the row) can be defined.

The parameters are:

width=nn The column width, I<including the gutter>. Must be supplied, there is no default. A shorthand method is to just supply the number as the I<first> parameter, as in [col 20]. gutter=n The number of spaces used to separate the column (on the right-hand side) from the next. Default is 2. spacing=n The line spacing used for wrapped text. Default is 1, or single-spaced. wrap=(yes|no) Determines whether text that is greater in length than the column width will be wrapped to the next line. Default is I<yes>. align=(L|R|I) Determines whether text is aligned to the left (the default), the right, or in a way that might display an HTML text input field correctly.

[/col]

Terminates the column field.

MiniVend Conditional HTML

This facility cannot be considered a language, for constructs cannot be nested in a linear fashion, and operations cannot be performed (except as side effects to the [if] tag).

Starting with MiniVend 2.0, Perl code can be embedded directly in the pages for additional control. This overcomes some of the limitations of MiniVend conditional HTML.

NOTE: MiniVend interpolates tags in a highly ordered fashion, with each tag having a precedence. The order of the tag interpolation can be changed by enclosing the tag in a set of double square brackets, bringing it forward in the process. The order of interpolation is:

Most of the tests use Perl code, but MiniVend uses the Safe module with its default restrictions to help ensure that improper code will not crash the server or modify the wrong data. There is nothing to be done if your code enters an endless loop, though, and you have to use this capability with caution.

[if type field op* compare*]

Allows conditional building of HTML based on the setting of various MiniVend session and database values. Accessible areas are:

session

The MiniVend session variables. Of particular interest are login, frames , secure, and browser .

config

The MiniVend configuration variables. These are set by the directives in your MiniVend configuration file (or the defaults).

value

The MiniVend user variables, typically set in search, control, or order forms. Variables beginning with 'mv_' are MiniVend special values, and should be tested/used with caution.

scratch

The MiniVend scratchpad variables, which can be set with the [set name]value[/set] element.

validcc

A special case, takes the form [if validcc no type exp_date]. Evaluates to true if the supplied credit card number, type of card, and expiration date pass a validity test. Does checksum digit calculation to weed out typos or phony card numbers.

accessory

The accessories database.

shipping

The shipping database.

salestax

The salestax database.

The field term is the specifier for that area. For example, [if session.frames] would return true if the 'frames' session parameter was set.

As an example, consider buttonbars for frame-based setups. It would be nice to display a different buttonbar (with no frame targets) for sessions that are not using frames:

[if session frames] [buttonbar 1] [else] [buttonbar 2] [/else] [/if]

Another example might be the when search matches are displayed. If you use the string '[value mv_match_count] titles found', it will display a plural for only one match. Use:

[if value mv_match_count != 1] [value mv_match_count] matches found. [else] [/else] Only one match was found. [/if]

The op term is the compare operation to be used. Compare operations are as in Perl:

== numeric equivalence eq string equivalence > numeric greater-than gt string greater-than < numeric less-than lt string less-than != numeric non-equivalence ne string equivalence

Any simple perl test can be used, including some limited regex matching (no whitespace or conditionals can be contained in the comparison string). Discussion of this is beyond the scope of this document.

[else] text [/else]

The optional else-text for an if or if_field conditional.

[/if]

Terminates an if conditional.

[set variable]value[/set]

Sets a scratchpad variable to value . One way this is used is to save pages that a customer has seen -- perhaps for a rotating message. A rotating message implementation is shown in the sample page flypage.html .

The mv_* variables that are used for search and order conditionals are in another namespace -- they can be set by means of hidden fields in a form.

[data area field key]

Returns the value of the field in any of the arbitrary databases, or from the variable namespaces. Databases will hide variables, so don't name a database ``session'', ``scratch'', or any of the other reserved names! Case is sensitive, so in a pinch you could call the database ``Session'', but it would be better not to.

[loop item,item,item] value [/loop]

Returns a string consisting of the value, repeated for every item in a comma-separated list. Operates in the same fashion as the [item-list] tag, except for order-item-specific values. Intended to pull multiple attributes from an item modifier -- but can be useful for other things, like building a pre-ordained product list on a page.

Limited to 1024 values in the list.

[perl args] code [/perl]

See the section on Embedded Perl Code .

Embedded Perl Code

The arguments that can be passed are any to all of:

values

Gives read-write access to the user variables, including the MiniVend special variables, an anonymous hash. Referred to in your code as %values.

items

Gives read-only access to the items on order. This is an array of hashes, and includes the product code, quantity, and any modifiers you have specified. Referred to in your code as a reference to the array, $items.

scratch

Gives read-write access to the scratch variables, an anonymous hash. Referred to in your code as %scratch.

config

Gives read-write access to the configuration of the catalog. USE WITH EXTREME CAUTION -- many of the variables are references to anonymous arrays and hashes. You can crash your catalog if you modify the wrong thing. Referred to in your code as $config, a reference to the hash containing the configuration structure.

discount

Gives read-write access to session discounts, an anonymous hash. Referred to in your code as %discounts.

browser

The browser string from the users browser, read-only. Referred to in your code as $browser.

frames

The true/false value determining whether frames processing is enabled. Read-only -- you can set the value with [frames-off] or [frames-on]. Referred to in your code as $frames.

file

If specified, the anchor text should be a file name to read the Perl code from. This allows code to be maintained in separate files. The file name is relative to the MiniVend base directory unless specified as an absolute path.

The result of the tag will be the result of the last expression evaluated, just as in a subroutine. If there is a syntax error or other problem with the code, there will be no output.

Here is a simple one which does the equivalent of the classic hello.pl program:

Of course you wouldn't need to set the variable -- it is just there to show the capability.

To echo the user's browser, but within some HTML tags:

To show the user their name, and the current time:

On-the-fly Catalog Pages

If the directive PageSelectField is set to a valid product database field, and contains a valid MiniVend page name (relative to the catalog pages directory, without the .html suffix) it will be used to build the on-the-fly page.

Required Pages

As of MiniVend 1.03, the names of these pages can be set with the SpecialPage directive. The standard pages and their default locations:

badsearch (pages/badsearch.html)

The error page displayed if there is a system or user error with the search engine.

canceled.html (pages/badsearch.html)

The page displayed by MiniVend when an order has been canceled by the user.

catalog (pages/catalog.html)

The main catalog page presented by MiniVend when another page is not specified.

checkout (pages/order.html)

The page the customer is sent to when checking out (the location pointed to by a [finish_order] tag.

confirmation.html (pages/badsearch.html)

After the order is completed, the confirmation page is displayed.

failed (pages/failed.html)

If the sendmail program could not be invoked to email the completed order, the failed.html page is displayed. (Sadly we don't know if the email was successfully delivered).

flypage (pages/flypage.html)

If the catalog page for an item was not found when its [item_link] is clicked, this page is used as a template to build an on-the-fly page. See On-the-fly Catalog Pages .

interact (pages/interact.html)

Displayed if an unexpected response was received from the browser, such as not getting expected fields from submitting a form. This would probably happen from typos in the html pages, but could be a browser bug.

missing (pages/missing.html)

This page is displayed if the URL from the browser specifies a page that does not have a matching .html file in the pages directory. This can happen if the customer saved a bookmark to a page that was later removed from the database.

needfield (pages/needfield.html)

Displayed if the user did not fill in a required field in the order form. See REQUIRED FIELDS.

nomatch (pages/nomatch.html)

This page is displayed if the search engine is used, but there is no match for the search specification.

noproduct (pages/noproduct.html)

This page is displayed if the URL from the browser specifies the ordering of a product code which is not in the products file.

order (pages/order.html)

This page is displayed when the customer orders an item. It can contain any or all of the customer-entered values, but is commonly used as a status display (or ``shopping basket''). If frames are in use, the special order page can be configured with the directive FrameOrderPage .

search (pages/search.html)

Contains the default output page for the search engine results. Also required is an input page, which can be the same as search.html or an additional page. Five sample input pages are supplied with the demo - the query.html, results.html, helpquery.html, mvfaq.html, and category.html files in the sample/pages directory,

violation (pages/violation.html)

Displayed if a security violation is noted, such as an attempt to submit a credit card number on a non-secured form when in ExtraSecure mode.

DATABASES

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 when they change, from the the ASCII source file. 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.

MiniVend always uses DBM to manage sessions. To effectively use MiniVend, your system must have GDBM or DB_File support -- NDBM or others will not normally work, as the 1024- or 4096-byte limitations on key-value size will cause problems if your catalog is at all complex.

MiniVend reads the data to place in the DBM files from standard ASCII-delimited files. They can have ^M (carriage return) characters if desired, but must have a newline character to work -- Mac users uploading files must use ASCII mode, not binary mode!

Three delimiter schemes are provided as standard:

IMPORTANT NOTE: The items must be separated by a single delimiter character. The items are lined up for your reading convenience.

TAB

Fields separated by ^I characters. No whitespace should be at the beginning of the line.

code description price image SH543 Men's fine cotton shirt 14.95 shirts.jpg

PIPE

Fields separated by | characters. No whitespace should be at the beginning of the line.

code|description|price|image SH543|Men's fine cotton shirt|14.95|shirts.jpg

CSV

Fields enclosed in quotes, separated by commas. No whitespace should be at the beginning of the line.

"code", "description", "price", "image" "SH543", "Men's fine cotton shirt", "14.95", "shirts.jpg"

IMPORTANT NOTE: Field names are always case-sensitive.

MiniVend uses one mandatory database, the products file. It is kept in the file products.asc in the products directory.

It also has a number of standard but optional databases, some of which are in fixed special formats:

shipping.asc

The database of shipping options if the CustomShipping directive is in use. See Custom Shipping .

salestax.asc

The database of sales tax information if the [salestax] tag is to be used. A default is supplied -- caution, these things change! See Sales Tax.

accessories.asc

A simple auxiliary database keyed on the product code. It's value is available via the [item_accessories] or [accessories code] tags. See Accessories .

pricing.asc

The database of quantity pricing information. See Quantity Pricing.

The Products File

Field names are case-sensitive. Unless you have fields with the names ``description'' and ``price'' field, you will have to appropriately set the PriceField and DescriptionField directives to use the [item-price] and [item-description] tags.

The product code must be the first field in the line.

Arbitrary Databases

The databases are specified in Database directives, as:

That specifies a type 4 database, the ASCII version of which is located in the file /usr/data/arbitrary.asc (the DBM file will go there too, as /usr/data/arbitrary.db or arbitrary.gdbm), and the name it will be accessed under in MiniVend is ``Arbitrary''. The name is case sensitive. Fields are accessed with the [item_data name field] or [data name field key] elements.

SPECIAL FIELDS

These special fields all begin with mv_, and include:

THE SEARCH ENGINE

Two search engine interfaces are provided, and four types of searching are available. The default is a text-based search of the products.asc file. A binary search of a dictionary-ordered file can be specified. An optional Glimpse search is enabled by placing the command specification for Glimpse in the directive Glimpse . The last is a range-based search, best used in combination with one of the above -- especially on large files.

The default, a text based search, simply sequentially scans the lines in the target file. It returns the first field (delineated by the standard Delimiter ), for every line matching the search specification.

The Search Form

When the ``Search'' submit button is pressed (or <ENTER> is pressed) MiniVend will search the products.asc file for the string entered into the text field mv_searchspec , and return the product code pertaining to that line.

The same search for a fixed string, say ``shirt'', could be performed with the use of a hot link, using the special scan URL:

The default is to search every field on the line. If you only wished to match on the string shirt in the product database field ``description'', you could modify the search:

If you want to let the user decide on the search parameters, you can use checkboxes or radiobox fields to set the fields:

Fields can be stacked -- if more than one is checked, all checked fields will be searched. (This doesn't work for Glimpse in the return_file_name mode, though).

Glimpse

There are several ways to improve search speed for large catalogs.

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 a common string, as you might have in a category search, 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.

There are several things you have to watch for while using glimpse, and a liberal dose of the Glimpse documentation is suggested. In particular, the spelling error capability will not work in combination with the field-specific search -- Glimpse selects the line, but MiniVend's text-based search routines disqualify it when checking to see if the search string is within one of the specified fields.

Fast Binary Search

The search must be done on a dictionary-ordered pre-built index.

See the documentation for Vend::Search for more information. (From the MiniVend root directory, you can see it by using ``perldoc Vend::Search''.)

Range Searching

The value of 0 for mv_range_max is equivalent to infinity if doing a numeric search. (This makes it impossible to search for a ceiling of 0 with a negative mv_range_min, just in case you were planning on trying that.)

The fields are stackable, so you can set more than one range to check. The order is significant, in the sense that the array of field names and minimum/maximum values must be kept in order to achieve correspondence.

The optional mv_range_alpha specification allows alphanumeric range matching for the corresponding field -- if it is set, and you have stacked the fields, they must all be set. The mv_case field does apply if it is set -- otherwise the comparison is without regard to case.

If you wish to do ONLY a range search, you must select all lines with mv_return_all=yes in order to make the search operate. Range-only searches will be quite slow for large databases, since every line must be scanned. It should be quite usable for catalogs of less than 100,000 items in size, given a fast machine. Using it in combination with another search technique will yield quite quick results.

One-click searches

Here is the same thing from a home page (assuming /cgi-bin/vlink is the CGI path for MiniVend's vlink):

The two-letter abbreviations are mapped with these letters:

They can be treated just the same as form variables on the page, except that they can't contain spaces, '/' in a file name, or quote marks. These characters can be used, but only in URL decimal encoding, i.e. &#32; is a space, &#47 is a /, etc. -- &sp; will not be recognized.

So if you wish to do an OR search on the fields category and artist for the strings ``Surreal'' and ``Gogh'', while matching substrings, you would do:

Search Profiles

and place them in a file. Define the file name in the SearchProfile directive. Re-start the server. The profiles are numbered in the order found (not by file name), starting at 0, and are available by setting the variable mv_profile to the number of the profile.

The special variable mv_last stops interpretation of search variables. The following variables are always interpreted:

Other than that, if you set mv_last in a search profile, and there are other variables on the search form, they will not be interpreted.

The search profiles are also available, and especially useful, for one-click searches. They are available by setting scan/mp=n/se=text, where n is the number of the profile.

If you want to place multiple search profiles in the same file, separate them with __END__, which must be on a line by itself. Be careful, then they are interpreted in the order found, with the second file name not necessarily being the second profile (which would be numbered 1).

Search Reference

mv_base_directory

In the text search, set to the directory to base file searches from. File names without leading / characters will be based from there. In the Glimpse search, passed to Glimpse with the -H option, and Glimpse will look for its indices there. Default is ProductDir.

mv_case

If this item is set to yes, the search will return items without regard to upper or lower case. This is the default -- set to yes if case should be matched. Implement with a checkbox <INPUT TYPE=CHECKBOX> field.

mv_coordinate

If this item is set to yes, and the number of search fields equals the number of search specs, the search will return only items that match field to spec.

mv_dict_fold

Make dictionary matching case-insensitive. Ignored without mv_dict_look. NOTE: This is the reverse sense from mv_case.

mv_dict_end

Set to the string to end matching at in a dictionary-based search. If the string at the beginning of a line lexically exceeds this value, matching will stop. Ignored without mv_dict_look.

mv_dict_limit

Automatically set the limiting string (mv_dict_end) to be one character greater than the mv_dict_look variable, at the character position specified. A value of 1, for instance, will set the limiting string to ``fprsythe'' if the value of mv_dict_look is ``forsythe''. A useful value is -1, which will increment the last character (setting the mv_dict_end to ``forsythf'' in our example). This prevents having to scan the whole file once a unique match is found.

The order of this and the mv_dict_end variable is significant -- each will overwrite the other.

mv_dict_look

Set to the string to begin matching at in a dictionary-based search. If not set, the mv_dict_end, mv_dict_fold, and mv_dict_case variables will be ignored.

mv_dict_order

Make dictionary matching follow dictionary order, where only word characters and whitespace matter. Ignored without mv_dict_look.

mv_doit

This must be set to 'search' to make this a search page.

mv_exact_match

Normally MiniVend searches match words, as opposed to sentences. This behavior can be overridden with mv_exact_match, which when set will place quotes around any value in mv_searchspec or mv_dict_look.

mv_matchlimit

The page size for matches that are returned. If more matches than mv_matchlimit are found, the search paging mechanism will be employed if the proper [more_list] is present. Can be implemented as a scrolling list (INPUT TYPE=SELECT) or radiobox (INPUT TYPE=RADIO) field.

mv_max_matches

The maximum number of records that will be returned in a search. Default is 2000.

mv_orsearch

If this item is set to yes, the search will return items matching any of the words in searchspec. The default is no.

mv_profile

Selects one of the pre-defined search specifications set by the SearchProfile directive. If the special variable within that file, mv_last, is defined, it will prevent the scanning of the form input for further search modifications. The values of mv_searchspec and mv_dict_look are always scanned, so you can specify this to do the equivalent of setting multiple checkboxes or radioboxes with one click, while still reading the search input text.

mv_range_alpha

Sets the type of match, numeric or alphanumeric, for the range search in its corresponding range field. The search will return true (assuming it is greater than the mv_range_min specification) if the field searched is less than or equal to mv_range_max, in an alphanumeric sense.

mv_range_look

This sets a field to scan for a range of numbers. It must be accompanied with corresponding mv_range_min and mv_range_max variables. It can be a products file field name, if the search is in the products file, or it can be a column number of an arbitrary file or database.

mv_range_max

Sets the high bound for the range search in its corresponding range field. The search will return true (assuming it is greater than the mv_range_min specification) if the field searched is less than or equal to mv_range_max. To set the bound at infinity, or whatever your integer limit is, set mv_range_min to 0.

mv_range_min

Sets the low bound for the range search in its corresponding range field. The search will return true (assuming it is less than the mv_range_max specification) if the field searched is less than or equal to mv_range_min.

mv_return_fields

The fields that should be returned by the match. You should not normally set this, as the default of field 0 only works well with MiniVend's key-based database method of displaying search pages.

mv_search_field

The search field(s) to be searched, specified in one of two ways. If the field is in the products database, it can be specified by field name. If in an arbitrary database, it must be specified by row number (code cannot be specified).

If the number of instances matches the number of fields specified in the mv_searchspec variable, and mv_coordinate is set to true, each search field (in order specified on the form) will be matched with each search spec (again in that order).

mv_search_file

In the text search, set this variable to the file(s) to be scanned for a match. The default, if not set, is to scan the products.asc file. If set multiple times in a form (for a text search), will cause a search all the files. One file name per instance.

In the Glimpse search, follows the Glimpse wildcard-based file name matching scheme. Use with caution and a liberal dose of the Glimpse man page.

mv_search_match_count

Set by the search to indicate the total number of matches found.

mv_search_over_msg

The message that should be displayed if there is an overflow condition (max_matches is exceeded). Overrides the SearchOverMsg directive -- it is cleared by MiniVend if there is no overflow. Somewhat deprecated by match paging.

mv_search_page

The MiniVend-style name of the page that should display the search results. Overrides the FrameSearchPage directive, and the default value of 'search'.

mv_searchspec

The actual search string that is typed in by the customer. It is a text INPUT TYPE=TEXT field, or can be put in a select (drop-down) list to enable category searches. If multiple instances are found, they will be concatenated just as if multiple words had been placed in a text field.

The user can place quotes around words to specify that they match as a string. To enable this by default, use the mv_exact_match variable.

If mv_dict_look has a value, and mv_searchspec does not, then mv_searchspec will be set to the value of mv_dict_look.

If the number of instances matches the number of fields specified in the mv_search_field variable, and mv_coordinate is set to true, each search field (in order specified on the form) will be matched with each search spec (again in that order).

mv_searchtype

If set to glimpse, selects the Glimpse search (if Glimpse is defined). If set to text, selects the text-based search. Defaults to text if Glimpse is not defined, to Glimpse if it is. This can allow use of both search types if that is desirable -- for instance, searching for very common strings is better done by the text-based search. An example might be searching for categories of items instead of individual items.

mv_spelling_errors

The number of spelling errors that will be tolerated. Ignored unless using Glimpse. If you have a large catalog, you might wish to limit this to two.

mv_substring_match

If mv_substring_match is set to yes, matches on substrings as well as whole words. You would typically want to set this for dictionary-based searches.

The Results Page

On the search page, some special MiniVend tags are used to format the otherwise standard HTML. Each of the iterative tags is applied to every code returned from the search -- this is normally the product code, but could be a key to any of the arbitrary databases. The value placed by the [item-code] tag is set to whatever the first field (separated by whitespace) is, at least when the default of yes is in the UseCode directive.

NOTE: The special item tags (item_price, item_data, item_accessory, etc.) still refer to fields in the product database. To access arbitrary databases, you will need to use the idiom [data database field [item_code]].

[search_list]

Starts the representation of a search list. MiniVend tags can be embedded in the search list, yielding a table or formatted list of items with part number, description, price, and hyperlinks to order or go to its catalog page.

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.

In fact, any of the MiniVend database access tags can be used, allowing you to pull data from any of the fields in any of your predefined databases. Along with the MiniVend conditional tags, very complex pages can be built for each individual item returned in the search.

[/search_list]

Ends the search list.

[matches]

Replaced with the range of match numbers displayed by the search page. Looks something like ``1-50''. Make sure you insert this item between a [more_list] and [/more_list] element pair.

[more_list]

Starts the section of the search page which is only displayed if there are more matches than specified in mv_matchlimit . If there are less matches than the number in mv_matchlimit, all text/html between the [more_list] and [/more_list] elements is stripped.

Use in conjunction with the [more] element to place pointers to additional pages of matches.

[/more_list]

Companion to [more_list].

[more]

Inserts a series of hyperlinks that will call up the next matches in a series. They look like this:

Previous 1 2 3 4 5 6 Next

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.

[item_link code]

Expands into a hyperlink which will jump the user to a page under the ItemLinkDir (default is the pages directory), with anchor text as set in ItemLinkValue (default is ``More Details''). If the page is not present, then flypage.html will be used to build a page from the entry in the database. If that doesn't work (perhaps due to a missing flypage.html) then the error page notfound.html will be displayed. Only active in the search list.

[process_search]

Calls the search with the proper URL, including MiniVend session tags. Used as the ACTION value for the search form.

[process_target frame]

Calls the search with the proper URL, including MiniVend session tags. Used as the ACTION value for the search form if the results are to be targeted to a different window than the one set by SearchFrame (which is ``_self'' by default).

THE ORDER PROCESS

The name of the page to display can be configured in several ways:

1. Set the SpecialPage 'order' to the page to display when an item is ordered.

2. Set the FrameOrderPage directive to the page to use when frames are enabled. This overrides option 1.

3. Use the [order item page] Order it! [/order] form of order tag to specify an arbitrary order page for an item.

4. If already on an order page, set the mv_checkout, mv_orderpage, mv_nextpage, mv_successpage, or mv_errorpage variables.

   The variables mentioned above modify the page display in the following ways:

5. Page to be displayed on a refresh

6. Page to be displayed when checkout is called from the form

7. Page to display on a return operation

8. Page to be displayed on a successful order check (see Advanced Multi-level Order Pages )

9. Page to be displayed on a failed order check (see Advanced Multi-level Order Pages )

The structure of the Accessories database is a simple key-value pair -- if you have more complex accessory setups you can define one of the Arbitrary Databases and use that.

The following elements are used on the order page:

[value field]

Expands into the current value of the customer input field named by field. See the section on input fields for more information.

[nitems]

Expands into the total number of items ordered so far.

[subtotal]

Expands into the subtotal cost, exclusive of sales tax, of all the items ordered so far.

[salestax]

Expands into the sales tax on the subtotal of all the items ordered so far. If there is no key field to derive the proper percentage, such as state or zip code, it is set to whatever the default is. See Sales Tax for more information.

[total_cost]

Expands into the total cost of all the items ordered so far, including sales tax (if any).

[if_field fieldname]

If the database field fieldname is non-blank, the following text up to the [/if_field] tag is substituted. This can be used to substitute IMG or other tags only if the corresponding source item is present. Also accepts a [else]else text[/else] pair for the opposite condition.

[/if_field]

Terminates an [if_field fieldname] element.

.

[item_accessories]

Evaluates to the value of the Accessories database entry for the item.

[item_code]

Evaluates to the product code for the current item.

[item_data database fieldname]

Evaluates to the field name fieldname in the arbitrary database table database, for the current item.

[item_description]

Evaluates to the product description (from the products file) for the current item.

[item_field fieldname]

Evaluates to the field name fieldname in the database, for the current item.

[item_increment]

Evaluates to the number of the item in the match list. Used for numbering search matches or order items in the list.

[item_modifier]

Evaluates to the modifier value for the current item.

[item_price]

Evaluates to the price (from the products file) of the current item.

[item_quantity]

Evaluates to the quantity ordered for the current item.

[item_subtotal]

Evaluates to the subtotal (quantity * price) for the current item. Quantity price breaks are taken into account.

[modifier_name]

Evaluates to the name to give an input box in which the customer can specify the modifier to the ordered item.

[quantity_name]

Evaluates to the name to give an input box in which the customer can enter the quantity to order.

[loop_accessories]

Evaluates to the value of the Accessories database entry for the item.

[loop_code]

Evaluates to the product code for the current item.

[loop_data database fieldname]

Evaluates to the field name fieldname in the arbitrary database table database, for the current item.

[loop_description]

Evaluates to the product description (from the products file) for the current item.

[loop_field fieldname]

Evaluates to the field name fieldname in the database, for the current item.

[loop_increment]

Evaluates to the number of the item in the list. Used for numbering items in the list.

[loop_price]

Evaluates to the price (from the products file) of the current item.

Advanced Multi-level Order Pages

Specifications take the form of an order page variable (like name or address), followed by an equals sign and one of five check types:

required

A non-blank value is required

mandatory

Must be non-blank, and must have been specified on this form, not a saved value from a previous form

phone

The field must look like a phone number, by a very loose specification allowing numbers from all countries

phone_us

Must have US phone number formatting, with area code

email

Rudimentary email address check, must have an '@' sign, a name, and a minimal domain

&fatal

Set to '&fatal=yes' if an error should generate the error page

&final

Set to '&final=yes' if a successful check should cause the order to be placed

&set

Set a minivend variable to a value, i.e. &set=mv_email [value email]. This is usually placed at the end after a &fatal pragma would have caused the process to stop if there was an error

The following file specifies a simple check of formatted parameters:

The profile above only performs the &set directives if all of the previous checks have passed -- the &fatal=yes will stop processing after the check of the email address if any of the previous checks failed.

If you want to place multiple order profiles in the same file, separate them with __END__, which must be on a line by itself. Be careful, then they are interpreted in the order found, with the second file name not necessarily being the second profile. (Which would be numbered 1, of course, just for clarity. At least it is clear to a programmer.)

Simple Order Report File

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.

Fully-configurable Order Reports

You could if you wish include HTML in the file, which will be interpreted by many mailers, but you can choose to use standard ASCII format. An example report is provided in the demo file <pages/ord/report.html>.

Order Receipts

The Order Counter

This capability is made possible by the File::CounterFile module, available (as a part of the fine libwww modules) at the same place you got MiniVend. It is included with the distribution.

Customer Input Fields

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.

ITEM ATTRIBUTES

The configuration file directive UseModifier is used to set the name of the modifier or modifiers. For example

will attach both a size and color attribute to each item code that is ordered.

The modifier value is accessed in the [item-list] loop with the [item-modifier attribute] tag, and form input fields are placed with the [modifier-name attribute] tag. This is similar to the way that quantity is handled, except that attributes can be ``stacked'' by setting multiple values in an input form.

Use the [loop item,item,item] list to reference multiple display or selection fields for modifiers. The modifier value can then be used to select data from an arbitrary database for attribute selection and display.

You cannot define a modifier name of quantity, as that is already used. You must be sure that no fields in your forms are the same name as the attribute name you select,

Product Discounts

The discounts are specified via a formula. The formula is scanned for the variables $q and $s, which are substituted for with the item quantity and subtotal respectively. In the case of the item and all items discount, the formula must evaluate to a new subtotal for all items of that code that are ordered. The discount for the entire order is applied to the entire order, and would normally be a monetary amount to subtract or a flat percentage discount.

Discounts are applied to the effective price of the product, including any quantity discounts.

To apply a straight 20% discount to all items:

To take 25% off of only item 00-342:

To subtract $5.00 from the customer's order:

Perl code can be used to apply the discounts. Here is an example of a discount for item code 00-343 which prices the second one ordered at 1 cent:

SALES TAX

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. The subtotal will include any taxable items, and will also include the shipping cost if the state/zip is included in the TaxShipping directive. 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 should be easily converted to MiniVend format -- but some systems are rather convoluted, and it will be well to check and see if the program can export to a flat ASCII file format based on zip code.

If some items are not taxable, then you must set up a field in your database which indicates that. You then place the name of that field in the NonTaxableField directive. If the field for that item evaluates true on a yes-no basis (i.e. is set to 'yes', 'y', 1, or the like), sales tax will not be applied to the item. If it evaluates false, it will be taxed.

If your state taxes shipping, use the TaxShipping directive. Utah and Nevada are known to tax shipping -- there may be others.

SHIPPING

Custom Shipping

IMPORTANT NOTE: Before MiniVend 2.0, there could only be one field used to set the criteria. As of MiniVend 2.0, the entry in the shipping file which is exactly the same as the value of the mv_shipmode variable will be used to determine the field criteria for the shipping method. This allows weight to be used for one mode, while price or quantity is used for another.

The shipping cost database (located in ProductDir/shipping.asc) 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.

code

The unique identifier for that shipping method

description

Text to describe the method, accessed with the [shipping_description] element

criteria

Whether it is for weight, quantity, price, etc. This only makes a difference in the field that matches the shipping mode exactly!

minimum

The low bound of quantity/weight this entry applies to

maximum

The high bound of quantity/weight this entry applies to

cost

The total cost (formula if begins with 'f', or multiplier, if begins with 'x')

1. The base code is selected. If there is more than one entry per code, numbers should be appended.

2. The criterion field is found -- if it is quantity, then it is the total quantity of items on the order form.

3. The value of the criteria is determined, and if it falls with in the minimum and maximum, the cost is then applied. This will be called the accumulated criterion.

4. If the cost is fixed, it is simply added.

5. If the cost field begins with an 'x', the cost is multiplied by the accumulated criterion -- price, weight, etc.

6. If the cost field begins with 'f', the formula following is applied. Use $x as the value of the accumulated criterion.

7. If the cost field begins with 'u', a UPS lookup is done.

8. If no match is found, the 'default' entry is used.

NOTE: The columns are lined up for your reading convenience, the actual entries should have ONE tab between fields.

If the user selected RPS, (code RPSG), and the quantity on the order was 3, the cost of 7.00 from rpsg1 would be applied. If the quantity were 7, the next entry from rpsg2 would be selected, for a cost of 10.00. If the quantity were 15, rpsg3 would be selected, and the quantity of 15 multiplied by 0.95, for a total cost of 14.25.

The second one is a more complicated formula -- using price as the criteria.

The third is a special case. It specifies a UPS lookup based on three things:

The routines use standard UPS lookup tables. First, the UPS Zone file must be present. That is a standard UPS document, specific to your area, that you must obtain from UPS and enter into and make available to MiniVend in TAB-delimited format. You specify it with the UpsZoneFile directive. Second, you must obtain the cost tables from UPS (you can get them from www.ups.com) and place them into a MiniVend database. That database, selected with the first argument (upsg in the example) of the cost specification, is consulted to determine the UPS cost for that weight and zip code. See the sample demo, which has a functional implementation, for more information.

Note that the first entry in each class does not have a number appended to it. That is the entry used to determine the criteria (quantity, weight, price, etc. It is also used to apply the cost if the value of the criteria is less than 1.

Default Shipping Mode

This will make the entry on the order form checked by default when the user starts the order process, if it is put in the form:

TRACKING AND BACKEND ORDER ENTRY

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 products directory. 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.

Easy ASCII Tracking

If you set AsciiTrack to a legal file name (based in VendRoot unless it has a leading ``/''), a copy of the order will be saved there as well as being emailed.

If you set AsciiBackend to a legal file name (based in VendRoot unless it has a leading ``/''), it will save the backend fields along with the item-code and quantity of items being ordered.

For either directive, if the file name string begins with a pipe ``|'', a program will be run and the output ``piped'' to that program. This allows easy backend entry of orders with an external program.

SSL SECURITY

IMPORTANT NOTE: MiniVend attempts to perform operations securely, but no guarantees or warranties 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 . 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.

MINIVEND CONFIGURATION FILE

Server Configuration File

If no Catalog directives are present, all of the directives listed under Catalog Configuration File are operative for the single catalog that will be served by MiniVend.

Otherwise, there are only a few directives that are defined in the minivend.cfg file.

Catalog

Specifies a catalog that can run using this MiniVend server. There are three parameters, separated by spaces and/or tabs.

The first is the name of the catalog -- it will be referred to as that name in error, warning, and informational messages.

The second is the base directory of the catalog. If the directory does not contain a catalog.cfg file, the server will report an error and refuse to start.

The third directive is very important to get right -- it is the SCRIPT_NAME of the vlink program that runs the catalog. It must be unique from other CGI program paths that run on this server -- that is how the catalog is selected for operation.

Catalog sample /home/minivend/sample /cgi-bin/sample

DisplayErrors

While all errors are reported in the error log file, you can also have errors displayed by the browser. This is convenient while you are testing your configuration. Default is No.

DisplayErrors Yes

ForkSearches

Determines whether search operations will be forked (best for single server) or not (sometimes good for MultiServer mode). The default is Yes.

ForkSearches No

HammerLock

The number of seconds after which a locked session could be considered to be lost due to malfunction. This will kill the lock on the session. Only here for monitoring of session hand-off, if this error shows up in the error log the system setup should be examined. Default is 30.

HammerLock 60

MailErrorTo

The email address that server errors should be sent to. No secure information will normally be forwarded, so any email address is fine. If none is specified, no errors will be mailed.

MailErrorTo webmaster

MultiServer

If defined to be true, then multiple servers can share the socket and serve users. Not usable on SGI systems. Default is no

MultiServer yes

SendMailProgram

Specifies the program used to send email. Defaults to '/usr/lib/sendmail'. If it is not found at startup, MiniVend will complain and refuse to start.

SendMailProgram /bin/mailer

Catalog Configuraton File

In the catalog configuration file, these directives are required :

VendURL

Specifies the base URL that will run vlink as a cgi-bin program.

VendURL http://machine.company.com/cgi-bin/vlink

MailOrderTo

Specifies the email address to mail completed orders to.

MailOrderTo orders@xyzcorp.com

Optional Configuration Directives

AlwaysSecure

Determines whether checkout page operations should always be secure. Set it to the pages that should always be secure, separated by spaces and/or tabs.

AlwaysSecure checkout

AsciiBackend

A file name to log order fields in (set by BackendOrder). Unless preceded by a leading '/', will be placed relative to VendRoot. If the first character is a '|', it is the name of a program to send the fields to. Disabled by default.

AsciiBackend |/usr/order/scripts/place_order

AsciiTrack

A file name to log formatted orders in. Unless preceded by a leading '/', will be placed relative to VendRoot. Disabled by default.

AsciiTrack etc/orders.txt

ButtonBars

The ButtonBars directive allows you to define several preset button bars that reside in files. The button bar file will usually contain an IMG link, along with its associated client-side image map. This allows you to insert a [buttonbar 1] or [buttonbar 2] directive instead of the equivalent HTML, and is designed to make it easy to change the look of your pages with the change of one file. If the file does not exist at program configuration time, the tag is simply stripped. The line in the minivend.cfg file takes the form of the directive, followed by any number of vend-style file names (relative to the PageDir, with no .html suffix).

ButtonBars bars/button0 bars/button1 bars/button2 bars/button3

CheckoutFrame

The frame name where the checkout page will go, if frames are enabled. Default is ``_top''.

CheckoutFrame _blank

Cookies

Determines whether we will send (and read back) a cookie to get the session ID for links that go outside the catalog. Allows arbitrary HREF links to be placed in MiniVend pages, while still saving the contents of the session.

Cookies Yes

CollectData

The points at which to log various data items collected by MiniVend, such as failed or successful searches. This allows you to find out what your customers are searching for and NOT finding -- perhaps you want to add it, or change your product description to match. Uses something like the HTTP common log format.

The choices to enter are:

matched Search strings that match nomatch Search strings that fail to match page Pages that are accessed nopage Pages that are not found

Enter as a space or comma-separated list, i.e.

CollectData matched,nomatch,page

CreditCards

If set to Yes, enables the encryption and saving of fields on the order form that contain credit_card in their name. See Order Security. Default is no, or not enabled.

CreditCards Yes

CustomShipping

If not blank, enables the addition of shipping charges based on quantity or weight of items ordered. See Custom Shipping .

CustomShipping quantity

DataDir

The location of the extra database files if no path information is provided. Set to ``products'' as the default, and is relative to VendRoot if there is no leading slash.

DataDir /user/data

Database

Definition of an arbitrary database, in the form "Database database file type``, where ''file" is the name of an ASCII file in the same format as the products database. The file is relative to VendRoot, and is put in DataDir if no path is provided. Records can be accessed with the [data database field key] tag. The type is an integer from one to six, and specifies the format. There can be an unlimited number of databases defined. See Arbitrary Databases .

Database BookReviews reviews.txt 3

DefaultShipping

This sets the default shipping mode by initializing the variable mv_ship_mode. If not set in minivend.cfg , it is default.

DefaultShipping UPS

Delimiter

One of TAB, PIPE, CSV, or your own custom delimiter. (It is not suggested that you use a custom delimiter). TAB means a tab-delimited database (the default if not set), PIPE a pipe-delimited one, and CSV a quote-comma format.

Delimiter CSV

DescriptionField

The field that will be accessed with the [item-description] element.

DescriptionField ProductDescription

DescriptionTrim

This sets the text string after which no more of the product description will be displayed in the search area. This is useful to clip long descriptions, while still having them available to search. The default is no trimming.

DescriptionTrim DESCRIPTION:

EncryptProgram

Enables the encryption of fields containing the string credit_card in their name. If the Des module is not included, should contain a program command line specification that indicates how an external encryption program will work. Two placeholders, %p and %f, are defined, which are replaced at encryption time with the password and temporary file name respectively. See Order Security.

EncryptProgram /usr/local/bin/des -E -k %p < %f

FinishOrder

A text string or image tag which is substituted for the [finish_order] tag.

FinishOrder <IMG SRC="/icons/fin_ord.gif" ALT="FINISH ORDER">

FrameOrderPage

The MiniVend-style page name (i.e. no .html extension, relative to PageDir ) which contains the special order page for when frames are in use. If not set (the default), the standard order page will be used.

FrameOrderPage fr_order

FrameSearchPage

The MiniVend-style page name (i.e. no .html extension, relative to PageDir ) which contains the special search page for when frames are in use. If not set (the default), the standard search page will be used.

FrameSearchPage fr_resul

Glimpse

The pathname for the glimpse command, used if glimpse searches are to be enabled. If you wish to use glimpseserver, you must include the -C, -J, and -K tags if they are needed.

Glimpse /usr/local/bin/glimpse -C -J srch_engine -K2345

Help

The Help directive allows you to define an unlimited number of help messages or image specifications that reside in a file (or files). It is called by the [help item] tag, where item is the first line of a help file entry which looks like:

help1 This is help item one. It ends after a blank line, and is called by a [help help1] element embedded in a MiniVend page. help2 This is help item two. It ends after a blank line, and is called by a [help help2] element embedded in a MiniVend page.

If the file (or the entry) does not exist at program configuration time, the tag is simply stripped. The line in the minivend.cfg file takes the form of the directive, followed by any number of vend-style file names (relative to the PageDir, with no .html suffix). See the demo for an example of how it is used.

Help help/hintfile

ImageDir

The directory where all relative IMG and INPUT source file specifications are based. IT MUST HAVE A TRAILING / TO WORK. If the images are to be in the DocumentRoot (of the HTTP server or virtual server) subdirectory images, for example, you would use the ImageDir specification '/images/'. This would change SRC=``order.gif'' to SRC=``/images/order.gif'' in IMG and INPUT tags. It has no effect on other SRC tags.

ImageDir /images/

ItemLinkDir

The directory where the [item_link] tag will base all of its hot links in, relative to the pages directory. The default is blank, basing all links in the pages directory. If set, it needs a trailing '/' to operate properly.

ItemLinkDir partno/

ItemLinkValue

Specifies the text or image you want to use to provide a clickable link to the catalog page (in the search form, or other forms).

ItemLinkValue <IMG SRC="/images/gopage.gif" ALT="GO TO PAGE">

LogFile

A file where user pages accesses and search specifications will be logged if CollectData is set. Defaults to 'etc/log'.

LogFile etc/log

MixMatch

Sets whether quantity price breaks will be on TOTAL quantity or per-item quantity. Default is no mix and match, pricing is on a per-item basis. A yes or no field.

MixMatch yes

Mv_Background

Sets the background patterns to be used in the color schemes. The line must begin with 'BEGIN', then is followed by up to 15 pattern URLs containing background patterns to be used with the color schemes. Each pattern should be separated by one or more spaces. set to 0 to disable a background pattern for a particular scheme. Remember, the schemes are numbered in the order that they occur.

Mv_Background BEGIN /images/blue_pap.gif 0 /images/temple.jpg

Mv_BgColor

Sets the background colors to be used in the color schemes. The line must begin with 'BEGIN', then is followed by up to 15 RGB color specifications for background color. The specification can be in #RRGGBB color format, or can be one of the colors that will be recognized (steelblue, white, etc.) Each color should be separated by one or more spaces. Set to 'none' to disable a color (use the browser default) for a particular scheme. Remember, the schemes are numbered in the order that they occur.

Mv_BgColor BEGIN steelblue none white

Mv_LinkColor

Sets the link colors to be used in the color schemes. The line must begin with 'BEGIN', then is followed by up to 15 RGB color specifications for link color. The specification can be in #RRGGBB color format, or can be one of the colors that will be recognized (steelblue, white, etc.) Each color should be separated by one or more spaces. Set to 'none' to disable a color (use the browser default) for a particular scheme. Remember, the schemes are numbered in the order that they occur.

Mv_LinkColor BEGIN ltgreen none red

Mv_TextColor

Sets the text colors to be used in the color schemes. The colors are accessed with the [body n] tag, where n is the color scheme number. The line must begin with 'BEGIN', then is followed by up to 15 RGB color specifications for text color. The specification can be in #RRGGBB color format, or can be one of the colors that will be recognized (steelblue, white, etc.) Each color should be separated by one or more spaces. Set to 'none' to disable a color (use the browser default) for a particular scheme. Remember, the schemes are numbered in the order that they occur, beginning with 1.

Mv_TextColor BEGIN white none black

Mv_VlinkColor

Sets the visited link colors to be used in the color schemes. The line must begin with 'BEGIN', then is followed by up to 15 RGB color specifications for visited link color. The specification can be in #RRGGBB color format, or can be one of the colors that will be recognized (steelblue, white, etc.) Each color should be separated by one or more spaces. Set to 'none' to disable a color (use the browser default) for a particular scheme. Remember, the schemes are numbered in the order that they occur.

Mv_VlinkColor BEGIN orange none blue

NonTaxableField

The name of the field in the products database that is set (to 1 or yes) if an item is not to be taxed. Will log an error and tax it anyway if the field doesn't exist in the database. Blank by default, disabling the feature.

NonTaxableField wholesale

OrderCounter

The name of the file (relative to VendRoot if no leading /) that maintains the order number.

OrderCounter etc/order.number

OrderFrame

The frame name where the order page will go, if frames are enabled. If the frame doesn't exist, a new frame will be created. The default is '_top', which fills the browser window with the page.

OrderFrame _blank

OrderProfile

Allows an unlimited number of order profiles to be set up, specifying complex checks to be performed at each of the steps in the checkout process.

The files specified can be located anywhere -- if relative paths are used, they are relative to the MiniVend root directory.

OrderProfile prof/order0 prof/order1 prof/order2

They are accessed by setting the mv_profile variable to the number of the search profile, starting at 0.

OrderReport

The location of the simple order report file. Defaults to report.

OrderReport /data/order-form

PageDir

Location of catalog pages. Defaults to the pages subdirectory in the VendRoot directory.

PageDir /data/catalog/pages

PGP

If credit card information is to be accepted, and the emailed order will go over an unsecure network to reach its destination, PGP security should be used. The key ring to be used must be for the user that is running the MiniVend server, and the key user specified must have a key on the public key ring of that user.

PGP /usr/local/bin/pgp -feat orders@company.com

If this directive is non-null, PGP will be used to encrypt the order, the stored orders on disk, and the backend order string sent to an external file or program. If for some reason an error comes from PGP, the customer will be given the special page 'failed'.

PriceBreaks

The quantities where price breaks should be placed. Used to set up the pricing.asc entries to match actual pricing. Unlimited number of breaks -- only enter the lowest quantity it applies to.

PriceBreaks 10 25 50 100 1000

PriceCommas

If you desire no commas in your price numbers (for the [item_price] tag) set this to 'no'. The default is to put commas in.

PriceCommas no

PriceDivide

The number the price should be divided by to get the price in units (dollars or such). The default is one -- if you use penny pricing you can set it to 100.

PriceDivide 100

PriceField

The field in the product database that will be accessed with the [item-price] element. Default is ``price''.

PriceField ProductPrice

ProductDir

Location of the product files. Defaults to the products subdirectory of the VendRoot directory.

ProductDir /data/catalog/for-sale

Random

The Random directive allows you to define an unlimited number of random messages or image specifications that reside in files. It is called by the [random] tag. You don't know which one will show up! Even I don't, it is random. If the file does not exist at program configuration time, the tag is simply stripped. The line in the minivend.cfg file takes the form of the directive, followed by any number of vend-style file names (relative to the PageDir, with no .html suffix).

Random rand/message1 rand/message2 rand/message3 rand/message4

Rotate

The Rotate directive allows you to define an unlimited number of rotating messages or image specifications that reside in files. It is called by the [rotate] tag. If the file does not exist at program configuration time, the tag is simply stripped. The line in the catalog.cfg file takes the form of the directive, followed by any number of vend-style file names (relative to the PageDir, with no .html suffix).

Rotate rotate/banner1 rotate/banner2 rotate/banner3 rotate/banner4

ReadPermission and WritePermission

By default, only the user account that MiniVend runs under (as set by the setuid permission on svend) can read and write files created by MiniVend. WritePermission and ReadPermission can be set to 'user', 'group', or 'world'.

ReadPermission group WritePermission group

ReceiptPage

The page to be displayed as a receipt after the user has submitted an order. Replaces the standard 'confirmation' page. Blank by default, showing no receipt page to the user.

ReceiptPage receipt

ReportIgnore

A comma-separated list of items you don't want to have sent by email on the order report. Default is blank, or none. Fields beginning with 'mv_', the MiniVend special variables, are automatically ignored.

ReportIgnore credit_card_no

RequiredFields

A comma-separated list of items you want to make sure the customer fills in before an order can be submitted. If an empty field is found when the customer submits the order, the special page needfield.html will be displayed to request that they enter the information. No default.

RequiredFields name,company,email,address,city,state,zip

SalesTax

If non-blank, enables automatic addition of sales tax based on the order form. The value is a comma-separated list of the field names (as placed in order.html), in priority order, which should be used to look up sales tax percentage in the salestax.asc database. This database is not supplied with MiniVend -- it is typically received from a third party by quarterly or monthly subscription.

SalesTax zip,state

ScratchDir

The directory where scratch files will be written, notably cached searches. Defaults to VendRoot/etc.

ScratchDir /tmp

SearchOverMsg

A string that is substituted for a [search_over_msg] tag, used to indicate that the search engine returned more than the number of items it was limited to.

SearchOverMsg You had more than

SearchFrame

The frame name where search results will go, if frames are enabled. If the frame doesn't exist, a new frame will be created. The default is '_self'.

SearchFrame main

SearchProfile

Allows an unlimited number of search profiles to be set up, specifying complex searches based on a single click. Takes a series of MiniVend variable specifications.

As an added measure of control, the specification is evaluated with the special MiniVend [if area value ....]value[else]other value[/else][/if] syntax to provide conditional setting of search parameters.

The following file specifies a dictionary-based search in the file 'dict.product':

mv_search_file=dict.product mv_return_fields=1 [if value fast_search] mv_dict_limit=-1 mv_last=1 [/if]

The search profiles are specified in the same manner as the ButtonBars directive, with files to be located in the MiniVend page tree and read at program startup. If you change a search profile, you must stop and start MiniVend to have the changes take effect.

SearchProfile srch/search0 srch/search1 srch/search2

They are accessed by setting the mv_profile variable to the number of the search profile.

SecureURL

The base URL for secure forms/page transmissions. Normally it is the same as VendURL except for the https: protocol definition. Default is blank, disabling secure access.

SecureURL https://machine.com/xyzcorp/cgi-bin/vlink

SessionDatabase

When storing sessions in a DBM database, specify the base name of the DBM file to use. The file extensions of .pag, .dir, .db, or .gdbm (depending on the DBM implementation used) will be appended.

SessionDatabase session-data

Starting at MiniVend 2.0, it is possible for multiple catalogs to share the same session file. This allows a ``mall'' to be set up where many storefronts use a common ordering point. It would be wise to share the order pages, salestax database, and shipping database if that is the case. You will also need to set SessionLockFile appropriately if the database is to be shared. Defaults to 'session', which is appropriate for separate session files (and therefore standalone catalogs). Can be an absolute path name if desired.

SessionLockFile

The file to use for locking coordination of the sessions.

SessionLockFile session-data.lock

It is possible for multiple catalogs to share the same session file. You will also need to set SessionDatabase appropriately if the database is to be shared. Defaults to 'session.lock', which is appropriate for separate session files (and therefore standalone catalogs). Can be an absolute path name if desired.

SessionExpire

A customer can exit their browser or leave the catalog pages at any time, and no indication is given to the HTTPD server aside from the lack of further requests that have the same session id. Old session information needs to be periodically expired. The SessionExpire specifies the minimum time to keep track of session information. Defaults to one day.

SessionExpire 4 hours

Shipping

Specifies a shipping charge to add onto the total price for items ordered. If you do not want to include a fixed shipping charge on the order page, leave this 0 and do not include the [shipping] element in the order page. Defaults to 0. Overridden by the CustomShipping directive.

Shipping 5.00

TaxShipping

A comma or space separated list of states or jurisdictions that tax shipping cost, i.e. UT. Blank by default, never taxing shipping.

TaxShipping UT,NV,94024

Tracking

Enables order and popularity tracking when entered, as well as enabling password and credit card encryption for order security (in combination with the EncryptProgram directive). Its value is the initial order number that will be used as the beginning key for orders in the tracking database. See Tracking and Backend Order Entry and Order Security.

Tracking Order100001

UpsZoneFile

The file containing the UPS zone information, specified relative to the MiniVend page directory unless it begins with a /. The file containing the zone information should be in a tab-delimited format, with the three-letter zip prefix of the customer used to determine the zone. It interpolates based on the value in mv_shipmode. A user database named the same as the mv_shipmode variable must be present or the lookup will return zero.

UpsZoneFile /usr/minivend/data/ups_zone.asc

See the sample demo for an implementation -- the zone file in use is for Denver, CO and environs.

UseCode

This determines whether the part number field in the ASCII product file will be used to determine the link to the item for the [item_link] tag. If set, this has the effect of creating a different HTML page link for every part number. If not set (the default), the [item_link] tag uses the value of the last field in the ASCII product file as the link value. This option can be used to great effect with a program which automatically creates catalog pages from the database.

UseCode yes

UseModifier

Determines whether any attributes, the modifiers specified in the directive, can be attached to the item. See Item Attributes. The default is no modifier. Don't use a value of 'quantity' -- it will not do what you want.

UseModifier size,color

ADMINISTERING MINIVEND

Some thought should be given to where the databases, error logs, and session files should be located, especially on an ISP that might have multiple users sharing a MiniVend server. In particular, you might put all of the session files and logs in a directory that is not writable by the user -- if the directory or file is corrupted the server may go down.

To test the format of user catalog configuration files before restarting the server, you can do (from VendRoot):

That will check all configuration files for syntax errors, which might otherwise prevent the server from starting.

Starting, Stopping, and Re-starting the Servers

The following commands assume that you made /usr/local/lib/minivend your MiniVend base directory.

To start the server:

If the optional n, an integer from 1 to 9, is supplied, that number of servers will be started (assuming you have the MultiServer directive set to yes.

Assuming the server starts correctly, you will see a message stating the process ID it is running under -- that information is also sent to /usr/local/lib/minivend/error.log.

To re-start the server:

This is typically done to force MiniVend to re-read its configuration. You will see a message stating that a TERM signal has been sent to the process ID the servers are running under -- that information is also sent to /usr/local/lib/minivend/error.log. Check the error.log file for confirmation that the server has restarted properly.

To stop the server(s):

You will see a message stating that a TERM signal has been sent to the process ID the server is running under -- that information is also sent to /usr/local/lib/minivend/error.log.

Because processes waiting for lock in MultiServer mode are blocking signals, they may have to be killed more than once to die. This is normal and is of no concern.

Static page trees

You must specify a valid catalog to build. If you wish the page tree to go to a specific directory, you specify it as the next and optional parameter.

The page build iterates through every page in the pages directory, and every part number in the database (using the on-the-fly page build), and builds a page in regular HTML. All regular page references are converted to HREFs, except for search, scan, and order references which are kept relative to VendURL. This allows you to build static page trees that, in combination with cookies, can serve many pages via HTTP without parsing from MiniVend. It can also build page trees that are scannable by a search engine spider.

Making the Product Database

Expiring Sessions

You could add a crontab entry such as the following:

MiniVend will wait until the current transaction is finished before expiring, so you can do this at any time without disabling web access. Any search cache files for the affected session (kept in ScratchDir ) will be removed as well.

CONTROLLING PAGE APPEARANCE

Using Frames

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 sample demo pages:

Body and Buttonbar Control

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 catalog.cfg file, 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 in catalog.cfg, 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.)

Integrated Image Maps

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:

Random Banners

Rotating Banners

In-line Help

MANUAL INSTALLATION

The MiniVend installation is complex, and requires quite a few distinct steps. That is why there is an interactive configuration script that is included with MiniVend -- it merely does automatically what is described below. It makes the process much easier, and will install the demo catalog. This configuration script has been tested on some, but not all, UNIX systems. Please report problems to <mikeh@iac.net>.

Needed Directories

User catalog pages, user databases, and user configuration files should all go into their private directories. Because the catalog pages are served through the MiniVend cgi-bin program and contain nonstandard elements, they should not be put into a public WWW directory, nor do they need to have world-readable file permissions.

IMPORTANT NOTE: As of MiniVend 2.0, since catalogs are all run under one server, permissions are complex and very important. Please let the MiniVend configuration program do the work!

You will want a public WWW directory for in-line image graphic files. MiniVend does not serve the images, only the HTML tags calling them. A useful convention is to place all buttonbars, backgrounds, and icons in the /images directory, with the catalog items perhaps located in the /images/catalog directory. It is up to you, but remember that you must use an absolute path -- relative paths will not do. MiniVend 2.0 supports the ImageDir directive, which places that as the absolute path in front of all relative IMG and INPUT SRC specifications.

You will need a cgi-bin directory in which to put the vlink or svend program.

Unpacking the Distribution

If you have GNU tar, you can combine these steps:

The Demo Systems

To install the full-featured demo:

To install the simple demo:

You will have to edit the files to insert the proper VEND_URL for your server. Here is a one line perl command which will do that if you placed the vlink executable in the default /cgi-bin/vlink location:

Testing Your CGI-BIN Directory

Copy ``testcgi'' into your cgi-bin directory, and make it executable.

Try running testcgi from your shell command line to make sure that everything is working.

testcgi should respond with the version of Perl that you are running and your numeric user id.

Now try running testcgi from your browser. Write down the numeric user id which you get there, as you will need it later for svend and mat.

Setting up VLINK

LINK_FILE

Set this to the name of the socket file that will be used for configuration, usually ``/usr/local/lib/minivend/etc/socket'' or the ``etc/socket'' under the directory you chose for the VendRoot.

LINK_TIMEOUT

Set this to the number of seconds vlink should wait before announcing that the MiniVend server is not running. The default of 20 is probably a reasonable value.

PERL

Set this to the location of the perl (version 5 or higher) executable.

VEND

Set to the location of minivend.pl, typically in the VendRoot directory.

You will see some output as the configure script checks your system. Then compile the program:

On some systems you can make the executable smaller with the strip program. But don't worry about it if strip is not on your system.

If you want MiniVend to run under a different user account than your own, make that user the owner of vlink. (You probably need to be root to do this). Do not make vlink owned by root, because making vlink setuid root is an unnecessary security risk.

Make vlink setuid:

Move the vlink executable to your cgi-bin directory:

Some systems unset the SUID bit when moving the file -- re-set it if necessary.

Setting up minivend.pl

If you have the Des library and Perl Des module, uncomment the line:

That will allow internal encryption of credit card numbers stored on disk.

SETTING UP SVEND

CGIUSER

Set this to the numeric uid (user id) which HTTPD runs cgi-bin programs under. Typically this will be 'http', 'nobody' or 'guest'.

PERL

Set this to the location of the perl (version 5 or higher) executable.

VEND

Set to the location of minivend.pl, typically in the VendRoot directory.

On some systems you can make the executable smaller with the strip program. But don't worry about it if strip is not on your system.

If you want MiniVend to run under a different user account than your own, make that user the owner of svend. (You probably need to be root to do this). Do not make svend owned by root, because making svend setuid root is an unnecessary security risk.

Make svend setuid:

Move the svend executable to your cgi-bin directory:

AUTHORS