=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