code: 01.00
section: User_defined_Tags
type: overview
title: User-defined Tags

<A NAME="User_defined_Tags">User-defined Tags</A></H1>
<P>
MiniVend 3.04 allows the definition of user tags when using the new parsed 
<FONT SIZE=-1>HTML</FONT> 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,
defined in <CODE>minivend.cfg</CODE>.

<P>
To define a tag that is catalog-specific, place <EM>UserTag</EM> directives in your catalog.cfg file. For server-wide tags, define them in
minivend.cfg. Catalog-specific tags take precedence if both are defined --
in fact, you can override the base MiniVend tag set with them. The
directive takes the form:

<P>
<PRE>   UserTag  tagname  property  value
</PRE>
<P>
where <CODE>tagname</CODE> is the name of the tag, <CODE>property</CODE> is the attribute (described below), and <A HREF="#item_value">value</A> is the value of the property for that tagname.

<P>
The user tags can either be based on Perl subroutines or just be aliases
for existing tags. Some quick examples are below.

<P>
An alias:

<P>
<PRE>    UserTag product_name Alias     data products title
</PRE>
<P>
This will change [product_name 99-102] into [data products title 99-102],
which will output the <CODE>title</CODE> database field for product code <CODE>99-102</CODE>. Don't use this with <CODE>[item-data ...]</CODE> and <CODE>[item-field ...]</CODE>, as they are parsed separately. You can do <CODE>[product-name [item-code]]</CODE>, though.

<P>

<FONT SIZE=-1>A</FONT> simple subroutine:

<P>
<PRE>    UserTag company_name Routine   sub { &quot;Your company name&quot; }
</PRE>
<P>
When you place a [company-name] tag in a MiniVend page, the text 
<CODE>Your company name</CODE> will be substituted.

<P>

<FONT SIZE=-1>A</FONT> subroutine with a passed text as an argument:

<P>
<PRE>    UserTag caps   Routine   sub { return &quot;\U@_&quot; }
    UserTag caps   HasEndTag 
</PRE>
<P>
The tag [caps]This text should be all upper case[/caps] will become
<CODE>THIS TEXT SHOULD BE ALL UPPER CASE</CODE>.

<P>
Here is a useful one you might wish to use:

<P>
<PRE>    UserTag quick_table HasEndTag
    UserTag quick_table Interpolate
    UserTag quick_table Order   border
    UserTag quick_table Routine &lt;&lt;EOF
    sub {
        my ($border,$input) = @_;
        $border = &quot; BORDER=$border&quot; if $border;
        my $out = &quot;&lt;TABLE ALIGN=LEFT$border&gt;&quot;;
        my @rows = split /\n+/, $input;
        my ($left, $right);
        for(@rows) {
            $out .= '&lt;TR&gt;&lt;TD ALIGN=RIGHT VALIGN=TOP&gt;';
            ($left, $right) = split /\s*:\s*/, $_, 2;
            $out .= '&lt;B&gt;' unless $left =~ /&lt;/;
            $out .= $left;
            $out .= '&lt;/B&gt;' unless $left =~ /&lt;/;
            $out .= '&lt;/TD&gt;&lt;TD VALIGN=TOP&gt;';
            $out .= $right;
            $out .= '&lt;/TD&gt;&lt;/TR&gt;';
            $out .= &quot;\n&quot;;
        }
        $out .= '&lt;/TABLE&gt;';
    }
    EOF
</PRE>
<P>
Called with:

<P>
<PRE>    [quick-table border=2]
    Name: [value name]
    City: [value city][if value state], [value state][/if] [value country]
    [/quick_table]
</PRE>
<P>
The properties for UserTag are are:

<DL>
<DT><STRONG><A NAME="item_Alias">Alias</A></STRONG><DD>

An alias for an existing (or other user-defined) tag. It takes the form:

<P>
<PRE>    UserTag tagname Alias    tag to insert
</PRE>
<P>
An Alias is the only property that does not require a <EM>Routine</EM>
to process the tag.

<P><DT><STRONG><A NAME="item_attrAlias">attrAlias</A></STRONG><DD>

An alias for an existing attribute for defined tag. It takes the form:

<P>
<PRE>    UserTag tagname attrAlias   alias attr
</PRE>
<P>
As an example, the standard MiniVend <A HREF="#item_value">value</A> tag takes a named attribute of <A HREF="#item_name">name</A> for the variable name, meaning that <CODE>[value name=var]</CODE>
will display the value of form field <CODE>var</CODE>. If you put this line in catalog.cfg:

<P>
<PRE>    UserTag value attrAlias   identifier name
</PRE>
<P>
then <CODE>[value identifier=var]</CODE> will be an equivalent tag.

<P><DT><STRONG><A NAME="item_CanNest">CanNest</A></STRONG><DD>

Notifies MiniVend that this tag must be checked for nesting. Only applies
to tags that have <EM>HasEndTag</EM> defined, of course. 
<FONT SIZE=-1>NOTE:</FONT> Your routine must handle the subtleties of
nesting, so don't use this unless you are quite conversant with parsing
routines. See the routines <CODE>tag_loop_list</CODE> and <CODE>tag_if</CODE> in lib/Vend/Interpolate.pm for an example of a nesting tag.

<P>
<PRE>    UserTag tagname CanNest
</PRE>
<P><DT><STRONG><A NAME="item_HasEndTag">HasEndTag</A></STRONG><DD>

Defines an ending [/tag] to encapsulate your text -- the text in between
the beginning <CODE>[tagname]</CODE> and ending <CODE>[/tagname]</CODE> will be the last argument sent to the defined subroutine.

<P>
<PRE>    UserTag tagname HasEndTag
</PRE>
<P><DT><STRONG><A NAME="item_Implicit">Implicit</A></STRONG><DD>

This defines a tag as implicit, meaning it can just be an <CODE>attribute</CODE> 
instead of an <CODE>attribute=value</CODE> pair. It must be a recognized attribute in the tag definition, or there
will be big problems. Use this with caution!

<P>
<PRE>    UserTag tagname Implicit attribute value
</PRE>
<P>
If you want to set a standard include file to a fixed value by default, but
don't want to have to specify <CODE>[include file=&quot;/long/path/to/file&quot;]</CODE>
every time, you can just put:

<P>
<PRE>    UserTag include Implicit file file=/long/path/to/file
</PRE>
<P>
and <CODE>[include file]</CODE> will be the equivalent. You can still specify another value with C[include
file=``/another/path/to/file'']

<P><DT><STRONG><A NAME="item_InsertHTML">InsertHTML</A></STRONG><DD>

This attribute makes 
<FONT SIZE=-1>HTML</FONT> tag output be inserted into the containing tag,
in effect adding an attribute=value pair (or pairs).

<P>
<PRE>    UserTag tagname InsertHTML   htmltag  mvtag|mvtag2|mvtagN
</PRE>
<P>
In MiniVend's standard tags, among others, the 
<FONT SIZE=-1>&lt;OPTION</FONT> ...&gt; tag has the [selected ..] and
[checked ...] tags included with them, so that you can do:

<P>
<PRE>   &lt;INPUT TYPE=checkbox
        MV=&quot;checked mvshipmode upsg&quot; NAME=mv_shipmode&gt; UPS Ground shipping
</PRE>
<P>
to expand to this:

<P>
<PRE>   &lt;INPUT TYPE=checkbox CHECKED NAME=mv_shipmode&gt; UPS Ground shipping
</PRE>
<P>
Providing, of course, that <CODE>mv_shipmode</CODE>  <STRONG>is</STRONG> equal to <CODE>upsg</CODE>. If you want to turn off this behavior on a per-tag basis, add the
attribute mv.noinsert=1 to the tag on your page.

<P><DT><STRONG><A NAME="item_InsideHTML">InsideHTML</A></STRONG><DD>

To make a container tag be placed <STRONG>after</STRONG> the containing 
<FONT SIZE=-1>HTML</FONT> tag, use the InsideHTML setting.

<P>
<PRE>    UserTag tagname InsideHTML   htmltag  mvtag|mvtag2|mvtagN
</PRE>
<P>
In MiniVend's standard tags, the only InsideHTML tag is the &lt;
<FONT SIZE=-1>SELECT&gt;</FONT> tag when used with <EM>loop</EM>, which causes this:

<P>
<PRE>   &lt;SELECT MV=&quot;loop upsg upsb upsr&quot; NAME=mv_shipmode&gt;
   &lt;OPTION VALUE=&quot;[loop-code]&quot;&gt; [shipping-desc [loop-code]]
   &lt;/SELECT&gt;
</PRE>
<P>
to expand to this:

<P>
<PRE>   &lt;SELECT NAME=mv_shipmode&gt;
   [loop upsg upsb upsr]
   &lt;OPTION VALUE=&quot;[loop-code]&quot;&gt; [shipping-desc [loop-code]]
   [/loop]
   &lt;/SELECT&gt;
</PRE>
<P>
Without the InsideHTML setting, the [loop ...] would have been <STRONG>outside</STRONG>
of the select -- not what you want. If you want to turn off this behavior
on a per-tag basis, add the attribute mv.noinside=1 to the tag on your
page.

<P><DT><STRONG><A NAME="item_Interpolate">Interpolate</A></STRONG><DD>

The behavior for this attribute depends on whether the tag is a container
(i.e. <A HREF="#item_HasEndTag">HasEndTag</A> is defined). If it is not a container, the <A HREF="#item_Interpolate">Interpolate</A>
attribute causes the <STRONG>the resulting HTML</STRONG> from the <CODE>UserTag</CODE> will be re-parsed for more MiniVend tags. If it is a container, <A HREF="#item_Interpolate">Interpolate</A>
causes the contents of the tag to be parsed <STRONG>before</STRONG> the tag routine is run.

<P>
<PRE>    UserTag tagname Interpolate
</PRE>
<P><DT><STRONG><A NAME="item_InvalidateCache">InvalidateCache</A></STRONG><DD>

If this is defined, the presence of the tag on a page will prevent search
cache, page cache, and static builds from operating on the page.

<P>
<PRE>    UserTag tagname InvalidateCache
</PRE>
<P>
It does not override [tag flag build][/tag], though.

<P><DT><STRONG><A NAME="item_Order">Order</A></STRONG><DD>

The optional arguments that can be sent to the tag. This defines not only
the order in which they will be passed to <EM>Routine</EM>, but the name of the tags. If encapsulated text is appropriate (<EM>HasEndTag</EM> is set), it will be the last argument.

<P>
<PRE>    UserTag tagname Order param1 param2
</PRE>
<P><DT><STRONG><A NAME="item_PosRoutine">PosRoutine</A></STRONG><DD>

Identical to the Routine argument -- a subroutine that will be called when
the new syntax is not used for the call, i.e. <CODE>[usertag argument]</CODE> instead of <CODE>[usertag ARG=argument]</CODE>. If not defined, <EM>Routine</EM> is used, and MiniVend will usually do the right thing.

<P><DT><STRONG><A NAME="item_ReplaceAttr">ReplaceAttr</A></STRONG><DD>

Works in concert with InsertHTML, defining a <STRONG>single</STRONG> attribute which will be replaced in the insertion operation..

<P>
<PRE>  UserTag tagname ReplaceAttr  htmltag attr
</PRE>
<P>
An example is the standard 
<FONT SIZE=-1>HTML</FONT> &lt;
<FONT SIZE=-1>A</FONT> 
<FONT SIZE=-1>HREF=...&gt;</FONT> tag. If you want to use the MiniVend tag
 <CODE>[area pagename]</CODE> inside of it, then you would normally want to replace the 
<FONT SIZE=-1>HREF</FONT> attribute. So the equivalent to the following is
defined within MiniVend:

<P>
<PRE>  UserTag  area  ReplaceAttr  a  href
</PRE>
<P>
Causing this

<P>
<PRE>    &lt;A MV=&quot;area pagename&quot; HREF=&quot;a_test_page.html&quot;&gt;
</PRE>
<P>
to become

<P>
<PRE>    &lt;A HREF=&quot;<A HREF="http://yourserver/cgi/simple/pagename?X8sl2lly">http://yourserver/cgi/simple/pagename?X8sl2lly</A>;;44&quot;&gt;
 
when intepreted.
    
=item ReplaceHTML
</PRE>
<P>
For HTML-style tag use only. Causes the tag containing the MiniVend tag to
be stripped and the result of the tag to be inserted, for certain tags. For
example:

<P>
<PRE>  UserTag company_name Routine sub { my $l = shift; return &quot;$l: XYZ Company&quot; }
  UserTag company_name HasEndTag
  UserTag company_name ReplaceHTML  b    company_name
</PRE>
<P>

<FONT SIZE=-1>&lt;BR&gt;</FONT> is the 
<FONT SIZE=-1>HTML</FONT> tag, and ``company_name'' is the MiniVend tag. At that point, the usage:


<P>
<PRE>    &lt;B MV=&quot;company-name&quot;&gt; Company &lt;/B&gt;  ---&gt;&gt;  Company: XYZ Company
</PRE>
<P>
Tags not in the list will not be stripped:

<P>
<PRE>    &lt;I MV=&quot;company-name&quot;&gt; Company &lt;/I&gt; ---&gt;&gt;  &lt;I&gt;Company: XYZ Company&lt;/I&gt;
</PRE>
<P><DT><STRONG><A NAME="item_Routine">Routine</A></STRONG><DD>

An inline subroutine that will be used to process the arguments of the tag.
It must not be named, and will be allowed to access unsafe elements only if
the <CODE>minivend.cfg</CODE> parameter <EM>AllowGlobal</EM> is set for the catalog.

<P>
<PRE>    UserTag tagname Routine  sub { &quot;your perl code here!&quot; }
</PRE>
<P>
The routine may use a ``here'' document for readability:

<P>
<PRE>    UserTag tagname Routine &lt;&lt;EOF
    sub {
        my ($param1, $param2, $text) = @_;
        return &quot;Parameter 1 is $param1, Parameter 2 is $param2&quot;;
    }
    EOF
</PRE>
<P>
The usual <EM>here documents</EM> caveats apply.

<P>
Parameters defined with the <EM>Order</EM> property will be sent to the routine first, followed by any encapsulated
text (<EM>HasEndTag</EM> is set).

<P></DL>
<P>
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-)

</BODY>

</HTML>


code: 01.02
section: MINIVEND_TAG_REFERENCE
type: item
title: [accessories ...]

<A NAME="_accessories_">[accessories ...]</A></H2>
<P>
named: [accessories code=``code'' arg=``attribute*, type*, field*,
database*, name*, outboard*'']

<P>
positional: [accessories code attribute*, type*, field*, database*, name*,
outboard*]

<P>
If not given one of the optional arguments, expands into the value of the
accessories database entry for the product identified by <EM>code</EM> as found in the products database.

<P>
If passed any of the optional arguments, initiates special processing of
item attributes based on entries in the product database.

<P>
See <EM>Item Attributes</EM> for a complete description of the arguments.

<P>
When called with an attribute, the database is consulted and looks for a
comma-separated list of attribute options. They take the form:

<P>
<PRE>    name=Label Text, name=Label Text*
</PRE>
<P>
The label text is optional -- if none is given, the <STRONG>name</STRONG> will be used.

<P>
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:

<P>
<PRE>    [accessories TK112 color]
</PRE>
<P>
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:

<P>
<PRE>    &lt;SELECT NAME=&quot;mv_order_color&quot;&gt;
    &lt;OPTION VALUE=&quot;beige&quot;&gt;Almond
    &lt;OPTION VALUE=&quot;gold&quot;&gt;Harvest Gold
    &lt;OPTION SELECTED&gt;White
    &lt;OPTION VALUE=&quot;green&quot;&gt;Avocado
    &lt;/SELECT&gt;
