=head1 NAME

ictags - Interchange Tags Reference

=head1 DESCRIPTION

=head1 Interchange Tag Reference

Interchange functions are accessed via the Interchange Tag Language
(ITL). The pages in a catalog may be mostly HTML, but they will use
ITL tags to provide access to Interchange's functions. ITL is a
superset of MML, or Minivend Markup Language. Minivend was the
predecessor to Interchange.

These tags perform various display and modification operations for the
user session. There nearly 100 standard predefined tags, and the
UserTag facility allows you to create tags that perform your own
functions and can be just as powerful as the built-in tags.

This document covers Interchange versions 4.7 through 4.9.

=head1 Tag Syntax

ITL tags are similar to HTML in syntax, in that they accept parameters
or attributes and that there are both I<standalone> and I<container>
tags.

We will call an attribute a I<parameter> if it may be called
positionally or if it must be included (see the I<parameter> and
I<attribute> sections below).

A standalone tag has no ending element, e.g.:

    [value name]

This tag will insert the user's name, providing they have given it to
you in a form. A container tag has both a beginning and an ending
element, as in:

    [if value name]
    You have a name. It is [value name].
    [/if]

=head2 Standard Syntax

The most common syntax is to enclose the tag with its parameters and
attributes in [square brackets]. If the tag has an end tag, the tag
and its end tag will delimit contained body text:

  [tagname parameters attributes]Contained Body Text[/tagname]

B<Caveat - macros: >Some macros look like tags or end tags. For
example, [/page] is a macro for </A>. This allows you to
conveniently write [page I<href>]Target[/page], but 'Target' is
not treated as contained body text.



When using the [tagname ...] syntax, there must be no whitespace
between the left bracket ('[') and the tagname.

