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

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

As an alternative syntax, you can usually embed an Interchange tag as an attribute within an HTML tag. This allows some HTML editors to work more easily with Interchange templates (though you should consider the above HTML-comment-style brackets first). The following is a basic example of HTML-Embedded syntax:

  <HTMLtag MV="tagname positional parameters" other HTML attributes>

The following examples will each loop over any items in the shopping cart, displaying their part number, description, and price, but only IF there are items in the cart.

HTML syntax:

    <TABLE MV="if items">
    <TR MV="item-list">
    <TD> [item-code] </TD>
    <TD> [item-description] </TD>
    <TD> [item-price] </TD>
    </TR></TABLE>

Standard syntax:

    [if items]
    <TABLE>
    [item-list]
    <TR>
    <TD> [item-code] </TD>
    <TD> [item-description] </TD>
    <TD> [item-price] </TD>
    </TR>
    [/item-list]</TABLE>
    [/if]

Avoid the HTML-embedded usage if you can.

The Foundation catalog included with Interchange disables parsing of the HTML-embedded syntax. This is for better performance, since it saves the server from checking every HTML tag for Interchange tag calls. This is done in the catalog by setting the pragma no_html_parse in catalog.cfg.

2.4. 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.4.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.5. 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.5.1. interpolate

This attribute behaves differently depending on 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.5.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.5.3. send

Deprecated

2.6. 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.7. 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.7.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 [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-exec]
[prefix-field] (Optimization note-- one query per field if you use this; we optimize around this if only one products table)
[prefix-filter] (like filter tag but doesn't interpolate)
[prefix-increment]
[prefix-last]
[prefix-line] (tab-delimited list of parameters returned)
[prefix-match]
[prefix-modifier]
[prefix-next]
[prefix-options]
[prefix-param]
[prefix-pos]
[prefix-price]
[prefix-quantity]
[prefix-sub]
[prefix-subtotal]
[if-prefix-data]
[if-prefix-field]
[if-prefix-modifier] (hash list only)
[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]

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 field] or [prefix-data 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 on 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] [/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 foo_field], which specifically addresses the table foo. See also [C[jump="#prefix-param"]prefix-param]> and [C[jump="#prefix-pos"]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]

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 field as returned (starting with 0); [prefix-param] lets you access the data by field name instead of 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 synonymns, for foo is the first returned parameter and becomes the code for this row. Another synonym is [prefix-pos 0]; and [prefix-pos 1] is the same as [prefix-param bar].

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

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

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

3.24. quantity-name

   [quantity-name]

Outputs for successive items in the list:

    1. quantity0
    2. quantity1
    3. quantity2

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

4. Tags

Each ITL tag is show below. Calling information is defined for the main tag, sub-tags are described in 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="[modifier-name size]">
    [loop option="[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 on 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- 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 [PREFIX-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 [PREFIX-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. 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.23. 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.24. href

Requires 'type=links'.

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

4.1.2.25. 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.26. 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.27. 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.28. secure

Requires 'type=links'.

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

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

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

HTML-embedded example (disabled if no_html_parse Pragma active):

    <A MV="area dir/page" HREF="dir/page.html">

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.

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

    [attr_list hash]

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

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

ASP-like Perl call:

   $Tag->bounce(  { href => VALUE_href
                     if => VALUE_if
}, $body  );

or similarly with positional parameters,

    $Tag->bounce(href,if, $attribute_hash_reference, $body);

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 use this tag in a [perl] or ASP section.

4.9. cart

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

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.9.2. Description

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

4.9.2.1. name

4.10. 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.10.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.10.1.1. See Also

try

    [catch ]

Tag expansion example:

   [catch ]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.10.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.10.2.1. label

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

4.11. cgi

4.11.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->cgi(
        {
         name => VALUE,
        }
    )

 OR

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

Tag expansion example:

   [cgi name]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.11.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 are submitted with every 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.11.2.1. name

4.12. checked

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

Tag expansion example:

   [checked name value]
---
   TAGRESULT

ASP-like Perl call:

   $Tag->checked(  { name => VALUE_name
                      value => VALUE_value
}, $body  );

or similarly with positional parameters,

    $Tag->checked(name,value, $attribute_hash_reference, $body);

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

4.12.2.1. name

4.12.2.2. value

4.13. 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.13.1. Summary

    [control name defaultother_named_attributes]

Tag expansion example:

   [control name default]
---
   TAGRESULT

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.13.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.13.2.1. default

Value to return if scratchpad variable missing or empty

4.13.2.2. name

Name of scratchpad variable to set or return

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

• (must not specify name; may specify default)

4.13.2.4. set

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

4.14. 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.14.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 indexother_named_attributes]

Tag expansion example:

   [control_set index]
---
   TAGRESULT

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.14.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.14.2.1. index

4.15. counter

4.15.1. Summary

Parameters: file

Positional parameters in same order.

Invalidates cache: YES

Called Routine:

ASP-like Perl call:

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

 OR

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

Attribute aliases

            name ==> file
    [counter file]

Tag expansion example:

   [counter file]
---
   TAGRESULT

ASP-like Perl call:

   $Tag->counter(  { file => VALUE_file
}, $body  );

or similarly with positional parameters,

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

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

The counter is implemented using Perl's File::Counter module, which protects the file against simultaneous access by multiple processes.

WARNING: This tag will not work under Safe, i.e. in embedded Perl.

Additional parameters:

4.15.2.1. decrement=1

Causes the counter to count down instead of up.

4.15.2.2. start=50

Causes a new counter to be created and to start from 50 (for example) if it did not exist before.

4.15.2.3. value=1

Shows the value of the counter without incrementing or decrementing it.

4.15.2.4. file

4.16. currency

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

Tag expansion example:

   [currency convert noformat]
---
   TAGRESULT

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.16.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.16.2.1. convert

4.16.2.2. noformat

4.17. data

4.17.1. Summary

Parameters: table field key

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: 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 keyother_named_attributes]

Tag expansion example:

   [data table field key]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.17.2. Description