</PRE>
<P>
In combination with the <EM>mv_order_item</EM> and <EM>mv_order_quantity</EM> variables this can be used to allow entry of an attribute at time of order.

<P>
<HR>


code: 01.03
section: MINIVEND_TAG_REFERENCE
type: item
title: [area ...]

<A NAME="_area_">[area ...]</A></H2>
<P>
named: [area href=``dir/page'' secure=1* arg=``argument''* form=``form
string''*]

<P>
positional: [area pg arg*]

<P>

<FONT SIZE=-1>HTML</FONT> example: 
<FONT SIZE=-1>&lt;A</FONT> MV=``area dir/page'' HREF=``dir/page.html''&gt;


<P>
Produces the 
<FONT SIZE=-1>URL</FONT> to call a MiniVend page, without the surrounding 
<FONT SIZE=-1>A</FONT> 
<FONT SIZE=-1>HREF</FONT> notation. This can be used to get control of your 
<FONT SIZE=-1>HREF</FONT> items, perhaps to place an 
<FONT SIZE=-1>ALT</FONT> string or a Javascript construct. It was originally named
 <CODE>area</CODE> because it also can be used in a client-side image map.

<P>
<PRE>   &lt;A HREF=&quot;[area catalog]&quot; ALT=&quot;Main catalog page&quot;&gt;
</PRE>
<P>
The optional <EM>arg</EM> is used just as in the <EM>page</EM> tag.

<P>
The optional <CODE>form</CODE> argument allows you to encode a form in the link.

<P>
<PRE>        &lt;A HREF=&quot;[area form=&quot;
                mv_order_item=99-102
                mv_order_size=L
                mv_order_quantity=1
                mv_separate_items=1
                mv_todo=refresh&quot;
                ]&quot;&gt; Order t-shirt in Large size &lt;/A&gt;
</PRE>
<P>
The two form values <EM>mv_session_id</EM> and <EM>mv_arg</EM> are automatically added when appropriate. (<EM>mv_arg</EM> is the <CODE>arg</CODE> parameter for the tag.)

<P>
If the parameter <CODE>href</CODE> is not supplied, <EM>process</EM> is used, causing normal MiniVend form processing.

<P>
This would generate a form that ordered item number 99-102 on a separate
line (<CODE>mv_separate_items</CODE> being set), with size <CODE>L</CODE>, in quantity 2. Since the page is not set, you will go to the default
shopping cart page -- equally you could set <CODE>mv_orderpage=yourpage</CODE>
to go to <CODE>yourpage</CODE>.

<P>
You must have TolerateGet set (which is the default) and all normal
MiniVend form caveats apply -- you must have an action, you must supply a
page if you don't want to go to the default, etc.

<P>
You can theoretically submit any form with this, though none of the
included values can have newlines or trailing whitespace. If you want to do
something like that you will have to write a UserTag.

<P>
<HR>


code: 01.04
section: MINIVEND_TAG_REFERENCE
type: item
title: [areatarget ...]

<A NAME="_areatarget_">[areatarget ...]</A></H2>
<P>
named: [areatarget href=``dir/page'' target=``frame'' arg=``argument'']

<P>
positional: [areatarget pg frame arg*]

<P>
Inserts a Vend 
<FONT SIZE=-1>URL</FONT> in a format to provide a targeted reference for a client-side imagemap. You set up the 
<FONT SIZE=-1>&lt;AREA&gt;</FONT> tag with:


<P>
<PRE>      &lt;AREA COORDS=&quot;220,0,270,20&quot; HREF=&quot;[areatarget page frame]&quot;&gt;
</PRE>
<P>
If frames are enabled, this will expand to:

<P>
<PRE>      &lt;AREA COORDS=&quot;220,0,270,20&quot;
         HREF=&quot;<A HREF="http://machine.company.com/vlink/page?ErTxVV8l">http://machine.company.com/vlink/page?ErTxVV8l</A>;;38&quot; TARGET=&quot;frame&quot;&gt;
</PRE>
<P>
If frames are <EM>not</EM> enabled, this will expand to:

<P>
<PRE>      &lt;AREA COORDS=&quot;220,0,270,20&quot;
         HREF=&quot;<A HREF="http://machine.company.com/vlink/page?ErTxVV8l">http://machine.company.com/vlink/page?ErTxVV8l</A>;;38&quot;&gt;
</PRE>
<P>
<HR>


code: 01.05
section: MINIVEND_TAG_REFERENCE
type: item
title: [body ...]

<A NAME="_body_">[body ...]</A></H2>
<P>
named: [body type=``n'' extra=``ATTRIBUTE'']

<P>
positional: [body n extra*]

<P>
Selects from the predefined color schemes and/or backgrounds, and just
becomes a &lt;
<FONT SIZE=-1>BODY&gt;</FONT> tag if none are defined. The <CODE>extra</CODE> parameter is always appended. See <EM>CONTROLLING PAGE APPEARANCE</EM>.

<P>
<HR>


code: 01.06
section: MINIVEND_TAG_REFERENCE
type: item
title: [buttonbar ...]

<A NAME="_buttonbar_">[buttonbar ...]</A></H2>
<P>
named: [buttonbar type=``n'']

<P>
positional: [buttonbar n]

<P>

<FONT SIZE=-1>AUTOINTERPOLATE:</FONT> Yes, can be turned off with 
<FONT SIZE=-1>INTERPOLATE=0</FONT>


<P>
Selects from the predefined buttonbars, and is stripped if it doesn't
exist. See <EM>CONTROLLING PAGE APPEARANCE</EM>. This is somewhat superceded by Variable and [include filename].

<P>
<HR>


code: 01.07
section: MINIVEND_TAG_REFERENCE
type: item
title: [calc]

<A NAME="_calc_">[calc]</A></H2>
<P>
syntax: [calc] 
<FONT SIZE=-1>EXPRESSION</FONT> [/calc]

<P>

<FONT SIZE=-1>AUTOINTERPOLATE:</FONT> Yes, can be turned off with 
<FONT SIZE=-1>INTERPOLATE=0</FONT>


<P>
Starts a region where the arguments are calculated according to normal
arithmetic symbols. For instance:

<P>
<PRE>    [calc] 2 + 2 [/calc]
</PRE>
<P>
will display:

<P>
<PRE>    4
</PRE>
<P>
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.

<P>

<FONT SIZE=-1>TIP:</FONT> The [calc] tag will remember variable values
inside one page, so you can do the equivalent of a memory store and memory
recall for a loop.

<P>
<HR>


code: 01.08
section: MINIVEND_TAG_REFERENCE
type: item
title: [cart ...]

<A NAME="_cart_">[cart ...]</A></H2>
<P>
named: [cart name=``name'']

<P>
positional: [cart name]

<P>
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 <EM>PriceAdjustment</EM>
feature to set it.

<P>
<HR>


code: 01.09
section: MINIVEND_TAG_REFERENCE
type: item
title: [checked ...]

<A NAME="_checked_">[checked ...]</A></H2>
<P>
named: [checked name=``var_name'' value=``value'']

<P>
positional: [checked var_name value]

<P>
You can provide a ``memory'' for drop-down menus, radio buttons, and
checkboxes with the [checked] and [selected] tags.

<P>
This will output 
<FONT SIZE=-1>CHECKED</FONT> if the variable <CODE>var_name</CODE> is equal to
<A HREF="#item_value">value</A>. Not case sensitive.

<P>
<HR>


code: 01.10
section: MINIVEND_TAG_REFERENCE
type: item
title: [comment] ...]

<A NAME="_comment_">[comment] ...]</A></H2>
<P>
syntax: [comment] code [/comment]

<P>
Comments out MiniVend tags (and anything else) from a page. The contents
are not displayed unless DisplayComments is set in minivend.cfg. Can be
nested.

<P>
<HR>


code: 01.11
section: MINIVEND_TAG_REFERENCE
type: item
title: [currency ...]

<A NAME="_currency_">[currency ...]</A></H2>
<P>
named: [currency convert=1*] number [/currency]

<P>
positonal: [currency convert*]

<P>

<FONT SIZE=-1>AUTOINTERPOLATE:</FONT> Yes, can be turned off with 
<FONT SIZE=-1>INTERPOLATE=0</FONT>


<P>
When passed a value of a single number, formats it according to the
currency specification. For instance:

<P>
<PRE>    [currency]4[/currency]
</PRE>
<P>
will display:

<P>
<PRE>    4.00
</PRE>
<P>
Uses the <EM>Locale</EM> and <EM>PriceCommas</EM> settings as appropriate, and can contain a [calc] region. If the optional
``convert'' parameter is set, it will convert according to PriceDivide&gt;
for the current locale. If Locale is set to <CODE>fr_FR</CODE>, and <EM>PriceDivide</EM> for <CODE>fr_FR</CODE> is 0.167, the following sequence

<P>
<PRE>    [currency convert=1] [calc] 500.00 + 1000.00 [/calc] [/currency]
</PRE>
<P>
will cause the number 8.982,04 to be displayed.

<P>
<HR>


code: 01.12
section: MINIVEND_TAG_REFERENCE
type: item
title: [data ...]

<A NAME="_data_">[data ...]</A></H2>
<P>
named: [data base=``database'' field=``field'' key=``key'' value=``value''
op=``increment] )

<P>
positional: [data area field key ``value''* increment*]

<P>

<FONT SIZE=-1>HTML</FONT> example: 
<FONT SIZE=-1>&lt;PARAM</FONT> MV=data MV.TABLE=database MV.COL=field MV.ROW=key&gt;


<P>
Returns the value of the field in any of the arbitrary databases, or from
the variable namespaces. If the optional <STRONG>value</STRONG> 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 <STRONG>value</STRONG>.

<P>
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 <CODE>products</CODE> database writable, for example.

<P>
In addition, the <A HREF="#item__data_">[data ...]</A> tag can access a number of elements in the MiniVend session database:

<P>
<PRE>    accesses      Accesses within the last 30 seconds
    arg           The argument passed in a [page ...] or [area ...] tag
    browser       The user browser string
    host          MiniVend's idea of the host (modified by DomainTail)
    last_error    The last error from the error logging
    last_url      The current MiniVend path_info
    logged_in     Whether the user is logged in (add-on UserDB feature)
    pageCount     Number of unique URLs generated
    prev_url      The previous path_info
    referer       HTTP_REFERER string
    ship_message  The last error messages from shipping
    source        Source of original entry to MiniVend
    time          Time (seconds since Jan 1, 1970) of last access
    user          The REMOTE_USER string
    username      User name logged in as (add-on UserDB feature)
</PRE>
<P>
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.

<P>
<HR>


code: 01.13
section: MINIVEND_TAG_REFERENCE
type: item
title: [default ...]

<A NAME="_default_">[default ...]</A></H2>
<P>
named: [default name=``variable'' default=``default value'' set=1*]

<P>
positional: [default variable value*]

<P>

<FONT SIZE=-1>HTML</FONT> example: 
<FONT SIZE=-1>&lt;PARAM</FONT> MV=``default'' MV.NAME=variable MV.DEFAULT=``default'' 
<FONT SIZE=-1>MV.</FONT> set=1&gt;


<P>
Returns the value of the user form variable <CODE>variable</CODE> if it is non-empty. Otherwise returns <CODE>default</CODE>, which is the string ``default'' if there is no default supplied. Got
that?

<P>
If the flag <CODE>set</CODE> is present and non-zero, then the variable will be set to the <CODE>default</CODE> and <EM>no value returned to the page</EM>. This allows you to initialize things like country, shipping mode, and
other values on a checkout page.

<P>
<HR>


code: 01.14
section: MINIVEND_TAG_REFERENCE
type: item
title: [description ...]

<A NAME="_description_">[description ...]</A></H2>
<P>
named: [description code=``code'' base=``database'']

<P>
positonal: [description code database*]

<P>
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 <STRONG>base</STRONG>.

<P>
<HR>


code: 01.15
section: MINIVEND_TAG_REFERENCE
type: item
title: [discount ...]

<A NAME="_discount_">[discount ...]</A></H2>
<P>
named: [discount code=key]

<P>
positional: [discount code]

<P>
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:

<P>
<PRE>    1. A discount for one particular item code (code/key is the item-code)
    2. A discount applying to all item codes (code/key is ALL_ITEMS)
    3. A discount applied after all items are totaled
       (code/key is ENTIRE_ORDER)
</PRE>
<P>
The discounts are specified via a formula. The formula is scanned for the
variables <CODE>$q</CODE> and $s, which are substituted for with the item
<EM>quantity</EM> and <EM>subtotal</EM> respectively. In the case of the item and all items discount, the formula
must evaluate to a new subtotal for all items <EM>of that code</EM> 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.

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

<P>
To apply a straight 20% discount to all items:

<P>
<PRE>    [discount ALL_ITEMS] $s * .8 [/discount]
</PRE>
<P>
or with named attributes:

<P>
<PRE>    [discount code=ALL_ITEMS] $s * .8 [/discount]
</PRE>
<P>
To take 25% off of only item 00-342:

<P>
<PRE>    [discount 00-342] $s * .75 [/discount]
</PRE>
<P>
To subtract $5.00 from the customer's order:

<P>
<PRE>    [discount ENTIRE_ORDER] $s - 5 [/discount]
</PRE>
<P>
To reset a discount, set it to the empty string: 

<P>
<PRE>        [discount ALL_ITEMS][/discount]
</PRE>
<P>
Perl code can be used to apply the discounts. Here is an example of a
discount for item code 00-343 which prices the <EM>second</EM> one ordered at 1 cent:

<P>
<PRE>    [discount 00-343]
    return $s if $q == 1;
    my $p = $s/$q;
    my $t = ($q - 1) * $p;
    $t .= 0.01;
    return $t;
    [/discount]
</PRE>
<P>
If you want to display the discount amount, use the [item-discount] tag.

<P>
<PRE>    [item-list]
    Discount for [item-code]: [item-discount]
    [/item-list]
</PRE>
<P>
Finally, if you want to display the discounted subtotal, you need to use
the [calc] capability:

<P>
<PRE>    [item-list]
    Discounted subtotal for [item-code]: [currency][calc]
                                            [item-price] * [item-quantity]
                                            [/calc][/currency]
    [/item-list]
</PRE>
<P>
<HR>


code: 01.16
section: MINIVEND_TAG_REFERENCE
type: item
title: [field ...]

<A NAME="_field_">[field ...]</A></H2>
<P>
named: [field code=``code'' name=``fieldname'']

<P>
positional: [field name code]

<P>

<FONT SIZE=-1>HTML</FONT> example: 
<FONT SIZE=-1>&lt;PARAM</FONT> MV=field MV.COL=column MV.ROW=key&gt;


<P>
Expands into the value of the field <EM>name</EM> for the product identified by <EM>code</EM> as found by searching the products database. It will return the first entry
found in the series of <EM>Product Files</EM>. the products database. If you want to constrain it to a particular
database, use the [data base name code] tag.

<P>
<HR>


code: 01.17
section: MINIVEND_TAG_REFERENCE
type: item
title: [file ...]

<A NAME="_file_">[file ...]</A></H2>
<P>
named: [file name=``name'' type=``dos|mac|unix''*]

<P>
positional: [file name]

<P>
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 <EM>NoAbsolute</EM>.

<P>
The optional <A HREF="#item_type">type</A> parameter will do an appropriate 
<FONT SIZE=-1>ASCII</FONT> translation on the file before it is sent.

<P>
<HR>


