tags


MiniVend Alphabetical Tag Reference

MiniVend has over 80 different elements (we will also interchangeably refer to them as tags) which are used to access the database, format and display HTML pages, and perform system control. A reference to most of the tags follows.

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

When a tag is separated by an underscore, as in item_list, a dash is just as appropriate (i.e. item-list). They are interchangeable, except that the ending tag and beginning tag should match (don't use [item-list] list [/item_list]).

Beginning with MiniVend 3.0, there is an experimental page syntax which interprets tags with named arguments, similar to HTML. It has more regular precedence rules -- tags are interpreted in sequential order rather than a set interpolation sequence. (Page serving speed is usually somewhat slower when using the new syntax.) The calling syntax is shown under the normal syntax -- if not specified, it is the same. Some tags (those inside item_list or loop constructs, for example) are not changed.

To use the new page syntax, place one [new] tag at the top of the page. To force old syntax, place one [old] tag at the very top of the page. Further [new] and [old] tags will control syntax in re-evaluated portions of the page (for example, within the [tag]minivend tags[/tag] construct).

Tag Descriptions

[accessories code attribute*, type*, field*, database*, name*]
(new syntax [accessories code=``code'' arg="attribute*, type*, field*, database*, name*])

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

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

attribute The item attribute as specified in the UseModifier configuration directive. Typical are "size" or "color". type The action to be taken. The default is 'select', which builds an HTML select form entry for the attribute. field The database field name to be used to build the entry (usually a select form field). Defaults to a field named the same as the attribute. database The database to find B<field> in, defaults to the first products file where the item code is found. name Name of the form variable to use if a form is being built. Defaults to mv_order_B<attribute> -- i.e. if the attribute is B<size>, the form variable will be named B<mv_order_size>.

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

name=Label Text, name=Label Text*

The label text is optional -- if none is given, the name will be used.

If an asterisk is the last character of the label text, the item is the default selection. If no default is specified, the first will be the default. An example:

[accessories TK112 color]

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:

<SELECT NAME="mv_order_color"> <OPTION VALUE="beige">Almond <OPTION VALUE="gold">Harvest Gold <OPTION SELECTED>White <OPTION VALUE="green">Avocado </SELECT>

In combination with the mv_order_item and mv_order_quantity variables this can be used to allow entry of an attribute at time of order.

[[any]]
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).

NOTE: This is ignored if using the new syntax.

[area pg]
(new syntax [area href=``dir/page'' target=``frame'' arg=``argument''])

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

The optional arg is used just as in the page tag.

[areatarget pg frame arg*]
(new syntax [area href=``dir/page'' target=``frame'' arg=``argument'']

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

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

If frames are enabled, this will expand to:

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

If frames are not enabled, this will expand to:

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

The optional arg is used just as in the page tag.

[body n]
(new syntax [body type=``n''])

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

[buttonbar n]
(new syntax [buttonbar type=``n''])

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

[calc]
Starts a region where the arguments are calculated according to normal arithmetic symbols. For instance:

[calc] 2 + 2 [/calc]

will display:

4

[/calc]
Terminates the calculated region.

TIP: The [calc] tag is really the same as the [perl] tag, except that it doesn't accept arguments, is more efficient to parse, and is interpolated at a higher precedence.

[cart name]
(new syntax [cart name=``name''])

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 [nitems] and [shipping] will reflect the normal price field -- you must either emulate those operations with embedded Perl or the [item-list], [calc], and [currency] tags, or use an embedded Perl routine to set it. This would change the price field used:

[[perl config]$Safe{'config'}->{PriceField} = 'discount_price'[/perl]]

Place it at the top of the page, before the [item-list], to ensure it is interpolated early enough.

[checked var_name value]
(new syntax [checked name=``var_name'' value=``value''])

This will output CHECKED if the variable var_name is equal to value . Not case sensitive.

[col width=nn wrap=yes|no gutter=n align=left|right|input spacing=n]
Sets up a column for use in a [row]. This parameter can only be contained inside a [row nn] [/row] tag pair. Any number of columns (that fit within the size of the row) can be defined.

The parameters are:

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

[condition] text [/condition]
Only used with the [if explicit] tag. Allows an arbitrary expression in Perl 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 [perl] construct.

[currency]
When passed a value of a single number, formats it according to the currency specification. For instance:

[currency]4[/currency]

will display:

4.00

Uses the Locale, PriceDivide, and PriceComma settings as appropriate, and can contain a [calc] region. If Locale is set to 'pt', and PriceDivide to 100, the following

[currency] [calc] 50000 + 100000 [/calc] [/currency]

the number 1.500,00 will be displayed.

[data area field key ``value''* increment*]
(new syntax: [data base=``database'' name=``field'' code=``key'' value=``value'' op="increment] )

Returns the value of the field in any of the arbitrary databases, or from the variable namespaces. If the optional value is supplied, the database value will be changed to it -- no ] characters may be present in the value unless using the new tag style. If the option increment* is present, the field will be atomically incremented with the value in value .

If a DBM-based database is to be modified, it must be flagged writable on the page calling the write tag. Use [tag flag write]products[/tag] to mark the products database writeable, for example.

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

[/col]
Terminates the column field.

[description code database*]
(new syntax [description code=``code'' base=``database''])

Expands into the description of the product identified by code as found in the products database. If there is more than one products file defined, they will be searched in order unless constrained by the optional argument base.

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

[field name code]
(new syntax [field code=``code'' name=``fieldname''])

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

[file name]
(new syntax [file name=``name''])

Inserts the contents of the named file. The file should normally be relative to the catalog directory -- file names beginning with / or .. are only allowed if the MiniVend server administrator has disabled NoAbsolute.

[finish_order page*]
(new syntax [finish_order href=``page''])

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

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

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

This tag is deprecated -- it is suggested that you use the construct:

[if items] [page ord/basket]Check Basket[/page] [/if]

It will be removed in a future version of MiniVend.

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

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

[frames_on]
Turns on the frames processing option, which is disabled by default. The proper way to use this is to put it ONLY in 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.

[/if]
Terminates an if conditional.

[/if_field]
Terminates an [if_field fieldname] element.

COMPATIBILITY NOTE: MiniVend 1.02 used the [/if] end tag for an [if_field] element. This was supported through MiniVend 1.03, but is gone in 2.0 -- you may need to change it.

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

[if type field op* compare*]
(new syntax [if type=``type'' term=``field'' op=``op'' compare=``compare''])

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

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

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

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

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

[if items]You have items in your shopping cart.[/if] [if items layaway]You have items on layaway.[/if]

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

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

accessory
The accessories database.

shipping
The shipping database.

salestax
The salestax database.

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

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

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

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

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

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

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

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

[item_accessories attribute*, type*, field*, database*, name*]
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.

[item_code]
Evaluates to the product code for the current item.

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

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

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

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

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

[/item_list]
Terminates the [item_list] tag.

[item_list cart*]
(new syntax [item_list name=``cart''])

Places an iterative list of the items in the specified shopping cart, the main cart by default. See Item Lists for a description.

[item_modifier attribute]
Evaluates to the modifier value of attribute for the current item.

[item_price n*]
Evaluates to the price for quantity n (from the products file) of the current item.

[item_quantity]
Evaluates to the quantity ordered for the current item.

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

[loop_accessories]
Evaluates to the value of the Accessories database entry for the item.

[loop_code]
Evaluates to the product code for the current item.

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

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

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

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

[loop_price n*]
Evaluates to the price for optional quantity n (from the products file) of the current item.

.

[loop item item item] value [/loop]
(new syntax: [loop arg=``item item item''])

Returns a string consisting of the value, 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.

Limited to 1024 values in the list in the direct call -- to iterate over a complete database use [tag each database] list text [/tag].

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

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

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

Previous 1 2 3 4 5 6 Next

The current page will not be a hyperlink. Every time the new link is pressed, the list is re-built to correspond to the current page. If there is no Next or Previous page, that link will not be shown.

See the fr_resul.html or search.html files for examples. Make sure you insert this item between a [more_list] and [/more_list] element pair.

[/more_list]
Companion to [more_list].

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

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

[msql array] SQL [/msql]
A complete array of arrays, suitable for eval by Perl, can be returned by this query. This tag pair encloses any valid mSQL 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:

[perl]
    my $string =<<'EOF';
 [msql array]select * from arbitrary where code <= '19'[/msql]
 EOF
    my $ary = eval $string;
    my $out = '';
    my $i;
    foreach $i (@$ary) {
        $out .= $i->[0];
        $out .= "
"; } $out; [/perl]

NOTE: The 'EOF' string terminator must START the line, and not have trailing characters. DOS users, beware of carriage returns!

[msql hash] SQL [/msql]
A complete hash of hashes, suitable for eval by Perl, can be returned by this query. This tag pair encloses any valid mSQL 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:

[perl]
    my $string =<<'EOF';
 [msql hash]select * from arbitrary where code <= '19'[/msql]
 EOF
    my $hash = eval $string;
    my $out = '';
    my $key;
    foreach $key (keys %$hash) {
        $out .= $key->{field1};
        $out .= "
"; } $out; [/perl]

[msql html] SQL [/msql]
This tag returns a set of HTML table rows with bold field names at the top, followed by each row in a set of table cells. The <TABLE> and </TABLE> tags are not supplied, so you can set your own border and shading options. Example:

<TABLE BORDER=2> [msql html]select * from arbitrary where code > '19' order by field2[/msql] </TABLE>

[msql list SQL] list [/msql]
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 HTML table:

<TABLE BORDER=2> <TR><TH><B>SKU</B></TH><TH><B>Description</B></TH><TH><B>Price</B></TH> [msql list select * from arbitrary where code > '19' order by field2 ] <TR> <TD>[page [msql-code]][msql-code]</A></TD> <TD>[msql-param 1]</TD> <TD>[msql-param 2]</TD> </TR> [/msql] </TABLE>

It uses the same tags as in the [loop_list], except prefixed with msql. Available are the following, in order of interpolation:

[msql_param n] Field n of the returned query (in the row) [if_msql_field fld] Returns enclosed text only product field not empty [/if_msql_field] Terminator for above [if_msql_data db fld] Returns enclosed text only if data field not empty [/if_msql_field] Terminator for above [msql_increment] Returns integer count of row [msql_code] The first field of each row returned [msql_data db fld] Database field for [msql_code] [msql_description] Product description for [msql_code] [msql_field fld] Product field for [msql_code] [msql_link] Same as item-link [msql_price q*] Price for [msql_code], optional quantity q

[msql param] SQL [/msql]
A list of keys, or in fact any mSQL fields, can be returned as a set of parameters suitable for passing to a program or list primitive. This tag pair encloses any valid mSQL 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.

[msql set] SQL [/msql]
Any arbitrary SQL 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:

[msql 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]' ) [/msql]

The values entered by the user are escaped, which prevents errors if quote characters have slipped into their entry.

[ n [any] HTML n ]
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 MiniVendtags will still be interpolated in the normal order, but it can usually be combined with the [post] [/post] pair to achieve the desired order.

NOTE: This is ignored if using the new syntax.

[nitems cart*]
Expands into the total number of items ordered so far. Takes an optional cart name as a parameter.

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

[order code cart/page* database*]
(new syntax [order code=``code'' href=``cart/page'' base=``database''])

Expands into a hypertext link which will include the specified code in the list of products to order and display the order page. code should be a product code listed in one of the ``products'' databases. The optional argument cart/page selects the shopping cart the item will be placed in (begin with / to use the default cart 'main') and the order page that will display the order. The optional argument database constrains the order to a particular products file -- if not specified, all databases defined as products files will be searched in sequence for the item.

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

TIP: A small efficiency boost in large pages is to just use the </A> tag.

[page pg arg*]
(new syntax [page href=``dir/page'' target=``frame'' arg=``argument''])

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

The additional argument will be passed to MiniVend and placed in the {arg} session parameter. This allows programming of a conditional page display based on where the link came from. The argument is then available with the tag [data session arg], or the embedded Perl session variable $Safe{'session'}->{arg}.

A bit of magic occurs if MiniVend has built a static page for the target page. Instead of generating a normal MiniVend-parsed page reference, a static page reference will be inserted.

[pagetarget pg frame arg*]
(new syntax [page href=``dir/page'' target=``frame'' arg=``argument''])

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

The optional arg is used just as in the page tag.

[perl args] code [/perl]
As of MiniVend 2.0, Perl code can be directly embedded in pages. The tag is specified as [perl arguments] any_legal_perl_code [/perl].

(new syntax [perl arg=``arguments''])

Using MiniVend variables with embedded Perl capability is not recommended unless you are thoroughly familiar with Perl 5 references. It is best to pass the values you need with MiniVend tags, which are mostly interpolated before the [perl] tags. Example:

# Simple example my $shipmode = '[value mv_shipmode]'; # If the item might contain a single quote my $comments = '[value comments escaped]'; # Another method my $comments = q{[value comments]};

This allows you to pass user-space variables for most needed operations. You can pass whole lists of items with constructs like:

# Perl ignores the trailing comma my(%prices) = ( [item_list] '[item_code]', '[item-price]', [/item_list]);

Even easier is the definition of a subroutine:

[set Thanks] my($name, $number) = @_; "Thanks, $name, for your order! The order number is $number.\n"; [/set] [perl sub] Thanks ('[value name escaped]', '[value mv_order_number escaped]') [/perl]

(The escaped causes any single quotes which might be contained in the values to be escaped, preventing syntax errors in the case of a name like ``O'Reilly''.)

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

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

carts
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}}.

# Move contents of 'layaway' cart to main cart $Safe{carts}->{main} = $Safe{carts}->{layaway}; $Safe{carts}->{main} = [];

Careful with this -- you can lose the items on order with improper code, though syntax errors will be caught before the code is run.

cgi
Gives read-only access to the actual variables that were passed in the current CGI session. This is useful for testing what the user actually placed on the form, not just what MiniVend placed in the session database. Called with

# Set if the user had a value for name in the *current* form $name = $Safe{'cgi'}->{name};

config
Gives read-write access to the configuration of the catalog. USE WITH EXTREME CAUTION -- many of the variables are references to anonymous arrays and hashes. You can crash your catalog if you modify the wrong thing. Referred to in your code as $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.

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

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

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

items
Gives read-only access to the items on order, for the current cart. 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}}.

# Product code of first item in cart $item_code = $Safe{items}->[0]->{code}; # Quantity for third item in cart $item_code = $Safe{items}->[2]->{quantity}; # Color of second item in cart $item_code = $Safe{items}->[2]->{color};

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

sub
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 @_ argument array.

IMPORTANT NOTE: Global subroutines are not subject to the stringent security checking of the Safe module, so almost anything goes there. The subroutine will be able to modify any variable in MiniVend, and will be able to write to read and write any file that the MiniVend daemon has permission to write. Though this gives great power, it should be used with caution. Careful! They are defined in the main minivend.cfg file, so should be safe from individual users in a multi-catalog system.

Global subroutines are defined in minivend.cfg with the GlobalSub directive.

Catalog subroutines are defined in catalog.cfg, with the Sub directive. They are subject to the stringent Safe.pm security restrictions that are controlled by SafeUntrap.

Scratch subroutines are defined in the pages, and are also subject to Safe.pm checking. See the beginning of this section for an example of a subroutine definition. There is no ``sub name { }'' that surrounds it -- the subroutine is named from the name of the scratch variable.

values
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'}->{variable}.

# Read the user's selected shipping mode my $shipmode = $Safe{values}->{mv_shipmode};

The code can be as complex as desired, but cannot use any operators.that modify the filesystem or use ``unsafe'' operations like ``system'', ``exec'', or backticks. These constraints are enforced with the default permissions of the standard Perl module Safe -- operations may be untrapped on a system-wide basis with the SafeUntrap directive.

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

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

[perl] my $tmp = "Hello, world!"; $tmp; [/perl]

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

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

[perl browser] my $html = '<H5>'; $html .= $Safe{'browser'}; $html .= '</H5>'; $html; [/perl]

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

[perl values] my $string = "Hi, " . $Safe{values}->{'name'} ". The time is now "; $string .= localtime; $string; [/perl]

[post]
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.

NOTE: This is ignored if using the new syntax.

[/post]
Terminates a [post] region.

[price code quantity* database*]
(new syntax [price code=``code'' quantity=``quantity'' base=``database''])

Expands into the price of the product identified by code as found in the products database. If there is more than one products file defined, they will be searched in order unless constrained by the optional argument base. The optional argument quantity selects an entry from the quantity price list.

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

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

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

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

[rotate ceiling*]
(new syntax [rotate ceiling=``n''])

Selects from the predefined rotating banner messages, and is stripped if none exist. The optional ceiling sets the highest number that will be selected -- the default is to sequence through all defined rotating banners. Each user has a separate rotation pattern. See Controlling Page Appearance.

[/row]
Terminates a [row nn] element.

[row nn]
(new syntax [row width=``nn''])

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

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

[/search_list]
Ends the search list.

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

In particular, all of the item tags described under order page are active. The most useful one might be [item_link], which if properly used, can allow the user to search the catalog for an item, then click a link to go to detailed catalog page for the item. See the sample results.html page for an example.

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

[selected var_name value MULTIPLE*]
(new syntax [selected name=``var_name'' value=``value'' multiple=``yes''])

This will output SELECTED if the variable var_name is equal to value . If the optional MULTIPLE argument is present, it will look for any of a variety of values. Not case sensitive.

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

<SELECT NAME="color"> <OPTION [selected color blue]> Blue <OPTION [selected color green]> Green <OPTION [selected color red]> Red </SELECT>

Here is the same thing, but for a shopping-basket color selection

<SELECT NAME="[modifier-name color]"> <OPTION [selected [modifier-name color] blue]> Blue <OPTION [selected [modifier-name color] green]> Green <OPTION [selected [modifier-name color] red]> Red </SELECT>

[set variable]value[/set]
(new syntax [set name=``variable''] value [/set])

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

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

[shipping_description mode*]
(new syntax [shipping_description name=``mode''])

The text description of mode -- the default is the shipping mode currently selected.

[sort frn]
Placed inside the search list. Causes sorting of the search return, starting from the first position on the line. The fields that are there to sort are set by mv_return_fields. Accepts none, any, or combinations of the flags:

f case-insensitive sort (folded) (mutually exclusive of n) n numeric order (mutually exclusive of f) r reverse sort

[sort]<options>[/sort]
Placed inside the search list. Causes sorting of the search return based on the passed options. The fields that are there to sort are set by mv_return_fields.

The field options passed in either numeric or field name form. If they are field numbers, they are numbered as sent to the search list in the order specified by mv_return_fields, starting from 0 and proceeding upwards. If column names, they are as found in the first record of the searched file (by default the ASCII source for the product database), except for the key or first field. followed by a required colon (:) and the options, if any.

Accepts none, any, or combinations of the flags:

f case-insensitive sort (folded) (mutually exclusive of n) n numeric order (mutually exclusive of f) r reverse sort

The <options> are a field number and an optional flag or flags, in a similar fashion to the Unix sort command, and are interpolated for form values before being used. As an example, if you set up the following fields on your search form:

<INPUT TYPE="hidden" NAME="mv_return_fields" VALUE="0,title,artist,price"> <INPUT TYPE="radio" NAME="the_sort_field" VALUE="title"> Sort by Title <INPUT TYPE="radio" NAME="the_sort_field" VALUE="artist"> Sort by Artist <INPUT TYPE="radio" NAME="the_sort_option" VALUE=""> Forward sort <INPUT TYPE="radio" NAME="the_sort_option" VALUE="r"> Reverse sort NOTE: The 0 refers to the database code/key used for [item-code]

This would combine with the following search result page fragment to sort by either title or artist.

[search-list] [sort] [value the_sort_field]:[value the_sort_option] [/sort] 2r or <1>.

PERFORMANCE TIP: on heavily trafficed systems, it will pay to use only column numbers rather than named fields, as it reduces processing and may obviate an access to the searched file to find the field names.

[static /html/path] static-area [/static]
Removed in MiniVend 3.00 -- the automatic static page-building capability of MiniVend takes care of this automatically.

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

[tag arg* arg*]text[/tag]
Performs any of a number of operations, based on the presence of arg. The arguments that may be given are:

each database
Returns a loop-list with every key in database evaluated as the [loop-code]. This will return the key and field name for every record in the products database:

[tag each products][loop-code] [loop-field name]<BR>[/tag]

export database file* type*
Exports a complete MiniVend database to its text source file (or any specified file). The integer n, if specified, will select export in one of the enumerated MiniVend export formats. The following tag will export the products database to products.txt (or whatever you have defined its source file as), in the format specified by the Database directive:

[tag export products][/tag]

Same thing, except to the file products/new_products.txt:

[tag export products products/newproducts.txt][/tag]

Same thing, except the export is done with a PIPE delimiter:

[tag export products products/newproducts.txt 5][/tag]

The file is relative to the catalog directory, and only may be an absolute path name if NoAbsolute is set to No.

flag arg
Sets a MiniVend condition, currently only enabling writes on a DBM database or databases. The following enables writes on the products and sizes databases:

[tag flag write]products sizes[/tag]

mSQL and in-memory databases are always writeable.

log dir/file
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:

[tag log logs/transactions.txt] [item_list][item-code] [item-description] [/item_list][/tag]

The file is relative to the catalog directory, and only may be an absolute path name if NoAbsolute is set to No.

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

[tag mime My Plain Text]Your message here.[/tag]

will return

Content-Type: TEXT/PLAIN; CHARSET=US-ASCII Content-ID: [sequential, lead as in mime boundary] Content-Description: My Plain Text Your message here.

When used in concert with [tag mime boundary], [tag mime header], and [tag mime id], allows MIME attachments to be included -- typically with PGP-encrypted credit card numbers. See the demo page ord/receipt.html for an example.

mime boundary
Returns a MIME message boundary with unique string keyed on session ID, page count, and time.

mime header
Returns a MIME message header with the proper boundary for that session ID, page count, and time.

mime id
Returns a MIME message id with the proper boundary for that session ID, page count, and time.

time
Formats the current time according to POSIX strftime arguments. The following is the string for Thursday, April 30, 1997.

[tag time]%A, %B %d, %Y[/tag]

[tag]encased text[/tag]
If no argument is supplied to the [tag][/tag] pair, the encased text will be early-interpolated for MiniVend tags. This can be especially useful when using the new page syntax, as you can force certain tags to be interpolated using the old syntax (just use an [old] tag to begin with).

.

[then] text [/then]
This is optional, as the text immediately following the [if ..] tag is used as the conditionally substitued text. When used, the [then] [/then] pair allows more readable constructs, as all whitespace around the [then] and tags will be stripped. If you wish to have leading or trailing whitespace, you can enclose the value in single or double quotes.

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

[uniq]
Placed immediately after the [search_list] tag. If specified on a sorted return list, causes only the first line containing an [item-code] to be returned -- all subsequent lines will not be interpreted on the list. Note that [matches] and [more-list] may not operate as you wish in this case.

[value field flag*]
Expands into the current value of the customer input field named by field. If flag is present, single and double quotes will be escaped with a backslash; this allows reliable SQL inserts. See the section on input fields for more information.

.

Cache Invalidation

Tags which cause static building or cacheing to fail are:

[cart ...] [if validcc ...] [salestax] [checked ...] [if value ...] [salestax] [data ...]* [item_list] [scratch ...] [default ...] [last_page] [selected ...] [discount] [lookup ..] [shipping] [frames_on|off] [loop-data ...]* [shipping_desc] [if data ...]* [loop-field ...]* [sql set] [if discount ...] [msql set] [subtotal] [if items ...] [nitems] [total_cost] [if scratch ...] [nitems] [value ...] [if session ...] [perl] * Only if database referenced is dynamic