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]

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)

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

For standalone tags (reparsed)

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

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:

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]

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.

item group quantity code mv_ib mv_mi mv_si

You can also set modifier names with the mv_UseModifier scratch variable -- [set mv_UseModifier] size color [/set] has the same effect as above. This allows multiple options to be set for products. Whichever one is in effect at order time will be used. Be careful; you cannot set it more than once on the same page. Setting the mv_separate_items or global directive 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.

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

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:

  type="radio left n fontsizem"

  type="radio right n fontsizem"

  type="check left n fontsizem"

  type="check right n fontsizem"

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.

• text
  • textarea (default is 4 rows, 40 columns, like 'textarea_4_40')
  • textarea_rows_cols
  • text_cols
  • textarea rows=rows cols=cols wrap=WRAP value
• password
  • password (default is 12 columns, like 'password_12')
  • password_cols
• combo (similarly for reverse_combo and move_combo)
  • 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

    [and type term op compare]

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]

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.
   • Interchange will ignore the href parameter (the link will be set to 'scan'.
   • 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.
   • 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]

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.

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)

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]

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:

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]

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

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

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]

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]

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]

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]