code: 01.18
section: MINIVEND_TAG_REFERENCE
type: item
title: [fly-list ...]

<A NAME="_fly_list_">[fly-list ...]</A></H2>
<P>
named: [fly-list code=``product_code'' base=``table''] ... [/fly-list]

<P>
``NewTags Yes'' mode only.

<P>
Defines an area in a random page which performs the flypage lookup
function, implementing the tags below.

<P>
<PRE>   [fly-list code=&quot;[data session arg]&quot;]
    (contents of flypage.html)
   [/fly-list]
</PRE>
<P>
If you place the above around the contents of the demo flypage, in a file
named <CODE>flypage2.html</CODE>, it will make these two calls display identical pages:

<P>
<PRE>    [page 00-0011] One way to display the Mona Lisa [/page]
    [page flypage2 00-0011] Another way to display the Mona Lisa [/page]
</PRE>
<P>
<HR>


code: 01.19
section: MINIVEND_TAG_REFERENCE
type: item
title: [framebase ...]

<A NAME="_framebase_">[framebase ...]</A></H2>
<P>
named: [framebase name]

<P>
Outputs a 
<FONT SIZE=-1>&lt;BASE</FONT> FRAME=``name''&gt; tag only if MiniVend is in frames mode. It should be used within the 
<FONT SIZE=-1>HTML</FONT> 
<FONT SIZE=-1>&lt;HEAD&gt;</FONT> section.


<P>
<HR>


code: 01.20
section: MINIVEND_TAG_REFERENCE
type: item
title: [frames_off]

<A NAME="_frames_off_">[frames_off]</A></H2>
<P>
named: [frames_off]

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

<P>

<FONT SIZE=-1>IMPORTANT</FONT> 
<FONT SIZE=-1>NOTE:</FONT> This doesn't turn of frames in your browser! If you let a 
<FONT SIZE=-1>TARGET</FONT> tag escape, it will probably cause a new window to be opened, or other types of anomalous operation.


<P>
<HR>


code: 01.21
section: MINIVEND_TAG_REFERENCE
type: item
title: [frames_on]

<A NAME="_frames_on_">[frames_on]</A></H2>
<P>
named: [frames_on]

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


<P>
<HR>


code: 01.22
section: MINIVEND_TAG_REFERENCE
type: item
title: [if ...]

<A NAME="_if_">[if ...]</A></H2>
<P>
named: [if type=``type'' term=``field'' op=``op'' compare=``compare'']

<P>
positional: [if type field op* compare*]

<P>
negated: [if type=``!type'' term=``field'' op=``op'' compare=``compare'']

<P>
positional: [if !type field op* compare*]

<P>
Allows conditional building of 
<FONT SIZE=-1>HTML</FONT> based on the setting of various MiniVend session
and database values. The general form is:

<P>
<PRE>    [if type term op compare]
    [then]
                                If true, this is printed on the document.
                                The [then] [/then] is optional in most
                                cases. If ! is prepended to the type
                                setting, the sense is reversed and
                                this will be output for a false condition.
    [/then]
    [elsif type term op compare]
                                Optional, tested when if fails
    [/elsif] 
    [else]
                                Optional, printed when all above fail
    [/else]
    [/if]
</PRE>
<P>
The <CODE>[if]</CODE> tag can also have some variants:

<P>
<PRE>    [if explicit][condition] CODE [/condition]
                Displayed if valid Perl CODE returns a true value.
    [/if]
</PRE>
<P>
You can do some Perl-style regular expressions:

<P>
<PRE>    [if value name =~ /^mike/]
                                This is the if with Mike.
    [elsif value name =~ /^sally/]
                                This is an elsif with Sally.
    [/elsif]
    [elsif value name =~ /^pat/]
                                This is an elsif with Pat.
    [/elsif]
    [else]
                                This is the else, no name I know.
    [/else]
    [/if]
</PRE>
<P>
While the new tag syntax works for <CODE>[if ...]</CODE>, 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]

<P>
Oops! This will not work with the new parser. You must do instead

<P>
<PRE>    [compat]
    [if value name =~ /[value b_name]/]
        Shipping name matches billing name.
    [/if]
    [/compat]
</PRE>
<P>
or

<P>
<PRE>    [if type=value term=name op=&quot;=~&quot; compare=&quot;/[value b_name]/&quot;]
        Shipping name matches billing name.
    [/if]
</PRE>
<P>
The latter has the advantage of working with any tag:

<P>
<PRE>    [if type=value term=high_water op=&quot;&lt;&quot; compare=&quot;[shipping]&quot;]
        Shipping cost is too high, charter a truck.
    [/if]
</PRE>
<P>
If you wish to do 
<FONT SIZE=-1>AND</FONT> and 
<FONT SIZE=-1>OR</FONT> operations, you will have to use
 
<CODE>[if explicit]</CODE>. This allows complex testing and parsing of values.

<P>
There are many test targets available:

<DL>
<DT><STRONG><A NAME="item_config">config Directive</A></STRONG><DD>

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

<P>
<PRE>    [if config CreditCardAuto]
    Auto credit card validation is enabled.
    [/if]
</PRE>
<P><DT><STRONG><A NAME="item_data">data  database::field::key</A></STRONG><DD>

The MiniVend databases. Retrieves a field in the database and returns true
or false based on the value.

<P>
<PRE>    [if data products::size::99-102]
    There is size information.
    [else]
    No size information.
    [/else]
    [/if]
</PRE>
<P>
<PRE>    [if data products::size::99-102 =~ /small/i]
    There is a small size available.
    [else]
    No small size available.
    [/else]
    [/if]
</PRE>
<P><DT><STRONG><A NAME="item_discount">discount</A></STRONG><DD>

Checks to see if a discount is present for an item.

<P>
<PRE>    [if discount 99-102]
    Item is discounted.
    [/if]
</PRE>
<P><DT><STRONG><A NAME="item_explicit">explicit</A></STRONG><DD>


<FONT SIZE=-1>A</FONT> test for an explicit value. If perl code is placed
between a [condition] [/condition] tag pair, it will be used to make the
comparison. Arguments can be passed to import data from user space, just as
with the [perl] tag.

<P>
<PRE>    [if explicit]
    [condition]
        $country = '[value country]';
        return 1 if $country =~ /u\.?s\.?a?/i;
        return 0;
    [/condition]
    You have indicated a US address.
    [else]
    You have indicated a non-US address. 
    [/else]
    [/if]
</PRE>
<P>
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.

<P>
This will work for <EM>Variable</EM> values:

<P>
<PRE>    [if explicit &quot;__MYVAR__&quot;] .. [/if]
</PRE>
<P><DT><STRONG><A NAME="item_file">file</A></STRONG><DD>

Tests for existence of a file. Useful for placing image tags only if the
image is present.

<P>
<PRE>    [if file /home/user/www/images/[item-code].gif]
    &lt;IMG SRC=&quot;[item-code].gif&quot;&gt;
    [/if]
</PRE>
<P>
The <A HREF="#item_file">file</A> test requires that the <EM>SafeUntrap</EM> directive contains
<CODE>ftfile</CODE> (which is the default).

<P><DT><STRONG><A NAME="item_items">items</A></STRONG><DD>

The MiniVend shopping carts. If not specified, the cart used is the main
cart. Usually used as a litmus test to see if anything is in the cart, for
example:

<P>
<PRE>  [if items]You have items in your shopping cart.[/if]
  
  [if items layaway]You have items on layaway.[/if]
</PRE>
<P><DT><STRONG><A NAME="item_ordered">ordered</A></STRONG><DD>

Order status of individual items in the MiniVend shopping carts. If not
specified, the cart used is the main cart. The following items refer to a
part number of 99-102.

<P>
<PRE>  [if ordered 99-102] ... [/if]
    Checks the status of an item on order, true if item
    99-102 is in the main cart.
</PRE>
<P>
<PRE>  [if ordered 99-102 layaway] ... [/if]
    Checks the status of an item on order, true if item
    99-102 is in the layaway cart.
</PRE>
<P>
<PRE>  [if ordered 99-102 main size] ... [/if]
    Checks the status of an item on order in the main cart,
    true if it has a size attribute.
</PRE>
<P>
<PRE>  [if ordered 99-102 main size =~ /large/i] ... [/if]
    Checks the status of an item on order in the main cart,
    true if it has a size attribute containing 'large'.
    THE CART NAME IS REQUIRED IN THE OLD SYNTAX. The new
    syntax for that one would be:
</PRE>
<P>
<PRE>    [if type=ordered term=&quot;99-102&quot; compare=&quot;size =~ /large/i&quot;]
</PRE>
<P>
<PRE>    To make sure it is exactly large, you could use:
</PRE>
<P>
<PRE>    [if ordered 99-102 main size eq 'large'] ... [/if]
</PRE>
<P>
<PRE>  [if ordered 99-102 main lines] ... [/if]
      Special case -- counts the lines that the item code is
      present on. (Only useful, of course, when mv_separate_items
      or SeparateItems is defined.)
</PRE>
<P><DT><STRONG><A NAME="item_salestax">salestax</A></STRONG><DD>

The salestax database.

<P>
<PRE>    [if salestax [value state] &gt; 0]
    There is salestax for your state.
    [else]
    No salestax for your state.
    [/else]
    [/if]
</PRE>
<P>
Key matching is case-insensitive.

<P><DT><STRONG><A NAME="item_scratch">scratch</A></STRONG><DD>

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

<P>
<PRE>    [if scratch mv_separate_items]
    Ordered items will be placed on a separate line.
    [else]
    Ordered items will be placed on the same line.
    [/else]
    [/if]
</PRE>
<P><DT><STRONG><A NAME="item_session">session</A></STRONG><DD>

The MiniVend session variables. Of particular interest are <EM>login</EM>, <EM>frames</EM>, <EM>secure</EM>, and <EM>browser</EM>.

<P><DT><STRONG><A NAME="item_shipping">shipping</A></STRONG><DD>

The shipping database.

<P><DT><STRONG><A NAME="item_validcc">validcc</A></STRONG><DD>


<FONT SIZE=-1>A</FONT> special case, takes the form [if validcc no type exp_date]. Evaluates to true if the supplied credit card number, type of card, and expiration date pass a validity test. Does a 
<FONT SIZE=-1>LUHN-10</FONT> calculation to weed out typos or phony card numbers.


<P><DT><STRONG><A NAME="item_value">value</A></STRONG><DD>

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

<P></DL>
<P>
The <EM>field</EM> term is the specifier for that area. For example, [if session frames] would
return true if the <A HREF="#item_frames">frames</A> session parameter was set.

<P>
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:

<P>
<PRE>    [if session frames]
        [buttonbar 1]
    [else]
        [buttonbar 2]
    [/else]
    [/if]
</PRE>
<P>
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:

<P>
<PRE>    [if value mv_match_count != 1]
        [value mv_match_count] matches found.
    [else]
        Only one match was found.
    [/else]
    [/if]
</PRE>
<P>
The <EM>op</EM> term is the compare operation to be used. Compare operations are as in
Perl:

<P>
<PRE>    ==  numeric equivalence
    eq  string equivalence
    &gt;   numeric greater-than
    gt  string greater-than
    &lt;   numeric less-than
    lt  string less-than
    !=  numeric non-equivalence
    ne  string equivalence
</PRE>
<P>
Any simple perl test can be used, including some limited regex matching.
More complex tests are best done with <CODE>[if explicit]</CODE>.

<DL>
<DT><STRONG><A NAME="item__then_">[then] text [/then]</A></STRONG><DD>

This is optional if you are not nesting if conditions, as the text
immediately following the [if ..] tag is used as the conditionally
substituted text. If nesting [if ...] tags you should use a [then][/then]
on any outside conditions to ensure proper interpolation.

<P><DT><STRONG><A NAME="item__elsif">[elsif type field op* compare*]</A></STRONG><DD>

named attributes: [elsif type=``type'' term=``field'' op=``op''
compare=``compare'']

<P>
Additional conditions for test, applied if the initial <CODE>[if ..]</CODE> test fails.

<P><DT><STRONG><A NAME="item__else_">[else] text [/else]</A></STRONG><DD>

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

<P><DT><STRONG><A NAME="item__condition_">[condition] text [/condition]</A></STRONG><DD>

Only used with the [if explicit] tag. Allows an arbitrary expression
<STRONG>in Perl</STRONG> to be placed inside, with its return value interpreted as the result of the
test. If arguments are added to [if explicit args], those will be passed as
arguments are in the <EM>[perl]</EM> construct.

<P></DL>
<P>
<HR>


code: 01.23
section: MINIVEND_TAG_REFERENCE
type: item
title: [import table type*] RECORD [/import]

<A NAME="_import_table_type_RECORD_im">[import table type*] RECORD [/import]</A></H2>
<P>
Named attributes:

<P>
<PRE>    [import table=table_name
            type=(TAB|PIPE|CSV|%%|LINE)
            continue=(NOTES|UNIX|DITTO)
            separator=c]
</PRE>
<P>
Import one or more records into a database. The <A HREF="#item_type">type</A> is any of the valid MiniVend delimiter types, with the default being
defined by the setting of <EM>Delimiter</EM>. The table must already be a defined MiniVend database table; it cannot be created on the fly. (If you need that, it is time to use 
<FONT SIZE=-1>SQL.)</FONT>


<P>
The <A HREF="#item_type">type</A> of <CODE>LINE</CODE> and <CODE>continue</CODE> setting of <CODE>NOTES</CODE> is particularly useful, for it allows you to name your fields and not have
to remember the order in which they appear in the database. The following
two imports are identical in effect:

<P>
<PRE>    [import table=orders]
    code: [value mv_order_number]
    shipping_mode: [shipping-description]
    status: pending
    [/import]
  
    [import table=orders]
    shipping_mode: [shipping-description]
    status: pending
    code: [value mv_order_number]
    [/import]
</PRE>
<P>
The <A HREF="#item_code">code</A> or key must always be present, and is always named <A HREF="#item_code">code</A>.

<P>
If you do not use <CODE>NOTES</CODE> mode, you must import the fields in the same order as they appear in the 
<FONT SIZE=-1>ASCII</FONT> source file.

<P>
The <CODE>[import ....] TEXT [/import]</CODE> region may contain multiple records. If using <CODE>NOTES</CODE> mode, you must use a separator, which by default is a form-feed character 
<FONT SIZE=-1>(^L).</FONT>

<P>
<HR>


code: 01.24
section: MINIVEND_TAG_REFERENCE
type: item
title: [include ...]

<A NAME="_include_">[include ...]</A></H2>
<P>
named: [include file=``name'']

<P>
positional: [include file]

<P>

<FONT SIZE=-1>AUTOINTERPOLATE:</FONT> 
<FONT SIZE=-1>ALWAYS</FONT> -- even Variable settings are interpolated.


<P>
<STRONG>NOTE:</STRONG> New to MiniVend 3.04.

<P>
Same as <CODE>[file name]</CODE> except interpolates for all MiniVend tags and variables.

<P>
<HR>


code: 01.25
section: MINIVEND_TAG_REFERENCE
type: item
title: [item-accessories ...]

<A NAME="_item_accessories_">[item-accessories ...]</A></H2>
<P>
named: [item-accessories attribute*, type*, field*, database*, name*,
outboard*]

<P>
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 <EM>stacked</EM> on top of each other.

<P>
The configuration file directive <EM>UseModifier</EM> is used to set the name of the modifier or modifiers. For example

<P>
<PRE>    UseModifier        size,color
</PRE>
<P>
will attach both a size and color attribute to each item code that is
ordered.

<P>
<STRONG>IMPORTANT NOTE:</STRONG> You may not use the following names for attributes:

