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. Also recognized are 'multiple', which builds a multiple select box, and 'list', which simply lists the possible values. 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

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.

[/calc]
Terminates the calculated region.

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

[/col]
Terminates the column field.

[comment] code [/comment]
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.

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

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

[discount_price n*]
Evaluates to the discount price for quantity n (from the products file) of the current item. Returns regular price if not discounted.

[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_data database fieldname]
If the database field fieldname in database is non-blank for the current item, the following text up to the [/if_data] tag is substituted. This can be used to substitute IMG or other tags only if the corresponding source item is present. Also accepts a [else]else text[/else] pair for the opposite condition. Operates in search lists, item list, and the on-the-fly page.

[/if_data]
Terminates an [if_data database fieldname] element.

[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. Operates in search lists, item lists, and the on-the-fly page.

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]
Terminates an [if_field fieldname] element.

[if_loop_data database fieldname]
Same as [if_data ...], except operates in loop lists.

[/if_loop_data]
Terminates an [if_loop_data database fieldname] element.

[if_loop_field fieldname]
Same as [if_field ...], except operates in loop lists.

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

[if_msql_data database fieldname]
Same as [if_data ...], except operates in Msql lists.

[/if_msql_data]
Terminates an [if_msql_data database fieldname] element.

[if_msql_field fieldname]
Same as [if_field ...], except operates in Msql lists.

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

[/if_data]
Terminates an [if_data database fieldname] element.

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

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

[if config CreditCardAuto] Auto credit card validation is enabled. [/if]

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

[if data products::size::99-102] There is size information. [else] No size information. [/else] [/if] [if data products::size::99-102 =~ /small/i] There is a small size available. [else] No small size available. [/else] [/if]

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

[if discount 99-102] Item is discounted. [/if]

explicit
A 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.

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

This example is a bit contrived, as the same thing could be accomplished with [if value country =~ /u\.?s\.?a?/i], but you will run into many situations where it is useful.

This will work for Variable values:

[if explicit "__MYVAR__"] .. [/if]

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

[if file /home/user/www/images/[item-code].gif] <IMG SRC="[item-code].gif"> [/if]

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]

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

[if ordered 99-102] ... [/if] Checks the status of an item on order, true if item 99-102 is in the main cart. [if ordered 99-102 layaway] ... [/if] Checks the status of an item on order, true if item 99-102 is in the layaway cart. [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. [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: [if type=ordered term="99-102" compare="size =~ /large/i"] To make sure it is exactly large, you could use: [if ordered 99-102 main size eq 'large'] ... [/if] [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.)

salestax
The salestax database.

[if salestax [value state] > 0] There is salestax for your state. No salestax for your state. [/else] [/if]

Key matching is case-insensitive.

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

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

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

shipping
The shipping database.

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.

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.

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.

[/if]
Terminates an if conditional.

[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_discount]
Returns the difference between the regular price and the discounted price.

[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]
Ends an item list.

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

Within any order page, the [item_list cart*] element shows a list of all the items ordered by the customer so far. It works by repeating the source between [item_list] and [/item_list] once for each item ordered. Between the item_list markers the various [item_....] elements will return information for the current item.

Item lists cannot be used inside the on-the-fly page or within search lists, as the tags are the same.

[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 next_img* prev_img* page_img*]
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.

If the optional arguments next_img, prev_img, and/or page_img are present, they represent image files that will be inserted instead of the standard 'Next', 'Previous', and page number. If prev_img is none, then no previous link will be output. If page_img is none, then no links to pages of matches will be output. These are URLs, are substituted for with ImageDir, and will be encased in IMG tags.

In addition, if page_img is used, it will be passed an argument of the digit that is to be represented. This would allow an image generator program to be used, generating page numbers on the fly.

As an example, if you use [more-list next.gif prev.gif page_num.cgi], the following will be the anchors:

Previous <IMG SRC="prev.gif"> Page 1 <IMG SRC="/cgi-bin/page_num.cgi?1"> Page 2 <IMG SRC="/cgi-bin/page_num.cgi?2"> Next <IMG SRC="next.gif">

[ 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]
Perl code can be directly embedded in MiniVend 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. If you wish to have default arguments supplied to them, use the SubArgs directive.

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

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. A [loop item,item..] list is similar, but does not include the items that are associated with the order list, and the tags are prefixed loop_, so that loop and item lists may be interspersed. Item lists are evaluated before loop lists, so you can put an item-code inside of an loop list. If you want to reverse the order, put the loop list in a double set of brackets to force earlier evaluation. Up to 1024 items may be present in a loop list.

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

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

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

[/search_list]
Ends the search list.

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

The following enables writes on the products and sizes databases:

[tag flag write]products sizes[/tag]

mSQL and in-memory databases are always writeable.

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

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.

[tag scan/options]encased text[/tag]
Builds a one-click search based on the enclosed text. Properly translates whitespace and non-word characters to be parseable by MiniVend. You can add the normal scan options, just the se=searchtext parameter will be affected. These two sequences evaluate the same:

[tag scan/sf=category]Renaissance[/tag] [page scan/sf=category/se=Renaissance]Renaissance[/page]

Where it is useful is in adding long strings that would otherwise be difficult to encode, like

[tag scan/sf=author/os=yes]John F. Kennedy[/tag]

instead of:

[page scan/sf=author/se=John.20F..20Kennedy]John F. Kennedy[/page]

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

[tag show_tags][value whatever][/tag]

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]

touch
Touches a database to allow use of the tag_data() 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.

[tag touch]products[/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