Interchange Tags Reference
==========================

ictags.1.118 (Draft)

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

2. Tag Syntax
=============

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

We will call an attribute a parameter if it may be called positionally
or if it must be included (see the parameter and 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]

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

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

2.2. HTML-Comment
-----------------

ITL also allows you to use '<!--[' and ']-->' as interchangeable
alternatives to plain square brackets: [tagname] and <!--[tagname]-->
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 -->'

2.2.1. 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 Template Parsing Order appendix if you are modifying the
special administrative interface pages and intend to use this syntax.

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

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.

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

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

2.3.1. 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 href ('scan') did not need to be quoted;
only the argument to arg, which contained a tag, needed the quotes.

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

2.4.1. interpolate
------------------

This attribute behaves differently depending upon whether the tag is a
container or 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
[area href=somepage]. (Note that [page ...] and [order ..] are not
container tags.)

For container tags (interpolated)

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

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

For standalone tags (reparsed)

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

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

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

2.4.3. send
-----------

Deprecated

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

2.6. 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 n is an integer array index. Note that you cannot use both an
array and a hash with the same attribute - if you use attribute.n, you
cannot also use 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 (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.

2.6.1. 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 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 } );

3. Looping tags and Sub-tags
============================

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

     [PREFIX-accessories]

     [PREFIX-alternate]

     [PREFIX-calc]

     [PREFIX-change]

     [PREFIX-code]

     [PREFIX-data]

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

     [PREFIX-discount]

     [PREFIX-discount-subtotal]

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

     [PREFIX-increment]

     [PREFIX-last]

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

     [PREFIX-modifier]

     [PREFIX-next]

     [PREFIX-param]

     [PREFIX-pos]

     [PREFIX-price]

     [PREFIX-quantity]

     [PREFIX-subtotal]

     [if-PREFIX-data]

     [if-PREFIX-field]

     [if-PREFIX-param]

     [if-PREFIX-pos]

     [modifier-name]

     [quantity-name]

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, 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' },
    ]

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

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

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

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

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

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

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

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

3.9. PREFIX-discount-subtotal
-----------------------------

   [PREFIX-discount-subtotal]

Inserts the discounted subtotal of the ordered items.

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

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

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

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

3.14. PREFIX-modifier
---------------------

   [PREFIX-modifier attribute]

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

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

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

3.17. 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 Nth 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.

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

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

3.20. PREFIX-subtotal
---------------------

   [PREFIX-subtotal]

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

3.21. 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!

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

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

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

4. Tags
=======

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

4.1. 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 Looping tags and Sub-tags.

4.1.1. 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    none
              (or specified other) table
arg           Positionally interpreted comma-delimited  none
              list of values for the following
              attributes:"attribute, type, column,
              table, name, outboard, passed"

Attributes                         Default
.................................. .................................. 
attribute                          none
typeOne of select, value, text,    select
textarea, hidden, password, combo,
move_combo, reverse_combo, show,
options, labels, checkbox, radio,
links
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

Tag expansion example:

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

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

4.1.1.1. See Also
-----------------

Looping tags and Sub-tags.

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

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

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

Notes:

1.   The 'attribute' attribute is required.

2.   See the type attribute for a list of types.

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



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

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

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

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

4.1.2.4. arg
------------

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

4.1.2.5. attribute
------------------

Despite the name, this has nothing to do with tag attributes. You can
set attributes for 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.

4.1.2.6. 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=m, COLS=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=m and cols=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 rows is the
number of rows and cols is the number of columns.

o    text

     o    textarea   (default is 4 rows, 40 columns, like
          'textarea_4_40')

     o    textarea_rows_cols

     o    text_cols

     o    textarea rows=rows cols=cols wrap=WRAP value

o    password

     o    password   (default is 12 columns, like 'password_12')

     o    password_cols

o    combo (similarly for reverse_combo and move_combo)

     o    combo   (default is 1 row, 16 columns, like 'combo_1_16')

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.

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

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