<P>
<PRE>    item  group  quantity  code  mv_ib  mv_mi  mv_si
</PRE>
<P>
You can also set it in scratch with the mv_UseModifier scratch variable --
[set mv_UseModifier]size color[/set] has the same effect as above. This
allows multiple options to be set for products. Whichever one is in effect
at order time will be used. Be careful, you cannot set it more than once on
the same page. Setting the <EM>mv_separate_items</EM> or global directive <EM>SeparateItems</EM>
places each ordered item on a separate line, simplifying attribute
handling. The scratch setting for <CODE>mv_separate_items</CODE> has the same effect.

<P>
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.

<P>
You cannot define a modifier name of <EM>code</EM> or <EM>quantity</EM>, 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. 

<P>
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.

<P>
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.

<P>
<PRE>    &lt;SELECT NAME=&quot;[modifier-name size]&quot;&gt;
    &lt;OPTION  [selected [modifier-name size] S]&gt; S
    &lt;OPTION  [selected [modifier-name size] M]&gt; M
    &lt;OPTION  [selected [modifier-name size] L]&gt; L
    &lt;OPTION [selected [modifier-name size] XL]&gt; XL
    &lt;/SELECT&gt;
</PRE>
<P>
It could just as easily be done with a radio button group combined with the
[checked ...] tag.

<P>
MiniVend 3.0 will automatically generate the above select box when the
[accessories &lt;code&gt; size] or [item-accessories size] tags are called.
They have the syntax:

<P>
<PRE>   [item_accessories attribute*, type*, field*, database*, name*, outboard*]
  
   [accessories code attribute*, type*, field*, database*, name*, outboard*]
</PRE>
<DL>
<DT><STRONG><A NAME="item_code">code</A></STRONG><DD>

Not needed for item-accessories, this is the product code of the item to
reference. =item attribute

<P>
The item attribute as specified in the UseModifier configuration directive.
Typical are <CODE>size</CODE> or <CODE>color</CODE>.

<P><DT><STRONG><A NAME="item_type">type</A></STRONG><DD>

The action to be taken. One of:

<P>
<PRE>  select          Builds a dropdown &lt;SELECT&gt; menu for the attribute.
                  NOTE: This is the default.
 
  multiple        Builds a multiple dropdown &lt;SELECT&gt; menu for the
                  attribute.  The size is equal to the number of
                  option choices.
                   
  display         Shows the label text for *only the selected option*.
   
  show            Shows the option choices (no labels) for the option.
   
  radio           Builds a radio box group for the item, with spaces
                  separating the elements.
                   
  radio nbsp      Builds a radio box group for the item, with &amp;nbsp;
                  separating the elements.
                   
  radio left n    Builds a radio box group for the item, inside a
                  table, with the checkbox on the left side. If &quot;n&quot;
                  is present and is a digit from 2 to 9, it will align
                  the options in that many columns.
                   
  radio right n   Builds a radio box group for the item, inside a
                  table, with the checkbox on the right side. If &quot;n&quot;
                  is present and is a digit from 2 to 9, it will align
                  the options in that many columns.
</PRE>
<P>
<PRE>   
  check           Builds a checkbox group for the item, with spaces
                  separating the elements.
                   
  check nbsp      Builds a checkbox group for the item, with &amp;nbsp;
                  separating the elements.
                   
  check left n    Builds a checkbox group for the item, inside a
                  table, with the checkbox on the left side. If &quot;n&quot;
                  is present and is a digit from 2 to 9, it will align
                  the options in that many columns.
                   
  check right n   Builds a checkbox group for the item, inside a
                  table, with the checkbox on the right side. If &quot;n&quot;
                  is present and is a digit from 2 to 9, it will align
                  the options in that many columns.
</PRE>
<P>
The default is 'select', which builds an 
<FONT SIZE=-1>HTML</FONT> select form entry for the attribute. Also
recognized is 'multiple', which generates a multiple-selection drop down
list, 'show', which shows the list of possible attributes, and 'display',
which shows the label text for the selected option only.

<P><DT><STRONG><A NAME="item_field">field</A></STRONG><DD>

The database field name to be used to build the entry (usually a field in
the products database). Defaults to a field named the same as the
attribute.

<P><DT><STRONG><A NAME="item_database">database</A></STRONG><DD>

The database to find <STRONG>field</STRONG> in, defaults to the first products file where the item code is found.

<P><DT><STRONG><A NAME="item_name">name</A></STRONG><DD>

Name of the form variable to use if a form is being built. Defaults to
mv_order_<STRONG>attribute</STRONG> -- i.e. if the attribute is <STRONG>size</STRONG>, the form variable will be named <STRONG>mv_order_size</STRONG>.

<P><DT><STRONG><A NAME="item_outboard">outboard</A></STRONG><DD>

If calling the item-accessories tag, and you wish to select from an
outboard database, you can pass the key to use to find the accessory data.

<P></DL>
<P>
When called with an attribute, the database is consulted and looks for a
comma-separated list of attribute options. They take the form:

<P>
<PRE>    name=Label Text, name=Label Text*
</PRE>
<P>
The label text is optional -- if none is given, the <STRONG>name</STRONG> will be used.

<P>
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:

<P>
<PRE>    [item_accessories color]
</PRE>
<P>
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:

<P>
<PRE>    &lt;SELECT NAME=&quot;mv_order_color&quot;&gt;
    &lt;OPTION VALUE=&quot;beige&quot;&gt;Almond
    &lt;OPTION VALUE=&quot;gold&quot;&gt;Harvest Gold
    &lt;OPTION SELECTED&gt;White
    &lt;OPTION VALUE=&quot;green&quot;&gt;Avocado
    &lt;/SELECT&gt;
</PRE>
<P>
In combination with the <EM>mv_order_item</EM> and <EM>mv_order_quantity</EM> variables this can be used to allow entry of an attribute at time of order.

<P>
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.

<P>
The value can then be displayed with [item-modifier size] on the order
report, order receipt, or any other page containing an [item_list]. 

<P>
<HR>


code: 01.26
section: MINIVEND_TAG_REFERENCE
type: item
title: [item-list ...]

<A NAME="_item_list_">[item-list ...]</A></H2>
<P>
named: [item-list name=``cart'']

<P>
positional: [item-list cart*]

<P>
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.

<P>

<FONT SIZE=-1>NOTE:</FONT> The special tags that reference item within the list are not normal MiniVend tags, do not take named attributes, and cannot be contained in an 
<FONT SIZE=-1>HTML</FONT> tag (other than to substitute for one of its values or provide a conditional container). They are interpreted only inside their corresponding list container. Normal MiniVend tags can be interspersed, though they will be interpreted
 <EM>after</EM> all of the list-specific tags.

<P>
Between the item_list markers the following elements will return
information for the current item:

<DL>
<DT><STRONG><A NAME="item__if_data">[if-data table column]</A></STRONG><DD>

If the database field <CODE>column</CODE> in table <EM>table</EM> is non-blank, the following text up to the [/if_data] tag is substituted. This can be used to substitute 
<FONT SIZE=-1>IMG</FONT> or other tags only if the corresponding source item is present. Also accepts a [else]else text[/else] pair for the opposite condition.


<P><DT><STRONG>[if-data ! table column]</STRONG><DD>

Reverses sense for [if-data].

<P><DT><STRONG><A NAME="item__if_data_">[/if-data]</A></STRONG><DD>

Terminates an [if_data table column] element.

<P><DT><STRONG><A NAME="item__if_field">[if-field fieldname]</A></STRONG><DD>

If the products database field <EM>fieldname</EM> is non-blank, the following text up to the [/if_field] tag is substituted.
If you have more than one products database table (see <EM>ProductFiles</EM>), it will check them in order until a matching key is found. This can be used to substitute 
<FONT SIZE=-1>IMG</FONT> or other tags only if the corresponding source item is present. Also accepts a [else]else text[/else] pair for the opposite condition.


<P><DT><STRONG>[if-field ! fieldname]</STRONG><DD>

Reverses sense for [if-field].

<P><DT><STRONG><A NAME="item__if_field_">[/if-field]</A></STRONG><DD>

Terminates an [if_field fieldname] element.

<P><DT><STRONG><A NAME="item__item_accessories">[item-accessories attribute*, type*, field*, database*, name*]</A></STRONG><DD>

Evaluates to the value of the Accessories database entry for the item. If
passed any of the optional arguments, initiates special processing of item
attributes based on entries in the product database.

<P><DT><STRONG><A NAME="item__item_code_">[item-code]</A></STRONG><DD>

Evaluates to the product code for the current item.

<P><DT><STRONG><A NAME="item__item_data">[item-data database fieldname]</A></STRONG><DD>

Evaluates to the field name <EM>fieldname</EM> in the arbitrary database table <EM>database</EM>, for the current item.

<P><DT><STRONG><A NAME="item__item_description_">[item-description]</A></STRONG><DD>

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

<P><DT><STRONG><A NAME="item__item_field">[item-field fieldname]</A></STRONG><DD>

Evaluates to the field name <EM>fieldname</EM> in the products database, for the current item. If the item is not found in
the first of the
<EM>ProductFiles</EM>, all will be searched in sequence.

<P><DT><STRONG><A NAME="item__item_increment_">[item-increment]</A></STRONG><DD>

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

<P><DT><STRONG><A NAME="item__item_last_tags_item_last_">[item-last]tags[/item-last]</A></STRONG><DD>

Evaluates the output of the MiniVend tags encased inside the tags, and if
it evaluates to a numerical non-zero number (i.e. 1, 23, or -1) then the
list iteration will terminate. If the evaluated number is
<STRONG>negative</STRONG>, then the item itself will be skipped. If the evaluated number is <STRONG>positive</STRONG>, then the item itself will be shown but will be last on the list.

<P>
<PRE>      [item-last][calc]
        return -1 if '[item-field weight]' eq '';
        return 1 if '[item-field weight]' &lt; 1;
        return 0;
        [/calc][/item-last]
</PRE>
<P>
If this is contained in your <CODE>[item-list]</CODE> (or <CODE>[search-list]</CODE> or flypage) and the weight field is empty, then a numerical <CODE>-1</CODE> will be output from the [calc][/calc] tags; the list will end and the item
will <STRONG>not</STRONG> 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 <CODE>[item-list]</CODE>, any price for the item will still be added to the subtotal.) 
<FONT SIZE=-1>NOTE:</FONT> no 
<FONT SIZE=-1>HTML</FONT> style.


<P><DT><STRONG><A NAME="item__item_modifier">[item-modifier attribute]</A></STRONG><DD>

Evaluates to the modifier value of <CODE>attribute</CODE> for the current item.

<P><DT><STRONG><A NAME="item__item_next_tags_item_next_">[item-next]tags[/item_next]</A></STRONG><DD>

Evaluates the output of the MiniVend tags encased inside, and if it
evaluates to a numerical non-zero number (i.e. 1, 23, or -1) then the item
will be skipped with no output. Example:

<P>
<PRE>      [item-next][calc][item-field weight] &lt; 1[/calc][/item-next]
</PRE>
<P>
If this is contained in your <CODE>[item-list]</CODE> (or <CODE>[search-list]</CODE> or flypage) and the product's weight field is less than 1, then a numerical <CODE>1</CODE> will be output from the [calc][/calc] operation. The item will not be
shown. (If it is an <CODE>[item-list]</CODE>, any price for the item will still be added to the subtotal.)

<P><DT><STRONG><A NAME="item__item_price">[item-price n* noformat*]</A></STRONG><DD>

Evaluates to the price for quantity <CODE>n</CODE> (from the products file) of the current item, with currency formatting. If
the optional ``noformat'' is set, then currency formatting will not be
applied.

<P><DT><STRONG><A NAME="item__discount_price">[discount-price n* noformat*]</A></STRONG><DD>

Evaluates to the discount price for quantity <CODE>n</CODE> (from the products file) of the current item, with currency formatting. If
the optional ``noformat'' is set, then currency formatting will not be
applied. Returns regular price if not discounted.

<P><DT><STRONG><A NAME="item__item_discount_">[item-discount]</A></STRONG><DD>

Returns the difference between the regular price and the discounted price.

<P><DT><STRONG><A NAME="item__item_quantity_">[item-quantity]</A></STRONG><DD>

Evaluates to the quantity ordered for the current item.

<P><DT><STRONG><A NAME="item__item_subtotal_">[item-subtotal]</A></STRONG><DD>

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

<P><DT><STRONG><A NAME="item__modifier_name">[modifier-name attribute]</A></STRONG><DD>

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

<P><DT><STRONG><A NAME="item__quantity_name_">[quantity-name]</A></STRONG><DD>

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

<P></DL>
<P>
<HR>


code: 01.27
section: MINIVEND_TAG_REFERENCE
type: item
title: [lookup ...]

<A NAME="_lookup_">[lookup ...]</A></H2>
<P>
named: [lookup table=``database'' col=``column'' key=row value=``[value
name]'']

<P>
positional: [lookup table column row ``a quoted value'']

<P>
This is essentially same as the following:

<P>
<PRE>    [if value name]
    [then][value name][/then]
    [else][data database column row][/else]
    [/if]
</PRE>
<P>
<HR>


code: 01.28
section: MINIVEND_TAG_REFERENCE
type: item
title: [loop ...]

<A NAME="_loop_">[loop ...]</A></H2>
<P>
named: [loop with=``-a''* arg=``item item item'' search=``se=whatever'']

<P>
positional: [loop item item item] 
<FONT SIZE=-1>LIST</FONT> [/loop]

<P>

<FONT SIZE=-1>HTML</FONT> example: 

<P>
<PRE>    &lt;TABLE&gt;&lt;TR MV=&quot;loop 1 2 3&quot;&gt;&lt;TD&gt;[loop-code]&lt;/TD&gt;&lt;/TR&gt;&lt;/TABLE&gt;
</PRE>
<P>
Returns a string consisting of the 
<FONT SIZE=-1>LIST,</FONT> 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.

<P>
Loop lists can be nested reliably in MiniVend 3.06 by using the
with=``tag'' parameter. New syntax:

<P>
<PRE>    [loop arg=&quot;A B C&quot;]
        [loop with=&quot;-a&quot; arg=&quot;[loop-code]1 [loop-code]2 [loop-code]3&quot;]
            [loop with=&quot;-b&quot; arg=&quot;X Y Z&quot;]
                [loop-code-a]-[loop-code-b]
            [/loop]
        [/loop]
    [/loop]
</PRE>
<P>
An example in the old syntax:

<P>
<PRE>    [compat]
    [loop 1 2 3]   
        [loop-a 1 2 3 ]
        [loop-b 1 2 3]
            [loop-code].[loop-code-a].[loop-code-b]
        [/loop-b]
        [/loop-a]
    [/loop]
    [/compat]
</PRE>
<P>
All loop items in the inner loop-a loop need to have the <CODE>with</CODE> value appended, i.e. <CODE>[loop-field-a name]</CODE>, <CODE>[loop-price-a]</CODE>, etc. Nesting is arbitrarily large, though it will be slow for many
levels.

<P>
You can do an arbitrary search with the search=``args'' parameter, just as
in a one-click search:

<P>
<PRE>    [loop search=&quot;se=Americana/sf=category&quot;]
        [loop-code] [loop-field title]
    [/loop]
</PRE>
<P>
The above will show all items with a category containing the whole world
``Americana'', and will work the same in both old and new syntax.

<DL>
<DT><STRONG><A NAME="item__if_loop_data">[if-loop-data table field] IF [else] ELSE [/else][/if-loop-field]</A></STRONG><DD>

