MiniVend allows customers to select items to buy from catalog pages. The
program tracks which products they have selected and the quantity
desired. From the ordering page they may complete the ordering process
by entering their name and address, or return to browsing and select
more items. Once the order process is completed, MiniVend submits
the order to the system via email or an external order entry program.
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.
Normally, each request for a World Wide Web page which comes in to a
server stands on its own. While the server will probably know which
machine a request comes from, it may not know if the next request
comes from the same browser or even from the same user on that
machine.
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:
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 MiniVend version described in this document is available from:
http://www.iac.net/~mikeh/download.html
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.
You will probably need Perl version 5.002 to run MiniVend 1.03. Many sites
are still running lower Perl versions. In addition, on systems that do not
have GDBM or DB_File installed, some of MiniVend's features (notably
DBM order and page access tracking) will not be available. Large catalogs
may be impossible to run due to memory limitations.
You can download the latest Perl 5 from any CPAN (Comprehensive Perl
Archive Network) site. Here are some of the many:
Czech Republic
ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/
Finland
ftp://ftp.funet.fi/pub/languages/perl/CPAN/
France
ftp://ftp.ibp.fr/pub/perl/CPAN/
ftp://ftp.pasteur.fr/pub/computing/unix/perl/CPAN/
Germany
ftp://ftp.leo.org/pub/comp/programming/languages/perl/CPAN/
ftp://ftp.rz.ruhr-uni-bochum.de/pub/programming/languages/perl/CPAN/
Great Britain
ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/
The Netherlands
ftp://ftp.cs.ruu.nl/pub/PERL/CPAN/
Poland
ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
Portugal
ftp://ftp.ci.uminho.pt/pub/lang/perl/
Slovenia
ftp://ftp.arnes.si/software/perl/CPAN/
Sweden
ftp://ftp.sunet.se/pub/lang/perl/CPAN/
Switzerland
ftp://ftp.switch.ch/mirror/CPAN/
AUSTRALASIA
Australia
ftp://coombs.anu.edu.au/pub/perl/CPAN/
ftp://ftp.mame.mu.oz.au/pub/perl/CPAN/
New Zealand
ftp://ftp.tekotago.ac.nz/pub/perl/CPAN/
ASIA
Japan
ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
Taiwan
ftp://dongpo.math.ncu.edu.tw/perl/CPAN/
AFRICA
South Africa
ftp://ftp.is.co.za/programming/perl/CPAN/
The most important issue with MiniVend is the permissions with
which the CGI program and the MiniVend server run.
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.
Before you begin, select the base directory where you want to install
MiniVend. You can unpack the tar file either there, or in another
temporary directory -- the configure script handles either. The
suggested directory is /usr/local/lib/minivend -- but really any
directory will do. You must of course have write permission there; and
you will eventually need to have write permission on your CGI-BIN
and HTML directories.
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:
gzip -d mvend200.tar.gz
tar xf mvend200.tar
If you have GNU tar, you can combine these steps:
tar xzf mvend200.tar.gz
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:
./configure
If you have trouble with ./configure, try this:
perl configure.pl /usr/bin/perl
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
.
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:
Located in the directory where the individual catalog resides,
this file has most of the parameters which define the catalog.
Each catalog can be completely independent, with different databases --.or catalogs can share any or all databases and session files. This
means that several catalogs can share the same information, allowing
``virtual malls''. Each catalog maintains its own pages and possibly its
own databases, but can easily share ordering information with other
storefronts.
The steps to set up the multiple server capability are:
Install the MiniVend software. Use the supplied makecat program
to install the demo catalogs, 'sample' and 'simple'.
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.
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'.
Run the makecat program:
bin/makecat real
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.
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:
http://www.iac.net/~mikeh/bugreport.html
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.
MiniVend uses its own tags to implement catalog functions -- they
are similar to normal HTML, but are in [square brackets]. They
will be referred to as either tags or elements in this document.
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.
The first thing you must do is develop your product database. This might
contain all of the information used to display pages about your
products -- or just the product code (SKU), short description, and
price. At the minimum, those three fields are required.
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).
The on-the-fly page capability of MiniVend makes it easy to build
your catalog without hard-coding a single page. To build category
pages, use the one-click search. To build single-item pages, use
the flypage.html template and build your own.
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.
The demo catalogs supplied with MiniVend are there to give you a starting
point for your own catalog. Play with them, change them, and rename them --
add your own icons, change flypage.html, change the results.html files,
etc.
Determine how users will enter and exit your catalog. There are quite
complex and intelligent conditional schemes possible, especially if you
use the
Cookies
capability, but simplicity is often the easiest and
most reliable.
Pages in the catalog are written in regular HTML with extensions to
support catalog ordering. To distinguish them from regular HTML, these
extended elements use square brackets instead of angular brackets.
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.
As of MiniVend 1.03, all you need to do to have users with cookie-capable
browsers retain session context is enable the
Cookies
directive.
You can then intermix standard HREF and MiniVend page links without
fear of losing the shopping basket.
NOTE: In the descriptions, parameters marked with an asterisk* are
optional.
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
.
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.
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.
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.
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:
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.
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.
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.
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. Must be
supplied, there is no default. A shorthand method
is to just supply the number as the I 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.
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.
To build complex order forms and reports, MiniVend supplies some conditional
capability with the [if ...] text [else] else-text [/else][/if]
construct. It allows for testing for a condition within the Vend session,
and if true, inserting text and/or HTML. If the condition is not true, no
text (or the optional [else] text) will be inserted.
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:
[[any tag]] item-list loop default value scratch calc if lookup set
data file finish_order frames_on frames_off secure_order framebase
body help buttonbar random rotate checked selected accessories field
static pagetarget area areatarget page last_page perl order nitems
discount subtotal shipping shipping_description salestax total_cost
price description row process_order process_search process_target
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.
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.
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.
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:
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:
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.
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.
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.
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.
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.
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.
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.
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 code can be as complex as desired, but cannot use any operators.that modify the filesystem or use ``unsafe'' operations like ``system'',
``exec'', or backticks. These constraints are enforced with the default
permissions of the standard Perl module Safe.
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:
[perl] my $tmp = "Hello, world!"; $tmp; [/perl]
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:
[perl browser]
my $html = '
';
$html .= $browser;
$html .= '
';
$html;
[/perl]
To show the user their name, and the current time:
[perl values]
my $string = "Hi, " . $values{'name'} ". The time is now ";
$string .= localtime;
$string;
[/perl]
If an item is displayed on the search list (or order list) and there is
a link to a special page keyed on the item, MiniVend will attempt to
build the page ``on the fly''. It will look for the special page
flypage.html, which is used as a template for building the page. If
[item_field fieldname]
,
[item_price]
, (etc.) elements are used on the page,
quite complex and information-packed pages can be built. The
[if_field fieldname]
HTML
[/if_field]
pair can be used to only insert
HTML if there is a non-blank value in a particular field.
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.
A number of HTML pages are required for MiniVend operation. Typically they
are used to transmit error messages, status of search or order operations, and
other out of boundary conditions.
As of MiniVend 1.03, the names of these pages can be set with the SpecialPage
directive. The standard pages and their default locations:
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).
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
.
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.
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.
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
.
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,
MiniVend, as with most powerful shopping cart programs, is all about
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.
A simple auxiliary database keyed on the product code. It's value
is available via the [item_accessories] or [accessories code] tags.
See
Accessories
.
Each product you are selling should be given a product code: A short
code that identifies the product on the ordering page and in the
catalog. You can use any combination of letters, digits, dashes,
periods, pound signs, or underscores for the product code. The
products.asc file is a ASCII-delimited list of all the product codes,
along with an arbitrary number of fields which must contain at least the
fields 'description' and 'price' (or whatever you set the PriceField and
DescriptionField directives to). Any additional information you want in
the catalog can be placed in any arbitrary field.
See MiniVend Database Capabilityfor details on the format.
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.
MiniVend can also manage an unlimited number of arbitrary databases.
They are in the same format as the products file by default, but
6 addressable schemes are available:
Type 1 Default - same as products file (TAB, PIPE, or CSV)
Type 2 Each field on its own line, a blank line or lines
separates the record. Watch those carriage
returns!
Type 3 Fields separated by a \n%%\n combination, records by
\n%%%\n (where \n is a newline). Watch those carriage
returns!
Type 4 CSV
Type 5 PIPE
Type 6 TAB
The databases are specified in
Database
directives, as:
Database Arbitrary /usr/data/arbitrary.asc 4
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.
MiniVend treats some form fields specially, to link to the search engine
and provide more control over user presentation.
These special fields all begin with mv_, and include:
mv_background Explained in Controlling Page Appearance
mv_base_directory Explained in Search Engine
mv_bgcolor Explained in Controlling Page Appearance
mv_case Explained in Search Engine
mv_checkout Explained in The Order Page
mv_coordinate Explained in Search Engine
mv_credit_card* Discussed in order security
mv_customcolors Explained in Controlling Page Appearance
mv_dict_end Explained in Search Engine
mv_dict_fold Explained in Search Engine
mv_dict_limit Explained in Search Engine
mv_dict_look Explained in Search Engine
mv_dict_order Explained in Search Engine
mv_doit Common to all forms, sets default action
mv_errorpage Sets error page if order check fails
mv_exact_match Explained in Search Engine
mv_helpon Turns on the help feature if defined
mv_helpoff Turns off the help feature if defined
mv_linkcolor Explained in Controlling Page Appearance
mv_matchlimit Explained in Search Engine
mv_max_matches Explained in Search Engine
mv_nextpage Sets next page user will go to after submission
mv_order_item Explained in The Order Page
mv_order_number Explained in Fully Configurable Order Reports
mv_orderpage Explained in The Order Page
mv_orsearch Explained in Search Engine
mv_profile Explained in Search Engine
mv_range_alpha Explained in Search Engine
mv_range_look Explained in Search Engine
mv_range_max Explained in Search Engine
mv_range_min Explained in Search Engine
mv_resetcolors Explained in Controlling Page Appearance
mv_return_fields Explained in Search Engine
mv_search_field Explained in Search Engine
mv_search_file Explained in Search Engine
mv_search_over_msg Explained in Search Engine
mv_search_page Explained in Search Engine
mv_searchspec Explained in Search Engine
mv_searchtype Explained in Search Engine
mv_shipmode Explained in The Order Page
mv_spelling_errors Explained in Search Engine
mv_substring_match Explained in Search Engine
mv_textcolor Explained in Controlling Page Appearance
mv_todo Common to all forms, sets form action
mv_todo.map Contains form imagemap
mv_todo.checkout.x Causes checkout action on click of image
mv_todo.return.x Causes return action on click of image
mv_todo.submit.x Causes submit action on click of image
mv_todo.x Set by form imagemap
mv_todo.y Set by form imagemap
mv_vlinkcolor Explained in Controlling Page Appearance
MiniVend implements a search engine which will search the product
database (or any other file) for items based on customer input. It uses
the (example) query.html, results.html, helpquery.html, mvfaq.html,
and category.html files in the <EM>sample/pages</EM> directory,
and has some of its own special tags and variables.
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.
A number of variables can be set on search forms to determine which search
will be used, and what fields in the database it will search.
Here is a simple 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:
Search by author
Search by title
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).
To use the Glimpse search, you must build the Glimpse index based on
files in your
ProductDir
, or wherever the files to be searched will
be located. If you installed MiniVend in the default
/usr/local/lib/minivend, the command line to build the index for the
products file would be:
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 searching is useful for scanning large databases for
strings that match the beginning of a line. They use the standard
Perl module Search::Dict, and are enabled through use of the
mv_dict_look
,
mv_dict_end
,
mv_dict_limit
,
mv_dict_fold
, and
mv_dict_order
variables.
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 allows you to qualify your search returns with a field
that must be within a certain numeric or alphanumeric range. To use it,
set the mv_range_look variable to the products database field, or a
column/field number for another file. Then set the corresponding
mv_range_min
and
mv_range_max
variables with a selectable field.
Search on Price
Min
Max
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.
The two-letter abbreviations are mapped with these letters:
ac mv_all_chars mp mv_profile
bd mv_base_directory ms mv_min_string
co mv_coordinate os mv_orsearch
cs mv_case ra mv_return_all
de mv_dict_end rd mv_return_delim
df mv_dict_fold rf mv_return_fields
di mv_dict_limit rg mv_range_alpha
dl mv_dict_look rl mv_range_look
do mv_dict_order rm mv_range_min
dr mv_record_delim rn mv_return_file_name
em mv_exact_match rs mv_return_spec
er mv_spelling_errors rx mv_range_max
fi mv_search_file se mv_searchspec
hs mv_head_skip sf mv_search_field
id mv_index_delim sp mv_search_page
ml mv_matchlimit st mv_searchtype
mm mv_max_matches su mv_substring_match
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.   is a space, / 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:
[page scan/se=Surreal/se=Gogh/os=yes/su=yes/sf=artist/sf=category]
Van Gogh -- compare to surrealists
[/page]
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).
The sample srch/query.html, srch/helpquery.html and
srch/category.html pages show example search forms. You can modify
them to present the search in any way you like -- just be careful to use
the proper variable names for passing to MiniVend. It is also necessary
that you copy the hidden variables as-is -- they are required to
interpret the request as a search. The special form variables are:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
The MiniVend-style name of the page that should display the search
results. Overrides the FrameSearchPage directive, and the default
value of 'search'.
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).
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.
Once a search has been done, there needs to be a way of presenting
the output. By default, the special page search.html is used -- but
any number of search pages can be specified by passing the value in
the search form, specified in the variable
mv_search_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]].
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.
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.
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.
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.
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.
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 page(s) are where the items are tracked and adjusted by the
customer. It is possible, beginning with MiniVend 1.03, to have an
unlimited number of order pages. This allows a basket/checkout type
of ordering scheme, with custom order pages for items which have
many accessories.
The name of the page to display can be configured in several
ways:
Set the SpecialPage 'order' to the page to display
when an item is ordered.
Set the FrameOrderPage directive to the page to use
when frames are enabled. This overrides option 1.
Use the [order item page] Order it! [/order] form of
order tag to specify an arbitrary order page for an item.
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:
Page to be displayed on a refresh
Page to be displayed when checkout is called from the form
The Accessories database is a place to keep conditional accessory.items for display on the order page (or anywhere else, for that matter).
This allows you to place additional conditional items on the order page,
perhaps checkboxes or a drop-down menu to select a color or style. Or
you can have whole conditional trees to automatically configure a product
to a customer's needs.
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:
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.
Expands into the total cost of all the items ordered so far, including
sales tax (if any).
Within any order page, the [item_list] element shows a list of all the.items ordered by the customer so far. It works by repeating the source
between [item_list] and [/item_list] once for each item ordered.
Between the item_list markers the following elements will return
information for the current item:
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.
Evaluates to the name to give an input box in which the
customer can enter the quantity to order.
A [loop item,item..] list is similar, but does not include the items.that are associated with the order list, and the tags are prefixed
loop_, so that loop and item lists may be interspersed. Item lists
are evaluated before loop lists, so you can put an item-code inside of
an loop list. If you want to reverse the order, put the loop list in a
double set of brackets to force earlier evaluation. Up to 1024 items
may be present in a loop list.
An unlimited number of order checking profiles can be defined
with the
OrderProfile
directive. This allows a multi-level ordering
process, with checking for format and validity at every stage.
Specifications take the form of an order page variable (like name
or address), followed by an equals sign and one of five check types:
Rudimentary email address check, must have an '@' sign,
a name, and a minimal domain
Also, there are three pragmas that can be used to change behavior:.
&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
As an added measure of control, the specification is evaluated with the.special MiniVend tags to provide conditional setting of order
parameters. With the new [perl] [/perl] capability, quite complex checks
can be done. Also, the name of the page to be displayed on an error
can be set in the
mv_errorpage
variable.
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.)
You can specify a fully-configurable order report by setting the hidden
field ``mv_order_report'' to a legal MiniVend page. This page will be
interpolated with all MiniVend tags before sending by email. The order
number as set by backend ordering is in the variable mv_order_number,
and available for your use.
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>.
If you specify a legal MiniVend page name in the ReceiptPage directive,
the user will be sent this page instead of the default ``confirmation.html''
file. The file can of course be configured with all MiniVend tags, and
will be interpolated for the ordered items before they are deleted from
the user record.
An order counter can be enabled if the
OrderCounter
directive
is set to a file name. An incrementing count of all orders will be
kept and assigned as orders are placed. By default, the number
starts at 0, but you can edit the file and change the default
starting number at any time.
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.
On the order (or shopping basket) page, by default order.html, you will
have a number of input fields allowing customer to enter information
such as their name and address. You can add more fields simply by
putting more input elements on the order.html page, and the information
will automatically be included in the order report. Input elements
should be written in this way:
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,
value="[value name]"
will evaluate to the name entered on the previous order screen, such
as:
value="Jane Smith"
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.
MiniVend allows item attributes to be set for each ordered item. This
allows a size, color, or other modifier to be attached to a common
part number. If multiple attributes are set, then they should be
separated by commas. Previous attribute values can be saved by means
of a hidden field on a form, and new attributes stacked on top of
each other.
The configuration file directive
UseModifier
is used to set
the name of the modifier or modifiers. For example
UseModifier size,color
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 can be set upon display of any page. The discounts
apply only to the customer receiving them, and are of one of three types:
1. A discount for one particular item code (key is the item-code)
2. A discount applying to all item codes (key is ALL_ITEMS)
3. A discount applied after all items are totaled
(key is ENTIRE_ORDER)
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:
[discount ALL_ITEMS] $s * .8 [/discount]
To take 25% off of only item 00-342:
[discount 00-342] $s * .75 [/discount]
To subtract $5.00 from the customer's order:
[discount ENTIRE_ORDER] $s - 5 [/discount]
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:
[discount 00-343]
return $s if $q == 1;
my $p = $s/$q;
my $t = ($q - 1) * $p;
$t .= 0.01;
return $t;
[/discount]
MiniVend allows calculation of sales tax on a straight percentage basis,
with certain items allowed to be tax-exempt. To enable this feature,
the directive
SalesTax
is initialized with the name of a field (or
fields) on the order form. Commonly, this is zipcode and/or state:
SalesTax zip,state
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:
default 0
45056 .0525
61821 .0725
61801 .075
IL .0625
OH .0525
WA .08
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.
MiniVend allows the addition of a flat shipping charge with
the
Shipping
directive. Most catalogs have more elaborate
requirements, requiring use of the
Custom Shipping
capability
of MiniVend.
MiniVend allows custom shipping charges to be added to an order based on
the value of an entry in the database. To enable custom shipping, enter
the default field to use in the
CustomShipping
directive:
CustomShipping weight
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.
The total cost (formula if begins with 'f', or multiplier,
if begins with 'x')
The cost is calculated like this:.
The base code is selected. If there is more than one entry per
code, numbers should be appended.
The criterion field is found -- if it is quantity, then it
is the total quantity of items on the order form.
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.
If the cost is fixed, it is simply added.
If the cost field begins with an 'x', the cost is multiplied
by the accumulated criterion -- price, weight, etc.
If the cost field begins with 'f', the formula following
is applied. Use $x as the value of the accumulated criterion.
If the cost field begins with 'u', a UPS lookup is done.
If no match is found, the 'default' entry is used.
Here is an example shipping file using all of the methods of.determining shipping cost.
NOTE: The columns are lined up for your reading convenience, the actual
entries should have ONE tab between fields.
rpsg RPS Ground quantity 0 0 0
rpsg1 RPS Ground quantity 1 5 7.00
rpsg2 RPS Ground quantity 6 10 10.00
rpsg3 RPS Ground quantity 11 99999999 x .95
usps US Postal price 0 0 0
usps1 US Postal price 1 50 f 7 + (1 * $x / 10)
usps2 US Postal price 50 100 f 12 + (.90 * $x / 10)
usps3 US Postal price 100 99999999 f 12 + (.05 * $x)
upsg UPS Ground weight 0 0 0
upsg1 UPS Ground weight 1 99999999 u upsg [value zip]
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:
1. Your UPS zone
2. Weight (careful, always use weight for this one!)
3. The zip/postal code of the recipient
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.
MiniVend has a tracking option, enabled with the configuration
directive
Tracking
. Entered orders and page popularity are tracked.
The tracking database is also used to hold encrypted data such as credit
card numbers, expiration dates, and the encrypted MiniVend password.
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:
Key Value
---------------- ----------------------------
Order00001 (The order report, filled in -- see "Order Report File")
BackendOrder00001 Joe J. User123 Any St.Main StreetOH
12345Acct#123P-1332
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:
Key Value
---------------- ----------------------------
CcOrder00001 (encrypted data)
ExpOrder00001 (encrypted data)
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.
Instead of the DBM-based tracking, you can choose to track only orders
and not pages with the
AsciiBackend
and
AsciiTrack
directives.
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.
MiniVend has several features that enable secure ordering via SSL
(Secure Sockets Layer). Despite their mystique, SSL servers are actually
quite easy to operate. The difference between the standard HTTP server
and the SSL HTTPS server, from the standpoint of the user, is only in
the encryption and the specification of the URL -- https: is used for the
URL protocol specification instead of the usual http: designation.
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:
use Des;
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:
EncryptProgram /usr/bin/des -e -k %p < %f
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 2.0 now runs multiple catalogs on the
same server. If no
Catalog
directives are present in the main
minivend.cfg
file, the server will read only a single catalog's
information from the one
minivend.cfg
file, just as in
previous versions of the program.
The VendRoot directory, specified in the main program minivend.pl, is
the default location of all of the MiniVend program, configuration,
special, and library files. Unless changed in minivend.pl, the main
MiniVend server configuration file will be minivend.cfg in the VendRoot
directory.
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.
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.
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.
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.
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.
If multiple catalogs are to be run, each must have a
catalog.cfg
file located in the catalog base directory. It contains most of
the configurable parameters for MiniVend -- each is independent
from catalog to catalog.
In the catalog configuration file, these directives are
required
:
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.
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.
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).
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.
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
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.
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.
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
.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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'.
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.
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.
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
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).
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'.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Several utilities are supplied in the VendRoot/bin directory:
stop Stops the server(s)
start Starts the server(s)
restart Re-starts the server (simply stops and starts)
dump Dumps the session file for a particular catalog
expire Expires sessions for a particular catalog
buildtree Builds static page trees from the database
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):
perl -w minivend.pl -test
That will check all configuration files for syntax errors, which
might otherwise prevent the server from starting.
When running in server mode, MiniVend operates much faster. Since
it is loaded once, and keeps some of the database files open continuously,
it merely needs to field the CGI request (via vlink) and perform
the appropriate function. But because it is running, some of the
databases are locked -- and you will need to unlock them to perform
administrative functions. The supplied scripts will do that
for you.
The following commands assume that you made /usr/local/lib/minivend
your MiniVend base directory.
To start the server:
/usr/local/lib/minivend/bin/start [n]
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:
/usr/local/lib/minivend/bin/restart [n]
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):
/usr/local/lib/minivend/bin/stop
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.
You can build a complete static page tree for a particular
catalog with this command:
buildtree [output-dir]
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.
As of MiniVend 1.02, the product database is made automatically upon
server startup, and no special command is required. You must notuse the old makedbm command from V1.01.
You should periodically expire old sessions to keep the session
database file from growing too large.
expire -c catalog
You could add a crontab entry such as the following:
# once a day at 4:40 am
40 4 * * * perl /usr/local/lib/minivend/bin/expire -c catalog
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.
MiniVend fully supports frames, the proposed extension to HTML 3.0. (Currently
only Netscape 2.0 and above browsers support frames.) Frames significantly
enhance the electronic catalog experience, since the user can maintain
a context -- with a search frame, a product details frame, a table-of-contents
frame, etc. The demo included with MiniVend is based on frames, though if
you access it with a non-frame browser it will operate perfectly well.
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:
greet.html Starting frame for frames-based browsers - has [frames_on]
nf_greet.html Turns off frames -- has [frames_off]
reframe.html Re-enables frames after they have been turned off
MiniVend provides centralized page color and imagemap control through
use of the [body n] and [buttonbar n] elements. It also can place a random
message from a series of messages with the [random] element, and embed
help messages with the [help item] element.
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:
Mv_Background BEGIN /images/blue_pap.gif
Mv_BgColor BEGIN none steelblue white
Mv_LinkColor BEGIN none white black
Mv_TextColor BEGIN none ltgreen blue
Mv_VlinkColor BEGIN none orange purple
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:
ButtonBars bars/artbar0 bars/artbar1 bars/artbar2
The above entry allows you to define three imagemaps and access them in
your pages simply as [buttonbar 0], [buttonbar 1], and [buttonbar 2]. The
advantage of this scheme is central definition of a series of button bars
with only a few tags -- if you change your page colors or mapping, you
need only change one file and the change will roll over to all of your
catalog pages. Since some installations can number in the thousands
of catalog pages, using the pre-defined buttonbars can save a lot of
editing. (Server-side includes cannot be used to achieve the same thing
with MiniVend, since they wouldn't have the proper URLs.)
Imagemaps can also be defined on forms, with the special form variable
mv_todo.map. A series of map actions can be defined --
the action specified in the default entry will be applied if none
of the other coordinates match. The image is specified with a standard
HTML 2.0 form field of type IMAGE. Here is an example:
All of the actions will be combined together into one image map with
NCSA-style functionality -- see the NCSA imagemap documentation for
details -- except that MiniVend form actions are defined instead
of URLs. The standard actions are:
submit Submit order
refresh Refresh order page (update quantities, etc.)
cancel Cancel order and wipe credit card numbers
return Go to previous page (or page defined in mv_nextpage variable)
control Control help, colors, etc.
search Search for an item in the catalog
The [random] element, in conjunction with the
Random
directive in the
catalog.cfg file, is similar to the buttonbar tag, except it displays
random messages or images. It can be used to place a random tip, hint,
ad, or message, and can be any legal HTML construct.
The [rotate] element, in conjunction with the
Rotate
directive in the
minivend.cfg file, is similar to the random tag, except it displays
messages or images guaranteed to be presented to the user in a specific
order. It can be used to place a tip, hint, ad, or message, and can be any
legal HTML construct.
The [help tag] element, in conjunction with the Help directive in the
minivend.cfg file, is similar to the buttonbar tag, except it displays
help messages or images, and is keyed by item name. The help can be
contained in any of a series of files defined in the Help directive. It
can contain most MiniVend elements. The user can turn off help through
a form -- see the control.html file for an example.
NOTE: The manual installation procedure is not up to date.
It is HIGHLY RECOMMENDED that you use the configure script.
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>.
The MiniVend program, and its supporting libraries, should all
go into one directory.
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.
The products directory contains a sample product file and the file
report in the main directory is the sample order report. Sample catalog
pages are in the directories sample/ and simple/. If you would like to
use them as a starting point for your own catalog, you can either have
the configure script install the demo for you, or you can copy the
sample files into the MiniVend directory and your HTML directory, which
for these examples is assumed to be /usr/local/etc/httpd/htdocs.
To install the full-featured demo:
cd /usr/minivend # wherever your vend directory is
mkdir /usr/local/etc/httpd/htdocs/sample # or your document root
mkdir /usr/local/etc/httpd/htdocs/sample/images
cp sample/images/* /usr/local/etc/httpd/htdocs/sample/images
cp sample/special*.html /usr/local/etc/httpd/htdocs/sample
cp sample/index.html /usr/local/etc/httpd/htdocs/sample
cp sample/intro.html /usr/local/etc/httpd/htdocs/sample
cp sample/address.html /usr/local/etc/httpd/htdocs/sample
To install the simple demo:
cd /usr/minivend # wherever your vend directory is
mkdir /usr/local/etc/httpd/htdocs/sample # or your document root
mkdir /usr/local/etc/httpd/htdocs/sample/images
cp sample/images/* /usr/local/etc/httpd/htdocs/sample/images
cp simple/index.html /usr/local/etc/httpd/htdocs/sample
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:
cd /usr/local/etc/httpd/htdocs/sample # or your document root
perl -npi -e 's:__VEND_URL__:/cgi-bin/vlink:g' *.html
This is a good time to test your cgi-bin configuration and find out
the numeric user-id which your HTTPD server runs cgi-bin programs
under. Edit ``src/testcgi'' and change the first line to refer to your Perl
version 5 (or higher) executable.
#!/usr/bin/perl
Copy ``testcgi'' into your cgi-bin directory, and make it executable.
The
vlink
program, compiled from link.c, is a small C program
which is setuid to the user account which can access the catalog data
files, and contacts a running MiniVend daemon. If the MiniVend daemon,
is not running, it will attempt to start it. The following defines at the
beginning of link.c should be set:
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.
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.
Set to the location of minivend.pl, typically in the VendRoot
directory.
Change directories to the src directory, then run the GNU.configure script:
cd src
./configure
You will see some output as the configure script checks your system.
Then compile the program:
cc link.c -o vlink
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.
strip vlink
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.
chown vendacct vlink
Make vlink setuid:
chmod u+s vlink
Move the vlink executable to your cgi-bin directory:
mv svend /the/cgi-bin/directory
Some systems unset the SUID bit when moving the file -- re-set it
if necessary.
svend is a small C program which is setuid to the user account which
can access the catalog data files. The following defines at the
beginning of svend.c should be set:
Set to the location of minivend.pl, typically in the VendRoot
directory.
Compile svend.c with your C compiler:.
cc svend.c -o svend
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.
strip svend
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.
chown vendacct svend
Make svend setuid:
chmod u+s svend
Move the svend executable to your cgi-bin directory:
Original author of Vend is Andrew Wilcox, awilcox@world.std.com
MiniVend is based on Vend 0.2, with portions from Vend 0.3,
and is enhanced and modified extensively by Mike Heins, mikeh@iac.net