4.1.2.9. name
-------------

This sets the name of the form variable to use if appropriate for the
widget being built. Defaults to 'mv_order_attribute' - i.e. if the
attribute is size, the form variable will be named mv_order_size.

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

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

4.1.2.11. 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 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 Blue, and the
value of green with a label of 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.

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

4.1.2.13. prepend
-----------------

You can set a string to prepend to the returned output of the tag.
Note that this is 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>

4.1.2.14. append
----------------

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

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

4.1.2.16. 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
is:

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

4.1.2.17. rows
--------------

The tag will pass the number you choose through to the HTML 'ROWS=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=n attribute is undefined.

4.1.2.18. cols
--------------

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

See also 'rows' above.

4.1.2.19. width
---------------

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

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

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

4.1.2.22. price_data
--------------------

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

4.1.2.24. joiner
----------------

Requires '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.

4.1.2.25. href
--------------

Requires 'type=links'.

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

4.1.2.26. template
------------------

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

4.1.2.27. form
--------------

Requires '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 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.

4.1.2.28. empty
---------------

Requires '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.

4.1.2.29. secure
----------------

Requires 'type=links'.

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

4.1.2.30. new
-------------

Requires '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":

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

4.2. and
--------

4.2.1. Summary
--------------

Parameters: type term op compare

Pass attribute hash as last to subroutine: no

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: no

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

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.

ASP-like Perl call:

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

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

4.2.2.1. compare
----------------

4.2.2.2. op
-----------

4.2.2.3. term
-------------

4.2.2.4. type
-------------

4.3. area
---------

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

4.3.1. Summary
--------------

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

Parameters    Description                               Default
............. ......................................... ............. 
href          Path to Interchange page or actionSpecial process
              arguments'scan' links to a search (using
              search arguments in arg)'http://...'
              external link (requires form attribute)
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

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

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.3.1.1. See Also
-----------------

page

4.3.2. 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 arg is used just as in the page tag.

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

4.3.2.2. search
---------------

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

1.   Place the search specification in the named search attribute.

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

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

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

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

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 page tag for more detail.

4.3.2.3. secure
---------------

4.3.2.4. Examples
-----------------

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>

4.4. assign
-----------

Allows you to assign numeric values to preempt calculation of one or
more of the following 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.

4.4.1. Summary
--------------

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

Attributes    Description                               Default
............. ......................................... ............. 
clear         Clears all pending 'assign' tag           none
              assignments
handling      Assigns an override value for [handling]  none
              tags
salestax      Assigns an override value for [salestax]  none
              tags
shipping      Assigns an override value for [shipping]  none
              tags
subtotal      Assigns an override value for [subtotal]  none
              tags

Other_Characteristics
.................................. .................................. 
Invalidates cache                  No
Container tag                      No

ASP-like Perl call:

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

4.4.1.1. See Also
-----------------

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

4.4.2. Description
------------------

The assign tag allows you to assign numeric override values to one or
more of the following 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 destination:

    [assign salestax=0 shipping=4.99]

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

    [assign salestax="" handling=0]

This restores the normal behavior to the [shipping] and [handling]
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 ("").

4.4.2.1. clear
--------------

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

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

4.4.2.3. handling
-----------------

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

Important note

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



4.4.2.4. salestax
-----------------

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

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

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

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

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

4.5.2. Description
------------------

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

Tags according to the following rules:

4.5.2.1. {key}
--------------

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

4.5.2.2. {key|fallback string}
------------------------------

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

4.5.2.3. {key true string}
--------------------------

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

4.5.2.4. {key?} true text {/key?}
---------------------------------

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

4.5.2.5. {key:} false text {/key:}
----------------------------------

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

4.5.2.6. hash
-------------

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

4.6. banner
-----------

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

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

Tag expansion example:

    [banner category=my_category]

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.6.1.1. See Also
-----------------

Banner/Ad rotation