Outputs the 
<FONT SIZE=-1>IF</FONT> if the <A HREF="#item_field">field</A> in <CODE>table</CODE> is non-empty, and the 
<FONT SIZE=-1>ELSE</FONT> (if any) otherwise.

<P><DT><STRONG><A NAME="item__if_loop_field">[if-loop-field field] IF [else] ELSE [/else][/if-loop-field]</A></STRONG><DD>

Outputs the <STRONG>IF</STRONG> if the <A HREF="#item_field">field</A> in the <CODE>products</CODE> table is non-empty, and the <STRONG>ELSE</STRONG> (if any) otherwise.

<P><DT><STRONG><A NAME="item__loop_accessories_">[loop-accessories]</A></STRONG><DD>

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

<P><DT><STRONG><A NAME="item__loop_change">[loop-change marker]</A></STRONG><DD>

Same as <EM>[on_change]</EM> but within loop lists.

<P><DT><STRONG><A NAME="item__loop_code_">[loop-code]</A></STRONG><DD>

Evaluates to the product code for the current item.

<P><DT><STRONG><A NAME="item__loop_data">[loop-data database fieldname]</A></STRONG><DD>

Evaluates to the field name <EM>fieldname</EM> in the arbitrary database table <EM>database</EM>, for the current item.

<P><DT><STRONG><A NAME="item__loop_description_">[loop-description]</A></STRONG><DD>

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

<P><DT><STRONG><A NAME="item__loop_field">[loop-field fieldname]</A></STRONG><DD>

Evaluates to the field name <EM>fieldname</EM> in the database, for the current item.

<P><DT><STRONG><A NAME="item__loop_increment_">[loop-increment]</A></STRONG><DD>

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

<P><DT><STRONG><A NAME="item__loop_last_tags_loop_last_">[loop-last]tags[/loop-last]</A></STRONG><DD>

Evaluates the output of the MiniVend tags encased inside, and if it
evaluates to a numerical non-zero number (i.e. 1, 23, or -1) then the loop
iteration will terminate. If the evaluated number is
<STRONG>negative</STRONG>, then the item itself will be skipped. If the evaluated number is <STRONG>positive</STRONG>, then the item itself will be shown but will be last on the list.

<P>
<PRE>      [loop-last][calc]
        return -1 if '[loop-field weight]' eq '';
        return 1 if '[loop-field weight]' &lt; 1;
        return 0;
        [/calc][/loop-last]
</PRE>
<P>
If this is contained in your <CODE>[loop list]</CODE> and the weight field is empty, then a numerical <CODE>-1</CODE> will be output from the [calc][/calc] tags; the list will end and the item
will <STRONG>not</STRONG> 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.

<P><DT><STRONG><A NAME="item__loop_next_tags_loop_next_">[loop-next]tags[/loop-next]</A></STRONG><DD>

Evaluates the output of the MiniVend tags encased inside, and if it
evaluates to a numerical non-zero number (i.e. 1, 23, or -1) then the loop
will be skipped with no output. Example:

<P>
<PRE>      [loop-next][calc][loop-field weight] &lt; 1[/calc][/loop-next]
</PRE>
<P>
If this is contained in your <CODE>[loop list]</CODE> and the product's weight field is less than 1, then a numerical <CODE>1</CODE> will be output from the [calc][/calc] operation. The item will not be
shown.

<P><DT><STRONG><A NAME="item__loop_price">[loop-price n* noformat*]</A></STRONG><DD>

Evaluates to the price for optional quantity n (from the products file) of
the current item, with currency formatting. If the optional ``noformat'' is
set, then currency formatting will not be applied.

<P></DL>
<P>
<HR>


code: 01.29
section: MINIVEND_TAG_REFERENCE
type: item
title: [nitems ...]

<A NAME="_nitems_">[nitems ...]</A></H2>
<P>
named: [nitems cart*]

<P>
Expands into the total number of items ordered so far. Takes an optional
cart name as a parameter.

<P>
<HR>


code: 01.30
section: MINIVEND_TAG_REFERENCE
type: item
title: [order ...]

<A NAME="_order_">[order ...]</A></H2>
<P>
named: [order code=``code'' href=``cart/page'' base=``database'']

<P>
positional: [order code cart/page* database*]

<P>

<FONT SIZE=-1>HTML</FONT> example: 
<FONT SIZE=-1>&lt;A</FONT> MV=``order code'' HREF=``ord/basket''&gt;


<P>
Expands into a hypertext link which will include the specified code in the
list of products to order and display the order page. <STRONG>code</STRONG>
should be a product code listed in one of the ``products'' databases. The
optional argument <STRONG>cart/page</STRONG> selects the shopping cart the item will be placed in (begin with / to use
the default cart <CODE>main</CODE>) and the order page that will display the order. The optional argument <STRONG>database</STRONG> 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.

<P>
Example: 

<P>
<PRE>  Order a [order TK112]Toaster[/order] today.
</PRE>
<P>
<HR>


code: 01.31
section: MINIVEND_TAG_REFERENCE
type: item
title: [/order]

<A NAME="_order_">[/order]</A></H2>
<P>
named: [/order]

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

<P>
<HR>


code: 01.32
section: MINIVEND_TAG_REFERENCE
type: item
title: [page ...]

<A NAME="_page_">[page ...]</A></H2>
<P>
named: [page href=``dir/page'' arg=``argument''* secure=1* form=``form
string''*]

<P>
positional: [page dir/page arg*] (only two positional parameters)

<P>

<FONT SIZE=-1>HTML</FONT> example: 
<FONT SIZE=-1>&lt;A</FONT> MV=``page'' MV.HREF=``dir/page'' MV.ARG=``arg'' HREF=``dir/page.html''&gt;


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

<P>
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'}-&gt;{arg}. If you set the catalog configuration option
<EM>NewEscape</EM>, which is the default, then spaces and some other characters will be
escaped with the <CODE>%NN</CODE> HTTP-style notation and unescaped when
the argument is read back into the session.

<P>

<FONT SIZE=-1>A</FONT> bit of magic occurs if MiniVend has built a static plain 
<FONT SIZE=-1>HTML</FONT> 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 
<FONT SIZE=-1>ID.</FONT>


<P>
The optional <CODE>form</CODE> argument allows you to encode a form in the link.

<P>
<PRE>                [page form=&quot;
                                mv_order_item=99-102
                                mv_order_size=L
                                mv_order_quantity=1
                                mv_separate_items=1
                                mv_todo=refresh&quot;] Order t-shirt in Large size &lt;/A&gt;
</PRE>
<P>
The two form values <EM>mv_session_id</EM> and <EM>mv_arg</EM> are automatically added when appropriate. (<EM>mv_arg</EM> is the <CODE>arg</CODE> parameter for the tag.)

<P>
If the parameter <CODE>href</CODE> is not supplied, <EM>process</EM> is used, causing normal MiniVend form processing. If the <CODE>href</CODE> points to an http:// link no MiniVend 
<FONT SIZE=-1>URL</FONT> processing will be done, but the mv_session_id

<P>
This would generate a form that ordered item number 99-102 on a separate
line (<CODE>mv_separate_items</CODE> being set), with size <CODE>L</CODE>, in quantity 2. Since the page is not set, you will go to the default
shopping cart page -- equally you could set <CODE>mv_orderpage=yourpage</CODE>
to go to <CODE>yourpage</CODE>.

<P>
You must have TolerateGet set (which is the default) and all normal
MiniVend form caveats apply -- you must have an action, you must supply a
page if you don't want to go to the default, etc.

<P>
You can theoretically submit any form with this, though none of the
included values can have newlines or trailing whitespace. If you want to do
something like that you will have to write a UserTag.

<P>
<HR>


code: 01.33
section: MINIVEND_TAG_REFERENCE
type: item
title: [pagetarget ...]

<A NAME="_pagetarget_">[pagetarget ...]</A></H2>
<P>
named: [pagetarget href=``dir/page'' target=``frame'' arg=``argument'']

<P>
positional: [pagetarget pg frame arg*]

<P>
Same as the page element above, except it specifies an output frame to
target if frames are turned on. The name <STRONG>is</STRONG> 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 &lt;a href=``http://machine.company.com/cgi-bin/vlink/shirts?WehUkATn;;1''
TARGET=``main''&gt;. The catalog page displayed will come from <CODE>shirts.html</CODE> in the pages directory, and be output to the <CODE>main</CODE> frame. Be careful, frame names are case-sensitive.

<P>
MiniVend allows you to pass a search in a 
<FONT SIZE=-1>URL.</FONT> Just specify the search with the special page
reference <CODE>scan</CODE>. Here is an example:

<P>
<PRE>     [page scan
                        se=Impressionists
                        sf=category]
        Impressionist Paintings
     [/page]
</PRE>
<P>
Here is the same thing from a home page (assuming /cgi-bin/vlink is the 
<FONT SIZE=-1>CGI</FONT> path for MiniVend's vlink):

<P>
<PRE>     &lt;A HREF=&quot;/cgi-bin/vlink/scan/se=Impressionists/sf=category&quot;&gt;
        Impressionist Paintings
     &lt;/A&gt;
</PRE>
<P>
The two-letter abbreviations are mapped with these letters:

<P>
<PRE>  DL  mv_raw_dict_look
  MM  mv_more_matches
  SE  mv_raw_searchspec
  ac  mv_all_chars
  bd  mv_base_directory
  bs  mv_begin_string
  co  mv_coordinate
  cs  mv_case
  de  mv_dict_end
  df  mv_dict_fold
  di  mv_dict_limit
  dl  mv_dict_look
  do  mv_dict_order
  dp  mv_delay_page
  dr  mv_record_delim
  em  mv_exact_match
  er  mv_spelling_errors
  fi  mv_search_file
  fm  mv_first_match
  fn  mv_field_names
  hs  mv_head_skip
  id  mv_index_delim
  lr  mv_line_return
  ml  mv_matchlimit
  mm  mv_max_matches
  mp  mv_profile
  ms  mv_min_string
  ne  mv_negate
  nu  mv_numeric
  op  mv_column_op
  os  mv_orsearch
  ra  mv_return_all
  rd  mv_return_delim
  rf  mv_return_fields
  rg  mv_range_alpha
  rl  mv_range_look
  rm  mv_range_min
  rn  mv_return_file_name
  rs  mv_return_spec
  rx  mv_range_max
  se  mv_searchspec
  sf  mv_search_field
  sp  mv_search_page
  sq  mv_sql_query
  st  mv_searchtype
  su  mv_substring_match
  tc  mv_sort_command
  tf  mv_sort_field
  to  mv_sort_option
  ty  mv_sort_crippled
</PRE>
<P>
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 
<FONT SIZE=-1>URL</FONT> hex encoding, i.e. <CODE>%20</CODE> is a space, <CODE>%2F</CODE> is a

<CODE>/</CODE>, etc. -- <CODE>&amp;sp;</CODE> or <CODE>&amp;#32;</CODE> will not be recognized. If you use one of the methods below to escape these
``unsafe'' characters, you won't have to worry about this.

<P>
Beginning in MiniVend 3.08, you may specify a one-click search in three different ways. The first is as used in previous versions, with the scan 
<FONT SIZE=-1>URL</FONT> being specified completely as the page name. The second two use the ``argument'' parameter to the
 <CODE>[page ...]</CODE> or <CODE>[area ...]</CODE>
tags to specify the search (an argument to a scan is never valid anyway).

<DL>
<DT><STRONG><A NAME="item_Original">Original</A></STRONG><DD>

If you wish to do an 
<FONT SIZE=-1>OR</FONT> search on the fields category and artist for the
strings ``Surreal'' and ``Gogh'', while matching substrings, you would do:

<P>
<PRE> [page scan se=Surreal/se=Gogh/os=yes/su=yes/sf=artist/sf=category]
    Van Gogh -- compare to surrealists
 [/page]
</PRE>
<P>
In this method of specification, 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.)

<P><DT><STRONG><A NAME="item_Ampersand">Ampersand</A></STRONG><DD>

You can substitute &amp; for / in the specification and be able to use /
and quotes and spaces in the specification.

<P>
<PRE> [page scan se=&quot;Van Gogh&quot;&amp;sp=lists/surreal&amp;os=yes&amp;su=yes&amp;sf=artist&amp;sf=category]
    Van Gogh -- compare to surrealists
 [/page]
</PRE>
<P>
Any ``unsafe'' characters will be escaped. 

<P><DT><STRONG><A NAME="item_Multi">Multi-line</A></STRONG><DD>

You can specify parameters one to a line, as well. 

<P>
<PRE>    [page scan
        se=&quot;Van Gogh&quot;
        sp=lists/surreal
        os=yes
        su=yes
        sf=artist
        sf=category
    ] Van Gogh -- compare to surrealists [/page]
</PRE>
<P>
Any ``unsafe'' characters will be escaped. You may not search for trailing
spaces in this method; it is allowed in the other notations.

<P></DL>
<P>
New syntax and old syntax handle the tags the same, though if by some odd
chance you wanted to be able to search for a <CODE>]</CODE> (right square bracket) you would need to use new syntax.

<P>
The optional <EM>arg</EM> is used just as in the <EM>page</EM> tag.

<P>
<HR>


code: 01.34
section: MINIVEND_TAG_REFERENCE
type: item
title: [/page]

<A NAME="_page_">[/page]</A></H2>
<P>
named: [/page]

<P>
Expands into &lt;/a&gt;. Used with the page element, such as:

<P>
<PRE>  [page shirts]Our shirt collection[/page]. 
</PRE>
<P>

<FONT SIZE=-1>TIP:</FONT> 
<FONT SIZE=-1>A</FONT> small efficiency boost in large pages is to just use the 
<FONT SIZE=-1>&lt;/A&gt;</FONT> tag.


<P>
<HR>


code: 01.35
section: MINIVEND_TAG_REFERENCE
type: item
title: [perl ...]

<A NAME="_perl_">[perl ...]</A></H2>
<P>
named: [perl args=``arg1 arg2 ... argn'' interpolate=1*] 
<FONT SIZE=-1>CODE</FONT> [/perl]

<P>
positional: [perl args] code [/perl]

<P>

<FONT SIZE=-1>HTML</FONT> example:

<P>
<PRE>    &lt;PRE mv=perl mv.arg=&quot;values browser&quot;&gt;
        $name = $Safe{'values'}{'name'};
        $name = $Safe{'browser'};
        return &quot;Hi, $name! How do you like your $browser?
    &lt;/PRE&gt;
</PRE>
<P>
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.

<P>
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 
<FONT SIZE=-1>INTERPOLATE=1</FONT> parameter to have tags inside [perl] and [/perl] interpreted. (In the old syntax, most tags are evaluated before [perl], though there are exceptions.)