Syntax: [data table=db_table column=column_name key=key filter="uc|lc|name|namecase|no_white|etc."* append=1* 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.17.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.17.2.2. 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.17.2.3. key

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

4.17.2.4. table

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

4.18. default

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

Tag expansion example:

   [default name default]
---
   TAGRESULT

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.18.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.18.2.1. default

4.18.2.2. name

4.19. description

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

Tag expansion example:

   [description code base]
---
   TAGRESULT

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.19.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.19.2.1. base

4.19.2.2. code

4.20. discount

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

Tag expansion example:

   [discount code]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.20.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.20.2.1. code

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

Tag expansion example:

   [dump ]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.21.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.22. ecml

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

4.22.1. Summary

    [ecml name functionother_named_attributes]

Tag expansion example:

   [ecml name function]
---
   TAGRESULT

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

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

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

4.22.2.1. function

ecml function (default = 'widget')

4.22.2.2. name

4.23. either

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

4.23.1. Summary

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

No parameters.

Pass attribute hash as last to subroutine: no

Must pass named parameter interpolate=1 to cause interpolation.

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

Invalidates cache: no

Called Routine:

ASP-like Perl call:

    $Tag->either(
        {
        },
        BODY
    )

 OR

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

Tag expansion example:

   [either ]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.23.2. Description

NO Description

4.24. error

4.24.1. Summary

Parameters: name

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

Called Routine:

ASP-like Perl call:

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

 OR

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

Tag expansion example:

   [error name]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.24.2. Description

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

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

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

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

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

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

The options are:

4.24.2.1. all=1

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

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

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

4.24.2.2. joiner=char

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

4.24.2.3. keep=1

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

4.24.2.4. show_error=1

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

4.24.2.5. show_label=1

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

First Name: blank

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

show_label was added in 4.7.0.

4.24.2.6. show_var=1

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

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

4.24.2.7. std_label

std_label=<label string for error message>

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

        <FONT COLOR=RED>label_str<SMALL><I>(%s)</I></SMALL></FONT>

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

4.24.2.8. required=1

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

4.24.2.9. name

4.25. export

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

4.25.1. Summary

    [export tableother_named_attributes]

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

Tag expansion example:

   [export table]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.25.2. Description

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

4.25.2.1. delete

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

4.25.2.2. field

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

4.25.2.3. file

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

4.25.2.4. sort

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

4.25.2.5. table

The table to export

4.25.2.6. type

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

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

• If using NOTES
  • notes_separator (defaults to "\f")
  • notes_field (defaults to "notes_field")

4.25.2.7. verify

must be true when deleting a column

4.26. field

4.26.1. Summary

Parameters: name code

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->field(
        {
         name => VALUE,
         code => VALUE,
        }
    )

 OR

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

Attribute aliases

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

Tag expansion example:

   [field name code]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.26.2. Description

HTML example: <PARAM MV=field MV.COL=column MV.ROW=key>

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

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

4.26.2.1. code

4.26.2.2. name

4.27. file

4.27.1. Summary

Parameters: name type

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->file(
        {
         name => VALUE,
         type => VALUE,
        }
    )

 OR

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

Tag expansion example:

   [file name type]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.27.2. Description

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

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

4.27.2.1. name

4.27.2.2. type

4.28. filter

4.28.1. Summary

Parameters: op

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. [filter] FOO [/filter]. Nesting: NO

Invalidates cache: no

Called Routine:

ASP-like Perl call:

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

 OR

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

Tag expansion example:

   [filter op]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.28.2. Description

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

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

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

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

will display as

    Grant Wood

Another way to do this would be:

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

Filters available include:

4.28.2.1. cgi

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

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

4.28.2.2. digits

Returns only digits.

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

4.28.2.3. digits_dot

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

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

4.28.2.4. dos

Turns linefeeds into carriage-return / linefeed pairs.

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

4.28.2.5. entities

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

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

4.28.2.6. gate

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

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

4.28.2.7. lc

Lowercases the text.

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

4.28.2.8. lookup

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

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

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

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

4.28.2.9. mac

Changes newlines to carriage returns.

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

4.28.2.10. name

Transposes a LAST, First name pair.

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

4.28.2.11. namecase

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

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

4.28.2.12. no_white

Strips all whitespace.

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

4.28.2.13. pagefile

Strips leading slashes and dots.

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

4.28.2.14. sql

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

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

4.28.2.15. strip

Strips leading and trailing whitespace.

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

4.28.2.16. text2html

Rudimentary HTMLizing of text.

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

4.28.2.17. uc

Uppercases the text.

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

4.28.2.18. unix

Removes those crufty carriage returns.

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

4.28.2.19. urlencode

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

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

4.28.2.20. value

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

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

4.28.2.21. word

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

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

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

    package Vend::Interpolate;

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

That filter will reverse the characters sent.

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

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

4.28.2.22. op

4.29. flag

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

4.29.1. Summary

    [flag type]

Tag expansion example:

   [flag type]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.29.2. Description

The flag tag controls database access and transactions.

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

For example, you can call

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

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

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

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

4.29.2.1. build

Forces build of static Interchange page specified by the name attribute

4.29.2.2. checkhtml

4.29.2.3. commit

Attempts to commit transactions

4.29.2.4. read

Flags the table read-only

4.29.2.5. rollback

Attempts to rollback transactions

4.29.2.6. show

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

4.29.2.7. tables

The name of the table to flag

• 'table' is an alias

4.29.2.8. transactions

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

4.29.2.9. type

4.29.2.10. value

The boolean value of the flag

4.29.2.11. write

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

4.30. fly_list

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

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

Invalidates cache: no

Called Routine:

ASP-like Perl call:

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

 OR

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

Tag expansion example:

   [fly_list code base]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.30.2. Description

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

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

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

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

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

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

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

4.30.2.1. base

4.30.2.2. code

4.31. fly_tax

4.31.1. Summary

Parameters: area

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->fly_tax(
        {
         area => VALUE,
        }
    )

 OR

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

Tag expansion example:

   [fly_tax area]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.31.2. Description

Builds a tax rate from taxarea, taxrate, taxshipping, variable values, and the SalesTax directive value.

4.31.2.1. area

4.32. goto

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

4.32.1. Summary

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

or positionally,

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

ASP-like Perl call:

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

4.32.2. Description

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

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

4.32.2.1. name

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

4.32.2.2. if

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

For example, this will not execute the goto:

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

4.33. handling

4.33.1. Summary

Parameters: mode

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->handling(
        {
         mode => VALUE,
        }
    )

 OR

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

Attribute aliases

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

Tag expansion example:

   [handling mode]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.33.2. Description

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

4.33.2.1. mode

4.34. harness

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

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

4.34.1. Summary

    [harness other_named_attributes]

Tag expansion example:

   [harness ]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.34.2. Description

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

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

4.34.2.1. expected

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

4.34.2.2. name

This will appear in your output message (useful for distinguishing harness tags from one another) (default "testnnn")

4.35. href

Alias for [area] tag.

4.36. html_table

Builds an HTML table

4.36.1. Summary

    [html_table other_named_attributes]

Tag expansion example:

   [html_table ]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.36.2. Description

Builds an HTML table

4.36.2.1. columns

Whitespace-delimited list of columns

4.36.2.2. delimiter

Line delimiter to use if tag body is delimited text rather than an array reference (default "\t")

4.36.2.3. fc

HTML attributes for <TD> in the first cell

4.36.2.4. fr

HTML attributes for <TR> in the first row

4.36.2.5. record_delim

Record delimiter to use if tag body is delimited text rather than an array reference (default "\n")

4.36.2.6. td

HTML attributes for <TD>

4.36.2.7. th

HTML attributes for <TH>

4.36.2.8. tr

HTML attributes for <TR>

4.37. if

4.37.1. Summary

Parameters: type term op compare

THIS TAG HAS SPECIAL POSITIONAL PARAMETER HANDLING.

Pass attribute hash as last to subroutine: no

Must pass named parameter interpolate=1 to cause interpolation.

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

Invalidates cache: YES

Called Routine:

Called Routine for positonal:

ASP-like Perl call:

Not applicable. Any [if ...] call can be better and more efficiently done with Perl.

Attribute aliases

            base ==> type
            comp ==> compare
            condition ==> compare
            operator ==> op
    [if type term op compare]

Tag expansion example:

   [if type term op compare]
---
   TAGRESULT

ASP-like Perl call:

   $Tag->if(  { compare => VALUE_compare
                 op => VALUE_op
                 term => VALUE_term
                 type => VALUE_type
}, $body  );

or similarly with positional parameters,

    $Tag->if(type,term,op,compare, $attribute_hash_reference, $body);

4.37.2. Description

Named call example: [if type="type" term="field" op="op" compare="compare"]

Positional call example: [if type field op compare]

negated: [if type="!type" term="field" op="op" compare="compare"]

Positional call example: [if !type field op compare]

Allows conditional building of HTML based on the setting of various Interchange session and database values. The general form is:

    [if type term op compare]
    [then]
                                If true, this is printed on the document.
                                The [then] [/then] is optional in most
                                cases. If ! is prepended to the type
                                setting, the sense is reversed and
                                this will be output for a false condition.
    [/then]
    [elsif type term op compare]
                                Optional, tested when if fails
    [/elsif]
    [else]
                                Optional, printed when all above fail
    [/else]
    [/if]

The [if] tag can also have some variants:

    [if type=explicit compare=`$perl_code`]
        Displayed if valid Perl CODE returns a true value.
    [/if]

You can do some Perl-style regular expressions:

    [if value name =~ /^mike/]
                                This is the if with Mike.
    [elsif value name =~ /^sally/]
                                This is an elsif with Sally.
    [/elsif]
    [elsif value name =~ /^pat/]
                                This is an elsif with Pat.
    [/elsif]
    [else]
                                This is the else, no name I know.
    [/else]
    [/if]

While named parameter tag syntax works for [if ...], it is more convenient to use positional calls in most cases. The only exception is if you are planning on doing a test on the results of another tag sequence:

    [if value name =~ /[value b_name]/]
        Shipping name matches billing name.
    [/if]

Oops! This will not work. You must do instead

    [if base=value field=name op="=~" compare="/[value b_name]/"]
        Shipping name matches billing name.
    [/if]

or better yet

    [if type=explicit compare=`
                        $Value->{name} =~ /$Value->{b_name}/
                        `]
        Shipping name matches billing name.
    [/if]

Interchange also supports a limited [and ...] and [or ...] capability:

    [if value name =~ /Mike/]
    [or value name =~ /Jean/]
    Your name is Mike or Jean.
    [/if]

    [if value name =~ /Mike/]
    [and value state =~ /OH/]
    Your name is Mike and you live in Ohio.
    [/if]

If you wish to do very complex AND and OR operations, you will have to use [if explicit] or better yet embedded Perl/ASP. This allows complex testing and parsing of values.

There are many test targets available:

4.37.2.1. config Directive

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

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

4.37.2.2. data database::field::key

The Interchange databases. Retrieves a field in the database and returns true or false based on the value.

    [if data products::size::99-102]
    There is size information.
    [else]
    No size information.
    [/else]
    [/if]

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

4.37.2.3. discount

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

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

4.37.2.4. explicit

A test for an explicit value. If perl code is placed between a [condition] [/condition] tag pair, it will be used to make the comparison. Arguments can be passed to import data from user space, just as with the [perl] tag.

    [if explicit]
    [condition]
        $country = '[value country]';
        return 1 if $country =~ /u\.?s\.?a?/i;
        return 0;
    [/condition]
    You have indicated a US address.
    [else]
    You have indicated a non-US address.
    [/else]
    [/if]

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

This will work for Variable values:

    [if type=explicit compare="__MYVAR__"] .. [/if]

4.37.2.5. file

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

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

The file test requires that the SafeUntrap directive contains ftfile (which is the default).

4.37.2.6. items

The Interchange shopping carts. If not specified, the cart used is the main cart. Usually used as a litmus test to see if anything is in the cart, for example:

  [if items]You have items in your shopping cart.[/if]

  [if items layaway]You have items on layaway.[/if]

4.37.2.7. ordered

Order status of individual items in the Interchange shopping carts. If not specified, the cart used is the main cart. The following items refer to a part number of 99-102.

  [if ordered 99-102] Item 99-102 is in your cart. [/if]
    Checks the status of an item on order, true if item
    99-102 is in the main cart.

  [if ordered 99-102 layaway] ... [/if]
    Checks the status of an item on order, true if item
    99-102 is in the layaway cart.

  [if ordered 99-102 main size] ... [/if]
    Checks the status of an item on order in the main cart,
    true if it has a size attribute.

  [if ordered 99-102 main size =~ /large/i] ... [/if]
    Checks the status of an item on order in the main cart,
    true if it has a size attribute containing 'large'.

    To make sure it is exactly large, you could use:

  [if ordered 99-102 main size eq 'large'] ... [/if]

4.37.2.8. pragma

The Interchange Pragma settings, set with the the catalog.cfg manpage directive Pragma or with [pragma name].

    [if pragma dynamic_variables]
    __THE_VARIABLE__
    [else]
    [data table=variable column=Variable key=THE_VARIABLE]
    [/else]
    [/if]

4.37.2.9. scratch

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

    [if scratch mv_separate_items]
    ordered items will be placed on a separate line.
    [else]
    ordered items will be placed on the same line.
    [/else]
    [/if]

4.37.2.10. session

the Interchange session variables. of particular interest are i<login>, i<frames>, i<secure>, and i<browser>.

4.37.2.11. validcc

a special case, takes the form [if validcc no type exp_date]. evaluates to true if the supplied credit card number, type of card, and expiration date pass a validity test. does a luhn-10 calculation to weed out typos or phony card numbers. Uses the standard CreditCardAuto variables for targets if nothing else is passed.

4.37.2.12. value

the Interchange user variables, typically set in search, control, or order forms. variables beginning with c<mv_> are Interchange special values, and should be tested/used with caution.

The field term is the specifier for that area. For example, [if session logged_in] would return true if the logged_in session parameter was set.

As an example, consider buttonbars for frame-based setups. It would be nice to display a different buttonbar (with no frame targets) for sessions that are not using frames:

    [if scratch frames]
        __BUTTONBAR_FRAMES__
    [else]
        __BUTTONBAR__
    [/else]
    [/if]

Another example might be the when search matches are displayed. If you use the string '[value mv_match_count] titles found', it will display a plural for only one match. Use:

    [if value mv_match_count != 1]
        [value mv_match_count] matches found.
    [else]
        Only one match was found.
    [/else]
    [/if]

The op term is the compare operation to be used. Compare operations are as in Perl:

    ==  numeric equivalence
    eq  string equivalence
    >   numeric greater-than
    gt  string greater-than
    <   numeric less-than
    lt  string less-than
    !=  numeric non-equivalence
    ne  string equivalence

Any simple perl test can be used, including some limited regex matching. More complex tests are best done with [if explicit].

4.37.2.13. [then] text [/then]

This is optional if you are not nesting if conditions, as the text immediately following the [if ..] tag is used as the conditionally substituted text. If nesting [if ...] tags you should use a [then][/then] on any outside conditions to ensure proper interpolation.

4.37.2.14. [elsif type field op* compare*]

named attributes: [elsif type="type" term="field" op="op" compare="compare"]

Additional conditions for test, applied if the initial [if ..] test fails.

4.37.2.15. [else] text [/else]

The optional else-text for an if or if_field conditional.

4.37.2.16. [condition] text [/condition]

Only used with the [if explicit] tag. Allows an arbitrary expression in Perl to be placed inside, with its return value interpreted as the result of the test. If arguments are added to [if explicit args], those will be passed as arguments are in the [perl] construct.

4.37.2.17. compare

4.37.2.18. op

4.37.2.19. term

4.37.2.20. type

4.38. import

4.38.1. Summary

Parameters: table type

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.

Interpolates container text by default>.

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

Invalidates cache: YES

Called Routine:

ASP-like Perl call:

    $Tag->import(
        {
         table => VALUE,
         type => VALUE,
        },
        BODY
    )

 OR

    $Tag->import($table, $type, $ATTRHASH, $BODY);

Attribute aliases

            base ==> table
            database ==> table
    [import table typeother_named_attributes]

Tag expansion example:

   [import table type]
---
   TAGRESULT

ASP-like Perl call:

   $Tag->import(  { table => VALUE_table
                     type => VALUE_type
}, $body  );

or similarly with positional parameters,

    $Tag->import(table,type, $attribute_hash_reference, $body);

4.38.2. Description

Named attributes:

    [import table=table_name
            type=(TAB|PIPE|CSV|%%|LINE)
            continue=(NOTES|UNIX|DITTO)
            separator=c]

Import one or more records into a database. The type is any of the valid Interchange delimiter types, with the default being defined by the setting of the database DELIMITER. The table must already be a defined Interchange database table; it cannot be created on the fly. (If you need that, it is time to use SQL.)

The type of LINE and continue setting of NOTES is particularly useful, for it allows you to name your fields and not have to remember the order in which they appear in the database. The following two imports are identical in effect:

    [import table=orders]
    code: [value mv_order_number]
    shipping_mode: [shipping-description]
    status: pending
    [/import]

    [import table=orders]
    shipping_mode: [shipping-description]
    status: pending
    code: [value mv_order_number]
    [/import]

The code or key must always be present, and is always named code.

If you do not use NOTES mode, you must import the fields in the same order as they appear in the ASCII source file.

The [import ....] TEXT [/import] region may contain multiple records. If using NOTES mode, you must use a separator, which by default is a form-feed character (^L).

4.38.2.1. table

4.38.2.2. type

4.39. include

4.39.1. Summary

Parameters: file locale

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:

Not applicable.

    [include file locale]

Tag expansion example:

   [include file locale]
---
   TAGRESULT

ASP-like Perl call:

   $Tag->include(  { file => VALUE_file
                      locale => VALUE_locale
}, $body  );

or similarly with positional parameters,

    $Tag->include(file,locale, $attribute_hash_reference, $body);

4.39.2. Description

Same as [file name] except interpolates for all Interchange tags and variables. Does NOT do locale translations.

4.39.2.1. file

4.39.2.2. locale

4.40. index

Creates an index for the specified table.

4.40.1. Summary

    [index tableother_named_attributes]

Tag expansion example:

   [index table]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.40.2. Description

Creates an index for the specified table.

4.40.2.1. basefile

Database filename. Exports the table to this filename if old or missing before indexing. See also the export tag for additional relevent attributes such as delimiter type, etc.

4.40.2.2. col

alias for fields

4.40.2.3. columns

alias for fields

4.40.2.4. export_only

Just do the export if necessary (not the index).

4.40.2.5. extension

Index file extension (default "idx")

4.40.2.6. fields

field(s) to index

4.40.2.7. fn

alias for fields

4.40.2.8. show_status

Return '1' to the page if successful

4.40.2.9. spec

The index specification

4.40.2.10. table

4.41. item_list

4.41.1. Summary

Parameters: name

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. [item_list] FOO [/item_list]. Nesting: NO

Invalidates cache: YES

Called Routine:

ASP-like Perl call:

    NOTE: This would not usually be used with embedded Perl -- a better
    choice would normally be:

                 for(@$Items) { CODE }

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

 OR

    $Tag->item_list($name, $ATTRHASH, $BODY);

Attribute aliases

            cart ==> name
    [item_list nameother_named_attributes]

Tag expansion example:

   [item_list name]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.41.2. Description

Within any page, the [item_list cart*] element shows a list of all the items ordered by the customer so far. It works by repeating the source between [item_list] and [/item_list] once for each item ordered.

NOTE: The special tags that reference item within the list are not normal Interchange tags, do not take named attributes, and cannot be contained in an HTML tag (other than to substitute for one of its values or provide a conditional container). They are interpreted only inside their corresponding list container. Normal Interchange tags can be interspersed, though they will be interpreted after all of the list-specific tags.

Between the item_list markers the following elements will return information for the current item:

4.41.2.1. [if-data table column]

If the database field column in table table is non-blank, the following text up to the [/if_data] tag is substituted. This can be used to substitute IMG or other tags only if the corresponding source item is present. Also accepts a [else]else text[/else] pair for the opposite condition.

4.41.2.2. [if-data ! table column]

Reverses sense for [if-data].

4.41.2.3. [/if-data]

Terminates an [if_data table column] element.

4.41.2.4. [if-field fieldname]

If the products database field fieldname is non-blank, the following text up to the [/if_field] tag is substituted. If you have more than one products database table (see ProductFiles), it will check them in order until a matching key is found. This can be used to substitute IMG or other tags only if the corresponding source item is present. Also accepts a [else]else text[/else] pair for the opposite condition.

4.41.2.5. [if-field ! fieldname]

Reverses sense for [if-field].

4.41.2.6. [/if-field]

Terminates an [if_field fieldname] element.

4.41.2.7. [item-accessories attribute*, type*, field*, database*, name*]

Evaluates to the value of the Accessories database entry for the item. If passed any of the optional arguments, initiates special processing of item attributes based on entries in the product database.

4.41.2.8. [item-code]

Evaluates to the product code for the current item.

4.41.2.9. [item-data database fieldname]

Evaluates to the field name fieldname in the arbitrary database table database, for the current item.

4.41.2.10. [item-description]

Evaluates to the product description (from the products file) for the current item.

In support of OnFly, if the description field is not found in the database, the description setting in the shopping cart will be used instead.

4.41.2.11. [item-field fieldname]

Evaluates to the field name fieldname in the products database, for the current item. If the item is not found in the first of the ProductFiles, all will be searched in sequence.

4.41.2.12. [item-increment]

Evaluates to the number of the item in the match list. Used for numbering search matches or order items in the list.

4.41.2.13. [item-last]tags[/item-last]

Evaluates the output of the Interchange tags encased inside the tags, and if it evaluates to a numerical non-zero number (i.e. 1, 23, or -1) then the list iteration will terminate. If the evaluated number is negative, then the item itself will be skipped. If the evaluated number is positive, then the item itself will be shown but will be last on the list.

      [item-last][calc]
        return -1 if '[item-field weight]' eq '';
        return 1 if '[item-field weight]' < 1;
        return 0;
        [/calc][/item-last]

If this is contained in your [item-list] (or [search-list] or flypage) and the weight field is empty, then a numerical -1 will be output from the [calc][/calc] tags; the list will end and the item will not be shown. If the product's weight field is less than 1, a numerical 1 is output. The item will be shown, but will be the last item shown. (If it is an [item-list], any price for the item will still be added to the subtotal.) NOTE: no HTML style.

4.41.2.14. [item-modifier attribute]

Evaluates to the modifier value of attribute for the current item.

4.41.2.15. [item-next]tags[/item_next]

Evaluates the output of the Interchange tags encased inside, and if it evaluates to a numerical non-zero number (i.e. 1, 23, or -1) then the item will be skipped with no output. Example:

      [item-next][calc][item-field weight] < 1[/calc][/item-next]

If this is contained in your [item-list] (or [search-list] or flypage) and the product's weight field is less than 1, then a numerical 1 will be output from the [calc][/calc] operation. The item will not be shown. (If it is an [item-list], any price for the item will still be added to the subtotal.)

4.41.2.16. [item-price n* noformat*]

Evaluates to the price for quantity n (from the products file) of the current item, with currency formatting. If the optional "noformat" is set, then currency formatting will not be applied.

4.41.2.17. [discount-price n* noformat*]

Evaluates to the discount price for quantity n (from the products file) of the current item, with currency formatting. If the optional "noformat" is set, then currency formatting will not be applied. Returns regular price if not discounted.

4.41.2.18. [item-discount]

Returns the difference between the regular price and the discounted price.

4.41.2.19. [item-discount_subtotal]

Inserts the discounted subtotal of the ordered items.

4.41.2.20. [item-quantity]

Evaluates to the quantity ordered for the current item.

4.41.2.21. [item-subtotal]

Evaluates to the subtotal (quantity * price) for the current item. Quantity price breaks are taken into account.

4.41.2.22. [modifier-name attribute]

Evaluates to the name to give an input box in which the customer can specify the modifier to the ordered item.

4.41.2.23. [quantity-name]

Evaluates to the name to give an input box in which the customer can enter the quantity to order.

4.41.2.24. name

4.42. label

The page label for goto. See [goto] tag for description. Note that this is not a standard tag, but is simply a marker used by goto.

Parameter: name

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

4.42.1. Summary

NO SUMMARY SECTION

    [label ]

Tag expansion example:

   [label ]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.42.2. Description

NO DESCRIPTION SECTION

4.43. log

Log contained text to specified file.

4.43.1. Summary

    [log fileother_named_attributes]

Tag expansion example:

   [log file]
---
   TAGRESULT

ASP-like Perl call:

   $Tag->log(  { file => VALUE_file
}, $body  );

or similarly with positional parameters,

    $Tag->log(file, $attribute_hash_reference, $body);

4.43.2. Description

Log contained text to specified file.

4.43.2.1. create

Set create=1 to create the file if not present

4.43.2.2. delim

Line delimiter

4.43.2.3. file

name of file to log to. 'file=">filename"' also sets 'create' attribute.

4.43.2.4. hide

Suppress status otherwise returned by tag to the page.

4.43.2.5. process

Processing (if any) to apply to the content while logging

• nostrip (don't strip leading/trailing whitespace and convert "\r\n" to "\n"

4.43.2.6. record_delim

Record delimiter

4.43.2.7. type

Log type

• text (ordinary text file)
• quot (delimited entries)
• error (add Interchange error formatting and time/location stamps)

4.44. loop

4.44.1. Summary

Parameters: list

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. [loop] FOO [/loop]. Nesting: NO

Invalidates cache: no

Called Routine:

ASP-like Perl call:

    NOTE: This would not usually be used with embedded Perl -- a better
    choice would normally be:

                 for(@list) { CODE }

    $Tag->loop(
        {
         list => VALUE,
        },
        BODY
    )

 OR

    $Tag->loop($list, $ATTRHASH, $BODY);

Attribute aliases

            arg ==> list
            args ==> list
    [loop listother_named_attributes]

Tag expansion example:

   [loop list]
---
   TAGRESULT

ASP-like Perl call:

   $Tag->loop(  { list => VALUE_list
}, $body  );

or similarly with positional parameters,

    $Tag->loop(list, $attribute_hash_reference, $body);

4.44.2. Description

HTML example:

    <TABLE><TR MV="loop 1 2 3"><TD>[loop-code]</TD></TR></TABLE>

Returns a string consisting of the LIST, repeated for every item in a comma-separated or space-separated list. Operates in the same fashion as the [item-list] tag, except for order-item-specific values. Intended to pull multiple attributes from an item modifier -- but can be useful for other things, like building a pre-ordained product list on a page.

Loop lists can be nested reliably in Interchange by using the prefix="tag" parameter. New syntax:

    [loop list="A B C"]
        [loop prefix=mid list="[loop-code]1 [loop-code]2 [loop-code]3"]
            [loop prefix=inner list="X Y Z"]
                [mid-code]-[inner-code]
            [/loop]
        [/loop]
    [/loop]

You can do an arbitrary search with the search="args" parameter, just as in a one-click search:

    [loop search="se=Americana/sf=category"]
        [loop-code] [loop-field title]
    [/loop]

The above will show all items with a category containing the whole world "Americana", and will work the same in both old and new syntax.

Ranges are accepted when you pass a list if you set the ranges option:

    [loop list="A..Z" ranges=1][loop-code] [/loop]

The above lists all of the characters from A to Z. Any Perl incrementing variable list will work, but most commonly a range would be something like 1..100. You can mix regular sets -- 1..5 10 20 would produce the list 1 2 3 4 5 10 20.

If you surround the repeating text section with a [list] [/list] anchor, the more-list, ml=N, and on-match / no-match processing is done just as in [query] and [search-region].

Using the acclist option will parse Interchange option lists, as used in product options. The value is available with [loop-code], the label with [loop-param label]. If the size data for SKU TS-007 was set to the string S=Small, M=Medium, L=Large, XL=Extra Large then you could produce a select list of options this way:

    [loop list="[data products size TS-007]" acclist=1]
            [on-match]<SELECT NAME=mv_order_size>[/on-match]
                [list]<OPTION VALUE="[loop-code]"> [loop-param label]</OPTION>[/list]
        [on-match]</SELECT>[/on-match]
    [/loop]

Of course the above is probably more easily produced with [accessories code=TS-007 attribute=size], but there will be other uses for the capability. For instance:

         <SELECT NAME=Season>
    [loop acclist=1
                list="
                        Q1=Winter,
                        Q2=Spring,
                        Q3=Summer,
                        Q4=Fall
                "]> <OPTION VALUE="[loop-code]"> [loop-param label]</OPTION>
    [/loop]

If your parameter list needs to have spaces in the parameters, surround them with double or single quotes and set the quoted=1 option: in product options. If the size data for SKU TS-007 was set to the string S=Small, M=Medium, L=Large, XL=Extra Large then you could produce a select list of options this way:

    [loop list="[data products size TS-007]" acclist=1]
            [on-match]<SELECT NAME=mv_order_size>[/on-match]
                [list]<OPTION VALUE="[loop-code]"> [loop-param label]</OPTION>[/list]
        [on-match]</SELECT>[/on-match]
    [/loop]

4.44.2.1. [if-loop-data table column] IF [else] ELSE [/else][/if-loop-field]

Outputs the IF if the column in table is non-empty, and the ELSE (if any) otherwise.

See [if-prefix-data].

4.44.2.2. [if-loop-field column] IF [else] ELSE [/else][/if-loop-field]

Outputs the IF if the column in the products table is non-empty, and the ELSE (if any) otherwise. Will fall through to the first non-empty field if there are multiple ProductFiles.

See [if-prefix-field].

4.44.2.3. [if-loop-param param] IF [else] ELSE [/else][/if-loop-param]

Only works if you have named return fields from a search (or from a passed list with the lr=1 parameter).

Outputs the IF if the returned param is non-empty, and the ELSE (if any) otherwise.

See [if-prefix-param].

4.44.2.4. [if-loop-pos N] IF [else] ELSE [/else][/if-loop-pos]

Only works if you have multiple return fields from a search (or from a passed list with the lr=1 parameter).

Parameters are numbered from ordinal 0, with [loop-pos 0] being the equivalent of [loop-code].

Outputs the IF if the returned positional parmeter N is non-empty, and the ELSE (if any) otherwise.

See [if-prefix-pos].

4.44.2.5. [loop-accessories]

Outputs an [accessories ...] item.

See [prefix-accessories].

4.44.2.6. [loop-change marker]

See [prefix-change].

4.44.2.7. [loop-code]

Evaluates to the code for the current item.

See [prefix-code].

4.44.2.8. [loop-data database fieldname]

Evaluates to the field name fieldname in the arbitrary database table database, for the current item.

See [prefix-data].

4.44.2.9. [loop-description]

Evaluates to the product description (from the products file, passed description in on-fly item, or description attribute in cart) for the current item.

See [prefix-description].

4.44.2.10. [loop-field fieldname]

Evaluates to the field name fieldname in the database, for the current item.

See [prefix-field].

4.44.2.11. [loop-increment]

Evaluates to the number of the item in the list. Used for numbering items in the list.

Starts from integer 1.

See [prefix-increment].

4.44.2.12. [loop-last]tags[/loop-last]

Evaluates the output of the Interchange tags encased inside, and if it evaluates to a numerical non-zero number (i.e. 1, 23, or -1) then the loop iteration will terminate. If the evaluated number is negative, then the item itself will be skipped. If the evaluated number is positive, then the item itself will be shown but will be last on the list.

      [loop-last][calc]
        return -1 if '[loop-field weight]' eq '';
        return 1 if '[loop-field weight]' < 1;
        return 0;
        [/calc][/loop-last]

If this is contained in your [loop list] and the weight field is empty, then a numerical -1 will be output from the [calc][/calc] tags; the list will end and the item will not be shown. If the product's weight field is less than 1, a numerical 1 is output. The item will be shown, but will be the last item shown.

4.44.2.13. [loop-next]tags[/loop-next]

Evaluates the output of the Interchange tags encased inside, and if it evaluates to a numerical non-zero number (i.e. 1, 23, or -1) then the loop will be skipped with no output. Example:

      [loop-next][calc][loop-field weight] < 1[/calc][/loop-next]

If this is contained in your [loop list] and the product's weight field is less than 1, then a numerical 1 will be output from the [calc][/calc] operation. The item will not be shown.

4.44.2.14. [loop-price n* noformat*]

Evaluates to the price for optional quantity n (from the products file) of the current item, with currency formatting. If the optional "noformat" is set, then currency formatting will not be applied.

4.44.2.15. list

4.45. mail

Mail contained text to recipient specified by 'to' using the program specified with the SendMailProgram catalog directive.

4.45.1. Summary

    [mail toother_named_attributes]

Tag expansion example:

   [mail to]
---
   TAGRESULT

ASP-like Perl call:

   $Tag->mail(  { to => VALUE_to
}, $body  );

or similarly with positional parameters,

    $Tag->mail(to, $attribute_hash_reference, $body);

4.45.2. Description

Mail contained text to recipient specified by 'to' using the program specified with the SendMailProgram catalog directive.

4.45.2.1. extra

Additional headers (these will also be added to 'raw' messages)

4.45.2.2. hide

Suppress tag return value. This would otherwise be the 'success' attribute setting.

4.45.2.3. raw

Send it raw without creating headers and checking content, recipient, subject, etc.

4.45.2.4. show

The tag will return the final message with headers in the page

4.45.2.5. success

Tag return value if successful (default is 1).

4.45.2.6. to

4.46. mvasp

Executes the ASP-style perl code contained by the tag. The code will run under the restrictions of the Safe module. This is very similar to the [perl] tag, except that the standard '<%' and '%>' ASP delimiters allow you to mix HTML and perl code.

4.46.1. Summary

    [mvasp tables] ASP here [/mvasp]
    [mvasp tables="db1 db2 ..." other_named_attributes] ASP here [/mvasp]

Tag expansion example:

   [mvasp tables="products" failure="ASP Broke <BR>"]
      <P>This is HTML</p>
      <% my $sku = $Values->{code}; %>
      <P>More HTML</p>
      <% my $result = "Looked up SKU $sku. It is a ";
         $result .= $Tag->data('products', 'description', $sku );
         $Document->write( "$result <br>\n" ); %>
      <P>Still more HTML</p>
   [/mvasp]
------------------------------------------------------
      <P>This is HTML</p>

      <P>More HTML</p>
      Looked up SKU os28044. It is a Framing Hammer <br>

      <P>Still more HTML</p>

4.46.1.1. See Also

perl, Interchange Programming

4.46.2. Description

Executes the ASP-style perl code contained by the tag. The code will run under the restrictions of the Safe module. This is very similar to the [perl no_return=1] tag, except that the standard '<%' and '%>' ASP delimiters allow you to mix HTML and perl code.

See the perl tag and ASP-Like Perl sections for more detail.

4.46.2.1. tables

Whitespace-separated list of database tables to make available within the ASP-Perl code. See perl tag.

4.46.2.2. failure

The value the tag should return in case the perl code fails the eval. See perl tag.

4.46.2.3. no_return

The return value of the perl code is always suppressed. If you want output from the ASP code sections, you must explicitly write it with the &HTML or $Document->write() functions.

You can also retrieve the return value of the perl code from the session hash via [data session mv_perl_result]. See perl tag.

4.46.2.4. subs

Enable GlobalSub routines (requires catalog directive AllowGlobal). See perl tag.

4.46.2.5. global

Turn off Safe protection (requires catalog directive AllowGlobal). See perl tag.

4.46.2.6. file

Prepend the contents of the specified file or FileDatabase entry to the perl code before eval'ing it. See perl tag.

4.46.2.7. Examples

See the ASP-Like Perl section of Interchange Programming.

4.47. nitems

Returns the total number of items ordered. Uses the current cart if none specified.

4.47.1. Summary

    [nitems name]

Tag expansion example:

   [nitems name]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.47.2. Description

Expands into the total number of items ordered so far. Takes an optional cart name as a parameter.

4.47.2.1. compare

Regular expression the specified qualifier attribute's value must match to be counted. This replaces the truth value comparison.

• Default: None (uses truth value of the specified qualifier attribute)

4.47.2.2. name

Cart name

• Default: current cart

4.47.2.3. qualifier

An item attribute that must be true in order to count the item.

• Default: None

4.48. options

Builds HTML widgets as defined in the options table for selecting options associated with a given product. This tag handles simple, matrix or modular options. See also the accessories tag.

Here is an illustrative example from the 'tools' sample data set of the foundation catalog:

===
   [options code=os28005]
---
   <input type=hidden name=mv_item_option value="logo">
     <SELECT NAME="mv_order_logo">
     <OPTION VALUE="c">Construct Something
     <OPTION VALUE="y" SELECTED>Your Logo</SELECT><BR>
   <input type=hidden name=mv_item_option value="color">
     <INPUT TYPE="radio" NAME="mv_order_color" VALUE="BLK" >&nbsp;Black
     <INPUT TYPE="radio" NAME="mv_order_color" VALUE="BEIGE" >&nbsp;Beige
     <INPUT TYPE="radio" NAME="mv_order_color" VALUE="WHITE" >&nbsp;White<BR>
   <input type=hidden name=mv_item_option value="bristle">
     <SELECT NAME="mv_order_bristle">
     <OPTION VALUE="synthetic">Synthetic
     <OPTION VALUE="camel">Camel Hair</SELECT>
===

4.48.1. Summary

    [options code]

===
   [options code=os28011 label=1 price=1]
---
   Handle<BR>
     <input type=hidden name=mv_item_option value="handle">
       <SELECT NAME="mv_order_handle">
       <OPTION VALUE="W">Wood handle
       <OPTION VALUE="E">Ebony handle ($20.00)</SELECT><BR>
   Blade material<BR>
     <input type=hidden name=mv_item_option value="blade">
       <SELECT NAME="mv_order_blade">
       <OPTION VALUE="P">Plastic blade ($-1.22)
       <OPTION VALUE="S" SELECTED>Steel blade
       <OPTION VALUE="T">Titanium blade ($100.00)</SELECT>
===

===
   [options code=os28005 td=1]
---
   <td><input type=hidden name=mv_item_option value="logo">
      <SELECT NAME="mv_order_logo">
      <OPTION VALUE="c">Construct Something
      <OPTION VALUE="y" SELECTED>Your Logo</SELECT></td>
   <td><input type=hidden name=mv_item_option value="color">
      <INPUT TYPE="radio" NAME="mv_order_color" VALUE="BLK" >&nbsp;Black
      <INPUT TYPE="radio" NAME="mv_order_color" VALUE="BEIGE" >&nbsp;Beige
      <INPUT TYPE="radio" NAME="mv_order_color" VALUE="WHITE" >&nbsp;White</td>
   <td><input type=hidden name=mv_item_option value="bristle">
      <SELECT NAME="mv_order_bristle">
      <OPTION VALUE="synthetic">Synthetic
      <OPTION VALUE="camel">Camel Hair</SELECT></td>
===

Tag expansion example:

   [options code]
---
   TAGRESULT

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.48.2. Description

NO DESCRIPTION SECTION

4.48.2.1. bold

Boldfaces the labels if the 'label' option is set.

• Default: False

4.48.2.2. code

Product key (usually sku).

• No default

4.48.2.3. joiner

The joiner for the widgets.

• Default: <BR>

4.48.2.4. label

Shows labels for the options with the widgets.

The following example (using another item from the 'tools' data) illustrates the price and label attributes:

===
   [options code=os28011 label=1 price=1]
---
   Handle<BR>
     <input type=hidden name=mv_item_option value="handle">
       <SELECT NAME="mv_order_handle">
       <OPTION VALUE="W">Wood handle
       <OPTION VALUE="E">Ebony handle ($20.00)</SELECT><BR>
   Blade material<BR>
     <input type=hidden name=mv_item_option value="blade">
       <SELECT NAME="mv_order_blade">
       <OPTION VALUE="P">Plastic blade ($-1.22)
       <OPTION VALUE="S" SELECTED>Steel blade
       <OPTION VALUE="T">Titanium blade ($100.00)</SELECT>
===

(again, the output has been reformatted to fit the page).

• Default: False

4.48.2.5. price

Boolean. If set and the options have prices, the HTML widget(s) will show the prices. This is like the price attribute of the accessories tag.

Note that the price_data setting comes from the 'price' column of the options table.
Technical note-- If your options table has different mappings, you can control this with $::Variable->{MV_OPTION_TABLE_MAP}
• Default: False

4.48.2.6. table

Table to use for option attributes.

• Default: 'options'

4.48.2.7. td

Results as table rows. For example, compare the following example from the 'tools' sample data set with the earlier example:

===
   [options code=os28005 td=1]
---
   <td><input type=hidden name=mv_item_option value="logo">
      <SELECT NAME="mv_order_logo">
      <OPTION VALUE="c">Construct Something
      <OPTION VALUE="y" SELECTED>Your Logo</SELECT></td>
   <td><input type=hidden name=mv_item_option value="color">
      <INPUT TYPE="radio" NAME="mv_order_color" VALUE="BLK" >&nbsp;Black
      <INPUT TYPE="radio" NAME="mv_order_color" VALUE="BEIGE" >&nbsp;Beige
      <INPUT TYPE="radio" NAME="mv_order_color" VALUE="WHITE" >&nbsp;White</td>
   <td><input type=hidden name=mv_item_option value="bristle">
      <SELECT NAME="mv_order_bristle">
      <OPTION VALUE="synthetic">Synthetic
      <OPTION VALUE="camel">Camel Hair</SELECT></td>
===

(Note that the output was reformatted to fit this page)

4.49. or

4.49.1. Summary

Parameters: type term op compare

THIS TAG HAS SPECIAL POSITIONAL PARAMETER HANDLING.

Pass attribute hash as last to subroutine: no

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: no

Called Routine:

Called Routine for positonal:

ASP-like Perl call:

    $Tag->or(
        {
         type => VALUE,
         term => VALUE,
         op => VALUE,
         compare => VALUE,
        }
    )

 OR

    $Tag->or($type, $term, $op, $compare);

Attribute aliases

            base ==> type
            comp ==> compare
            operator ==> op
    [or type term op compare]