The tags, which are in [square brackets], are interpreted by MiniVend and many different values can be substituted. Some examples are:
[value input_field]
tag. The input_field is a normal HTML form field.
[data table=products field=name key=334-12].
[data session source]
and [data session referer]), domain they are from ([data session host]),
the time of their last access ([data session time]), and many other parameters.
[file directory/file],
or the output from an arbitrary program (given proper permission from
your administrator!).
The link program, which is a regular CGI program, calls the MiniVend server. The MiniVend server sees the path information which is appended to the URL calling it, and brings up the corresponding page. The page contains a link to order items from your catalog.
The user clicks on the link and MiniVend looks in the a products database, finds the item, and places it in the user's shopping cart. (Each user has a separate shopping cart, which is attached to their session .)
Once the user decides to purchase, they check out by filling out a form with their name, address, payment information, etc. In the process they may make choices about how the product should be shipped, how they will pay, and provide any other information you may ask for. They then place (or ``submit'') the order.
Their payment may be taken at that point via CyberCash and a soft-goods product downloaded -- or their order information may be simply sent to you, the store owner, via encrypted email or FAX. The order is saved to a file or database table as backup, or in the case of fully-automated systems sent directly to an order entry program or database link.
All of these operations are fully configurable by you. The base MiniVend distribution includes a sample store -- some users have simply customized the text and images inside, changed the database entries, and opened their store. You will probably want to fully customize for a distinctive catalog look and feel.
MiniVend keeps track of who is ordering what by including in the URL a session id , which is a random piece of text which is different for each customer browsing the catalog.
This session ID is either tracked with cookies, or it can be passed along through special URLs within catalog pages. Pages in the catalog served by MiniVend running as a cgi-bin program generate a special URL for every link. Here is an example of such a URL:
An explanation of each part:
Pages are delivered through the following steps:
The only exception is that any individual or organization using uninvited email solicitations (commonly known as SPAM) may not use MiniVend for a period of one year from their last SPAM incident. Upon sending of SPAM, the user must immediately discontinue using MiniVend
Once their Internet Service Provider (or network backbone provider) is notified by the author, they must discontinue use of MiniVend. Use of MiniVend after such a notification is subject to a US$1,000 per day license fee payable to the author.
If such an individual uses MiniVend, let the author know and an immediate investigation will be started.
MiniVend is not guaranteed to be supported other than by making full source code available. If it breaks you get to keep both pieces. However, the author is always looking to improve MiniVend and sometimes answers questions. The more concise and better-researched your question, the more likely it is to get an answer. No tutorials will be provided, though. You have to learn all of this stuff on your own.
You can also go to any CPAN archive and access the directory
authors/id/MIKEH.
You can download the latest Perl 5 from any CPAN (Comprehensive Perl Archive Network) site. Here are some of the many:
NORTH AMERICA
EUROPE
AUSTRALASIA
ASIA
AFRICA
MiniVend uses a server running in the background, with a small
C program (generically 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 3.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
for multiple users if run as the superuser.
NOTE FOR WINDOWS: Windows users need to unzip the file with whatever program they use, or obtain the self-extracting executable.
Before installing, check the site where you obtained MiniVend for any patches that might have been issued since the release.
Change to the created directory, something like:
Run the configure script with:
NOTE FOR WINDOWS: Type configure instead. The ./ is needed for
UNIX users with a properly setup shell.
If you have trouble with ./configure, try this:
Replace the perl with the proper path to your Perl 5.004
or higher binary.
You will be asked for the directory where you want to install MiniVend -- 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. This directory is referred to later in the documentation as VendRoot or the MiniVend software directory.
The process should be self-explanatory. If you have trouble answering the questions asked, look closely at the examples provided. If you still have trouble, you will need to find a tutorial about the World Wide Web -- the WWW FAQ at www.boutell.com would be a good place to look.
If you discover any problems, refer to the section I 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 If you are on an ISP where all of your files are in HTML document
space, you should disable all access to your MiniVend catalog directory
with the proper HTTP access restrictions. Normally that is creating
a .htaccess file like this:
If you are unable to do this, it is recommended that you do not run
MiniVend. If you can set file permissions such that files will not be
served, it may be OK, but security will be a problem. Please be careful
with your customers' personal information.
The
Catalog
directive defines which catalogs will be
created at server startup.
Each catalog can be completely independent, with different databases --
or catalogs can share any or all pages, databases, and session files. This
means that several catalogs can share the same information, allowing
``virtual malls''.
is encountered in the catalog.cfg file.
If you get a message about not being able to find libraries, or if you
get a core dump or segment fault message, it is always improperly built
or configured Perl and has nothing to do with MiniVend. Contact your
system administrator or install a new Perl yourself.
The
Check the two error log files --
error.log
in the MiniVend
home directory (where minivend.cfg resides) and
error.log
in the
catalog directory (where catalog.cfg resides; there can be many of
these). Many problems can be diagnosed quickly if these error logs
are consulted.
Check the README file, the FAQ, and mail list archive at the official
MiniVend web site for information:
You may subscribe to the MiniVend users mail list by sending the
message text
Double check that you have the following things:
If you have trouble with the vlink program (named
simple
in the demo
configuration), try re-running The
IMPORTANT NOTE: The MiniVend server should not run as the user
The program files can be owned by anyone, but any databases, ASCII
database source files, error logs, and the directory that holds them
must be writable by the proper user ID, that is the one that is
executing the minivend program. The best way to operate in
multi-user, multi-catalog setups is to create a special
The
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, but are not a finished product.
Some other things you might put in:
You can also define any other attribute information in a database
field.
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, though you would be surprised how much of a maintenance headache
they are compared to database definitions. Build them just about like
normal HTML pages, except for the MiniVend tags to order the item.
Place them wherever they can be reached -- if you are using searches,
you will want to name the file by the part number, or at least make a
link to it.
Some other things you might put in:
All of the mentioned features (and more) are demonstrated in the
simple
demo catalog.
These tags perform various display and modification operations for
the user session. The tag names and their general function are:
The syntax for each tag is displayed in the documentation below.
The first page displayed in the catalog, if no argument is supplied to
the Unless you are using the HTTP 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. You cannot use relative image names as
you would in an HTML document! MiniVend has the capability of defining
an image directory (with the
ImageDir
directive) that automatically
adjusts your image path to a set base directory.
MiniVend has a powerful static page-building capability. This allows you
to pre-build catalog pages that don't contain dynamic elements (such
as order/shopping basket status) into HTML, then automatically point
the browser to those pages when appropriate. This reduces the number
of pages that MiniVend must parse in real time, and can increase server
capacity by orders of magnitude. See
STATIC PAGE BUILDING
.
If you plan to use more than one host name within the same domain for
naming purposes (perhaps a secure server and non-secure server) then
you can set the domain with the
CookieDomain
directive. This must
contain at least two periods (.) as per the cookie specification, and
you cannot set a domain that your server is not located within.
When a tag is separated by an underscore, as in item_list, a dash
is just as appropriate (i.e.
Insert a hyperlink to the specified catalog page pg. For
example, [page shirts] will expand into <
a href=``http://machine.company.com/cgi-bin/vlink/shirts?WehUkATn;;1''>. The
catalog page displayed will come from ``shirts.html'' in the
pages directory.
The additional argument will be passed to MiniVend and placed in
the {arg} session parameter. This allows programming of a conditional
page display based on where the link came from. The argument is then
available with the tag [data session arg], or the embedded Perl session
variable $Safe{'session'}->{arg}. If you set the catalog configuration
option
NewEscape
, then spaces and some other characters will be escaped
with the %NN HTTP-style notation and unescaped when the argument is read
back into the session.
A bit of magic occurs if MiniVend has built a static page for the
target page. Instead of generating a normal MiniVend-parsed page
reference, a static page reference will be inserted if the user has
accepted and sent back a cookie with the session ID.
Like the areatarget element, except it will never yield
a frame target.
The optional
arg
is used just as in the page tag.
TIP: A small efficiency boost in large pages is to just use the </A>
tag.
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 one of the ``products'' databases. The
optional argument cart/page selects the shopping cart the item will be
placed in (begin with / to use the default cart Example:
You may also specify attributes like size or color at time of order,
and may batch select whole groups of items. Read further to see how,
or order the T-shirt from the more details page of the
simple
demo
to see how it is done.
This version of MiniVend implements the database in GDBM, DB_File, SQL,
or in-memory format. If you have DBM, large catalogs can be used without
using too much memory. The DBM files are built automatically when they
change, from the the ASCII source file. If you don't have either GDBM
or DB_File, or you set the environment variable MINIVEND_NODBM before
starting the server, an in-memory product database will be used. Catalogs
of more than, say, 1,000 items will use large amounts of memory.
Support for SQL databases is included. Form-based updates and inserts
allow user input and remote maintenance. No other database besides
MiniVend's internal one is needed -- but you may find that keeping your
database in an SQL manager makes it easier to integrate MiniVend with
other tools.
NOTE: In the following descriptions, we will use the following
terms interchangeably:
It is required that the key be the first column of an ASCII source file
for GDBM, Berkeley DB, or in-memory built-in database formats. It is also
strongly suggested that you keep that practice for SQL databases, since
MiniVend's import, export, and search facilities will work much better
with that practice.
NOTE: Microsoft Excel is a widely-used tool to maintain MiniVend databases,
but has several problems with its standard TAB-delimited export, like
encasing fields containing commas in quotes, generating extra carriage
returns embedded in records, and not including trailing blank fields.
To avoid problems, use a text-qualifier of none.
The ASCII files can have ^M (carriage return) characters if desired, but must
have a newline character at the end of the line to work -- Mac users
uploading files must use ASCII mode, not binary mode!
MiniVend sets the default ASCII delimiter scheme with the
Delimiter
directive, which can have one of three settings, TAB, PIPE, or CSV.
IMPORTANT NOTE: The items must be separated by a single delimiter.
The items are lined up for your reading convenience.
The
Delimiter
directive sets the default scheme, and should be set
to one of those three values. TAB is the default scheme.
IMPORTANT NOTE: Field names are usually case-sensitive. Unless
you are consistent in the names, you will have problems. All lower
or all upper case names are recommended.
MiniVend uses one mandatory database, the products database. It is by
default identified as
products
and the ASCII source is kept in the
file
products.asc
in the products directory. This file is also the
default file for searching with the
THE SEARCH ENGINE
.
MiniVend also has a number of standard but optional databases, some
of which are in fixed special formats:
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, and must be
unique. Product codes can contain the characters A-Za-z0-9, along with
hyphen ( The words should be separated by one of the approved delimiting schemes
(TAB, PIPE, or CSV, set with the
Delimiter
directive), and are
case-sensitive. If you play with the case of the ``description'' or ``price''
field, you will have to appropriately set the
PriceField
and
DescriptionField
directives.
NOTE: CSV is not recommended as the scheme for the products database.
It is much slower than TAB- or PIPE-delimited, and dramatically
reduces search engine functionality -- no field-specific searches are
possible. Don't use it unless you know exactly what you are doing --
you will be sorry if you do. Using CSV for any small database that
will not be searched is fine.
The databases are specified in
Database
directives, as:
That specifies a type 4 database, the ASCII version of which is located in the
file arbitrary.csv, and the identifier it will be accessed under in MiniVend is
``Arbitrary''. The DBM file, if any, will be created in the same directory if
the ASCII file is newer, or if the DBM file does not exist. The files will be
created as arbitrary.db or arbitrary.gdbm, depending on DBM type.
The
identifier
is case sensitive, and can only contain characters
in the class [A-Za-z0-9_]. Fields are accessed with the
[item_data
identifier
field] or [data
identifier
field key] elements.
In addition to the database, the session files will be kept in the
default format, and are affected by the actions below.
The order of preference is:
Installing GDBM_File requires rebuilding Perl after obtaining the
GNU GDBM package, and is beyond the scope of this forum. Linux will
typically have this by default -- most other operating systems will
need to specifically build this in.
Installing DB_File requires rebuilding Perl after obtaining the
Berkeley DB package, and is beyond the scope of this document. BSDI,
FreeBSD, and Linux will typically have it by default -- most other
operating systems will need to specifically build this in.
If you wish to use DB_File even though you have GDBM_File in your
Perl, you must set the environment variable MINIVEND_DBFILE to
a true (non-zero, non-blank) value:
Then re-start the server.
If you wish to use this despite the presence of GDBM_File or DB_File,
set the environment variable MINIVEND_NODBM as above, then re-start
the server.
You probably should restrict the field names to the same set of characters
as database identifiers -- this will prevent conflict with external database
programs, noticeably SQL databases which use the period (.) as a table.field
separator.
NOTE: CONTINUE applies to all types except CSV.
DITTO is invoked when the key field is blank -- it adds the contents of
following fields to the one above, separated by a newline character. This
allows additional text to be added to a field beyond the 255 characters
available with most spreadsheets and flat-file databaseses.
Example in catalog.cfg:
Products.asc file:
The description for product 00-0011 will contain the contents of the
description
field on both lines, separated by a newline.
NOTE: Fields are separated by tabs, formatted for reading convenience.
This will work for multiple fields in the same record. If the field
contains any non-empty value, it will be appended.
It is beyond the scope of this document to describe SQL, mSQL,
or DBI/DBD, and we will not attempt to. Sufficient familiarity is assumed.
In most cases, MiniVend cannot perform administrative functions like
creating a database or setting access permissions. This must be done
with the tools provided with your SQL distribution. But if given a
blank database and the permission to read and write it, MiniVend can
import ASCII files and bootstrap you from there.
The configuration of the DBI database is done by setting attributes in
additional
Database
directives after the initial defining line as
described above. For example, the following defines the database arbitrary
as a DBI database, sets the data source (DSN) to an appropriate value for an
mSQL database named
As a shorthand method, you can instead include the DSN as the type:
Supported configuration attributes include (but are not limited to):
where mSQL selects the driver (case IS important), This is the same as the DBI_DSN environment variable -- if you don't set
the DSN parameter, then the value of DBI_DSN will be used to
try and find the proper database to connect to.
The supported list as of release of MiniVend 3.02 is:
Issue the shell command
You must have mySQL, DBI, and DBD::mysql completely installed and
tested, and have created the database To change to ODBC, the only changes required might
be:
The DSN setting is specific to your ODBC setup. The ChopBlanks setting takes
care of the space-padding in Solid and some other databases -- it is not
specific to ODBC. Once again, DBI, DBD::ODBC, and the and appropriate ODBC
driver must be installed and tested.
For any of these, you may pass arguments with the [arg]argument[/arg]
quoting method, which substitutes the contained value for successive values
of
NOTE: The 'EOF' string terminator must START the line, and not
have trailing characters. DOS users, beware of carriage returns!
The values entered by the user are escaped, which prevents errors if
quote characters have slipped into their entry.
It uses the same tags as in the [loop_list], except prefixed
with
You can set this as many times as desired if it will not fit on
the line nicely.
To create an index automatically, you can append information when
the value is in quotes:
The field delimiter to use is TAB by default, but can be changed
with the Database DELIMITER directive:
If you wish to create other secondary keys to speed sorts and
searches, you can either use MiniVend tags in an admin menu
page
or use external database tools. Careful! Not all SQL databases use
the same index commands. For example, with MySQL you would do instead:
If you wish to use an existing SQL database instead of importing, set the
NoImport
directive in catalog.cfg to include any database identifiers you
never wish to import:
WARNING: If MiniVend has write permission on the products database,
you must be careful to set the
NoImport
directive or create the
proper .sql file. If that is not done, and the database source file
is changed, the SQL database could be overwritten. In any case,
always back up your database before enabling it for use by MiniVend.
Perhaps a better method is to define the same sort of tags in an
OrderProfile
, and then use forms and buttons to access the
profile.
There is 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).
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.
To use the new more regular syntax by default, set the
NewTags
directive to In most cases, tags specified in the old fashion will work the same
in the new syntax. The only time you will need to modify them is when
there is some ambiguity as to which parameter is which, or when you need
to use the output of a tag as the attribute parameter for another tag.
With some exceptions ([if ....] [/if], [include] and [buttonbar ..] among
them) the output of a tag will not be re-interpreted for MiniVend tag
constructs. All tags accept the INTERPOLATE=1 tag modifier, which causes
the interpretation to take place. It is frequent that you will not
want to interpret the contents of a [set variable] TAGS [/set] pair,
as that might contain tags which should only be upon evaluating an
order profile, search profile, or mv_click operation. If you wish
to perform the evaluation at the time a variable is set, you would use
[set name=variable interpolate=1] TAGS [/set].
To use the new syntax only on a particular page, place one If you have regions of the page which work under the old syntax,
you can surround them with [compat] [/compat] tag pair. This will
evaluate that region only according to the old syntax.
NOTE WHEN USING OLD SYNTAX: 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:
The following are equivalent for attribute names:
Returns the value of the field in any of the arbitrary databases,
or from the variable namespaces. If the optional
value
is supplied,
the database value will be changed to it -- no ] characters may be
present in the value unless using the new tag style. If the option
increment* is present, the field will be atomically incremented with
the value in
value
.
If a DBM-based database is to be modified, it must be flagged writable
on the page calling the write tag. Use [tag flag write]products[/tag]
to mark the
products
database writable, for example.
In addition, the
Databases will hide variables, so don't name a database ``session'',
``scratch'', or any of the other reserved names or you won't be able
to use the [data ...] tag to read them. Case is sensitive, so in
a pinch you could call the database ``Session'', but it would be better
not to.
Expands into the value of the field name for the product
identified by
code
as found by searching the products database.
It will return the first entry found in the series of Product Files.
the products database. If you want to constrain it to a particular
database, use the [data base name code] tag.
Many things can be controlled with scratch variables, notable search and
order processing, the mv_click multiple variable setting facility, and
key MiniVend conditions like whether an item will be ordered on a separate
line.
There are two tags which are used to access the space, [set name]value[/set]
and [scratch name].
Sets a scratchpad variable to
value
.
Most of 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.
You can set an order profile with:
A search profile would be set with:
Both can be sorted with [sort table:field:mod -start +number] modifiers.
See
SORTING
.
Returns a string consisting of the LIST, repeated for every item in a
comma-separated or space-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.
Loop lists can be nested reliably in MiniVend 3.06 by using the
with=``tag'' parameter. New syntax:
An example in the old syntax:
All loop items in the inner loop-a loop need to have the
If this is contained in your
If this is contained in your
The
You can do some Perl-style regular expressions:
While the new tag syntax works for Oops! This will not work with the new parser. You must do instead
or
The latter has the advantage of working with any tag:
If you wish to do AND and OR operations, you will have to use
There are many test targets available:
This example is a bit contrived, as the same thing could be
accomplished with [if value country =~ /u\.?s\.?a?/i], but
you will run into many situations where it is useful.
This will work for
Variable
values:
Key matching is case-insensitive.
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:
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.
More complex tests are best done with
Additional conditions for test, applied if the initial
Same thing, except to the file products/new_products.txt:
Same thing, except the export is done with a PIPE delimiter:
The file is relative to the catalog directory, and only may be
an absolute path name if
NoAbsolute
is set to
The following enables writes on the
products
and
SQL databases are always writable if allowed by the SQL database itself --
in-memory databases will never be written.
The [tag flag build][/tag] combination forces static build of a page, even
if dynamic elements are contained. Similarly, the [tag flag cache][/tag]
forces search or page caching (not usually wise).
The file is relative to the catalog directory, and only may be
an absolute path name if
NoAbsolute
is set to
will return
When used in concert with [tag mime boundary], [tag mime header], and
[tag mime id], allows MIME attachments to be included -- typically with
PGP-encrypted credit card numbers. See the demo page ord/receipt.html
for an example.
Where it is useful is in adding long strings that would otherwise
be difficult to encode, like
instead of:
To define a tag that is catalog-specific, place UserTag directives in
your catalog.cfg file. For server-wide tags, define them in minivend.cfg.
Catalog-specific tags take precedence if both are defined. The directive
takes the form:
where The user tags can either be based on Perl subroutines or just be
aliases for existing tags. Some quick examples are below.
An alias:
This will change [product_name 99-102] into [data products title 99-102],
which will output the A simple subroutine:
A subroutine with a passed text as an argument:
The tag [caps]This text should be all upper case[/caps] will become
Here is a useful one you might wish to use:
Called with:
The properties for UserTag are are:
An Alias is the only property that does not require a
Routine
to process the tag.
The routine may use a ``here'' document for readability:
The usual here documents caveats apply.
Parameters defined with the
Order
property will be sent to the routine
first, followed by any encapsulated text (
HasEndTag
is set).
Expands into the price of the product identified by code as found in
the products database. If there is more than one products file defined,
they will be searched in order unless constrained by the optional
argument base. The optional argument quantity selects an entry
from the quantity price list.
Expands into the description of the product identified by code as found in
the products database. If there is more than one products file defined,
they will be searched in order unless constrained by the optional
argument base.
If not given one of the optional arguments, expands into the value
of the accessories database entry for the product
identified by
code
as found in the products database.
If passed any of the optional arguments, initiates special processing
of item attributes based on entries in the product database.
When called with an attribute, the database is consulted and looks for
a comma-separated list of attribute options. They take the form:
The label text is optional -- if none is given, the name will
be used.
If an asterisk is the last character of the label text, the item is
the default selection. If no default is specified, the first will be
the default. An example:
This will search the product database for a field named ``color''. If
an entry ``beige=Almond, gold=Harvest Gold, White*, green=Avocado'' is found,
a select box like this will be built:
In combination with the mv_order_item and mv_order_quantity variables
this can be used to allow entry of an attribute at time of order.
Inserts the contents of the named file. The file should normally
be relative to the catalog directory -- file names beginning with
/ or .. are only allowed if the MiniVend server administrator
has disabled
NoAbsolute
.
NOTE: New to MiniVend 3.04.
Same as
[file name]
except interpolates for all MiniVend tags
and variables.
Selects from the predefined color schemes and/or backgrounds, and
just becomes a <BODY> tag if none are defined. See
Controlling Page Appearance.
Selects from the predefined buttonbars, and is stripped if it
doesn't exist. See Controlling Page Appearance.
Selects from the predefined rotating banner messages, and is stripped if
none exist. The optional
* marks an optional parameter
Places an iterative list of the items in the specified shopping cart,
the main cart by default. See
Item Lists
for a description.
The text description of mode -- the default is the
shipping mode currently selected.
The shipping cost of the items in the basket via
will display:
TIP: The [calc] tag is really the same as the [perl] tag, except
that it doesn't accept arguments, is more efficient to parse, and
is interpolated at a higher precedence.
will display:
Uses the
Locale
,
PriceDivide
, and
PriceCommas
settings as
appropriate, and can contain a [calc] region. If Locale is set to
the number 1.500,00 will be displayed.
Sets the name of the current shopping cart for display of shipping, price,
total, subtotal, and nitems tags. If you wish to use a different price
for the cart, all of the above except [shipping] will reflect the normal
price field. You must emulate those operations with embedded Perl or the
[item-list], [calc], and [currency] tags, or use the
PriceAdjustment
feature to set it.
Formats text in tables. Intended for use in emailed 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.
The parameters are:
If this is contained in your
If this is contained in your
(new syntax [perl arg=``arguments''* interpolate=1*])
Using MiniVend variables with embedded Perl capability is not recommended
unless you are thoroughly familiar with Perl 5 references. You can insert
Minivend tags inside the Perl code, though when using the new syntax,
you will need to pass an INTERPOLATE=1 parameter to have tags inside
[perl] and [/perl] interpreted. (In the old syntax, most tags are evaluated
before [perl], though there are exceptions.)
More often you will want to use the tag access routine &safe_tag, which
takes the tag name and any arguments as parameters. This has the advantage
of only performing the operation when the code is executed. (A few tags can't
be used with safe_tag, notably ones accessing a database that has not
previously been accessed on the page.)
Examples:
This allows you to pass user-space variables for most needed
operations. You can pass whole lists of items with constructs
like:
Even easier is the definition of a subroutine:
(The The arguments that can be passed are any to all of:
Careful with this -- you can lose the items on order with improper
code, though syntax errors will be caught before the code is run.
IMPORTANT NOTE: Global subroutines are not subject to the stringent
security checking of the Safe module, so almost anything goes
there. The subroutine will be able to modify any variable in MiniVend,
and will be able to write to read and write any file that the MiniVend
daemon has permission to write. Though this gives great power, it should
be used with caution. Careful! They are defined in the main minivend.cfg
file, so should be safe from individual users in a multi-catalog system.
Global subroutines are defined in
minivend.cfg
with the
GlobalSub
directive, or in user catalogs which have been
enabled via
AllowGlobal
. Global subroutines are much faster
than the others as they are precompiled. (Faster still are UserTag
definitions.)
Catalog subroutines are defined in
catalog.cfg
, with
the
Sub
directive. They are subject to the stringent Safe.pm
security restrictions that are controlled by
SafeUntrap
. If you
wish to have default arguments supplied to them, use the
SubArgs
directive.
Scratch subroutines are defined in the pages, and are also subject
to Safe.pm checking. See the beginning of this section for an
example of a subroutine definition. There is no ``sub name { }'' that
surrounds it -- the subroutine is named from the name of the
scratch variable.
The result of the tag will be the result of the last expression
evaluated, just as in a subroutine. If there is a syntax error
or other problem with the code, there will be no output.
Here is a simple one which does the equivalent of the classic
hello.pl program:
Of course you wouldn't need to set the variable -- it is just there
to show the capability.
To echo the user's browser, but within some HTML tags:
To show the user their name, and the current time:
Because the tags are the same, an [item_list] cannot be used on
an on-the-fly page. The [loop item, item] tag is still usable.
If the directive
PageSelectField
is set to a valid product database
field which 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.
Active tags in their order of interpolation:
NOTE: This is ignored if using the new syntax.
NOTE: This is ignored if using the new syntax.
NOTE: This is ignored if using the new syntax.
NOTE: The distributed demo does not use these default values.
The names of these pages can be set with the
SpecialPage
directive. The standard pages and their default locations:
To check a page for validity, set the global directive CheckHTML
to the name of the program (don't do any output redirection). A good
choice is the freely available program weblint -- it would be
set in
minivend.cfg
with:
Of course you must restart the server for it to be recognized.
The full path to the program should be used -- if you have trouble,
check it from the command line (as you should with all external programs
called by MiniVend).
Insert [tag flag checkhtml][/tag] at the top or bottom
of pages you want to check, and the output of your checker
should be appended to the browser output as a comment, visible
if you view the page or frame source.
To do this only at times, use a
Variable
setting:
and place __CHECK_HTML__ in your pages. You can then set
the Variable to the empty string if you wish to disable it.
These special fields all begin with mv_, and include:
(O = order, S = search, C = control, A = all, X in scratch space)
Mapping of actions in the ActionMap directive means that the
value
of
the submit button is scanned to determine the action. To map the string
``Place Order'' to the action submit, you would put in the
catalog.cfg
file:
And on the form you would make a submit button:
When the button is clicked by the user, the
submit
action will
be performed.
To set a default action for a form, set the variable
mv_doit
as
a hidden variable:
When any other submit button (for a meaningless variable, the MiniVend
demos use mv_submit) is pressed, the mv_todo value will not be
found, so the
refresh
action defined in
mv_doit
will be used.
The defined actions are:
If there is an order profile defined, the form will be checked against
the definition in the order profile and submitted if the pragma &final
is set to yes. If &final is set to no (the default), and the check
succeeds, the user will be routed to the MiniVend page defined in mv_successpage,
mv_nextpage, or mv_orderpage. Finally, if the check fails, the user will be
routed to mv_failpage, mv_nextpage, or mv_orderpage in that order.
The special variable mv_click sets variables just as if they
were put in on the form. It is controlled by a single button,
as in:
When the user clicks the submit button, all three variables will take
on the values defined in the ``Search by Category'' scratch variable. You
can set the scratch variable on the same form as the button is on -- in
fact that is recommended for clarity.
The variable will not be carried from form to form, it must be set
on the form being submitted.
The special variable mv_check sets variables for the form actions
checkout, control, refresh, return, search,
and
submit
.
This function operates after all of the values are set from the form,
including the ones set by mv_click, and can be used to condition
input to search routines or orders.
The variable sets can contain and be generated by most MiniVend tags --
the profile is interpolated for MiniVend tags before being used. Careful
of interpolation order, and don't use the [post] tag -- it will not work.
Embedded Perl will work, and is recommended for most conditional
operations within the profile.
Any setting of variables already containing a value will overwrite
the variable, so to build sets of fields (as in mv_search_field
and mv_return_fields) you must use comma separation or place the
null character with a Here is a small example which will set the value of
mv_nextpage
to
route the user to a special page if their search inputs are invalid:
It takes arguments based on the special form variables mv_argN, where
N is an integer that corresponds to the argument number (starting
at zero). Arguments can be of four types:
An example would be a password-protected message. Here is a form:
And a subroutine:
And a results page secret.html (remember, set the destination for the
return
action with
mv_nextpage
):
This will output CHECKED if the variable
This will output SELECTED if the variable Here is a drop-down menu that remembers an item-modifier
color selection:
Here is the same thing, but for a shopping-basket color
selection
To submit a form to the regular non-secure server, just omit the
The stackable mv_order_item variable with be decoded with multiple
values, causing the order of any items that are checked.
To place a ``delete'' checkbox on your shopping basket display:
In this case, first instance of the variable name set by [quantity-name]
will be used as the order quantity, deleting the item from the form.
Of course, not all variables are stackable. Check the documentation for
which ones can be stacked -- or experiment on your own.
NOTE: If you are updating a non-SQL database, you will have to perform a
[tag export database][/tag] operation if you wish to update the ASCII
source file with the results of your update.
You of course may insert or update records in any SQL database with the
[sql set] tag, but you may also do form-based updates or inserts.
In an update form, four special MiniVend variables are used to select
the database parameters:
The variables in the form do not update the user's session values,
so they can correspond to database field names without fear of corrupting
the user session.
Examples of search forms and result pages are included in the supplied
demos.
Two search engine interfaces are provided, and five 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
.
There is a range-based search, used in combination with
one of the above. And finally, there is an SQL search which
translates the MiniVend search interface to SQL queries.
The default, a text based search, sequentially scans the lines in
the target file. By default it returns the first field (delineated by
the standard
Delimiter
), for every line matching the search
specification. This corresponds to the product code, which is then
used to key specific accesses to the database.
The text-based search is capable of sophisticated field-specific
searches with fully-independent case-sensitivity, substring, and negated
matching. (There is not yet a full search language except for SQL queries,
so AND/OR matching is not supported across multiple fields. Stay tuned
for this in MiniVend 3.1 or later.)
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:
In the hot-linked URL search:
If you want to let the user decide on the search parameters, you can
use checkboxes or radiobox fields to set the fields:
Fields can be stacked -- if more than one is checked, all checked fields
will be searched. (This doesn't work for Glimpse in the return_file_name
mode, though).
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/POSIX 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 you are intending to search for numbers, add the -n option to
the Glimpse command line.
(A large catalog is one of more than several thousand items -- smaller
ones have acceptable speed in any of the search modes.)
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.
The search must be done on a dictionary-ordered pre-built index,
production of which is left as an exercise for the user.
Hint: the field to search is the first field in the file, then the
product code should be in the second field, delimited by
Delimiter
.
You will also have to set mv_return_fields=1 to return the product code
in the search.
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
10,000 items in size, given a fast machine. Using it in combination
with another search technique (in the same query) will yield faster search
returns.
The following variables are in effect for SQL searches:
Their two-letter abbreviations are in effect (as below), so you may
easily do a one-click SQL search.
If you are using SQL for the products database, and the table
you are searching is in the same SQL database, you don't need to
specify the table other than in the query. If you are not using
SQL for products, or it resides in a different database, then
you must specify a MiniVend database identifier located in the
same SQL database as the table you are querying. Use the
mv_search_file variable:
Once you have selected the database, you may query any table that
is located within the same SQL data source.
There are two modes for SQL search:
When the user clicks the button, the query will be done and the
results returned using the default search return page. You may
set the return page with mv_search_page as in the other searches,
but most other variables have no effect.
Another exception is the mv_searchspec variable, which when set with
either user-entered text or by another method, will be inserted
in place of a single question mark in the query:
When the user selects one of the search categories, the value of
mv_searchspec will be substituted for the question mark, and quoted
if the field is not numeric in nature.
The spaces necessary in SQL queries make hand generation of one-click
URLs pretty tedious. You may generate one-click searches easily using
[tag sql] SQL [/tag]. For example, the query
generates HTML that starts out:
The actual URL is a bit too long to show. The same result would be generated
by:
The first example may be more intuitive for some; it is marginally faster.
For example, if you don't specify a field or fields in the table to
search, MiniVend will search all fields as is the default for the
text and Glimpse searches. This can be quite inefficient, as the
resulting query looks something like:
You get the picture. Each field is checked in turn. Much better is
to set the mv_search_field variable to the field(s) you wish searched,
skipping the ones that make no sense:
This generates a much more limited query.
If there are more mv_searchspec values than fields, then only the
first search field is used. The below query will fail, as the
second and subsequent search fields are ignored.
If there are more mv_search_field values than mv_searchspec values,
then only the first search specification will be used:
The string 'Dali' will never be looked for.
If the number of search fields and search specs are the same, a coordinated
AND search is done, and only rows matching all searchspecs will be
found.
The mv_range_look facility is in use for the complex form query as well,
and operates in exactly the same way.
The following search will find all Van Gogh paintings that are between
$1,000,000 and $20,000,000, providing the price field is a numeric data
type. It also illustrates the use of some other MiniVend variables that
are usable for SQL searches.
It will generate the query:
Here is the same thing from a home page (assuming /cgi-bin/vlink is
the CGI path for MiniVend's vlink):
The two-letter abbreviations are mapped with these letters:
They can be treated just the same as form variables on the
page, except that they can't contain spaces, '/' in a file
name, or quote marks. These characters can be used
in URL hex encoding, i.e. %20 is a space, %2F is a
To replace a / (slash) in a file name (for the sp, bd, or fi parameter)
you must use the shorthand of ::, i.e. sp=results::standard. (This may
not work for some browsers, so you should probably either put the page
in the main pages directory or define the page in a search profile.)
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:
You may specify a search inside a page with the [search se=searchstring]
tag. The parameters are the same as the the one-click search, and the
output is always a newline-separated list of the return objects -- by
default a series of item codes. The output of a [search ...] tag should
almost always be passed to a [loop LIST] [/loop] tag pair for iteration.
Here is an example which will search for and show a series of products
that match the categories
The advantage of the in-page search is that you can embed searches within
searches, and you can have straight unchanging links from static HTML pages.
These correspond to the MiniVend search variables that can
be set on a form. You can set it right on the page that contains
the search.
Then in the search form, set a variable with the name of the profile:
In a one-click search, you use the
You can also place them in a file. Define the file name in the
SearchProfile
directive. (You must reconfig the catalog for MiniVend
to read it.) The profile is named by placing a name following a __NAME__
pragma:
The __NAME__ must begin the line, and be followed by whitespace
and then the name.
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.
If you want to place multiple search profiles in the same file,
separate them with __END__, which must be on a line by itself.
NOTE: The following definitions frequently refer to
field name
and column and column number -- all are the references to the
columns of a searched text file as separated by delimiter characters.
The field names can be specified in several ways.
If stacked to match the mv_search_field and mv_searchspec variables,
and
mv_coordinate
is set, it will operate only for the corresponding
field.
Case sensitivity, substring matching, and negation all work on a field-by
field basis according to the following:
If a search specification is blank, it will be removed and all
case-sensitivity/negation/substring options will be adjusted accordingly.
The order of this and the
mv_dict_end
variable is significant -- each
will overwrite the other.
Defines the field names for the file being searched. This guarantees
that they will be available, and prevents a disk access if using named
fields on a search file (that is not the product database ASCII source,
where field names are already known). This must be exactly correct,
or it will result in anomalous search operation. Usually passed in a
hidden field or search profile as a comma-separated list.
NOTE: You should use this on the product database only if you
plan on both pre-sorting with
mv_sort_field
and then post-sorting
with [sort]field:opt[/sort].
If stacked to match the mv_search_field and mv_searchspec variables,
and mv_coordinate is set, it will operate only for the corresponding
field.
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 Glimpse search, follows the Glimpse wildcard-based file name
matching scheme. Use with caution and a liberal dose of the Glimpse
man page.
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 sql, formulates an SQL select statement to return the
search list.
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.
The file field(s) the search is to be sorted on, specified in one of two
ways. If the file(s) to be searched have a header line (the first line)
that contains
Delimiter
-separated field names, it can be specified
by field name. If can also be specified by column number (the code or key
is specified with a value of 0, for both types). These can be stacked,
if coming from a form, or placed in a single specification separated
by commas.
NOTE FOR ADVANCED USERS: If specifying a sort for the product database,
mv_field_names
must be specified if you will be doing a fieldname-addressed
post-sort.
The way that each field should be sorted. The flags are
If stacked to match the mv_search_field and mv_searchspec variables,
and mv_coordinate is set, it will operate only for the corresponding
field.
.
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.
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.
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.
Placed inside the search list. Causes sorting of the search return
based on the passed options. The fields that are there
to sort are set by
mv_return_fields
.
The field options passed in either numeric or field name form. If
they are field numbers, they are numbered as sent to the search list
in the order specified by
mv_return_fields
,
starting from 0 and proceeding upwards. If column names, they are
as found in the first record of the searched file (by default the
ASCII source for the product database), except for the key or first field.
followed by a
required
colon (:) and the options, if any.
Accepts none, any, or combinations of the flags:
The <options> are a field number and an optional flag or flags, in a
similar fashion to the Unix sort command, and are interpolated for form
values before being used. As an example, if you set up the following
fields on your search form:
This would combine with the following search result page fragment
to sort by either title or artist.
[search-list]
[sort]
[value the_sort_field]:[value the_sort_option]
[/sort]
PERFORMANCE TIP: on heavily trafficked systems, it will pay to use only
column numbers rather than named fields, as it reduces processing and may
obviate an access to the searched file to find the field names.
Along with the companion
[/on_change marker]
, surrounds a region which
should only be output when a field (or other repeating value) changes its
value. This allows indented lists similar to database reports to be easily
formatted. The repeating value must be a tag interpolated in the search
process, such as Of course, this will only work as you expect when the search results
are properly sorted.
The Here is a simple example for a search list that has a field
category
and
The above should put out a table that only shows the category and
subcategory once, while showing the name for every product. (The
Use in conjunction with the [more] element to place pointers to
additional pages of matches.
If the optional arguments In addition, if As an example, if you use [more-list next.gif prev.gif page_num.cgi], the
following will be the anchors:
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 See the
To change this, set the
scratch
variable mv_put_session on the page
in question:
This setting is persistent, so it is recommended that you
do it once at the beginning of the user session if you wish it to be the
default. If you don't want it to be the default, reset it to the
empty value (or zero) on another page:
If your catalog frequently specifies category searches in a
large catalog, speed of search return can be increased by a
large factor.
You needn't do more than just enable the cache for one-click
searches. To make them operate on a form-based search, specify
the form variable names, separated by a spaces and/or a comma,
that will generate a unique cache key. Example:
If you have the MD5 module installed on Perl, it will be used
to generate the cache keys. This will guarantee a unique
cache ID.
If you don't have MD5 installed, a 32-bit checksum will be used to create
the cache key. It is conceivable, but unlikely, that two separate
searches could generate the same 32-bit checksum and return the same
cached search.
IMPORTANT NOTE: The search cache is only invalidated by a
catalog reconfiguration. If you change your product database
or any other files you search, you should reconfigure or the
search returns may be wrong.
Search caching is disabled on a client-by-client basis if the
client browser does not have cookie capability, for the generated
session numbers would be incorrect otherwise.
It is not strictly necessary to display an order basket when
an item is ordered. If you specify a different page to be
displayed that is fine, but most customers will be confused if
you don't give them an indication that the order operation has
succeeded.
Any order basket is an HTML
If coming from a search results or on-the-fly page, you may use the generated
[item-code] thusly:
Bear in mind that if you have not reached the page via a search or
on-the-fly operation, [item-code] means nothing and will cause an error.
The default quantity is one. An initial quantity may be set by the user
by adding an mv_order_quantity variable:
You can order multiple items by stacking the variables:
Initial size or color may be set as well, provided
UseModifier
is
set up properly:
If the order is coming from a generated flypage, loop list, or search
results page, you can get a canned select box from the
If you wish to stack more than one master item, then you must define
mv_order_group for all items, with either a 1 value (master) or 0 value
(sub-item). A master owns all subsequent sub-items until the next master
is defined.
When the master item NOTE: You cannot use checkboxes for this type of thing, for they
do not pass a value when unchecked. Use radio groups or select/drop-down
buttons.
The attributes
The name of the page to display can be configured in several
ways:
the order will be placed in the cart named layaway. However, by default
you won't see what you want! That is because the default shopping basket
page won't display the cart you are thinking it will -- it will show
the main cart. So copy the default cart (pages/ord/basket.html in the demos)
to a new file, insert a [cart layaway] tag, and submit it as a MiniVend
page name addendum to the cart name:
Now the contents of the layaway cart will be displayed. If you need
to display a different price, you will have to emulate the [subtotal],
[item-price], [item-subtotal], etc. fields with [item-list], [calc],
and [currency] tags. This snippet emulates the item-price tag for
a different price field layaway-price:
An item subtotal:
A cart subtotal, using the item-list tag:
The zero is needed because of the trailing plus sign left by the
iterative [item-list] tag.
Even sales tax can be emulated if you use something like a
[data salestax [value state]] tag, and do some similar calculation.
That is left as an exercise for the user.
Shipping and the [nitems] tag will still work properly with a
different price.
You can also order items from a form, using the mv_order_item,
mv_cartname
, and optional mv_order_quantity variables.
Specifications take the form of an order page variable (like name
or address), followed by an equals sign and one of five check types:
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.
Any input field from the order page can be included using the dollar
sign notation.
To prevent a value from being included in the order report, just add it
to the
ReportIgnore
configuration directive.
MiniVend defines some values for use in the search form -- they begin
with
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>.
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.
Choose a name for this input field such as ``email'' for an email
address. Set the name attribute to the name you have chosen.
The value attribute specifies the default value to give the field when
the page is displayed. Because the customer may enter information on
the order page, return to browsing, and come back to the order page,
you want the default value to be what was entered the first time. This
is done with the [value] element, which returns the last value of an
input field. Thus,
will evaluate to the name entered on the previous order screen, such
as:
which will be displayed by the browser.
The size attributes specifies how many characters wide the input field
should be on the browser. You do not need to set this to fit the
longest possible value since the browser will scroll the field, but
you should set it large enough to be comfortable for the customer.
For speed, MiniVend builds the code that is used to determine a product's
price at catalog configuration time. If you choose to change a directive
that affects product pricing you must reconfigure the catalog.
There are several ways that MiniVend can modify the price of a product during
normal catalog operation. Several of them require that the
pricing.asc
file be present, and that you define a pricing database. You do that by
placing the following directive in
catalog.cfg
:
Configurable directives and tags with regard to pricing:
To enable the automatic modifier handling of MiniVend 3.0, you would
define a size field in products.asc:
You would place the proper tag within your [item-list] on the shopping-basket
or order page:
In the pricing.asc database source, you would need:
As of MiniVend 3.06, if you want to assign a price based on the option,
precede the number with an equals sign:
IMPORTANT NOTE: Price adjustments occur AFTER quantity price breaks, so
the above would negate anything set with the
PriceBreaks
directive/option.
The configuration file directive
UseModifier
is used to set
the name of the modifier or modifiers. For example
will attach both a size and color attribute to each item code that
is order
IMPORTANT NOTE: You may not use the following names for attributes:
As of MiniVend 2.02, setting the mv_separate_items or global
directive
SeparateItems
places each ordered item on a separate
line, simplifying attribute handling.
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.
You cannot define a modifier name of
code
or quantity, as they
are already used. You must be sure that no fields in your forms
have digits appended to their names if the variable is the same name
as the attribute name you select, as the [modifier-name size] variables
will be placed in the user session as the form variables size0, size1,
size2, etc.
You can use the [loop item,item,item] list to reference multiple display
or selection fields for modifiers (in MiniVend 3.0, you can have it
automatically generated --see below). The modifier value can then be
used to select data from an arbitrary database for attribute selection
and display.
Below is a fragment from a shopping basket display form which
shows a selectable size with ``sticky'' setting. Note that this
would always be contained within the [item_list] [/item-list]
pair.
It could just as easily be done with a radio button group combined
with the [checked ...] tag.
MiniVend 3.0 will automatically generate the above select box
when the [accessories size <code>] or [item-accessories size]
tags are called. They have the syntax:
When called with an attribute, the database is consulted and looks for
a comma-separated list of attribute options. They take the form:
The label text is optional -- if none is given, the name will
be used.
If an asterisk is the last character of the label text, the item is
the default selection. If no default is specified, the first will be
the default. An example:
This will search the product database for a field named ``color''. If
an entry ``beige=Almond, gold=Harvest Gold, White*, green=Avocado'' is found,
a select box like this will be built:
In combination with the mv_order_item and mv_order_quantity variables
this can be used to allow entry of an attribute at time of order.
If used in an item list, and the user has changed the value, the generated
select box will automatically retain the current value the user has selected.
The value can then be displayed with [item-modifier size] on the
order report, order receipt, or any other page containing an
[item_list].
The discounts are specified via a formula. The formula is scanned for
the variables $q and $s, which are substituted for with the item
quantity and subtotal respectively. In the case of the item and
all items discount, the formula must evaluate to a new subtotal for all
items of that code that are ordered. The discount for the entire
order is applied to the entire order, and would normally be a monetary
amount to subtract or a flat percentage discount.
Discounts are applied to the effective price of the product, including
any quantity discounts.
To apply a straight 20% discount to all items:
To take 25% off of only item 00-342:
To subtract $5.00 from the customer's order:
Perl code can be used to apply the discounts. Here is an example of a
discount for item code 00-343 which prices the second one ordered at
1 cent:
If you want to display the discount amount, use the [calc] capability.
This example calculates the amount of the discount for all items in
the current shopping cart:
This being done, MiniVend assumes the presence of a file
salestax.asc
,
which contains a database with the percentages. Each line of
salestax.asc
should be a code (again, usually a five-digit zip or
a two letter state) followed by a tab, then a percentage. Example:
Based on the user's entry of information in the order form, MiniVend
will look up (for our example SalesTax directive) first the zip, then
the state, and apply the percentage to the SUBTOTAL of the order. The
subtotal will include any taxable items, and will also include the
shipping cost if the state/zip is included in the
TaxShipping
directive.
It will add the percentage, then make that available with the [salestax]
tag for display on the order form. If no match is found, the entry
'default' is applied -- that is normally 0, but can be anything.
If business is being done on a national basis, it is now common to have
to collect sales tax for multiple states. If you are doing so, it is possible
to subscribe to a service which issues regular updates of the sales tax
percentages -- usually by quarterly or monthly subscription. Such a
database should be easily converted to MiniVend format -- but some systems
are rather convoluted, and it will be well to check and see if the
program can export to a flat ASCII file format based on zip code.
If some items are not taxable, then you must set up a field in your
database which indicates that. You then place the name of that field
in the
NonTaxableField
directive. If the field for that item
evaluates true on a yes-no basis (i.e. is set to If your state taxes shipping, use the
TaxShipping
directive.
Utah and Nevada are known to tax shipping -- there may be others.
If you want to set a fixed tax for all orders, as might occur for VAT
in some countries, just set the
SalesTax
directive to a value like
or to do it without submitting a form:
To use CyberCash, you must first have a CyberCash Secure Merchant Payment
Server (SMPS) running on your system. It must be fully enabled, and
should be tested OK with the CyberCash test suite. This capability has
been tested to work with SMPS-2.1.x in The special mode The CCLib.pm file must be available to MiniVend -- if you cannot
install it in the main Perl library then the Minivend software
directory lib/ will suffice. If it is found at MiniVend startup,
a message will be displayed.
MiniVend only will charge CyberCash in the final phase of the order
process, i.e. at the time the receipt and order report are generated.
The full amount as shown by the [total-cost] tag will be billed --
if you need to do partial charges you will have to manage multiple
shopping carts.
The process of enabling CyberCash processing is something like this:
The order mode must be final, either by omitting an order profile
entirely or by defining an order profile that contains &final=yes.
If you must use other values, they can be redefined in catalog.cfg
with the
Variable
CYBER_REMAP like so:
or like so:
NOTE: As always when using the <<EOF (here document) capability, the
EOF must be on a line by itself, with no leading or trailing white space.
That includes carriage returns, Windows devotees. Upload in ASCII mode!
If you have defined the directive
EncryptProgram
to be something
containing the value pgp, then the
CreditCardAuto
method will be
used to encrypt the mv_credit_card_number value before it is wiped
from memory. (Errors in that process will be silently ignored.) It
will never be written to the user session, at least by MiniVend
itself, so attempts to recall it on future forms will be in vain.
If the authorization fails, the special page
failed
will be
displayed, and passed the CyberCash error message for display with
the [subject] tag. The order will not complete, i.e. the cart will
still be intact and no receipt or order report will be generated.
The error itself is always available as [data session cybercash_error].
If successful, the receipt page will be displayed, the order report
emailed, and the cart will be emptied. If you wish to display the
order-id returned from CyberCash on the receipt, it is available in
[data session cybercash_id]. If the order is successful, but is
detected as a ``success-duplicate'', [data session cybercash_error]
will contain the message returned from CyberCash.
All sort situations --
Examples, all based on the
simple
demo:
If you instead do:
The tag
Note the reversed order of the title for Van Gogh, and the presence of
the accessory item Gilded Frame at the front of the list (it has no
artist field, and as such sorts first).
Adding a slice option:
If the end value/chunk size exceeds the size of the list, only the
elements that exist will be displayed, starting from the start value.
A two level sort, that will sort products based first on their category
then on their title within the category.
To enable custom shipping, enter the default field to use in the
CustomShipping
directive:
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 CustomShipping directive only
sets the default field to be used if none is present in the
mode specification.
This will make the entry on the order form checked by default when the
user starts the order process, if it is put in the form:
To force a choice by the user, you can make mv_shipmode a required form
variable (with
RequiredFields
or in an order profile) and set
DefaultShipping
to zero.
The criteria field varies according to whether it is the first field in
the shipping file exactly matching the mode identifier. In that case, it
is called the main criterion. If it is in subsidiary shipping lines
matching the mode (with optional appended digits) then it is called a
qualifying criterion. The difference is that the main criterion returns
the basis for the calculation (i.e. weight or quantity) while the qualifying
criterion determines whether the individual line may match the conditions.
The return must be one of:
NOTE: You may use the same mode name for all lines in the same group,
but the first one will contain the main criteria.
NOTE: The columns are lined up for your reading convenience, the actual
entries should have ONE tab between fields.
If the cost returned is zero, the reason will be placed as an error
message in the session variable ship_message (available as [data session
ship_message]).
UPS weights are always rounded up if any fraction is present.
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. (As of March 1997, you
can use the standard .csv file distributed by UPS on their web site at
www.ups.com.) You specify it with the
UpsZoneFile
directive -- it is
usually named something like Second, you must obtain the cost tables from UPS (again, you can get them from
www.ups.com) and place them into a MiniVend database. That database, its
identifier specified with the first argument (upsg in the example) of the cost
specification, is consulted to determine the UPS cost for that weight and
rate schedule.
You can append a simple shipping cost qualification to a UPS lookup. If
any additional parameters are present after the five usual ones used for
UPS lookup, they will be interpreted as a Perl subroutine call. The
syntax is the same as if it was encased in the tag [perl sub] [/perl],
but the following substitutions are made prior to the call:
The example above also illustrates geographic qualification. If the value of
the form variable state on the checkout form is AK or HI, the U.S. states
Alaska and Hawaii, a $10.00 additional charge (over and above the normal 2.00
handling charge) is made. This can also be used to select on country, product
type, or any other qualification that can be encoded in the file.
NOTE: The text above appears indented, but in the
catalog.cfg
file
it must begin at the beginning of the line. Also, make sure you upload
in ASCII mode -- carriage returns are not tolerated.
It will simply return a cost of 20 if the country the user has entered is
US or USA -- and return 50 otherwise. Obviously much more complicated
routines can be defined. Read the following only if you know Perl well
and/or are not of faint heart.
You can call named subroutines with any of the methods, defined with
[set name] your_perl_code_here [/set],
Sub
, or
GlobalSub
.
If parameters are specified, separated by commas, they will be taken as
either fixed values or as database fields to be sent to the subroutine
in an anonymous hash keyed on the item code (for each item in the
*current* shopping cart).
If a database other than the products database is to be used, the database
name should be prepended with a colon ( To send fixed value to the subroutine (appended to the call reference
as an array of fixed scalar parameters), begin the parameter with a
semicolon. They will be appended globally after the hash reference.
Examples
The parameters are interpreted for MiniVend tags before being parsed.
Here is a complete example:
will call the subroutine
If the undefined value is returned by the routine, the next shipping mode
will be tried. If a non-numeric string value is returned, its value
will be placed as an error message in the session variable ship_message
(available as [data session ship_message]) and a zero cost will be returned.
If any number or the empty string is returned, it will be used as the
shipping cost (even 0).
You can specify user variables to examine for geographic offering
of shipping modes with the
CustomShipping
directive, and you can
specify which qualifications they must meet with the
Shipping
directive. Example:
This means the MiniVend will first examine the
If you wished only to process a handling charge once, you could do safely:
A non-blank/non-zero value in the database field very_heavy will then
trigger Perl code which will only set mv_handling once.
If you set AsciiBackend to a legal file name (based in VendRoot unless
it has a leading ``/''), it will save the backend fields defined in
BackendOrder
along with the item-code and quantity of items being
ordered. The fields are separated by TAB characters.
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.
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 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.
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. An external encryption program, such
as pgp(1) or des(1) can be used.
NOTE: The internal Des encryption mode is no longer supported in
MiniVend 2.02 and higher. Try PGP instead -- it is more secure and
easier to use.
To accept credit_card fields, you need to define the directive
CreditCardAuto
to yes.
EncryptProgram
also needs
to be defined with some value, one which will, with hope,
encrypt the number. PGP is now recommended above all other
encryption program. The entries should look something like:
See
CreditCardAuto
for more information on how to set the form variables.
In addition, you can create a file in any MiniVend page subdirectory
called .access. If that file is present and non-zero in size,
any pages in that directory are only available to users who have the
REMOTE_USER CGI variable set (which means they have given a user name and
password, ala normal HTTP Basic Authorization). This is a way to provide
``subscription-only'' pages that are only available to logged-in users.
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 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.
Here are the frames-specific tags:
IMPORTANT NOTE: This doesn't turn of frames in your browser! If
you let a TARGET tag escape, it will probably cause a new window
to be opened, or other types of anomalous operation.
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 The optional
arg
is used just as in the page tag.
Inserts a Vend URL in a format to provide a targeted reference for a
client-side imagemap. You set up the <AREA> tag with:
If frames are enabled, this will expand to:
If frames are not enabled, this will expand to:
The optional
arg
is used just as in the page tag.
You can use
One-click Multiple Variables
to set the target if you
wish.
The above snippet will, when placed in a MiniVend form, send the output
of a
Search
submission to the current default frame, but when
Continue Shopping is selected the output will will go to the page
browse.html
with the page routed to the top level frame for the
current browser window.
If you are setting a target with the [process_target target] tag, you
will either have to make that target none or set the
scratch
variable
mv_ignore_frame on the page at time of display. Either will prevent
conflicting window targets from being sent.
The [body n] element selects a color scheme -- numbered from 1 to 15 --
that is set by the Mv_Background, Mv_TextColor, Mv_BgColor,
Mv_LinkColor, and Mv_VlinkColor directives. Each can contain up to 15
parameters, after an opening BEGIN. Here is an example:
The above sequence set in the catalog.cfg file, defines three color
schemes, accessed with [body 1], [body 2], and [body 3] elements in
MiniVend pages. The first scheme uses the file The second scheme defines no background pattern (there is only one file
in the Mv_Background directive), but defines a background color of The third color scheme is similar to the second, except defines
white-black-blue-purple for the four colors. It is accessed with
a [body 3] element.
If there is no defined scheme for a body element (as there wouldn't be if
you put [body 4] in a page with the above schemes defined) MiniVend
simply outputs a standard <BODY> tag.
The user can also define their own colors if the Mv_customcolors
variable is set (upon a form submission). See the supplied
control.html
page for an example of how to set custom colors.
Image maps can be supplied and similarly controlled with the [buttonbar n]
series of tags. They are defined with the ButtonBars directive
in catalog.cfg, and take the form of a series of
file names in MiniVend format -- i.e., relative to the PageDir and
without a .html extension. To use the buttonbars, create a file
with an IMG directive set with the USEMAP element and an associated
client-side image map (defined with <MAP> </MAP>. The [areatarget]
or [area] tags are used to set the URLs. An example:
If the above were saved in the file PageDir/bars/artbar0.html (where PageDir
is your MiniVend pages directory), you would be able to access this
imagemap in your pages with a [buttonbar 0] tag, at least after MiniVend
read this line in the configuration file:
The above entry allows you to define three imagemaps and access them in
your pages simply as [buttonbar 0], [buttonbar 1], and [buttonbar 2]. The
advantage of this scheme is central definition of a series of button bars
with only a few tags -- if you change your page colors or mapping, you
need only change one file and the change will roll over to all of your
catalog pages. Since some installations can number in the thousands
of catalog pages, using the pre-defined buttonbars can save a lot of
editing. (Server-side includes cannot be used to achieve the same thing
with MiniVend, since they wouldn't have the proper URLs.)
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:
You can also use it to build page trees that are scannable by a search
engine spider.
As of MiniVend 3.03, to make static page building active, you must set
the
Static
directive to It is invoked when starting the MiniVend server by passing the extra parameters
Some tags which cause static building to fail are:
In addition, if a [search_list] references dynamic items, it will
also prevent a search from being cached or built statically.
Pages are also searched for static [page scan/...] searches, and
those searches are built statically if appropriate. They are placed
in the pages scan1.html on up, so don't name any of your pages scan
and then digits if you want to avoid clashing. Search builds recurse
one level down, meaning that if you have a category search that yields
more category searches, they will also be built. You can set the
recursion with
StaticDepth
-- the default is two.
A page marked as an
AdminPage
or
NoCache
will not be statically
built or cached.
If you wish a page to build statically anyway, despite the presence
of dynamic elements, you can insert Additionally if you pass a name with Pages are marked for static build in one of three ways:
The names of pages that are statically built are maintained in the file
Any pages included in the list(s) that fail due to dynamic elements
have their names placed in the file The
StaticDir
directive defines the
file path
to the root
of the page structure that will be built. If blank, it will use
the directory WARNING: Any existing files that are present may be removed
from this directory! Do not place normal pages there!
The
StaticPath
directive defines the URL path to the root
of the page structure that will be built. It is relative to
HTTP document root, and must obviously be the URL path to
StaticDir
.
Default is /, or DocumentRoot.
The
StaticSuffix
directive defines the suffix of the files that
will be built. The default is If you wish to build the catalog pages offline (recommended on servers
that are used by multiple catalogs), you can use the command:
where The definitions are maintained in the catalog.cfg file through the use
of built in POSIX support and MiniVend's
Locale
directive.
All settings are independent for each catalog and each user of that
catalog -- you can have customers accessing the same catalog in any
of an unlimited number of languages and currencies.
When accessed via the special tag [L]Value Setting[/L],
the value The L and /L must be capitalized -- this is done for speed of processing
as well as easy differentiation in text.
For longer series of strings, the configuration file recognizes:
The above sets two string substitutions. As long as this is valid Perl
syntax describing a series of settings, the text will be matched. It can
contain any arbitrary set of characters that don't contain The [L]default text[/L] is set before any other page processing. It is
equivalent to the characters ``default text'' or the appropriate Locale
translation for all intents and purposes. Minivend tags and Variable
values can be embedded.
You will need to be quite careful in editing pages with localization
information. Changing even one character of the message will change the
key value and invalidate the message for other languages. To prevent this,
you can instead use:
The key A
See the POSIX setlocale(3) man page for more information.
These will be used for formatting prices and will approximate the number
format used in most countries. To set the price format to something that
is exactly how you want it, you can use the special keys:
This is the presumably for locale The same display can be achieved with:
A common price_picture for European countries would be
IMPORTANT NOTE: The decimal point in use, set by The same setting for fr_FR above can be achieved with:
If the number of digits is greater than the # locations in the picture,
the digits will be changed to asterisks. An overflow number above would
show as
If the number of digits is greater than the # locations in the picture,
the digits will be changed to asterisks, displaying something like
The default will always be If
PriceBreaks
is enabled, then the field
The price will now be divided by
If a previous setting was made for an item based on another locale, it
will be maintained.
If you had this arbitrary database named
and this loop:
Using the default C setting for LC_COLLATE it would display:
If the proper LC_COLLATE settings for locale
You normally call configuration directives with the directive as the
first word on the line, with it's value or values following. Leading
whitespace is stripped from the value.
You may call additional files with a rudimentary #include file
statement. The directives called with includes are always appended
at the end of the main configuration file. Though order is rarely
important in the configuration files, you must define any directory
settings in the main configuration file near the top if they are to
be used to base the file calls of subsequent directives. Files are
relative to the catalog directory (or MiniVend software directory, if
in the main minivend.cfg file).
You can also use a type of ``here document'' to specify MiniVend directives,
with the usual <<MARKER syntax. No semicolon is used to terminate the
marker.
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.
The first is the name of the catalog -- it will be referred
to as that name in error, warning, and informational messages.
It must contain only alphanumeric characters, hyphens, and underscores.
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.
As of MiniVend 3.0, you can specify any number of alias script names
as additional parameters. This allows the calling path to be different
while still calling the same catalog -- it is most probably useful
when calling an SSL server or a members-only executable that requires
a username/password via HTTP Basic authorization. All branched links
will be called using the aliased URL.
In addition, if you set the global directive
FullUrl
to yes,
you can (and must in all catalogs) specify the server name that
will call the catalog. This allows you to have many virtual domains,
all of which use /cgi-bin/shop as the calling URL.
As with Perl ``here documents'', the EOF (or other end marker) must be the
ONLY thing on the line, with no leading or trailing white space. Do not
append a semicolon to the marker. (The above appears indented -- it
should not be that way in the file!)
IMPORTANT NOTE: These global subroutines are not subject to
security checks -- they can do most anything! For most purposes,
scratch subroutines or catalog subroutines (also
Sub
) are better.
GlobalSub routines are subject to full Perl use strict checking, so
you will get errors if you do not use lexical variables or complete
package qualifications for your variables.
DomainTail is preferable unless one of your HTTP servers does
not do host name lookups.
Default is
This will be executed with the user ID that MiniVend runs
under, so any commands that require root access will have
to be wrapped with an SUID program.
On Linux, you might lock out a host with:
This would require root permissions, however, under normal
circumstances. You can use You can write a script which modifies an appropriate access
control file, such as .htaccess for your CGI directory, to
do another level of lockout. A simple command line containing
BSDI and FreeBSD libraries are NOT safe, and SafeSignals will
automatically be disabled for those operating systems.
In general, if MiniVend ever just ``hangs'', particularly if you
can see a perl.core file, disable this directive.
The main reason that this would be used would be to conserve memory in
a series of stores that share most of the same pages or databases.
Set TolerateGet to
It would be typical to employ this on your shopping cart page or
perhaps put it on the
interact
page that is shown when
the normal error is received.
Actions are overwritten, even the default ones, if re-defined. Default
is blank. Can be set as many times as necessary. Not case sensitive.
The ButtonBars directive is deprecated in favor of
Variable
and
UserTag.
The choices to enter are:
Enter as a space or comma-separated list, i.e.
Orders are typically logged to other files via AsciiTrack, AsciiBackend,
or the [tag log ...]data[/tag] construct.
Care needs to be used. Each attribute specified in
PriceAdjustment
must have a corresponding column with the same name (case-sensitive),
which when keyed by the item attribute value yields the price adjustment
(if any) to be made for any item having that attribute and containing
that value. Used in concert with
PriceAdjustment
, and is not set by
default, disabling the common adjustment database feature.
Can be set in the
Locale
settings to allow different price
adjustment databases for different currencies (MV3.07 and up).
It must have at least two periods or browsers will ignore it.
If the
Cookies
directive is enabled, and mv_save_session is set
upon submission of a user form (or in the CGI variables through a perl
GlobalSub
), the cookie will be persistent for the period defined
by
SaveExpire
.
Caching and static page building will never be in effect unless
this directive is enabled.
This option uses the following standard fields on MiniVend order
processing forms:
PGP is recommended as the encryption program, though you should remember
that US commercial organizations may require a license for RSA.
Default is
description
. It is no longer a fatal error if this field
does not exist.
Overridden by [tag flag build][/tag] or [tag flag cache][/tag], depending
on context.
This is separate from the
PGP
directive, which enables PGP encryption
of the entire order.
If PGP is the encryption program (MiniVend determines this by searching
for the string
This is deprecated, and may be removed from future versions of MiniVend.
If the file (or the entry) 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). See the demo
for an example of how it is used.
The Help directive is vaguely deprecated in favor of arbitrary databases
and
Variable
.
Can be set in the
Locale
settings to allow different image
sets for different locales (MV3.07 and up).
Example of the custom setting:
Example of POSIX setlocale for France, if properly aliased:
See setlocale(3) for more information. If embedded Perl code
is used to sort search returns, then the setlocale() will carry
through to string collation.
MiniVend 3.07 extends the Locale array to accept many more settings.
See Internationalization.
This should probably be set to
The default prevents clashes with embedded Perl code.
If the limit is exceeded, then the command defined in the Global directive
LockoutCommand
will be executed and the shopping cart will be emptied.
The default is 0, disabling the check. Set it to a number greater than
the number of line items you ever expect a user to order.
They are accessed by setting the
mv_order_profile
variable to the
name of the order profile. Multiple profiles can
reside in the same file, if separated by __END__ tokens, which must be
on a line by themselves.
The profile is named by placing a name following a __NAME__
pragma:
The __NAME__ must begin the line, and be followed by whitespace
and then the name. The search profile can then be accessed by
mv_order_profile=``billing''
. See
Advanced Multi-level Order Pages
.
Can be set in the
Locale
settings to allow different page
sets for different locales (MV3.07 and up).
If this directive is non-null, the PGP command string as specified will be used
to encrypt the entire order -- in addition to any encryption done as a
result if
CreditCardAuto
, If for some reason an error comes from PGP, the
customer will be given the special page
failed
.
If you use MiniVend's htpasswd.pl (from 2.03 or higher) it will write
the catalog configuration file if given
catalog.cfg
as the file
name. The demo starts with an encrypted blank password, allowing you
to just hit enter.
A common case would be size. For shirts that are size XXL, you
might wish to add a dollar to the price for an item. In that case, you
can define a column in the standard pricing database See
CommonAdjust
for another scheme that makes the same adjustment
for any item having the attribute -- both schemes cannot be used at the
same time. (This is true even if you were to change the value of
$Vend::Cfg->{CommonAdjust} in a subroutine -- the pricing algorithm
is built at catalog startup.)
Can be set in the
Locale
settings to allow different price
adjustment fields for different currencies (MV3.07 and up).
This would be overridden if a
Locale
price_picture
is set.
Can be set in the
Locale
settings to allow a price
adjustment factor for different currencies (MV3.07 and up).
Can be set in the
Locale
settings to allow different price
fields for different currencies (MV3.07 and up).
As an added measure of control, the specification is evaluated with the
special MiniVend tag syntax to provide conditional setting of search
parameters.
The following file specifies a dictionary-based search in the file
'dict.product':
The __NAME__ is the value you will specify in the mv_profile variable
on the search form, as in
or with mp=profile in the one-click search.
Multiple profiles can reside in the same file, if separated by __END__
tokens. __NAME__ tokens should be left-aligned, and __END__ must be on
a line by itself with no leading or trailing whitespace.
Setting SeparateItems to
Can be overridden with the mv_separate_items variables (both
scratch and user).
It is possible for multiple catalogs to share the same session file. This
allows a ``mall'' to be set up where many store fronts 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.
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.
As with Perl ``here documents'', the EOF (or other end marker) must be the
ONLY thing on the line, with no leading or trailing white space. Do not
append a semicolon to the marker.
The above would be called with:
and will display an HTML table of the items in the current shopping cart,
sorted by the description. (Using an alternative form of quoting such
as q{ } will minimize problems with quotes in the passed parameters --
you may use any style you like, including here documents. Syntax errors
will be reported to
error.log
.)
Catalog subroutines may not perform unsafe operations -- the Safe.pm
module enforces this.
Defining
and calling the routine with
is the same as calling
This can make calling routines more natural, and is especially
useful in combination with
mv_subroutine
.
Most users now use the simpler and more flexible
Easy ASCII Tracking
capability.
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 catalog may go down.
To test the format of user catalog configuration files before
restarting the server, you can do (from VendRoot):
That will check all configuration files for syntax errors, which
might otherwise prevent a catalog from coming up. Once a catalog
configures properly, user reconfiguration will not crash it, just
cause an error. But it must come up when the server is started.
To start the server:
Assuming the server starts correctly, you will see the names of
catalogs as they are configured, along with a message stating
the process ID it is running under.
To re-start the server:
This is typically done to force MiniVend to re-read its configuration.
You will see a message stating that a TERM signal has been sent to the
process ID the servers are running under -- that information is also
sent to /home/minivend/error.log. Check the error.log file for
confirmation that the server has restarted properly.
To stop the server:
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 /home/minivend/error.log.
Because processes waiting for selection on some operating systems block
signals, they may have to wait for
HouseKeeping
seconds to stop. The
default is 60.
IMPORTANT NOTE: When sending sensitive information like credit card
numbers over a network, always ensure that the data is secured by a firewall,
or that the MiniVend server runs on the same machine as any SSL-based
server used for encryption.
If you only want to run with one method of communication, use the
A
reconfig
script is included with the demo catalogs, set up
with the
Password
method of authentication and a blank password,
suitable for the user to reconfigure the catalog from a Unix shell.
To set it up as a CGI, use the
MasterHost
or
RemoteUser
authentication methods.
The following updates the products database
More than one field can be updated on a single command line
The following takes input from
file
, which must be
formatted exactly like the original database
and adds/corrects any records contained therein.
Invoke the command without any arguments for a usage message
describing the options.
You could add a crontab entry such as the following:
MiniVend will wait until the current transaction is finished before
expiring, so you can do this at any time without disabling web access.
Any search paging files for the affected session (kept in
ScratchDir
)
will be removed as well.
MiniVend comes with debugging output disabled by default -- this is
for speed and code compactness. To enable debugging, change directory
to the MiniVend root (the software directory) and run:
This only works for MiniVend 3.06 and above. Earlier MiniVend versions
have only a crude debug available with the -D startup options.
To disable, use the command
Note that some warnings may be generated by the debugging itself, typically
``use of unitialized variable'' warnings generated by undefined debug references.
You can safely ignore these if they occur pointing to lines where the
logDebug routine is called.
IMPORTANT NOTE: This may affect some program operations. If something new fails in
debug mode, try it again in normal background server mode. In particular, changes
to the configuration made on the fly in the page will stick since the process
is not forked.
NOTE: The text levels only operate in conjunction with [tag flag debug].
If you want to output the debug information embedded in an HTML comment
at the end of the page you get from your browser, add level 1024. This
overrides the output to mvdebug temporarily, or to foreground output
indefinitely, if those are enabled.
Use this to set verbose but no tag details, with output to HTML:
Use this to look at only database operations, with output to HTML:
The debug mode of 8192 will enable DisplayErrors for every catalog.
The installation program (makecat) can be used to install your own
custom catalog template. See the supplied demo template
simple
for examples.
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 tlink program.
To install the demo:
Answer the prompts supplied by the program. Note that there are
two types of paths asked for, URL paths like the /cgi-bin inside
http://www.machine.com/cgi-bin/simple, and file paths that are
complete fully-qualified file path names.
You will see some output as the configure script checks your system.
Then compile the programs:
You can ensure your C compiler will be invoked properly with this
little ditty:
On some systems you can make the executable smaller with the strip
program. But don't worry about it if strip is not on your system.
If you want MiniVend to run under a different user account than your own,
make that user the owner of vlink. (You probably need to be root to do
this). Do not make vlink owned by root, because making vlink setuid
root is an huge and unnecessary security risk. It should also not
normally run as the default WWW user (often
Move the vlink executable to your cgi-bin directory:
Make vlink setuid:
Most systems unset the SUID bit when moving the file, so you should
change it after moving.
The SCRIPT_NAME as produced by the HTTP server must match the name
of the program. (As usual, you should let the makecat program do
the work.)
makecat program supplied with MiniVend will make those
for you.
~/catalogs/catalog_name/pages).
For the demos supplied with MiniVend, this means that only a few pages
will be copied to your HTML directory, with the remainder of the pages
staying in the directory defined as
PageDir
.
Setting up multiple catalogs
MiniVend has multiple catalog capability. It breaks the configuration
files into two pieces:
There may also be
SubCatalog
directives:.
SubCatalog easy simple /home/catalogs/simple /cgi-bin/easy
The remaining parameters are as in the
Catalog
directive..
Additional minivend.cfg parameters set up administrative parameters
that are catalog wide -- see
Server Configuration File
for details
on each of these.
The Catalog
MiniVend pages are NOT in normal HTML space. They are contained in the
catalog directory
. Each individual catalog must have its own base
directory. The catalog directory has this structure by default:
.
/cgi-bin/simple/products/gold will call the
page in the file
pages/products/gold.html
.
If something goes wrong
MiniVend is a complex program, and needs the services of other complex
programs to work. When there is a problem, it is not always MiniVend. It
may have to do with Perl or your HTTP server. In fact, in the over two
years of MiniVend's existence more basic installation problems have to
do with those than with MiniVend itself.
makecat program is intended to be used to create the
starting point for the catalog. If you don't get the demo to work
the first time, keep trying. If you still can't get the demo
to work, try running in INET mode. Finally, see the MiniVend FAQ at:
subscribe minivend-users to:
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 with a restrictive
setup. Determined and thoughtful users almost always make MiniVend work.
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!
makecat and using INET mode instead.
(Or you can copy the tlink INET mode link program over vlink). This
should work unchanged for many systems, but if you are on an ISP or have
a non-standard network configuration you may have to make some changes
to
minivend.cfg
. For tlink to work you must have the proper host
name(s) configured into the
TcpHost
directive in
minivend.cfg
. The
program selects port 7786 by default (the ASCII codes for ``M'' and ``V'')
-- if you decide to use another port, you must set the same number in
both the tlink program (before compilation, or by editing tlink.pl)
and the
minivend.cfg
file.
tlink program does not need to be SUID.
nobody!
minivend
user, then put that user in the group that each catalog user is in. If
you can define a group for each individual user, that provides the best
security. Then all associated files can be in 664 or 775 mode, and you
should have no problems with permissions.
vlink 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 and the CGI program vlink must be executing
on the same machine.
tlink program does not have this problem, but it must have the
proper host name(s) and TCP ports set in the
TcpHost
and
TcpPort
directives in
minivend.cfg
. Also, you should be careful of security
if sensitive information like customer credit card numbers is being
placed on a network wire.
SETTING UP YOUR CATALOG
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.
Start with a database
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.
.
On-the-fly pages, static, or both?
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 and a the search result page(s). To build
single-item pages, use the flypage.html template as an example and
build your own. You can also define a product database field (with the
PageSelectField
directive) to hold the name of the base on-the-fly
page for that item. You might define it to be the same as the category
of product, for example.
.
Use the demo catalogs
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.
Tree design
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.
The Essentials
The rest of this section describes the rest of the things you need to
know to make the most basic of MiniVend catalogs, one which displays
pages and uses the demo shopping basket and checkout sequence. If you
want to add custom features, like special shipping charges and
sales tax, you will need to go much further. But this will get you
started.
Catalog Pages -- MiniVend tags
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. We
will usually call them MiniVend tags or just tags.
vlink or tlink cgi-bin program, is ``catalog.html''. This page
will contain links to other catalog pages with the [page pagename] tag.
Individual products can be ordered by the [order <item-code>] element,
which brings up the shopping basket page. The shopping basket page
contains an [item-list], which builds information on each item ordered,
and optionally has input boxes for the customer to type in their
name and address. If desired, the customer can be ``stepped through''
the order process (as is demonstrated in the supplied demos). Once the
order has been sent the receipt page is displayed.
Cookies
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. Cookie capability is also required to use search
caching, page caching, and statically generated pages. If the browser
does not support cookies, the cache will be ignored.
Basic MiniVend Tags
NOTE: In the descriptions, parameters marked with an asterisk* are
optional.
item-list). They are interchangeable,
except that the ending tag and beginning tag should match (don't
use [item-list] list [/item_list]).
.
How to order an item
MiniVend can either use a form-based order or a link-based order to
place an item in the shopping cart. The link-based order uses the
special [order item-code] tag:
To order with a form, you set the form variable main) and the order page
that will display the order. The optional argument
database
constrains
the order to a particular products file -- if not specified, all databases
defined as products files will be searched in sequence for the item.
mv_order_item to.the item-code/SKU and use the
refresh
action:
Where do I go from here?
MiniVend is very complicated but very powerful. If you have read and
understood the documentation so far, you have a good start on building a
catalog. There are many, many, more features than are shown in the demo,
and mastering the ones you need will take time. Thousands of people have
built MiniVend catalogs -- you can too. If you feel it is beyond you,
then we would suggest engaging a competent consultant. Good luck!
DATABASES
MiniVend, as with most powerful shopping cart programs, is all about
databases.
If necessary, MiniVend reads the data to place in tables from standard.ASCII-delimited files. All of these ASCII source files are kept in the
products directory, normally
products
in the catalog directory (where
catalog.cfg is).
NOTE: Using the default TAB delimiter is highly recommended if you.are planning on searching the ASCII source file of the database. PIPE
works fairly well, but CSV delimiter schemes cause problems with searching.
| characters. No whitespace should be at the
beginning of the line.
.
The Product Database
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, hash 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.
-), underscore (_), pound sign/hash mark (#), slash (/),
and period (.).
Arbitrary Databases
MiniVend can manage an unlimited number of arbitrary database
tables. They are in the same format as the products file by default,
but an unlimited number of addressable schemes are available. These are
defined by default:
MiniVend built-in database support
If you specify one of the first 6 types, the database will automatically
be built in the default MiniVend DB style. You cannot mix the styles -- all
built-in databases on a single server will be the same style. They will
coexist just fine with an unlimited number of DBI databases of different
types.
.
Character usage restrictions
To review, database identifiers, field names, and product codes (database keys)
are restricted in the characters they may use. A short table showing
restrictions:
Import Attributes
Especially in SQL databases, there are certain things that can be set with
additional database attributes. For text import, the CONTINUE extended
database import attribute allows additional control over the format of
imported text.
.
\) at the end of a record, just like many Unix commands
and shells.
SQL SUPPORT
MiniVend can use any of a number of SQL databases through the powerful
Perl DBI/DBD access methods. No SQL database is included with MiniVend,
but there are a number widely available on the net, and many are free
for non-commercial use. Some examples include mSQL, mySQL, Solid, and Qbase.
Msql support
The first minimal SQL support provided by MiniVend was for the Msql.pm module.
This is now deprecated in favor of the DBI support. In most cases, existing
Msql users should be able to install and test DBD::mSQL, then change the
database directive to the type of dbi:mSQL:minivend and go from there. You
may have to set your directive to dbi:mSQL:minivend:localhost:1114 or some
other value corresponding to host and TCP port.
SQL support via DBI
MiniVend now provides complete external SQL database support via the Perl
DBI and DBD modules. This allow transparent access to any database that
is supported by a DBD module. The current list includes mSQL, mySQL,
Solid, Postgres, Oracle, Sybase, Informix, Ingres, Qbase, DB2, Fulcrum,
and others. Any ODBC (with appropriate driver) should also be supported.
minivend on port 1114 of the local machine:
Here is an example of a completely set up DBI database on mySQL, using.a comma-separated value input, setting the DBI attribute LongReadLen to
retrieve an entire field, and changing some field definitions from the
default char(128):
minivend selects the
database, othermachine.my.com selects the host, and 1112 is the port.
On many systems, dbi:mSQL:minivend will work just fine. (The minivend
database must already exist, of course.)
perldoc DBI for more information.
minivend for this to work.
Permissions are difficult on mySQL -- if you have trouble, try starting
the mySQL daemon with safe_mysqld --skip-grant-tables & for testing
purposes.
SQL Access Methods
A MiniVend SQL database can be accessed with the same tags as any of
the other databases can. In addition to those standard methods, direct
SQL support is provided with the [sql function] TEXT [/sql identifier]
tag set. The MiniVend database identifier only needs to be set if the
table resides in a different database than the main products database --
if you don't use SQL for the products database you will ALWAYS need to
set it.
%s in the query. For example:
.
my $string =<<'EOF';
[sql array]select * from arbitrary where code <= '19'[/sql arbitrary]
EOF
my $ary = eval $string;
my $out = '';
my $i;
foreach $i (@$ary) {
$out .= $i->[0];
$out .= "
";
}
$out;
[/perl]
my $string =<<'EOF';
[sql hash]select * from arbitrary where code <= '19'[/sql]
EOF
my $hash = eval $string;
my $out = '';
my $key;
foreach $key (keys %$hash) {
$out .= $key->{field1};
$out .= "
";
}
$out;
[/perl]
sql. Available are the following, in order of interpolation:
Importing from an ASCII file
When importing a file for SQL, MiniVend by default uses the
first column of the ASCII file as the primary key, with a char(16)
type, and assigns all other columns a char (128) definition. These
definitions can be changed by placing the proper definitions in COLUMN_DEF
Database
directive attribute:
Exporting from a database
To export your existing database to a file suitable for searching by
MiniVend, you can create an
AdminPage
(or any page, for that matter)
that contains a [tag export ...][/tag] element. For example, the following
UNIX shell script will create a page only accessible to the AdminUser
which will export the products database to the MiniVend default search
file
products.asc
:
# create the page.
cat <<EOF > pages/admin/export.html
<HTML><HEAD>
<TITLE>Export products.asc</TITLE>
</HEAD>
<BODY>
[if explicit ``[tag export products products.asc TAB][/tag]'']
Exported OK!
[else]
<FONT COLOR=RED>Error on export:</FONT> [data session last_error]
[/else]
[/if]
</BODY></HTML>
EOF
# Voila! Access with something like:
#
# http://yourcatalog.com/cgi-bin/simple/admin/export
MINIVEND TAG REFERENCE
To build complex order forms and reports, MiniVend has a complete
tag language with over 80 different functions.
New and Old syntax
Starting with MiniVend 3.0, a new tag syntax becomes operational.
It overcomes some of the limitations of MiniVend conditional HTML, and
has sequential evaluation.
Yes. The demo catalog is distributed with
NewTags Yes
starting at MiniVend 3.07.
[new]
tag in your page. Likewise, to use old syntax when new is the default,
place one [old] tag in the page.
DATA and FIELD
The [data ...] and [field ...] tags access elements of MiniVend databases.
They are the form used outside of the iterating lists, and can be effecfively
used to do lookups when the table, column/field or key/row is conditional based
on a previous operation.
.
[data ...] tag can access a number of elements in
the MiniVend session database:
SET and SCRATCH
Scratch variables are maintained in the user session separate from the
form variable values set on HTML forms.
.
LOOP and TAG EACH
Loop lists can be used to construct arbitrary lists based on the contents
of a database field or other value. The [tag each table] [/tag] construct
uses the same interior tags, but iterates over every key of a particular
database table.
.
with value
appended, i.e. [loop-field-a name], [loop-price-a], etc. Nesting
is arbitrarily large, though it will be slow for many levels.
table is non-empty, and the ELSE (if any)
otherwise.
[loop list] and the weight field is empty,
then a numerical -1 will be output from the [calc][/calc] tags; the
list will end and the item will not be shown. If the product's weight
field is less than 1, a numerical 1 is output. The item will be shown,
but will be the last item shown.
[loop list] and the product's weight
field is less than 1, then a numerical
1
will be output from the
[calc][/calc] operation. The item will not be shown.
IF
Allows conditional building of HTML based on the setting of various MiniVend.session and database values. The general form is:
[if] tag can also have some variants:
[if ...], it is more convenient
to use the old in most cases. It will work fine with both parsers.
The only exception is if you are planning on doing a test on the
results of another tag sequence:
[if value name =~ /[value b_name]/]
Shipping name matches billing name.
[/if]
[if explicit]. This allows complex testing and parsing of
values.
The
field
term is the specifier for that area. For example, [if session.frames] would return true if the
frames
session parameter was set.
mv_
are MiniVend special values, and should be tested/used
with caution.
[if explicit].
.
[if ..] test
fails.
TAG -- the catchall
Many MiniVend functions can be controlled or specified with [tag ...][/tag]
pairs.
.
.
name
for every record in the
products
database:
n, if specified, will select export in
one of the enumerated MiniVend export formats. The following tag will
export the products database to products.txt (or whatever you have
defined its source file as), in the format specified by the
Database
directive:
No.
sizes databases
held in MiniVend internal DBM format:
No.
description_string used as the
Content-Description. For example
&#lt; and [ respectively.
User-defined Tags
MiniVend 3.04 allows the definition of user tags when using the new
parsed HTML syntax (a [new] tag is on the page). They will not work
with the old syntax. 3.06 adds the tags on a server-wide basis.
tagname is the name of the tag, property is the attribute
(described below), and
value
is the value of the property for that
tagname.
title database field for product code 99-102.
Don't use this with [item-data ...] and [item-field ...], as they
are parsed separately. You could do [product-name [item-code]], though.
THIS TEXT SHOULD BE ALL UPPER CASE.
UserTag quick_table HasEndTag
UserTag quick_table Interpolate
UserTag quick_table Order border
UserTag quick_table Routine <<EOF
sub {
my ($border,$input) = @_;
$border = `` BORDER=$border'' if $border;
my $out = ``<TABLE ALIGN=LEFT$border>'';
my @rows = split /\n+/, $input;
my ($left, $right);
for(@rows) {
$out .= '<TR><TD ALIGN=RIGHT VALIGN=TOP>';
($left, $right) = split /\s*:\s*/, $_, 2;
$out .= '<B>' unless $left =~ /</;
$out .= $left;
$out .= '</B>' unless $left =~ /</;
$out .= '</TD><TD VALIGN=TOP>';
$out .= $right;
$out .= '</TD></TR>';
$out .= ``\n'';
}
$out .= '</TABLE>';
}
EOF
Note that the UserTag facility, combined with AllowGlobal, allows the.user to define tags just as powerful as the standard MiniVend tags.
This is not recommended for the novice, though -- keep it simple. 8-)
tag_loop_list and tag_if in
lib/Vend/Interpolate.pm for an example of a nesting tag.
[tagname] and ending [/tagname] will
be the last argument sent to the defined subroutine.
[usertag argument] instead
of [usertag ARG=argument]. If not defined,
Routine
is used, and MiniVend
will usually do the right thing.
UserTag tagname Routine <<EOF
sub {
my ($param1, $param2, $text) = @_;
return ``Parameter 1 is $param1, Parameter 2 is $param2'';
}
EOF
PRICE, DESCRIPTION, ACCESSORIES
.
FILE and INCLUDE
These elements read a file from the disk and insert the contents
in the location of the tag. [include ...] will allow insertion of
MiniVend variables.
.
BODY, BUTTONBAR, RANDOM, ROTATE
Tags to help manage page appearance and advertising links:
.
ceiling sets the highest number that will be
selected -- likewise floor sets the lowest. The default is to sequence
through all defined rotating banners. Each user has a separate rotation
pattern. See Controlling Page Appearance.
Tags for summarizing shopping basket/cart
The following elements are used to access common items
which need to be displayed on baskets and checkout pages.
.
mode -- the default
mode is the shipping mode currently selected in the mv_shipmode
variable. See
SHIPPING
.
pt,
and
PriceDivide
to 100, the following
Item Lists
Within any page, the [item_list cart*] 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:
.
column in table table is non-blank, the
following text up to the [/if_data] 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.
[item-list] (or [search-list] or
flypage) and the weight field is empty, then a numerical -1 will
be output from the [calc][/calc] tags; the list will end and the item
will not be shown. If the product's weight field is less than 1,
a numerical 1 is output. The item will be shown, but will be the last
item shown. (If it is an [item-list], any price for the item will
still be added to the subtotal.)
attribute for the current item.
[item-list] (or [search-list] or flypage)
and the product's weight field is less than 1, then a numerical
1
will
be output from the [calc][/calc] operation. The item will not be shown. (If
it is an [item-list], any price for the item will still be added to the
subtotal.)
n (from the products file)
of the current item.
n (from the products file)
of the current item. Returns regular price if not discounted.
Embedded Perl Code
Perl code can be directly embedded in MiniVend pages. The code
is specified as [perl arguments*] any_legal_perl_code [/perl]. The
value returned by the code will be inserted on the page.
escaped causes any single quotes which might be contained in the
values to be escaped, preventing syntax errors in the case of a name like
``O'Reilly''.)
The code can be as complex as desired, but cannot use any operators.that modify the file system or use ``unsafe'' operations like ``system'',
``exec'', or backticks. These constraints are enforced with the default
permissions of the standard Perl module Safe -- operations may
be untrapped on a system-wide basis with the
SafeUntrap
directive.
On-the-fly Catalog Pages
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 insert
HTML only if there is a non-blank value in a particular field.
Tags for controlling old syntax interpolation order
.
Required Pages
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.
.
Checking Page HTML
MiniVend, as of release 3.02, allows you to debug your page HTML with
an external page checking program. Because leaving this enabled on a
production system is potentially a very bad performance degradation, the
program is set in a the global configuration file with the CheckHTML
directive.
FORMS AND MINIVEND
MiniVend uses HTML forms for order, search, and control operations.
Order operations possibly include ordering an item, selecting item
size or other attributes, and reading user information for payment
and shipment. Search operations may also be triggered by a form.
In addition, the user can control certain aspects of the session,
such as order security, frames presentation, and background display
via a control form.
Special Form Fields
MiniVend treats some form fields specially, to link to the search engine
and provide more control over user presentation.
It has a number of predefined variables, most of whose names are prefixed with
mv_ to prevent name clashes. It also uses a few variables which are
postfixed with integer digits -- those are used to provide control in its
iterating lists.
Form Actions
Any MiniVend form can be used for any number of actions. The actions
are mapped by the
ActionMap
directive in the catalog configuration
file, and are selected on the form with either the mv_todo or
mv_doit
variables.
.
One-click Multiple Variables
MiniVend can set multiple variables with a single button or form
control. You first define the variable set (or profile, as in
search and order profiles) inside a scratch variable:
� literal.
The return value for the subroutine is available in the fixed .session variable return_value, accessible as [data session return_value].
Checks and Selections
You can provide a ``memory'' for drop-down menus, radio buttons, and
checkboxes with the [checked] and [selected] tags.
.
var_name is equal to
value
. Not case sensitive.
var_name is equal to
value
. If the optional MULTIPLE argument is present, it will
look for any of a variety of values. Not case sensitive.
Setting Form Security
You can ensure that a form will be submitted securely (to the base
URL in the SecureURL directive, that is) by specifying your form
input to be ACTION=``[process-target frame secure]''. If you are not
using frames, just specify the special frame ``_self'' or ``none''.
secure modifier.
Stacking Variables on the Form
Many MiniVend variables can be ``stacked'', meaning they can have
multiple values for the same variable name. As an example -- to allow
the user to order multiple items with one click, you can set up
a form like this:
Setting SQL tables with a form
Any MiniVend database can be updated with a form using the following method.
The MiniVend action set (see
ActionMap
), causes the update. Here.is an pair of example forms. One is used to set the key to access the
record (careful with the name, this one goes into the user session
values). The second actually performs the update. It uses the [loop]
tag with only one value to place default/existing values in the form
based on the input from the first form:
THE SEARCH ENGINE
MiniVend implements a search engine which will search the product
database (or any other file) for items based on customer input. It uses
either forms or URL-based searches (called with the special page name
scan). The search engine uses many special MiniVend tags and variables.
The Search Form
A number of variables can be set on search forms to determine which search
will be used, what fields in the database it will search, and what search
behavior will be.
Glimpse
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:
Fast Binary Search
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.
Range Searching
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.
SQL searches
MiniVend can formulate and execute SQL searches in much the same way as it does
text or Glimpse searches. Because of the SQL language and the limitations a
common subset places on the operation, not all parameters are supported.
.
One-click searches
MiniVend allows you to pass a search in a URL. Just specify the
search with the special page reference scan. Here is an
example:
/, etc. -- &sp; or   will not be recognized.
In-page searches
NOTE: New to MiniVend 3.03.
Americana and Contemporary within the
products database field
category
.
Search Profiles
You can predefine an unlimited number of search profiles that reside
in a file or files. To use this, make up a series of lines like:
mp modifier:
Search Reference
The supplied
simple/srchform.html
and
simple/results.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.
Fields can also always be specified by an integer column number, with 0.as the first column. This may reduce system processing somewhat, since
the field names don't have to be indexed every time they are referenced,
and won't have to be read from disk.
-H option,
and Glimpse will look for its indices there. Default is ProductDir.
.
r, n,
and f -- for reverse, numeric, and case-insensitive respectively.
These can be stacked, if coming from a form, or placed in a single
specification separated by commas. The stacked options will be
applied to the sort fields as they are defined, presuming those
are stacked.
The Results Page
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
.
.
artist:r or title:. This
could also be specified with 2r or
1
.
[sort] tag (after [search-list]
if doing sorts via mv_sort_field). If specified on a sorted return list,
causes only the first line containing an [item-code] to be returned --
all subsequent lines will not be interpreted on the list. Note that
[matches]
and [more-list] may not operate as you wish in this case.
Note that [on-change] is more likely useful.
[item-field field] or [item-data database field].
marker field is mandatory, and is also arbitrary, meaning that
you can select any marker you wish as long as it matches the marker
associated with
[/on_change marker]
. The value to be tested is contained
within a [condition]value[/condition] tag pair. The
[on_change marker]
tag
also processes an [else] [/else] pair for output when the value does
not change. The tags may be nested as long as the markers are different.
subcategory associated with each item:
will prevent blanked table cells if you use a border.)
next_img, prev_img, and/or page_img
are present, they represent image files that will be inserted instead
of the standard 'Next', 'Previous', and page number. If prev_img
is none, then no previous link will be output. If page_img is
none, then no links to pages of matches will be output. These are
URLs, are substituted for with
ImageDir
, and will be encased in
IMG tags. Lastly, border is the border number to put.
page_img is used, it will be passed an argument of
the digit that is to be represented. This would allow an image generator
program to be used, generating page numbers on the fly. The border
and border_selected values are integers indicating the border that
should be put around images in the page_img selection. The <border_selected>
is used for the current page if set.
Next or Previous page, that link
will not be shown.
fr_resul.html or
search.html
files for examples. Make sure
you insert this item between a [more_list] and [/more_list] element pair.
Updating session variables after a search
You may notice that if you set a scratch variable or reference a
variable set in a search routine on the results page, the change does
not stay in the user session.
Using a Search Cache
Each catalog may maintain a search cache, which is enabled by
specifying a file name (the name of the search cache DBM) in
the
SearchCache
directive in
catalog.cfg
. It operates by
developing a 32-bit checksum of the combined parameters of a
one-click scan search, or by combining the variable names/values
specified in mv_cache_params on a form-based search.
THE ORDER PROCESS
MiniVend has a completely flexible order basket and checkout
scheme. The
simple
demo presents a common use of this process,
in the directory pages/ord -- the files are:
FORM. It will have a number of
variables on it. At the minimum it must have an [item-list] to
loop through the items, and the quantity of each item must be
set in some place on that form. Any valid MiniVend tags may be
used on the page, and you may use multiple item lists if necessary.
How to set up an order link
On a product display page, use:
How to set up an order button
MiniVend can order via form submission as well. This allows you
to order a product (or group of products) via a form button. In its
simplest form, it is:
[item-accessories size] or [item-accessories size] tag. See
Item Attributes
.
Order Groups
MiniVend 3.06 allows you to group items together, making a master item
and sub-items. This can be used to delete accessories or options when
the master item is deleted. In its simplest form, you order just one
master item and all subsequent items are sub-items.
00-0011 is deleted from the basket,
00-0011a will be deleted as well. And when 19-202 is deleted,
then 99-102 will be deleted from the basket.
mv_mi and mv_si are set to the group and subitem status
of each item. The group, contained in the attribute mv_mi, is a
meaningless yet unique integer. All items in a group will have the same
value of mv_mi. The attribute mv_si is set to 0 if the item is
a master item, and 1 if it is a sub-item.
if the item is a master item, and
Basket display
The basket page(s) are where the items are tracked and adjusted by the
customer. It is possible to have an unlimited number of basket pages.
It is also possible to have multiple shopping carts, as in buy or
sell. This allows a basket/checkout type of ordering scheme, with custom
order pages for items which have many accessories.
The variables mentioned above modify the page display in the.following ways:
.
Multiple Shopping Carts
You can maintain multiple shopping carts with MiniVend (2.02 and above).
One shopping cart -- main, by name -- is defined when the user session
starts. If the user orders item M1212 with the following tag:
Advanced Multi-level Order Pages
An unlimited number of order checking profiles can be defined with the
OrderProfile
directive, or by defining order profiles in scratch
variables. This allows a multi-level ordering process, with checking
for format and validity at every stage.
Also, there are three pragmas that can be used to change behavior:.
As an added measure of control, the specification is evaluated for 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_failpage
variable.
Simple Order Report File
The simple order report file, ``report'', defines the layout of the order
report which gets mailed on the completion of the order. For example,
mv_ and are automatically ignored.
Fully-configurable Order Reports
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.
Order Receipts
If you specify a legal MiniVend page name in the ReceiptPage directive,
the user will be sent this page instead of the default ``confirmation''
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. If you want to have a different receipt for different
carts, set the mv_order_receipt variable in the form.
The Order Counter
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.
Customer Input Fields
On the order (or shopping basket) page, by default order.html, you will
have a number of input fields allowing the 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:
Product Pricing
MiniVend maintains a price in its database for every product. The price
field is the one required field in the product database -- it is necessary
to build the price routines.
For example, if you decided to adjust the price of T-shirt part number.99-102 up 1.00 when the size is extra large and down 1.00 when the size is small,
you would have the following directives defined in <catalog.cfg>:
price
in the pricing database. The price field contains a space-separated
list of prices that correspond to the quantity levels defined in the
PriceBreaks
directive. If quantity is to be applied to all items in
the shopping cart (as opposed to quantity of just that item) then the
MixMatch
directive should be set to Yes.
Item Attributes
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 multiple attributes for each item
can be stacked on top of each other.
Product Discounts
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:
Sales Tax
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:
yes, y, 1, or the
like), sales tax will not be applied to the item. If it evaluates false,
it will be taxed.
tax_code, and define a variable in the user session to reflect the
proper entry in the
salestax.asc
file. To set it to 15% with the
above
salestax.asc
file, you would put in a form:
Using CyberCash
MiniVend will directly interface with the Perl CCLib provided by
CyberCash, Inc. This allows direct card billing at the time the order is
placed. The CCLib.pm version should be 1.3 or greater. If the library is
found at startup, the message ``CyberCash module found'' will be displayed.
mauthcapture and mauthonly
modes. Any modes supported by CyberCash should work.
minivend_test will cause the transaction to complete
successfully and the information that would have been sent to the
CyberCash server to be logged in the catalog
error.log
file.
The fields containing name and address information should be.the same as on the standard MiniVend demo order pages:
Variable <<EOF
CYBER_REMAP
b_name my_bname
name my_name
address processed_address
city parsed_city
EOF
SORTING
MiniVend 3.03 regularizes the sorting options for sorting the search
lists, loop lists, and item lists based on the contents of database
fields. In addition, MiniVend 3.07 adds list slices, or limiting the
displayed entries based on a start value and chunk size (or start and
end value, from which a chunk size is determined). All accept a standard
format sort tag which must be directly after the list call:
[search list] , [loop list] , [tag each table], and
[item-list], take options of the form:
Multiple levels of sort are supported, and you can cross database.boundaries on different sort levels. Cross-database sorts on the same
level are not supported, so if you use multiple product databases you
will have to sort with embedded Perl. This is actually a feature in
some cases, since you can then display all items in a used database
before or after your new ones in
products
.
Note that large lists may take some time to sort -- if you have a product.database with many thousands of items, it is not recommended that you
use the [tag each products] sort unless you are planning on caching or
statically building your pages.
[sort products:title =3-4] is equivalent to the
above.
SHIPPING
MiniVend allows the addition of a flat shipping charge with
the
Shipping
directive. Most catalogs have more elaborate
requirements, requiring use of the
SHIPPING
capability
of MiniVend.
Default Shipping Mode
If a default shipping mode other than default is desired, enter
it into the
DefaultShipping
directive:
Shipping Cost Database
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. It always
needs to be present if
CustomShipping
is to be used.
The cost is calculated like this:.
IMPORTANT NOTE: The above only applies to the first field that.matches the shipping mode exactly. Following
criteria
fields contain
qualifier matching strings.
f,
by multiplier if it begins with x, by UPS-style lookup if
it begins with u, by named subroutine if it begins with an s, and
a straight cost otherwise. If it begins with an e, a zero cost
is returned with the following string as the error message.
Here is an example shipping file using all of the methods of.determining shipping cost.
default.
x, the cost is multiplied
by the accumulated criterion -- price, weight, etc.
f, the formula following
is applied. Use @@TOTAL@@ as the value of the accumulated criterion.
u, a UPS lookup is done.
s, a Perl subroutine call is made.
e, zero cost is returned and an
error placed in the session ship_message field, available as
[data session ship_message]. (If using the standard tag syntax,
you should surround it with [post] [/post] to ensure you get the
messages from the current page.)
.
usps, is a more complicated formula -- using price as the
criteria. If the total price of all items in the shopping cart (same as
[subtotal] without quantity price breaks in place) is from 1 to 50, the
cost will be 7.00 plus 10% of the order. If the total is from 50.01
to 100, the cost will be 12.00 plus 9% of the order total. If the
cost is 100.01 or greater, then 5% of the order total will be used
as the shipping cost.
upsg, is a special case. It specifies a UPS lookup based on your
UPS zone and two required values (and two optional arguments):
NNN.csv, where NNN is the first three
digits of the originating zip code.
fedex, uses a named subroutine. The example is
designed to work with this subroutine defined in catalog.cfg:
Sub <<EOF
sub fedex_cost {
my($country) = @_;
my $cost;
if($country =~ /^usa?$/i) {
$cost = 20;
}
else {
$cost = 50;
}
return $cost;
}
EOF
:) separator. If a key other
than the item code is to be used, it should be appended with a semi-colon
separator.
item_cost, and will send the weight of each
item, along with the value of the modes database column corresponding to
the shipping mode the user has selected, keyed with the value of country
on their order form. If the user has selected mode postal_air, and is
in the country coded as UK, the subroutine will be called as if it
was:
Determining shipping modes
MiniVend 3.07 and above uses the
CustomShipping
and
Shipping
directives to determine the shipping characteristics based on geography
or other session qualifier.
Geographic qualification
If the return value in the main criterion includes whitespace, the
remaining information in the field is used as a qualifier for the
subsidiary shipping modes. This can be used to create geographic
qualifications for shipping, as in:
Handling charges
Additional handling charges can be defined in the shipping file by setting
the form variable mv_handling to a space, comma, or null-separated set
of valid shipping modes. The lookup and charges are done in the same fashion,
and the additional charges are added to the order. (The user is responsible for
displaying the charge on the order report or receipt with a [shipping handling]
tag or the like.) All of the shipping modes found in mv_handling will be
applied -- if multiple instances are found on a form, the accordingly null-separated
values will all be applied. Careful! This should not be done in an item-list
unless you take care to account for multiple setting of the variables.
TRACKING AND BACKEND ORDER ENTRY
MiniVend allows the entry of orders into a system via one of several
methods. The
AsciiBackend
capability allows submittal of
parameters to an external order entry script. Support for SQL
allows entry of orders directly into an SQL database. Orders
can be written to an ASCII file. They can be formatted precisely
for email-based systems. The orders can be placed in a DBM file.
Finally, embedded Perl allows completely flexible order entry,
including real-time credit-card verification and settlement.
Easy ASCII Tracking
If you set AsciiTrack to a legal file name (based in VendRoot unless
it has a leading ``/''), a copy of the order will be saved there as well
as being emailed.
SQL Tracking
See the [sql set] tag for an example of entering orders in
an SQL database.
SSL SECURITY
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.
minivend,
minivend.cfg
,
and all modules included in minivend. Check them on a regular basis to
ensure they have not been changed.
Administrative Pages
With MiniVend's
GlobalSub
capability, very complex add-on schemes
can be implemented with Perl subroutines. And with the new
writable database, pages that modify the catalog data can be
made. If you mark a page as an
AdminPage
, only the catalog
administrator may use it.
CONTROLLING PAGE APPEARANCE
Using Frames
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.
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.
.
shirts.html in the
pages directory, and be output to the main frame. Be careful,
frame names are case-sensitive.
Changing output frame in a form
If you want to send output to different frames based on input
from the user, you can set the mv_change_frame variable. If found
in the current form, a Window-Target: header will be sent
to route the HTML output to the frame named in mv_change_frame.
Body and Buttonbar Control
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.
/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>.
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''>.
Integrated Image Maps
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:
Random Banners
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.
Rotating Banners
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.
In-line Help
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.
STATIC PAGE BUILDING
MiniVend now has a complete implementation of a static page building
facility. It allows you to build a parallel page tree completely in HTML,
and most importantly, keeps track of all of the URLs for you. It means
that MiniVend, whether the page on the browser was called dynamically
or statically, will call the appropriate page for you. This can mean
huge performance gains in catalogs with lots of pages in the browsing
structure, for any statically built pages never have to call MiniVend.
This improves performance and decreases server load.
Yes. This allows you to turn it on or off
with a single directive, and is a change from MiniVend 3.02 and below.
-build shop to the minivend program. MiniVend will scan
the entire page structure, testing each page to see if it has any
dynamic elements. Dynamic elements are those MiniVend tags which
depend on user session status, like the contents of the shopping cart,
conditional tests on user variables, or databases marked as dynamic
with the
DynamicData
directive. If a page has dynamic elements,
it will not be built statically.
[tag flag build][/tag] at the top
of the page. This tells the builder to ignore dynamic elements and build
the page anyway -- it will not override NoCache or AdminPage.
[tag flag build]name[/tag],
a symbolic link to name will be made in
StaticDir
. This allows
named pages to be reliably found -- otherwise the name of the page varies
with the order the search is found. Commonly you would use
[tag flag build][value mv_searchspec][/tag] to build a link based on
the search string.
In addition, you can build all possible on-the-fly pages out of the.database if the
StaticFly
directive is set. This is subject to
the
StaticPattern
as well, so you could build only a portion of the
database if you wished. Obviously catalogs that have many thousands of
items should be careful about use of
StaticFly
.
.build in the root of the
pages directory. MiniVend will use that as the list of pages to be
built on this run.
.static, located in the MiniVend
PageDir
. This is how MiniVend
knows which pages should be referenced with static URLs.
.unbuilt after the build process.
static in the catalog root, which can then be copied
to the appropriate place in HTML document space.
.html. DOSites might want to make
it .htm, and if you wished to have the files parsed for server
side includes you might use .shtml.
shop is the name of the catalog to be built. (Multiple -build name
directives can be used to build more than one catalog.)
INTERNATIONALIZATION
MiniVend 3.07 adds a rich set of I18N features to allow conditional message
display, differing price formats, different currency definitions, price
factoring, sorting, and other settings.
Setting the locale
The locale could be set to fr_FR (French for France) in one of two ways:
Once the locale is set for that user, it is in effect for the duration.of their session.
fr_FR before displaying the page.
MiniVend Locale Settings
The
Locale
directive has many possible settings, allowing
complete internationalization of page sets and currencies. The
Locale
directive is defined in a series of key/value pairs,
with a key (which contains word characters only) followed by
a value. The value should be surrounded with double quotes if
it contains whitespace. In this example, the key is Value setting.
Configuration de valeur will be displayed only if the
locale is set to fr_FR. If the locale is set to de_DE,
the string Werteinstellung will be dislayed. If it is neither,
the default value of Value Setting will be displayed.
Locale fr_FR <<EOF
{
``Value setting'',
``Configuration de valeur'',
"Search",
"Recherche"
}
EOF
[L] and [/L].
If using double quotes, string literals like \n and \t are recoginzed.
msg_key will then be used to index the message. This may be
preferable for many applications.
localize script is included with minivend. It will parse files
included on the command line and produce output that can be easily edited
to produce localized information. Given an existing file, it will merge
new information where appropriate.
Special Locale keys for price representation
MiniVend honors the standard POSIX keys:
.
en_US, the United States, and it would
display 4452.3 as $ 4,445.30.
###.###.###,##,
which would display the same number as 4.452,30. To add a franc
notation at the end for the locale fr_FR, you would use the setting:
mon_decimal_point, and
the thousands separator mon_thousands_sep must match the settings in
the picture. The frac_digits setting is not used in this case -- it is
derived from the location of the decimal (if any).
**.***,** fr.
**,***.**.
Dynamic locale directive changes
If you set Locale keys corresponding to some MiniVend
catalog.cfg
directives,
those values will be set when setting the locale.
.
price, but if the locale fr_FR is set, the
PriceField directive will change to prix to give prices in francs instead
of dollars.
prix from the pricing database
will be used to develop the quantity pricing. NOTE: If no Locale settings are
present, it will always be price, irrespective of the
PriceField
setting.
Otherwise it will always match
PriceField
.
.20, yielding franc prices five times
that of the dollar.
mon_thousands_sep will be used for standard currency formatting.
Ignored if using
price_picture
. Set to 1 or 0, to enable and disable
respectively. DO NOT USE Yes and No.
[locale key] and [/locale] tags. See the example above.
Sorting based on Locale
The MiniVend [sort database:field] keys will use the LC_COLLATE
setting for a locale provided that:
It is beyond the scope of this document to discuss these issues,.and you should contact your system administrator or local wizard
to help you set up locales on your system. NOTE: Windows locales
are not supported for sorting.
letters:
fr_FR were in effect,
then it would become:
MINIVEND CONFIGURATION FILES
MiniVend can and usually does run 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
early versions of the program.
Server Configuration File
The VendRoot directory, specified in the main program minivend, is
the default location of all of the MiniVend program, configuration,
special, and library files. Unless changed in minivend, the main
MiniVend server configuration file will be minivend.cfg in the VendRoot
directory.
.
GlobalSub <<EOF
sub count_orders {
my $counter = new File::CounterFile "/tmp/count_orders", '1';
my $number = $counter->inc();
return "There have been $number orders placed.\n";
}
EOF
No, and DomainTail must be set to No for it to
operate.
sudo or another method to
wrap and allow the command.
perl -0777 -npi -e 's/deny/deny from %s\ndeny/' /home/me/cgi-bin/.htaccess
would work as well (remember, the %s will become the IP
address of the offending user).
perldoc Safe at the command prompt. The default
is 249 148 for Perl 5.003, and ftfile sort for Perl 5.003_20 and
above, which untraps the file existence test operator and the sort
operator. Define it as blank to not allow any besides the default
restrictive operators.
tlink, specifies the hosts that are
allowed to send/receive transactions from any catalog on this MiniVend
server. Can be either an name or IP number, and multiple hosts can be
specified in a space-separated list. Default is localhost.
tlink, specifies the port
that will be monitored by the MiniVend server. Default is 7786.
Yes to allow GET forms. You will be able
to use METHOD=GET on the form if necessary, subject to the normal
limits of query string length. You will want to set the variable
mv_session_id to ensure that the session is not lost on browsers
that don't support cookies:
Catalog Configuration File
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.
Required Configuration Directives
In the catalog configuration file, these directives are
required
:
.
Optional Configuration Directives
These directives all have default values and are optional.
.
%p and
%f, are defined, which are replaced at encryption time with the
password and temporary file name respectively. See
Order Security
.
pgp in the command string), no password field or file
field need be used -- the field mv_credit_card_number will never be
written to disk in that case.
glimpseserver, you
must include the -C, -J, and -K tags if they are needed.
mon_decimal_point, thousands_sep, and frac_digits,
which are the the only international settings required. Default if not
set is to use US-English settings.
none to disable a color (use the browser
default) for a particular scheme. Remember, the schemes are numbered in
the order that they occur.
none to disable a color (use the browser default) for
a particular scheme. Remember, the schemes are numbered in the order
that they occur.
none to disable a color (use the browser default) for
a particular scheme. Remember, the schemes are numbered in the order
that they occur.
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.
none to disable a color (use the browser
default) for a particular scheme. Remember, the schemes are numbered in
the order that they occur.
[page name arg]
tag, among others).
Yes for new catalogs.
x is used as the substituted-for string
for the accumulated total. A yes/no directive -- default is No.
This will disappear soon.
robots.txt file you
may have created. If one of these bad robots orders several dozen or more
items, then the time required to save and restore the shopping cart from
the user session may become excessive.
pricing which
is named ``XXL''. If a value is found in that column it will be added
to the price for the item. Negative numbers result in subtraction if
you wish to reduce the price based on an attribute.
no. The default is to use commas (or whatever is
the thousands separator for your locale).
user, group, or
'world'.
https: protocol definition.
Default is blank, disabling secure access.
No, puts all
orders with the same part number on the same line.
Yes allows the item attributes to be
easily set for different instances of the same part number, allowing
easy setting of things such as size or color.
no.
Yes, static builds will attempt to generate
a page for every part number in the database using the on-the-fly page build
capability. If pages are already present with those names, they will be
overwritten. The default is No.
.html. Also affects the name of pages in the
MiniVend page directory -- if set to .htm the pages must be named with that
extension.
Sub <<EOF
sub sort_cart {
my(%items) = @_;
my($item,$name);
my $out = '<TABLE BORDER=1>';
foreach $name (sort keys %items) {
$out .= '<TR><TD>';
$out .= $items{$name};
$out .= '</TD><TD>';
$out .= $name;
$out .= '</TD></TR>';
}
$out .= '</TABLE>';
return $out;
}
EOF
quantity -- it will not
do what you want.
ADMINISTERING MINIVEND
Many utilities are supplied in the VendRoot/bin directory:
Starting, Stopping, and Re-starting the Servers
The following commands need to have VENDROOT changed to the
main directory where you installed MiniVend. If you made /home/minivend
your MiniVend base directory, the start command would be
/home/minivend/bin/start.
UNIX and INET modes
As of MiniVend 3.00, both UNIX-domain (the default) or INET-domain
sockets can be used for communication. INET domain sockets are useful
when more than one server, connected via a local-area network (LAN),
is used for accessing a MiniVend server.
-i and -u flags.
User reconfiguration
The individual catalogs can be reconfigured by the user by running
the reconfig command. At least one check must be made to authenticate --
by coming from a particular host (see
MasterHost
), having validated
by HTTP basic authorization (see
RemoteUser
), or by password entry
(see
Password
). The ideal way to use it is in combination with
HTTP basic authorization to allow remote reconfiguration by web
browser. It is possible at that point to have a completely FTP-
and HTTP-configured catalog.
Making the Product Database
The DBM product databases can be built offline with the offline
command. The directory to be used for output is specified either on
the command line with the -d option, or is taken from the
catalog.cfg
directive
OfflineDir
-- offline in the catalog directory by default.
The directory must exist. The source ASCII files should be present in
that directory, and the DBM files are created there. Existing files
will be overwritten.
Updating Individual Records
If you have a very large DBM database that takes a long time to build,
you may want to use the bin/update script to change just one field
in a record, or to add from a corrections list.
price field for
item 19-202 with the new value 25.00
Expiring Sessions
You should periodically expire old sessions to keep the session
database file from growing too large.
DEBUGGING
As of version 3.06, MiniVend allows you to see debugging information
based on the state of several controls.
.
nnnn, a numeric option set, is present, that debug level
will be set. The default level is 4097, running in the foreground with only
a few debug outputs (normal mode) present. If you want to run in the foreground
with maximum information, use the level 4351.
Yes
in both
minivend.cfg
and
catalog.cfg
. Debug information will be
included if available and level 1024 is set.
MANUAL INSTALLATION OF CATALOGS
A 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 many UNIX systems.
Needed Directories
The MiniVend program, and its supporting libraries, should all
go into one directory as installed by the installation program.
The Demo Systems
Sample catalog pages are in the directory 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 files
into the MiniVend directory and your HTML directory.
Setting up VLINK and TLINK
The vlink and tlink programs, compiled from vlink.c and
tlink.c, are small C programs which contact and interface to a running
MiniVend daemon. The vlink executable is normally made setuid to the
user account which runs MiniVend, so that the UNIX-domain socket file
can be set to secure permissions (user read-write only). It is normally
not necessary for the user to do anything -- they will be compiled by
the configuration program. If the MiniVend daemon is not running, either
will display a message indicating that the server is not available.
The following defines in the produced
config.h
should be set:
.
Compiling VLINK and TLINK
Change directories to the src directory, then run the GNU
configure script:
nobody or http)).
AUTHOR
Mike Heins, mike@minivend.com.
ACKNOWLEDGEMENTS
Original author of Vend was Andrew Wilcox. MiniVend was based on Vend 0.2,
with portions from Vend 0.3.