<P>
More often you will want to use the tag access routine <STRONG>&safe_tag</STRONG>, which takes the tag name and any arguments as parameters. This has the advantage of only performing the operation when the code is executed. 
<FONT SIZE=-1>(A</FONT> few tags can't be used with safe_tag, notably ones accessing a database that has not previously been accessed on the page.)


<P>
Examples:

<P>
<PRE>    # Simple example, old syntax
    [perl]
    $comments = '[value comments]';
    [/perl]
</PRE>
<P>
<PRE>    # New syntax
    # If the item might contain a single quote
    [perl interpolate=1]
    $comments = '[value comments escaped]';
    [/perl]
</PRE>
<P>
<PRE>    # Another method to avoid escape problems
    $comments = q{[value comments]};
</PRE>
<P>
<PRE>    # Works with all, only executed if code is reached
    $comments = safe_tag('value', 'comments');
</PRE>
<P>
This allows you to pass user-space variables for most needed operations.
You can pass whole lists of items with constructs like:

<P>
<PRE>    # Perl ignores the trailing comma
    my(%prices) = ( [item_list]
                    '[item_code]', '[item-price]',
                    [/item_list]);
</PRE>
<P>
Even easier is the definition of a subroutine:

<P>
<PRE>    [set Thanks]
    my($name, $number) = @_;
    &quot;Thanks, $name, for your order! The order number is $number.\n&quot;;
    [/set]
</PRE>
<P>
<PRE>    # New syntax
    [perl arg=sub interpolate=1]
        Thanks ('[value name escaped]', '[value mv_order_number escaped]')
    [/perl]
</PRE>
<P>
<PRE>    # Old syntax, depends on [value ...] interpolated before [perl]
    [perl sub]
        Thanks ('[value name escaped]', '[value mv_order_number escaped]')
    [/perl]
</PRE>
<P>
(The <CODE>escaped</CODE> 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''.)

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

<DL>
<DT><STRONG><A NAME="item_browser">browser</A></STRONG><DD>

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

<P><DT><STRONG><A NAME="item_carts">carts</A></STRONG><DD>

Gives read-write access to all of the shopping carts. on order. This is an
array of hashes, and includes the product code, quantity, and any modifiers
you have specified. Referred to in your code as a reference to the array,
$Safe{items} or @{$Safe{items}}.

<P>
<PRE>    # Move contents of 'layaway' cart to main cart
    $Safe{carts}-&gt;{main} = $Safe{carts}-&gt;{layaway};
    $Safe{carts}-&gt;{main} = [];
</PRE>
<P>
Careful with this -- you can lose the items on order with improper code,
though syntax errors will be caught before the code is run.

<P><DT><STRONG><A NAME="item_cgi">cgi</A></STRONG><DD>

Gives read-only access to the actual variables that were passed in the current 
<FONT SIZE=-1>CGI</FONT> session. This is useful for testing what the user actually placed on the form, not just what MiniVend placed in the session. Called with


<P>
<PRE>  # Set if the user had a value for name in the *current* form
  $name = $Safe{'cgi'}-&gt;{name};
</PRE>
<P><DT><STRONG>config</STRONG><DD>

Gives read-write access to the configuration of the catalog. 
<FONT SIZE=-1>USE</FONT> 
<FONT SIZE=-1>WITH</FONT> 
<FONT SIZE=-1>EXTREME</FONT> 
<FONT SIZE=-1>CAUTION</FONT> -- many of the variables are references to anonymous arrays and hashes. You can crash your catalog if you modify the wrong thing. Referred to in your code as $Safe{config}, a reference to the hash containing the configuration structure. If you use this, it is recommended that you refer frequently to the MiniVend source code.


<P><DT><STRONG>discount</STRONG><DD>

Gives read-write access to session discounts, an anonymous hash. Referred
to in your code as $Safe-&gt;{discounts}.

<P><DT><STRONG>file</STRONG><DD>

If specified, the anchor text is a file name to read the Perl code from.
This allows code to be maintained in separate files, though you need to
remember that any MiniVend tags contained will generally not be
interpolated (depending on interpolation order and use of the [[any]] and
[post] modifiers). The file name is relative to the MiniVend base directory
unless specified as an absolute path.

<P><DT><STRONG><A NAME="item_frames">frames</A></STRONG><DD>

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

<P><DT><STRONG>items</STRONG><DD>

Gives read-only access to the items on order, <EM>for the current cart</EM>. This is an array of hashes, and includes the product code, quantity, and
any modifiers you have specified. Referred to in your code as a reference
to the array, $Safe{items} or @{$Safe{items}}.

<P>
<PRE>    # Product code of first item in cart
    $item_code = $Safe{items}-&gt;[0]-&gt;{code};  
</PRE>
<P>
<PRE>    # Quantity for third item in cart
    $item_code = $Safe{items}-&gt;[2]-&gt;{quantity};  
</PRE>
<P>
<PRE>    # Color of second item in cart
    $item_code = $Safe{items}-&gt;[2]-&gt;{color};  
</PRE>
<P><DT><STRONG>scratch</STRONG><DD>

Gives read-write access to the scratch variables, a reference to an
anonymous hash. Referred to in your code as $Safe{scratch}.

<P><DT><STRONG><A NAME="item_sub">sub</A></STRONG><DD>

If specified, the anchor text is a subroutine name and optional parameters
to be passed. The subroutine can be defined in three ways; as a global
subroutine (works for entire server); as a catalog-wide pre-defined
subroutine; or in a scratchpad variable. All are called with the same
syntax -- the arguments are passed in via the <CODE>@_</CODE> argument
array.

<P>
<STRONG>IMPORTANT NOTE:</STRONG> Global subroutines are not subject to the stringent security checking of
the <EM>Safe</EM> 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.

<P>
Global subroutines are defined in <EM>minivend.cfg</EM> with the
<EM>GlobalSub</EM> directive, or in user catalogs which have been enabled via <EM>AllowGlobal</EM>. Global subroutines are much faster than the others as they are
pre-compiled. (Faster still are <EM>UserTag</EM>
definitions.)

<P>
Catalog subroutines are defined in <EM>catalog.cfg</EM>, with the <EM>Sub</EM> directive. They are subject to the stringent <EM>Safe.pm</EM>
security restrictions that are controlled by <EM>SafeUntrap</EM>. If you wish to have default arguments supplied to them, use the <EM>SubArgs</EM>
directive.

<P>
Scratch subroutines are defined in the pages, and are also subject to <EM>Safe.pm</EM> 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.

<P><DT><STRONG><A NAME="item_values">values</A></STRONG><DD>

Gives read-write access to the user variables, including the MiniVend
special variables, an anonymous hash. Referred to in your code as
%{Safe{'values'}} or $Safe{'values'}-&gt;{variable}.

<P>
<PRE>    # Read the user's selected shipping mode
    my $shipmode = $Safe{values}-&gt;{mv_shipmode};
</PRE>
<P></DL>
<P>
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 <EM>Safe</EM> -- operations may be untrapped on a system-wide basis with the <EM>SafeUntrap</EM> directive.

<P>
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.

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

<P>
<PRE>    [perl] my $tmp = &quot;Hello, world!&quot;; $tmp; [/perl]
</PRE>
<P>
Of course you wouldn't need to set the variable -- it is just there to show
the capability.

<P>
To echo the user's browser, but within some 
<FONT SIZE=-1>HTML</FONT> tags:

<P>
<PRE>    [perl browser]
    my $html = '&lt;H5&gt;';
    $html .= $Safe{'browser'};
    $html .= '&lt;/H5&gt;';
    $html;
    [/perl]
</PRE>
<P>
To show the user their name, and the current time:

<P>
<PRE>    [perl values]
</PRE>
<P>
<PRE>    my $string = &quot;Hi, &quot; . $Safe{values}-&gt;{'name'} &quot;. The time is now &quot;;
    $string .= localtime;
    $string;
</PRE>
<P>
<PRE>    [/perl]
</PRE>
<P>
<HR>


code: 01.36
section: MINIVEND_TAG_REFERENCE
type: item
title: [post]

<A NAME="_post_">[post]</A></H2>
<P>
syntax: [post] 
<FONT SIZE=-1>DELAYED</FONT> 
<FONT SIZE=-1>TAGS</FONT> [/post]


<P>
<STRONG>NOTE:</STRONG> This is ignored if using the new syntax.

<P>
Selects an area that will not be interpolated until after the rest of the
page is interpolated. If followed by a number, will match a terminating
[/post] tag with the corresponding number.

<P>
<HR>


code: 01.37
section: MINIVEND_TAG_REFERENCE
type: item
title: [price ...]

<A NAME="_price_">[price ...]</A></H2>
<P>
named: [price code=``code'' quantity=``quantity'' base=``database''
noformat=1*]

<P>
positional: [price code quantity* database* noformat*]

<P>
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 <STRONG>base</STRONG>. The optional argument <STRONG>quantity</STRONG> selects an entry from the quantity price list. To receive a raw number,
with no currency formatting, use the option <CODE>noformat=1</CODE>.

<P>
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.

<P>
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.

<P>
There are several ways that MiniVend can modify the price of a product
during normal catalog operation. Several of them require that the <EM>pricing.asc</EM>
file be present, and that you define a pricing database. You do that by
placing the following directive in <EM>catalog.cfg</EM>:

<P>
<PRE>  Database  pricing pricing.asc 1
</PRE>
<P>
Configurable directives and tags with regard to pricing:

<UL>
<LI>

Quantity price breaks are configured by means of the <EM>PriceBreaks</EM> and
<EM>MixMatch</EM> directives. They require a field named specifically <CODE>price</CODE>
in the pricing database. The <STRONG>price</STRONG> field contains a space-separated list of prices that correspond to the
quantity levels defined in the
<EM>PriceBreaks</EM> directive. If quantity is to be applied to all items in the shopping cart
(as opposed to quantity of just that item) then the
<EM>MixMatch</EM> directive should be set to <STRONG>Yes</STRONG>.

<P><LI>

Individual line-item prices can be adjusted according to the value of their
attributes. See <EM>PriceAdjustment</EM> and <EM>CommonAdjust</EM>. The pricing database <STRONG>must</STRONG> be defined unless you define the <EM>CommonAdjust</EM>
behavior.

<P><LI>

Product discounts for specific products, all products, or the entire order
can be configured with the [discount ...] tag. Discounts are applied on a
per-user basis -- you can gate the discount based on membership in a club
or other arbitrary means. See <EM>Product Discounts</EM>.

<P></UL>
<P>
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
&lt;catalog.cfg&gt;:

<P>
<PRE>  Database          pricing pricing.asc 1
  UseModifier       size
  PriceAdjustment   size
</PRE>
<P>
To enable the automatic modifier handling of MiniVend 3.0, you would define
a size field in products.asc:

<P>
<PRE>  code    description   price    size
  99-102  T-Shirt       10.00    S=Small, M=Medium, L=Large*, XL=Extra Large
</PRE>
<P>
You would place the proper tag within your [item-list] on the
shopping-basket or order page:

<P>
<PRE>    [item-accessories size]
</PRE>
<P>
In the pricing.asc database source, you would need:

<P>
<PRE>  code      S       XL
  99-102    -1.00   1.00
</PRE>
<P>
As of MiniVend 3.06, if you want to assign a price based on the option,
precede the number with an equals sign:

<P>
<PRE>  code    S       M       L       XL
  99-102  =9.00   =10     =10     =11
</PRE>
<P>

<FONT SIZE=-1>IMPORTANT</FONT> 
<FONT SIZE=-1>NOTE:</FONT> Price adjustments occur 
<FONT SIZE=-1>AFTER</FONT> quantity price breaks, so the above would negate anything set with the
 <EM>PriceBreaks</EM> directive/option.

<P>
Numbers that begin with an equals sign (<CODE>=</CODE>) are used as absolute prices and are <EM>interpolated for MiniVend tags first</EM>, so you can use subroutines to set the price. To facilite coordination
with the subroutine, the session variables <CODE>item_code</CODE> and <CODE>item_quantity</CODE> are set to the code and quantity of the item being evaluated. They would be
accessed in a global subroutine with <CODE>$Vend::Session-</CODE>&gt;<CODE>{item_code}</CODE>
and <CODE>$Vend::Session-</CODE>&gt;<CODE>{item_quantity}</CODE>.

<P>
The pricing information must always come from a database because of
security.

<P>
See <EM>CommonAdjust</EM> 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-&gt;{CommonAdjust} in a
subroutine -- the pricing algorithm is built at catalog configuration
time.)

<P>
<HR>


code: 01.38
section: MINIVEND_TAG_REFERENCE
type: item
title: [random]

<A NAME="_random_">[random]</A></H2>
<P>

<FONT SIZE=-1>AUTOINTERPOLATE:</FONT> Yes, can be turned off with 
<FONT SIZE=-1>INTERPOLATE=0</FONT>


<P>
Selects from the predefined random messages, and is stripped if none exist.
See <EM>CONTROLLING PAGE APPEARANCE</EM> in the MiniVend documentation.

<P>
<HR>


code: 01.39
section: MINIVEND_TAG_REFERENCE
type: item
title: [rotate ...]

<A NAME="_rotate_">[rotate ...]</A></H2>
<P>
named: [rotate floor=``n'' ceiling=``n'']

<P>
positional: [rotate ceiling* floor*]

<P>

<FONT SIZE=-1>AUTOINTERPOLATE:</FONT> Yes, can be turned off with 
<FONT SIZE=-1>INTERPOLATE=0</FONT>


<P>
Selects from the predefined rotating banner messages, and is stripped if
none exist. The optional <CODE>ceiling</CODE> sets the highest number that will be selected -- likewise <CODE>floor</CODE> sets the lowest. The default is to sequence through all defined rotating
banners. Each user has a separate rotation pattern, and each floor/ceiling
combination has a separate rotation value.

<P>
<HR>


code: 01.40
section: MINIVEND_TAG_REFERENCE
type: item
title: [row ...]

<A NAME="_row_">[row ...]</A></H2>
<P>
named: [row width=``nn''] 
<FONT SIZE=-1>COLUMN</FONT> 
<FONT SIZE=-1>DEFINITIONS</FONT> [/row]


<P>
positional: [row nn] .... [/row]

<P>
Formats text in tables. Intended for use in emailed reports or &lt;
<FONT SIZE=-1>PRE&gt;&lt;</FONT>
<FONT SIZE=-1>/PRE&gt;</FONT> 
<FONT SIZE=-1>HTML</FONT> areas. The parameter
 <EM>nn</EM> gives the number of columns to use. Inside the row tag, [col param=value
...] tags may be used. 

<DL>
<DT><STRONG><A NAME="item__col">[col width=nn wrap=yes|no gutter=n align=left|right|input spacing=n]</A></STRONG><DD>

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

<P>
The parameters are:

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

Terminates the column field.

<P></DL>
<P>
<HR>


code: 01.41
section: MINIVEND_TAG_REFERENCE
type: item
title: [salestax ...]

<A NAME="_salestax_">[salestax ...]</A></H2>
<P>
named: [salestax cart=cartname* noformat=1*]

<P>
old: [salestax cart* noformat*]

<P>
mandatory: 
<FONT SIZE=-1>NONE</FONT>

<P>
optional: cart noformat

<P>
Expands into the sales tax on the subtotal of all the items ordered so far
for the cart, default cart is <CODE>main</CODE>. If there is no key field to derive the proper percentage, such as state
or zip code, it is set to 0. If the noformat tag is present and non-zero,
the raw number with no currency formatting will be given.

<P>
<HR>


code: 01.42
section: MINIVEND_TAG_REFERENCE
type: item
title: [scratch ...]

<A NAME="_scratch_">[scratch ...]</A></H2>
<P>
named: [scratch name]

<P>
Returns the contents of a scratch variable to the page.

<P>
<HR>


code: 01.43
section: MINIVEND_TAG_REFERENCE
type: item
title: [selected ...]

<A NAME="_selected_">[selected ...]</A></H2>
<P>
named: [selected name=``var_name'' value=``value'' multiple=``yes'']

<P>
positional: [selected var_name value 
<FONT SIZE=-1>MULTIPLE*]</FONT>

<P>
You can provide a ``memory'' for drop-down menus, radio buttons, and
checkboxes with the [checked] and [selected] tags.

<P>
This will output 
<FONT SIZE=-1>SELECTED</FONT> if the variable <CODE>var_name</CODE> is equal to
<A HREF="#item_value">value</A>. If the optional 
<FONT SIZE=-1>MULTIPLE</FONT> argument is present, it will look for any of
a variety of values. Not case sensitive.