If a tag name includes an underscore or dash, as in [I<item_list>], a
dash is just as appropriate (i.e. [item-list]). The two forms are
interchangeable, except that an ending tag must match the tag (i.e.,
don't use [item-list] list [/item_list]).

=head2 HTML-Comment

ITL also allows you to use '<!--[' and ']-->' as interchangeable
alternatives to plain square brackets: [tagname] and
C<<!--[tagname]--E<gt>> are equivalent.

This allows you make your raw tags appear as comments to HTML browsers
or editors. You might want to do this if your editor has trouble with
ITL tags when editing Interchange page templates, or alternatively, if
you want to use one .html file both as an Interchange template and as
a static page delivered directly by your web server, without
Interchange processing.

To properly HTML-comment contained body text, place your comment-style
brackets appropriately, for example:

 <!--[tagname] Contained Body Text [/tagname]-->

Note that you must include whitespace between the HTML comment
delimiters and the square brackets if you wish to actually comment out
tag output in the browser. For example, if [value name] expands to
'Bill':

 '<!--[value name]-->'  becomes  'Bill'
 '<!-- [value name] -->'  becomes  '<!-- Bill -->'

Technical notes

While '<!--[' and '[' are completely interchangeable, the Interchange
parser does not replace ']-->' with ']' unless it also sees '<!--[' at
least once somewhere on the page. (This is a small parsing speed
optimization.)

See the I<Template Parsing Order> appendix if you are modifying the
special administrative interface pages and intend to use this syntax.

=head2 I<Named vs. Positional Parameters>

There are two styles of supplying parameters to a tag: named and
positional.

In the named style you supply a parameter name=value pair just as most
HTML tags use:

    [value name="foo"]

The positional-style tag that accomplishes the same thing looks like
this:

    [value foo]

The parameter name is the first positional parameter for the
[I<value>] tag. Some people find positional usage simpler for
common tags, and Interchange interprets them somewhat faster. If you
wish to avoid ambiguity you can always use named calling.

In most cases, tag parameters specified in the positional fashion work
the same as named parameters. However, there are a few situations
where you need to use named parameters:

=over 4

=item 1.

If you want to specify a parameter that comes positionally after a
parameter that you want to omit, e.g. omit the first parameter but
specify the second. The parser would have no way of knowing which is
which, so you just specify the second by name. This is rare, though,
because the first positional parameters are usually required for a
given tag anyway.

=item 2.

When there is some ambiguity as to which parameter is which, usually
due to whitespace.

=item 3.

When you need to use the output of a tag as the parameter or attribute
for another tag.

=back

Interpolating parameters

If you wish to use the value of a tag within a parameter of another
tag, you cannot use a positional call. You must also double-quote the
argument containing the tag you wish to have expanded. For example,
this will not work:

    [page scan se=[scratch somevar]]

To get the output of the [scratch somevar] interpreted, you must
place it within a named and quoted attribute:

    [page href=scan arg="se=[scratch somevar]"]

Note that the argument to B<href> ('scan') did not need to be quoted;
only the argument to B<arg>, which contained a tag, needed the quotes.

=head2 I<Universal Attributes>

Universal attributes apply to all tags, though each tag specifies its
own default for the attribute. The code implementing universal
attributes is external to the core routines that implement specific
tags.

I<interpolate>

This attribute behaves differently depending upon whether the tag is a
I<container> or I<standalone> tag. A container tag is one which has an
end tag, i.e. [tag] stuff [/tag]. A standalone tag has no end tag,
as in [I<area> href=somepage]. (Note that [I<page> ...] and [I<order>
..] are B<not> container tags.)

I<For container tags (interpolated)>

=over 4

=item *

If true ("interpolate=1"), the Interchange server will first process
any tags within the body text before passing it to the enclosing tag.

=item *

If false ("interpolate=0"), the enclosing tag will receive the raw
body text.

=back

I<For standalone tags (reparsed)>

=over 4

=item *

If true, the server will process the I<output> of the tag. This is
identical to the behavior of the I<reparse> attribute (see below for
explanation and examples).

=back

(Note: The mixing of 'interpolate' and 'reparse' logic occurred
because 'interpolate' already worked this way when 'reparse' was added
to Interchange. This may be fixed in a later release...)

Most standalone tags are not reparsed by default (i.e., interpolate=0
by default). There are some exceptions, such as the [I<include>] tag.

Interpolation example:

Assuming that name is 'Kilroy',

   [log interpolate=1][value name] was here[/log]
   [log interpolate=0][value name] was here[/log]

the first line logs 'Kilroy was here' to I<catalog_root>/etc/log,
while the second logs '[value name] was here'.

Reparsing example:

Suppose we set a scratch variable called 'now' as follows:

   [set name=now interpolate=0][time]%A, %B %d, %Y[/time][/set]

If today is Monday, January 1, 2001,

   [scratch name=now interpolate=0]
   [scratch name=now interpolate=1]

the first line yields

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

while the second yields

   Monday, January 1, 2001

I<reparse>

If true ("reparse=1"), the server will process any tags in the text
output by the reparsed tag.

Reparse applies only to container tags (those with an end tag). The
interpolate attribute controls reparsing of the output of
standalone tags (see above).

Most container tags will have their output re-parsed for more
Interchange tags by default. If you wish to inhibit this behavior, you
must explicitly set the attribute B<reparse> to 0. Note that you will
almost always want the default action. The only container ITL tag that
doesn't have reparse set by default is [I<mvasp>].

Example:

Assuming that name is 'Kilroy',

  1.   [perl reparse=0]
          my $tagname = 'value';
          return "[$tagname name] was here\n"
       [/perl]

  2.   [perl reparse=1]
          my $tagname = 'value';
          return "[$tagname name] was here\n"
       [/perl]

expands to

  1.   [value name] was here

  2.   Kilroy was here

I<send>

Deprecated

=head2 Tag-specific Attributes

Each tag may accept additional named attributes which vary from tag to
tag. Please see the entry for the tag in question for details about
tag-specific attributes.

=head2 I<Attribute Arrays and Hashes>

Some tags allow you to pass an array or hash as the value of an
attribute. For an ordinary tag, the syntax is as follows:

    attribute.n=value

    attribute.hashkey=value

where I<n> is an integer array index. Note that you cannot use both an
array and a hash with the same attribute - if you use
B<attribute.I<n>>, you cannot also use B<attribute.key> for the same
attribute.

Here is an example of an attribute array:

    search.0="se=hammer
              fi=products
              sf=description"
    search.1="se=plutonium
              fi=products
              sf=comment"

The [page] tag, for example, treats a search specification array as
a joined search, automatically adding the other relevant search
fields, including the 'co=yes' to indicate a combined search (I<joined
searches> are described in the Interchange database documentation).

Note that it is up to the tag to handle an array or hash value
properly. See the documentation for the specific tag before passing it
an attribute array or hash value.

Perl calls

Before passing attributes to a tag, the Interchange parser would
convert the above example to an anonymous array reference. It would
use the resulting arrayref as the value for the 'search' attribute in
this example.

If you were passing the above example directly to a tag routine within
a [perl] block or a usertag, you must actually pass an anonymous
array as the value of the attribute as S<follows:>

    my $arrayref = [ "se=hammer/fi=products/sf=description",
                     "se=plutonium/fi=products/sf=description", ];

    $Tag->routine( { search => $arrayref, } );

Similarly to use a hash reference for the 'entry' attribute:

    my $hashref = { name   => "required",
                    date   => 'default="%B %d, %Y"', };

    $Tag->routine( { entry => $hashref } );

=head1 Looping tags and Sub-tags

I<>Certain tags are not standalone; these are the ones that are
interpreted as part of a surrounding looping tag like [I<loop>],
[I<item-list>], [I<query>], or [I<search-region>].

=over 4

=item

[I<PREFIX-accessories>]

[I<PREFIX-alternate>]

[I<PREFIX-calc>]

[I<PREFIX-change>]

[I<PREFIX-code>]

[I<PREFIX-data>]

[I<PREFIX-description>] (Note safe-data and ed() escape)

[I<PREFIX-discount>]

[I<PREFIX-discount-subtotal>]

[I<PREFIX-field>] (Optimization note-- one query per field if you use
this; we optimize around this if only one products table)

[I<PREFIX-increment>]

[I<PREFIX-last>]

[I<PREFIX-line>] (tab-delimited list of parameters returned)

[I<PREFIX-modifier>]

[I<PREFIX-next>]

[I<PREFIX-param>]

[I<PREFIX-pos>]

[I<PREFIX-price>]

[I<PREFIX-quantity>]

[I<PREFIX-subtotal>]

[I<if-PREFIX-data>]

[I<if-PREFIX-field>]

[if-PREFIX-param]

[if-PREFIX-pos]

[I<modifier-name>]

[I<quantity-name>]

=back

PREFIX represents the prefix that is used in that looping tag. They
are only interpreted within their container and only accept positional
parameters. The default prefixes:

 Tag                   Prefix                  Examples
 [loop]                loop                    [loop-code], [loop-field price], [loop-increment]
 [item-list]           item                    [item-code], [item-field price], [item-increment]
 [search-list]         item                    [item-code], [item-field price], [item-increment]
 [query]               sql                     [sql-code], [sql-field price], [sql-increment]

Sub-tag behavior is consistent among the looping tags. Subtags are
parsed during evaluation of the enclosing loop, I<before> any regular
tags within the loop.

There are two types of looping lists: ARRAY and HASH.

An array list is the normal output of a [query], a search, or a
[loop] tag. It returns from 1 to N return fields, defined in the
mv_return_fields or rf variable or implicitly by means of a SQL
field list. The two queries below are essentially identical:

    [query sql="select foo, bar from products"]
    [/query]

    [loop search="
                    ra=yes
                    fi=products
                    rf=foo,bar
    "]

Both will return an array of arrays consisting of the foo column
and the bar column. The Perl data structure would look like:

    [
        ['foo0', 'bar0'],
        ['foo1', 'bar1'],
        ['foo2', 'bar2'],
        ['fooN', 'barN'],
    ]

A hash list is the normal output of the [item-list] tag. It returns
the value of all return fields in an array of hashes. A normal
[item-list] return might look like:

    [
        {
            code     => '99-102',
            quantity => 1,
            size     => 'XL',
            color    => 'blue',
            mv_ib    => 'products',
        },
        {
            code     => '00-341',
            quantity => 2,
            size     => undef,
            color    => undef,
            mv_ib    => 'products',
        },

    ]

You can also return hash lists in queries:

    [query sql="select foo, bar from products" type=hashref]
    [/query]

Now the data structure will look like:

    [
        { foo => 'foo0', bar => 'bar0' },
        { foo => 'foo1', bar => 'bar1' },
        { foo => 'foo2', bar => 'bar2' },
        { foo => 'fooN', bar => 'barN' },
    ]

=head2 PREFIX-accessories

   [PREFIX-accessories arglist]

Except for the usual differences that apply to all subtags (such as
parsing order), these are more or less equivalent for an array-type
S<list:>

    [accessories code=current_item_code arg=arglist]
    [item-accessories arglist]

See the [accessories] tag for more detail. Note that you must use
the comma-delimited list to set attributes - you cannot set named
attributes with the usual 'attribute=value' syntax.

If the list is a hash list, i.e. an [item-list], then the value of
the current item hash is passed so that a value default can be
established.

=head2 PREFIX-alternate

   [PREFIX-alternate N] DIVISIBLE [else] NOT DIVISIBLE [/else][/PREFIX-alternate]

Set up an alternation sequence. If the item-increment is divisible by
`N', the text will be displayed. If an `[else]NOT DIVISIBLE
TEXT[/else]' is present, then the NOT DIVISIBLE TEXT will be
displayed.

For example:

    [item-alternate 2]EVEN[else]ODD[/else][/item-alternate]
    [item-alternate 3]BY 3[else]NOT by 3[/else][/item-alternate]

There are some additional primitives:

 Tag                               Description
 [item-alternate first_only]       Only true on first item
 [item-alternate last_only]        Only true on last item
 [item-alternate except_last]      True except on last item
 [item-alternate except_first]     True except on last item
 [item-alternate 0]                Same as "first_only"
 [item-alternate -1]               Same as "except_last"

In the common case where you want to separate by a comma or other
joiner:

        You have the following items:
        [item-list]
                [item-code][item-alternate except_last], [/item-alternate]
        [/item-list]

=head2 PREFIX-calc

   [PREFIX-calc] 2 + [item-field price] [/PREFIX-calc]

Executes Perl code in the tag body. This is equivalent to the
[calc] ... [/calc] tag pair, except it's calculated at loop time
instead of later when the rest of the page is parsed.

=head2 PREFIX-change

   [PREFIX-change][condition] ... [/condition] TEXT [/PREFIX-change]

Sets up a breaking sequence that occurs when the contents of
[condition] [/condition] change. The most common one is a category
break to nest or place headers.

The region is only output when a field or other repeating value
between [condition] and [/condition] changes its value. This allows
indented lists similar to database reports to be easily formatted. The
repeating value must be a tag interpolated in the search process, such
as [PREFIX-field] or [PREFIX-field database field]. If you
need access to ITL tags, you can use [PREFIX-calc] with a
$Tag-foo()> call.

Of course, this will only work as you expect when the search results
are properly sorted.

The value to be tested is contained within a
[condition]value[/condition] tag pair. The [PREFIX-change] tag
also processes an [else] [/else] pair for output when the value
does not change.

Here is a simple example for a search list that has a field
category and subcategory associated with each item:

 <TABLE>
 <TR><TH>Category</TH><TH>Subcategory</TH><TH>Product</TH></TR>
 [search-list]
 <TR>
    <TD>
         [item-change cat]

         [condition][item-field category][/condition]

                 [item-field category]
         [else]
                 &nbsp;
         [/else]
         [/item-change cat]
    </TD>
    <TD>
         [item-change sub]

         [condition][item-field subcategory][/condition]

                 [item-field subcategory]
         [else]
                 &nbsp;
         [/else]
         [/item-change sub]
    </TD>
    <TD> [item-field name] </TD>
 [/search-list]
 </TABLE>

The above should put out a table that only shows the category and
subcategory once, while showing the name for every product. (The
&nbsp; will prevent blanked table cells if you use a border.)

=head2 PREFIX-code

   [PREFIX-code]

The key or code of the current loop. In an [item-list] this is
always the product code; in a loop list it is the value of the current
argument; in a search it is whatever you have defined as the first
mv_return_field (rf).

=head2 PREFIX-data

   [PREFIX-data table field]

Calls the column field in database table table for the current
[PREFIX-code] This may or may not be equivalent to [PREFIX-field
field] depending upon whether your search table is defined as one of
the ProductFiles.

=head2 PREFIX-description

   [PREFIX-description]

The description of the current item, as defined in the catalog.cfg
directive DescriptionField. In the demo, it would be the value of
the field description in the table products.

If the list is a hash list, and the lookup of DescriptionField
fails, then the attribute description will be substituted. This is
useful to supply shopping cart descriptions for on-the-fly items.

=head2 PREFIX-discount

   [PREFIX-discount]

The price of the current item is calculated, and the difference
between that price and the list price (quantity one) price is output.
This may have different behavior than you expect if you set the
[discount] tag along with quantity pricing.

=head2 PREFIX-discount-subtotal

   [PREFIX-discount-subtotal]

Inserts the discounted subtotal of the ordered items.

=head2 PREFIX-field

   [PREFIX-field]

Looks up a field value for the current item in one of several places,
in this order:

    1. The first ProductFiles entry.
    2. Additional ProductFiles in the order they occur.
    3. The attribute value for the item in a hash list.
    4. Blank

A common user error is to do this:

    [loop search="
                    fi=foo
                    se=bar
                "]

    [loop-field foo_field]
    [/loop]

In this case, you are searching the table foo for a string of
bar. When it is found, you wish to display the value of
foo_field. Unless foo is in ProductFiles and the code is not
present in a previous product file, you will get a blank or some value
you don't want. What you really want is [loop-data foo field],
which specifically addresses the table foo. See also
[PREFIX-param] and [PREFIX-pos].

=head2 PREFIX-increment

   [PREFIX-increment]

The current count on the list, starting from either 1 in a
zero-anchored list like [loop] or [item-list], or from the match
count in a search list.

If you skip items with [PREFIX-last] or [PREFIX-next], the count
is NOT adjusted.

=head2 PREFIX-last

   [PREFIX-last] CONDITION [/PREFIX-last]

If CONDITION evaluates true (a non-whitespace value that is not
specifically zero) then this will be the last item displayed.

=head2 PREFIX-line

   [PREFIX-line start_column]

Returns all array values from the current looping row in a single
string, with each value separated by a tab, roughly equivalent to
this:

  [PREFIX-pos 0](tab)[PREFIX-pos 1](tab)[PREFIX-pos 2](tab)[...]

for however many fields were returned in that row.

This is useful as a quick way to see all your results at a glance and
verify your search specification.

If the optional start_column attribute is given, the output starts
with that column instead of column 0.

=head2 PREFIX-modifier

   [PREFIX-modifier attribute]

If the item is a hash list (i.e. [item-list]), this will return the
value of the attribute.

=head2 PREFIX-next

   [PREFIX-next] CONDITION [/PREFIX-next]

If CONDITION evaluates true (a non-whitespace value that is not
specifically zero) then this item is skipped.

=head2 PREFIX-param

   [PREFIX-param name]

Returns the value of the column name associated with the looping tag
row. Each looping list returns an array of return fields, set in
searches with mv_return_field or rf. The default is only to
return the code of the search result, but by setting those parameters
you can return whichever columns you wish.

In a [query] ITL tag you can select multiple return fields with
something like:

    [query prefix=prefix sql="select foo, bar from baz where foo='buz'"]
        [prefix-code]  [prefix-param foo]  [prefix-param bar]
    [/query]

In this case, [prefix-code] and [prefix-param foo] are synonyms, as
foo is the first returned parameter and becomes the code for this
row. Another synonym is [prefix-pos 0].

Mixed case field names in your SQL tables will be forced to lower case
in the [prefix-param name] tag if the underlying Database does that
(as with most SQL types).  For example if your query is

    [query prefix=prefix sql="select Foo, Bar from baz where Foo='buz'"]

then you must use:

    [prefix-param foo] and [prefix-param bar]

to display your results, rather than:

    [prefix-param Foo] and [prefix-param Bar]

Note that the following code is invalid:

    [query prefix=prefix sql=|
        SELECT  table1.foo,
                table2.bar
        FROM    table1, table2
        WHERE   table1.code = table2.code
        AND     table1.foo = 'buz'
    |]
        [prefix-param table1.foo] [prefix-param table2.bar]
    [/query]

The problem with the above code is that DBI doesn't support column
names such as table1.foo in its resultsets.  The following query
syntax is fully supported by DBI and therefore by Interchange:

    [query prefix=prefix sql=|
        SELECT  table1.foo AS foo,
                table2.bar AS bar
        FROM    table1, table2
        WHERE   table1.code = table2.code
        AND     table1.foo = 'buz'
    |]
        [prefix-param foo] [prefix-param bar]
    [/query]

=head2 PREFIX-pos

   [PREFIX-pos N]

Returns the value of the array parameter associated with the looping
tag row. Each looping list returns an array of return fields, set
in searches with mv_return_field or rf. The default is only to
return the code of the search result, but by setting those parameters
you can return whichever columns you wish.

[PREFIX-pos N] outputs the data from the I<N>th column as returned
(starting with zero). [PREFIX-param] lets you access the data by
column name instead of by number.

In a [query ...] ITL tag you can select multiple return fields with
something like:

    [query prefix=prefix sql="select foo, bar from baz where foo='buz'"]
        [prefix-code]  [prefix-param foo]  [prefix-param bar]
    [/query]

In this case, [prefix-code] and [prefix-param foo] are synonyms,
as foo is the first returned parameter and becomes the code for
this row. Another synonym is [prefix-pos 0].  [prefix-pos 1] is the
same as [prefix-param bar].  The following code will produce
exactly the same output as the above:

    [query prefix=prefix sql="select foo, bar from baz where foo='buz'"]
        [prefix-pos 0]  [prefix-pos 0]  [prefix-pos 1]
    [/query]

Note that if you use the [PREFIX-pos] tag, you may have to review your
column numbers whenever you modify the columns you select.  For this
reason, queries that make use of the [PREFIX-param] tag may be
easier to maintain and will be less prone to future surprises.

=head2 PREFIX-price

   [PREFIX-price]

The price of the product identified by the current code, formatted for
currency. If Interchange's pricing routines cannot determine the price
(i.e. it is not a valid product or on-the-fly item) then zero is
returned. If the list is a hash list, the price will be modified by
its quantity or other applicable attributes (like size in the
demo).

=head2 PREFIX-quantity

   [PREFIX-quantity]

The value of the quantity attribute in a hash list. Most commonly
used to display the quantity of an item in a shopping cart
[item-list].

=head2 PREFIX-subtotal

   [PREFIX-subtotal]

The [PREFIX-quantity] times the [PREFIX-price]. This does take
discounts into account.

=head2 if-PREFIX-data

   [if-PREFIX-data table field] IF text [else] ELSE text [/else] [/if-PREFIX-data]

Examines the data field, i.e. [PREFIX-data table field], and if it is
non-blank and non-zero then the IF text will be returned. If it is
false, i.e. blank or zero, the ELSE text will be returned to the
page.

This is much more efficient than the otherwise equivalent [if
type=data term=table::field::[PREFIX-code]].

You cannot place a condition; i.e. [if-PREFIX-data table field eq
'something']. Use [if type=data ...] for that.

Careful, a space is not a false value!

=head2 if-PREFIX-field

   [if-PREFIX-field field] IF text [else] ELSE text [/else] [/if-PREFIX-field]

Same as [if-PREFIX-data ...] except uses the same data rules as
[PREFIX-field].

=head2 PREFIX-modifier-name

   [PREFIX-modifier-name attribute]

Outputs a variable name which will set an appropriate variable name
for setting the attribute in a form (usually a shopping cart). Outputs
for successive items in the list:

    1. attribute0
    2. attribute1
    3. attribute2

etc.

[PREFIX-modifier-name quantity] would be the same as
[PREFIX-quantity-name].

=head2 PREFIX-quantity-name

   [item-quantity-name]

Outputs for successive items in the list:

    1. quantity0
    2. quantity1
    3. quantity2

etc.

[PREFIX-modifier-name quantity] would be the same as
[PREFIX-quantity-name].

=head1 Tags

Each ITL tag is show below. Calling information is defined for the
main tag, sub-tags are described in I<Looping tags and Sub-tags>.

=head2 accessories

A Swiss-army-knife widget builder, this provides access to
Interchange's product option attributes (e.g., to choose or access
product options such as a shirt's size or color).

Can build selection objects (radio, check, select boxes, etc), forms
or hyperlinks, or can simply return a value.

Or more - see also I<Looping tags and Sub-tags>.

Summary

    [accessories code arg]
    [accessories code=os28044 arg="size, radio, ... " other_named_attributes] deprecated
    [accessories code=os28044 attribute=size type=radio ... other_named_attributes]

 Parameters   Description                               Default
 code         Value of the master key in the product (or specified other) tablenone
 arg          Positionally interpreted comma-delimited list of values for the following attributes:"attribute, type, column, table, name, outboard, passed"none

 Attributes                        Default
 attribute                         none
 typeOne of select, value, text, textarea, hidden, password, combo, move_combo, reverse_combo, show, options, labels, checkbox, radio, linksselect
 column                            attribute
 table                             products
 name                              mv_order_attribute
 outboard                          none
 passed                            none
 key (alias for code)              none
 row (alias for code)              none
 base (alias for table)            products
 database (alias for table)        products
 db (alias for table)              products
 col (alias for column             attribute
 field (alias for column           attribute
 delimiter                         comma (',')
 prepend                           none
 append                            none
 extra                             none
 js                                none
 rows                              varies with type; often 4
 cols                              varies with type; often 40
 width                             none
 default                           none
 price                             none
 price_data                        none
 contains (type=radio or check)    none
 joiner (type=links)               none
 href (type=links)                 none
 template (type=links)             none
 form (type=links)                 mv_action=return
 empty (type=links)                none
 secure (type=links)               none
 new                               none
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 No
 Container tag                     No
 Has Subtags                       No

B<Tag expansion example:>

    [accessories os28044 size]
---
    <SELECT NAME="mv_order_size"><OPTION VALUE="10oz">10oz\
    <OPTION VALUE="15oz">15oz<OPTION VALUE="20oz">20oz</SELECT>

B<ASP-like Perl call:>

    $Tag->accessories(  { code   => '[[EXAMPLE_SKU]]',
                          arg    => 'color, radio'
                          table  => 'special_products', }  );

or similarly with positional parameters,

    $Tag->accessories($code, $arg, $attribute_hash_reference);

See Also

I<Looping tags and Sub-tags>.

Description

This is the swiss-army-knife widget builder for providing access to
Interchange's product option attributes (e.g., to choose or access
product options such as a shirt's size or color).

Interchange allows you to choose item attribute values for each
ordered item - you can attach a size, color, or other modifier to a
line item in the shopping cart. You can also resubmit previous
attribute values via hidden fields on a form.

The catalog.cfg file directive I<UseModifier> is used to set the
name of the modifier or modifiers. For example

    UseModifier        size color

will attach both a size and color attribute to each item code that is
ordered.

B<Important Note -- >You may not use the following names for
attributes:

item  group  quantity  code  mv_ib  mv_mi  mv_si



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

The modifier value is accessed in the [item-list] loop with the
[item-param attribute] tag, and form input fields are placed
with the [modifier-name attribute] tag. This is similar to the
way that quantity is handled.

B<Note: >You must be sure that no fields in your forms have digits
appended to their names if the variable is the same name as the
attribute name you select, as the [PREFIX-modifier-name size]
variables will be placed in the user session as the form variables
size0, size1, size2, etc.



Interchange will automatically generate the select boxes when the
[accessories code="os28044" attribute="size"] or
[item-accessories size] tags are called. They have the syntax:

    [item-accessories attribute, type, column, table, name, outboard, passed]

    [accessories code=sku
                attribute=modifier
                type=select
                column=db_table_column_name
                table=db_table
                name=varname
                outboard=key
                passed="value=label, value2*, value3=label 3"]

    [accessories js=| onChange="set_description(simple_options, variant)"; |
                type=select
                name="[item-param o_group]"
                passed="=--choose--,[item-param o_value]"]

B<Notes: >

=over 4

=item 1.

The 'attribute' attribute is required.

=item 2.

See the type attribute for a list of types.

=item 3.

The trailing '*' in value2 will mark it as the default ('SELECTED')
value in the select widget (see below).

=back



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

   name_a=Label Text1, default_name=Default Label Text*, name_b, etc.

The label text is optional - if none is given, the B<name> will be
used (as in 'name_b' above).

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:

    [item-accessories 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
session variables, you can use this to allow a customer to enter an
item attribute during an order.

If used in an item list, and the user has changed the value, the
generated select box will automatically retain the current value the
user has selected.

The value can then be displayed with [item-modifier color] on the
order report, order receipt, or any other page containing an
[item-list].

Emulating with a loop

You can also build widgets directly, without using the accessories
tag. You may have to do so if you need more control of the content
than the tag offers. Below is a fragment from a shopping basket
display form which shows a selectable size with "sticky" setting and a
price that changes based upon the modifier setting. (Note that this
example would normally be contained within the
[item-list][/item-list] pair.)

    <SELECT NAME="[loop-modifier-name size]">
    [loop option="[loop-modifier-name size]" list="S, M, L, XL"]
    <OPTION> [loop-code] -- [price code="[item-code]" size="[loop-code]"]
    [/loop]
    </SELECT>

The output of the above would be similar to the output of
[item-accessories size, select] if the product database field size
contained the value S, M, L, XL. The difference is that the options
in the loop emulation show the adjusted price in addition to the size
within each option value.

I<Hash Lists> - Technical Note

As a technical note, some of the features of this tag work differently
depending upon whether it was called with an '$item' hash reference,
for example, as [item-accessories] within an [item-list].

In this context, the tag will have access to ancillary data from the
item (including, perhaps, a user's chosen item attribute value). For
example, if building a TEXTAREA widget within an [item-list], the
widget will show the chosen item attribute value. On the other hand,
within an array list such as a [search-list] in a
[search-region], the widget would be empty.

If you really know what you're doing, you can pass it the item hash
reference within a [perl] tag like this:

   $Tag->accessories( $code,
                      undef,              # 'arg' parameter value
                      $named_attribute_hashref,
                      $item_hashref );

See also Looping tags and Sub-tags for information about
hash-context and array-context in looping tags.

I<code>

This is the master key of the specified table (commonly sku in a
product table). If no table is specified, the tag uses the products
table by default.

You should not specify a code when looping on [item_accessories]
because it internally sets 'code' to the key for the current item
in the loop.

I<arg>

B<Deprecated after Interchange 4.6>

This allows you to pass values for some of the more commonly used
attributes in the manner of the [item-accessories] tag, as a
comma-delimited positional S<list:>

  arg="attribute, type, column, table, name, outboard, passed"

Whitespace within the list is optional.

If you leave out one or more of the above attributes, be sure to keep
the comma(s) if you are setting anything after it in the S<list:>

  arg="attribute, type, , table"

The above examples show the attribute names for clarity; you would
actually use the values. Hence, the previous example might actually be
something like the S<following:>

  arg="color, radio, , products"

Although you must use such a comma-delimited list to pass attributes
to the [item-accessories] tag, please use named attributes instead
for the [accessories] tag. The 'arg' attribute is deprecated.

For detail about a specific attribute, please see its subheading
below.

I<attribute>

Despite the name, this has nothing to do with tag attributes. You can
set attributes for I<items> in a database table (typically the
products table) with the UseModifier configuration directive.
Typical are size or color.

This selects the item attribute the tag will work with.

I<type>

This determines the action to be taken. One of:

 Action                            Description
 select                            Builds a dropdown <SELECT> menu for the item attribute, with the default item attribute value SELECTED. The accessories tag builds a select widget by default if type is not set.
 display                           Shows the label text for *only the selected option* if called in Hash List context (e.g., within an [item-list]). Ignored otherwise (i.e., the tag will build the default <SELECT> menu).
 show                              Returns the list of possible attributes for the item (without labels or any HTML widget). For example, if sku os28044 is available in several sizes:[accessories os28044 size,show]-----------------------------------------Sm=10oz, Med=15oz*, Lg=20oz
 options                           This shows the attribute options as a newline delimited list:[accessories os28044 size,options]-----------------------------------------SmMedLg
 labels                            This shows the attribute option labels:[accessories os28044 size,options]-----------------------------------------10oz15oz*20oz
 radio                             Builds a radio box group for the item, with spaces separating the elements.
 radio nbsp                        Builds a radio box group for the item, with &nbsp; separating the elements.
 radio break                       Builds a radio box group for the item, with '<br>' separating the radio button/label pairs from one another.
 radio left n                      Builds a radio box group for the item, inside a table, with the checkbox on the left side. If "n" is present and is a digit from 2 to 9, it will align the options in that many columns.You can also set FONT SIZE like this:  type="radio left n fontsizem"where -9 <= m <= 9
 radio right n                     Builds a radio box group for the item, inside a table, with the checkbox on the right side. If "n" is present and is a digit from 2 to 9, it will align the options in that many columns.You can also set FONT SIZE like this:  type="radio right n fontsizem"where -9 <= m <= 9
 check                             Builds a checkbox group for the item, with spaces separating the elements.
 check nbsp                        Builds a checkbox group for the item, with '&nbsp;' separating the checkbox/label pairs from one another.
 check break                       Builds a checkbox group for the item, with '<br>' separating the checkbox/label pairs from one another.
 check left n                      Builds a checkbox group for the item, inside a table, with the checkbox on the left side. If "n" is present and is a digit from 2 to 9, it will align the options in that many columns.You can also set FONT SIZE like this:  type="check left n fontsizem"where -9 <= m <= 9
 check right n                     Builds a checkbox group for the item, inside a table, with the checkbox on the right side. If "n" is present and is a digit from 2 to 9, it will align the options in that many columns.You can also set FONT SIZE like this:  type="check right n fontsizem"where -9 <= m <= 9
 textarea_XX_YY                    A textarea with XX columns and YY rows. The textarea will contain the selected item attribute value if used in Hash List context (e.g., within an [item-list]).If you simply use 'type=textarea', the size will default to 4 rows by 40 columns, unless you have set the rows or cols tag attributes.
 text_YY                           A text box with YY width in characters. The HTML tag's VALUE will be set to the selected item attribute value if used in Hash List context (e.g., within an [item-list]).If you simply use 'type=text', the width will default to 60, unless you have set the cols tag attribute.
 combo                             Special type, used with nullselect filter, for selecting from a list or inputting a new value
 reverse_combo                     Special type, used with last_non_null filter, for selecting from a list or inputting a new value - differs from combo in order of presentation
 move_combo                        Special type, used with null_to_space or null_to_comma filter, for selecting multiple non-ordered values from a list or inputting into a textarea
 links                             Produces a series of links based on the option values. The base form value is passed via the form parameter, just like in an [area ...] or [page ...] tag, and the value is named with the passed NAME attribute.
 value                             Returns the selected value if called in Hash List context (e.g., within an [item-list]), or nothing otherwise.
 hidden                            Creates a hidden form field. The hidden field's VALUE will be set to the selected item attribute value if used in Hash List context (e.g., within an [item-list]).
 password_YY                       A password box with YY width in characters. The HTML tag's VALUE will be set to the selected item attribute value if used in Hash List context (e.g., within an [item-list]).If you simply use 'type=password', the width will default to 12, unless you have set the cols tag attribute.

The default is 'select', which builds an HTML select form entry for
the attribute.

Some types build widgets that use the ROWS=I<m>, COLS=I<n>, or certain
other HTML attributes. For these, you can define widget rows and
columns within the string that sets the type; for example,
type="textarea_6_33_wrap=virtual" specifies a TEXTAREA widget with
ROWS=6, COLS=33, and WRAP=virtual. You should resort to this only when
you cannot use the named parameters, for example within an
[item-accessories] tag. Otherwise, use the rows=I<m> and
cols=I<n> tag attributes instead.

The result of setting conflicting values in the type string and the
rows or cols attributes is undefined.

The following list shows syntax for type strings, where I<rows> is the
number of rows and I<cols> is the number of columns.

=over 4

=item *

B<text>

=over 8

=item *

textarea   I<(default is 4 rows, 40 columns, like 'textarea_4_40')>

=item *

textarea_I<rows>_I<cols>

=item *

text_I<cols>

=item *

textarea rows=I<rows> cols=I<cols> wrap=I<WRAP value>

=back

=item *

B<password>

=over 8

=item *

password   I<(default is 12 columns, like 'password_12')>

=item *

password_I<cols>

=back

=item *

B<combo> (similarly for B<reverse_combo> and B<move_combo>)

=over 8

=item *

combo   I<(default is 1 row, 16 columns, like 'combo_1_16')>

=back

=back

In any of the option building types, you can append the string
ranges and a special option processing will be done -- any option
matching the pattern [A-Za-z0-0]..[A-Za-z0-0] will be expanded into a
comma separated range between the bounds. The same behavior is
accomplished by passing the accessories tag option ranges. For
example:


    [accessories name=foo type=select ranges=1 "A..C,1..5,10,20"]
      and
    [accessories name=foo type="select ranges" passed="A..C,1..5,10,20"]

      will both output:

    <select NAME="foo">
    <option VALUE="A">A
    <option VALUE="B">B
    <option VALUE="C">C
    <option VALUE="1">1
    <option VALUE="2">2
    <option VALUE="3">3
    <option VALUE="4">4
    <option VALUE="5">5
    <option VALUE="10">10
    <option VALUE="15">15
    <option VALUE="20">20
    </select>

The above applies to any of the option building types -- check,
combo, combo_move, labels, multiple, options, radio,
reverse_combo, and select. It will refuse to produce more than
5000 options -- that limit can be changed with Limit option_list N
in catalog.cfg, where N is an integer greater than 0.

I<column>

The column of the table corresponding to the attribute will
traditionally have the same name as the attribute, though it need not.

This specifies the table column that contains an item's attribute
values. The tag will find item attribute names and values in a
comma-delimited list of name=value pairs stored in this field of an
item's table entry. If unspecified, the column name will default to
the name given for the 'attribute' attribute.

For example, if an item in the products table has a 'size'
attribute, and each item's comma-delimited list of available sizes is
stored in the 'how_big' column, then you would need to specify
"column=how_big" because the tag's default column choice (size)
would be missing or used for some other purpose.

I<table>

This is the database table containing the item's attribute values. It
defaults to the first products file where the item code is found.

If you have configured your database so that the attributes are kept
in a different table from other item data, 'code' should be set to
the master key in this table. See 'outboard') if you are using
[item-accessories] and cannot specify code=key.

I<name>

This sets the name of the form variable to use if appropriate for the
widget 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>.

If the variable is set in the user session, the widget will "remember"
its previous setting. In other words, [value I<name>] will contain
the previous setting, which the widget will use as its default
setting. See also the default attribute.

I<outboard>

If calling the item-accessories tag, and you wish to select from an
outboard database table whose master key is different from the item
code, you can pass the key the tag should use to find the accessory
data.

I<passed>

You can use this to pass your own values to the widget the tag will
build. If you have set passed to a list of widget options, then the
tag will simply build a widget of the specified I<type> with your
values instead of fetching an attribute value list from the database.

For example, to generate a select box with a blank option (perhaps
forcing a select), the value of blue with a label of B<Blue>, and
the value of green with a label of B<Sea Green>, do:

    [accessories type=select
                 name=color
               passed="=--select--*, blue=Blue, green=Sea Green"]

This will generate:

    <SELECT NAME="color"><OPTION VALUE="" SELECTED>--select--\
    <OPTION VALUE="blue">Blue\
    <OPTION VALUE="green">Sea Green</SELECT>

Note: trailing backslashes ('\') in the above example indicate line
continuation and are not part of the tag output.

I<delimiter>

The list of attribute values will be a delimited string. This allows
you to specify an alternative delimiter if the list is not
comma-delimited (the default).

I<prepend>

You can set a string to prepend to the returned output of the tag.
Note that this is I<not> a list to prepend to the fetched attribute
value list, which is treated within the tag.

For example,

    [accessories code=os28044
                 type=select
            attribute=size
               append="Append Me<br>"
              prepend="Prepend Me"]
---
    Prepend Me<SELECT NAME="mv_order_size">\
    <OPTION VALUE="10oz">10oz\
    <OPTION VALUE="15oz">15oz\
    <OPTION VALUE="20oz">20oz</SELECT>Append Me<br>

I<append>

You can set a string to append to the returned output of the tag. Note
that this is I<not> a list to append to the fetched attribute value
list, which is treated within the tag.

I<extra>

Setting the 'extra' attribute appends its value as the last
attribute of the HTML output tag. The following example illustrates
the append, extra and js S<options:>

    [accessories code=os28044
                 type=select
            attribute=size
               append="Append Me<br>"
                extra="Last=Extra"
                   js="javascript_here"]
---
    <SELECT NAME="mv_order_size" javascript_here Last=Extra>\
    <OPTION VALUE="10oz">10oz\
    <OPTION VALUE="15oz">15oz\
    <OPTION VALUE="20oz">20oz</SELECT>Append Me<br>

I<js>

This allows you to place javascript within the start tag of the HTML
output. See the example given above for extra.

js has no default, except when 'type=move_combo', where the
default S<is:>

  onChange="addItem(this.form.Xname,this.form.name)"

I<rows>

The tag will pass the number you choose through to the HTML
'ROWS=I<n>' attribute in HTML widgets that accept it.

For some types, you can also define widget rows and columns within the
string that sets the type; for example,
type="textarea_6_33_wrap=virtual" specifies a TEXTAREA widget with
ROWS=6, COLS=33, and WRAP=virtual. You should resort to this only when
you cannot use the named parameters, for example within an
[item-accessories] tag.

The result of setting conflicting values in the type string and the
rows=I<n> attribute is undefined.

I<cols>

The tag will pass the number you choose through to the HTML
'COLS=I<n>' attribute in HTML widgets that accept it.

See also 'rows' above.

I<width>

This is a quasi-alias for 'cols' that only works with the 'text'
and '<password>' types. Use 'cols' instead.

I<default>

Sets the default attribute option in the widget returned by the tag.
This will override a default indicated with a trailing '*' in the
database or 'passed' string. This will also override the default of
a user's previous selection when the tag would otherwise have
preserved it.

For example the following selects blue by default rather than green as
it would otherwise have done,

    [accessories type=select
                 name=color
               passed="blue=blue, green=Sea Green*"
              default="blue"]
---
    <SELECT NAME="color"><OPTION VALUE="blue" SELECTED>blue\
    <OPTION VALUE="green">Sea Green</SELECT>
---

Obscure technical note: the tag ignores the 'default' attribute if
it has an item hash reference - see Hash Lists above.

I<price>

When combined with the price_data tag attribute, this allows you to
force prices for item attributes. You probably do not want to use
this; just let the tag pick up prices from your database table(s) when
appropriate.

If you are passing attribute values, you can use this to control the
displayed price in the widget.

    [accessories type=check
                 name=color
                price=1
           price_data="blue=20, green=50"
               passed="blue=Blue, green=Sea Green*"]
---
    <INPUT TYPE="checkbox" NAME="color"
               VALUE="blue" >&nbsp;Blue&nbsp;($20.00)
    <INPUT TYPE="checkbox" NAME="color"
                   VALUE="green" CHECKED>&nbsp;Sea Green&nbsp;($50.00)

I<price_data>

I<contains>

Requires 'type=radio' or 'type=check'.

Used to determine whether a substring match of the value will cause a
radio box or check box to be selected. If true, the match will happen
whether the value is on a word boundary or not -- if false, the value
must be on a word boundary. (When we speak of a word boundary, it is
in the Perl sense -- a word character [A-Za-z0-9_] followed or
preceded by a non-word character, or beginning or end of the string.)

I<joiner>

Requires 'I<type>=links'.

With type=links, the accessories tag returns a link for each
option. This allows you to override the default string ('<BR>') that
joins these links. You can use Perl's metacharacter escapes, such as
'\n' for newline or '\t' for tab.

I<href>

Requires 'I<type>=links'.

This sets the base HREF for the link in a links type. Default is
the current page.

I<template>

Requires 'I<type>=links'.

Allows you to override the standard Interchange template for a
hyperlink. You probably don't need to use this - grep the code to grok
it if you do (see 'sub build_accessory_links').

I<form>

Requires 'I<type>=links'.

This sets the base value for the form in a links type. Default is
mv_action=return, which will simply set the variable value in the
link.

For example, to generate a series of links - one per item attribute
value passed - that set the variable "color" to the corresponding
passed value (blank, blue, or green), do S<this:>

    [accessories type=links
                 name=color
               passed="=--select--, blue=Blue, green=Sea Green"]

This will generate something like the following:

    <A HREF="VENDURL/MV_PAGE?mv_action=return&color=blue">Blue</A><BR>
    <A HREF="VENDURL/MV_PAGE?mv_action=return&color=green">Sea Green</A>

where VENDURL is your Interchange URL for the catalog MV_PAGE is the
current page.

If you want the empty "--select--" option to show up, pass an empty=1
parameter.

I<empty>

Requires 'I<type>=links'.

Setting 'empty=1' includes a hyperlink for the empty "--select--"
option. See the example in form above; if empty=1 had been
specified, three links would have been generated.

I<secure>

Requires 'I<type>=links'.

Setting secure=1 causes the generated link(s) to point to your
secure Interchange URL.

I<new>

Requires 'I<type>=combo' or 'reverse_combo'.

You can use this to set a value in place of the 'New' or 'Current'
option in a combo box. For example, if item 'os28044' has size
attribute values of "Sm=10oz, Med=15oz, Lg=20oz"S<:>

    [accessories code=os28044 attribute=size type=combo new="my_new_value"]
---
    <INPUT TYPE=text NAME="mv_order_size" SIZE=16 VALUE="">
    <SELECT NAME="mv_order_size" SIZE="1">
    <OPTION VALUE="my_new_value">my_new_value
    <OPTION VALUE="Sm">10oz
    <OPTION VALUE="Med">15oz
    <OPTION VALUE="Lg">20oz</SELECT>

Or, with the default new value:

    [accessories code=os28044 attribute=size type=combo]
---
    <INPUT TYPE=text NAME="mv_order_size" SIZE=16 VALUE="">
    <SELECT NAME="mv_order_size" SIZE="1">
    <OPTION VALUE="">&lt;-- New
    <OPTION VALUE="Sm">10oz
    <OPTION VALUE="Med">15oz
    <OPTION VALUE="Lg">20oz</SELECT>

Default is no VALUE with option text set to '&lt;-- New' for a combo
box or 'Current --&gt;' for a reverse_combo box.

=head2 and

Summary

Parameters: B<type term op compare>

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

B<Note: >This tag has special positional parameter handling.

    [and type term op compare]

 Parameters   Description                               Default
 base         Alias for type                            DEFAULT_VALUE
 comp         Alias for compare                         DEFAULT_VALUE
 compare                                                DEFAULT_VALUE
 op                                                     DEFAULT_VALUE
 operator     Alias for op                              DEFAULT_VALUE
 term                                                   DEFAULT_VALUE
 type                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [value name=fname set="Mike" hide=1]
    [value name=lname set="" hide=1]

    ...

    [if value fname]
    [and value lname]
        Both first and last name are present.
    [else]
        Missing one of "fname" and "lname" from $Values.
    [/else]
    [/if]
---
    Missing one of "fname" and "lname" from $Values.

B<ASP-like Perl call:>

Not applicable. The [and ...] tag only is used with [if ...],
and Perl logic obviates the [if ...] tag.

Description

The [and ...] tag is only used in conjunction with [if ...]. 
Example:

        [if value fname]
        [and value lname]
        Both first and last name are present.
        [else]
        Missing one of "fname" and "lname" from $Values.
        [/else]
        [/if]

See the description of the [if] tag.

I<compare>

I<op>

I<term>

I<type>

=head2 area

Alias:  B<href>

Expands to the URL for an Interchange page or action, including the
Interchange session ID and supplied arguments. This is very similar to
the I<page> tag - these are equivalent:

    [page href=dir/page arg=mv_arg]TargetName</A>
    <A HREF="[area href=dir/page arg=mv_arg]">TargetName</A>

Summary

    [area href arg]
    [area href=dir/page arg=page_arguments other_named_attributes]

 Parameters   Description                               Default
 href         Path to Interchange page or actionSpecial arguments'scan' links to a search (using search arguments in arg)'http://...' external link (requires form attribute)process
 arg          Interchange arguments to page or action   none

 Attributes                        Default
 form                              none
 search                            No
 secure                            No
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 No
 Macro                             No
 Has end tag                       No

B<Tag expansion example:>

    [area href=dir/page.html arg="arg1=AA/arg2=BB"]

    www.here.com/cgi-bin/mycatalog/page.html?mv_session_id=6CZ2whqo&\
    mv_pc=1&mv_arg=arg1%3dAA/arg2%3dBB

B<ASP-like Perl call:>

    $Tag->area(  { href => "dir/page",
                   arg  => "arguments", }  );

or similarly with positional parameters,

    $Tag->area($href, $arg, $attribute_hash_reference);

See Also

I<page>

Description

The area tag is very similar to the [page] tag. It produces the
URL to call an Interchange page, but it differs from page in that
it does not supply the surrounding <A HREF ...> notation. This can be
used to get control of your HREF items, perhaps to place an ALT string
or a Javascript construct.

It was originally named area because it also can be used in a
client-side image map.

The area tag has an alias of href. The two links below are
identical in operation:

   <A HREF="[area href=catalog]" ALT="Main catalog page">Catalog Home</A>
   <A HREF="[href href=catalog]" ALT="Main catalog page">Catalog Home</A>

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

I<form>

The optional form argument allows you to encode a form in the link.

   <A HREF="[area form="mv_order_item=os28044
                        mv_order_size=15oz
                        mv_order_quantity=1
                        mv_separate_items=1
                        mv_todo=refresh"]"> Order 15oz Framing Hammer</A>

See the description of the [page] tag for more detail.

I<search>

Interchange allows you to pass a search in a URL. There are two ways
to do this:

=over 4

=item 1.

Place the search specification in the named search attribute.

=over 8

=item *

Interchange will ignore the href parameter (the link will be set to
'scan'.

=item *

If you give the arg parameter a value, that value will be available
as [value mv_arg] within the search display page.

=back

=item 2.

Set the href parameter to 'scan' and set arg to the search
specification.

=over 8

=item *

Note that you can use this form positionally - the values go into
href and arg, so you do not have to name parameters.

=back

=back

These are identical:

   <A HREF="[area scan
                  se=Impressionists
                  sf=category]">Impressionist Paintings</A>

   <A HREF="[area href=scan
                   arg="se=Impressionists
                        sf=category"]">Impressionist Paintings</A>

   <A HREF="[area search="se=Impressionists
                          sf=category"]">Impressionist Paintings</A>


See the description of the I<page> tag for more detail.

I<secure>

Examples

B<Tag expansion example:>

    [area href=dir/page.html arg="arg1=AA/arg2=BB"]

    www.here.com/cgi-bin/mycatalog/page.html?mv_session_id=6CZ2whqo&\
    mv_pc=1&mv_arg=arg1%3dAA/arg2%3dBB

Positional call example:

    <A HREF="[area ord/basket]">Check basket</A>

Named call example:

    <A HREF="[area ord/basket]">Check basket</A>

=head2 assign

Allows you to assign numeric values to preempt calculation of one or
more of the following S<tags:>

[handling], [salestax], [shipping], and [subtotal]

The assignment is persistent within a user's session until you clear
it, an assigned tag will return your value instead of calculating a
value.

Warning - please be sure you understand the dependencies within the
pricing system before using the assign tag. In particular, you must
have the value mv_shipmode set to assign to shipping, and
likewise you must set mv_handling to assign to handling. The
salestax and subtotal settings don't require any session
variables be set.

Summary

    [assign tag_name=value tag_name=value ...]
    [assign clear=1]

 Attributes   Description                               Default
 clear        Clears all pending 'assign' tag assignmentsnone
 handling     Assigns an override value for [handling] tagsnone
 salestax     Assigns an override value for [salestax] tagsnone
 shipping     Assigns an override value for [shipping] tagsnone
 subtotal     Assigns an override value for [subtotal] tagsnone

 Other_Characteristics             
 Invalidates cache                 No
 Container tag                     No

B<ASP-like Perl call:>

    $Tag->assign(  { shipping => 2.99, }  );

See Also

[handling], [salestax], [shipping], [subtotal],
[Shipping]

Description

The assign tag allows you to assign numeric override values to one
or more of the following S<tags:>

[handling], [salestax], [shipping], and [subtotal]

An assigned tag will return your value rather than calculating its own
until you clear the assignment.

Assignment is persistent within the user's session (unless cleared)
and affects only that user.

Assigning an empty string clears the tag's assignment. You can also
clear all pending assignments at once with the clear attribute.

For example, the following eliminates salestax and sets shipping to
$4.99 regardless of weight and S<destination:>

    [assign salestax=0 shipping=4.99]

This restores the [salestax] tag and eliminates handling
S<charges:>

    [assign salestax="" handling=0]

This restores the normal behavior to the [shipping] and
[handling] S<tags:>

    [assign clear=1]

Assignment affects only the value returned by a tag. Other behavior,
such as formatting for the local currency, is not affected by the
assignment.

Note - you will get an error in the error log (and any pending
assignment for the specified tag will be cleared) if you try to assign
a value other than a number or the empty string ("").

I<clear>

Setting this to a true value clears all pending assignments (i.e., all
assignable tags return to normal behavior).

I<shipping>

This sets the total value of shipping, rounded to locale-specific
fractional digits. Always active if assigned a numeric value. See the
[shipping] tag for detail about rounding, etc.

I<handling>

This option sets the total value of handling, rounded to fractional
digits.

B<Important note>

The [handling] tag is unlike the others in that it will be inactive
(despite your assignment) unless the [value B<mv_handling>]
variable is true (i.e., a nonzero, non-blank value).



I<salestax>

This preempts the salestax calculation. The assigned value is not
rounded.

I<subtotal>

This preempts the cart subtotal derived from prices. The assigned
value is not rounded.

Note that you cannot assign to [total-cost] - it will always be the
sum of the four above.

Before using the assign tag, please be sure you understand the
dependencies within the pricing system, such as the relationship
between [total-cost] and assigned tags.

=head2 attr-list

This tag is intended for use within embedded perl rather than as a
standalone tag within a template (i.e., the [attr-list ...] syntax
does not apply).

The $Tag-E<gt>attr_list($template, $hashref) usage provides a
shorthand for accessing values of a hash within embedded perl. It also
allows you to control defaults or set up conditional values.

Summary

    $Tag->attr_list($template, $hashref)

 Parameters   Description                               Default
 hash                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     NA (Though the template is technically body text)
 Has Subtags                       No
 Nests                             No

B<Tag expansion example> (ASP-like Perl call):

    [perl tables=products]
        my %opt = ( hashref => 1,
                 sql     => 'select * from  products', );

        my $ary_of_hash = $Db{products}->query(\%opt);

        my $template = <<EOF;
            {sku} - {description} - {price|Call for price}
            {image?}<IMG SRC="{image}">{/image?}
            {image:}No image available{/image:}
            <br>
            More body Text here
            <br>
EOF

        foreach my $ref (@$ary_of_hash) {
            $out .= $Tag->attr_list($template, $ref);
        }
        return $out;
     [/perl]
---
     os28113 - The Claw Hand Rake - Call for price
     <IMG SRC="/mycatalog/images/os28113.gif">

     <br>
     More body Text here
     <br>
     os28006 - Painters Brush Set - 29.99
     No image available

     <br>
     More body Text here
     <br>
     ...

Description

Tags an attribute list with values from a hash. Designed for use in
embedded Perl.

Tags according to the following rules:

{key}

Inserts the value of the key for the reference. In a database query,
this is the column name.

{key|fallback string}

Displays the value of {key} or if it is zero or blank, the fallback
string (i.e., default).

{key true string}

Displays true string if the value of {key} is non-blank, non-zero,
or displays nothing if the key is false.

{key?} true text {/key?}

Displays true text if the value of {key} is non-blank, non-zero,
and nothing otherwise.

{key:} false text {/key:}

Displays false text if the value of {key} is blank or zero, and
nothing otherwise.

I<hash>

This is the hash reference whose keys will be expanded within the
template (see above).

=head2 banner

Implements random or rotating banner ads. See also I<Banner/Ad
rotation>.

Summary

    [banner category]
    [banner category=my_category other_named_attributes]

 Parameters   Description                               Default
 category                                               default

 Attributes                        Default
 table                             banner
 r_field (unweighted)              rotate
 b_field                           banner
 separator (unweighted)            ':'
 delimiter (unweighted)            '{or}'
 weighted                          No
 once (weighted)                   No
 c_field (weighted)                category
 w_field (weighted)                weight
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 No
 Container tag                     No

B<Tag expansion example:>

    [banner category=my_category]

B<ASP-like Perl call:>

    $Tag->banner(  { category => $key, } );

or similarly with positional parameters,

    $Tag->banner($category, $attribute_hash_reference);

See Also

I<Banner/Ad rotation>

Description

Implements random or rotating banner ads. See I<Banner/Ad rotation> in
the Interchange Template documentation.

You will need a banner ad table (typically called 'banner') which
contains banner data. The following is an S<example:>

 code         category      weight        rotate        banner
 m_3          cat1          7             0             my banner 3
 m_1          cat1          1             0             my banner 1
 default                                  1             Default 1{or}Default 2{or}Default 3
 m_2          cat1          2             0             my banner 2
 t_1          cat2          4             0             their banner 1
 t_2          cat2          1             0             their banner 2

I<category>

S<Default:> category="default"

This specifies the category for weighted ad, or the table row (i.e.,
code value) for an unweighted ad.

I<table>

S<Default:> table="banner"

Setting 'table="my_banner_table"' forces the tag to refer to
'my_banner_table' rather than the default 'banner' table for banner ad
information.

I<r_field>

S<Default:> r_field="rotate"

Unweighted ads only.

A table row may include multiple banners in the 'banner' column. The
column specified by r_field contains a boolean that determines whether
to rotate banners. In the above table example, 'Default 1', 'Default
2' and 'Default 3' would rotate.

I<b_field>

S<Default:> b_field="banner"

This specifies the column containing the banner descriptor(s). The
default is 'banner'. Note that an entry might be a delimited list of
banner descriptors to rotate (see I<delimiter> below).

I<separator>

S<Default:> separator=":"

Unweighted ads only.

This sets the separator within the table key (i.e., code) for
multi-level categorized ads. See I<Banner/Ad rotation>.

I<delimiter>

S<Default:> delimiter="{or}"

Unweighted ads only.

This specifies the delimiter between rotating banner descriptors in
the 'banner' column.

I<weighted>

The banner tag will not apply weighting from the table unless you
set weighted=1. Note that the tag will behave as if you gave it a
standard unweighted entry - it will look for a matching row rather
than a matching category.

I<once>

Weighted ads only.

If the option once is passed (i.e., [banner once=1 weighted=1], then
the banners will not be rebuilt until the total_weight file is
removed. See I<Banner/Ad rotation>.

I<c_field>

S<Default:> c_field="category"

Weighted ads only.

This specifies the column containing the banner category for weighted
ads. The banner tag will display ads from rows in the table whose
category matches the category given in the tag, with frequency
corresponding to the weights in the table.

I<w_field>

S<Default:> w_field="weight"

Weighted ads only.

This specifies the column containing the banner weight.

=head2 bounce

Summary

Parameters: B<href if>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

None. This tag doesn't work with embedded Perl due to special
processing.

    [bounce href if]

 Parameters   Description                               Default
 href                                                   DEFAULT_VALUE
 if                                                     DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [bounce href if]
---
    TAG RESULT

B<ASP-like Perl call:>

None. This tag doesn't work with embedded Perl due to special
processing.

Description

The [bounce ...] tag is designed to send an HTTP redirect (302 status
code) to the browser and redirect it to another (possibly
Interchange-parsed) page.

It will stop ITL code execution at that point; further tags will not
be run through the parser. Bear in mind that if you are inside a
looping list, that list will run to completion and the [bounce] tag
will not be seen until the loop is complete.

Example of bouncing to an Interchange parsed page:

        [if !scratch real_user]
        [bounce href="[area violation]"]
        [/if]

Note the URL is produced by the [area ...] ITL tag.

Since the HTTP says the URL needs to be absolute, this one might cause
a browser warning:

        [if value go_home]
        [bounce href="/"]
        [/if]

But running something like one of the Interchange demos you can do:

        [if value go_home]
        [bounce href="__SERVER_NAME__/"]
        [/if]

        [if value go_home]
        [bounce href="/"]
        [/if]

I<href>

I<if>

=head2 calc

Calculates the value of the enclosed arithmetic expression.

Summary

    [calc] Expression [/calc]

B<No parameters>

B<No attributes> (though you can break it if you set
'interpolate=0')

 Other_Characteristics             
 Invalidates cache                 No
 Has Subtags                       No
 Container tag                     Yes
 Nests                             No

B<ASP-like Perl call:>

There is never a reason to call this tag from within Perl or ASP code.
Simply do the calculation directly.

Description

Calculates the value of the enclosed arithmetic expression.

Use it as follows: [calc] I<Expression> [/calc]

The enclosed region where the arguments are calculated according to
normal arithmetic symbols. For instance:

    [calc] 2 + 2 [/calc]

will expand to:

    4

The [calc] tag is really the same as the [perl] tag, except that it
doesn't accept arguments, interpolates surrounded Interchange tags by
default, and is slightly more efficient to parse.

Tip: The [calc] tag will remember variable values inside one page, so
you can do the equivalent of a memory store and memory recall for a
loop.

ASP Note: There is never a reason to call this tag from within Perl or
ASP code.

=head2 calcn

Calculates the value of the enclosed arithmetic expression.

Summary

    [calcn] Expression [/calcn]

B<No parameters>

B<No attributes>

 Other_Characteristics             
 Invalidates cache                 No
 Has Subtags                       No
 Container tag                     Yes
 Nests                             No

B<ASP-like Perl call:>

There is never a reason to call this tag from within Perl or ASP code.
Simply do the calculation directly.

Description

Equivalent to the [calc] tag, except that it does not
I<interpolate> by default.

NOTE: This tag was introduced in Interchange 4.9 and is therefore not
available in earlier versions.

=head2 cart

Summary

Parameters: B<name>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->cart(
        {
         name => VALUE,
        }
    )

 OR

    $Tag->cart($name);
    [cart name]

 Parameters   Description                               Default
 name                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [cart name]
---
    TAG RESULT

B<ASP-like Perl call:>

   $Tag->cart(  { name => VALUE_name
}, $body  );

or similarly with positional parameters,

    $Tag->cart(name, $attribute_hash_reference, $body);

Description

Sets the name of the current shopping cart for display of shipping,
price, total, subtotal, shipping, and nitems tags.

I<name>

=head2 catch

The page content contained within the [catch I<label>][/catch]
block executes if the correspondingly labelled  try block fails.

You can also return a result based on the error message caught in the
try block with paired subtags, like S<this:>

    [error message]body text[/error message]

Note that this feature excises I<all> tag/endtag pairs if
interpolation is turned off, so the catch tag interpolates by
default.

See also [try].

Summary

    [try my_label]
        Body text to return if no error
    [/try]
    .
    .
    .
    [catch label=my_label other_named_attributes]
        [/Pattern matching error message 1/]
            Return this if error 1 occurs
        [/Pattern matching error message 1/]

        [/Pattern matching error message 2/]
            Return this if error 2 occurs, etc.
        [/Pattern matching error message 2/]

        Default body text to process if try block caused an error
    [/catch]

 Parameters   Description                               Default
 label        The label shared by the paired try and catch blocks'default'

 Attributes                        Default
 interpolate                       Yes
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 No
 Container tag                     Yes
 Has Subtags                       [Error message text]body[/Error message text]

B<Tag expansion example>

Ignoring whitespace, the following would return division result if
successful, 0 on a division by zero, or an error S<message:>

    [set divisor]0[/set]
    [try label=div]
        [perl] eval(1 / [scratch divisor]) [/perl]
    [/try]
    [catch div]
        [/Illegal division by zero/]
            0
        [/Illegal division by zero/]
        [/eval "string" trapped by operation mask/]
            Perl Safe error
        [/eval "string" trapped by operation mask/]
        Other division error
    [/catch]
---
   Perl Safe error

B<ASP-like Perl call:>

    $Tag->catch(  { label => I<'my_label'>, },
                  $body  );

or similarly with positional parameters,

    $Tag->catch($label, $attribute_hash_reference, $body);

See Also

I<try>

    [catch]

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 No
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [catch]
---
    TAG RESULT

B<ASP-like Perl call:>

   $Tag->catch(  {
}, $body  );

or similarly with positional parameters,

    $Tag->catch(, $attribute_hash_reference, $body);

Description

The page content contained within the [catch I<label>][/catch]
block executes if the correspondingly labelled  try block fails.
The catch block executes in place on the page if triggered (I<i.e.>,
it does not return its result in place of the try block).

You can also return a result based on the error message caught in the
try block with paired subtags, like S<this:>

    [/error message/]special catch block for the error[/error message/]

The error message to use in the special block will generally be part
of the entry the error generates in your error log.  For example, a
division by zero error generates something like the following in the
error log:

   127.0.0.1 4cU3Pgsh:127.0.0.1 - [24/May/2001:14:45:07 -0400]\
   tag /cgi-bin/tag72/tag Safe: Illegal division by zero\
   at (eval 526) line 2.

(note that trailing backslashes in the example indicate a continued
line).

I<label>

This is the label specifying the corresponding [try block. Defaults
to 'default'.

=head2 cgi

Returns the the current value of the named CGI input variable.
HTML-escapes Interchange tags in the result for security.

Can also set a new CGI value within the current page.

Summary

    [cgi name]
    [cgi name=cgi_var_name other_named_attributes]

 Parameters   Description                               Default
 name         This is the name of the CGI variable whose value you want.None

 Attributes                        Default
 set                               none
 hide                              No
 filter                            none
 keep (with filter)                No
 enable_html                       No
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 Yes

B<Tag expansion example:>

Assuming CGI variable 'foo' = 'bar',

    [cgi foo]
---
    bar

B<ASP-like Perl call:>

    $Tag->cgi( { name => var_name } );

    # or if you simply want the value:
    $CGI->{var_name};

    # or:
    $CGI::values{var_name};

or similarly with positional parameters,

    $Tag->cgi($name, $attribute_hash_reference);

Description

Displays the value of a CGI variable B<submitted to the current page>.
This is similar to [value ...], except it displays the transitory
values that have been submitted with the current request.

For instance, if you access the following URL:

        http://VENDURL/pagename?foo=bar

bar will be substituted for [cgi foo].

This is the same as $CGI->{foo} in embedded Perl.

I<name>

This is the name of the CGI variable whose value you want.

I<set>

You can change a value with 'set=I<new_value>'. The tag will return
the CGI value you set unless you also set the I<hide>=1 attribute.

Note that this is only available in new-style tags, for safety
reasons.

I<hide>

Setting hide=1 suppresses the tag's return value, which can be
useful with the set attribute.

I<filter>

See the filter tag for a list of filters.

Setting 'filter="I<filter>"' modifies the named CGI variable with
the specified filter.

I<keep> (with filter)

Set keep=1 if you want the tag to return a filtered result but do
not want the filter to modify the CGI value itself in the $CGI::values
hash.

I<default>

This sets a return value in case the named CGI variable is missing or
otherwise false. The following will expand to S<"Using default":>

    [cgi name=myname set=0 hide=1]
    [cgi name=myname default="Using default"]

I<enable_html>

Any '<' characters will normally be converted into '&lt;' for safety
reasons. This conversion can be disabled using 'enable_html=1'.

=head2 checked

Summary

Parameters: B<name value>

Positional parameters in same order.

B<The attribute hash reference is passed> to the subroutine after the
parameters as the last argument. B<This may mean that there are
parameters not shown here.>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->checked(
        {
         name => VALUE,
         value => VALUE,
        }
    )

 OR

    $Tag->checked($name, $value, $ATTRHASH);
    [checked name value other_named_attributes]

 Parameters   Description                               Default
 case                                                   DEFAULT_VALUE
 cgi                                                    DEFAULT_VALUE
 default                                                DEFAULT_VALUE
 name                                                   DEFAULT_VALUE
 multiple                                               DEFAULT_VALUE
 value                                                  DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [value name=example set=neato]
    <INPUT TYPE=checkbox NAME=neato VALUE=1 [checked name=neato value=1]>
    <INPUT TYPE=checkbox NAME=silly VALUE=1 [checked name=silly value=1]>
    <INPUT TYPE=checkbox NAME=neato VALUE=1 CHECKED>
    <INPUT TYPE=checkbox NAME=silly VALUE=1 >

Description

You can provide a "memory" for drop-down menus, radio buttons, and
checkboxes with the [checked] and [selected] tags.

    <INPUT TYPE=radio NAME=foo
            VALUE=on [checked name=foo value=on default=1]>
    <INPUT TYPE=radio NAME=foo
            VALUE=off [checked name=foo value=off]>

This will output CHECKED if the variable var_name is equal to
value. Not case sensitive unless the optional case=1 parameter
is used.

The default parameter, if true (non-zero and non-blank), will cause
the box to be checked if the variable has never been defined.

Note that CHECKBOX items will never submit their value if not checked,
so the box will not be reset. You must do something like:

    <INPUT TYPE=checkbox NAME=foo
            VALUE=1 [checked name=foo value=1 default=1]>
    [value name=foo set=""]

By default, the Values space (i.e. [value foo]) is checked - if you
want to use the volatile CGI space (i.e. [cgi foo]) use the option
cgi=1.

Use the parameter default=1 to specify that this checkbox should be
marked CHECKED if the value/CGI variable has never been set.

If the parameter multiple=1 is set, the value parameter can
contain multiple (stacked) values that should be checked, separated by
ASCII null characters ("\0" in Perl).

I<case>

I<cgi>

I<default>

I<name>

I<multiple>

I<value>

=head2 control

Returns named scratchpad field or copies named scratch variable to
scratchpad. Returns value specified by 'default' attribute if
scratchpad variable is undefined or empty. Calling without a name
moves to next scratchpad. Calling without a name and 'reset=1' returns
to first scratchpad page.

Summary

    [control name default other_named_attributes]

 Parameters   Description                               Default
 default      Value to return if scratchpad variable missing or emptyDEFAULT_VALUE
 name         Name of scratchpad variable to set or returnDEFAULT_VALUE
 reset        Resets scratchpad (i.e. $::Control array) by setting special scratch variable 'control_index' to 0. Control_index is an index into the $::Control == $Vend::Session->{control} array of hashrefs.(must not specify name; may specify default)DEFAULT_VALUE
 set          Copies named scratch variable (i.e., from $::Scratch) to scratchpad with current control index.DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [control name default]
---
    TAG RESULT

B<ASP-like Perl call:>

   $Tag->control(  { default => VALUE_default
                      name => VALUE_name
}, $body  );

or similarly with positional parameters,

    $Tag->control(name,default, $attribute_hash_reference, $body);

Description

Returns named scratchpad field or copies named scratch variable to
scratchpad. Returns value specified by 'default' attribute if
scratchpad variable is undefined or empty. Calling without a name
moves to next scratchpad. Calling without a name and 'reset=1' returns
to first scratchpad page.

I<default>

Value to return if scratchpad variable missing or empty

I<name>

Name of scratchpad variable to set or return

I<reset>

Resets scratchpad (i.e. $::Control array) by setting special scratch
variable 'control_index' to 0. Control_index is an index into the
$::Control == $Vend::Session->{control} array of hashrefs.

=over 4

=item *

(must not specify name; may specify default)

=back

I<set>

Copies named scratch variable (i.e., from $::Scratch) to scratchpad
with current control index.

=head2 control_set

Bulk-sets scratchpad variables on the scratchpad page specified by
'index'. Note that, unlike [control], this does not copy values from
scratch.

Summary

This example sets var_one, var_two and var_three in the scratchpad on
page 5 (index begins with 0).

    [control_set index=4]
        [var_one]var_one_value[/var_one]
        [var_two]var_two_value[/var_two]
        [var_three]var_three_value[/var_three]
    [/control_set]

Parameters: B<index>

Positional parameters in same order.

B<The attribute hash reference is passed> after the parameters but
before the container text argument. B<This may mean that there are
parameters not shown here.>

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [control_set] FOO [/control_set].
Nesting: NO

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->control_set(
        {
         index => VALUE,
        },
        BODY
    )

 OR

    $Tag->control_set($index, $ATTRHASH, $BODY);
    [control_set index other_named_attributes]

 Parameters   Description                               Default
 index                                                  DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [control_set index]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->control_set(  { index => VALUE_index
}, $body  );

or similarly with positional parameters,

    $Tag->control_set(index, $attribute_hash_reference, $body);

Description

Bulk-sets scratchpad variables on the scratchpad page specified by
'index'. Note that, unlike [control], this does not copy values from
scratch.

I<index>

=head2 counter

Summary

Parameters: B<file start date sql>

Positional parameters: B<file>

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->counter(
        {
         file => VALUE,
         sql => VALUE,
         start => VALUE,
         date => 'local' || 'gmt',
        }
    )

 OR

    $Tag->counter($file, $ATTRHASH);

Attribute aliases

            name ==> file
    [counter file]

 Parameters   Description                               Default
 file                                                   DEFAULT_VALUE
 name         Alias for file                            DEFAULT_VALUE
 sql          Asserts a SQL-based counter               DEFAULT_VALUE
 date         Asserts a date-based counter              DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [counter file]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->counter(  { file => VALUE_file, sql => 'table:seq', start => VALUE, }  );

or similarly with positional parameters,

    $Tag->counter(file, $attribute_hash_reference);

Description

Manipulates a persistent counter, by default incrementing it and
returning the new value.

The counter value is stored in the specified file. If the file name
begins with a "/" then it is an absolute path. Otherwise, it is
relative to VendRoot. The default file is etc/counter. If the file
does not exist, it is created and initialized to the value of the
start parameter.

If the optional sql attribute is used, a SQL sequence will be used.
Currently MySQL and Postgres are supported. The sequence must already
exist. If no bypass parameter is sent, the table in the sequence
callout (explained below) will be used and must be an Interchange
table (i.e. set up with Database setting). If bypass is set, then
the DSN for the sequence will be passed in the dsn parameter.

If the optional date attribute is used, a date-based counter will
be made. It takes the form of the date in YYYYMMDD followed by the
start value, by default 0001. When the date changes, the counter
will flip over to the next day and the beginning start value.

WARNING: This tag may not work under I<Safe>, i.e. in embedded Perl.

Additional parameters:

I<decrement=1>

Causes the counter to count down instead of up. This option is not
applicable to SQL counters.

I<start=50>

Causes a new counter to be created and to start from 50 (for example)
if it did not exist before. This option is not applicable to SQL
counters.

I<value=1>

Shows the value of the counter without incrementing or decrementing
it. This option is not applicable to SQL counters.

I<sql="table:sequence">

The table and sequence name of the SQL counter.

If the type of database is Postgres, the table is used to derive
the database and the sequence will be a named sequence independent of
the table; the sequence is incremented and accessed by "SELECT
nextval('sequence_name')".

If the type of database is MySQL, an AUTO_INCREMENT key column is
assumed and an insert of 0 followed by "select last_insert_id()"
will increment then access the counter.

I<date="local">

Specifies the counter will be date-based with local time.

I<date="gmt">

Specifies the counter will be date-based with GMT.

I<file>

SQL Counter Examples

To set up a Postgres counter, simply create a named sequence in the
database:

  CREATE SEQUENCE "foo" start 1 increment 1 maxvalue 2147483647 minvalue 1 cache 1

You will want to make sure you have an Interchange table that uses
that database ("sometable" in the below example).

Then access it with:

    [counter sql="sometable:foo"]

You can create as many sequences as you like.

To set up a MySQL counter, add a table to your MySQL database in
catalog.cfg or other place like dbconf/mysql:

  Database sequence_name sequence_name.txt dbi:mysql:test_foundation
  Database sequence_name COLUMN_DEF "id=int NOT NULL AUTO_INCREMENT PRIMARY KEY"

Make sure you set up the sequence.txt file if you want Interchange to
create the table for you. Otherwise you can create the table yourself
from a mysql client:

mysql> create table sequence_name(id int NOT NULL AUTO_INCREMENT
PRIMARY KEY);

Then access it with:

    [counter sql="sequence_name:sequence_name"]

Alternatively, you can create the table without Interchange definition
as long as it is in the same database as an Interchange table:

  mysql> create table sequence_name(id int NOT NULL AUTO_INCREMENT PRIMARY KEY);

Then access it by calling the Interchange-defined table name followed
by the table that has the AUTO_INCREMENT key:

    [counter sql="products:sequence_name"]

To set up an Oracle counter, create a sequence:

  SQL> CREATE SEQUENCE foo START WITH 10000 INCREMENT BY 1
                 MAXVALUE 2147483647 MINVALUE 1 CACHE 2;

Then access via a table already connected to Oracle, in below
sometable:

    [counter sql="sometable:foo"]
  Database sequence_name sequence_name.txt dbi:mysql:test_foundation
  Database sequence_name COLUMN_DEF "id=int NOT NULL AUTO_INCREMENT PRIMARY KEY"

Make sure you set up the sequence.txt file if you want Interchange to
create the table for you. Otherwise you can create the table yourself
from a mysql client:

mysql> create table sequence_name(id int NOT NULL AUTO_INCREMENT
PRIMARY KEY);

Then access it with:

    [counter sql="sequence_name:sequence_name"]

Alternatively, you can create the table without Interchange definition
as long as it is in the same database as an Interchange table:

  mysql> create table sequence_name(id int NOT NULL AUTO_INCREMENT PRIMARY KEY);

Then access it by calling the Interchange-defined table name followed
by the table that has the AUTO_INCREMENT key:

    [counter sql="products:sequence_name"]

=head2 currency

Summary

Parameters: B<convert noformat>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Interpolates B<container text> by default.

This is a container tag, i.e. [currency] FOO [/currency]. Nesting: NO

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->currency(
        {
         convert => VALUE,
         noformat => VALUE,
        },
        BODY
    )

 OR

    $Tag->currency($convert, $noformat, $BODY);
    [currency convert noformat]

 Parameters   Description                               Default
 convert                                                DEFAULT_VALUE
 noformat                                               DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [currency convert noformat]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->currency(  { convert => VALUE_convert
                       noformat => VALUE_noformat
}, $body  );

or similarly with positional parameters,

    $Tag->currency(convert,noformat, $attribute_hash_reference, $body);

Description

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

    [currency]4[/currency]

will display:

    4.00

or something else depending on the I<Locale> and PriceCommas settings.
It can contain a [calc] region. If the optional "convert" parameter is
set, it will convert the value according to PriceDivide> for the
current locale. If Locale is set to fr_FR, and F<PriceDivide> for
fr_FR is 0.167, the following sequence

    [currency convert=1] [calc] 500.00 + 1000.00 [/calc] [/currency]

will cause the number 8.982,04 to be displayed.

I<convert>

I<noformat>

=head2 data

Summary

Main Parameters: B<table field key>

Positional parameters in same order.

Additional parameters: hash foreign value

B<The attribute hash reference is passed> to the subroutine after the
parameters as the last argument. B<This may mean that there are
parameters not shown here.>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->data(
        {
         table => VALUE,
         field => VALUE,
         key => VALUE,
        }
    )

 OR

    $Tag->data($table, $field, $key, $ATTRHASH);

Attribute aliases

            base ==> table
            code ==> key
            col ==> field
            column ==> field
            database ==> table
            name ==> field
            row ==> key
    [data table field key other_named_attributes]

 Parameters   Description                               Default
 base         Alias for table                           DEFAULT_VALUE
 code         Alias for key                             DEFAULT_VALUE
 col          Alias for field                           DEFAULT_VALUE
 column       Alias for field                           DEFAULT_VALUE
 database     Alias for table                           DEFAULT_VALUE
 field                                                  DEFAULT_VALUE
 hash                                                   DEFAULT_VALUE
 key                                                    DEFAULT_VALUE
 name         Alias for field                           DEFAULT_VALUE
 row          Alias for key                             DEFAULT_VALUE
 table                                                  DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [data table field key]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->data(  { field => VALUE_field
                   key => VALUE_key
                   table => VALUE_table
});

or similarly with positional parameters,

    $Tag->data(table,field,key, $attribute_hash_reference);

Description

Syntax:             [data table=db_table column=column_name key=key
filter="uc|lc|name|namecase|no_white|etc."* append=1*
foreign="foreign_key_column"* value="value to set to"* increment=1*]

Returns the value of the field in a database table, or from the
session namespace. If the optional B<value> is supplied, the entry
will be changed to that value. If the option increment* is present,
the field will be atomically incremented with the value in B<value>.
Use negative numbers in value to decrement. The append attribute
causes the value to be appended; and finally, the filter attribute
is a set of Interchange filters that are applied to the data 1) after
it is read; or 2)before it is placed in the table.

If a DBM-based database is to be modified, it must be flagged writable
on the page calling the write tag. Use [tag flag write]products[/tag]
to mark the products database writable, for example. B<This must be
done before ANY access to that table.>

In addition, the [data ...] tag can access a number of elements in
the Interchange session database:

    accesses           Accesses within the last 30 seconds
    arg                The argument passed in a [page ...] or [area ...] tag
    browser            The user browser string
    cybercash_error    Error from last CyberCash operation
    cybercash_result   Hash of results from CyberCash (access with usertag)
    host               Interchange's idea of the host (modified by DomainTail)
    last_error         The last error from the error logging
    last_url           The current Interchange path_info
    logged_in          Whether the user is logged in (add-on UserDB feature)
    pageCount          Number of unique URLs generated
    prev_url           The previous path_info
    referer            HTTP_REFERER string
    ship_message       The last error messages from shipping
    source             Source of original entry to Interchange
    time               Time (seconds since Jan 1, 1970) of last access
    user               The REMOTE_USER string
    username           User name logged in as (UserDB feature)

Note: Databases will hide session values, so don't name a database
"session". or you won't be able to use the [data ...] tag to read
them. Case is sensitive, so in a pinch you could call the database
"Session", but it would be better not to use that name at all.

I<field>

The name of the field whose value you want to fetch. Required unless
returning the entire row in combination with the hash option.

I<foreign>

To select a data element based on a foreign key, specify the foreign
key column in this field. Allows selection of a data element or record
based on a column that is not the primary key.

If the key is not unique, returns the first selected element.

From this table named "foo":

  sku  name    partno  group   subgroup
  AB   Item 1  1       A       1
  AC   Item 2  2       A       2
  AD   Item 3  3       B       1
  AE   Item 4  4       C       1

These calls:

  [data table=foo col=name key=AB]
  [data table=foo col=name key=1 foreign=partno]

would both return "Item 1".

If the foreign parameter is a hash value, a single value matching
the query-by-example set up by the hash is returned. For instance,
from our example table "foo", the following

  [data table=foo col=name key=1 foreign.group=A foreign.subgroup=2]

would return "Item 2".

If the query needs to be optimized in a particular order, you need to
use custom code or the array form of foreign. In our table "foo",
the following

  [data table=foo col=name key=1 foreign.0="group=A" foreign.1="subgroup=2"]

also returns "Item 2".

I<hash>

The hash option causes the data tag to return its results (the entire
row, if you omit the field parameter) as a reference to a hash with
column names as keys into the values of the row.

An example:

        $row_hash = $Tag->data({
                table => 'products',
                key   => 'os28004',
                hash  => 1,
        });

You could then access desired values this way:

        $out = 'Price: ' . $row_hash->{price};

I<key>

The key that identifies the row containing the value(s) you want to
fetch. Required.

I<table>

The name of the Interchange-defined table you want to fetch data from.
Required.

=head2 default

Summary

Parameters: B<name default>

Positional parameters in same order.

B<The attribute hash reference is passed> to the subroutine after the
parameters as the last argument. B<This may mean that there are
parameters not shown here.>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->default(
        {
         name => VALUE,
         default => VALUE,
        }
    )

 OR

    $Tag->default($name, $default, $ATTRHASH);
    [default name default other_named_attributes]

 Parameters   Description                               Default
 default                                                DEFAULT_VALUE
 name                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [default name default]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->default(  { default => VALUE_default
                      name => VALUE_name
}, $body  );

or similarly with positional parameters,

    $Tag->default(name,default, $attribute_hash_reference, $body);

Description

Returns the value of the user form variable variable if it is
non-empty. Otherwise returns default, which is the string "default"
if there is no default supplied. Got that? This tag is DEPRECATED
anyway.

I<default>

I<name>

=head2 description

Summary

Parameters: B<code base>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->description(
        {
         code => VALUE,
         base => VALUE,
        }
    )

 OR

    $Tag->description($code, $base);
    [description code base]

 Parameters   Description                               Default
 base                                                   DEFAULT_VALUE
 code                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [description code base]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->description(  { base => VALUE_base
                          code => VALUE_code
}, $body  );

or similarly with positional parameters,

    $Tag->description(code,base, $attribute_hash_reference, $body);

Description

Expands into the description of the product identified by code as
found in the products database. This is the value of the database
field that corresponds to the catalog.cfg directive
DescriptionField. If there is more than one products file defined,
they will be searched in order unless constrained by the optional
argument B<base>.

This tag is especially useful for multi-language catalogs. The
DescriptionField directive can be set for each locale and point to
a different database field; for example desc_en for English,
desc_fr for French, etc.

I<base>

I<code>

=head2 discount

Summary

Parameters: B<code>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [discount] FOO [/discount]. Nesting: NO

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->discount(
        {
         code => VALUE,
        },
        BODY
    )

 OR

    $Tag->discount($code, $BODY);
    [discount code]

 Parameters   Description                               Default
 code                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [discount code]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->discount(  { code => VALUE_code
}, $body  );

or similarly with positional parameters,

    $Tag->discount(code, $attribute_hash_reference, $body);

Description

Product discounts can be set upon display of any page. The discounts
apply only to the customer receiving them, and are of one of three
types:

    1. A discount for one particular item code (code/key is the item-code)
    2. A discount applying to all item codes (code/key is ALL_ITEMS)
    3. A discount applied after all items are totaled
       (code/key is ENTIRE_ORDER)

The discounts are specified via a formula. The formula is scanned for
the variables $q and $s, which are substituted for with the item
I<quantity> and I<subtotal> respectively. In the case of the item and
all items discount, the formula must evaluate to a new subtotal for
all items I<of that code> that are ordered. The discount for the
entire order is applied to the entire order, and would normally be a
monetary amount to subtract or a flat percentage discount.

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

To apply a straight 20% discount to all items:

    [discount ALL_ITEMS] $s * .8 [/discount]

or with named attributes:

    [discount code=ALL_ITEMS] $s * .8 [/discount]

To take 25% off of only item 00-342:

    [discount 00-342] $s * .75 [/discount]

To subtract $5.00 from the customer's order:

    [discount ENTIRE_ORDER] $s - 5 [/discount]

To reset a discount, set it to the empty string:

    [discount ALL_ITEMS][/discount]

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

    [discount 00-343]
    return $s if $q == 1;
    my $p = $s/$q;
    my $t = ($q - 1) * $p;
    $t .= 0.01;
    return $t;
    [/discount]

If you want to display the discount amount, use the [item-discount]
tag.

    [item-list]
    Discount for [item-code]: [item-discount]
    [/item-list]

Finally, if you want to display the discounted subtotal in a way that
doesn't correspond to a standard Interchange tag, you can use the
[calc] tag:

    [item-list]
    Discounted subtotal for [item-code]: [currency][calc]
                                            [item-price noformat] * [item-quantity]
                                            [/calc][/currency]
    [/item-list]

I<code>

=head2 dump

Dumps client connection information, cart contents, query value,
contents of environment, session, and CGI with Data::Dumper to the
page. This is useful for debugging.

Summary

No parameters.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->dump(
        {
        }
    )

 OR

    $Tag->dump($);
    [dump]

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [dump]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->dump(  {
}, $body  );

or similarly with positional parameters,

    $Tag->dump(, $attribute_hash_reference, $body);

Description

Dumps client connection information, cart contents, query value,
contents of environment, session, and CGI with Data::Dumper to the
page. This is useful for debugging.

=head2 ecml

Uses ECML (Electronic Commerce Markup Language) module to map
Interchange forms/userdb to ECML checkout

Summary

    [ecml name function other_named_attributes]

 Parameters   Description                               Default
 function     ecml function (default = 'widget')        DEFAULT_VALUE
 name                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [ecml name function]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->ecml(  { function => VALUE_function
                   name => VALUE_name
}, $body  );

or similarly with positional parameters,

    $Tag->ecml(name,function, $attribute_hash_reference, $body);

Description

This package implements the ECML standard for the Interchange demo.
ECML stands for "Electronic Commerce Modeling Language", but at this
writing it is a simple standard for naming variables so that
"electronic wallets" can pre-fill-in your checkout form based on users
past purchase from other companies.

It translates into ECML from the following Interchange variables:

 ECML                                     Interchange variable
 Ecom_BillTo_Online_Email                 b_email
 Ecom_BillTo_Postal_City                  b_city
 Ecom_BillTo_Postal_CountryCode           b_country
 Ecom_BillTo_Postal_Name_First            b_fname
 Ecom_BillTo_Postal_Name_Last             b_lname
 Ecom_BillTo_Postal_Name_Middle           b_mname
 Ecom_BillTo_Postal_Name_Prefix           b_title
 Ecom_BillTo_Postal_Name_Suffix           b_name_suffix
 Ecom_BillTo_Postal_PostalCode            b_zip
 Ecom_BillTo_Postal_StateProv             b_state
 Ecom_BillTo_Postal_Street_Line1          b_address1
 Ecom_BillTo_Postal_Street_Line2          b_address2
 Ecom_BillTo_Postal_Street_Line3          b_address3
 Ecom_BillTo_Telecom_Phone_Number         b_phone_day
 Ecom_ConsumerOrderID                     mv_order_number
 Ecom_Payment_Card_ExpDate_Day            mv_credit_card_exp_day
 Ecom_Payment_Card_ExpDate_Month          mv_credit_card_exp_month
 Ecom_Payment_Card_ExpDate_Year           mv_credit_card_exp_year
 Ecom_Payment_Card_Name                   c_name
 Ecom_Payment_Card_Number                 mv_credit_card_number
 Ecom_Payment_Card_Protocol               payment_protocols_available
 Ecom_Payment_Card_Type                   mv_credit_card_type
 Ecom_Payment_Card_Verification           mv_credit_card_verify
 Ecom_ReceiptTo_Online_Email              r_email
 Ecom_ReceiptTo_Postal_City               r_city
 Ecom_ReceiptTo_Postal_CountryCode        r_country
 Ecom_ReceiptTo_Postal_Name_First         r_fname
 Ecom_ReceiptTo_Postal_Name_Last          r_lname
 Ecom_ReceiptTo_Postal_Name_Middle        r_mname
 Ecom_ReceiptTo_Postal_Name_Prefix        r_title
 Ecom_ReceiptTo_Postal_Name_Suffix        r_name_suffix
 Ecom_ReceiptTo_Postal_PostalCode         r_zip
 Ecom_ReceiptTo_Postal_StateProv          r_state
 Ecom_ReceiptTo_Postal_Street_Line1       r_address1
 Ecom_ReceiptTo_Postal_Street_Line2       r_address2
 Ecom_ReceiptTo_Postal_Street_Line3       r_address3
 Ecom_ReceiptTo_Telecom_Phone_Number      r_phone
 Ecom_SchemaVersion                       ecml_version
 Ecom_ShipTo_Online_Email                 email
 Ecom_ShipTo_Postal_City                  city
 Ecom_ShipTo_Postal_CountryCode           country
 Ecom_ShipTo_Postal_Name_Combined         name
 Ecom_ShipTo_Postal_Name_First            fname
 Ecom_ShipTo_Postal_Name_Last             lname
 Ecom_ShipTo_Postal_Name_Middle           mname
 Ecom_ShipTo_Postal_Name_Prefix           title
 Ecom_ShipTo_Postal_Name_Suffix           name_suffix
 Ecom_ShipTo_Postal_PostalCode            zip
 Ecom_ShipTo_Postal_StateProv             state
 Ecom_ShipTo_Postal_Street_Line1          address1
 Ecom_ShipTo_Postal_Street_Line2          address2
 Ecom_ShipTo_Postal_Street_Line3          address3
 Ecom_ShipTo_Telecom_Phone_Number         phone
 Ecom_TransactionComplete                 end_transaction_flag

Once the form variables are input and sent to Interchange, the [ecml
function=mapback] tag will cause the input results to be mapped back
from the ECML names to the Interchange names.

If you only have a name variable in your UserDB, the module will
attempt to split it into first name and last name for ECML purposes
and map the results back. If you have fname and lname, then it
will not.

I<function>

ecml function (default = 'widget')

I<name>

=head2 either

The [either]this[or]that[/either] implements a check for the first
non-zero, non-blank value. It splits on [or], and then parses each
piece in turn. If a value returns true (in the Perl sense: non-zero,
non-blank) then subsequent pieces will be discarded without
interpolation.

Summary

    [either]
        This
    [or]
        That
    [or]
        The other
    [/either]

No parameters.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [either] FOO [/either]. Nesting: NO

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->either(
        {
        },
        BODY
    )

 OR

    $Tag->either($BODY);
    [either]

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [either]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->either(  {
}, $body  );

or similarly with positional parameters,

    $Tag->either(, $attribute_hash_reference, $body);

Description

B<NO Description>

=head2 error

Summary

Parameters: B<name>

Positional parameters in same order.

B<The attribute hash reference is passed> to the subroutine after the
parameters as the last argument. B<This may mean that there are
parameters not shown here.>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->error(
        {
         name => VALUE,
        }
    )

 OR

    $Tag->error($name, $ATTRHASH);
    [error name other_named_attributes]

 Parameters   Description                               Default
 name                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [error name]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->error(  { name => VALUE_name
}, $body  );

or similarly with positional parameters,

    $Tag->error(name, $attribute_hash_reference, $body);

Description

    [error var options]
        var is the error name, e.g. "session"

The [error ...] tag is designed to manage form variable checking for
the Interchange submit form processing action. It works in
conjunction with the definition set in mv_order_profile, and can
generate error messages in any format you desire.

If the variable in question passes order profile checking, it will
output a label, by default B<bold> text if the item is required, or
normal text if not (controlled by the <require> parameter. If the
variable fails one or more order checks, the error message will be
substituted into a template and the error cleared from the user's
session.

(Below is as of 4.03, the equivalent in 4.02 is [if type=explicit
compare="[error all=1 keep=1]"] ... [/if].)

To check errors without clearing them, you can use the idiom:

    [if errors]
    <FONT SIZE="+1" COLOR=RED>
        There were errors in your form submission.
    </FONT>
    <BLOCKQUOTE>
        [error all=1 show_error=1 joiner="<BR>"]
    </BLOCKQUOTE>
    [/if]

The options are:

I<all=1>

Display all error messages, not just the one referred to by <var>. The
default is only display the error message assigned to <var>.

text=<optional string to embed the error message(s) in>

place a "%s" somewhere in 'text' to mark where you want the error
message placed, otherwise it's appended on the end. This option also
implies show_error.

I<joiner=I<char>>

Character used to join multiple error messages. Default is '\n', a
newline.

I<keep=1>

keep=1 means don't delete the error messages after copy; anything else
deletes them.

I<show_error=1>

show_error=1 means return the error message text; otherwise just the
number of errors found is returned.

I<show_label=1>

show_label=1 causes the field label set by a previous [error] tag's
std_label attribute (see below) to be included as part of the error
message, like this:

 First Name: blank

If no std_label was set, the variable name will be used instead. This
can also be used in combination with show_var to show both the label
and the variable name.

show_label was added in 4.7.0.

I<show_var=1>

show_var=1 includes the name of the variable the error was found in as
part of the error message, like this:

 email: 'bob#nothing,net' not a valid email address

I<std_label>

std_label=<label string for error message>

used with 'required' to display a standardized error format. The HTML
formatting can be set via the global variable MV_ERROR_STD_LABEL with
the default being:

        <FONT COLOR=RED>{LABEL}<SMALL><I>(%s)</I></SMALL></FONT>

where {LABEL} is what you set std_label to and %s is substituted with
the error message. This option can not be used with the text= option.

I<required=1>

Specifies that this is a required field for formatting purposes. In
the std_label format, it means the field will be bolded. If you
specify your own label string, it will insert HTML anywhere you have
{REQUIRED: HTML}, but only when the field is required.

I<name>

=head2 export

Exports a database to a delimited text file (see also import).

Summary

    [export table other_named_attributes]

 Parameters   Description                               Default
 base         Alias for table                           DEFAULT_VALUE
 database     Alias for table                           DEFAULT_VALUE
 delete       If 'verify' attribute also set, deletes column specified by 'field' attribute rather than adding a column.DEFAULT_VALUE
 field        The column to add (or delete if delete and verify are true)DEFAULT_VALUE
 file         Filename to export to. Note that the NoAbsolute directive and other conditions may affect actual location of the output file.DEFAULT_VALUE
 sort         Output sorted rows (usage: sort="sort_field:sort_option") (see search/form variable 'mv_sort_option' for sort options)DEFAULT_VALUE
 table        The table to export                       DEFAULT_VALUE
 type         Specifies the [line, record] delimiter types. Either NOTES or one of the following:  my %Delimiter = (       2 => ["\n", "\n\n"],       3 => ["\n%%\n", "\n%%%\n"],       4 => ["CSV","\n"],       5 => ['|', "\n"],       6 => ["\t", "\n"],       7 => ["\t", "\n"],       8 => ["\t", "\n"],       LINE => ["\n", "\n\n"],       '%%%' => ["\n%%\n", "\n%%%\n"],       '%%' => ["\n%%\n", "\n%%%\n"],       CSV => ["CSV","\n"],       PIPE => ['|', "\n"],       TAB => ["\t", "\n"],       );If using NOTESnotes_separator (defaults to "\f")notes_field (defaults to "notes_field")DEFAULT_VALUE
 verify       must be true when deleting a column       DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [export table]
---
    1

B<ASP-like Perl call:>

   $Tag->export(  { table => VALUE_table
}, $body  );

or similarly with positional parameters,

    $Tag->export(table, $attribute_hash_reference, $body);

Description

Exports 'table' to a delimited text file. See also import tag which
imports files into databases.

I<delete>

If 'verify' attribute also set, deletes column specified by 'field'
attribute rather than adding a column.

I<field>

The column to add (or delete if delete and verify are true)

I<file>

Filename to export to. Note that the NoAbsolute directive and other
conditions may affect actual location of the output file.

I<sort>

Output sorted rows (S<usage:> sort="I<sort_field>:I<sort_option>")
(see search/form variable 'mv_sort_option' for sort options)

I<table>

The table to export

I<type>

Specifies the [line, record] delimiter types. Either NOTES or one of
the following:

  my %Delimiter = (
        2 => ["\n", "\n\n"],
        3 => ["\n%%\n", "\n%%%\n"],
        4 => ["CSV","\n"],
        5 => ['|', "\n"],
        6 => ["\t", "\n"],
        7 => ["\t", "\n"],
        8 => ["\t", "\n"],
        LINE => ["\n", "\n\n"],
        '%%%' => ["\n%%\n", "\n%%%\n"],
        '%%' => ["\n%%\n", "\n%%%\n"],
        CSV => ["CSV","\n"],
        PIPE => ['|', "\n"],
        TAB => ["\t", "\n"],
        );

=over 4

=item *

If using NOTES

=over 8

=item *

notes_separator (defaults to "\f")

=item *

notes_field (defaults to "notes_field")

=back

=back

I<verify>

must be true when deleting a column

=head2 field

Summary

Parameters: B<name code>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->field(
        {
         name => VALUE,
         code => VALUE,
        }
    )

 OR

    $Tag->field($name, $code);

Attribute aliases

            col ==> name
            column ==> name
            field ==> name
            key ==> code
            row ==> code
    [field name code]

 Parameters   Description                               Default
 code                                                   DEFAULT_VALUE
 col          Alias for name                            DEFAULT_VALUE
 column       Alias for name                            DEFAULT_VALUE
 field        Alias for name                            DEFAULT_VALUE
 key          Alias for code                            DEFAULT_VALUE
 name                                                   DEFAULT_VALUE
 row          Alias for code                            DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [field name code]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->field(  { code => VALUE_code
                    name => VALUE_name
}, $body  );

or similarly with positional parameters,

    $Tag->field(name,code, $attribute_hash_reference, $body);

Description

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

Note that if you only have one ProductFile products, which is the
default, [field column key] is the same as [data products column
key].

I<code>

I<name>

=head2 file

Summary

Parameters: B<name type>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->file(
        {
         name => VALUE,
         type => VALUE,
        }
    )

 OR

    $Tag->file($name, $type);
    [file name type]

 Parameters   Description                               Default
 name                                                   DEFAULT_VALUE
 type                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [file name type]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->file(  { name => VALUE_name
                   type => VALUE_type
}, $body  );

or similarly with positional parameters,

    $Tag->file(name,type, $attribute_hash_reference, $body);

Description

Inserts the contents of the named file. The file should normally be
relative to the catalog directory - file names beginning with / or ..
are not allowed if the Interchange server administrator has set
I<NoAbsolute> to Yes.

The optional type parameter will do an appropriate ASCII
translation on the file before it is sent.

I<name>

I<type>

=head2 filter

Summary

Parameters: B<op>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [filter] FOO [/filter]. Nesting: NO

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->filter(
        {
         op => VALUE,
        },
        BODY
    )

 OR

    $Tag->filter($op, $BODY);
    [filter op]

 Parameters   Description                               Default
 op                                                     DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [filter lc]UPPER CASE YOU WANT TO SEE AS LOWER CASE[/filter]

    Produces:

                upper case you want to see as lower case


B<ASP-like Perl call:>

   $Tag->filter(  { op => VALUE_op
}, $body  );

or similarly with positional parameters,

    $Tag->filter(op, $attribute_hash_reference, $body);

Description

Applies any of Interchange's standard filters to an arbitrary value,
or you may define your own. The filters are also available as
parameters to the cgi, data, and value tags.

Filters can be applied in sequence and as many as needed can be
applied.

Here is an example. If you store your author or artist names in the
database "LAST, First" so that they sort properly, you still might
want to display them normally as "First Last". This call

    [filter op="name namecase"]WOOD, Grant[/filter]

will display as

    Grant Wood

Another way to do this would be:

    [data table=products column=artist key=99-102 filter="name namecase"]

Filters available include:

Length filter

If you pass just a numeric argument, filter will return only first N
characters.  For example:

 [filter 5]Interchange[/filter]

results in:

"Inter"

By appending a ".", you can direct Interchange to append an ellipsis:

 [filter 5.]Interchange[/filter]

results in:

"Inter..."

                if (/^(\d+)(\.?)$/) {
                        substr($value, $1) = $2 ? '...' : ''
                                if length($value) > $1;
                        next;
                }

I<cgi>

Returns the value of the CGI variable. Useful for starting a filter
sequence with a seed value.

    'cgi' =>    sub {
                    return $CGI::values(shift);
                },

I<digits>

Returns only digits.

    'digits' => sub {
                    my $val = shift;
                    $val =~ s/\D+//g;
                    return $val;
                },

I<digits_dot>

Returns only digits and periods, i.e. [.0-9]. Useful for decommifying
numbers.

    'digits_dot' => sub {
                    my $val = shift;
                    $val =~ s/[^\d.]+//g;
                    return $val;
                },

I<dos>

Turns linefeeds into carriage-return / linefeed pairs.

    'dos' =>    sub {
                    my $val = shift;
                    $val =~ s/\r?\n/\r\n/g;
                    return $val;
                },

I<entities>

Changes C<<> to &lt;, " to &quot;, etc.

    'entities' => sub {
                    return HTML::Entities::encode(shift);
                },

I<gate>

Performs a security screening by testing to make sure a corresponding
scratch variable has been set.

    'gate' =>   sub {
                    my ($val, $var) = @_;
                    return '' unless $::Scratch->{$var};
                    return $val;
                },

I<lc>

Lowercases the text.

    'lc' =>     sub {
                    return lc(shift);
                },

I<lookup>

Looks up an item in a database based on the passed table and column.
Call would be:

    [filter op="uc lookup.country.name"]US[/filter]

This would be the equivalent of [data table=country column=name
key=US].

    'lookup' => sub {
                        my ($val, $tag, $table, $column) = @_;
                        return tag_data($table, $column, $val) || $val;
                },

I<mac>

Changes newlines to carriage returns.

    'mac' =>    sub {
                    my $val = shift;
                    $val =~ s/\r?\n|\r\n?/\r/g;
                    return $val;
                },

I<name>

Transposes a LAST, First name pair.

    'name' => sub {
                    my $val = shift;
                    return $val unless $val =~ /,/;
                    my($last, $first) = split /\s*,\s*/, $val, 2;
                    return "$first $last";
                },

I<namecase>

Namecases the text. Only works on values that are uppercase in the
first letter, i.e. [filter op=namecase]LEONARDO da Vinci[/filter] will
return "Leonardo da Vinci".

    'namecase' => sub {
                    my $val = shift;
                    $val =~ s/([A-Z]\w+)/\L\u$1/g;
                    return $val;
                },

I<no_white>

Strips all whitespace.

    'no_white' =>   sub {
                    my $val = shift;
                    $val =~ s/\s+//g;
                    return $val;
                },

I<pagefile>

Strips leading slashes and dots.

    'pagefile' => sub {
                    $_[0] =~ s:^[./]+::;
                    return $_[0];
                },

I<sql>

Change single-quote characters into doubled versions, i.e. ' becomes
''.

    'sql'       => sub {
                    my $val = shift;
                    $val =~ s:':'':g; # '
                    return $val;
                },

I<strip>

Strips leading and trailing whitespace.

    'strip' =>  sub {
                    my $val = shift;
                    $val =~ s/^\s+//;
                    $val =~ s/\s+$//;
                    return $val;
                },

I<text2html>

Rudimentary HTMLizing of text.

    'text2html' => sub {
                    my $val = shift;
                    $val =~ s|\r?\n\r?\n|<P>|;
                    $val =~ s|\r?\n|<BR>|;
                    return $val;
                },

I<uc>

Uppercases the text.

    'uc' =>     sub {
                    return uc(shift);
                },

I<unix>

Removes those crufty carriage returns.

    'unix' =>   sub {
                    my $val = shift;
                    $val =~ s/\r?\n/\n/g;
                    return $val;
                },

I<urlencode>

Changes non-word characters (except colon) to %3c notation.

    'urlencode' => sub {
                    my $val = shift;
                    $val =~ s|[^\w:]|sprintf "%%%02x", ord $1|eg;
                    return $val;
                },

I<value>

Returns the value of the user session variable. Useful for starting a
filter sequence with a seed value.

    'value' =>  sub {
                    return $::Values->(shift);
                },

I<word>

Only returns word characters. Locale does apply if collation is
properly set.

    'word' =>   sub {
                    my $val = shift;
                    $val =~ s/\W+//g;
                    return $val;
                },

You can define your own filters in a I<GlobalSub> (or Sub or
ActionMap):

    package Vend::Interpolate;

    $Filter{reverse} = sub { $val = shift; return scalar reverse $val  };

That filter will reverse the characters sent.

The arguments sent to the subroutine are the value to be filtered, any
associated variable or tag name, and any arguments appended to the
filter name with periods as the separator.

A [filter op=lookup.products.price]99-102[/filter] will send
('99-102', undef, 'products', 'price') as the parameters. Assuming the
value of the user variable foo is bar, the call [value
name=foo filter="lookup.products.price.extra"] will send ('bar',
'foo', 'products', 'price', 'extra').

I<op>

=head2 flag

Controls Interchange flags. For example, flags affect database access
and transactions for those databases able to support these features.
See also the [tag] tag.

Summary

    [flag type]

 Parameters   Description                               Default
 build        Forces build of static Interchange page specified by the name attributeDEFAULT_VALUE
 checkhtml                                              DEFAULT_VALUE
 commit       Attempts to commit transactions           DEFAULT_VALUE
 flag         Alias for type                            DEFAULT_VALUE
 name         Alias for type                            DEFAULT_VALUE
 read         Flags the table read-only                 DEFAULT_VALUE
 rollback     Attempts to rollback transactions         DEFAULT_VALUE
 show         Normally, the [flag] tag returns nothing to the page. Setting 'show=1' causes the tag to return status, if any.DEFAULT_VALUE
 table        Alias for tables                          DEFAULT_VALUE
 tables       The name of the table to flag'table' is an aliasDEFAULT_VALUE
 transactions Reopens the database in transactions mode if Safe.pm is not active (e.g., in a global subroutine, usertag or [perl global=1] tag). The limitation exists because it is not possible to reopen a database within Safe.pm.DEFAULT_VALUE
 type                                                   DEFAULT_VALUE
 value        The boolean value of the flag             DEFAULT_VALUE
 write        Flags the table writable by default (or read-only if you also set the value=0 attribute)DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [flag type]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->flag(  { type => VALUE_type
}, $body  );

or similarly with positional parameters,

    $Tag->flag(type, $attribute_hash_reference, $body);

Description

The flag tag controls database access and transactions.

If a DBM-based database is to be modified, it must be flagged writable
on the page calling the write tag.

For example, you can call

    [flag type=write value=1 table=products]

to mark the products DBM database writable. B<This must be done
before ANY access to that table.>

Note that SQL databases are always writable if allowed by the SQL
database itself, and in-memory databases will never be written.

Using [flag build] forces static build of a page, even if it
contains dynamic elements.

I<build>

Forces build of static Interchange page specified by the name
attribute

I<checkhtml>

I<commit>

Attempts to commit transactions

I<read>

Flags the table read-only

I<rollback>

Attempts to rollback transactions

I<show>

Normally, the [flag] tag returns nothing to the page. Setting
'show=1' causes the tag to return status, if any.

I<tables>

The name of the table to flag

=over 4

=item *

'table' is an alias

=back

I<transactions>

Reopens the database in transactions mode if I<Safe.pm> is not active
(e.g., in a global subroutine, usertag or [perl global=1] tag). The
limitation exists because it is not possible to reopen a database
within I<Safe.pm>.

I<type>

I<value>

The boolean value of the flag

I<write>

Flags the table writable by default (or read-only if you also set the
value=0 attribute)

=head2 fly-list

Summary

Parameters: B<code base>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [fly-list] FOO [/fly-list]. Nesting: NO

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->fly_list(
        {
         code => VALUE,
         base => VALUE,
        },
        BODY
    )

 OR

    $Tag->fly_list($code, $base, $BODY);
    [fly-list code base]

 Parameters   Description                               Default
 base                                                   DEFAULT_VALUE
 code                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [fly-list code base]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->fly_list(  { base => VALUE_base
                       code => VALUE_code
}, $body  );

or similarly with positional parameters,

    $Tag->fly_list(code,base, $attribute_hash_reference, $body);

Description

Syntax: [fly-list prefix=tag_prefix* code=code*]

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

   [fly-list]
    (contents of flypage.html)
   [/fly-list]

If you place the above around the contents of the demo flypage, in a
file named flypage2.html, it will make these two calls display
identical pages:

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

If you place a [fly-list] tag alone at the top of the page, it will
cause any page to act as a flypage.

By default, the prefix is item, meaning the [item-code] tag will
display the code of the item, the [item-price] tag will display
price, etc. But if you use the prefix, i.e. [fly-list prefix=fly],
then it will be [fly-code]; prefix=foo would cause [foo-code],
etc.

I<base>

I<code>

=head2 fly-tax

Summary

Parameters: B<area>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->fly_tax(
        {
         area => VALUE,
        }
    )

 OR

    $Tag->fly_tax($area);
    [fly-tax area]

 Parameters   Description                               Default
 area                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [fly-tax area]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->fly_tax(  { area => VALUE_area
}, $body  );

or similarly with positional parameters,

    $Tag->fly_tax(area, $attribute_hash_reference, $body);

Description

Builds a tax rate from TAXAREA, TAXRATE, and TAXSHIPPING
I<Variable> values, and the I<SalesTax> directive value.

I<area>

=head2 goto

Skips page content between [goto I<name>] and [label I<name>].
Note that the goto tag is not interpreted in the standard way, and
you cannot use the '$Tag->goto()' Perl syntax. Note also that skipping
endtags with goto will probably break your page.

Summary

    [goto name=label_name if=condition]
        content to skip
    [label name=label_name]

or positionally,

    [goto name if]
        content to skip
    [label name]

 Parameters   Description                               Default
 name         The name set in the corresponding [label] tagnone
 if           Condition for goto. Should evaluate to truth value before tag is parsed.true

 Other_Characteristics             
 Container tag                     No, but you use it like this:[goto name=label_name if=condition]body text[label label_name]
 Has Subtags                       [label] interpreted by goto

B<ASP-like Perl call:>

No Perl call available (Note that this tag is not parsed in the
standard way).

Description

Skips page content between [goto I<name>] and [label I<name>].
Note that the goto tag is not interpreted in the standard way, and
you cannot use the '$Tag->goto()' Perl syntax. Note also that skipping
endtags with goto will probably break your page.

The correspondingly named [label] tag marks the end of the page
content the goto should skip. Note that the [label] tag is not
an end tag, but simply a marker for the end of the text to skip.

B<Technical note (Interchange 4.8): >This tag may not work properly if
you have more than one goto/label pair on a page.



I<name>

This should match the name set in a [label] tag I<after> the goto tag
in the page (i.e., don't create loops).

I<if>

Condition for goto. If the argument to 'if' is true, the tag will
skip the text between the goto and <label>.  Note that the tag
itself does not evaluate the condition. The condition must evaluate to
a true or false value before the goto tag processes it.

For example, this will not execute the goto:

    [set go]0[/set]
    [goto name="there" if="[scratch go]"]

=head2 handling

Summary

Parameters: B<mode>

Positional parameters in same order.

B<The attribute hash reference is passed> to the subroutine after the
parameters as the last argument. B<This may mean that there are
parameters not shown here.>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->handling(
        {
         mode => VALUE,
        }
    )

 OR

    $Tag->handling($mode, $ATTRHASH);

Attribute aliases

            carts ==> cart
            modes ==> mode
            name ==> mode
            tables ==> table
    [handling mode other_named_attributes]

 Parameters   Description                               Default
 carts        Alias for cart                            DEFAULT_VALUE
 mode                                                   DEFAULT_VALUE
 modes        Alias for mode                            DEFAULT_VALUE
 name         Alias for mode                            DEFAULT_VALUE
 tables       Alias for table                           DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [handling mode]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->handling(  { mode => VALUE_mode
}, $body  );

or similarly with positional parameters,

    $Tag->handling(mode, $attribute_hash_reference, $body);

Description

Calculates and inserts handling costs. Accepts the same noformat and
convert arguments as the shipping tag.

I<cart>

I<mode>

I<table>

=head2 harness

Test harness block. Similar to try/catch. Interprets the body text and
checks the return value against expected and explicitly bad cases.

Returns DIED, OK, or NOT OK message along with your result if not the
expected value.

Summary

    [harness other_named_attributes]

 Parameters   Description                               Default
 expected     Tagname for delimiting your expected return value (default "OK")DEFAULT_VALUE
 name         This will appear in your output message (useful for distinguishing harness tags from one another) (default "testnnn")DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [harness]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->harness(  {
}, $body  );

or similarly with positional parameters,

    $Tag->harness(, $attribute_hash_reference, $body);

Description

Test harness block. Similar to try/catch. Interprets the body text and
checks the return value against expected and explicitly bad cases.

Returns DIED, OK, or NOT OK message along with the harness name and
your result if not the expected value.

I<expected>

Tagname for delimiting your expected return value (default "OK")

I<name>

This will appear in your output message (useful for distinguishing
harness tags from one another) (default "testI<nnn>")

=head2 href

Alias for [I<area>] tag.

=head2 html-table

Builds an HTML table

Summary

    [html-table other_named_attributes]

 Parameters   Description                               Default
 columns      Whitespace-delimited list of columns      DEFAULT_VALUE
 delimiter    Line delimiter to use if tag body is delimited text rather than an array reference (default "\t")DEFAULT_VALUE
 fc           HTML attributes for <TD> in the first cellDEFAULT_VALUE
 fr           HTML attributes for <TR> in the first row DEFAULT_VALUE
 record_delim Record delimiter to use if tag body is delimited text rather than an array reference (default "\n")DEFAULT_VALUE
 td           HTML attributes for <TD>                  DEFAULT_VALUE
 th           HTML attributes for <TH>                  DEFAULT_VALUE
 tr           HTML attributes for <TR>                  DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [html-table]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->html_table(  {
}, $body  );

or similarly with positional parameters,

    $Tag->html_table(, $attribute_hash_reference, $body);

Description

Builds an HTML table

I<columns>

Whitespace-delimited list of columns

I<delimiter>

Line delimiter to use if tag body is delimited text rather than an
array reference (default "\t")

I<fc>

HTML attributes for <TD> in the first cell

I<fr>

HTML attributes for <TR> in the first row

I<record_delim>

Record delimiter to use if tag body is delimited text rather than an
array reference (default "\n")

I<td>

HTML attributes for <TD>

I<th>

HTML attributes for <TH>

I<tr>

HTML attributes for <TR>

=head2 if

Summary

Parameters: B<type term op compare>

THIS TAG HAS SPECIAL POSITIONAL PARAMETER HANDLING.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [if] FOO [/if]. Nesting: NO

Invalidates cache: B<YES>

Called Routine:

Called Routine for positional:

B<ASP-like Perl call:>

Not applicable. Any [if ...] call can be better and more efficiently
done with Perl.

Attribute aliases

            base ==> type
            comp ==> compare
            condition ==> compare
            operator ==> op

 Parameters   Description                               Default
 base         Alias for type                            DEFAULT_VALUE
 comp         Alias for compare                         DEFAULT_VALUE
 compare                                                DEFAULT_VALUE
 condition    Alias for compare                         DEFAULT_VALUE
 op                                                     DEFAULT_VALUE
 operator     Alias for op                              DEFAULT_VALUE
 term                                                   DEFAULT_VALUE
 type                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [if type term op compare]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->if(  { compare => VALUE_compare
                 op => VALUE_op
                 term => VALUE_term
                 type => VALUE_type
}, $body  );

or similarly with positional parameters,

    $Tag->if(type,term,op,compare, $attribute_hash_reference, $body);

Description

Named call example: [if type="type" term="field" op="op"
compare="compare"]

Positional call example: [if type field op compare]

negated: [if type="!type" term="field" op="op" compare="compare"]

Positional call example: [if !type field op compare]

Allows conditional building of HTML based on the setting of various
Interchange session and database values. The general form is:

    [if type term op compare]
    [then]
                                If true, this is printed on the document.
                                The [then] [/then] is optional in most
                                cases. If ! is prepended to the type
                                setting, the sense is reversed and
                                this will be output for a false condition.
    [/then]
    [elsif type term op compare]
                                Optional, tested when if fails
    [/elsif]
    [else]
                                Optional, printed when all above fail
    [/else]
    [/if]

The [if] tag can also have some variants:

    [if type=explicit compare=`$perl_code`]
        Displayed if valid Perl CODE returns a true value.
    [/if]

You can do some Perl-style regular expressions:

    [if value name =~ /^mike/]
                                This is the if with Mike.
    [elsif value name =~ /^sally/]
                                This is an elsif with Sally.
    [/elsif]
    [elsif value name =~ /^pat/]
                                This is an elsif with Pat.
    [/elsif]
    [else]
                                This is the else, no name I know.
    [/else]
    [/if]

While named parameter tag syntax works for [if ...], it is more
convenient to use positional calls in most cases. The only exception
is if you are planning on doing a test on the results of another tag
sequence:

    [if value name =~ /[value b_name]/]
        Shipping name matches billing name.
    [/if]

Oops!  This will not work. You must do instead

    [if base=value term=name op="=~" compare="/[value b_name]/"]
        Shipping name matches billing name.
    [/if]

or better yet

    [if type=explicit compare=`
                        $Values->{name} =~ /$Values->{b_name}/
                        `]
        Shipping name matches billing name.
    [/if]

Interchange also supports a limited [and ...] and [or ...] capability:

    [if value name =~ /Mike/]
    [or value name =~ /Jean/]
    Your name is Mike or Jean.
    [/if]

    [if value name =~ /Mike/]
    [and value state =~ /OH/]
    Your name is Mike and you live in Ohio.
    [/if]

If you wish to do very complex AND and OR operations, you will have to
use [if explicit] or better yet embedded Perl/ASP. This allows
complex testing and parsing of values.

There are many test targets available:

I<config Directive>

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

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

I<data database::field::key>

The Interchange 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]

I<discount>

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

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

I<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 I<Variable> values:

    [if type=explicit compare="__MYVAR__"] .. [/if]

However, note that the 'compare' option is equivalent to the
[condition] block in that both evaluate as Perl code. That means you
need to watch out when you put in user-supplied values (so that users
can't inject Perl code on your server) and data from your own
variables or tables which may look different than you expected.

For example, say you're in a loop checking whether at least one of the
fields 'foo' and 'bar' has a value ("true" according to Perl):

    [if type=explicit compare="[loop-param foo][loop-param bar]"]

Most of the time this works fine. But if 'foo' contains a string
beginning with '0', such as '0009', Perl will try to interpret it as
an octal number, where the digit '9' is invalid, resulting in this
unexpected error in the catalog error log:

    Bad if 'explicit   0009': Illegal octal digit '9' at (eval 155) line 1, at end of line

A safer way to check is:

    [if type=explicit compare="q{[loop-param foo][loop-param bar]}"]

Although then your data should not contain a '}'. To be extra safe you
can surround your interpolated data with a [filter X] ... [/filter]
tag pair appropriate for the quoting method you've used.

I<file>

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

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

The file test requires that the I<SafeUntrap> directive contains
ftfile (which is the default).

I<items>

The Interchange 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]

I<ordered>

Order status of individual items in the Interchange 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] Item 99-102 is in your cart. [/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'.

    To make sure it is exactly large, you could use:

  [if ordered 99-102 main size eq 'large'] ... [/if]

I<pragma>

The Interchange Pragma settings, set with the L<catalog.cfg> directive
Pragma or with [pragma name].

    [if pragma dynamic_variables]
    __THE_VARIABLE__
    [else]
    [data table=variable column=Variable key=THE_VARIABLE]
    [/else]
    [/if]

I<scratch>

The Interchange 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]

I<session>

the Interchange session variables. of particular interest are
I<login>, I<frames>, I<secure>, and I<browser>.

I<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 a Luhn-10 calculation
to weed out typos or phony card numbers. Uses the standard
CreditCardAuto variables for targets if nothing else is passed.

I<value>

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

The I<field> term is the specifier for that area. For example, [if
session logged_in] would return true if the logged_in 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 scratch frames]
        __BUTTONBAR_FRAMES__
    [else]
        __BUTTONBAR__
    [/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 I<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 non-equivalence

Any simple perl test can be used, including some limited regex
matching. More complex tests are best done with [if explicit].

[then] text [/then]

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

[elsif type field op* compare*]

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

Additional conditions for test, applied if the initial [if ..] test
fails.

[else] text [/else]

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

[condition] text [/condition]

Only used with the [if explicit] tag. Allows an arbitrary expression
B<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 [I<perl>] construct.

I<compare>

I<op>

I<term>

I<type>

=head2 import

Summary

Parameters: B<table type>

Positional parameters in same order.

B<The attribute hash reference is passed> after the parameters but
before the container text argument. B<This may mean that there are
parameters not shown here.>

Interpolates B<container text> by default.

This is a container tag, i.e. [import] FOO [/import]. Nesting: NO

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->import(
        {
         table => VALUE,
         type => VALUE,
        },
        BODY
    )

 OR

    $Tag->import($table, $type, $ATTRHASH, $BODY);

Attribute aliases

            base ==> table
            database ==> table
    [import table type other_named_attributes]

 Parameters   Description                               Default
 base         Alias for table                           DEFAULT_VALUE
 database     Alias for table                           DEFAULT_VALUE
 table                                                  DEFAULT_VALUE
 type                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [import table type]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->import(  { table => VALUE_table
                     type => VALUE_type
}, $body  );

or similarly with positional parameters,

    $Tag->import(table,type, $attribute_hash_reference, $body);

Description

Named attributes:

    [import table=table_name
            type=(TAB|PIPE|CSV|%%|LINE)
            continue=(NOTES|UNIX|DITTO)
            separator=c]

Import one or more records into a database. The type is any of the
valid Interchange delimiter types, with the default being defined by
the setting of the database I<DELIMITER>. The table must already be a
defined Interchange database table; it cannot be created on the fly.
(If you need that, it is time to use SQL.)

The type of LINE and continue setting of NOTES is
particularly useful, for it allows you to name your fields and not
have to remember the order in which they appear in the database. The
following two imports are identical in effect:

    [import table=orders]
    code: [value mv_order_number]
    shipping_mode: [shipping-description]
    status: pending
    [/import]

    [import table=orders]
    shipping_mode: [shipping-description]
    status: pending
    code: [value mv_order_number]
    [/import]

The code or key must always be present, and is always named
code.

If you do not use NOTES mode, you must import the fields in the
same order as they appear in the ASCII source file.

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

I<table>

I<type>

=head2 include

Summary

Parameters: B<file locale>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

Not applicable.

    [include file locale]

 Parameters   Description                               Default
 file                                                   DEFAULT_VALUE
 locale                                                 DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [include file locale]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->include(  { file => VALUE_file
                      locale => VALUE_locale
}, $body  );

or similarly with positional parameters,

    $Tag->include(file,locale, $attribute_hash_reference, $body);

Description

Same as [file name] except interpolates for all Interchange tags
and variables. Does NOT do locale translations.

I<file>

I<locale>

=head2 index

Creates an index for the specified table.

Summary

    [index table other_named_attributes]

 Parameters   Description                               Default
 base         Alias for table                           DEFAULT_VALUE
 basefile     Database filename. Exports the table to this filename if old or missing before indexing. See also the export tag for additional relevant attributes such as delimiter type, etc.DEFAULT_VALUE
 col          alias for fields                          DEFAULT_VALUE
 columns      alias for fields                          DEFAULT_VALUE
 database     Alias for table                           DEFAULT_VALUE
 export_only  Just do the export if necessary (not the index).DEFAULT_VALUE
 extension    Index file extension (default "idx")      DEFAULT_VALUE
 fields       field(s) to index                         DEFAULT_VALUE
 fn           alias for fields                          DEFAULT_VALUE
 show_status  Return '1' to the page if successful      DEFAULT_VALUE
 spec         The index specification                   DEFAULT_VALUE
 table                                                  DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [index table]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->index(  { table => VALUE_table
}, $body  );

or similarly with positional parameters,

    $Tag->index(table, $attribute_hash_reference, $body);

Description

Creates an index for the specified table.

I<basefile>

Database filename. Exports the table to this filename if old or
missing before indexing. See also the export tag for additional
relevant attributes such as delimiter type, etc.

I<col>

alias for fields

I<columns>

alias for fields

I<export_only>

Just do the export if necessary (not the index).

I<extension>

Index file extension (default "idx")

I<fields>

field(s) to index

I<fn>

alias for fields

I<show_status>

Return '1' to the page if successful

I<spec>

The index specification

I<table>

=head2 item-list

Summary

Parameters: B<name>

B<The attribute hash reference is passed> after the parameters but
before the container text argument. B<This may mean that there are
parameters not shown here.>

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [item-list] FOO [/item-list]. Nesting:
NO

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    NOTE: This would not usually be used with embedded Perl -- a better
    choice would normally be:

                 for(@$Items) { CODE }

    $Tag->item_list(
        {
         name => VALUE,
        },
        BODY
    )

 OR

    $Tag->item_list($name, $ATTRHASH, $BODY);

Attribute aliases

            cart ==> name
    [item-list name other_named_attributes]

 Parameters   Description                               Default
 cart         Alias for name                            DEFAULT_VALUE
 name                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [item-list name]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->item_list(  { name => VALUE_name
}, $body  );

or similarly with positional parameters,

    $Tag->item_list(name, $attribute_hash_reference, $body);

Description

Within any page, the [item-list cart*] element shows a list of all
the items ordered by the customer so far. It works by repeating the
source between [item-list] and [/item-list] once for each item
ordered.

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

Between the [item-list] markers the following elements will return
information for the current item:

[if-data table column]

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

[if-data ! table column]

Reverses sense for [if-data].

[/if-data]

Terminates an [if-data table column] element.

[if-field fieldname]

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

[if-field ! fieldname]

Reverses sense for [if-field].

[/if-field]

Terminates an [if-field fieldname] element.

[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 I<fieldname> in the arbitrary database
table I<database>, for the current item.

[item-description]

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

In support of OnFly, if the description field is not found in the
database, the description setting in the shopping cart will be used
instead.

[item-field fieldname]

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

[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-last]tags[/item-last]

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

      [item-last][calc]
        return -1 if '[item-field weight]' eq '';
        return 1 if '[item-field weight]' < 1;
        return 0;
        [/calc][/item-last]

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

[item-modifier attribute]

Evaluates to the modifier value of attribute for the current item.

[item-next]tags[/item_next]

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

      [item-next][calc][item-field weight] < 1[/calc][/item-next]

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

[item-price n* noformat*]

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

[item-discount-price n* noformat*]

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

[item-discount]

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

[item-discount_subtotal]

Inserts the discounted subtotal of the ordered items.

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

[item-modifier-name attribute]

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

[quantity-name]

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

I<name>

=head2 label

The page label for goto. See [goto] tag for description.  Note that
this is not a standard tag, but is simply a marker used by goto.

Parameter: B<name>

    [goto name=label_name if=condition]
        content to skip
    [label name=label_name]

Summary

NO SUMMARY SECTION

    [label]

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 No
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [label]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->label(  {
}, $body  );

or similarly with positional parameters,

    $Tag->label(, $attribute_hash_reference, $body);

Description

NO DESCRIPTION SECTION

=head2 log

Log contained text to specified file.

Summary

    [log file other_named_attributes]

 Parameters   Description                               Default
 arg          Alias for file                            DEFAULT_VALUE
 create       Set create=1 to create the file if not presentDEFAULT_VALUE
 delim        Line delimiter                            DEFAULT_VALUE
 file         name of file to log to. 'file=">filename"' also sets 'create' attribute.DEFAULT_VALUE
 hide         Suppress status otherwise returned by tag to the page.DEFAULT_VALUE
 process      Processing (if any) to apply to the content while loggingnostrip (don't strip leading/trailing whitespace and convert "\r\n" to "\n"DEFAULT_VALUE
 record_delim Record delimiter                          DEFAULT_VALUE
 type         Log typetext (ordinary text file)quot (delimited entries)error (add Interchange error formatting and time/location stamps)DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [log file]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->log(  { file => VALUE_file
}, $body  );

or similarly with positional parameters,

    $Tag->log(file, $attribute_hash_reference, $body);

Description

Log contained text to specified file.

I<create>

Set create=1 to create the file if not present

I<delim>

Line delimiter

I<file>

name of file to log to. 'file=">I<filename>"' also sets 'create'
attribute.

I<hide>

Suppress status otherwise returned by tag to the page.

I<process>

Processing (if any) to apply to the content while logging

=over 4

=item *

nostrip (don't strip leading/trailing whitespace and convert "\r\n" to
"\n"

=back

I<record_delim>

Record delimiter

I<type>

Log type

=over 4

=item *

text (ordinary text file)

=item *

quot (delimited entries)

=item *

error (add Interchange error formatting and time/location stamps)

=back

=head2 loop

Summary

Parameters: B<list>

Positional parameters in same order.

B<The attribute hash reference is passed> after the parameters but
before the container text argument. B<This may mean that there are
parameters not shown here.>

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [loop] FOO [/loop]. Nesting: NO

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    NOTE: This would not usually be used with embedded Perl -- a better
    choice would normally be:

                 for(@list) { CODE }

    $Tag->loop(
        {
         list => VALUE,
        },
        BODY
    )

 OR

    $Tag->loop($list, $ATTRHASH, $BODY);

Attribute aliases

            arg ==> list
            args ==> list
    [loop list other_named_attributes]

 Parameters   Description                               Default
 arg          Alias for list                            DEFAULT_VALUE
 args         Alias for list                            DEFAULT_VALUE
 list                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [loop list]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->loop(  { list => VALUE_list
}, $body  );

or similarly with positional parameters,

    $Tag->loop(list, $attribute_hash_reference, $body);

Description

Returns a string consisting of the LIST, repeated for every item in a
comma-separated or space-separated list. Operates in the same fashion
as the [item-list] tag, except for order-item-specific values.
Intended to pull multiple attributes from an item modifier - but can
be useful for other things, like building a pre-ordained product list
on a page.

Loop lists can be nested reliably in Interchange by using the
prefix="tag" parameter. New syntax:

    [loop list="A B C"]
        [loop prefix=mid list="[loop-code]1 [loop-code]2 [loop-code]3"]
            [loop prefix=inner list="X Y Z"]
                [mid-code]-[inner-code]
            [/loop]
        [/loop]
    [/loop]

You can do an arbitrary search with the search="args" parameter, just
as in a one-click search:

    [loop search="se=Americana/sf=category"]
        [loop-code] [loop-field title]
    [/loop]

The above will show all items with a category containing the whole
world "Americana", and will work the same in both old and new syntax.

Ranges are accepted when you pass a list if you set the ranges
option:

    [loop list="A..Z" ranges=1][loop-code] [/loop]

The above lists all of the characters from A to Z. Any Perl
incrementing variable list will work, but most commonly a range would
be something like 1..100. You can mix regular sets -- 1..5 10 20
would produce the list 1 2 3 4 5 10 20.

If you surround the repeating text section with a [list] [/list]
anchor, the more-list, ml=N, and on-match / no-match processing is
done just as in [query] and [search-region].

Using the acclist option will parse Interchange option lists, as
used in product options. The value is available with [loop-code],
the label with [loop-param label]. If the size data for SKU
TS-007 was set to the string S=Small, M=Medium, L=Large, XL=Extra
Large then you could produce a select list of options this way:

    [loop list="[data products size TS-007]" acclist=1]
            [on-match]<SELECT NAME=mv_order_size>[/on-match]
                [list]<OPTION VALUE="[loop-code]"> [loop-param label]</OPTION>[/list]
        [on-match]</SELECT>[/on-match]
    [/loop]

Of course the above is probably more easily produced with
[accessories code=TS-007 attribute=size], but there will be other
uses for the capability. For instance:

         <SELECT NAME=Season>
    [loop acclist=1
                list="
                        Q1=Winter,
                        Q2=Spring,
                        Q3=Summer,
                        Q4=Fall
                "]> <OPTION VALUE="[loop-code]"> [loop-param label]</OPTION>
    [/loop]

If your parameter list needs to have spaces in the parameters,
surround them with double or single quotes and set the quoted=1
option: in product options. If the size data for SKU TS-007 was set
to the string S=Small, M=Medium, L=Large, XL=Extra Large then you
could produce a select list of options this way:

    [loop list="[data products size TS-007]" acclist=1]
            [on-match]<SELECT NAME=mv_order_size>[/on-match]
                [list]<OPTION VALUE="[loop-code]"> [loop-param label]</OPTION>[/list]
        [on-match]</SELECT>[/on-match]
    [/loop]

A nice shortcut is available when using [loop] to generate <OPTION>
lists inside HTML <SELECT>...</SELECT> blocks, when you want the
user's last selection to be chosen by default on subsequent page
views. Interchange simplifies this with functions that output
"SELECTED" (surrounded by appropriate whitespace) for an <OPTION> if a
certain value is set to the <OPTION VALUE="...">. (It sounds more
complicated than it really is.)

For example, consider:

 <select name=search_cat>
[loop
        search="
                fi=cat
                st=db
                ra=yes
                rf=name
                tf=name
                un=1
        "
]
<option[selected search_cat [loop-code]>[loop-code]
[/loop]
</select>

When the user returns to the page, their last selection will be chosen
as the default. (Assuming the value search_cat was set after the
search, which is normally is with standard searches.)

[loop] offers the option attribute, which can give loops that parse
faster and are easier to write. The following example is equivalent to
the one above:

 <select name=search_cat>
[loop
        option=search_cat
        search="
                fi=cat
                st=db
                ra=yes
                rf=name
                tf=name
                un=1
        "
]
<option>[loop-code]
[/loop]
</select>

It works equally well when option values are explicitly specified:

 <option value="[loop-code]">So-called "[loop-code]"

See also the ictemplates documentation in the section "Checks and
Selections."

[if-loop-data table column] IF [else] ELSE [/else][/if-loop-field]

Outputs the IF if the column in table is non-empty, and the ELSE
(if any) otherwise.

See [I<if-PREFIX-data>].

[if-loop-field column] IF [else] ELSE [/else][/if-loop-field]

Outputs the B<IF> if the column in the products table is
non-empty, and the B<ELSE> (if any) otherwise. Will fall through to
the first non-empty field if there are multiple ProductFiles.

See [I<if-PREFIX-field>].

[if-loop-param param] IF [else] ELSE [/else][/if-loop-param]

Only works if you have named return fields from a search (or from a
passed list with the lr=1 parameter).

Outputs the B<IF> if the returned param is non-empty, and the
B<ELSE> (if any) otherwise.

See [if-PREFIX-param].

[if-loop-pos N] IF [else] ELSE [/else][/if-loop-pos]

Only works if you have multiple return fields from a search (or from a
passed list with the lr=1 parameter).

Parameters are numbered from ordinal 0, with [loop-pos 0] being the
equivalent of [loop-code].

Outputs the B<IF> if the returned positional parameter N is
non-empty, and the B<ELSE> (if any) otherwise.

See [if-PREFIX-pos].

[loop-accessories]

Outputs an [accessories ...] item.

See [I<PREFIX-accessories>].

[loop-change marker]

See [I<PREFIX-change>].

[loop-code]

Evaluates to the code for the current item.

See [I<PREFIX-code>].

[loop-data database fieldname]

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

See [I<PREFIX-data>].

[loop-description]

Evaluates to the product description (from the products file, passed
description in on-fly item, or description attribute in cart) for the
current item.

See [I<PREFIX-description>].

[loop-field fieldname]

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

See [I<PREFIX-field>].

[loop-increment]

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

Starts from integer 1.

See [I<PREFIX-increment>].

[loop-last]tags[/loop-last]

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

      [loop-last][calc]
        return -1 if '[loop-field weight]' eq '';
        return 1 if '[loop-field weight]' < 1;
        return 0;
        [/calc][/loop-last]

If this is contained in your [loop list] and the weight field is
empty, then a numerical -1 will be output from the [calc][/calc]
tags; the list will end and the item will B<not> be shown. If the
product's weight field is less than 1, a numerical 1 is output. The
item will be shown, but will be the last item shown.

[loop-next]tags[/loop-next]

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

      [loop-next][calc][loop-field weight] < 1[/calc][/loop-next]

If this is contained in your [loop list] and the product's weight
field is less than 1, then a numerical 1 will be output from the
[calc][/calc] operation. The item will not be shown.

[loop-price n* noformat*]

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

I<list>

=head2 mail

Mail contained text to recipient specified by 'to' using the program
specified with the SendMailProgram catalog directive.

Summary

    [mail to other_named_attributes]

 Parameters   Description                               Default
 extra        Additional headers (these will also be added to 'raw' messages)DEFAULT_VALUE
 hide         Suppress tag return value. This would otherwise be the 'success' attribute setting.DEFAULT_VALUE
 raw          Send it raw without creating headers and checking content, recipient, subject, etc.DEFAULT_VALUE
 show         The tag will return the final message with headers in the pageDEFAULT_VALUE
 success      Tag return value if successful (default is 1).DEFAULT_VALUE
 to                                                     DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<ASP-like Perl call:>

   $Tag->mail(  { to => VALUE_to
}, $body  );

or similarly with positional parameters,

    $Tag->mail(to, $attribute_hash_reference, $body);

Description

Mail contained text to recipient specified by 'to' using the program
specified with the SendMailProgram catalog directive.

I<extra>

Additional headers (these will also be added to 'raw' messages)

I<hide>

Suppress tag return value. This would otherwise be the 'success'
attribute setting.

I<raw>

Send it raw without creating headers and checking content, recipient,
subject, etc.

I<show>

The tag will return the final message with headers in the page

I<success>

Tag return value if successful (default is 1).

I<to>

=head2 mvasp

Executes the ASP-style perl code contained by the tag. The code will
run under the restrictions of the I<Safe> module. This is very similar
to the [perl] tag, except that the standard '<%' and '%>' ASP
delimiters allow you to mix HTML and perl code.

Summary

    [mvasp tables] ASP here [/mvasp]
    [mvasp tables="db1 db2 ..." other_named_attributes] ASP here [/mvasp]

 Parameters   Description                               Default
 tables       Database tables to be made available to ASP Perl codenone
 table        Alias for tables                          none

 Attributes                        Default
 failure                           none
 no_return                         Always true
 subs                              No
 arg="subs"                        Same as subs
 global                            No
 file                              none
 interpolate                       No
 reparse                           No

 Other_Characteristics             
 Invalidates cache                 Yes
 Has Subtags                       <% and %>
 Container tag                     Yes
 Nests                             No

B<Tag expansion example:>

    [mvasp tables="products" failure="ASP Broke <BR>"]
        <P>This is HTML</p>
        <% my $sku = $Values->{code}; %>
        <P>More HTML</p>
        <% my $result = "Looked up SKU $sku. It is a ";
            $result .= $Tag->data('products', 'description', $sku );
            $Document->write( "$result <br>\n" ); %>
        <P>Still more HTML</p>
    [/mvasp]
---
    <P>This is HTML</p>

    <P>More HTML</p>
    Looked up SKU os28044. It is a Framing Hammer <br>

    <P>Still more HTML</p>

See Also

I<perl>, I<Interchange Programming>

Description

Executes the ASP-style perl code contained by the tag. The code will
run under the restrictions of the I<Safe> module. This is very similar
to the [perl no_return=1] tag, except that the standard '<%' and
'%>' ASP delimiters allow you to mix HTML and perl code.

See the perl tag and I<ASP-Like Perl> sections for more detail.

I<tables>

Whitespace-separated list of database tables to make available within
the ASP-Perl code. See perl tag.

I<failure>

The value the tag should return in case the perl code fails the eval.
See perl tag.

I<no_return>

The return value of the perl code is always suppressed. If you want
output from the ASP code sections, you must explicitly write it with
the &HTML or $Document->write() functions.

You can also retrieve the return value of the perl code from the
session hash via [I<data> session mv_perl_result]. See perl tag.

I<subs>

Enable I<GlobalSub> routines (requires catalog directive
AllowGlobal). See perl tag.

I<global>

Turn off I<Safe> protection (requires catalog directive
AllowGlobal). See perl tag.

I<file>

Prepend the contents of the specified file or FileDatabase entry to
the perl code before eval'ing it. See perl tag.

Examples

See the I<ASP-Like Perl> section of I<Interchange Programming>.

=head2 nitems

Returns the total number of items ordered.  Uses the current cart if
none specified.

Summary

    [nitems name]

 Parameters   Description                               Default
 compare      Regular expression the specified qualifier attribute's value must match to be counted. This replaces the truth value comparison.Default: None (uses truth value of the specified qualifier attribute)DEFAULT_VALUE
 name         Cart nameDefault: current cart            DEFAULT_VALUE
 qualifier    An item attribute that must be true in order to count the item.Default: NoneDEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [nitems name]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->nitems(  { name => VALUE_name
}, $body  );

or similarly with positional parameters,

    $Tag->nitems(name, $attribute_hash_reference, $body);

Description

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

I<compare>

Regular expression the specified qualifier attribute's value must
match to be counted. This replaces the truth value comparison.

=over 4

=item *

S<Default:> None (uses truth value of the specified qualifier
attribute)

=back

I<name>

Cart name

=over 4

=item *

S<Default:> current cart

=back

I<qualifier>

An item attribute that must be true in order to count the item.

=over 4

=item *

S<Default:> None

=back

=head2 options

Builds HTML widgets as defined in the options table for selecting
options associated with a given product. This tag handles simple,
matrix or modular options.  See also the accessories tag.

Here is an illustrative example from the 'tools' sample data set of
the foundation S<catalog:>

 ===
    [options code=os28005]
---
    <input type=hidden name=mv_item_option value="logo">
        <SELECT NAME="mv_order_logo">
        <OPTION VALUE="c">Construct Something
        <OPTION VALUE="y" SELECTED>Your Logo</SELECT><BR>
    <input type=hidden name=mv_item_option value="color">
        <INPUT TYPE="radio" NAME="mv_order_color" VALUE="BLK" >&nbsp;Black
        <INPUT TYPE="radio" NAME="mv_order_color" VALUE="BEIGE" >&nbsp;Beige
        <INPUT TYPE="radio" NAME="mv_order_color" VALUE="WHITE" >&nbsp;White<BR>
    <input type=hidden name=mv_item_option value="bristle">
        <SELECT NAME="mv_order_bristle">
        <OPTION VALUE="synthetic">Synthetic
        <OPTION VALUE="camel">Camel Hair</SELECT>
Z<>===

Summary

    [options code]

 Parameters   Description                               Default
 bold         Boldfaces the labels if the 'label' option is set.Default: FalseDEFAULT_VALUE
 code         Product key (usually sku).No default      DEFAULT_VALUE
 joiner       The joiner for the widgets.Default: <BR>  DEFAULT_VALUE
 label        Shows labels for the options with the widgets.The following example (using another item from the 'tools' data) illustrates the price and label attributes:===   [options code=os28011 label=1 price=1]---   Handle<BR>     <input type=hidden name=mv_item_option value="handle">       <SELECT NAME="mv_order_handle">       <OPTION VALUE="W">Wood handle       <OPTION VALUE="E">Ebony handle ($20.00)</SELECT><BR>   Blade material<BR>     <input type=hidden name=mv_item_option value="blade">       <SELECT NAME="mv_order_blade">       <OPTION VALUE="P">Plastic blade ($-1.22)       <OPTION VALUE="S" SELECTED>Steel blade       <OPTION VALUE="T">Titanium blade ($100.00)</SELECT>===(again, the output has been reformatted to fit the page).Default: FalseDEFAULT_VALUE
 price        Boolean. If set and the options have prices, the HTML widget(s) will show the prices. This is like the price attribute of the accessories tag.Note that the price_data setting comes from the 'price' column of the options table.Technical note-- If your options table has different mappings, you can control this with $::Variable->{MV_OPTION_TABLE_MAP}False
 table        Table to use for option attributes.Default: 'options'DEFAULT_VALUE
 td           Results as table rows. For example, compare the following example from the 'tools' sample data set with the earlier example:===   [options code=os28005 td=1]--- <td><input type=hidden name=mv_item_option value="logo">    <SELECT NAME="mv_order_logo">    <OPTION VALUE="c">Construct Something    <OPTION VALUE="y" SELECTED>Your Logo</SELECT></td> <td><input type=hidden name=mv_item_option value="color">    <INPUT TYPE="radio" NAME="mv_order_color"           VALUE="BLK" >&nbsp;Black    <INPUT TYPE="radio" NAME="mv_order_color"           VALUE="BEIGE" >&nbsp;Beige    <INPUT TYPE="radio" NAME="mv_order_color"           VALUE="WHITE" >&nbsp;White</td> <td><input type=hidden name=mv_item_option value="bristle">    <SELECT NAME="mv_order_bristle">    <OPTION VALUE="synthetic">Synthetic    <OPTION VALUE="camel">Camel Hair</SELECT></td>===(Note that the output was reformatted to fit this page)DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [options code]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->options(  { code => VALUE_code
}, $body  );

or similarly with positional parameters,

    $Tag->options(code, $attribute_hash_reference, $body);

Description

NO DESCRIPTION SECTION

I<bold>

Boldfaces the labels if the 'label' option is set.

=over 4

=item *

S<Default:> False

=back

I<code>

Product key (usually sku).

=over 4

=item *

No default

=back

I<joiner>

The joiner for the widgets.

=over 4

=item *

S<Default:> <BR>

=back

I<label>

Shows labels for the options with the widgets.

The following example (using another item from the 'tools' data)
illustrates the price and label S<attributes:>

 ===
   [options code=os28011 label=1 price=1]
---
   Handle<BR>
     <input type=hidden name=mv_item_option value="handle">
       <SELECT NAME="mv_order_handle">
       <OPTION VALUE="W">Wood handle
       <OPTION VALUE="E">Ebony handle ($20.00)</SELECT><BR>
   Blade material<BR>
     <input type=hidden name=mv_item_option value="blade">
       <SELECT NAME="mv_order_blade">
       <OPTION VALUE="P">Plastic blade ($-1.22)
       <OPTION VALUE="S" SELECTED>Steel blade
       <OPTION VALUE="T">Titanium blade ($100.00)</SELECT>
Z<>===

(again, the output has been reformatted to fit the page).

=over 4

=item *

S<Default:> False

=back

I<price>

Boolean. If set and the options have prices, the HTML widget(s) will
show the prices. This is like the price attribute of the
accessories tag.

=over 4

=item

Note that the price_data setting comes from the 'price' column of
the options table.

Technical note-- If your options table has different mappings, you can
control this with $::Variable->{MV_OPTION_TABLE_MAP}

=back

=over 4

=item *

S<Default:> False

=back

I<table>

Table to use for option attributes.

=over 4

=item *

S<Default:> 'options'

=back

I<td>

Results as table rows. For example, compare the following example from
the 'tools' sample data set with the earlier example:

 ===
   [options code=os28005 td=1]
---
   <td><input type=hidden name=mv_item_option value="logo">
      <SELECT NAME="mv_order_logo">
      <OPTION VALUE="c">Construct Something
      <OPTION VALUE="y" SELECTED>Your Logo</SELECT></td>
   <td><input type=hidden name=mv_item_option value="color">
      <INPUT TYPE="radio" NAME="mv_order_color" VALUE="BLK" >&nbsp;Black
      <INPUT TYPE="radio" NAME="mv_order_color" VALUE="BEIGE" >&nbsp;Beige
      <INPUT TYPE="radio" NAME="mv_order_color" VALUE="WHITE" >&nbsp;White</td>
   <td><input type=hidden name=mv_item_option value="bristle">
      <SELECT NAME="mv_order_bristle">
      <OPTION VALUE="synthetic">Synthetic
      <OPTION VALUE="camel">Camel Hair</SELECT></td>
Z<>===

(Note that the output was reformatted to fit this page)

=head2 or

Summary

Parameters: B<type term op compare>

THIS TAG HAS SPECIAL POSITIONAL PARAMETER HANDLING.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine:

Called Routine for positional:

B<ASP-like Perl call:>

    $Tag->or(
        {
         type => VALUE,
         term => VALUE,
         op => VALUE,
         compare => VALUE,
        }
    )

 OR

    $Tag->or($type, $term, $op, $compare);

Attribute aliases

            base ==> type
            comp ==> compare
            operator ==> op
    [or type term op compare]

 Parameters   Description                               Default
 base         Alias for type                            DEFAULT_VALUE
 comp         Alias for compare                         DEFAULT_VALUE
 compare                                                DEFAULT_VALUE
 op                                                     DEFAULT_VALUE
 operator     Alias for op                              DEFAULT_VALUE
 term                                                   DEFAULT_VALUE
 type                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [or type term op compare]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->or(  { compare => VALUE_compare
                 op => VALUE_op
                 term => VALUE_term
                 type => VALUE_type
}, $body  );

or similarly with positional parameters,

    $Tag->or(type,term,op,compare, $attribute_hash_reference, $body);

Description

B<NO Description>

I<compare>

I<op>

I<term>

I<type>

=head2 order

Expands into a hypertext link which will include the specified item in
the list of products to order and display the order page.

Summary

    [order code quantity]Link Text</A>
    [order code=os28044 quantity=2]Link Text</A>

 Parameters   Description                               Default
 code         This is the unique identifier for the item, typically the SKU in the products tablenone
 quantity     Quantity to order                         1

 Attributes                        Default
 code                              No
 page                              SpecialPage order
 cart                              main cart
 base                              ProductFiles array
 area                              off
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 No
 Container tag                     No
 Has end tag                       No ([/order] is a macro for </A>)

B<Tag expansion example:>

    [order os28044 2]Buy Framing Hammer[/order]
---
    <A HREF="http://localhost.localdomain/cgi-bin/tag72/ord/basket?\
    mv_session_id=6CZ2whqo&mv_pc=1&mv_action=refresh&\
    mv_order_item=os28044&mv_order_quantity=3">Buy Framing Hammer</A>

B<ASP-like Perl call:>

    $Tag->order($code, $quantity);

Description

Expands into a hypertext link which will include the specified code in
the list of products to order and display the order page.

B<code> should be a product code listed in one of the "products"
databases. The optional argument B<base> constrains the order to a
particular products file. If not specified, all tables defined as
ProductFiles will be searched in sequence for the item.

The optional argument B<cart> selects the shopping cart where the item
will be placed.

B<page> allows you to specify a different order page than the default
one specified by SpecialPage order.

How to Order an Item

Interchange can either use a form-based order or a link-based order to
place an item in the shopping cart. The order tag creates a
link-based order.

You can use the area tag with form variables if you need more
control, for example, to change frames for the S<order:>

   <A HREF="[area href=ord/basket
                  form="mv_order_item=os28044
                        mv_order_quantity=2
                        mv_action=refresh"]"
    TARGET=newframe> Order Framing Hammer</A>

This can also be done more easily with the area option to the
order tag:

    <A HREF="[order code=os28044 quantity=2 area=1]"
         TARGET=newframe> Order Framing Hammer</A>

To order with a form, you set the form variable mv_order_item to
the item-code/SKU and use the refresh S<action:>

   <FORM ACTION="[process]" METHOD=POST>
   <INPUT TYPE=hidden  NAME="mv_todo"        VALUE="refresh">
   <INPUT TYPE=hidden  NAME="mv_order_item"  VALUE="os28044">

   Order <INPUT NAME="mv_order_quantity" SIZE=3 VALUE=1> Framing Hammer

   <INPUT TYPE=submit VALUE="Order!">
   </FORM>

Groups of items may be batched:

   <FORM ACTION="[process]" METHOD=POST>
   <INPUT TYPE=hidden  NAME="mv_todo"        VALUE="refresh">

   <INPUT TYPE=hidden  NAME="mv_order_item"  VALUE="TK112">
   <INPUT NAME="mv_order_quantity" SIZE=3> Standard Toaster

   <INPUT TYPE=hidden  NAME="mv_order_item"  VALUE="TK200">
   <INPUT NAME="mv_order_quantity" SIZE=3> Super Toaster

   <INPUT TYPE=submit VALUE="Order!">
   </FORM>

Items that have a quantity of zero (or blank) will be skipped. Only
items with a positive quantity will be placed in the basket.

Attributes like size or color may be specified at time of order. See
the accessories tag for detail.

=head2 page

Expands to a hyperlink to an Interchange page or action, including
surrounding <A HREF ...>. The URL within the link includes the
Interchange session ID and supplied arguments. The optional [/page] is
simply a macro for </A>.

If you do not want the <A HREF ...>, use the I<area> tag instead -
these are equivalent:

    [page href=dir/page arg=mv_arg]TargetName</A>
    <A HREF="[area href=dir/page arg=mv_arg]">TargetName</A>

Summary

    [page href arg]
    [page href=dir/page arg=page_arguments other_named_attributes]

 Parameters   Description                               Default
 href         Path to Interchange page or actionSpecial arguments'scan' treats arg as a search argument'http://...' external link (requires form attribute)process
 arg          Interchange arguments to page or action   none
 base         alias for arg                             none

 Attributes                        Default
 extra                             none
 form                              none
 search                            No
 secure                            No
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 No
 Macro                             No
 Has end tag                       No ([/page] is a macro for </A>)

B<Tag expansion example:>

    [page href=dir/page.html arg="arg1=AA/arg2=BB"]

    <a href="www.here.com/cgi-bin/mycatalog/page.html?mv_session_id=6CZ2whqo&\
    mv_pc=1&mv_arg=arg1%3dAA/arg2%3dBB">

B<ASP-like Perl call:>

    $Tag->page(  { href => "dir/page",
                   arg  => "arguments", }  );

or similarly with positional parameters,

    $Tag->page($href, $arg, $attribute_hash_reference);

Using arrayref for joined search (see also I<Attribute Arrays and
Hashes>)

    my $searchref = [ "se=hammer/fi=products/sf=description",
                      "se=plutonium/fi=products/sf=description", ];

    $Tag->page( { href   => 'scan',
                  search => $searchref, } );

See Also

I<area>

Description

The page tag inserts a hyperlink to the specified Interchange page
or action. For example, [page shirts] will expand into

   <a href="http://www.here.com/cgi-bin/mycatalog/shirts?mv_session_id=6CZ2whqo&mv_pc=1">

The catalog page displayed will come from "shirts.html" in the pages
directory.

The additional argument will be passed to Interchange 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 $Session->{arg}. Spaces and some other characters
will be escaped with the %NN HTTP-style notation and unescaped when
the argument is read back into the session.

For better performance, Interchange can prebuild and cache pages that
would otherwise be generated dynamically. If Interchange has built
such a static page for the target, the page tag produces a link to
the cached page whenever the user has accepted and sent back a cookie
with the session ID. If the user did not accept the cookie,
Interchange cannot use the cache, since the link must then include the
I<mv_session_id> argument in order to preserve session.

I<extra>

I<form>

The optional form argument allows you to encode a form in the link.

        [page form="mv_order_item=os28044
                    mv_order_size=15oz
                    mv_order_quantity=1
                    mv_separate_items=1
                    mv_todo=refresh"] Order 15oz Framing Hammer</A>

The two form values I<mv_session_id> and I<mv_arg> are automatically
added when appropriate. The form value I<mv_arg> receives the value of
the tag's arg parameter.

This would generate a form that ordered quantity one of item number
os28044 with size 15oz. The item would appear on a separate line
in the shopping cart, since mv_separate_items is set. Since the
href is not set, you will go to the default shopping cart page -
alternatively, you could have set mv_orderpage=yourpage to go to
yourpage.

All normal Interchange form caveats apply - you must have an action,
you must supply a page if you don't want to go to the default, etc.

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

If the parameter href is not supplied, I<process> is used, causing
normal Interchange form processing.

If the href points to an http:// link, then no Interchange URL
processing will be done, but the URL will include mv_session_id,
mv_pc, and any arguments supplied with the arg attribute:

       [page  href="http://www.elsewhere.net/cgi/script"
              form="cgi_1=ONE
                    cgi_2=TWO"
               arg="Interchange argument"]External link</A>

       <A HREF="http://www.elsewhere.net/cgi/script?\
        mv_session_id=6CZ2whqo&mv_pc=1&mv_arg=Interchange%20argument&\
        cgi_1=ONE&cgi_2=TWO">External link</A>

I<search>

Interchange allows you to pass a search in a URL. There are two ways
to do this:

=over 4

=item 1.

Place the search specification in the named search attribute.

=over 8

=item *

Interchange will ignore the href parameter (the link will be set to
'scan'.

=item *

If you give the arg parameter a value, that value will be available
as [value mv_arg] within the search display page.

=back

=item 2.

Set the href parameter to 'scan' and set arg to the search
specification.

=over 8

=item *

Note that you can use this form positionally - the values go into
href and arg, so you do not have to name parameters.

=back

=back

These are identical:

    [page scan
          se=Impressionists
          sf=category]
        Impressionist Paintings
    </a>

    [page href=scan
          arg="se=Impressionists
               sf=category"]
        Impressionist Paintings
    </A>

    [page search="se=Impressionists
                  sf=category"]
        Impressionist Paintings
    </a>

Here is the same thing from a non-Interchange page (e.g., a home
page), assuming '/cgi-bin/mycatalog' is the CGI path to Interchange's
vlink):

     <A HREF="/cgi-bin/mycatalog/scan/se=Impressionists/sf=category">
        Impressionist Paintings
     </A>

Sometimes, you will find that you need to pass characters that will
not be interpreted positionally. In that case, you should quote the
arguments:

    [page href=scan
          arg=|
                se="Something with spaces"
          |]

See the I<Search and Form Variables> appendix for a listing of the
form variables along with two-letter abbreviations and descriptions.

They can be treated just the same as form variables on the page,
except that they can't contain spaces, '/' in a file name, or quote
marks. These characters can be used in URL hex encoding, i.e. %20 is a
space, %2F is a /, etc. - &sp; or &#32; will not be
recognized. If you use one of the methods below to escape these
"unsafe" characters, you won't have to worry about this.

You may specify a one-click search in three different ways. The first
is as used in previous versions, with the scan URL being specified
completely as the page name. The second two use the "argument"
parameter to the [page ...] or [area ...]> tags to specify the
search (an argument to a scan is never valid anyway).

I<secure>

Original syntax

If you wish to do an OR search on the fields category and artist for
the strings "Surreal" and "Gogh", while matching substrings, you would
do:

 [page scan se=Surreal/se=Gogh/os=yes/su=yes/sf=artist/sf=category]
    Van Gogh -- compare to surrealists
 </a>

In this method of specification, to replace a / (slash) in a file name
(for the sp, bd, or fi parameter) you must use the shorthand of ::,
i.e. sp=results::standard. (This may not work for some browsers, so
you should probably either put the page in the main pages directory or
define the page in a search profile.)

Ampersand syntax

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

 [page scan se="Van Gogh"&sp=lists/surreal&os=yes&su=yes&sf=artist&sf=category]
    Van Gogh -- compare to surrealists
 </a>

Any "unsafe" characters will be escaped.

Multi-line syntax

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

    [page scan
        se="Van Gogh"
        sp=lists/surreal
        os=yes
        su=yes
        sf=artist
        sf=category
    ] Van Gogh -- compare to surrealists </a>

Any "unsafe" characters will be escaped. You may not search for
trailing spaces in this method; it is allowed in the other notations.

Joined searches

You can also specify a joined search using an attribute array (see
S<I<Attribute Arrays and Hashes>):>

    [page href=scan
      search.0="se=fragrant
                fi=products
                sf=smell"
      search.1="se=purple
                sf=color"
      search.2="se=perennial
                sf=type"]

The search routine called by the page tag automatically adds the other
relevant search specification elements, including the 'co=yes' to
indicate a combined search (I<joined searches> are described in the
Interchange database documentation).

[/page]

This is not an actual end tag, but simply a macro that expands to
</A>. The following two lines are equivalent:

  [page shirts]Our shirt collection[/page]
  [page shirts]Our shirt collection</A>

Tip: In large pages, just use the </A> tag for a small performance
improvement.

=head2 perl

Executes the perl code contained by the tag. The code will run under
the restrictions of Perl's I<Safe> module by default. The tag expands
to the value returned by the enclosed code (i.e., printing to STDOUT
or STDERR is useless).

See also I<Interchange Programming>.

Summary

    [perl tables] Code here [/perl]
    [perl tables="db1 db2 ..." other_named_attributes] Code here [/perl]

 Parameters   Description                               Default
 tables       Database tables to be made available to ASP Perl codenone
 table        Alias for tables                          none

 Attributes                        Default
 failure                           none
 no_return                         No
 subs                              No
 arg="subs"                        Same as subs
 global                            No
 file                              none
 number_errors                     none
 eval_label                        none
 short_errors                      none
 trim_errors                       none
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 Yes
 Has Subtags                       No
 Container tag                     Yes

B<Tag expansion example:>

    [perl tables="products" failure="Perl code error <BR>"]
     my $result = "Looked up SKU $Values->{code}. It is a ";
     $result .= $Tag->data('products', 'description', $Values->{code} );
     return ("$result <br>\n");
    [/perl]
---
    Looked up SKU os28044. It is a Framing Hammer <br>

B<ASP-like Perl call:> (e.g., to use it like a runtime eval() within
your code)

    $Tag->perl(  { tables  => "products", },
                 $code  );

or similarly with positional parameters,

    $Tag->perl( $tables, $attribute_hash_reference );

See Also

See also I<Interchange Programming>, [calc], and [mvasp].

Description

This tag allows you to embed perl code within an Interchange page. The
code will run under the restrictions of Perl's I<Safe> module by
default. Perl's 'warnings' and 'strict' pragmas are both turned
off, and I<Safe> will block you from turning them on, since it blocks
Perl's 'use' command. (This is not usually a problem, since you
should probably use an alternative such as a usertag if your code is
complex enough to need strict.)

The tag expands to the value returned by the enclosed code (i.e.,
printing to STDOUT or STDERR is useless).

    [perl]
        $name    = $Values->{name};
        $browser = $Session->{browser};
        return "Hi, $name! How do you like your $browser?
    [/perl]

Object references are available for most Interchange tags and
functions, as well as direct references to Interchange session and
configuration values.

 Object                            Description
 $CGI->{key}                       Hash reference to raw submitted values
 $CGI_array->{key}                 Arrays of submitted values
 $Carts->{cartname}                Direct reference to shopping carts
 $Config->{key}                    Direct reference to $Vend::Cfg
 $DbSearch->array(@args)           Do a DB search and get results
 $Document->header()               Writes header lines
 $Document->send()                 Writes to output
 $Document->write()                Writes to page
 $Scratch->{key}                   Direct reference to scratch area
 $Session->{key}                   Direct reference to session area
 $Tag->tagname(@args)              Call a tag as a routine (UserTag too!)
 $TextSearch->array(@args)         Do a text search and get results
 $Values->{key}                    Direct reference to user form values
 $Variable->{key}                  Config variables (same as $Config->{Variable});
 &HTML($html)                      Same as $Document->write($html);
 &Log($msg)                        Log to the error log

For full descriptions of these objects, see I<Interchange Perl
Objects>.

I<tables>

This should be a whitespace-separated list of database tables you want
to make available within the Perl code.

If you wish to use database values in your Perl code, the tag must
pre-open the table(s) you will be using. Here is an example using the
products S<table:>

    [perl tables=products]
        my $cost = $Tag->data('products', 'our_cost', $Values->{code});
        $min_price = $cost * ( 1 + $min_margin );
        return ($min_price > $sale_price) ? $min_price : $sale_price;
    [/perl]

If you do not do this, your code will fail with a runtime I<Safe>
error when it tries to look up 'our_cost' in the products database
with the data tag.

Even if you properly specify the tables to pre-open, some database
operations will still be restricted because Safe mode prohibits
creation of new objects. For SQL, most operations can be performed if
the Safe::Hole module is installed. Otherwise, you may have to set
the global=1 attribute to use data from SQL tables.

Interchange databases can always be accessed as long as they are
pre-opened by using an item first.

Technical note:

I<Safe> objects (including database handles) may persist within a
page, and the perl tag does not necessarily destroy objects created
earlier in the page. As a result, your code may work even though you
did not set 'tables' properly, only to break later when you change
something elsewhere on the page.

For example, this will work because the first call to [accessories
...] opens the (default) products table:

    [accessories code=os28044 attribute=size]

    [perl]
        return $Tag->accessories( { attribute => 'size',
                                    code      => 'os28085' } );
    [/perl]

If you remove the first [accessories ...] tag, then the
$Tag->accessories call will fail with a I<Safe> error unless you also
set 'tables=products' in the perl tag.

The moral of this story is to ensure that you pass all necessary
tables in the perl tag.

I<failure>

If your code contains a compile or runtime error and fails to evaluate
(i.e., eval($code) would set $@), the tag will return the value set
for the failure attribute. The error will be logged as usual.

For example,

    [perl failure="It Broke"]
        my $cost = $Tag->data('products', 'our_cost', $Values->{code});
        $min_price = $cost * ( 1 + $min_margin );
        return ($min_price > $sale_price) ? $min_price : $sale_price;
    [/perl]

will return 'It Broke' because the $Tag->Data(...) call will fail
under the I<Safe> module (see I<tables> above).

I<no_return>

If no_return=1, this attribute suppresses the return value of the
perl code.

You can retrieve the return value from the session hash via [I<data>
session mv_perl_result] until it gets overwritten by another perl
tag.

If no_return is set, the perl tag I<will> return any output
explicitly written with the &HTML or $Document->write() functions.

B<Note: >

If no_return is I<not> set, then the $Document->write() buffer is
not returned (unless you use $Document->hot(1) or $Document->send(),
in which case the contents of the write buffer will probably appear
before anything else on the page). See I<Interchange Perl Objects> for
more detail.



Here is an example:

    [perl tables=products no_return=1]
        my $cost = $Tag->data('products', 'our_cost', $Values->{code});
        $min_price = $cost * ( 1 + $min_margin );
        &HTML( ($min_price > $sale_price) ? $min_price : $sale_price );
        return ($min_price > $sale_price) ? 'too low' : 'ok';
    [/perl]

This will put the same price on the page as our earlier example, but

$Session-E<gt>{mv_perl_result} will be either 'too low' or 'ok'.

The [mvasp] tag is very similar to [perl no_return=1].

I<subs>

If you have set the AllowGlobal catalog directive, setting
subs=1 will enable you to call I<GlobalSub> routines within the
enclosed perl code. Note that this can compromise security.

I<global>

If you have set the AllowGlobal catalog directive, setting
global=1 will turn off I<Safe> protection within the tag.

The code within the tag will then be able to do anything the user ID
running Interchange can. This seriously compromises security, and you
should know what you are doing before using it in a public site. It is
especially dangerous if a single Interchange server is shared by
multiple companies or user IDs.

Also, full 'use strict' checking is turned on by default when in
global mode. You can turn it off by using 'no strict;' within your
code. Note that any strict errors will go to the Interchange error
logs, and the tag itself will fail silently within the page.

I<file>

This prepends the contents of the specified file or FileDatabase
entry to the enclosed perl code (if any), then executes as usual.

For example,

    [perl file="my_script.pl"][/perl]

would execute myscript.pl and expand to its return value.

Absolute filenames (or filenames containing '../') are prohibited by
the NoAbsolute catalog directive.

If the filename is not absolute, Interchange first looks for a file in
the current directory, then in the list set with the TemplateDir
catalog directive. If it fails to find a file by that name, it then
looks for an entry by that name in the database specified with the
FileDatabase catalog directive.

I<file>

Add line numbers to the source code displayed in the error.log,
amazingly useful if some of the perl is being generated elsewhere and
interpolated.

I<eval_label>

Set to a string, will replace the (eval ###) in the error message with
this label, handy to quickly track down bugs when you have more than
one perl block in the page, especially if you are using
I<short_errors>.

I<short_errors>

If set to a true value, syntax errors and the like in perl tags will
log just the error, not the whole source code of the block in
question, handy when you have the code open in an editor anyway and
don't want the error itself to get scrolled away when running 'tail -f
error.log'.

I<trim_errors>

If set to a number, and the error produced includes a line number,
then only that number of lines before and after the broken line itself
will be displayed, instead of the whole block.

=head2 price

Summary

Parameters: B<code>

Positional parameters in same order.

B<The attribute hash reference is passed> to the subroutine after the
parameters as the last argument. B<This may mean that there are
parameters not shown here.>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->price(
        {
         code => VALUE,
        }
    )

 OR

    $Tag->price($code, $ATTRHASH);

Attribute aliases

            base ==> mv_ib
    [price code other_named_attributes]

 Parameters   Description                               Default
 base         Alias for mv_ib                           DEFAULT_VALUE
 code                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [price code]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->price(  { code => VALUE_code
}, $body  );

or similarly with positional parameters,

    $Tag->price(code, $attribute_hash_reference, $body);

Description

Arguments:

        code       Product code/SKU
        base       Only search in product table *base*
        quantity   Price for a quantity
        discount   If true(1), check discount coupons and apply
        noformat   If true(1), don't apply currency formatting

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

Interchange maintains a price in its database for every product. The
price field is the one required field in the product database - it is
necessary to build the price routines.

For speed, Interchange builds the code that is used to determine a
product's price at catalog configuration time. If you choose to change
a directive that affects product pricing you must reconfigure the
catalog.

Quantity price breaks are configured by means of the I<CommonAdjust>
directive. There are a number of CommonAdjust recipes which can be
used; the standard example in the demo calls for a separate pricing
table called pricing. Observe the following:

   CommonAdjust  pricing:q2,q5,q10,q25, ;products:price, ==size:pricing

This says to check quantity and find the applicable column in the
pricing database and apply it. In this case, it would be:

    2-4      Column *q2*
    5-9      Column *q5*
    10-24    Column *q10*
    25 up    Column *q25*

What happens if quantity is one? It "falls back" to the price that is
in the table products, column price.

After that, if there is a size attribute for the product, the column
in the pricing database corresponding to that column is checked for
additions or subtractions (or even percentage changes).

If you use this tag in the demo:

    [price code=99-102 quantity=10 size=XL]

the price will be according to the q10 column, adjusted by what is
in the XL column. (The row is of course 99-102.) The following entry
in pricing:

  code    q2   q5   q10  q25  XL
  99-102  10   9    8    7    .50

Would yield 8.50 for the price. Quantity of 10 in the q10 column,
with 50 cents added for extra large (XL).

Following are several examples based on the above entry as well as
this the entry in the products table:

  code    description   price    size
  99-102  T-Shirt       10.00    S=Small, M=Medium, L=Large*, XL=Extra Large

NOTE: The examples below assume a US locale with 2 decimal places, use
of commas to separate, and a dollar sign ($) as the currency
formatting.

  TAG                                          DISPLAYS
  ----------------------------------------     --------
  [price 99-102]                               $10.00
  [price code="99-102"]                        $10.00
  [price code="99-102" quantity=1]             $10.00
  [price code="99-102" noformat=1]             10
  [price code="99-102" quantity=5]             $9.00
  [price code="99-102" quantity=5 size=XL]     $9.50
  [price code="99-102" size=XL]                $10.50
  [price code="99-102" size=XL noformat=1]     10.5

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

Adding [discount 99-102] $s * .9[/discount] deducts 10% from the price
at checkout, but the price tag will not show that unless you add the
discount=1 parameter.

    [price code="99-102"]            -->   $10.00
    [price code="99-102" discount=1] -->   $9.00

See I<Product Discounts>.

I<base>

I<code>

=head2 process

This is a shortcut for the 'process' action, expanding to your catalog
URL and session ID. It is analogous to the area tag for the
'process' page, but is more limited. The following expansion is
S<illustrative:>

    [process target=targetframe]
---
    http://www.here.com/cgi-bin/mycatalog/process.html?\
    id=6CZ2whqo" TARGET="targetframe

(the trailing backslash indicates continuation, i.e., the result
should be only one line)

Note the mismatched quotes in the expansion.  Your surrounding HTML
should supply the containing quotes, like S<this:>

   <A HREF="[process target=targetframe]">...

Aliases:  B<process_target>, B<process_order>

Summary

    [process target secure]
    [process target=targetframe secure=1 other_named_attributes]

 Parameters   Description                               Default
 target       The target frame or window                None
 secure       Boolean.  If true (secure=1), the URL will link to your secure server.No

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 No
 Container tag                     No

B<Tag expansion example:>

    [process targetframe 1]
---
    http://secure.here.com/cgi-bin/mycatalog/process.html?\
    id=6CZ2whqo" TARGET="targetframe

B<ASP-like Perl call:>

    $Tag->process(  { target => 'frametarget',
                      secure => 1, } );

or similarly with positional parameters,

    $Tag->process($target, $secure, $attribute_hash_reference);

=head2 process-search

This is an exact alias for [area<C search>].

=head2 query

Passes SQL statements through to SQL databases, or allows SQL queries
via Interchange's database abstraction into non-SQL databases and text
files. The latter requires the Perl I<SQL Statement> module (included
with Bundle::Interchange from CPAN).

Summary

    [query sql]
    [query sql="SQL_query_text" other_named_attributes]

 Parameters   Description                               Default
 sql          The SQL statement.Passed directly through to an SQL database.For a non-SQL table, the tag interprets your SQL first. See the SQL Statement module for limitations and detail.none
 query        Alias for sql                             none

 Attributes                        Default
 table                             products
 base (alias for table)            products
 type (row_count, html, list, textref)none: uses arrayref="" if no type
 arrayref                          arrayref="" if no type given
 hashref                           none
 more (type=list)                  No
 xx form var. abbrev. (type=list)  see form variable
  (type=list)                      sql
 list_prefix (type=list)           list
 random (type=list)                No
 safe_data (type=list)             No
 label (type=list)                 current
 form (type=list)                  none
 wantarray                         No
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 No
 Container tag                     Yes
 Has subtags                       Yes
 Nests                             No

B<Tag usage example:>

This will list sku, description and price for ten products per page,
followed by hyperlinks to the other pages of the list. Note that you
may interpolate Interchange tags in the usual way if you double-quote
the SQL statement.

    [query sql="select sku, description, price from products where price < [value mv_arg]"
         type=list
         more=1
           ml=10]

      [on_match]Matched<br>[/on_match]
      [no_match]Not Found<br>[/no_match]

      [list]
        [sql-code] [sql-param description] [sql-price]
      [/list]

      [more_list]
        Matches [matches] of [match-count] shown.<BR>
        [more]
      [/more_list]
    [/query]

B<ASP-like Perl call:>

   my $sql = "select * from products order by price";
   my $result_array = $Tag->query( { sql => $sql,  },
                                   $body );
   my ($same_results, $col_name_hash, $col_name_array) =
                      $Tag->query( { sql => $sql,  },
                                   $body );

   my $result_hasharray = $Tag->query( { sql     => $sql,
                                         hashref => 'my_results',  },
                                       $body );

or similarly with positional parameters,

    $Tag->query( $sql, $attribute_hash_reference, $body);

Description

The query tag allows you to make SQL queries. If you are using an
SQL database table, the tag will pass your SQL statement directly to
the database and return the result.

If your table is not in an SQL database (for example, GDBM, text,
LDAP, and in-memory tables), Interchange will internally convert it to
an Interchange search specification with the Perl I<SQL Statement>
module (included with Bundle::Interchange from CPAN). This means that
you can use simple SQL queries regardless of the underlying database
implementation.

I<Subtags>

For list queries (type=list), the following subtags are available:

 Subtag                            Usage
 on_match                           [on_match]   do this if something matched [/on_match]
 no_match                           [no_match]   do this if nothing matched [/no_match]
 list                               [list_prefix]   do this for each matched item [/list_prefix]The 'list' subtag defines a region where you can use any of the looping subtags that work in array-list context (see Looping tags and Sub-tags).The default looping tag prefix will be 'sql'. Note however that you can override this by setting the prefix attribute in the enclosing query tag.Similarly, the list_prefix attribute renames the [list] subtag itself to the value you set (see list_prefix below).
 more_list                          [more_list]   [more] [/more_list]The 'more_list' and 'more' subtags are used when paginating the query results (see 'more' attribute). The [more] subtag will expand to a list of links to the other pages of the query results.

See also the example at the end of the Summary section above.

Perl and ASP usage

If you are calling $Tag->query within a perl tag (or whenever the
code is secured by the I<Safe.pm> module), you must be sure to set the
tables attribute properly in the enclosing perl tag (see the
perl tag documentation for detail).

The I<types> that return text to a page (i.e., row_count, html, and
textref) work as usual, returning an appropriate string. Note that you
may also have access to the results as an array reference in
$Vend::Interpolate::Tmp->{''} for the life of the page.

If you do not set a I<type>, the tag will return a reference to an
array of array references, since the default with no I<type> is
arrayref="".

If you call $Tag->query in scalar context and set I<arrayref> or
I<hashref>, it will return your results as a reference to an array of
either arrayrefs or hashrefs, respectively (i.e., the same data
structures you would get from Perl's DBI.pm module with
fetchall_arrayref).

In list context, the first returned element is the aforementioned
reference to your results. The second element is a hash reference to
your column names, and the third element is an an array reference to
the list of column names.

The following examples should be S<illustrative:>

  [perl tables=products]
    my $sql = "select sku, price, description from products
               where price < 10 order by price";

    my $results = $Tag->query( { sql => $sql, } );
    my ( $same_results, $col_name_hashref, $col_name_arrayref)
        = $Tag->query( { sql => $sql, } );

    my $hash_results = $Tag->query( {     sql => $sql,
                                      hashref => 'my_results' } );

    # $Vend::Interpolate::Tmp->{my_results} == $hash_results
    # $Vend::Interpolate::Tmp->{''} == $results == $same_results

    my $out = "The returned structure is\n";
        $out .= $Tag->uneval( $results );

    #loop through each row & display the fields
    foreach my $row (@$hash_results) {
       $out .= '<p>sku: ' . $row->{sku}
           $out .= '<br>price: ' . $row->{price};
           $out .= '<br>description: ' . $row->{description};
    }
    return $out;

  [/perl]

B<Technical Note: >The $Tag->query() call works a bit differently in
GlobalSubs and UserTags than within a perl tag.  Specifically, in a
GlobalSub or global UserTag, if you call query() in list context and
want the three references (i.e., results, column hash and column
array), then you need to set the 'I<wantarray>=1' attribute in the
query() call.  See the I<wantarray> attribute.



I<sql>

This is the text of your SQL statement. The standard Interchange
quoting rules apply. For example, use double quotes (") if you want to
interpolate Interchange tags within your SQL statement, backticks (`)
to calculate a value, I<etc.>

    [query sql="select description, price from products
               where price < [value mv_arg]" ...]
        ...
    [/query]

I<table>

The table attribute sets the database to use for the query. The
default will typically be the database containing the 'products'
table (unless you have changed the first entry in
$Vend::Cfg->{ProductFiles}).

I<type>

If you are not setting the 'arrayref' or 'hashref' attributes,
then the type attribute defines the way the query will return its
results. The type should be one of the S<following:>

 Type                              Returns
 html                              The html type returns the results in an html table. You will need to supply the enclosing <TABLE ...> and </TABLE> html tags. The following is an example of typical usage: <TABLE>   [query sql="select * from products               where price > 12               order by price"         type=html]   [/query] </TABLE>
 list                              This allows you to use subtags to control the query output and pagination. See the Subtags section above for detail.
 row_count                         This causes the tag to return the number of rows in the query result.
 textref                           This causes the tag to return a the query results as a serialized array of arrays that Perl can evaluate with its eval() function. Here is an illustrative example:  my $rows = eval( $Tag->query( { sql  => "select * from products"                                  type => "textref" } )                 );  my $r3_c0 = $rows->[3]->[0];

If you do not specify a type, the tag will create an arrayref as if
you had set 'arrayref=""'.

I<arrayref and hashref>

If you set 'arrayref=I<keyname>' or 'hashref=I<keyname>', the
query will not return results to the page. Instead, it will place the
results of your query in the $Vend::Interpolate::Tmp hash. Using
'arrayref=my_query' sets $Vend::Interpolate::Tmp->{my_query} to
refer to an array of array references, while 'hashref=my_query'
creates an array of hash references.

Note that this is useful only if you intend to access the results
within Perl code (for example, within a [perl] tag), since there is
no direct output to the returned page.

The $Vend::Interpolate::Tmp hash persists only for the life of the
template page being processed. If you need the query results array
reference to outlive the page, you will have to save the reference
somewhere more persistent such as the $Session S<hash:>

   $Session->{my_query} = $Vend::Interpolate::Tmp->{my_query};

Beware the impact on performance if you do this with large result
sets.

Technical note - the string returned by the 'textref' type will
B<eval>() to the 'arrayref' data structure.

I<more>

Requires 'type=list'.

You must set more=1 to properly paginate your results from list
queries (see 'type=list' above. If you do not set more=1, then
the links to later pages will merely redisplay the first page of your
results.

I<form variable abbreviations>

Requires 'type=list'.

See the I<Search and Form Variables> appendix for a list of form
variables. Note that you must use the two-letter abbreviation rather
than the full form variable name.

A few deserve special S<mention:>

 Abbr                  Name                    Description
 ml                    mv_matchlimit           Sets number of rows to return. If paginating (more=1), sets rows returned per page.
 fm                    mv_first_match          Start displaying search at specified match
 sp                    mv_search_page          Sets the page for search display
 st                    mv_searchtype           Forces a specific search type (text, glimpse, db or sql), overriding the default determined from your database implementation.

I<>

Requires 'type=list'.

Setting 'prefix=foo' overrides the default prefix of 'sql' for loop
subtags within a list region (see I<Looping tags and Sub-tags>).

See the I<list_prefix> attribute below for an illustrative example.

I<list_prefix>

Requires 'type=list'.

Setting 'list_prefix=bar' overrides the default region tagname of
'list'. The best way to show this is by example. Compare the following
two examples of list queries, the first using the defaults and the
second with explicitly set prefix and list_prefix.

    [query sql="select sku, description, price from products
               where price < 20"
         type=list
         more=1
           ml=10]

      [on_match]Matched<br>[/on_match]
      [no_match]Not Found<br>[/no_match]

      [list]
        [sql-code] [sql-param description] [sql-price]
      [/list]

      [more_list]
        [more]
      [/more_list]
    [/query]
---
    [query  sql="select sku, description, price from products
                where price < 20"
           type=list
         prefix=foo
    list_prefix=bar
           more=1
             ml=10]

      [on_match]Matched<br>[/on_match]
      [no_match]Not Found<br>[/no_match]

      [bar]
        [foo-code] [foo-param description] [foo-price]
      [/bar]

      [more_list]
        [more]
      [/more_list]
    [/query]

I<random>

Requires 'type=list'.

You can use the 'random' attribute to randomly select a set of rows
from the whole result set of your query. In other words, setting
'random=I<n>', where I<n> > 0, causes the [list] region to loop
over I<n> randomly chosen rows rather than the full query result set.

The example below would display three randomly chosen products priced
under 20.

    [query sql="select * from products
               where price < 20"
         type=list
       random=3]

      [list]
        [sql-code] [sql-param description] [sql-price]
      [/list]

    [/query]

I<safe_data>

Requires 'type=list'.

Note - you should not set this unless you need it and know what you
are doing.

Setting 'safe_data=1' allows the [sql-data] tag to return values
containing the '[' character. See also I<Looping tags and Sub-tags>.

Beware of reparsing issues.

I<label>

Requires 'type=list'.

If you are setting up multiple simultaneously active search objects
within a page, this allows you to distinguish them. The default label
is 'current'. Most people will not need this.

I<form>

Requires 'type=list'.

You can use this to pass one CGI form variable in the pagination links
of a [more-list]. For example, 'form="foo=bar"' to include
'&foo=bar' in the URL of each of the pagination links.

Note that the variable will not be available in the initial result set
since the query returns the first page directly (i.e., you did not
follow a pagination link).

I<wantarray>

This is relevant only when calling $Tag->query( ... ) within global
Perl code such as a globalsub or global usertag where $MVSAFE::Safe is
not defined. In these cases, setting 'wantarray=1' allows the call
to

  $Tag->query( { wantarray => 1, ... }, ... );

to return references as it would if called within an ordinary
[perl] tag. Note that it does not force list context if you call
$Tag->query in scalar context.

Here is another example of the use of the array references, from a
UserTag:

    my $sku = 'os28044';
    my $sql = qq{select description, price from products where sku = '$sku'};
    my $table = 'products';

    my ($results, $col_name_hashref, $col_name_arrayref) = $Tag->query({
            wantarray => 1,
            sql => "$sql",
            table => "$table"});

    my $out;

    # this will get the first field (description)..
    $out = 'description: ' . $results->[0]->[0];

    # and this the second field (price)..
    $out .= '<br>price: ' . $results->[0]->[1];

    # this will tell us the position in the $results array of the price field..
    $out .= '<br>position of price field: ' . $col_name_hashref->{price};
    return $out;

If the [query] returns more than one row, the second row's description
field would be:

    $results->[1]->[0]

Technical note - the ordinary [query ...] ... [/query] usage
forces scalar context on the query call and suppresses the return
value for those types that would return references if $Tag->query
were called within a [perl] tag. The wantarray option is needed
because global subs and usertags are also affected by this unless you
set wantarray.

Example of a nested query:

    [query
        ml=99
        type=list
        sp="@@MV_PAGE@@"
        sql=|
            SELECT  foo1, foo2, foo3
            FROM    bar
            WHERE   someothercol = 'bang'
        |]
        [list]

            Here is [sql-param foo1] from outer <br>


           [query
               prefix=usr
               list_prefix=detail
               ml=1
               type=list
               sp="@@MV_PAGE@@"
               sql=|
                SELECT  flip
                FROM    flap
                WHERE   flog = 'flan'
              |]

             [usr-on-match]
                something was found in the inner!
             [/usr-on-match]

             [detail]

                Here is [usr-param flip] from inner <br>

                Here is [sql-param foo2] from outer!! <br>

             [/detail]
           [/query]

            Here is [sql-param foo3] from outer!!! <br>

        [/list]
        [on-match]
            Something was found in the outer query<br>
        [/on-match]
        [no-match]
            Nothing was found in the outer query<br>
        [/no-match]
        [more-list]
                <br>[matches] in the outer query<br>
        [/more-list]
    [/query]

Notice the use of 'prefix' and 'list_prefix' on subsequent inner
queries.

=head2 read-cookie

Returns the value of the named cookie. Returns nothing if the cookie
does not exist.

Summary

    [read-cookie name]
    [read-cookie name=mycookie]

 Attributes   Description                               Default
 name         The name of the cookie whose value you wantnone

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 Yes
 Container tag                     No

B<Usage example:>

    [read-cookie name=MV_SESSION_ID]
---
    6CZ2whqo

B<ASP-like Perl call:>

    $Tag->read_cookie(  { name => $name, }  );

or similarly with positional parameters,

    $Tag->read_cookie( $name );

Description

This tag expands to the value of the named cookie (or nothing if the
cookie does not exist).

See the Netscape specification at
I<http://www.netscape.com/newsref/std/cookie_spec.html> if you need
more cookie-specific detail.

I<name>

This is the name of the cookie whose value you want to retrieve.

I<Parsing an HTTP_COOKIE string>

If you pass this tag a second parameter within a Perl call, it will
use your value as the HTTP_COOKIE string (ignoring the real one). This
only applies if you pass the values positionally within a perl call
since there is no name for the HTTP_COOKIE string S<input:>

  $Tag->read_cookie('MV_SESSION_ID', "MV_SESSION_ID=UnHyaDQj:127.0.0.1; ...");

=head2 restrict

Restrict tag execution in a region. If a restricted tag is
encountered, it is simply output.

Summary

    [restrict tag1 tag2]
    [restrict policy=deny enable="page area value"]

 Attributes   Description                               Default
 policy       Whether to allow or deny by default.      deny
 enable       Tags to enable when default policy is deny.none
 disable      Tags to disable. Overrides enable.        none

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 Yes
 Container tag                     No

B<Usage example:>

    [read-cookie name=MV_SESSION_ID]
---
    6CZ2whqo

B<ASP-like Perl call:>

    N/A. Cannot be called effectively.

Description

Restrict tag execution in a region. If a restricted tag is
encountered, it is simply output. It can be used to allow certain tags
in a user-editable region, while denying dangerous tags. Or it can be
used to restrict all tag execution in a region.

I<policy>

Default is deny, which makes most sense. You then specifically
enable certain ITL tags. If you set allow by default, you must be
very careful that you really are disabling all of what you consider to
be dangerous tags.

I<enable>

A space-separated or comma-separated list of tags to disable when the
default policy is deny. Has no effect when the default policy is
allow, and any tags passed in the disable parameter override the
enable.

I<disable>

A space-separated or comma-separated list of tags to disable when the
default policy is allow. If you have a list of tags that are
enabled, perhaps stored in a scratch variable, you can disable some of
those tags since this takes precedence over the enable.

=head2 row

Summary

Parameters: B<width>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Interpolates B<container text> by default.

This is a container tag, i.e. [row] FOO [/row]. Nesting: NO

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->row(
        {
         width => VALUE,
        },
        BODY
    )

 OR

    $Tag->row($width, $BODY);
    [row width]

 Parameters   Description                               Default
 width                                                  DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [row width]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->row(  { width => VALUE_width
}, $body  );

or similarly with positional parameters,

    $Tag->row(width, $attribute_hash_reference, $body);

Description

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

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

I<width>

=head2 salestax

Summary

Parameters: B<name noformat>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->salestax(
        {
         name => VALUE,
         noformat => VALUE,
        }
    )

 OR

    $Tag->salestax($name, $noformat);

Attribute aliases

            cart ==> name
    [salestax name noformat]

 Parameters   Description                               Default
 cart         Alias for name                            DEFAULT_VALUE
 name                                                   DEFAULT_VALUE
 noformat                                               DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [salestax name noformat]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->salestax(  { name => VALUE_name
                       noformat => VALUE_noformat
}, $body  );

or similarly with positional parameters,

    $Tag->salestax(name,noformat, $attribute_hash_reference, $body);

Description

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

I<name>

I<noformat>

=head2 scratch

Summary

Parameters: B<name>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->scratch(
        {
         name => VALUE,
        }
    )

 OR

    $Tag->scratch($name);
    [scratch name]

 Parameters   Description                               Default
 name                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [scratch name]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->scratch(  { name => VALUE_name
}, $body  );

or similarly with positional parameters,

    $Tag->scratch(name, $attribute_hash_reference, $body);

Description

Returns the contents of a scratch variable to the page. (A scratch
variable is set with a [set] value [/set] container pair.)

I<name>

=head2 scratchd

Deletes the named scratch variable and returns its value before the
deletion. For example,

    [scratchd varname_to_delete]

deletes the scratch variable I<varname_to_delete>.

See also the scratch and set tags.

Summary

    [scratchd P_PARAM]
    [scratchd N_PARAM other_named_attributes]

 Parameters   Description                               Default
 name         Name of scratch variable to delete        None

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 Yes
 Container tag                     No

B<Tag expansion example:>

    [set myvar]This is myvar[/set]
    .
    .
    .
    [scratchd myvar]
---
    This is myvar

B<ASP-like Perl call:>

    $Tag->scratchd($name, $attribute_hash_reference);

Description

Deletes the named scratch variable and returns its value before the
deletion.

=head2 search-list

Formats results returned by a search. Must be enclosed within a
search-region. Has sub-tags (see Looping tags and Sub-tags).

=head2 search-region

Summary

Parameters: B<arg>

B<The attribute hash reference is passed> after the parameters but
before the container text argument. B<This may mean that there are
parameters not shown here.>

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [search-region] FOO [/search-region].
Nesting: NO

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->search_region(
        {
         arg => VALUE,
        },
        BODY
    )

 OR

    $Tag->search_region($arg, $ATTRHASH, $BODY);

Attribute aliases

            args ==> arg
            params ==> arg
            search ==> arg
    [search-region arg other_named_attributes]

 Parameters   Description                               Default
 arg                                                    DEFAULT_VALUE
 args         Alias for arg                             DEFAULT_VALUE
 params       Alias for arg                             DEFAULT_VALUE
 search       Alias for arg                             DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [search-region arg]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->search_region(  { arg => VALUE_arg
}, $body  );

or similarly with positional parameters,

    $Tag->search_region(arg, $attribute_hash_reference, $body);

Description

B<NO Description>

I<arg>

=head2 selected

Summary

Parameters: B<name value>

Positional parameters in same order.

B<The attribute hash reference is passed> to the subroutine after the
parameters as the last argument. B<This may mean that there are
parameters not shown here.>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->selected(
        {
         name => VALUE,
         value => VALUE,
        }
    )

 OR

    $Tag->selected($name, $value, $ATTRHASH);
    [selected name value other_named_attributes]

 Parameters   Description                               Default
 case                                                   DEFAULT_VALUE
 cgi                                                    DEFAULT_VALUE
 default                                                DEFAULT_VALUE
 name                                                   DEFAULT_VALUE
 multiple                                               DEFAULT_VALUE
 value                                                  DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [value name=example set=neato]
    <OPTION[selected example neato]>Neato
    <OPTION[selected example silly]>Silly
---
    <OPTION SELECTED>Neato
    <OPTION>Silly

Description

You can provide a "memory" for drop-down menus, radio buttons, and
checkboxes with the [checked] and [selected] tags.

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 unless the optional
case=1 parameter is used.

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="[item-modifier-name color]">
    <OPTION [selected [item-modifier-name color] blue]> Blue
    <OPTION [selected [item-modifier-name color] green]> Green
    <OPTION [selected [item-modifier-name color] red]> Red
    </SELECT>

By default, the Values space (i.e. [value foo]) is checked - if you
want to use the volatile CGI space (i.e. [cgi foo]) use the parameter
cgi=1.

Use the parameter default=1 to specify the option that should be
marked SELECTED if the value/CGI variable has never been set.

If the parameter multiple=1 is set, the value parameter can
contain multiple (stacked) values that should be selected, separated
by ASCII null characters ("\0" in Perl).

I<case>

I<cgi>

I<default>

I<name>

I<multiple>

I<value>

=head2 set

Summary

Parameters: B<name>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [set] FOO [/set]. Nesting: NO

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->set(
        {
         name => VALUE,
        },
        BODY
    )

 OR

    $Tag->set($name, $BODY);
    [set name]

 Parameters   Description                               Default
 name                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<ASP-like Perl call:>

   $Tag->set(  { name => VALUE_name
}, $body  );

or similarly with positional parameters,

    $Tag->set(name, $attribute_hash_reference, $body);

Description

Sets a scratch variable to I<value>.

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

You can set an order profile with:

  [set checkout]
  name=required
  address=required
  [/set]
  <INPUT TYPE=hidden NAME=mv_order_profile VALUE="checkout">

A search profile would be set with:

  [set substring_case]
  mv_substring_match=yes
  mv_case=yes
  [/set]
  <INPUT TYPE=hidden NAME=mv_profile VALUE="substring_case">

Any of these profile values can be set in the OrderProfile files as
well.

I<name>

=head2 set-cookie

Sets browser cookie(s) with the specified attributes.

Summary

    [set-cookie named_attributes]

Parameters must be named (no positional usage except in Perl call)

 Attributes   Description                               Default
 name         The name you give the cookie              none
 value        The value (automatically html-escaped by Interchange)none
 expire       Expiration date as"Wdy, DD-Mon-YYYY HH:MM:SS GMT"none
 domain       Overrides the domain(s) set in CookieDomainDomain(s), if any, defined in the CookieDomain directive
 path         legal URL paths for the cookie            URL path(s) to your catalog, including aliases

 Other_Characteristics             
 Invalidates cache                 Yes
 Container tag                     No

B<Usage example:>

    [set-cookie name=mycookie
               value="the value"
              expire="Tue, 03-Apr-2001 17:00:00 GMT"]
---
    This tag returns no value in the page

B<ASP-like Perl call:>

    $Tag->set_cookie(  { name   => $name,
                         value  => $value,
                         expire => $expire,
                         domain => $domain,
                         path   => $path, }  );

or similarly with positional parameters,

    $Tag->set_cookie( $name, $value, $expire, $domain, $path );

Description

This tag sets one or more browser cookies with your specified name,
value, and expiration. (Interchange will set more than one cookie if
needed to ensure that the cookie is visible from all Catalog URL
path aliases and CookieDomains.)

See the Netscape specification at
I<http://www.netscape.com/newsref/std/cookie_spec.html> for more
cookie-specific detail.

If you need access to the cookie from outside of your Interchange
catalog, you can also set the domain and URL paths for which the
cookie will be valid. If you need the cookie only within your catalog
and the domains specified by the CookieDomain directive, you
probably should not override the Interchange domain and path defaults.

I<name>

This is the name of the cookie. This is the key you will use when
reading the cookie later.

I<value>

This is the value to store in the cookie.

I<expire>

Persistent cookies (that outlive a browser session) require an
expiration date. There are two ways to set it -- relative times and
absolute times.

=over 4

=over 8

=item absolute

=back

=back

The date must be a string of the S<form:>

=over 4

=item

"Wdy, DD-Mon-YYYY HH:MM:SS GMT"

=back

and the timezone must be GMT.

=over 4

=over 8

=item relative

=back

=back

Supply a period in the form NN sec|min|hours|days|weeks.

Example:

 [set-cookie name=THE_COOKIE value=foo expire="7 days"]

If you do not supply a date (either absolute or relative), the cookie
will disappear when the user closes the browser.

I<domain>

The value you set will override the Interchange default domain(s). You
might set this if you need access to the cookie from outside the
Interchange catalog, but it is usually better to set the
CookieDomain directive in your catalog.

The default is to use your catalog's domain or all CookieDomain
values.

I<path>

The value you set will override the Interchange default URL path(s).

The default is to set a cookie with a path for each catalog alias (see
the Catalog directive). This ensures that the cookie will be
visible regardless of how the end user returns to your catalog.

Tips

You can use the time tag in conjunction with the set-cookie tag to set
the expiration date to an absolute date.

   [set-cookie
     name=mycookie
     value="the value"
     expire="[time gmt=1 adjust='+2190']%a, %m-%b-%Y %H:%M:%S GMT[/time]"
   ]

In the example above, the adjustment of +2190 will set a cookie
expiration of 2190 hours forward from the current date.

You can use the

=head2 seti

Summary

Parameters: B<name>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Interpolates B<container text> by default.

This is a container tag, i.e. [seti] FOO [/seti]. Nesting: NO

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->seti(
        {
         name => VALUE,
        },
        BODY
    )

 OR

    $Tag->seti($name, $BODY);
    [seti name]value[/seti]

 Parameters   Description                               Default
 name                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [seti name]value[/seti]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->seti(  { name => VALUE_name
}, $body  );

or similarly with positional parameters,

    $Tag->seti(name, $attribute_hash_reference, $body);

Description

Equivalent to the [set] tag, except that it I<interpolates> by
default.

I<name>

=head2 setlocale

Sets locale and/or currency for the current page. Can be made
persistent for the user with the 'persist' option. Resets default
locale if called without arguments.  See also I<Setting the Locale> in
the template documentation.

Summary

    [setlocale]

 Parameters   Description                               Default
 currency     The currency format to use.Default: [scratch mv_currency] (see also 'persist' attribute)DEFAULT_VALUE
 locale       The locale to use.Default: [scratch mv_locale] (see also 'persist' attribute)DEFAULT_VALUE
 persist      Setting 'persist=1' also sets the scratch variables, mv_locale and mv_currency to specified locale and currency. This makes the locale settings persistent for the user's session. Otherwise (persist=0), the setlocale tag affects the remainder of the current page only.DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [setlocale]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->setlocale(  {
}, $body  );

or similarly with positional parameters,

    $Tag->setlocale(, $attribute_hash_reference, $body);

Description

Immediately sets the locale to locale, and will cause it to persist
in future user pages if the persist is set to a non-zero, non-blank
value. If the currency attribute is set, the pricing and
currency-specific locale keys and Interchange configuration directives
are modified to that locale. If there are no arguments, it sets it
back to the user's default locale as defined in the scratch variables
mv_locale and mv_currency.

This S<allows:>

    Dollar Pricing:

    [setlocale en_US]
    [item-list]
    [item-code]: [item-price]<BR>
    [/item-list]

    Franc Pricing:

    [setlocale fr_FR]
    [item-list]
    [item-code]: [item-price]<BR>
    [/item-list]

    [comment] Return to the user's default locale [/comment]
    [setlocale]

I<currency>

The currency format to use.

=over 4

=item *

S<Default:> [scratch mv_currency] (see also 'persist' attribute)

=back

I<locale>

The locale to use.

=over 4

=item *

S<Default:> [scratch mv_locale] (see also 'persist' attribute)

=back

I<persist>

Setting 'persist=1' also sets the scratch variables, B<mv_locale>
and B<mv_currency> to specified locale and currency. This makes the
locale settings persistent for the user's session. Otherwise
(persist=0), the setlocale tag affects the remainder of the
current page only.

=head2 shipping

Returns the cost of shipping the items in the cart via the shipping
mode set with the B<mode> parameter. See also the I<Shipping> section
of the Database documentation.

Summary

    [shipping mode]

 Parameters   Description                               Default
 add          Adds the argument to add as data for a shipping.asc file (in $Vend::Cfg->{ScratchDir}/) and sets it.DEFAULT_VALUE
 cart         Alias: carts Comma-delimited list of names of carts to calculate shipping cost for.Default: current cartDEFAULT_VALUE
 carts        Alias for cart                            DEFAULT_VALUE
 convert      Applies the conversion (if any) set with the PriceDivide catalog configuration directive.Default: TrueDEFAULT_VALUE
 default      Resets shipping mode to default of [value mv_shipmode]DEFAULT_VALUE
 file         Filename to read shipping from (default is usual shipping database, e.g., shipping.asc)DEFAULT_VALUE
 format       Format for results with label attribute.Default: '<OPTION VALUE="%M"%S>%D (%F)'For example,    [shipping mode="FLAT"             label=1            format="My Format Desc %D Price %F"]DEFAULT_VALUE
 handling     Boolean-- use [value mv_handling] rather than [value mv_shipping] as first default for mode. Note that this attribute matters only if you do not specify the mode in the tag.Note that this is set by the [handling tag (which calls the shipping tag internally).  You should probably use the handling tag rather than setting this directly.Default: FalseDEFAULT_VALUE
 hide         Suppresses output                         DEFAULT_VALUE
 label        By default, returns HTML <OPTION ...> widget for shipping mode(s), including description and cost. You can override the widget with the format attribute.  Note that label overrides noformat.Here is an example from the foundation checkout.html page: [shipping     label=1     mode=|[data            table=country                        key='[default country US]'                        col=shipmodes]| ]DEFAULT_VALUE
 mode         Aliases: name, modes Whitespace, null or comma delimited list of modes for which to calculate shipping cost.  See also mv_shipmode.Default: [value mv_handling] if handling=1 or [value mv_shipmode] or 'default'DEFAULT_VALUE
 modes        Alias for mode                            DEFAULT_VALUE
 name         Alias for mode                            DEFAULT_VALUE
 noformat     Returns result as a number rather than a string formatted for the current locale's currency.Default: TrueDEFAULT_VALUE
 reset_messageBoolean. Blanks the session's current shipping message (i.e., $Session->{ship_message}).DEFAULT_VALUE
 reset_modes  Clears list of modes in $Vend::Cfg->{Shipping_line}Default: FalseDEFAULT_VALUE
 table        Alias: tables Whitespace-delimited list of tables containing shipping data required for perl or query calculations (e.g., in the 'PERL' field of your shipping database - see Shipping). You must specify the tables to get past the Perl 'Safe.pm' protection. For example, you will get 'Safe' errors if you refer to an SQL table without specifying it here.Default: NoneDEFAULT_VALUE
 tables       Alias for table                           DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [shipping mode]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->shipping(  { mode => VALUE_mode
}, $body  );

or similarly with positional parameters,

    $Tag->shipping(mode, $attribute_hash_reference, $body);

Description

This tag calculates the shipping cost for items in the current cart
via the specified shipping mode (usually set in the mv_shipmode
variable).  See the I<Shipping> section of the Database documentation
for detail.

It also has options to build a selection widget (usually SELECT or
RADIO types) with embedded cost data.

Rounding

Note that the tag rounds the calculated shipping cost to a
locale-specific number of fractional digits (e.g., to the nearest
penny, or 2 digits after the decimal point in the USA).

I<add>

Adds the argument to B<add> as data for a shipping.asc file (in
$Vend::Cfg->{ScratchDir}/) and sets it.

I<cart>

=over 4

=item *

S<Alias:> B<carts> Comma-delimited list of names of carts to calculate
shipping cost for.

=item *

S<Default:> current cart

=back

I<convert>

Applies the conversion (if any) set with the PriceDivide catalog
configuration directive.

=over 4

=item *

S<Default:> True

=back

I<default>

Resets shipping mode to default of [value mv_shipmode]

I<file>

Filename to read shipping from (default is usual shipping database,
e.g., shipping.asc)

I<format>

Format for results with B<label> attribute.

=over 4

=item *

S<Default:> '<OPTION VALUE="%M"%S>%D (%F)'

=item *

For example,

    [shipping mode="FLAT"

=back
             label=1
            format="My Format Desc %D Price %F"]

I<handling>

Boolean-- use [value mv_handling] rather than [value mv_shipping] as
first default for B<mode>. Note that this attribute matters only if
you do not specify the B<mode> in the tag.

=over 4

=item *

Note that this is set by the [handling tag (which calls the
shipping tag internally).  You should probably use the handling tag
rather than setting this directly.

=item *

S<Default:> False

=back

I<hide>

Suppresses output

I<label>

By default, returns HTML <OPTION ...> widget for shipping mode(s),
including description and cost. You can override the widget with the
B<format> attribute.  Note that B<label> overrides B<noformat>.

=over 4

=item *

Here is an example from the foundation checkout.html page:

    [shipping

=back
        label=1
        mode=|[data table=country key='[default country US]' col=shipmodes]|
    ]

I<mode>

=over 4

=item *

S<Aliases:> B<name>, B<modes> Whitespace, null or comma delimited list
of modes for which to calculate shipping cost.  See also mv_shipmode.

=item *

S<Default:> [value mv_handling] if B<handling=1> or [value
mv_shipmode] or 'default'

=back

I<noformat>

Returns result as a number rather than a string formatted for the
current locale's currency.

=over 4

=item *

S<Default:> True

=back

I<no_state>

Bypasses the state lookup for [shipping widget=TYPE] and [shipping
possible=1].

I<possible>

Returns all possible modes for the selected country and state, based
on the country and state tables.

Does a query to find the shipmodes column of the state based on the
user value state, and/or the shipmodes column of the country
based on the value country

NOTE: You can set the following, though most will use the Interchange
defaults:

 state_table         state table for lookup (default "state")
 country_table       country table for lookup (default "country")
 state_modes_field   shipmodes field in state table (default "shipmodes")
 country_modes_field shipmodes field in country table (default "shipmodes")
 country_table       country table for lookup (default "country")
 state_var           state variable in user session (default "state")
 country_var         country variable in user session (default "country")
 shipmode_var        shipmode variable in user session (default "mv_shipmode")

I<reset_message>

Boolean. Blanks the session's current shipping message (i.e.,
$Session->{ship_message}).

I<reset_modes>

Clears list of modes in $Vend::Cfg->{Shipping_line}

=over 4

=item *

S<Default:> False

=back

I<resolve>

Returns the one shipping mode to set as a default, based on the best
information available. Usually selects the first in the list based on
country or state.

I<table>

=over 4

=item *

S<Alias:> B<tables> Whitespace-delimited list of tables containing
shipping data required for perl or query calculations (I<e.g.>, in the
'PERL' field of your shipping database - see I<Shipping>). You must
specify the tables to get past the Perl 'I<Safe.pm>' protection. For
example, you will get 'I<Safe>' errors if you refer to an SQL table
without specifying it here.

=item *

S<Default:> None

=back

I<widget>

Returns a pre-configured widget for shipping mode selection. Will
select the modes from [shipping possible=1], but will also do shipping
calculations to see if they are valid.

If there is no weight, zip, country, or other needed information, it
will return "not enough information".

In other words, [shipping widget=select] might return to the page:

 <select name="mv_shipmode">
        <option value="upsg" SELECTED>UPS Ground (&#36;4.20)
        <option value="upsb">UPS 2nd Day Air (&#36;8.76)
 </select>

=head2 shipping-desc

Returns the shipping description for the specified shipping B<mode>. 
See the I<Shipping> section of the Database documentation.  See also
shipping.asc database for shipping modes.

S<Alias:> B<shipping-description>

The two tags below are identical in S<operation:>

   [shipping-desc mode]
   [shipping-description mode]

Summary

    [shipping-desc mode]
    [shipping-desc mode=shipping_mode]

 Parameters   Description                 Default
 mode         Shipping mode. This is a key into the shipping.asc database. See Shipping documentation.mv_shipmode, or 'default' if mv_shipmode not set

 Other_Characteristics             
 Invalidates cache                 Yes, but only if no mode given
 Container tag                     No

B<Tag expansion example:>

    [shipping-desc 1DM]
---
    UPS Next Day Air Early AM

B<ASP-like Perl call:>

    $Tag->shipping_desc( $mode );

=head2 soap

Summary

Parameters: B<call uri proxy>

Positional parameters in same order.

B<The attribute hash reference is passed> to the subroutine after the
parameters as the last argument. B<This may mean that there are
parameters not shown here.>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->soap(
        {
         call => VALUE,
         uri => VALUE,
         proxy => VALUE,
        }
    )

 OR

    $Tag->soap($call, $uri, $proxy, $ATTRHASH);
    [soap call uri proxy other_named_attributes]

 Parameters   Description                               Default
 call                                                   DEFAULT_VALUE
 proxy                                                  DEFAULT_VALUE
 uri                                                    DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [soap call uri proxy]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->soap(  { call => VALUE_call
                   proxy => VALUE_proxy
                   uri => VALUE_uri
}, $body  );

or similarly with positional parameters,

    $Tag->soap(call,uri,proxy, $attribute_hash_reference, $body);

Description

B<NO Description>

I<call>

I<proxy>

I<uri>

=head2 strip

Strips leading and trailing whitespace from the contained body text.

Summary

    [strip]
       Body text to strip
    [/strip]

No parameters.

 Other_Characteristics             
 Invalidates cache                 No
 Container tag                     Yes
 Has Subtags                       No

B<ASP-like Perl call:>

   $Tag->strip($BODY);

or even better, just do it directly like this

   $BODY =~ s/^\s+//;
   $BODY =~ s/\s+$//;

=head2 subtotal

Summary

Parameters: B<name noformat>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->subtotal(
        {
         name => VALUE,
         noformat => VALUE,
        }
    )

 OR

    $Tag->subtotal($name, $noformat);

Attribute aliases

            cart ==> name
    [subtotal name noformat]

 Parameters   Description                               Default
 cart         Alias for name                            DEFAULT_VALUE
 name                                                   DEFAULT_VALUE
 noformat                                               DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [subtotal name noformat]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->subtotal(  { name => VALUE_name
                       noformat => VALUE_noformat
}, $body  );

or similarly with positional parameters,

    $Tag->subtotal(name,noformat, $attribute_hash_reference, $body);

Description

Positional: [subtotal cart* noformat*]

mandatory: NONE

optional: cart noformat

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

I<name>

I<noformat>

=head2 tag

Summary

Parameters: B<op arg>

Positional parameters in same order.

B<The attribute hash reference is passed> after the parameters but
before the container text argument. B<This may mean that there are
parameters not shown here.>

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [tag] FOO [/tag]. Nesting: NO

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->tag(
        {
         op => VALUE,
         arg => VALUE,
        },
        BODY
    )

 OR

    $Tag->tag($op, $arg, $ATTRHASH, $BODY);

Attribute aliases

            description ==> arg
    [tag op arg other_named_attributes]

 Parameters   Description                               Default
 arg                                                    DEFAULT_VALUE
 description  Alias for arg                             DEFAULT_VALUE
 op                                                     DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes
 attach_only                       No

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [tag op arg]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->tag(  { arg => VALUE_arg
                  op => VALUE_op
}, $body  );

or similarly with positional parameters,

    $Tag->tag(op,arg, $attribute_hash_reference, $body);

Description

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

I<export database file* type*>

Exports a complete Interchange database to its text source file (or
any specified file). The integer n, if specified, will select
export in one of the enumerated Interchange 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 I<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 I<NoAbsolute> is set to No.

I<flag arg>

Sets an Interchange condition.

The following enables writes on the products and sizes databases
held in Interchange internal DBM format:

    [tag flag write]products sizes[/tag]

SQL databases are always writable if allowed by the SQL database
itself - in-memory databases will never be written.

The [tag flag build][/tag] combination forces static build of a page,
even if dynamic elements are contained. Similarly, the [tag flag
cache][/tag] forces search or page caching (not usually wise).

I<log dir/file>

Logs a message to a file, fully interpolated for Interchange 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 I<NoAbsolute> is set to No.

I<mime description_string>

Returns a MIME-encapsulated message with the boundary as employed in
the other mime tags, and the description_string 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 etc/report for an
example. Adding the attribute attach_only=1 to the tag call will set
the content disposition to "attachment" (vs. inline).

I<mime boundary>

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

I<mime header>

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

I<mime id>

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

I<show_tags>

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

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

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

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

I<arg>

I<op>

=head2 time

Summary

Parameters: B<locale>

Positional parameters in same order.

B<The attribute hash reference is passed> after the parameters but
before the container text argument. B<This may mean that there are
parameters not shown here.>

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [time] FOO [/time]. Nesting: NO

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->time(
        {
         locale => VALUE,
        },
        BODY
    )

 OR

    $Tag->time($locale, $ATTRHASH, $BODY);
    [time locale other_named_attributes]

 Parameters   Description                               Default
 adjust       Temporarily adjust the time for display purposes.none
 gmt          Display time as GMT.                      none
 locale       Format the time according to the named locale.none
 tz           Use the passed timezone to display the time.none
 zerofix      Strips leading zeroes from numbers.       none

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [time locale]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->time(  { locale => VALUE_locale
}, $body  );

or similarly with positional parameters,

    $Tag->time(locale, $attribute_hash_reference, $body);

Description

Formats the current time according to POSIX strftime arguments. The
following is the string for Monday, January 1, 2001.

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

See the strftime man page for information on the arguments (which
are the same as modern UNIX date commands).

Accepts the following options:

I<adjust>

If you wish to temporarily adjust the time for display purposes, you
can pass an adjust parameter with the number of hours (plus or
minus).

        [time]%c[/time]
        [time adjust="-3"]%c[/time]

Will display:

 Mon 01 Jan 2001 11:29:03 AM EST
 Mon 01 Jan 2001 08:29:03 AM EST

If the number ends in zero and has 3 digits or more, it is assumed
that the number is in timezone format (i.e +500) the local time or
from GMT:

        [time]%c[/time]
        [time adjust="-330"]%c[/time]
        [time adjust="-300"]%c[/time]

Will display:

 Mon 01 Jan 2001 11:29:03 AM EST
 Mon 01 Jan 2001 07:59:03 AM EST
 Mon 01 Jan 2001 08:29:03 AM EST

If you want to force the number to be just a number of hours, add the
hours parameter:

        [time]%c[/time]
        [time adjust="100" hours=1]%c[/time]

Will display:

 Mon 01 Jan 2001 11:29:03 AM EST
 Fri 05 Jan 2001 15:29:03 PM EST

If adjust is an Interchange time duration with a suffix of sec,
min, hrs, days, or weeks, that will be used.

        [time]%c[/time]
        [time adjust="2 days"]%c[/time]

Will display:

 Mon 01 Jan 2001 11:29:03 AM EST
 Wed 03 Jan 2001 11:29:03 AM EST

Note that the time zone does not change - you should either pick a
format which doesn't display zone, use the tz parameter, or manage
it yourself.

NOTE: You can adjust time globally for an Interchange installation by
setting the $ENV{TZ} variable on many systems. Set TZ in your
environment and then restart Interchange:

        ## bash/ksh/sh
        TZ=PST7PDT; export TZ
        interchange -restart

        ## csh/tcsh
        setenv TZ PST7PDT
        interchange -restart

On most modern UNIX systems, all times will now be in the PST zone.

I<gmt>

If you want to display time as GMT, use the gmt parameter:

        [time]%c[/time]
        [time gmt=1]%c[/time]

will display:

        Mon 01 Jan 2001 11:33:26 AM EST
        Mon 01 Jan 2001 04:33:26 PM EST

Once again, the zone will not be set to GMT, so you should pick a
format string which doesn't use zone, use the tz parameter, or
manage it yourself.

I<locale>

Format the time according to the named locale, assuming that locale
is available on your operating system. For example, the following:

        [time locale=en_US]%B %d, %Y[/time]
        [time locale=fr_FR]%B %d, %Y[/time]

should display:

        January 01, 2001
        janvier 01, 2001

I<tz>

Use the passed timezone to display the time. Will adjust for hours
difference.

Example:

        [time tz=GMT0]
        [time tz=CST6CDT]
        [time tz=PST8PDT]

will display:

        Mon 01 Jan 2001 04:43:02 PM GMT
        Mon 01 Jan 2001 10:43:02 AM CST
        Mon 01 Jan 2001 08:43:02 AM PST

Note that the first alphabetical string is the zone name when not
under daylight savings time, the digit is the number of hours
displacement from GMT, and the second alphabetical string is the zone
name when in daylight savings time. NOTE: This may not work on all
operating systems.

I<zerofix>

Strips leading zeroes from numbers.

=head2 timed-build

Summary

Parameters: B<file>

Positional parameters in same order.

B<The attribute hash reference is passed> after the parameters but
before the container text argument. B<This may mean that there are
parameters not shown here.>

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [timed-build] FOO [/timed-build].
Nesting: NO

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->timed_build(
        {
         file => VALUE,
        },
        BODY
    )

 OR

    $Tag->timed_build($file, $ATTRHASH, $BODY);
    [timed-build file other_named_attributes]

 Parameters   Description                               Default
 auto         Turn on automatic region processing.      none
 file         Name of the cache file.                   none
 if           Conditional display of the cached region. none
 minutes      Number of minutes after which the timed build should be repeated.60
 period       Alternative way of expressing time.       none

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [timed-build file]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->timed_build(  { file => VALUE_file
}, $body  );

or similarly with positional parameters,

    $Tag->timed_build(file, $attribute_hash_reference, $body);

Description

Allows you to build CPU-intensive regions of ITL tags on a timed
basis.

In the simplest case, surround a region of ITL with [timed-build]
and [/timed-build]:

        [timed-build]
                Built at [time]%c[/time].
        [/timed-build]

If a file parameter is not passed, saves to the directory I<timed>
in catalog root, with the file name of the current page. If the
minutes parameter is not passed specifying how often the page
should be rebuilt, then it will not be rebuilt until the output file
is removed.

Accepts the following parameters:

I<auto>

Turns on automatic region processing. The text of the timed-build
region is processed to determine a unique checksum or digest (using
MD5), and that file name is checked in the directory tmp/auto-timed
(assuming ScratchDir is set to tmp). If no number of minutes is
supplied, 60 is assumed.

This is designed to automatically build regions of commonly used areas
without having to manage the file name yourself.

Implies login=1, but will still abort if no session ID cookie has
been sent. Use force=1 to ignore cookie status.

I<file>

Name of the file to save the results in. Relative to catalog root. The
directory must exist.

I<if>

Allows you to to only display the cached region when the if
parameter is true. For example, you can do:

        [timed-build if="[value timed]"]
        ITL tags....
        [/timed-build]

The cached region will only be displayed if the variable timed is
set to a non-zero, non-blank value. Otherwise, the ITL tags will be
re-interpreted every time.

I<minutes>

The number of minutes after which the timed build should be repeated.
If set to 0, it will be built once and then not rebuilt until the
output file is removed.

I<period>

Alternative way of expressing time. You can pass a string describing
the rebuild time period:

        [timed-build period="4 hours"]
        ITL tags....
        [/timed-build]

This is really the same as minutes=240. Useful for passing seconds:

        [timed-build period="5 seconds"]
        ITL tags....
        [/timed-build]

The region will be rebuilt every 5 seconds.

Performance S<Tip:> use minutes of .08 instead; avoids having to parse
the period string.

If you have the StaticDir catalog.cfg parameter set to a writable
path, you can build a cached static version of your catalog over time.
Simply place a [timed-build] tag at the top of pages you wish to build
statically. Assuming the catalog is not busy and write lock can be
obtained, the StaticDBM database will be updated to mark the page as
static and the next time a link is made for that page the static
version will be presented.

=head2 tmp

Summary

Parameters: B<name>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Interpolates B<container text> by default.

This is a container tag, i.e. [tmp] FOO [/tmp]. Nesting: NO

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->tmp(
        {
         name => VALUE,
        },
        BODY
    )

 OR

    $Tag->tmp($name, $BODY);

    [tmp name]value[/tmp]

 Parameters   Description                               Default
 name                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate                       Yes
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [tmp name]value[/tmp]

B<ASP-like Perl call:>

   $Tag->tmp(  { name => VALUE_name
}, $body  );

or similarly with positional parameters,

    $Tag->tmp(name, $attribute_hash_reference, $body);

Description

Sets a Scratch variable to the value specified in the tag body.
This is just as the [seti] tag would do it, except that the I<name>
is added to the list of Scratch keys that are to be deleted
immediately after the current page has been processed and served. This
saves session write time in many cases.

This tag interpolates automatically. (Interpolation can be turned off
with interpolate=0.) See also: [tmpn].

IMPORTANT NOTE: the [tmp ...][/tmp] tag is not appropriate for setting
order profiles or mv_click actions. If you want to avoid that, use
a profile stored via the catalog.cfg directive OrderProfile.

I<name>

=head2 tmpn

Summary

Parameters: B<name>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [tmpn] FOO [/tmpn]. Nesting: NO

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->tmpn(
        {
         name => VALUE,
        },
        BODY
    )

 OR

    $Tag->tmpn($name, $BODY);

    [tmpn name]value[/tmp]

 Parameters   Description                               Default
 name                                                   DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<ASP-like Perl call:>

   $Tag->tmpn(  { name => VALUE_name
}, $body  );

or similarly with positional parameters,

    $Tag->tmpn(name, $attribute_hash_reference, $body);

Description

Equivalent to the [tmp] tag, except that it does not I<interpolate>
by default.

NOTE: This tag was introduced in Interchange 4.9 and is therefore not
available in earlier versions.

I<name>

=head2 total-cost

Summary

Parameters: B<name noformat>

Positional parameters in same order.

Pass attribute hash as last to subroutine: B<no>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->total_cost(
        {
         name => VALUE,
         noformat => VALUE,
        }
    )

 OR

    $Tag->total_cost($name, $noformat);

Attribute aliases

            cart ==> name
    [total-cost name noformat]

 Parameters   Description                               Default
 cart         Alias for name                            DEFAULT_VALUE
 name                                                   DEFAULT_VALUE
 noformat                                               DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [total-cost name noformat]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->total_cost(  { name => VALUE_name
                         noformat => VALUE_noformat
}, $body  );

or similarly with positional parameters,

    $Tag->total_cost(name,noformat, $attribute_hash_reference, $body);

Description

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

I<name>

I<noformat>

=head2 tree

Summary

Parameters: B<table master subordinate start>

B<The attribute hash reference is passed> after the parameters but
before the container text argument. B<This may mean that there are
parameters not shown here.>

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [tree] FOO [/tree]. Nesting: NO

Invalidates cache: B<no>

Called Routine:

B<ASP-like Perl call:>

    $Tag->tree(
        {
         table => VALUE,
         master => VALUE,
         subordinate => VALUE,
         start => VALUE,
        },
        BODY
    )

 OR

    $Tag->tree($table, $master, $subordinate, $start, $ATTRHASH, $BODY);

Attribute aliases

            sub ==> subordinate
    [tree table master subordinate start other_named_attributes]

 Parameters   Description                               Default
 master                                                 DEFAULT_VALUE
 start                                                  DEFAULT_VALUE
 sub          Alias for subordinate                     DEFAULT_VALUE
 subordinate                                            DEFAULT_VALUE
 table                                                  DEFAULT_VALUE

 Attributes                        Default
 interpolate                       No
 reparse                           Yes

 Other_Characteristics             
 Invalidates cache                 no
 Container tag                     Yes
 Has Subtags                       No
 Nests                             No

B<Tag expansion example:>

    [tree table master subordinate start]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->tree(  { master => VALUE_master
                   start => VALUE_start
                   subordinate => VALUE_subordinate
                   table => VALUE_table
}, $body  );

or similarly with positional parameters,

    $Tag->tree(table,master,subordinate,start, $attribute_hash_reference, $body);

Description

Provides iterative list capability for binary trees. It produces
hash-based rows use the same tags as [item-list]; sets some
additional hash key entries to describe the tree and provide display
control.

Works on a data set with the structure:

    parent  child
    99      a
    a       b
    a       c
    a       d
    a       x
    x       y
    x       z
    99      m
    99      n
    99      o
    o       e
    o       f
    o       g

Sets several keys which assist in walking and displaying the tree.

I<mv_level>

Level of the item. If it is in the first level, it is 0. Sublevels are
infinite (except for performance).

I<mv_increment>

Increment label for the item. Normally goes from 1...n, but can be
changed to A...Z or a...z in outline mode.

I<mv_children>

If in autodetect mode, set to the number of children this branch has.
If a leaf, set to 0.

I<mv_spacing>

A multiple of level times the spacing option. Useful for setting width
of spacer images.

The above sample data placed in a table named "tree" would produce:

    a           mv_level=0, mv_increment=1, mv_children=4
        b       mv_level=1, mv_increment=1, mv_children=0
        c       mv_level=1, mv_increment=2, mv_children=0
        d       mv_level=1, mv_increment=3, mv_children=0
        x       mv_level=1, mv_increment=4, mv_children=2
            y   mv_level=2, mv_increment=1, mv_children=0
            z   mv_level=2, mv_increment=2, mv_children=0
    m           mv_level=0, mv_increment=1, mv_children=0
    n           mv_level=0, mv_increment=2, mv_children=0
    o           mv_level=0, mv_increment=3, mv_children=3
        e       mv_level=1, mv_increment=1, mv_children=0
        f       mv_level=1, mv_increment=2, mv_children=0
        g       mv_level=1, mv_increment=3, mv_children=0

from the tag call:

        <table>
    [tree   start=99
            table=tree
            master=parent
            subordinate=child
            autodetect=1
            spacing=4
            full=1]
        <tr>
        <td>
        [if-item-param mv_level]
                [item-calc]
                        return '&nbsp' x [item-param mv_spacing];
                [/item-calc]
        [/if-item-param]
        [item-param child]
        </td>
        <td>
                mv_level=[item-param mv_level],
                mv_increment=[item-param mv_increment],
                mv_children=[item-param mv_children]
        </td>
        </tr>
        [/tree]
        </table>

Accepts the following parameters:

I<table>

Database table which contains the tree. Must be a valid Interchange
table identifier.

I<master>

The column which is used to determine the parent of the item.

I<subordinate>

The child column, which determines which items are sub-items of the
current one. Used to re-query for items with its value in master.

I<start_item>

The first item to be followed, i.e. the master value of all the
top-level items.

I<autodetect>

Specifies that the next level should be followed to detect the number
of child items contained. Not recursive; only follows far enough to
determine the children of the current item.

I<full>

Specifies that all items should be followed. Essentially the same as
specifying memo and passing the explode variable, but not
dependent on them. Useful for building lists for inclusion in embedded
Perl, among other things.

I<stop>

An optional stop field which, when the value is true, can stop the
following of the branch.

I<continue>

An optional continue field which, when the value is true, can force
the branch to be followed.

I<sort>

The column which should be used for ordering the items - determines
the order in which they will be displayed under the current parent.

I<outline>

Sets outline mode, where mv_increment will be displayed with letter
values or numeral values. If set to specifically 1, will produced
outline increments like:

    1
        A
        B
            1
            2
        C
            1
            2
                a
                b
                    1
                    2
                        a
                        b
    2

I<memo>

Indicates that the collapse/explode/toggle features are to be used,
and names a Scratch variable where the values should be stored.

I<collapse>

The name of a variable in the user's session which will determine that
the tree should be "collapsed". When collapsed, the child items will
not be followed unless they are set to be followed with toggle.
Zeros all toggles.

Requires memo to be set if values are to be retained.

I<toggle>

The name of a variable in the user's session which will determine that
the current item should be either followed or not followed. The first
time the toggle variable corresponding to its primary key is
passed, the item will be expanded. The next call will "collapse" the
item.

Requires memo to be set if values are to be retained.

I<explode>

The name of a variable in the user's session which will determine that
the tree should be "exploded". When exploded, all child items are
followed and the full tree can be displayed.

Requires memo to be set if values are to be retained.

I<pedantic>

When set to a true value, and an endless tree is detected (i.e. the
child branch contains a parent) then the error will be logged to the
catalog error log and the tree call will return with an error.

If pedantic is not set (the default), the current leaf will be
shown but never followed. This allows partial display of the tree.

I<log_error>

When set to a true value, and an endless tree is detected (i.e. the
child branch contains a parent) then the error will be logged to the
catalog error log. No logging done by default.

I<show_error>

When set to a true value, and an endless tree is detected (i.e. the
child branch contains a parent) then the error will be returned in the
page. Errors are NOT shown by default.

In addition to the above values, all valid options for a list tag are
in force. For example, you can set a "SELECTED" value on an option
list with option=1, set the tag prefix with prefix, etc.

I<master>

I<start>

I<subordinate>

I<table>

=head2 try

Allows you to trap errors. Interchange processes the body text of the
[try][/try] block and returns it normally if it does not
generate an error. If it does generate an error, Interchange executes
the [catch][/catch] block.

See also 'catch'.

Summary

    [try label=my_label other_named_attributes]
        Body text to return if no error
    [/try]
    .
    .
    .
    [catch my_label]
        Body text to return if try block caused an error
    [/catch]

 Parameters   Description                               Default
 label        The label shared by the paired try and catch blocks'default'

 Attributes            Description             Default
 status                Returns 0 (failed) or 1 (succeeded) instead of page outputnone
 hide                  Suppresses page output  No
 clean                 Suppress try block output if it has an errorNo
 interpolate           See Interpolating ParametersNo
 reparse               See Interpolating ParametersYes

 Other_Characteristics             
 Invalidates cache                 No
 Container tag                     Yes

B<Tag expansion example:>

    [set divisor]0[/set]
    [try label=div]
        [calc] 1 / [scratch divisor] [/calc]
    [/try]
    [catch div]Division error[/catch]
---
    Division Error

B<ASP-like Perl call:>

    $Tag->try(    { label  => I<'try_catch_label'>,
                    status => 1, },
                  $try_body  );

    $Tag->catch(  { label  => I<'try_catch_label'>, },
                  $catch_body )

or similarly with positional parameters,

    $Tag->try($label, $attribute_hash_reference, $try_body);
    $Tag->catch($label, $attribute_hash_reference, $catch_body);

See Also

catch

Description

Allows you to trap errors. Interchange processes the body text of the
[try][/try] block and returns it normally if it does not
generate an error. If it does generate an error, interchange executes
the [catch][/catch] block. The catch block executes where it is
on the page (I<i.e.>, it does not replace the output of the try
block).

Note that the catch block must occur after the [try] block in the
document.

I<label>

The try and catch blocks are matched by this label.

Technical S<note:>

The try tag will also place a result in the $Session object.  For
example, the following returns the 'Illegal division by zero...' error
message if it S<occurs:>

    [try label=divide][calc] 1 / [scratch divisor] [/calc][/try]

    [catch divide]
        [calc]$Session->{try}{divide}[/calc]
    [/catch]

The $Session->{try}{divide} object will be set to the empty string
('') if there was no error, or it will contain the error message if
there was an error.

The [perl] and [calc] tags also set
$Session->{try}->{I<active_label>} on errors.

I<status>

Suppresses try block output and returns 1 if no error or 0 if an
error occurred instead.  Executes the catch block as usual in case
of an error.

I<hide>

Suppresses try block output (regardless of success or failure). 
Executes the catch block as usual in case of an error.

I<clean>

Setting 'clean=1' will cause the try block to suppress its
output only if it has an error. Otherwise (clean=0 or not set), the
try block will return whatever partial output it has completed
before the error.  The catch block will work as usual.

=head2 update

Forces an update of the specified interchange function. Function may
be one of the S<following:>

=over 4

=item *

B<cart> (updates current or named cart)

=item *

B<process> (updates order or search)

=item *

B<values> (updates user-entered fields)

=item *

B<data> (updates database, using current B<mv_> CGI form variables)

=back

Summary

    [update function]

 Parameters   Description                               Default
 function     cartUpdates current or named cart (see name attribute)processUpdates an order or a search pagevaluesUpdates user-entered fieldsdataUpdates database, using current mv_ CGI form variables, for example:mv_data_table Table to updatemv_data_key Key into tablemv_data_fields Fields to update (space or null delimited)mv_data_function One of the following:deleteupdateinsertdeleteetc.DEFAULT_VALUE
 name         Cart name to update (if 'function=cart')Default: current cartDEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [update function]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->update(  { function => VALUE_function
}, $body  );

or similarly with positional parameters,

    $Tag->update(function, $attribute_hash_reference, $body);

Description

Forces an update of the specified interchange function. Function may
be one of the S<following:>

=over 4

=item *

B<cart> (updates current or named cart)

=item *

B<process> (updates order or search)

=item *

B<values> (updates user-entered fields)

=item *

B<data> (updates database, using current B<mv_> CGI form variables)

=back

I<function>

=over 4

=item *

cart

=over 8

=item *

Updates current or named cart (see name attribute)

=back

=item *

process

=over 8

=item *

Updates an order or a search page

=back

=item *

values

=over 8

=item *

Updates user-entered fields

=back

=item *

data

=over 8

=item *

Updates database, using current B<mv_> CGI form variables, for
S<example:>

=over 12

=item *

B<mv_data_table> Table to update


=item *

B<mv_data_key> Key into table


=item *

B<mv_data_fields> Fields to update (space or null delimited)


=item *

B<mv_data_function> One of the S<following:>

=over 16

=item *

delete


=item *

update


=item *

insert


=item *

delete

=back


=item *

etc.

=back

=back

=back

I<name>

Cart name to update (if 'function=cart')

=over 4

=item *

S<Default:> current cart

=back

=head2 userdb

Summary

Parameters: B<function>

Positional parameters in same order.

B<The attribute hash reference is passed> to the subroutine after the
parameters as the last argument. B<This may mean that there are
parameters not shown here.>

Invalidates cache: B<YES>

Attribute aliases

            name ==> nickname
            table ==> db
    [userdb function other_named_attributes]

 Parameters   Description                               Default
 function                                               DEFAULT_VALUE
 name         Alias for nickname                        DEFAULT_VALUE
 table        Alias for db                              DEFAULT_VALUE

 Attributes                        Default
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [userdb function]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->userdb({
       function => VALUE
   });

or similarly with positional parameters,

    $Tag->userdb(function, $attribute_hash_reference);

Description

Interchange provides a [userdb ...] tag to access the UserDB
functions.

    [userdb
        function=function_name
        username="username"*
        password="password"*
        verify="password"*
        oldpass="old password"*
        shipping="fields for shipping save"
        billing="fields for billing save"
        preferences="fields for preferences save"
        force_lower=1
        param1=value*
        param2=value*
        hide=1
        show=1
        ...
    ]

* Optional

It is normally called in an mv_click or mv_check setting, as in:

    [set Login]
    mv_todo=return
    mv_nextpage=welcome
    [userdb function=login]
    [/set]

    <FORM ACTION="[process]" METHOD=POST>
    <INPUT TYPE=hidden NAME=mv_click VALUE=Login>
    Username <INPUT NAME=mv_username SIZE=10>
    Password <INPUT NAME=mv_password SIZE=10>
    </FORM>

There are several global parameters that apply to any use of the
userdb functions. Most importantly, by default the database table
is set to be I<userdb>. If you must use another table name, then you
should include a database=table parameter with any call to
userdb. The global parameters (default in parentheses):

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

I<function>

I<name>

I<table>

=head2 value

Returns the the current value of the named form input field.
HTML-escapes Interchange tags in the result for security.

Can also set a new value within the current page.

Summary

    [value name]
    [value name=form_var_name other_named_attributes]

 Parameters   Description                               Default
 name         This is the name of the form variable whose value you want.None

 Attributes                        Default
 set                               none
 hide                              No
 filter                            none
 keep (with filter)                No
 scratch                           No
 default                           none
 enable_html                       No
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 Yes

B<Tag expansion example:>

Assuming form variable 'foo' = 'bar',

    [value foo]
---
    bar

B<ASP-like Perl call:>

    $Tag->value( { name => var_name } );

    # or if you simply want the value:
    $Values->{var_name};

or similarly with positional parameters,

    $Tag->value($name, $attribute_hash_reference);

Description

Usage example:

   <INPUT TYPE="text" NAME="name" VALUE="[value name]">
   <INPUT TYPE="text" NAME="name" VALUE="[value name=name]">

Expands into the current value of the named customer/form input
field. When the value is returned, any Interchange tags present in the
value will be escaped. This prevents users from entering Interchange
tags in form values, which would be a serious security risk.

I<name>

This is the name of the form variable whose value you want.

I<set>

You can change a value with 'set=I<new_value>'. The tag will return
the value you set unless you also set the I<hide>=1 attribute.

Use this to "uncheck" a checkbox or set other form variable values to
defaults. If you simply want a place to store your own data, use the
set and scratch tags instead.

Note that this is only available in new-style tags, for safety
reasons.

I<hide>

Setting hide=1 suppresses the tag's return value, which can be
useful with the set attribute.

I<filter>

See the filter tag for a list of filters.

Setting 'filter="I<filter>"' modifies the named value with the
specified filter.

I<keep> (with filter)

Set keep=1 if you want the tag to return a filtered result but do
not want the filter to modify the form value itself in the $::Values
hash.

I<scratch>

Setting 'scratch=1' places a copy of the value in the $::Scratch
hash. An illustrative S<example:>

   foo is [value name=foo scratch=1] in the Values hash
   foo is now also [scratch foo] in the Scratch hash

I<default>

This sets a return value in case the named value is missing or
otherwise false. The following will expand to S<"Using default":>

    [value name=myname set=0 hide=1]
    [value name=myname default="Using default"]

I<enable_html>

Any '<' characters will normally be converted into '&lt;' for safety
reasons. This conversion can be disabled using 'enable_html=1'.

=head2 value-extended

Summary

Parameters: B<name>

Positional parameters in same order.

B<The attribute hash reference is passed> to the subroutine after the
parameters as the last argument. B<This may mean that there are
parameters not shown here.>

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine:

B<ASP-like Perl call:>

    $Tag->value_extended(
        {
         name => VALUE,
        }
    )

 OR

    $Tag->value_extended($name, $ATTRHASH);
    [value-extended name other_named_attributes]

 Parameters   Description                               Default
 name                                                   DEFAULT_VALUE

 Attributes                        Default
 umask                             none
 interpolate (reparse)             No

 Other_Characteristics             
 Invalidates cache                 YES
 Container tag                     No
 Has Subtags                       No
 Nests                             Yes

B<Tag expansion example:>

    [value-extended name]
---
    TODO: (tag result)

B<ASP-like Perl call:>

   $Tag->value_extended( { name => VALUE_name }, $body );

or similarly with positional parameters,

    $Tag->value_extended(name, $attribute_hash_reference, $body);

Description

Named call example:

   [value-extended
            name=formfield
            outfile=filename*
            umask=octal*
            ascii=1*
            yes="Yes"*
            no="No"*
            joiner="char|string"*
            test="isfile|length|defined"*
            index="N|N..N|*"
            file_contents=1*
            maxsize=length*
            elements=1*
   ]

Expands into the current value of the customer/form input field named
by field. If there are multiple elements of that variable, it will
return the value at index; by default all joined together with a
space.

If the variable is a file variable coming from a multipart/form-data
file upload, then the contents of that upload can be returned to the
page or optionally written to the outfile.

I<name>

Specify which value variable to deal with. If no other parameters are
present, then the value of the variable will be returned. If there are
multiple elements, then by default they will all be returned joined by
a space. If joiner is present, then they will be joined by its
value.

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

I<joiner>

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

I<test>

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

I<index>

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

I<file_contents>

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

I<maxsize>

The maximum file size allowed, in bytes. If a file of greater size
than maxsize is uploaded, the tag will return false and an error will
be logged.

I<outfile>

Names a file to write the contents of a file upload to. It will not
accept an absolute file name; the name must be relative to the catalog
directory. If you wish to write images or other files that would go to
HTML space, you must use the HTTP server's Alias facilities or make
a symbolic link.

I<umask>

Permission mask (in octal) to apply to the uploaded file's permission
bits. You may want to set this to make a file world-readable, or to
keep it from being group-readable. See the UNIX chmod(1) manpage for
details.

I<ascii>

To do an auto-ASCII translation before writing the outfile, set the
ascii parameter to a non-blank, non-zero value. Default is no
translation.

I<yes>

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

I<no>

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

=head1 User-defined Tags

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

   UserTag  tagname  property  value

where tagname is the name of the tag, property is the attribute
(described below), and value is the value of the property for that
tagname.

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

An alias:

    UserTag product_name Alias     data products title

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

A simple subroutine:

    UserTag company_name Routine   sub { "Your company name" }

When you place a [company-name] tag in an Interchange page, the text
Your company name will be substituted.

A subroutine with a passed text as an argument:

    UserTag caps   Routine   sub { return "\U@_" }
    UserTag caps   HasEndTag

The tag [caps]This text should be all upper case[/caps] will become
THIS TEXT SHOULD BE ALL UPPER CASE.

Here is a useful one you might wish to use:

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

Called with:

    [quick-table border=2]
    Name: [value name]
    City: [value city][if value state], [value state][/if] [value country]
    [/quick_table]

As is the case with [perl] tag, user tags run under the Perl
I<Safe.pm> module with warnings disabled. Unlike [perl] tags,
however, user tags use Perl's 'strict' pragma.

The properties for UserTag are:

=head2 Alias

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

    UserTag tagname Alias    tag to insert

An Alias is the only property that does not require a I<Routine> to
process the tag.

=head2 attrAlias

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

    UserTag tagname attrAlias   alias attr

As an example, the standard Interchange value tag takes a named
attribute of name for the variable name, meaning that [value
name=var] will display the value of form field var. If you put this
line in catalog.cfg:

    UserTag value attrAlias   identifier name

then [value identifier=var] will be an equivalent tag.

=head2 CanNest

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

    UserTag tagname CanNest

=head2 HasEndTag

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

    UserTag tagname HasEndTag

=head2 Implicit

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

    UserTag tagname Implicit attribute value

If you want to set a standard include file to a fixed value by
default, but don't want to have to specify [include
file="/long/path/to/file"] every time, you can just put:

    UserTag include Implicit file file=/long/path/to/file

and [include file] will be the equivalent. You can still specify
another value with [include file="/another/path/to/file"].

=head2 Interpolate

The behavior for this attribute depends on whether the tag is a
container (i.e. HasEndTag is defined). If it is not a container,
the Interpolate attribute causes the B<the resulting HTML> from the
UserTag to be re-parsed for more Interchange tags. If it is a
container, Interpolate causes the contents of the tag to be parsed
B<before> the tag routine is run.

    UserTag tagname Interpolate

=head2 InvalidateCache

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

    UserTag tagname InvalidateCache

It does not override [tag flag build][/tag], though.

=head2 Order

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

    UserTag tagname Order param1 param2

=head2 PosRoutine

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

=head2 Routine

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

    UserTag tagname Routine  sub { "your perl code here!" }

The routine may use a "here" document for readability:

    UserTag tagname Routine <<EOF
    sub {
        my ($param1, $param2, $text) = @_;
        return "Parameter 1 is $param1, Parameter 2 is $param2";
    }
    EOF

The usual I<here documents> caveats apply.

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

Note that the UserTag facility, combined with AllowGlobal, allows the
user to define tags just as powerful as the standard Interchange tags.
This is not recommended for the novice, though - keep it simple. 8-)

=head1 Standard Usertags

The distribution includes a number of prebuilt usertags in the
usertag directory in the Interchange software directory. Some of
these are used by the foundation catalog or its administrative
interface.

=head2 bar_button

Displays content based on current page. Could be used for building
e.g. menu bars.

Summary

    [bar-button page current]...[selected]...[/selected][/bar-button]
    [bar-button page=page current=current-page]...[selected]...[/selected][/bar-button]

B<Positional parameters: >The first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.



 Parameters   Description                               Default
 page         Name of page for which this bar-button is definednone
 current      Name of the current page                  Current page: MV_PAGE

 Other_Characteristics             
 Invalidates cache                 No
 Macro                             No
 Has end tag                       [/bar-button]

B<Tag expansion example:>

To build a simple '3-button' menu bar one could put the following on
each of the pages. The results of this code for page2 are shown below.

        <table><tr>
        [bar-button page=page1]
        <TD><A HREF="[area page1]">PAGE-1</A></TD>
        [selected]
        <TD bgcolor="red"><A HREF="[area page1]"><B>PAGE-1-selected</B></A></TD>
        [/selected]
        [/bar-button]
        [bar-button page=page2]
        <TD><A HREF="[area page2]">PAGE-2</A></TD>
        [selected]
        <TD bgcolor="red"><A HREF="[area page2]"><B>PAGE-2-selected</B></A></TD>
        [/selected]
        [/bar-button]
        [bar-button page=page3]
        <TD><A HREF="[area page3]">PAGE-3</A></TD>
        [selected]
        <TD bgcolor="red"><A HREF="[area page3]"><B>PAGE-3-selected</B></A></TD>
        [/selected]
        [/bar-button]
        </tr></table>
---
        PAGE-1    PAGE-2-selected    PAGE-3

B<ASP-like Perl call:>

    $Tag->button_bar(  { page => $page,
                     current  => $current,
                         body => $body}  );

or similarly,

    $Tag->area($page, $current, $body);

See Also

bar_link routine

Description

Displays content based on current page. The content between the
[selected][/selected] tags will be displayed only if the name of the
current page matches the name that was passed to the page parameter
(page=page-name). The default content will be displayed when there is
no match.

I<page>

The name of the page for which this definition of the bar-button is
defined.

I<current>

The name of the current page. Defaults to current page MV_PAGE.

=head2 button

=head2 convert_date

This tag converts a given date format into another format.

Summary

    [convert_date day* other_named_attributes[/convert_date]
    [convert_date day=n* other_named_attributes[/convert_date]

B<Positional parameters: >The first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.



 Parameters   Description                               Default
 days         The number of days from or before today   none

 Attributes                        Default
 format                            '%d-%b-%Y %I:%M%p' or '%d-%b-%Y'
 fmt - Alias for format            none
 raw                               none
 zerofix                           none

 Other_Characteristics             
 Invalidates cache                 No
 Macro                             No
 Has end tag                       [/convert_date]

B<Tag expansion example:>

  a. [convert-date][/convert-date]
  b. [convert-date 1][/convert-date]
  c. [convert-date -1][/convert-date]
  d. [convert-date]2001-5-1[/convert-date]
  e. [convert-date]2001-05-01[/convert-date]
  f. [convert-date]20010515[/convert-date]
  g. [convert-date raw=1]2001-05-18[/convert-date]
  h. [convert-date fmt="%d-%m-%Y"]2001-05-18[/convert-date]
  i. [convert-date]200 1 -  --051 =9[/convert-date]
  j. [convert-date]2001 -  --05 -20 11 1 5[/convert-date]
  k. [convert-date raw=1]2001-05-21 11:15[/convert-date]
---
  a. 18-May-2001 03:15AM (todays day and time)
  b. 19-May-2001 03:15AM (today + 1 day)
  c. 17-May-2001 03:15AM (today - 1 day)
  d. 01-May-2001
  e. 01-May-2001
  f. 15-May-2001
  g. 20010518
  h. 18-05-2001
  i. 19-May-2001
  j. 20-May-2001 11:15AM
  k. 200105211115

B<ASP-like Perl call:>

    $Tag->convert_date( { days => 1 } );

    $Tag->convert_date( { body => "2001-05-19 15:35",
                       format => "%d-%m-%Y %H:%M", } );

or similarly with positional parameters,

    $Tag->convert_date( 1 );

Description

This tag converts almost any given date format into another, possibly
user defined, format.

I<days>

Number of days from or before today's date and time. Will only be used
if nothing is supplied between the tags.

I<format>

POSIX time format string of your choice. See Unix strftime(3) manpage
for complete details.

I<raw>

If this option is set to true, will display given date in raw format,
e.g. yyyymmdd or yyyymmddHHMM.

I<zerofix>

Strips leading zeroes from numbers.

=head2 db_date

This tag returns the time of last access of the database source file.

Summary

    [db_date table* format*]

B<Positional parameters: >The first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.



 Parameters   Description                               Default
 table        Table name.                               products
 format       POSIX time format string                  %A %d %b %Y

 Other_Characteristics             
 Invalidates cache                 No
 Macro                             No
 Has end tag                       No

B<Tag expansion example:>

    [db-date]
    [db-date cat]
    [db-date table=cat format="%d %b %Y"]
---
    Wednesday 02 May 2001 (products.txt)
    Wednesday 03 May 2001 (cat.txt)
    03 May 2001 (cat.txt)

B<ASP-like Perl call:>

    $Tag->db_date( { table => cat,
                    format => "%d %b %Y", } );

or similarly with positional parameters,

    $Tag->db_date( "cat", "%d %b %Y" );

Description

This tag returns the time of last access of the database source file.

I<table>

Table name. Defaults to products if not specified.

I<format>

POSIX time format string. See Unix strftime(3) manpage for details.
Defaults to '%A %d %b %Y' when not specified.

=head2 delete_cart

This tag deletes a cart from the userdb.

Summary

    [delete_cart nickname]
    [delete_cart nickname="cart-name"]

B<Positional parameters: >The first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.



 Parameters   Description                               Default
 nickname     Must be an existing nickname              none

 Other_Characteristics             
 Invalidates cache                 No
 Macro                             No
 Has end tag                       No

B<Tag expansion example:>

    [delete_cart mycart]
    [delete_cart nickname="mycart"]

B<ASP-like Perl call:>

    $Tag->delete_cart( { nickname => "mycart", } );

or similarly with positional parameters,

    $Tag->delete_cart( "mycart" );

See Also

I<userdb>, I<load_cart>, I<save_cart> and pages
templates/components/saved_carts_list_small, pages/saved_carts.html
for more examples.

Description

Deletes a cart with name nickname from the user database. Basically
the same as [userdb function=delete_cart nickname=mycart].

I<nickname>

Nickname of cart to be deleted.

=head2 email

This tag takes a recipient address and a body text and uses the
SendmailProgram with -t option to send email.

Summary

    [email to subject* reply* from* extra*]Your message[/email]
    [email to=to_address subject=subject reply=reply_address
        from=from_address extra=extra_headers]Your message[/email]

B<Positional parameters: >The first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.



 Parameters   Description                               Default
 to           Email address of recipient                none
 subject      Subject line                              String: <no subject>
 reply        Email address to be used for the reply-to headernone
 from         Senders email address                     First address in MailOrderTo configuration variable
 extra        Additional headers to be included         none

 Other_Characteristics             
 Invalidates cache                 No
 Macro                             No
 Has end tag                       [/email]

B<Tag expansion example:>

    [email
           to="foo@bar.com"
      subject="Greetings"
         from="bar@foo.com"
    ]
    Hello World
    [/email]

B<ASP-like Perl call:>

    $Tag->email(  { to => $to,
                  from => $from,
               subject => $subject,
                 reply => $reply,
                 extra => $extra,
                  body => $body }  );

or similarly,

    $Tag->email($to, $subject, $reply, $from, $extra, $body);

See Also

I<email_raw> and etc/mail_receipt, pages/process_return.html,
pages/stock-alert-added.html for examples.

Description

Will send the content between the [email][/email] tags as an email to
the recipient (to) using the SendmailProgram with -t option.

extra

Extra headers to be included. Example: Errors-To:
errors@yourdomain.com

from

Email address identifying the sender of the message. Will use the
first email address of the MailOrderTo configuration variable if it is
not supplied.

reply

Email address to be used for the Reply-to header. No Reply-to header
will be present if this parameter is omitted.

subject

Short text describing the content of the message. The Subject line of
an email message. The string <no subject> will be substituted if this
parameter is omitted.

to

Valid email address(es) of the recipient(s). This parameter is
required.

=head2 email_raw

This tag takes a raw email message, B<including headers>, and uses the
SendmailProgram with -t option.

Summary

    [email_raw]Your message including headers[/email_raw]

 Other_Characteristics             
 Invalidates cache                 No
 Macro                             No
 Has end tag                       [/email_raw]

B<Tag expansion example:>

    [email_raw]
From: foo@bar.com
To: bar@foo.com
Subject: baz

The text of the message.
    [/email_raw]

The headers must be at the beginning of the line, and the header must
have a valid To: or it will not be delivered.

B<ASP-like Perl call:>

    $Tag->email_raw(  { body => $body }  );

or similarly,

    $Tag->email_raw($body);

See Also

I<email>

Description

Will send the content between the [email_raw][/email_raw] tags as a
raw email message to the recipient specified in the supplied headers
using the SendmailProgram with -t option.

=head2 fedex_query

=head2 formel

=head2 fortune

This tag uses the fortune(1) command to display a random saying.

 Options:

        short=yes|no* Select only short (< 160 chars) fortunes
        a=1           Select from all fortunes, even potentially offensive ones.
        o=1           Select only from potentially offensive fortunes.
        raw=1         Don't do any HTML formatting

Example:

        [fortune short=yes]


=head2 get-url

Fetch a URL and return the contents.

Summary

    [get-url url]
    [get-url url="valid-url" strip=1*]

B<Positional parameters: >The first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.



 Parameters   Description                               Default
 url          Must be a valid URL. Meaning, you have to supply the protocol.  Examplehttp://demo.icdevgroup.org/ftp://ftp.icdevgroup.org/none

 Attributes                        Default
 strip                             none

 Other_Characteristics             
 Invalidates cache                 No
 Macro                             No
 Has end tag                       No

B<Tag expansion example:>

    [get-url http://demo.icdevgroup.org/]
    [get-url url="http://demo.icdevgroup.org/" strip=1]

B<ASP-like Perl call:>

    $Tag->get_url( { url => "http://demo.icdevgroup.org/", } );

    $Tag->get_url( { url => "http://demo.icdevgroup.org/",
                   strip => 1, } );

or similarly with positional parameters,

    $Tag->get_url( "http://demo.icdevgroup.org/" );

Description

Uses the LWP libraries (LWP::Simple) to fetch a URL and returns the
contents.

I<strip>

If the strip option is set, strips everything up to <body> and
everything after </body>.

I<url>

Must be a valid URL (including protocol).

=head2 load_cart

This tag loads a cart by name from the userdb.

Summary

    [load_cart nickname]
    [load_cart nickname="cart-name"]

B<Positional parameters: >The first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.



 Parameters   Description                               Default
 nickname     Must be an existing nickname.Nickname is constructed from:a name parttime modified (time the cart was saved by save_cart tag)type (c for cart, r for recurring)none

 Other_Characteristics             
 Invalidates cache                 No
 Macro                             No
 Has end tag                       No

B<Tag expansion example:>

    [load_cart mycart:990102732:c]
    [load_cart nickname="mycart:990102732:c"]

B<ASP-like Perl call:>

    $Tag->load_cart( { nickname => "mycart:990102732:c", } );

or similarly with positional parameters,

    $Tag->load_cart( "mycart:990102732:c" );

See Also

I<userdb>, I<delete_cart>, I<save_cart> and pages
templates/components/saved_carts_list_small, pages/saved_carts.html
for more examples.

Description

Loads a cart with name nickname from the user database. It will be
merged with the current cart. Basically the same as [userdb
function=get_cart nickname=cartname merge=1].

I<nickname>

Nickname of cart to be loaded. See above.

=head2 loc

=head2 rand

=head2 reconfig

=head2 reconfig_time

=head2 reconfig_wait

=head2 save_cart

This tag saves the current cart or recurring order in the userdb under
a given name.

Summary

    [save_cart nickname recurring]
    [save_cart nickname="cart-name" recurring=1]

B<Positional parameters: >The first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.



 Parameters   Description                               Default
 nickname     Label for the cart.                       none
 recurring    Set to true if recurring. Set to false, or omit if cart.none

 Other_Characteristics             
 Invalidates cache                 No
 Macro                             No
 Has end tag                       No

B<Tag expansion example:>

    [save_cart mycart]
    [save_cart nickname=mycart recurring=1]

B<ASP-like Perl call:>

    $Tag->save_cart( { nickname => mycart,
                      recurring => 1, } );

or similarly with positional parameters,

    $Tag->save_cart( "mycart", "1" );

See Also

I<userdb>, I<delete_cart>, I<load_cart> and pages
templates/components/saved_carts_list_small, pages/saved_carts.html
for more examples.

Description

Saves the current cart with name nickname in the user database.
Basically the same as [userdb function=set_cart nickname=cartname]

I<nickname>

Nickname for the current cart to be saved. You can use same nickname
for different carts. An index will be added if there are more carts
with the same nickname.

I<recurring>

Set to true if recurring. Set to false, or simply omit it, if it is a
cart.

=head2 summary

This tag calculates column totals.

Summary

    [summary amount]
    [summary amount=n.nn other_named_attributes]

B<Positional parameters: >The first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.



 Parameters   Description                               Default
 amount       Numerical value to be added to previous totalnone

 Attributes                        Default
 currency                          none
 format                            none
 hide                              none, no hiding
 name                              ONLY0000, internal use only
 reset                             none
 total                             none

 Other_Characteristics             
 Invalidates cache                 No
 Macro                             No
 Has end tag                       No

B<Tag expansion example:>

    [loop list="10 20 30.5"]
        [summary amount="[loop-code]" hide=1]
    [/loop]
    [summary total=1 format="%.3f"]
    [summary total=1 currency=1]
---
    60.500
    $60.50

B<ASP-like Perl call:>

    $Tag->summary( { amount => 10.5,
                       hide => 1, } );

    $Tag->summary( { amount => 25,
                       name => mytotal,
                   currency => 1, } );

or similarly with positional parameters,

    $Tag->summary( 10.5, $attribute_hash_reference );

See Also

templates/components/cart, pages/ord/checkout.html for more examples.

Description

The summary tag provides you with an easy way to calculate and display
totals. The display of the amounts is fully customizable. You can hide
display, or you can show the amounts with the proper currency
formatting according to the locale, or you can define your own
formatting. Any number of summaries can be kept on a page.

I<currency>

The amount or total will be displayed according to the currency
formatting of the current locale if this attribute is set to true (non
blank or zero).

I<format>

You can choose any formatting of the amount you like. Just set the
format attribute to the desired formatting string (%s, %.2f etc.).
When both, currency and format attributes are set, the format
attribute will take precedence. So it doesn't make much sense to set
them both at the same time.

I<hide>

Will suppress the display of amount when set to true.

I<name>

You can calculate as many totals as you like on the same page. Just
supply a different label for each summary.

I<reset>

Will erase the total(s) if set to true. Be careful tough. It will
reset ALL totals when you have no name attribute supplied. If you have
provided a label for the name attribute then it will only reset the
total for that particular label. All others won't be touched.

I<total>

Will show the total instead of the amount if set to true.

=head2 table_organize

Takes an unorganized set of table cells and organizes them into rows
based on the number of columns.

Summary

    [table-organize cols* other_named_attributes]
             [loop ....] <td> [loop-tags] </td> [/loop]
        [/table-organize]

    [table-organize cols=n* other_named_attributes]
             [loop ....] <td> [loop-tags] </td> [/loop]
        [/table-organize]

B<Positional parameters: >The first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.



 Parameters   Description                               Default
 cols         Number of columns.                        2
 columns      Alias for cols.                           2

 Attributes                        Default
 caption                           none
 columnize                         none
 embed                             none
 filler                            &nbsp;
 limit                             none
 pretty                            none
 rows                              none
 table                             none
 td                                none
 tr                                none

 Other_Characteristics             
 Invalidates cache                 No
 Macro                             No
 Has end tag                       [/table-organize]

B<Tag expansion example:>

This example produces a table that (1) alternates rows with background
colors "#EEEEEE" and "#FFFFFF", and (2) aligns the columns right,
center, left:

        [table-organize
            cols=3
            pretty=1
            tr.0='bgcolor="#EEEEEE"'
            tr.1='bgcolor="#FFFFFF"'
            td.0='align=right'
            td.1='align=center'
            td.2='align=left'
        ]
            [loop list="1 2 3 1a 2a 3a 1b"] <td> [loop-code] </td> [/loop]
        [/table-organize]
---
        <tr bgcolor="#EEEEEE">
                <td align=right>1</td>
                <td align=center>2</td>
                <td align=left>3</td>
        </tr>
        <tr bgcolor="#FFFFFF">
                <td align=right>1a</td>
                <td align=center>2a</td>
                <td align=left>3a</td>
        </tr>
        <tr bgcolor="#EEEEEE">
                <td align=right>1b</td>
                <td align=center>&nbsp;</td>
                <td align=left>&nbsp;</td>
        </tr>

If the attribute columnize=1 is present, the result will look like:

            <tr bgcolor="#EEEEEE">
                    <td align=right>1</td>
                    <td align=center>1a</td>
                    <td align=left>1b</td>
            </tr>
            <tr bgcolor="#FFFFFF">
                    <td align=right>2</td>
                    <td align=center>2a</td>
                    <td align=left>&nbsp;</td>
            </tr>
            <tr bgcolor="#EEEEEE">
                    <td align=right>3</td>
                    <td align=center>3a</td>
                    <td align=left>&nbsp;</td>
            </tr>

See the source for more ideas on how to extend this tag.

B<ASP-like Perl call:>

    $Tag->table_organize( { cols => 3,
                            pretty => 1, }, $BODY );

or similarly with positional parameters:

    $Tag->table_organize( $cols, $attribute_hash_reference, $BODY );

See Also

pages/flypage.html, pages/quantity.html,
templates/components/best_horizontal, templates/components/cart,
templates/components/cross_horizontal, templates/components/random,
templates/components/random_vertical, templates/components/upsell

Description

Takes an unorganized set of table cells and organizes them into rows
based on the number of columns; it will also break them into separate
tables.

If the number of cells are not on an even modulus of the number of
columns, then "filler" cells are pushed on.

I<cols (or columns)>

Number of columns. This argument defaults to 2 if not present.

I<rows>

Optional number of rows. Implies "table" parameter.

I<table>

If present, will cause a surrounding <TABLE> </TABLE> pair with the
attributes specified in this option.

I<caption>

Table <CAPTION> container text, if any. Can be an array.

I<td>

Attributes for table cells. Can be an array.

I<tr>

Attributes for table rows. Can be an array.

I<columnize>

Will display cells in (newspaper) column order, i.e. rotated.

I<pretty>

Adds newline and tab characters to provide some reasonable indenting.

I<filler>

Contents to place in empty cells put on as filler. Defaults to
"&nbsp;".

I<limit>

Maximum number of cells to use. Truncates extra cells silently.

I<embed>

If you want to embed other tables inside, make sure they are called
with lower case <td> elements, then set the embed tag and make the
cells you wish to organize be <TD> elements. To switch that sense, and
make the upper-case or mixed case be the ignored cells, set the embed
parameter to "lc".

    [table-organize embed=lc]
                <td>
                        <TABLE>
                                <TR>
                                <TD> something
                                </TD>
                                </TR>
                        </TABLE>
                </td>
    [/table-organize]

or

    [table-organize embed=uc]
                <TD>
                        <table>
                                <tr>
                                <td> something
                                </td>
                                </tr>
                        </table>
                </TD>
    [/table-organize]

The "tr", "td", and "caption" attributes can be specified with
indexes; if they are, then they will alternate according to the
modulus.

The "td" option array size should probably always equal the number of
columns; if it is bigger, then trailing elements are ignored. If it is
smaller, no attribute is used.

=head2 title_bar

Creates a quick title bar.

Summary

    [title-bar width size color]My title[/title-bar]
    [title-bar width=600 size=5 color="#ff0000"]My title[/title-bar]

B<Positional parameters: >The first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.



 Parameters   Description                               Default
 color        Background color the bar.Defaults tovariable HEADERBG or#444444HEADERBG or #444444
 size         Font size                                 6
 width        Width of the title bar                    500

 Other_Characteristics             
 Invalidates cache                 No
 Macro                             No
 Has end tag                       [/title-bar]

B<Tag expansion example:>

    [title-bar 600 5 red]My title[/title-bar]
    [title-bar width=600 size=5 color="#ff0000"]My title[/title-bar]

B<ASP-like Perl call:>

    $Tag->title_bar( { body => "My Title", } );

    $Tag->title_bar( { width => 400,
                       color => "#0000ff",
                        body => "My title", } );

or similarly with positional parameters,

    $Tag->title_bar( 600, 5, "red", "My title" );

Description

Quickly adds a title bar to your pages without having to type the html
each time. Background color, width of the bar and size of the text can
be customized by setting the appropriate parameter. The text color
defaults to variable HEADERTEXT or when its not present to white.

I<color>

Sets the background color of the bar. You can set the color as 'red',
'#ff0000', or 'bgcolor="#ff0000"'.

I<size>

Determines the size of the text. Parameter should be set to a value
accepted by the HTML <font> tag size attribute.

I<width>

Sets the width of the bar.

=head2 ups_query

=head2 usertrack

=head2 var

=head2 xml-generator

This is a quick and dirty tag that generates XML tags based upon one
of two types of data (delimited and session).

Summary

    [xml-generator type* other_named_attributes][/xml-generator]
    [xml-generator type=value* other_named_attributes][/xml-generator]
    [xml-generator type=value* other_named_attributes][][/xml-generator]

*Optional

B<Positional parameters: >The first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.



 Parameters   Description                               Default
 type         Data type. Delimited or session           delimited

 Attributes                        Default
 attributes                        none
 dbdump                            none
 delimiter                         \t
 field_names                       &nbsp;
 separator                         \n
 toplevel_tag                      'table' for delimited type and 'session' for other type
 record_tag                        record
 field_tag                         field
 key_name                          none
 spacer                            [\s,]+
 no_second                         none
 skip_empty                        none

 Other_Characteristics             
 Invalidates cache                 No
 Macro                             No
 Has end tag                       [/xml-generator]

B<Tag expansion example:>

    [xml-generator type=delimited
             attributes="date"
                   date="[tag time]%d-%b-%Y[/tag]"
           toplevel_tag=products
    ]code       description     price
        [query list=1
                        sql="select sku, description, price from products"
                        prefix=xml][xml-code]  [xml-param description] [xml-param price]
        [/query]
    [/xml-generator]
---
    <products date="18-May-2001">
            <record key="os28113">
                    <code>os28113</code>
                    <description>The Claw Hand Rake</description>
                    <price>14.99</price>
            </record>
            <record key="os28006">
                    <code>os28006</code>
                    <description>Painters Brush Set</description>
                    <price>29.99</price>
            </record>
            ...
    </products>

B<ASP-like Perl call:>

    $Tag->xml_generator( {type => delimited,
                      toplevel_tag => apex,  }, $BODY );


or similarly with positional parameters,

    $Tag->xml_generator( $type, $attribute_hash_reference, $BODY );

Description

I<type>

delimited

Accepts a delimited and separated (default is TAB delimiter and
newline separator) list of records such as that generated by an
'[item-list]', '[sql]', or '[loop search=""]' ITL tag.

session

When the type is not delimited, it can contain any hash reference into
the Interchange session. Examples are:

        values       The form values
        scratch      Scratch values
        errors       Error values
        other        Any other Session key, for example "source" for
                     [data session source]

If the value is a hash, then it will be sent as an XML record with the
top level equal to "session", and a second_level tag equal to the hash
name, and keys as separate XML container tags. If the parameter "that
is equal to the type" is given, only those fields will be shown.
Otherwise the entire hash will be shown. For example, this tag:

        [xml-generator type="values" values="fname lname"][/xml-generator]

will generate:

        <session>
                <values>
                        <fname>First</fname>
                        <lname>Last</lname>
                </values>
        </session>

if it is a scalar, then only the second level will be done:

        [xml-generator type="cybercash_id"][/xml-generator]

will do the equivalent of:

        <session>
                <cybercash_id>[data session cybercash_id]</cybercash_id>
        </session>

So bringing it all together, the following:

        [xml-generator type="values scratch source"
                       values="fname lname"
                       scratch="downloads"][/xml-generator]
will generate:

        <session>
                <values>
                        <fname>First</fname>
                        <lname>Last</lname>
                </values>
                <scratch>
                        <downloads>0</downloads>
                </scratch>
                <source>Partner1</source>
        </session>

I<no_second>

Prevents the second-level tags from being generated. Extending the
last example in the "session" type above, this

        [xml-generator  type="values scratch source"
                        no_second=1
                        values="fname lname"
                        scratch="downloads"][/xml-generator]
will generate:

        <session>
                <fname>First</fname>
                <lname>Last</lname>
                <downloads>0</downloads>
                <source>Partner1</source>
        </session>

I<attributes>

The attributes (if any) to pass on to the top level tag. For instance,

    [xml-generator
          attributes="date"
                date="[tag time]%d-%b-%Y[/tag]"
        toplevel_tag=order
    ][/xml-generator]

will generate a toplevel tag pair of:

        <order date="18-Mar-2001">
        </order>

I<dbdump>

Will dump all tables in the catalog when this attribute is set true.
Used attributes are "toplevel_tag", "record_tag", "field_tag", and
"skip_empty" or default values ('table', 'record', 'field'
respectively).

 Output format:
    <database name="catalogname">
        <toplevel_tag name="tablename1">
            <record_tag key="value of first field-1">
                <field_tag name="fieldname1">fieldvalue1</field_tag>
                <field_tag name="fieldname2">fieldvalue2</field_tag>
                        </record_tag>
            <record_tag key="value of first field-2">
                <field_tag name="fieldname1">fieldvalue1</field_tag>
                <field_tag name="fieldname2">fieldvalue2</field_tag>
                        </record_tag>
                </toplevel_tag>
        <toplevel_tag name="tablename2">
            <record_tag key="value of first field-1">
                <field_tag name="fieldname1">fieldvalue1</field_tag>
                <field_tag name="fieldname2">fieldvalue2</field_tag>
                        </record_tag>
                </toplevel_tag>
        </database>

B<Important note:> All tables are read into memory. So be warned, this
could be a real memory hog.

Ton Verhagen's proposal:

=over 4

=item 1.

Add option to select tables. E.g. dump_tables="products cat area"
and/or

=item 2.

Add option to select an output file. E.g. dump_file="tabledump.XML".
Send output to file line by line.

=back

I<delimiter>

Character used as delimiter of fields in delimited data type. Defaults
to a tab character.

I<field_names>

Space or comma-delimited list of field names to be used for delimited
data type. Should be in the same order as in the data list provided
(between the tags).

Another way of providing the field names would be:

    [xml-generator .....]fieldname-1    fieldname-2     fieldname-3
        [field value list
         delimited by option delimiter and
         separated by option separator][/xml-generator]

B<Note: >Field name list B<must> be tab delimited.

Ton Verhagen's humble opinion: This should change in future versions!
Use option delimiter instead.

I<separator>

Character used as line separator in list between
[xml-separator][xml-separator] tags and in output 'session' data type.
Defaults to a newline, "\n".

I<toplevel_tag>

The toplevel tag name to use. Defaults to "table" for the 'dbdump
mode' and delimited type, and "session" for the other.

I<record_tag>

Defines the tag name for the record tag. Defaults to 'record'. Used
for 'dbdump mode' and delimited type.

I<field_tag>

Defines the tag name for the field tag. Defaults to 'field'. Only used
in 'dbdump mode'.

I<key_name>

Only used in delimited data type. Defines fieldname to determine key
value in "record_tag".

    <record_tag key="value of field with name defined by key_name"> ....

I<spacer>

Character used as delimiter in type parameter definition and
corresponding attributes. Defaults to '[\s,]+' (one or more whitespace
or comma).

    [xml-generator type="values|scratch"
                 values="value1|value2"
                scratch="scratch1|scratch2"
                 spacer="|"
    ][/xml-generator]

I<skip_empty>

Only used in I<dbdump> mode (dbdump=1). Will skip empty fields if this
attribute is set true.

Template Parsing Order

Standard Parsing

Under normal circumstances, the template page containing tags and HTML
is parsed in the following order:

=over 4

=item 1.

Any content in MV_AUTOLOAD is prepended to the template page.

=over 8

=item

I<>

=back

I<>

=item 2.

Any [pragma] tags anywhere in the text are processed, and the
specified pragmas are set.

=over 8

=item *

Since [pragma] tags are preprocessed before any other content,
reparse will not catch them, nor will they work if included in
variables. Also, the specified pragma will apply to the entire
template (not just the section after the tag).

=item *

If you want to apply a pragma with a variable or only to part of a
document, you must use [tag pragma="..."] instead.

=back

I<>

=item 3.

Variables (macros) are processed in the following order:

=over 8

=item 4.

@@VARNAME@@ global variables

=item 5.

@_VARNAME_@ local or global variables

=item 6.

__VARNAME__ local variables

=back

I<>

=item 7.

Interchange comments are stripped.

=over 8

=item

I<>

=back

I<>

=item 8.

False-endtag macros are expanded (e.g., [/page] and [/order]).

=over 8

=item

I<>

=back

I<>

=item 9.

'<!--[tagname]-->' escapes are converted to [tagname]

=over 8

=item *

This can be a convenience for your HTML editor if it has trouble with
tags using the standard [tagname] syntax.

=item *

However, if you want to HTML-comment out an Interchange tag in content
that will be fed raw to a browser, you must include whitespace between
the HTML comment delimiters and the tag, like this, '<!--  [tagname] 
-->'.

=back

I<>

=item 10.

The main tag parser is called.

=over 8

=item *

Some tags parse recursively (depending upon reparse and
interpolate settings, of course).

=item *

Some tags (e.g., [loop]) process PREFIX-tags in their contained
body text. Hence, the PREFIX-tags are not handled recursively.

=item *

Some tags are interpreted in the lib/Vend/Parse.pm:start routine. You
cannot call them with the '$Tag->I<tagname>()' syntax. They S<are:>

=over 12

=item *

The [goto] tag. Note also that the [goto] tag handles the
[label] tag.


=item *

The [bounce] tag.

=back

=back

I<>

=item 11.

Image paths substitution on the HTML output occurs.

=over 8

=item

I<>

=back

I<>

=back

Nonstandard parsing within the admin interface

Parsing of content via the specialized [regenerate] usertag
included with the administrative interface does not obey the above
order. The MV_AUTOLOAD and '<!--[tagname]-->' escapes are skipped.
There are some other more subtle differences as well; in the very
unlikely event that you need to check this in the source code, compare
the 'interpolate_html' and 'cache_html' routines in Interpolate.pm.

Nonstandard parsing of Subtags

Subtags are parsed within the containing array-list or hash-list
context created by the containing tag (see I<Looping tags and
Sub-tags>).

=over 4

=item *

All subtags at an earlier precedence level are treated before any in
the next level.

=item *

Within the same level, tags are processed in the order the appear on
the page.

=item *

Any standard tags are processed during 'interpolate' (before) or
'reparse' (after) phases of processing the containing tag.

=back

B<Technical note>

Processing within a hash- or array-list is actually done as a series
of global regular expression substitutions on the page. Each
substitution replaces one tag with the output of the subroutine(s)
associated with it.



In array-list context, subtags are processed in the following
S<order:>

=over 4

=item 1.

Check for PREFIX-B<line> and prepare for it if present (does not
process PREFIX-B<line> at this time)

=item 2.

PREFIX-B<sub> definitions processed

=item 3.

B<if>-PREFIX-I<*> nesting resolved

=item 4.

PREFIX-B<alternate> processed

=item 5.

B<if>-PREFIX-B<param>  processed

=item 6.

B<if>-PREFIX-B<pos>  processed

=item 7.

PREFIX-B<pos>  processed

=item 8.

B<if>-PREFIX-B<field>  processed

=item 9.

PREFIX-B<line>  processed

=item 10.

PREFIX-B<increment>  processed

=item 11.

PREFIX-B<accessories>  processed

=item 12.

PREFIX-B<options>  processed

=item 13.

PREFIX-B<code>  processed

=item 14.

PREFIX-B<description>  processed

=item 15.

PREFIX-B<field>  processed

=item 16.

PREFIX-B<price>  processed

=item 17.

PREFIX-B<change>  processed

=item 18.

PREFIX-B<calc>  processed

=item 19.

PREFIX-B<exec>  processed

=item 20.

PREFIX-B<filter>  processed

=item 21.

PREFIX-B<last>  processed

=item 22.

PREFIX-B<next>  processed

=item 23.

User's previous HTML widget SELECTED settings restored

=item 24.

Reparse standard tags in output of above (if reparse enabled for the
containing tag)

=back

In hash-list context, subtags are processed in the following S<order:>

=over 4

=item 1.

PREFIX-B<sub> definitions processed

=item 2.

B<if>-PREFIX-I<*> nesting resolved

=item 3.

PREFIX-B<alternate> processed

=item 4.

PREFIX-B<line>  processed

=item 5.

B<if>-PREFIX-B<param>  processed

=item 6.

B<if>-PREFIX-B<field>  processed

=item 7.

B<if>-PREFIX-B<modifier>  processed (B<if>-PREFIX-B<param> and
B<if>-PREFIX-B<modifier> are functionally identical except for parse
order)

=item 8.

PREFIX-B<increment>  processed

=item 9.

PREFIX-B<accessories>  processed

=item 10.

PREFIX-B<options>  processed

=item 11.

PREFIX-B<sku>  processed

=item 12.

PREFIX-B<code>  processed

=item 13.

PREFIX-B<quantity>  processed

=item 14.

PREFIX-B<modifier>  processed

=item 15.

PREFIX-B<param>  processed

=item 16.

PREFIX-B<quantity-name>  processed

=item 17.

PREFIX-B<modifier-name>  processed

=item 18.

PREFIX-B<subtotal>  processed

=item 19.

PREFIX-B<discount-subtotal>  processed

=item 20.

PREFIX-B<code>  processed again differently (operating on new
instances of PREFIX-B<code> in output of above?)

=item 21.

PREFIX-B<field>  processed

=item 22.

PREFIX-B<description>  processed

=item 23.

PREFIX-B<price>  processed

=item 24.

PREFIX-B<discount-price>  processed

=item 25.

PREFIX-B<difference>  processed

=item 26.

PREFIX-B<discount>  processed

=item 27.

PREFIX-B<change>  processed

=item 28.

PREFIX-B<tag>  processed (*** CHECK THIS TAG NAME ***)

=item 29.

PREFIX-B<calc>  processed

=item 30.

PREFIX-B<exec>  processed

=item 31.

PREFIX-B<filter>  processed

=item 32.

PREFIX-B<last>  processed

=item 33.

PREFIX-B<next>  processed

=item 34.

User's previous HTML widget SELECTED settings restored

=item 35.

Reparse standard tags in output of above (if reparse enabled for the
containing tag)

=back

Search and Form Variables

Variable Names

I<other>

 Name                scan   Type   Description
 mv_all_chars        ac     S      Turns on punctuation matching
 mv_arg[0-9]+               A      Parameters for mv_subroutine (mv_arg0,mv_arg1,...)
 mv_base_directory   bd     S      Sets base directory for search file names
 mv_begin_string     bs     S      Pattern must match beginning of field
 mv_case             cs     S      Turns on case sensitivity
 mv_cartname                O      Sets the shopping cart name
 mv_check                   A      Any form, sets multiple user variables after update
 mv_click                   A      Any form, sets multiple form variables before update
 mv_click                   XA     Default mv_click routine, click is mv_click_arg
 mv_click name              XA     Routine for a click name, sends click as arg
 mv_click_arg               XA     Argument name in scratch space
 mv_coordinate       co     S      Enables field/spec matching coordination
 mv_column_op        op     S      Operation for coordinated search
 mv_credit_card*            O      Discussed in order security (some are read-only)
 mv_dict_end         de     S      Upper bound for binary search
 mv_dict_fold        df     S      Non-case sensitive binary search
 mv_dict_limit       di     S      Sets upper bound based on character position
 mv_dict_look        dl     S      Search specification for binary search
 mv_dict_order       do     S      Sets dictionary order mode
 mv_doit                    A      Sets default action
 mv_email                   O      Reply-to address for orders
 mv_exact_match      em     S      Sets word-matching mode
 mv_failpage         fp     O,S    Sets page to display on failed order check/search
 mv_field_file       ff     S      Sets file to find field names for Glimpse
 mv_field_names      fn     S      Sets field names for search, starting at 1
 mv_first_match      fm     S      Start displaying search at specified match
 mv_head_skip        hs     S      Sets skipping of header line(s) in index
 mv_index_delim      id     S      Delimiter for search fields (TAB default)
 mv_matchlimit       ml     S      Sets match page size
 mv_max_matches      mm     S      Sets maximum match return
 mv_min_string       ms     S      Sets minimum search spec size
 mv_negate           ne     S      Records NOT matching will be found
 mv_nextpage         np     A      Sets next page user will go to
 mv_numeric          nu     S      Comparison numeric in coordinated search
 mv_order_group             O      Allows grouping of master item/sub item
 mv_order_item              O      Causes the order of an item
 mv_order_number            O      Order number of the last order (read-only)
 mv_order_quantity          O      Sets the quantity of an ordered item
 mv_order_profile           O      Selects the order check profile
 mv_order_receipt           O      Sets the receipt displayed
 mv_order_report            O      Sets the order report sent
 mv_order_subject           O      Sets the subject line of order email
 mv_orsearch         os     S      Selects AND/OR of search words
 mv_profile          mp     S      Selects search profile
 mv_record_delim     dr     S      Search index record delimiter
 mv_return_all       ra     S      Return all lines found (subject to range search)
 mv_return_delim     rd     S      Return record delimiter
 mv_return_fields    rf     S      Fields to return on a search
 mv_return_file_name rn     S      Set return of file name for searches
 mv_return_spec      rs     S      Return the search string as the only result
 mv_save_session            C      Set to non-zero to prevent expiration of user session
 mv_search_field     sf     S      Sets the fields to be searched
 mv_search_file      fi     S      Sets the file(s) to be searched
 mv_search_line_returnlr    S      Each line is a return code (loop search)
 mv_search_match_count      S      Returns the number of matches found (read-only)
 mv_search_page      sp     S      Sets the page for search display
 mv_searchspec       se     S      Search specification
 mv_searchtype       st     S      Sets search type (text, glimpse, db or sql)
 mv_separate_items          O      Sets separate order lines (one per item ordered)
 mv_session_id       id     A      Suggests user session id (overridden by cookie)
 mv_shipmode                O      Sets shipping mode for custom shipping
 mv_sort_field       tf     S      Field(s) to sort on
 mv_sort_option      to     S      Options for sort
 mv_spelling_errors  er     S      Number of spelling errors for Glimpse
 mv_substring_match  su     S      Turns off word-matching mode
 mv_successpage             O      Page to display on successful order check
 mv_todo                    A      Common to all forms, sets form action
 mv_todo.map                A      Contains form imagemap
 mv_todo.checkout.x         O      Causes checkout action on click of image
 mv_todo.return.x           O      Causes return action on click of image
 mv_todo.submit.x           O      Causes submit action on click of image
 mv_todo.x                  A      Set by form imagemap
 mv_todo.y                  A      Set by form imagemap
 mv_unique           un     S      Return unique search results only
 mv_value            va     S      Sets value on one-click search (va=var=value)

Abbreviations

The two-letter abbreviations are mapped with these letters:

 Abbr  Long name
 DL    mv_raw_dict_look
 MM    mv_more_matches
 ac    mv_all_chars
 ar    mv_arg
 bd    mv_base_directory
 bs    mv_begin_string
 ck    mv_cache_key
 co    mv_coordinate
 cs    mv_case
 cv    mv_verbatim_columns
 de    mv_dict_end
 df    mv_dict_fold
 di    mv_dict_limit
 dl    mv_dict_look
 do    mv_dict_order
 dr    mv_record_delim
 em    mv_exact_match
 er    mv_spelling_errors
 fi    mv_search_file
 fm    mv_first_match
 fn    mv_field_names
 hs    mv_head_skip
 id    mv_session_id
 il    mv_index_delim
 ix    mv_index_delim
 lb    mv_search_label
 lo    mv_list_only
 lr    mv_line_return
 lr    mv_search_line_return
 ml    mv_matchlimit
 mm    mv_max_matches
 mp    mv_profile
 ms    mv_min_string
 ne    mv_negate
 np    mv_nextpage
 nu    mv_numeric
 op    mv_column_op
 os    mv_orsearch
 pc    mv_pc
 ra    mv_return_all
 rd    mv_return_delim
 rf    mv_return_fields
 rn    mv_return_file_name
 rr    mv_return_reference
 rs    mv_return_spec
 se    mv_searchspec
 sf    mv_search_field
 si    mv_search_immediate
 sp    mv_search_page
 sq    mv_sql_query
 st    mv_searchtype
 su    mv_substring_match
 tf    mv_sort_field
 to    mv_sort_option
 un    mv_unique
 va    mv_value

 ________________________________________

Copyright 2002-2004 Interchange Development Group. Copyright 2001-2002
Red Hat, Inc. Freely redistributable under terms of the GNU General
Public License.