4.6.2. Description
------------------

Implements random or rotating banner ads. See 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 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

4.6.2.1. category
-----------------

Default: category="default"

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

4.6.2.2. table
--------------

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.

4.6.2.3. r_field
----------------

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.

4.6.2.4. b_field
----------------

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

4.6.2.5. separator
------------------

Default: separator=":"

Unweighted ads only.

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

4.6.2.6. delimiter
------------------

Default: delimiter="{or}"

Unweighted ads only.

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

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

4.6.2.8. 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 Banner/Ad rotation.

4.6.2.9. c_field
----------------

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.

4.6.2.10. w_field
-----------------

Default: w_field="weight"

Weighted ads only.

This specifies the column containing the banner weight.

4.7. bounce
-----------

4.7.1. Summary
--------------

Parameters: href if

Positional parameters in same order.

Pass attribute hash as last to subroutine: no

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: no

Called Routine:

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

Tag expansion example:

    [bounce href if]
---
    TAG RESULT

ASP-like Perl call:

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

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

4.7.2.1. href
-------------

4.7.2.2. if
-----------

4.8. calc
---------

Calculates the value of the enclosed arithmetic expression.

4.8.1. Summary
--------------

    [calc] Expression [/calc]

No parameters

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

ASP-like Perl call:

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

4.8.2. Description
------------------

Calculates the value of the enclosed arithmetic expression.

Use it as follows: [calc] 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.

4.9. calcn
----------

Calculates the value of the enclosed arithmetic expression.

4.9.1. Summary
--------------

    [calcn] Expression [/calcn]

No parameters

No attributes

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

ASP-like Perl call:

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

4.9.2. Description
------------------

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

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

4.10. cart
----------

4.10.1. Summary
---------------

Parameters: name

Positional parameters in same order.

Pass attribute hash as last to subroutine: no

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: YES

Called Routine:

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

Tag expansion example:

    [cart name]
---
    TAG RESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.10.2. Description
-------------------

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

4.10.2.1. name
--------------

4.11. catch
-----------

The page content contained within the [catch 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 this:

    [error message]body text[/error message]

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

See also [try].

4.11.1. 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    'default'
              catch blocks

Attributes                         Default
.................................. .................................. 
interpolate                        Yes
reparse                            Yes

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

Tag expansion example

Ignoring whitespace, the following would return division result if
successful, 0 on a division by zero, or an error 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

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.11.1.1. See Also
------------------

try

    [catch]

Attributes                         Default
.................................. .................................. 
interpolate (reparse)              No

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

Tag expansion example:

    [catch]
---
    TAG RESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.11.2. Description
-------------------

The page content contained within the [catch label][/catch] block
executes if the correspondingly labelled  try block fails. The catch
block executes in place on the page if triggered (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 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).

4.11.2.1. label
---------------

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

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

4.12.1. Summary
---------------

    [cgi name]
    [cgi name=cgi_var_name other_named_attributes]

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

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

Other_Characteristics
.................................. .................................. 
Invalidates cache                  Yes

Tag expansion example:

Assuming CGI variable 'foo' = 'bar',

    [cgi foo]
---
    bar

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

4.12.2. Description
-------------------

Displays the value of a CGI variable 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.

4.12.2.1. name
--------------

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

4.12.2.2. set
-------------

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

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

4.12.2.3. hide
--------------

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

4.12.2.4. filter
----------------

See the filter tag for a list of filters.

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

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

4.12.2.6. default
-----------------

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

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

4.12.2.7. enable_html
---------------------

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

4.13. checked
-------------

4.13.1. Summary
---------------

Parameters: name value

Positional parameters in same order.

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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: YES

Called Routine:

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

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 >

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

4.13.2.1. case
--------------

4.13.2.2. cgi
-------------

4.13.2.3. default
-----------------

4.13.2.4. name
--------------

4.13.2.5. multiple
------------------

4.13.2.6. value
---------------

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

4.14.1. Summary
---------------

    [control name default other_named_attributes]

Parameters    Description                               Default
............. ......................................... ............. 
default       Value to return if scratchpad variable    DEFAULT_VALUE
              missing or empty
name          Name of scratchpad variable to set or     DEFAULT_VALUE
              return
reset         Resets scratchpad (i.e. $::Control array) DEFAULT_VALUE
              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)