<P>
Here is a drop-down menu that remembers an item-modifier color selection:

<P>
<PRE>    &lt;SELECT NAME=&quot;color&quot;&gt;
    &lt;OPTION [selected color blue]&gt; Blue
    &lt;OPTION [selected color green]&gt; Green
    &lt;OPTION [selected color red]&gt; Red
    &lt;/SELECT&gt;
</PRE>
<P>
Here is the same thing, but for a shopping-basket color selection

<P>
<PRE>    &lt;SELECT NAME=&quot;[modifier-name color]&quot;&gt;
    &lt;OPTION [selected [modifier-name color] blue]&gt; Blue
    &lt;OPTION [selected [modifier-name color] green]&gt; Green
    &lt;OPTION [selected [modifier-name color] red]&gt; Red
    &lt;/SELECT&gt;
</PRE>
<P>
<HR>


code: 01.44
section: MINIVEND_TAG_REFERENCE
type: item
title: [set ...]

<A NAME="_set_">[set ...]</A></H2>
<P>
named: [set name=``variable''] value [/set]

<P>
positional: [set variable]value[/set]

<P>

<FONT SIZE=-1>HTML</FONT> example: 
<FONT SIZE=-1>&lt;PRE</FONT> MV=``set variable''&gt; value 
<FONT SIZE=-1>&lt;/PRE&gt;</FONT>


<P>
Sets a scratchpad variable to <EM>value</EM>.

<P>
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.

<P>
You can set an order profile with:

<P>
<PRE>  [set checkout]
  name=required
  address=required
  [/set]
  &lt;INPUT TYPE=hidden NAME=mv_order_profile VALUE=&quot;checkout&quot;&gt;
</PRE>
<P>

<FONT SIZE=-1>A</FONT> search profile would be set with:

<P>
<PRE>  [set substring_case]
  mv_substring_match=yes
  mv_case=yes
  [/set]
  &lt;INPUT TYPE=hidden NAME=mv_profile VALUE=&quot;substring_case&quot;&gt;
</PRE>
<P>
<HR>


code: 01.45
section: MINIVEND_TAG_REFERENCE
type: item
title: [shipping ...]

<A NAME="_shipping_">[shipping ...]</A></H2>
<P>
named: [shipping name=``mode'']

<P>
positional: [shipping mode*]

<P>
The shipping cost of the items in the basket via <CODE>mode</CODE> -- the default mode is the shipping mode currently selected in the <CODE>mv_shipmode</CODE>
variable. See <EM>SHIPPING</EM>.

<P>
<HR>


code: 01.46
section: MINIVEND_TAG_REFERENCE
type: item
title: [shipping_description ...]

<A NAME="_shipping_description_">[shipping_description ...]</A></H2>
<P>
named: [shipping_description name=``mode'']

<P>
old: [shipping-description mode*]

<P>
mandatory: 
<FONT SIZE=-1>NONE</FONT>

<P>
optional: <STRONG>name</STRONG> is the shipping mode identifier, i.e. <CODE>upsg</CODE>.

<P>
The text description of <STRONG>mode</STRONG> -- the default is the shipping mode currently selected.

<P>
<HR>


code: 01.47
section: MINIVEND_TAG_REFERENCE
type: item
title: [sql ...]

<A NAME="_sql_">[sql ...]</A></H2>
<P>
named: [sql array] 
<FONT SIZE=-1>SQL</FONT> [/sql identifier*]

<P>

<FONT SIZE=-1>A</FONT> complete array of arrays, suitable for <EM>eval</EM> by Perl, can be returned by this query. This tag pair encloses any valid 
<FONT SIZE=-1>SQL</FONT> query, and returns the results (if any) as a
string representing rows and columns, in Perl array syntax. If placed in an
embedded Perl area as:

<P>
<PRE> [perl]
</PRE>
<P>
<PRE>    my $string =&lt;&lt;'EOF';
 [sql array]select * from arbitrary where code &lt;= '19'[/sql arbitrary]
</PRE>
<P>
<PRE> EOF
    my $ary = eval $string;
    my $out = '';
    my $i;
    foreach $i (@$ary) {
        $out .= $i-&gt;[0];
        $out .= &quot;&lt;BR&gt;&quot;;
    }
    $out;
</PRE>
<P>
<PRE> [/perl]
</PRE>
<P>

<FONT SIZE=-1>NOTE:</FONT> The 
<FONT SIZE=-1>'EOF'</FONT> string terminator must 
<FONT SIZE=-1>START</FONT> the line, and not have trailing characters. 
<FONT SIZE=-1>DOS</FONT> users, beware of carriage returns!


<P>
<HR>


code: 01.48
section: MINIVEND_TAG_REFERENCE
type: item
title: [sql ...]

<A NAME="_sql_">[sql ...]</A></H2>
<P>
named: [sql hash] 
<FONT SIZE=-1>SQL</FONT> [/sql identifier*]

<P>

<FONT SIZE=-1>A</FONT> complete hash of hashes, suitable for <EM>eval</EM> by Perl, can be returned by this query. This tag pair encloses any valid 
<FONT SIZE=-1>SQL</FONT> query, and returns the results (if any) as a
string representing rows and columns, in Perl associative array, or hash,
syntax. If placed in an embedded Perl area as:

<P>
<PRE> [perl]
</PRE>
<P>
<PRE>    my $string =&lt;&lt;'EOF';
 [sql hash]select * from arbitrary where code &lt;= '19'[/sql]
</PRE>
<P>
<PRE> EOF
    my $hash = eval $string;
    my $out = '';
    my $key;
    foreach $key (keys %$hash) {
        $out .= $key-&gt;{field1};
        $out .= &quot;&lt;BR&gt;&quot;;
    }
    $out;
</PRE>
<P>
<PRE> [/perl]
</PRE>
<P>
<HR>


code: 01.49
section: MINIVEND_TAG_REFERENCE
type: item
title: [sql ...]

<A NAME="_sql_">[sql ...]</A></H2>
<P>
named: [sql html] 
<FONT SIZE=-1>SQL</FONT> [/sql]

<P>
This tag returns a set of 
<FONT SIZE=-1>HTML</FONT> table rows with <STRONG>bold</STRONG> field names at the top, followed by each row in a set of table cells. The 
<FONT SIZE=-1>&lt;TABLE&gt;</FONT> and 
<FONT SIZE=-1>&lt;/TABLE&gt;</FONT> tags are not supplied, so you can set your own border and shading options. Example:


<P>
<PRE>  &lt;TABLE BORDER=2&gt;
  [sql html]select * from arbitrary where code &gt; '19' order by field2[/sql]
  &lt;/TABLE&gt;
</PRE>
<P>
<HR>


code: 01.50
section: MINIVEND_TAG_REFERENCE
type: item
title: [sql ...]

<A NAME="_sql_">[sql ...]</A></H2>
<P>
named: [sql list 
<FONT SIZE=-1>SQL]</FONT> list [/sql]

<P>
This tag differs from the rest in that it passes the query enclosed inside the tag itself. The enclosed text is then evaluated with the same method as with a loop list, with data items (in columns) iterated over for the contents of a list. The following snippet will place a three-column list in an 
<FONT SIZE=-1>HTML</FONT> table:


<P>
<PRE>  &lt;TABLE BORDER=2&gt;
  &lt;TR&gt;&lt;TH&gt;&lt;B&gt;SKU&lt;/B&gt;&lt;/TH&gt;&lt;TH&gt;&lt;B&gt;Description&lt;/B&gt;&lt;/TH&gt;&lt;TH&gt;&lt;B&gt;Price&lt;/B&gt;&lt;/TH&gt;
  [sql list
    select * from arbitrary where code &gt; '19' order by field2 ]
  &lt;TR&gt;
    &lt;TD&gt;[page [sql-code]][sql-code]&lt;/A&gt;&lt;/TD&gt;
    &lt;TD&gt;[sql-param 1]&lt;/TD&gt;
    &lt;TD&gt;[sql-param 2]&lt;/TD&gt;
  &lt;/TR&gt;
  [/sql]
  &lt;/TABLE&gt;
</PRE>
<P>
It uses the same tags as in the [loop_list], except prefixed with <CODE>sql</CODE>. Available are the following, in order of interpolation:

<P>
<PRE>  [sql_param n]        Field n of the returned query (in the row)
  [if_sql_field fld]   Returns enclosed text only product field not empty
  [/if_sql_field]      Terminator for above
  [if_sql_data db fld] Returns enclosed text only if data field not empty
  [/if_sql_field]      Terminator for above
  [sql_increment]      Returns integer count of row
  [sql_code]           The first field of each row returned
  [sql_data db fld]    Database field for [sql_code]
  [sql_description]    Product description for [sql_code]
  [sql_field fld]      Product field for [sql_code]
  [sql_link]           Same as item-link
  [sql_price q*]       Price for [sql_code], optional quantity q
</PRE>
<P>
<HR>


code: 01.51
section: MINIVEND_TAG_REFERENCE
type: item
title: [sql ...]

<A NAME="_sql_">[sql ...]</A></H2>
<P>
named: [sql param] 
<FONT SIZE=-1>SQL</FONT> [/sql]

<P>

<FONT SIZE=-1>A</FONT> list of keys, or in fact any 
<FONT SIZE=-1>SQL</FONT> fields, can be returned as a set of parameters suitable for passing to a program or list primitive. This tag pair encloses any valid 
<FONT SIZE=-1>SQL</FONT> query, and returns the results (if any) as a series of space separated fields, enclosed in quotes. This folds the entire return into a single row, so it may be used as a list of keys.


<P>
<HR>


code: 01.52
section: MINIVEND_TAG_REFERENCE
type: item
title: [sql ...]

<A NAME="_sql_">[sql ...]</A></H2>
<P>
named: [sql set] 
<FONT SIZE=-1>SQL</FONT> [/sql identifier*]

<P>
Any arbitrary 
<FONT SIZE=-1>SQL</FONT> query can be passed with this method. No return
text will be sent. This might be used for passing an order to an order
database, perhaps on the order report or receipt page. An example might be:

<P>
<PRE> [sql set]
     insert into orders
     values
      ('[value mv_order_number]',
       '[value name escape]',
       '[value address escape]',
       '[value city escape]',
       '[value state escape]',
       '[value zip escape]',
       '[value phone escape]',
       '[item-list]
         Item: [item-code] Quan: [item-quantity] Price: [item-price]
        [/item-list]'
      )
 [/sql orders]
</PRE>
<P>
The values entered by the user are escaped, which prevents errors if quote
characters have slipped into their entry.

<P>
<HR>


code: 01.53
section: MINIVEND_TAG_REFERENCE
type: item
title: [subtotal ...]

<A NAME="_subtotal_">[subtotal ...]</A></H2>
<P>
named: [subtotal cart=cartname* noformat=1*]

<P>
old: [subtotal cart* noformat*]

<P>
mandatory: 
<FONT SIZE=-1>NONE</FONT>

<P>
optional: cart noformat

<P>
Expands into the subtotal cost, exclusive of sales tax, of all the items
ordered so far for the optional <CODE>cart</CODE>. If the noformat tag is present and non-zero, the raw number with no
currency formatting will be given.

<P>
<HR>


code: 01.54
section: MINIVEND_TAG_REFERENCE
type: item
title: [tag ...]

<A NAME="_tag_">[tag ...]</A></H2>
<P>
named: [tag op=operation arg=``arg1 arg2 ... argn''] 
<FONT SIZE=-1>TEXT</FONT> [/tag]

<P>
positional: [tag arg* arg*]text[/tag]

<P>
Performs any of a number of operations, based on the presence of <CODE>arg</CODE>. The arguments that may be given are:

<DL>
<DT><STRONG><A NAME="item_each">each database</A></STRONG><DD>

Returns a loop-list with every key in <A HREF="#item_database">database</A> evaluated as the [loop-code]. This will return the key and field <A HREF="#item_name">name</A>
for every record in the <CODE>products</CODE> database:

<P>
<PRE>    [tag each products][loop-code]  [loop-field name]&lt;BR&gt;[/tag]
</PRE>
<P><DT><STRONG><A NAME="item_export">export database file* type*</A></STRONG><DD>

Exports a complete MiniVend database to its text source file (or any
specified file). The integer <CODE>n</CODE>, 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
<EM>Database</EM> directive:

<P>
<PRE>    [tag export products][/tag]
</PRE>
<P>
Same thing, except to the file products/new_products.txt:

<P>
<PRE>    [tag export products products/newproducts.txt][/tag]
</PRE>
<P>
Same thing, except the export is done with a 
<FONT SIZE=-1>PIPE</FONT> delimiter:

<P>
<PRE>    [tag export products products/newproducts.txt 5][/tag]
</PRE>
<P>
The file is relative to the catalog directory, and only may be an absolute
path name if <EM>NoAbsolute</EM> is set to <CODE>No</CODE>.

<P><DT><STRONG><A NAME="item_flag">flag arg</A></STRONG><DD>

Sets a MiniVend condition.

<P>
The following enables writes on the <CODE>products</CODE> and <CODE>sizes</CODE> databases held in MiniVend internal 
<FONT SIZE=-1>DBM</FONT> format:

<P>
<PRE>    [tag flag write]products sizes[/tag]
</PRE>
<P>

<FONT SIZE=-1>SQL</FONT> databases are always writable if allowed by the 
<FONT SIZE=-1>SQL</FONT> database itself -- in-memory databases will never be written.


<P>
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).

<P><DT><STRONG><A NAME="item_log">log dir/file</A></STRONG><DD>

Logs a message to a file, fully interpolated for MiniVend tags. The
following tag will send every item code and description in the user's
shopping cart to the file logs/transactions.txt:

<P>
<PRE>    [tag log logs/transactions.txt]
    [item_list][item-code]  [item-description]
    [/item_list][/tag]
</PRE>
<P>
The file is relative to the catalog directory, and only may be an absolute
path name if <EM>NoAbsolute</EM> is set to <CODE>No</CODE>.

<P><DT><STRONG><A NAME="item_mime">mime description_string</A></STRONG><DD>

Returns a MIME-encapsulated message with the boundary as employed in the
other mime tags, and the <CODE>description_string</CODE> used as the Content-Description. For example

<P>
<PRE>   [tag mime My Plain Text]Your message here.[/tag]
</PRE>
<P>
will return

<P>
<PRE>  Content-Type: TEXT/PLAIN; CHARSET=US-ASCII
  Content-ID: [sequential, lead as in mime boundary]
  Content-Description: My Plain Text
  
  Your message here.
</PRE>
<P>
When used in concert with [tag mime boundary], [tag mime header], and [tag mime id], allows 
<FONT SIZE=-1>MIME</FONT> attachments to be included -- typically with PGP-encrypted credit card numbers. See the demo page ord/report.html for an example.


<P><DT><STRONG>mime boundary</STRONG><DD>

Returns a 
<FONT SIZE=-1>MIME</FONT> message boundary with unique string keyed on session 
<FONT SIZE=-1>ID,</FONT> page count, and time.


<P><DT><STRONG>mime header</STRONG><DD>

Returns a 
<FONT SIZE=-1>MIME</FONT> message header with the proper boundary for that session 
<FONT SIZE=-1>ID,</FONT> page count, and time.


<P><DT><STRONG>mime id</STRONG><DD>

Returns a 
<FONT SIZE=-1>MIME</FONT> message id with the proper boundary for that session 
<FONT SIZE=-1>ID,</FONT> page count, and time.


<P><DT><STRONG><A NAME="item_show_tags">show_tags</A></STRONG><DD>

The encased text will not be substituted for with MiniVend tags, with &lt; and [ characters changed to <CODE>&amp;</CODE>#lt; and <CODE>&amp;</CODE>#91; respectively.

<P>
<PRE>    [tag show_tags][value whatever][/tag]
</PRE>
<P><DT><STRONG><A NAME="item_time">time</A></STRONG><DD>

Formats the current time according to 
<FONT SIZE=-1>POSIX</FONT> strftime arguments. The following is the string
for Thursday, April 30, 1997.

<P>
<PRE>    [tag time]%A, %B %d, %Y[/tag]
</PRE>
<P><DT><STRONG><A NAME="item_touch">touch</A></STRONG><DD>

Touches a database to allow use of the <CODE>tag_data()</CODE> routine in
user-defined subroutines. If this is not done, the routine will error out
if the database has not previously been accessed on the page.

<P>
<PRE>    [tag touch products][/tag]
</PRE>
<P></DL>
<P>
<HR>


code: 01.55
section: MINIVEND_TAG_REFERENCE
type: item
title: [total-cost ...]

<A NAME="_total_cost_">[total-cost ...]</A></H2>
<P>
named: [total-cost cart*]

<P>
Expands into the total cost of all the items in the current shopping cart,
including sales tax (if any).

<P>
<HR>


code: 01.56
section: MINIVEND_TAG_REFERENCE
type: item
title: [userdb ...]

<A NAME="_userdb_">[userdb ...]</A></H2>
<P>
MiniVend provides a <CODE>[userdb ...]</CODE> tag to access the UserDB functions.

<P>
<PRE> [userdb
        function=function_name
        username=&quot;username&quot;*
        password=&quot;password&quot;*
        verify=&quot;password&quot;*
        oldpass=&quot;old password&quot;*
        shipping=&quot;fields for shipping save&quot;
        billing=&quot;fields for billing save&quot;
        preferences=&quot;fields for preferences save&quot;
        force_lower=1
        param1=value*
        param2=value*
        ...
        ]
</PRE>
<P>
* Optional

<P>
It is normally called in an <CODE>mv_click</CODE> or <CODE>mv_check</CODE> setting, as in:

<P>
<PRE>    [set Login]
    mv_todo=return
    mv_nextpage=welcome
    [userdb function=login]
    [/set]
</PRE>
<P>
<PRE>    &lt;FORM ACTION=&quot;[process-target]&quot; METHOD=POST&gt;
    &lt;INPUT TYPE=hidden NAME=mv_click VALUE=Login&gt;
    Username &lt;INPUT NAME=mv_username SIZE=10&gt;
    Password &lt;INPUT NAME=mv_password SIZE=10&gt;
    &lt;/FORM&gt;
</PRE>
<P>
There are several global parameters that apply to any use of the <CODE>userdb</CODE> functions. Most importantly, by default the database table is set to be <EM>userdb</EM>. If you must use another table name, then you should include a <CODE>database=table</CODE> parameter with any call to <CODE>userdb</CODE>. The global parameters (default in parens):

<P>
<PRE>    database     Sets user database table (userdb)
    show         Show the return value of certain functions
                 or the error message, if any (0)
    force_lower  Force possibly upper-case database fields
                 to lower case session variable names (0)
    billing      Set the billing fields (see Accounts)
    shipping     Set the shipping fields (see Address Book)
    preferences  Set the preferences fields (see Preferences)
    bill_field   Set field name for accounts (accounts)
    addr_field   Set field name for address book (address_book)
    pref_field   Set field name for preferences (preferences)
    cart_field   Set field name for cart storage (carts)
    pass_field   Set field name for password (password)
    time_field   Set field for storing last login time (time)
    expire_field Set field for expiration date (expire_date)
    acl          Set field for simple access control storage (acl)
    file_acl     Set field for file access control storage (file_acl)
    db_acl       Set field for database access control storage (db_acl)
</PRE>
<P>
<HR>


code: 01.57
section: MINIVEND_TAG_REFERENCE
type: item
title: [value ...]

<A NAME="_value_">[value ...]</A></H2>
<P>
named: [value name=field escaped=1 set=``new value'']

<P>
positional: [value field flag*]

<P>

<FONT SIZE=-1>HTML</FONT> examples:

<P>
<PRE>   &lt;PARAM MV=&quot;value name&quot;&gt;
   &lt;INPUT TYPE=&quot;text&quot; NAME=&quot;name&quot; VALUE=&quot;[value name]&quot;&gt;
</PRE>
<P>
Expands into the current value of the customer/form input field named by
field. If <A HREF="#item_flag">flag</A> is present, single quotes will be escaped with a backslash; this allows you
to contain the <A HREF="#item__value_">[value ...]</A> tag within single quotes. (It is somewhat better to use other quoting
methods.) When the value is returned, any MiniVend tags present in the
value will be escaped. This prevents users from entering MiniVend tags in
form values, which would be a serious security risk.

<P>
If the <CODE>set</CODE> value is present, the form variable value will be set to it and the empty
string returned. Use this to ``uncheck'' a checkbox or set other form
variable values to defaults. <STRONG>NOTE:</STRONG> This is only available in new-style tags, for safety reasons.

<P>
<HR>


code: 01.58
section: MINIVEND_TAG_REFERENCE
type: item
title: [[any]]

<A NAME="_any_">[[any]]</A></H2>
<P>
<STRONG>NOTE:</STRONG> This is ignored if using the new syntax.

<P>
Forces early interpolation of any tag. Sometimes needed if the order of
interpolation does not achieve the desired result (meaning you see MiniVend
tags displayed on the page).

<P>
<HR>


code: 01.58
section: MINIVEND_TAG_REFERENCE
type: item
title: [value-extended ...]

<A NAME="_value_extended_">[value-extended ...]</A></H2>
<P>
<PRE> named: [value-extended 
            name=formfield
            outfile=filename*
            ascii=1*
            yes=&quot;Yes&quot;*
            no=&quot;No&quot;*
            joiner=&quot;char|string&quot;*
            test=&quot;isfile|length|defined&quot;*
            index=&quot;N|N..N|*&quot;
            file_contents=1*
            elements=1*]
</PRE>
<P>
positional: [value-extended name]

<P>

<FONT SIZE=-1>HTML</FONT> examples:

<P>
<PRE>   No match found for &lt;PARAM MV=&quot;value-extended&quot;
                                                MV.JOINER=&quot; and &quot;
                                                MV.NAME=mv_searchspec&gt;
   &lt;INPUT TYPE=&quot;text&quot; NAME=&quot;mv_searchspec&quot;
        VALUE=&quot;[value-extended name=mv_searchspec index=0]&quot;&gt;
   &lt;INPUT TYPE=&quot;text&quot; NAME=&quot;mv_searchspec&quot;
        VALUE=&quot;[value-extended name=mv_searchspec index=1]&quot;&gt;
</PRE>
<P>
Expands into the current value of the customer/form input field named by
field. If there are multiple elements of that variable, it will return the
value at <A HREF="#item_index">index</A>; by default all joined together with a space.

<P>
If the variable is a file variable coming from a multipart/form-data file
upload, then the contents of that upload can be returned to the page or
optionally written to the <A HREF="#item_outfile">outfile</A>.

<DL>
<DT><STRONG>name</STRONG><DD>

The form variable 
<FONT SIZE=-1>NAME.</FONT> If no other parameters are present, then the
value of the variable will be returned. If there are multiple elements,
then by default they will all be returned joined by a space. If <A HREF="#item_joiner">joiner</A>
is present, then they will be joined by its value.

<P>
In the special case of a file upload, the value returned is the name of the
file as passed for upload.

<P><DT><STRONG><A NAME="item_joiner">joiner</A></STRONG><DD>

The character or string that will join the elements of the array. Will
accept string literals such as ``\n'' or ``\r''.

<P><DT><STRONG><A NAME="item_test">test</A></STRONG><DD>

Three tests -- <CODE>isfile</CODE> returns true if the variable is a file upload.
<CODE>length</CODE> returns the length. <CODE>defined</CODE> returns whether the value has ever been set at all on a form.

<P><DT><STRONG><A NAME="item_index">index</A></STRONG><DD>

The index of the element to return if not all are wanted. This is useful
especially for pre-setting multiple search variables. If set to <CODE>*</CODE>, will return all (joined by <A HREF="#item_joiner">joiner</A>). If a range, such as <CODE>0 .. 2</CODE>, will return multiple elements.

<P><DT><STRONG><A NAME="item_file_contents">file_contents</A></STRONG><DD>

Returns the contents of a file upload if set to a non-blank, non-zero
value. If the variable is not a file, returns nothing.

<P><DT><STRONG><A NAME="item_outfile">outfile</A></STRONG><DD>

Names a file to write the contents of a file upload to. It will not accept an absolute file name; the name must be relative to the catalog directory. If you wish to write images or other files that would go to 
<FONT SIZE=-1>HTML</FONT> space, you must use the 
<FONT SIZE=-1>HTTP</FONT> server's
 <A HREF="#item_Alias">Alias</A> facilities or make a symbolic link.

<P><DT><STRONG><A NAME="item_ascii">ascii</A></STRONG><DD>

To do an auto-ASCII translation before writing the <A HREF="#item_outfile">outfile</A>, set the <A HREF="#item_ascii">ascii</A> parameter to a non-blank, non-zero value. Default is no translation.

<P><DT><STRONG><A NAME="item_yes">yes</A></STRONG><DD>

The value that will be returned if a test is true or a file is written
successfully. Defaults to <CODE>1</CODE> for tests and the empty string for uploads.

<P><DT><STRONG><A NAME="item_no">no</A></STRONG><DD>

The value that will be returned if a test is false or a file write fails.
Defaults to the empty string.

<P></DL>
<P>
<HR>


code: 01.59
section: MINIVEND_TAG_REFERENCE
type: item
title: [ n [any] HTML n ]

<A NAME="_n_any_HTML_n_">[ n [any] HTML n ]</A></H2>
<P>
<STRONG>NOTE:</STRONG> This is ignored if using the new syntax.

<P>
Where n is a single digit in the range 0-9. If present, it forces early
interpolation of that region of MiniVend tags, and is differentiated from
other early interpolation areas. The enclosed MiniVend tags will still be
interpolated in the normal order, but it can usually be combined with the
[post] [/post] pair to achieve the desired order.

<P>
<HR>


code: 02.00
section: MINIVEND_TAG_REFERENCE
type: overview
title: MINIVEND TAG REFERENCE

<A NAME="MINIVEND_TAG_REFERENCE">MINIVEND TAG REFERENCE</A></H1>
<P>
There are dozens of MiniVend pre-defined tag functions. If you don't see
just what you need, you can use <CODE>USER DEFINED TAGS</CODE> to create tags just as powerful as the pre-defined ones.

<P>
There are two styles of tag -- HTML/new, and old. Old style is a legacy
from prior versions of MiniVend and is no longer in standard use, but its
positional syntax can <EM>usually</EM> still be used in New/HTML mode for convenience.

<P>
In the new style, you can specify constructs inside an 
<FONT SIZE=-1>HTML</FONT> tag:

<P>
<PRE>    &lt;TABLE MV=&quot;if items&quot;&gt;
    &lt;TR MV=&quot;item-list&quot;&gt;
    &lt;TD&gt; [item-code] &lt;/TD&gt;
    &lt;TD&gt; [item-description] &lt;/TD&gt;
    &lt;TD&gt; [item-price] &lt;/TD&gt;
    &lt;/TR&gt;&lt;/TABLE&gt;
</PRE>
<P>
The above will loop over any items in the shopping cart, displaying their part number, description, and price, but only 
<FONT SIZE=-1>IF</FONT> there are items in the cart.


<P>
The same thing can be achieved with:

<P>
<PRE>    [if items]
    &lt;TABLE&gt;
    [item-list]
    &lt;TR&gt;
    &lt;TD&gt; [item-code] &lt;/TD&gt;
    &lt;TD&gt; [item-description] &lt;/TD&gt;
    &lt;TD&gt; [item-price] &lt;/TD&gt;
    &lt;/TR&gt;
    [/item-list]&lt;/TABLE&gt;
    [/if]
</PRE>
<P>
To use the new more regular syntax by default, set the <EM>NewTags</EM>
directive to <CODE>Yes</CODE>. The demo catalog is distributed with <CODE>NewTags Yes</CODE>
starting at MiniVend 3.07.

<P>
In most cases, tags specified in the old positional fashion will work the
same in the new style. The only time you will need to modify them is when
there is some ambiguity as to which parameter is which (usually due to
whitespace), or when you need to use the output of a tag as the attribute
parameter for another tag.

<P>
<STRONG>TIP:</STRONG> This will not work in the new style as it did in the old:

<P>
<PRE>    [page scan se=[scratch somevar]]
</PRE>
<P>
To get the output of the <CODE>[scratch somevar]</CODE> interpreted, you must place it within a named and quoted attribute:

<P>
<PRE>    [page href=scan arg=&quot;se=[scratch somevar]&quot;]
</PRE>
<P>
What is done with the results of the tag depends on whether it is a
<EM>container</EM> or <EM>standalone</EM> tag. 
<FONT SIZE=-1>A</FONT> container tag is one which has an end tag, i.e. <CODE>[tag] stuff [/tag]</CODE>. 
<FONT SIZE=-1>A</FONT> standalone tag has no end tag, as in [area
href=somepage]. (Note that [page ...] and [order ..] are <STRONG>not</STRONG> container tags.)

<P>

<FONT SIZE=-1>A</FONT> container tag will have its output re-parsed for
more MiniVend tags by default. If you wish to inhibit this behavior, you
must explicitly set the attribute <STRONG>reparse</STRONG> to 0. (Prior to MiniVend 3.09, <STRONG>reparse</STRONG>
did not exist.) Note that you will almost always wish the default action.

<P>
With some exceptions ([include], [calc], [currency], and [buttonbar ..] among them) the output of a standalone tag will not be re-interpreted for MiniVend tag constructs. All tags accept the 
<FONT SIZE=-1>INTERPOLATE=1</FONT> tag modifier, which causes the interpretation to take place. It is frequent that you will
 <STRONG>not</STRONG> want to interpret the contents of a [set variable] 
<FONT SIZE=-1>TAGS</FONT> [/set] pair, as that might contain tags which
should only be upon evaluating an order profile, search profile, or <EM>mv_click</EM> operation. If you wish to perform the evaluation at the time a variable is set, you would use [set name=variable interpolate=1] 
<FONT SIZE=-1>TAGS</FONT> [/set].


<P>
To use the new syntax only on a particular page, place <STRONG>one</STRONG>  <CODE>[new]</CODE>
tag in your page. Likewise, to use old syntax when new is the default,
place <STRONG>one</STRONG>  <CODE>[old]</CODE> tag in the page.

<P>
If you have regions of the page which work under the old style and fail
with the new style, you can surround them with [compat] [/compat] tag pair.
This will evaluate that region only with the old style repeated
interpolation.

<P>
<STRONG>NOTE WHEN USING THE OLD TAG PARSER (NewTags No) or [compat][/compat]:</STRONG>
MiniVend in old mode 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:

<P>
<PRE>  tag [[ANY TAG]] cart item-list loop default value scratch calc if lookup
  set data msql|sql file finish_order frames_on frames_off
  framebase body help buttonbar random rotate checked selected
  accessories field pagetarget area areatarget page last_page
  perl order nitems discount subtotal shipping shipping_description
  salestax total_cost price currency description row process_order
  process_search process_target
</PRE>
<P>
<HR>