set           Copies named scratch variable (i.e., from DEFAULT_VALUE
              $::Scratch) to scratchpad with current
              control index.

Attributes                         Default
.................................. .................................. 
interpolate (reparse)              No

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

Tag expansion example:

    [control name default]
---
    TAG RESULT

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

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

4.14.2.1. default
-----------------

Value to return if scratchpad variable missing or empty

4.14.2.2. name
--------------

Name of scratchpad variable to set or return

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

o    (must not specify name; may specify default)

4.14.2.4. set
-------------

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

4.15. control_set
-----------------

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

4.15.1. 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: index

Positional parameters in same order.

The attribute hash reference is passed after the parameters but before
the container text argument. 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: no

Called Routine:

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

Tag expansion example:

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

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.15.2. Description
-------------------

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

4.15.2.1. index
---------------

4.16. counter
-------------

4.16.1. Summary
---------------

Parameters: file start date sql

Positional parameters: file

Invalidates cache: YES

Called Routine:

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

Tag expansion example:

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

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

4.16.2. 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 Safe, i.e. in embedded Perl.

Additional parameters:

4.16.2.1. decrement=1
---------------------

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

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

4.16.2.3. value=1
-----------------

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

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

4.16.2.5. date="local"
----------------------

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

4.16.2.6. date="gmt"
--------------------

Specifies the counter will be date-based with GMT.

4.16.2.7. file
--------------

4.16.3. 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"]

4.17. currency
--------------

4.17.1. Summary
---------------

Parameters: convert noformat

Positional parameters in same order.

Pass attribute hash as last to subroutine: no

Interpolates container text by default.

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

Invalidates cache: no

Called Routine:

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

Tag expansion example:

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

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

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

4.17.2.1. convert
-----------------

4.17.2.2. noformat
------------------

4.18. data
----------

4.18.1. Summary
---------------

Main Parameters: table field key

Positional parameters in same order.

Additional parameters: hash foreign value

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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: no

Called Routine:

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

Tag expansion example:

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

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

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

4.18.2.1. field
---------------

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

4.18.2.2. 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".

4.18.2.3. 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};

4.18.2.4. key
-------------

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

4.18.2.5. table
---------------

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

4.19. default
-------------

4.19.1. Summary
---------------

Parameters: name default

Positional parameters in same order.

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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: YES

Called Routine:

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

Tag expansion example:

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

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

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

4.19.2.1. default
-----------------

4.19.2.2. name
--------------

4.20. description
-----------------

4.20.1. Summary
---------------

Parameters: code base

Positional parameters in same order.

Pass attribute hash as last to subroutine: no

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: no

Called Routine:

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

Tag expansion example:

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

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

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

4.20.2.1. base
--------------

4.20.2.2. code
--------------

4.21. discount
--------------

4.21.1. Summary
---------------

Parameters: code

Positional parameters in same order.

Pass attribute hash as last to subroutine: no

Must pass named parameter interpolate=1 to cause interpolation.

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

Invalidates cache: YES

Called Routine:

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

Tag expansion example:

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

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.21.2. 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
quantity and subtotal respectively. In the case of the item and all
items discount, the formula must evaluate to a new subtotal for all
items 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 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]

4.21.2.1. code
--------------

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

4.22.1. Summary
---------------

No parameters.

Pass attribute hash as last to subroutine: no

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: no

Called Routine:

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

Tag expansion example:

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

ASP-like Perl call:

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

or similarly with positional parameters,

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

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

4.23. ecml
----------

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

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

Tag expansion example:

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

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

4.23.2. 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           add