ictags.sdf

!init OPT_LOOK="icdevgroup"; OPT_STYLE="manual" 
# $Id: ictags.sdf,v 1.123 2005-07-20 02:22:20 jon Exp $

!define DOC_NAME "Interchange Tags Reference"
!define DOC_TYPE ""
!define DOC_CODE "ictags"
!define DOC_VERSION substr('$Revision: 1.123 $', 11, -2)
!define DOC_STATUS "Draft"
!define DOC_PROJECT "Interchange"
!define DOC_URL "http://www.icdevgroup.org/doc/ictags.html"
!define DOC_OWNER "2002-2004 Interchange Development Group, 1996-2002 Red Hat, Inc."

!define SHOW_COMMENTS 0
!define EXAMPLE_SESSION "6CZ2whqo"
!define EXAMPLE_DOMAIN "www.here.com"
!define EXAMPLE_CATALOG "mycatalog"
!define EXAMPLE_VLINK "mycatalog"
!define EXAMPLE_SECURE_DOMAIN "secure.here.com"
!define EXAMPLE_SKU "os28044"
!define EXAMPLE_PRICE 19.99
!define EXAMPLE_SIZE "15oz"
!define EXAMPLE_SIZE1 "10oz"
!define EXAMPLE_SIZE2 "20oz"
!define EXAMPLE_DESCRIPTION "Framing Hammer"
!build_title

H1: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
C<UserTag> facility allows you to create tags that perform your own
functions and can be just as powerful as the built-in tags.

This document covers Interchange versions 4.7 through 4.9.

H1:Tag Syntax

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

We will call an attribute a I<parameter> if it may be called
positionally or if it must be included (see the
{{CMD[jump="#parameters"]parameter}} and
{{CMD[jump="#attributes"]attribute}} sections below).

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

E:    E<lbracket>{{C[jump="#value"]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:

!block example
    E<lbracket>{{C[jump="#if"]if}} value name]
    You have a name. It is [C<value> name].
    E<lbracket>/if]
!endblock

H2:Standard Syntax

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

!block example
  E<lbracket>B<tagname> I<parameters> I<attributes>]Contained Body Text[/tagname]
!endblock

!block note; label="CaveatE<nbspace>E<emdash> macros: "
Some macros look like tags or end tags. For example,
E<lbracket>{{C[jump="#page"]/page}}E<rbracket> is a macro for
E<lt>/AE<gt>. This allows you to conveniently write
E<lbracket>{{C[jump="#page"]page}}E<nbspace>I<href>]Target[C</page>],
but 'Target' is not treated as contained body text.
!endblock

When using the [C<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
E<lbracket>{{CMD[jump="#item-list"]item_list}}], a dash is just as appropriate
(i.e. C<[item-list]>). The two forms are interchangeable, except that an
ending tag must match the tag (i.e., don't use
C<E<lbracket>item-list]E<nbspace>listE<nbspace>[/item_list]>).

H2: HTML-Comment

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

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

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

E: E<lt>!--[tagname] Contained Body Text E<lbracket>/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
E<lbracket>{{C[jump="#value"]value}}E<nbspace>name] expands to 'Bill':

E: 'E<lt>!--[value name]-->'  becomes  'Bill'
E: 'E<lt>!-- [value name] -->'  becomes  '<!-- Bill -->'

H3: 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 {{CMD[jump="#Template Parsing Order"]Template Parsing Order}}
appendix if you are modifying the special administrative interface
pages and intend to use this syntax.

H2: {{CMD[id="parameters"]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:

E:    E<lbracket>{{CMD[jump="#value"]value}} name="foo"]

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

E:    E<lbracket>value foo]

The parameter C<name> is the first positional parameter for the
C<E<lbracket>{{CMD[jump="#value"]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:

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

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

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

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

E:    E<lbracket>{{C[jump="#page"]page}} scan se=[{{C[jump="#scratch"]scratch}} somevarE<2]>

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

E:    E<lbracket>{{C[jump="#page"]page}} href=scan arg="se=[{{C[jump="#scratch"]scratch}} somevar]"]

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

H2: {{CMD[id="attributes"]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.


H3: {{CMD[id="attr_interpolate"]interpolate}}

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

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

I<For standalone tags (reparsed)>
* If true, the server will process the I<output> of the tag. This is
identical to the behavior of the {{CMD[jump="#attr_reparse"]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
E<lbracket>{{CMD[jump="#include"]include}}] tag.

N: Interpolation example:

Assuming that C<name> is 'Kilroy',

!block example
   E<lbracket>{{C[jump="#log"]log}} interpolate=1][{{C[jump="#value"]value}}C< name>] was here[/log]
   E<lbracket>{{C[jump="#log"]log}} interpolate=0][{{C[jump="#value"]value}}C< name>] was here[/log]
!endblock   

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

N: Reparsing example:

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

!block example
   E<lbracket>{{C[jump="#set"]set}} name=now interpolate=0][{{C[jump="#time"]time}}]%A, %B %d, %Y[/time][/set]
!endblock

If today is Monday, January 1, 2001, 

!block example
   E<lbracket>{{C[jump="#scratch"]scratch}} name=now interpolate=0]
   E<lbracket>{{C[jump="#scratch"]scratch}} name=now interpolate=1]
!endblock

the first line yields
E:   E<lbracket>{{C[jump="#time"]time}}]%A, %B %d, %Y[/time]

while the second yields
E:   Monday, January 1, 2001


H3: {{CMD[id="attr_reparse"]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
C<interpolate> attribute controls reparsing of the output of
standalone tags (see above).

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

N: Example:

Assuming that C<name> is 'Kilroy',

!block example
  1.   E<lbracket>{{C[jump="#perl"]perl}} reparse=0]
          my $tagname = 'value';
          return "[$tagname name] was here\n"
       [/perl]

  2.   E<lbracket>{{C[jump="#perl"]perl}} reparse=1]
          my $tagname = 'value';
          return "[$tagname name] was here\n"
       [/perl]
!endblock   

expands to

!block example
  1.   E<lbracket>{{C[jump="#value"]value}}C< name>] was here

  2.   Kilroy was here
!endblock


H3: {{CMD[id="attr_send"]send}}

Deprecated


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


H2: {{CMD[id="attr_array_hash"]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:

!block example
    attribute.I<n>=value

    attribute.hashkey=value
!endblock

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

Here is an example of an attribute array:

!block example
    search.0="se=hammer
              fi=products
              sf=description"
    search.1="se=plutonium
              fi=products
              sf=comment"
!endblock

The E<lbracket>{{C[jump="#page"]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 ({{CMD[jump="icdatabase.html#Coordinated and Joined Searching"]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.

H3: 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 E<lbracket>{{C[jump="#perl"]perl}}] block or a
{{C[jump="#User-defined Tags"]usertag}}, you must actually pass an
anonymous array as the value of the attribute as N<follows:>

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

    $Tag->I<routine>( { search => $arrayref, } );
!endblock

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

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

    $Tag->I<routine>( { entry => $hashref } );
!endblock


H1: Looping tags and Sub-tags

{{CMD[id="subtags"]}}Certain tags are not standalone; these are the
ones that are interpreted as part of a surrounding looping tag
like E<lbracket>{{CMD[jump="#loop"]loop}}], E<lbracket>{{CMD[jump="#item-list"]item-list}}], E<lbracket>{{CMD[jump="#query"]query}}], or E<lbracket>{{CMD[jump="#search-region"]search-region}}E<rbracket>.

. E<lbracket>{{CMD[jump="#PREFIX-accessories"]PREFIX-accessories}}]
. E<lbracket>{{CMD[jump="#PREFIX-alternate"]PREFIX-alternate}}]
. E<lbracket>{{CMD[jump="#PREFIX-calc"]PREFIX-calc}}]
. E<lbracket>{{CMD[jump="#PREFIX-change"]PREFIX-change}}]
. E<lbracket>{{CMD[jump="#PREFIX-code"]PREFIX-code}}]
. E<lbracket>{{CMD[jump="#PREFIX-data"]PREFIX-data}}]
. E<lbracket>{{CMD[jump="#PREFIX-description"]PREFIX-description}}] (Note C<safe-data> and C<ed()> escape)
. E<lbracket>{{CMD[jump="#PREFIX-discount"]PREFIX-discount}}]
. E<lbracket>{{CMD[jump="#PREFIX-discount-subtotal"]PREFIX-discount-subtotal}}]
. E<lbracket>{{CMD[jump="#PREFIX-field"]PREFIX-field}}] (Optimization note-- one query per field if you use this; we optimize around this if only one products table) 
. E<lbracket>{{CMD[jump="#PREFIX-increment"]PREFIX-increment}}]
. E<lbracket>{{CMD[jump="#PREFIX-last"]PREFIX-last}}]
. E<lbracket>{{CMD[jump="#PREFIX-line"]PREFIX-line}}] (tab-delimited list of parameters returned)
. E<lbracket>{{CMD[jump="#PREFIX-modifier"]PREFIX-modifier}}]
. E<lbracket>{{CMD[jump="#PREFIX-next"]PREFIX-next}}]
. E<lbracket>{{CMD[jump="#PREFIX-param"]PREFIX-param}}]
. E<lbracket>{{CMD[jump="#PREFIX-pos"]PREFIX-pos}}]
. E<lbracket>{{CMD[jump="#PREFIX-price"]PREFIX-price}}]
. E<lbracket>{{CMD[jump="#PREFIX-quantity"]PREFIX-quantity}}]
. E<lbracket>{{CMD[jump="#PREFIX-subtotal"]PREFIX-subtotal}}]
. E<lbracket>{{CMD[jump="#if-PREFIX-data"]if-PREFIX-data}}]
. E<lbracket>{{CMD[jump="#if-PREFIX-field"]if-PREFIX-field}}]
. C<[if-PREFIX-param]>
. C<[if-PREFIX-pos]>
. E<lbracket>{{CMD[jump="#PREFIX-modifier-name"]modifier-name}}]
. E<lbracket>{{CMD[jump="#PREFIX-quantity-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:

!block table
Tag|Prefix|Examples
E<lbracket>{{CMD[jump="#loop"]loop}}]|loop|E<lbracket>loop-code], [loop-field price], [loop-increment]
E<lbracket>{{CMD[jump="#item-list"]item-list}}]|item|E<lbracket>item-code], [item-field price], [item-increment]
E<lbracket>{{C[jump="#search-list"]search-list}}]|item|E<lbracket>item-code], [item-field price], [item-increment]
E<lbracket>{{CMD[jump="#query"]query}}]|sql|E<lbracket>sql-code], [sql-field price], [sql-increment]
!endblock

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

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

An array list is the normal output of a E<lbracket>{{C[jump="#query"]query}}], a search, or a E<lbracket>{{C[jump="#loop"]loop}}]
tag. It returns from 1 to N C<return fields>, defined in the C<mv_return_fields>
or C<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 C<foo> column and
the C<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' },
>    ]


H2: PREFIX-accessories

E:   E<lbracket>PREFIX-accessories arglistE<rbracket>

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

!block example
    [accessories code=I<current_item_code> arg=I<arglist>]
    [item-accessories I<arglist>]
!endblock

See the E<lbracket>{{C[jump="#accessories"]accessories}}] tag for more
detail. Note that you must use the comma-delimited list to set
attributesE<nbspace>E<emdash> you cannot set named attributes with the
usual 'attribute=value' syntax.

If the list is a hash list,
i.e. an E<lbracket>{{C[jump="#item-list"]item-list}}],
then the value of the current item hash is passed so that a value default
can be established.


H2: PREFIX-alternate

E:   E<lbracket>PREFIX-alternate N] DIVISIBLE [else] NOT DIVISIBLE [/else][/PREFIX-alternate]

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

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

There are some additional primitives:

!block table
Tag|Description
E<lbracket>item-alternate first_only]|Only true on first item
E<lbracket>item-alternate last_only]|Only true on last item
E<lbracket>item-alternate except_last]|True except on last item
E<lbracket>item-alternate except_first]|True except on last item
E<lbracket>item-alternate 0]|Same as "first_only"
E<lbracket>item-alternate -1]|Same as "except_last"
!endblock

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

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

H2: PREFIX-calc

E:   E<lbracket>PREFIX-calc] 2 + [item-field price] [/PREFIX-calc]

Executes Perl code in the tag body. This is equivalent to the
E<lbracket>{{C[jump="#calc"]calc}}] ... [/calc] tag pair, except it's
calculated at loop time instead of later when the rest of the page is parsed.

H2: PREFIX-change

E:   E<lbracket>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
E<lbracket>{{C[jump="#PREFIX-field"]PREFIX-field}}]
or E<lbracket>{{C[jump="#PREFIX-field"]PREFIX-field}}C< database field>].
If you need access to ITL tags, you can use
E<lbracket>{{C[jump="#PREFIX-calc"]PREFIX-calc}}] with a C<$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
C<[condition]value[/condition]> tag pair. The E<lbracket>C<PREFIX-change>E<rbracket> tag
also processes an C<[else] [/else]> pair for output when the value does
not change.

Here is a simple example for a search list that has a field C<category> and
C<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 C<&nbsp;>
will prevent blanked table cells if you use a border.)

H2: PREFIX-code

E:   E<lbracket>PREFIX-code]

The key or code of the current loop.
In an E<lbracket>{{C[jump="#item-list"]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 C<mv_return_field>
(C<rf>).

H2: PREFIX-data

E:   E<lbracket>PREFIX-data table field]

Calls the column C<field> in database table C<table> for the current
E<lbracket>{{C[jump="#PREFIX-code"]PREFIX-code}}]
This may or may not be equivalent to
E<lbracket>{{C[jump="#PREFIX-field"]PREFIX-field}} field]
depending upon whether your search table is defined as one of the
{{C[jump="icconfig.html#ProductFiles"]ProductFiles}}.

H2: PREFIX-description

E:   E<lbracket>PREFIX-description]

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

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

H2: PREFIX-discount

E:   E<lbracket>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
E<lbracket>{{C[jump="#discount"]discount}}] tag along with quantity pricing.


H2: PREFIX-discount-subtotal

E:   E<lbracket>PREFIX-discount-subtotal]

Inserts the discounted subtotal of the ordered items.


H2: PREFIX-field

E:   E<lbracket>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 C<foo> for a string
of C<bar>. When it is found, you wish to display the value of C<foo_field>.
Unless C<foo> is in
{{C[jump="icconfig.html#ProductFiles"]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
E<lbracket>{{C[jump="#PREFIX-data"]loop-data}}C< foo field>], which specifically 
addresses the table C<foo>. See also E<lbracket>{{C[jump="#PREFIX-param"]PREFIX-param}}]
and E<lbracket>{{C[jump="#PREFIX-pos"]PREFIX-pos}}].


H2: PREFIX-increment

E:   E<lbracket>PREFIX-increment]

The current count on the list, starting from either 1 in a zero-anchored
list like E<lbracket>{{C[jump="#loop"]loop}}] or E<lbracket>{{C[jump="#item-list"]item-list}}], or from the match count in a
search list.

If you skip items with E<lbracket>{{C[jump="#PREFIX-last"]PREFIX-last}}]
or E<lbracket>{{C[jump="#PREFIX-next"]PREFIX-next}}], the count is NOT
adjusted.

H2: PREFIX-last

E:   E<lbracket>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.

H2: PREFIX-line

E:   E<lbracket>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:

E:  E<lbracket>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 C<start_column> attribute is given, the output starts with that column instead of column 0.

H2: PREFIX-modifier

E:   E<lbracket>PREFIX-modifier attribute]

If the item is a hash list (i.e.
E<lbracket>{{C[jump="#item-list"]item-list}}]), this will return the value
of the C<attribute>.

H2: PREFIX-next

E:   E<lbracket>PREFIX-next] CONDITION [/PREFIX-next]

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

H2: PREFIX-param

E:   E<lbracket>PREFIX-param name]

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

In a E<lbracket>{{C[jump="#query"]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, E<lbracket>{{C[jump="#PREFIX-code"]prefix-code}}]
and [prefix-param foo] are synonyms, as C<foo> is the first returned
parameter and becomes the code for this row.
Another synonym is E<lbracket>{{C[jump="#PREFIX-pos"]prefix-pos}} 0].

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

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

then you must use:

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

to display your results, rather than:

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

Note that the following code is invalid:

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

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

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

H2: PREFIX-pos

E:   E<lbracket>PREFIX-pos N]

Returns the value of the array parameter associated with the looping tag row. Each looping list returns an array of C<return fields>, set in searches with
C<mv_return_field> or C<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.

E<lbracket>PREFIX-pos N] outputs the data from the I<N>th column as returned
(starting with zero).
E<lbracket>{{C[jump="#PREFIX-param"]PREFIX-param}}] lets you access the data
by column name instead of by number.

In a E<lbracket>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, E<lbracket>{{C[jump="#PREFIX-code"]prefix-code}}]
and E<lbracket>{{C[jump="#PREFIX-param"]prefix-param}} foo] are synonyms,
as C<foo> is the first returned parameter and becomes the code for this row.
Another synonym is [prefix-pos 0].  [prefix-pos 1] is the same as
E<lbracket>{{C[jump="#PREFIX-param"]prefix-param}} bar].  The following code
will produce exactly the same output as the above:

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

Note that if you use the [PREFIX-pos] tag, you may have to review your column
numbers whenever you modify the columns you select.  For this reason, queries
that make use of the E<lbracket>{{C[jump="#PREFIX-param"]PREFIX-param}}] tag
may be easier to maintain and will be less prone to future surprises.

H2: PREFIX-price

E:   E<lbracket>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 C<quantity> or other
applicable attributes (like C<size> in the demo).

H2: PREFIX-quantity

E:   E<lbracket>PREFIX-quantity]

The value of the C<quantity> attribute in a hash list. Most commonly
used to display the quantity of an item in a shopping cart
E<lbracket>{{C[jump="#item-list"]item-list}}].

H2: PREFIX-subtotal

E:   E<lbracket>PREFIX-subtotal]

The E<lbracket>{{C[jump="#PREFIX-quantity"]PREFIX-quantity}}]
times the E<lbracket>{{C[jump="#PREFIX-price"]PREFIX-price}}].
This does take discounts into account.

H2: if-PREFIX-data

E:   E<lbracket>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 C<IF text> will be returned. If it is false,
i.e. blank or zero, the C<ELSE text> will be returned to the page.

This is much more efficient than the otherwise equivalent
E<lbracket>{{C[jump="#if"]if}} C<type=data term=table::field::>E<lbracket>{{C[jump="#PREFIX-code"]PREFIX-code}}]].

You cannot place a condition;
i.e. C<[if-PREFIX-data table field eq 'something']>.
Use E<lbracket>{{C[jump="#if"]if}}C< type=data> ...] for that.

Careful, a space is not a false value!

H2: if-PREFIX-field

E:   E<lbracket>if-PREFIX-field field] IF text [else] ELSE text [/else] [/if-PREFIX-field]

Same as E<lbracket>{{C[jump="#if-PREFIX-data"]if-PREFIX-data}} ...]
except uses the same data rules as
E<lbracket>{{C[jump="#PREFIX-field"]PREFIX-field}}].

# H2: {{CMD[id="PREFIX-modifier-name"]PREFIX-modifier-name}}
H2: PREFIX-modifier-name

E:   E<lbracket>PREFIX-modifier-name attribute]

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

>    1. attribute0
>    2. attribute1
>    3. attribute2

etc.

C<[PREFIX-modifier-name quantity]>
would be the same as
E<lbracket>{{C[jump="#PREFIX-quantity-name"]PREFIX-quantity-name}}].

# H2: {{CMD[id="quantity-name"]PREFIX-quantity-name}}
H2: PREFIX-quantity-name

E:   E<lbracket>item-quantity-name]

Outputs for successive items in the list:

>    1. quantity0
>    2. quantity1
>    3. quantity2

etc.

E<lbracket>{{C[jump="#PREFIX-modifier-name"]PREFIX-modifier-name}}C< quantity>]
would be the same as C<[PREFIX-quantity-name]>.


H1: Tags

Each ITL tag is show below. Calling information is defined for the main tag,
sub-tags are described in
{{CMD[jump="#Looping tags and Sub-tags"]Looping tags and Sub-tags}}.


H2: 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 moreE<nbspace>E<emdash> see also {{CMD[jump="#Looping tags and Sub-tags"]Looping tags and Sub-tags}}.


H3: Summary

!block example;
    [B<accessories> code arg]
    [B<accessories> code=[[EXAMPLE_SKU]] arg="size, radio, ... " I<other_named_attributes>] I<deprecated>
    [B<accessories> code=[[EXAMPLE_SKU]] attribute=size type=radio ... I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#accessories_code"]code}}|<<
Value of the master key in the product (or specified other) table
>>|I<none>
{{CMD[jump="#accessories_arg"]arg}}|<<
Positionally interpreted comma-delimited list of values for the
following N<attributes:>
. "attribute, type, column, table, name, outboard, passed"
>>|I<none>
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#accessories_attribute"]attribute}}|I<none>
<<
{{CMD[jump="#accessories_type"]type}}
. One of select, value, text, textarea, hidden, password, combo,
move_combo, reverse_combo, show, options, labels, checkbox, radio, links
>>|select
{{CMD[jump="#accessories_column"]column}}|I<attribute>
{{CMD[jump="#accessories_table"]table}}|products
{{CMD[jump="#accessories_name"]name}}|mv_order_I<attribute>
{{CMD[jump="#accessories_outboard"]outboard}}|I<none>
{{CMD[jump="#accessories_passed"]passed}}|I<none>
{{CMD[jump="#accessories_code"]key}} (alias for code)|I<none>
{{CMD[jump="#accessories_code"]row}} (alias for code)|I<none>
{{CMD[jump="#accessories_table"]base}} (alias for C<table>)|products
{{CMD[jump="#accessories_table"]database}} (alias for C<table>)|products
{{CMD[jump="#accessories_table"]db}} (alias for C<table>)|products
{{CMD[jump="#accessories_column"]col}} (alias for C<column>|I<attribute>
{{CMD[jump="#accessories_column"]field}} (alias for C<column>|I<attribute>
{{CMD[jump="#accessories_delimiter"]delimiter}}|comma (',')
{{CMD[jump="#accessories_prepend"]prepend}}|I<none>
{{CMD[jump="#accessories_append"]append}}|I<none>
{{CMD[jump="#accessories_extra"]extra}}|I<none>
{{CMD[jump="#accessories_js"]js}}|I<none>
{{CMD[jump="#accessories_rows"]rows}}|I<varies with >C<type>I<; often> 4
{{CMD[jump="#accessories_cols"]cols}}|I<varies with >C<type>I<; often> 40
{{CMD[jump="#accessories_width"]width}}|I<none>
{{CMD[jump="#accessories_default"]default}}|I<none>
{{CMD[jump="#accessories_price"]price}}|I<none>
{{CMD[jump="#accessories_price_data"]price_data}}|I<none>
{{CMD[jump="#accessories_contains"]contains}} (C<type>=radio or check)|I<none>
{{CMD[jump="#accessories_joiner"]joiner}} (C<type>=links)|I<none>
{{CMD[jump="#accessories_href"]href}} (C<type>=links)|I<none>
{{CMD[jump="#accessories_template"]template}} (C<type>=links)|I<none>
{{CMD[jump="#accessories_form"]form}} (C<type>=links)|C<mv_action=return>
{{CMD[jump="#accessories_empty"]empty}} (C<type>=links)|I<none>
{{CMD[jump="#accessories_secure"]secure}} (C<type>=links)|I<none>
{{CMD[jump="#accessories_new"]new}}|I<none>
{{CMD[jump="#attr_interpolate"]interpolate}} (reparse)|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<No>
Container tag|I<No>
Has Subtags|I<No>
!endblock

B<Tag expansion example:>

!block example
    E<lbracket>accessories os28044 size]
---
    <SELECT NAME="mv_order_size"><OPTION VALUE="10oz">10oz\
    <OPTION VALUE="15oz">15oz<OPTION VALUE="20oz">20oz</SELECT>
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->accessories(  { code   => '[[EXAMPLE_SKU]]',
                          arg    => 'color, radio'
                          table  => 'special_products', }  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->accessories($code, $arg, $attribute_hash_reference);
!endblock

H4: See Also

{{CMD[jump="#Looping tags and Sub-tags"]Looping tags and Sub-tags}}.


H3: 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
itemE<nbspace>E<emdash> 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 C<catalog.cfg> file directive {{I[jump="icconfig.html#UseModifier"]UseModifier}} is used to set
the name of the modifier or modifiers. For example

E:    {{C[jump="icconfig.html#UseModifier"]UseModifier}}        size color

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

!block note; label="Important Note -- "
You may not use the following names for attributes:

    item  group  quantity  code  mv_ib  mv_mi  mv_si
!endblock

You can also set modifier names with the mv_UseModifier
scratch variableE<nbspace>E<emdash>
E<lbracket>{{C[jump="#set"]set}}E<nbsp>mv_UseModifier] size color
E<lbracket>/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
C<mv_separate_items> or global directive I<SeparateItems> places each
ordered item on a separate line, simplifying attribute handling. The
scratch setting for C<mv_separate_items> has the same effect.

The modifier value is accessed in the E<lbracket>{{C[jump="#item-list"]item-list}}] loop with the
E<lbracket>{{C[jump="#PREFIX-param"]item-param}}C< attribute>]
tag, and form input fields are placed with the
E<lbracket>{{C[jump="#PREFIX-modifier-name"]modifier-name}}C< attribute>]
tag. This is similar to the way that quantity
is handled.

!block note; label="Note: "
You must be sure that no fields in your forms have digits appended to
their names if the variable is the same name as the attribute name you
select, as the
E<lbracket>{{C[jump="#PREFIX-modifier-name"]PREFIX-modifier-name}}C< size>]
variables will be placed in the
user session as the form variables size0, size1, size2, etc.
!endblock

Interchange will automatically generate the select boxes when the
E<lbracket>{{C[jump="#accessories"]accessories}}
C<code=>"[[EXAMPLE_SKU]]"E<nbspace>C<attribute=>"size"] or
E<lbracket>{{C[jump="#PREFIX-accessories"]item-accessories}}C< size>]
tags are called. They have the syntax:

!block example
    [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]"]
!endblock

!block note; label="Notes: "

^ The '{{C[jump="#accessories_attribute"]attribute}}' attribute is required.
+ See the {{C[jump="#accessories_type"]type}} attribute for a list of types.
+ The trailing '*' in value2 will mark it as the default ('SELECTED')
value in the select widget (see below).
!endblock

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

E:   name_a=Label Text1, default_name=Default Label Text*, name_b, I<etc.>

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

If an asterisk is the last character of the label text, the item is
the default selection. If no default is specified, the first will be
the default. An example:

E:    [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:

!block example
    <SELECT NAME="mv_order_color">
    <OPTION VALUE="beige">Almond
    <OPTION VALUE="gold">Harvest Gold
    <OPTION SELECTED>White
    <OPTION VALUE="green">Avocado
    </SELECT>
!endblock

In combination with the C<mv_order_item> and C<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 E<lbracket>{{C[jump="#PREFIX-modifier"]item-modifier}} color] on the
order report, order receipt, or any other page containing an
E<lbracket>{{C[jump="#item-list"]item-list}}]. 

H4: Emulating with a loop

You can also build widgets directly, without using the C<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
E<lbracket>{{C[jump="#item-list"]item-list}}]C<[/item-list]> pair.)

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

The output of the above would be similar to the output of
E<lbracket>item-accessories size, select] if the product database
field C<size> contained the value C<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.

H4: {{CMD[id="accessories_hash_lists"]Hash Lists}} E<emdash> Technical Note

As a technical note, some of the features of this tag work differently
depending upon whether it was called with an '$item' hash reference, for
example, as E<lbracket>C<item-accessories>] within an
E<lbracket>{{C[jump="#item-list"]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
E<lbracket>{{C[jump="#item-list"]item-list}}], the widget will show
the chosen item attribute value. On the other hand, within an array
list such as a E<lbracket>{{C[jump="#search-list"]search-list}}] in a
E<lbracket>{{C[jump="#search-region"]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 E<lbracket>{{C[jump="#perl"]perl}}] tag like this:

!block example; lang="Perl"
   $Tag->accessories( $code,
                      undef,              # 'arg' parameter value
                      $named_attribute_hashref,
                      $item_hashref );
!endblock

See also {{C[jump="#Looping tags and Sub-tags"]Looping tags and Sub-tags}} for
information about hash-context and array-context in looping tags.


H4: {{CMD[id="accessories_code"]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 C<code> when looping on
E<lbracket>item_accessories] because it internally sets 'C<code>' to
the key for the current item in the loop.


H4:  {{CMD[id="accessories_arg"]arg}}

B<Deprecated after Interchange 4.6>

This allows you to pass values for some of the more commonly used
attributes in the manner of the
E<lbracket>{{C[jump="#PREFIX-accessories"]item-accessories}}] tag,
as a comma-delimited positional N<list:>

E:  B<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 N<list:>

E:  B<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 N<following:>

E:  B<arg>="color, radio, , products"

Although you must use such a comma-delimited list to pass attributes
to the
E<lbracket>{{C[jump="#PREFIX-accessories"]item-accessories}}] tag,
please use named
attributes instead for the
E<lbracket>{{C[jump="#accessories"]accessories}}] tag.
The 'C<arg>' attribute is deprecated.

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


H4: {{CMD[id="accessories_attribute"]attribute}}

Despite the name, this has nothing to do with tag attributes. You can
set attributes for I<items> in a database table (typically the products
table) with the {{C[jump="icconfig.html#UseModifier"]UseModifier}}
configuration directive. Typical are C<size> or C<color>.

This selects the item attribute the tag will work with.

H4: {{CMD[id="accessories_type"]type}}

This determines the action to be taken. One of:

!block table; colvaligns="TT"
Action|Description
select|<<
Builds a dropdown <SELECT> menu for the item attribute, with the
default item attribute value SELECTED. The C<accessories> tag builds a
select widget by default if C<type> is not set.
>>
display|<<
Shows the label text for *only the selected option* if called in
{{C[jump="#accessories_hash_lists"]Hash List}} context (e.g., within an
E<lbracket>{{C[jump="#item-list"]item-list}}]). Ignored otherwise
(i.e., the tag will build the default <SELECT> menu).
>>
show|<<
Returns the list of possible attributes for the item (without labels
or any HTML widget). For example, if sku os28044 is available in
several N<sizes:>
. E<lbracket>accessories os28044 size,show]
. -----------------------------------------
. Sm=10oz, Med=15oz*, Lg=20oz
>>
options|<<
This shows the attribute options as a newline delimited list:
. E<lbracket>accessories os28044 size,options]
. -----------------------------------------
. Sm
. Med
. Lg
>>
labels|<<
This shows the attribute option N<labels:>
. E<lbracket>accessories os28044 size,options]
. -----------------------------------------
. 10oz
. 15oz*
. 20oz
>>
radio|<<
Builds a radio box group for the item, with spaces separating the
elements.
>>
radio nbsp|<<
Builds a radio box group for the item, with &nbsp;
separating the elements.
>>
radio break|<<
Builds a radio box group for the item, with '<br>'
separating the radio button/label pairs from one another.
>>
radio left n|<<
Builds a radio box group for the item, inside a
table, with the checkbox on the left side. If "n"
is present and is a digit from 2 to 9, it will align
the options in that many columns.

You can also set FONT SIZE like N<this:>
E:  type="radio left I<n> fontsizeI<m>"

where -9 <= I<m> <= 9
>>
radio right n|<<
Builds a radio box group for the item, inside a
table, with the checkbox on the right side. If "n"
is present and is a digit from 2 to 9, it will align
the options in that many columns.

You can also set FONT SIZE like N<this:>
E:  type="radio right I<n> fontsizeI<m>"

where -9 <= I<m> <= 9
>>
check|<<
Builds a checkbox group for the item, with spaces
separating the elements.
>>
check nbsp|<<
Builds a checkbox group for the item, with '&nbsp;'
separating the checkbox/label pairs from one another.
>>
check break|<<
Builds a checkbox group for the item, with '<br>'
separating the checkbox/label pairs from one another.
>>
check left I<n>|<<
Builds a checkbox group for the item, inside a
table, with the checkbox on the left side. If "n"
is present and is a digit from 2 to 9, it will align
the options in that many columns.

You can also set FONT SIZE like N<this:>
E:  type="check left I<n> fontsizeI<m>"

where -9 <= I<m> <= 9
>>
check right n|<<
Builds a checkbox group for the item, inside a
table, with the checkbox on the right side. If "n"
is present and is a digit from 2 to 9, it will align
the options in that many columns.

You can also set FONT SIZE like N<this:>
E:  type="check right I<n> fontsizeI<m>"

where -9 <= I<m> <= 9
>>
textarea_XX_YY|<<
A textarea with XX columns and YY rows. The textarea will contain the
selected item attribute value if used in
{{C[jump="#accessories_hash_lists"]Hash List}} context (e.g., within an
E<lbracket>{{C[jump="#item-list"]item-list}}]).

If you simply use 'C<type>=textarea', the size will default to 4 rows
by 40 columns, unless you have set the
{{C[jump="#accessories_rows"]rows}} or
{{C[jump="#accessories_cols"]cols}} tag attributes.
>>
text_YY|<<
A text box with YY width in characters. The HTML tag's VALUE will be
set to the selected item attribute value if used in
{{C[jump="#accessories_hash_lists"]Hash List}} context (e.g., within an
E<lbracket>{{C[jump="#item-list"]item-list}}]).

If you simply use 'C<type>=text', the width will default to 60, unless
you have set the {{C[jump="#accessories_cols"]cols}} tag attribute.
>>
combo|<<
Special type, used with nullselect filter,
for selecting from a list or inputting a
new value
>>
reverse_combo|<<
Special type, used with last_non_null filter,
for selecting from a list or inputting a
new valueE<nbspace>E<emdash> differs from combo in order of
presentation
>>
move_combo|<<
Special type, used with null_to_space or
null_to_comma filter, for selecting multiple non-ordered
values from a list or inputting into a textarea
>>
links|<<
Produces a series of links based on the option
values. The base form value is passed via the
form parameter, just like in an E<lbracket>area ...] or
E<lbracket>page ...] tag, and the value is named with
the passed NAME attribute.
>>
value|<<
Returns the selected value if called in
{{C[jump="#accessories_hash_lists"]Hash List}} context (e.g., within an
E<lbracket>{{C[jump="#item-list"]item-list}}]), or nothing otherwise.
>>
hidden|<<
Creates a hidden form field. The hidden field's VALUE will be set to
the selected item attribute value if used in
{{C[jump="#accessories_hash_lists"]Hash List}} context (e.g., within an
E<lbracket>{{C[jump="#item-list"]item-list}}]).
>>
password_YY|<<
A password box with YY width in characters. The HTML tag's VALUE will be
set to the selected item attribute value if used in
{{C[jump="#accessories_hash_lists"]Hash List}} context (e.g., within an
E<lbracket>{{C[jump="#item-list"]item-list}}]).

If you simply use 'C<type>=password', the width will default to 12,
unless you have set the {{C[jump="#accessories_cols"]cols}} tag
attribute.
>>
!endblock

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

Some types build widgets that use the ROWS=I<m>, COLS=I<n>, or certain
other HTML attributes. For these, you can define widget rows and
columns within the string that sets the type; for example,
C<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
E<lbracket>{{C[jump="#PREFIX-accessories"]item-accessories}}]
tag. Otherwise, use the
{{C[jump="#accessories_rows"]rows}}=I<m> and
{{C[jump="#accessories_cols"]cols}}=I<n> tag attributes instead.

The result of setting conflicting values in the
{{C[jump="#accessories_type"]type}} string and the C<rows> or C<cols>
attributes is undefined.

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

* B<text>
** textarea   I<(default is 4 rows, 40 columns, like 'textarea_4_40')>
** textarea_I<rows>_I<cols>
** text_I<cols>
** textarea rows=I<rows> cols=I<cols> wrap=I<WRAP value>
* B<password>
** password   I<(default is 12 columns, like 'password_12')>
** password_I<cols>
* B<combo> (similarly for B<reverse_combo> and B<move_combo>)
** combo   I<(default is 1 row, 16 columns, like 'combo_1_16')>

In any of the option building types, you can append the string C<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 C<ranges>. For example:

!block 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>
!endblock

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

H4: {{CMD[id="accessories_column"]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 '{{C[jump="#accessories_attribute"]attribute}}'
attribute.

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


H4: {{CMD[id="accessories_table"]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,
'{{C[jump="#accessories_code"]code}}' should be set to the master key
in this table. See '{{C[jump="#accessories_outboard"]outboard}}') if
you are using
E<lbracket>{{C[jump="#PREFIX-accessories"]item-accessories}}] and cannot
specify C<code=key>.


H4: {{CMD[id="accessories_name"]name}}

This sets the name of the form variable to use if appropriate for the
widget being built. Defaults to
'mv_order_B<attribute>'E<nbspace>E<emdash> i.e. if the attribute is
B<size>, the form variable will be named B<mv_order_size>.

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


H4: {{CMD[id="accessories_outboard"]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
{{C[jump="#accessories_code"]code}}, you can pass the key the tag
should use to find the accessory data.


H4: {{CMD[id="accessories_passed"]passed}}

You can use this to pass your own values to the widget the tag will
build. If you have set C<passed> to a list of widget options, then the
tag will simply build a widget of the specified
{{CMD[jump="#accessories_type"]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 C<blue> with a label of B<Blue>, and the
value of C<green> with a label of B<Sea Green>, do:

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

This will generate:

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

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


H4: {{CMD[id="accessories_delimiter"]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).


H4: {{CMD[id="accessories_prepend"]prepend}}

You can set a string to prepend to the returned output of the tag.
Note that this is I<not> a list to prepend to the fetched
{{C[jump="#accessories_attribute"]attribute}} value list, which is
treated within the tag.

For example,
!block 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>B<Append Me><br>
!endblock

H4: {{CMD[id="accessories_append"]append}}

You can set a string to append to the returned output of the tag.
Note that this is I<not> a list to append to the fetched
{{C[jump="#accessories_attribute"]attribute}} value list, which is
treated within the tag.

H4: {{CMD[id="accessories_extra"]extra}}

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

!block example
    [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>
!endblock

H4: {{CMD[id="accessories_js"]js}}

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

C<js> has no default, except when
'{{C[jump="#accessories_type"]type}}=move_combo', where the default
N<is:>

E:  onChange="addItem(this.form.XI<name>,this.form.I<name>)"


H4: {{CMD[id="accessories_rows"]rows}}

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

For some types, you can also define widget rows and columns within the
string that sets the {{C[jump="#accessories_type"]type}}; for example,
{{C[jump="#accessories_type"]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
E<lbracket>{{C[jump="#PREFIX-accessories"]item-accessories}}] tag.

The result of setting conflicting values in the
{{C[jump="#accessories_type"]type}} string and the C<rows>=I<n>
attribute is undefined.

H4: {{CMD[id="accessories_cols"]cols}}

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

See also '{{C[jump="#accessories_rows"]rows}}' above.

H4: {{CMD[id="accessories_width"]width}}

This is a quasi-alias for '{{C[jump="#accessories_cols"]cols}}' that
only works with the 'C<text>' and '<password>' types. Use
'{{C[jump="#accessories_cols"]cols}}' instead.

H4: {{CMD[id="accessories_default"]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 '{{C[jump="#accessories_passed"]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,

!block example
    [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>
---
!endblock

Obscure technical note: the tag ignores the 'C<default>' attribute if
it has an item hash referenceE<nbspace>E<emdash> see
{{C[jump="#accessories_hash_lists"]Hash Lists}} above.

H4: {{CMD[id="accessories_price"]price}}

When combined with the C<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.

!block example
    [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)
!endblock

H4: {{CMD[id="accessories_price_data"]price_data}}

H4: {{CMD[id="accessories_contains"]contains}}

Requires '{{C[jump="#accessories_type"]type}}=radio' or 'C<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.)


H4: {{CMD[id="accessories_joiner"]joiner}}

Requires '{{CMD[jump="#accessories_type"]type}}=links'.

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


H4: {{CMD[id="accessories_href"]href}}

Requires '{{CMD[jump="#accessories_type"]type}}=links'.


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


H4: {{CMD[id="accessories_template"]template}}

Requires '{{CMD[jump="#accessories_type"]type}}=links'.

Allows you to override the standard Interchange template for a
hyperlink. You probably don't need to use thisE<nbspace>E<emdash>
grep the code to grok it if you do (see 'sub build_accessory_links').


H4: {{CMD[id="accessories_form"]form}}

Requires '{{CMD[jump="#accessories_type"]type}}=links'.

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

For example, to generate a series of linksE<nbspace>E<emdash> one
per item attribute value passedE<nbspace>E<emdash> that set the
variable "color" to the corresponding {{C[jump="#accessories_passed"]passed}}
value (blank, blue, or green), do N<this:>

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

This will generate something like the following:

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

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.


H4: {{CMD[id="accessories_empty"]empty}}

Requires '{{CMD[jump="#accessories_type"]type}}=links'.

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


H4: {{CMD[id="accessories_secure"]secure}}

Requires '{{CMD[jump="#accessories_type"]type}}=links'.

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

H4: {{CMD[id="accessories_new"]new}}

Requires '{{CMD[jump="#accessories_type"]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,E<nbspace>Med=15oz,E<nbspace>Lg=20oz"N<:>

!block example
    [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>
!endblock

Or, with the default new value:

!block example
    [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>
!endblock

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


H2: and


H3: Summary

\Parameters: B<type term op compare>


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

 

# BEGIN ############### and Summary Tables ####################
.Note: This tag has special positional parameter handling.

!block example;
    [B<and> type term op compare]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#and_type"]base}}|<<
Alias for type
>>|DEFAULT_VALUE
{{CMD[jump="#and_compare"]comp}}|<<
Alias for compare
>>|DEFAULT_VALUE
{{CMD[jump="#and_compare"]compare}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#and_op"]op}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#and_op"]operator}}|<<
Alias for op
>>|DEFAULT_VALUE
{{CMD[jump="#and_term"]term}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#and_type"]type}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block 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.
!endblock


B<ASP-like Perl call:>

Not applicable. The [C<and> ...] tag only is used with
E<lbracket>{{C[jump="#if"]if}} ...], and Perl
logic obviates the
E<lbracket>{{C[jump="#if"]if}} ...] tag.

# END +++++++++++++++ and End Summary Tables ++++++++++++++++++++


H3: Description

The [and ...] tag is only used in conjunction with
E<lbracket>{{C[jump="#if"]if}} ...].  Example:

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

See the description of the E<lbracket>{{C[jump="#if"]if}}] tag.





# BEGIN ########### and Subsections ##############
H4: {{CMD[id="and_compare"]compare}}



H4: {{CMD[id="and_op"]op}}



H4: {{CMD[id="and_term"]term}}



H4: {{CMD[id="and_type"]type}}



# END ++++++++++++ and Subsections +++++++++++++

H2: area

N:Alias:  B<href>

Expands to the URL for an Interchange page or action,
including the Interchange session ID and supplied arguments. This is
very similar to the {{CMD[jump="#page"]page}} tagE<nbspace>E<emdash> these are
equivalent:
>    [page href=dir/page arg=mv_arg]TargetName</A>
>    <A HREF="[area href=dir/page arg=mv_arg]">TargetName</A>


H3: Summary

!block example;
    [B<area> href arg]
    [B<area> href=dir/page arg=page_arguments I<other_named_attributes>]
!endblock


#!block table; style="plain"; colvaligns="TTT"; format="262"
!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
href|<<
Path to Interchange page or action
. I<Special arguments>
** '{{C[jump="#area_search"]scan}}' links to a search (using search arguments in B<arg>)
** 'http://...' external link (requires B<form> attribute)
>>|process
arg|Interchange arguments to page or action|I<none>
!endblock

#!block table; style="plain"; colvaligns="TT"
!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#area_form"]form}}|I<none>
{{CMD[jump="#area_search"]search}}|I<No>
{{CMD[jump="#area_secure"]secure}}|I<No>
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

#!block table; style="plain"; headings=1; colvaligns="TT"
!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<No>
Macro|I<No>
Has end tag|I<No>
!endblock

B<Tag expansion example:>

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

    [[EXAMPLE_DOMAIN]]/cgi-bin/[[EXAMPLE_CATALOG]]/page.html?mv_session_id=[[EXAMPLE_SESSION]]&\
    mv_pc=1&mv_arg=arg1%3dAA/arg2%3dBB
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->area(  { href => "dir/page",
                   arg  => "arguments", }  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->area($href, $arg, $attribute_hash_reference);
!endblock

H4: See Also

{{CMD[jump="#page"]page}}


H3: Description


The C<area> tag is very similar to the E<lbracket>{{C[jump="#page"]page}}]
tag. It produces the URL to call an Interchange page, but it differs
from C<page> in that it does not supply the surrounding
E<lt>AE<nbspace>HREFE<nbspace>...E<gt> 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 C<area> because it also can be used in a
client-side image map.

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

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

The optional I<arg> is used just as in the {{CMD[jump="#page"]page}} tag.


H4: {{CMD[id="area_form"]form}}

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

!block example
   <A HREF="[area form="mv_order_item=[[EXAMPLE_SKU]]
                        mv_order_size=[[EXAMPLE_SIZE]]
                        mv_order_quantity=1
                        mv_separate_items=1
                        mv_todo=refresh"]"> Order [[EXAMPLE_SIZE]] [[EXAMPLE_DESCRIPTION]]</A>
!endblock

See the description of the E<lbracket>{{C[jump="#page"]page}}] tag for more
detail.


H4: {{CMD[id="area_search"]search}}

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

^ Place the search specification in the named C<search> attribute.

** Interchange will ignore the C<href> parameter (the link will be set
to 'scan'.

** If you give the C<arg> parameter a value, that value will be
available as E<lbracket>{{C[jump="#value"]value}} mv_arg] within the
search display page.

+ Set the C<href> parameter to 'scan' and set C<arg> to the search
specification.

** Note that you can use this form positionallyE<nbspace>E<emdash> the
values go into C<href> and C<arg>, so you do not have to name
parameters.

These are identical:

!block example
   <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>

!endblock

See the description of the {{CMD[jump="#page_search"]page}} tag for more
detail.

H4: {{CMD[id="area_secure"]secure}}


H4: Examples

B<Tag expansion example:>

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

    [[EXAMPLE_DOMAIN]]/cgi-bin/[[EXAMPLE_CATALOG]]/page.html?mv_session_id=[[EXAMPLE_SESSION]]&\
    mv_pc=1&mv_arg=arg1%3dAA/arg2%3dBB
!endblock

Positional call example:

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

Named call example:

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

H2: assign

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

E<lbracket>{{C[jump="#handling"]handling}}],
E<lbracket>{{C[jump="#salestax"]salestax}}],
E<lbracket>{{C[jump="#shipping"]shipping}}], and
E<lbracket>{{C[jump="#subtotal"]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.

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

H3: Summary

!block example;
    [B<assign> I<tag_name=value> I<tag_name=value> ...]
    [B<assign> C<clear=1>]
!endblock

!block table; colvaligns="TTT"; format="262"
Attributes|Description|Default
{{CMD[jump="#assign_clear"]clear}}|<<
Clears all pending 'C<assign>' tag assignments
>>|I<none>
{{CMD[jump="#assign_handling"]handling}}|<<
Assigns an override value for E<lbracket>{{C[jump="#handling"]handling}}] tags
>>|I<none>
{{CMD[jump="#assign_salestax"]salestax}}|<<
Assigns an override value for E<lbracket>{{C[jump="#salestax"]salestax}}] tags
>>|I<none>
{{CMD[jump="#assign_shipping"]shipping}}|<<
Assigns an override value for E<lbracket>{{C[jump="#shipping"]shipping}}] tags
>>|I<none>
{{CMD[jump="#assign_subtotal"]subtotal}}|<<
Assigns an override value for E<lbracket>{{C[jump="#subtotal"]subtotal}}] tags
>>|I<none>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<No>
Container tag|I<No>
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->assign(  { shipping => 2.99, }  );
!endblock

H4: See Also

E<lbracket>{{C[jump="#handling"]handling}}],
E<lbracket>{{C[jump="#salestax"]salestax}}],
E<lbracket>{{C[jump="#shipping"]shipping}}],
E<lbracket>{{C[jump="#subtotal"]subtotal}}], 
E<lbracket>{{C[jump="icdatabase.html#Shipping"]Shipping}}]


H3: Description

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

E<lbracket>{{C[jump="#handling"]handling}}],
E<lbracket>{{C[jump="#salestax"]salestax}}],
E<lbracket>{{C[jump="#shipping"]shipping}}], and
E<lbracket>{{C[jump="#subtotal"]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
{{C[jump="#assign_clear"]clear}} attribute.

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

!block example
    [assign salestax=0 shipping=4.99]
!endblock

This restores the E<lbracket>{{C[jump="#salestax"]salestax}}] tag and
eliminates handling N<charges:>

!block example
    [assign salestax="" handling=0]
!endblock

This restores the normal behavior to the
E<lbracket>{{C[jump="#shipping"]shipping}}] and
E<lbracket>{{C[jump="#handling"]handling}}] N<tags:>

!block example
    [assign clear=1]
!endblock

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

NoteE<nbspace>E<emdash> 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 ("").


H4: {{CMD[id="assign_clear"]clear}}

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

H4: {{CMD[id="assign_shipping"]shipping}}

This sets the total value of shipping, rounded to locale-specific fractional digits. Always
active if assigned a numeric value. See the
E<lbracket>{{C[jump="#shipping"]shipping}}] tag for detail about rounding, etc.

H4: {{CMD[id="assign_handling"]handling}}

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

!block note; label="Important note"

The E<lbracket>{{C[jump="#handling"]handling}}]
tag is unlike the others in that it will be inactive (despite your
assignment) unless the E<lbracket>{{C[jump="#value"]value}}
B<mv_handling>] variable is true (i.e., a nonzero, non-blank value).
!endblock

H4: {{CMD[id="assign_salestax"]salestax}}

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


H4: {{CMD[id="assign_subtotal"]subtotal}}

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


Note that you cannot assign to
E<lbracket>{{C[jump="#total-cost"]total-cost}}]E<nbspace>E<emdash> it
will always be the sum of the four above.

Before using the C<assign> tag, please be sure you understand the
dependencies within the pricing system, such as the relationship
between E<lbracket>{{C[jump="#total-cost"]total-cost}}] and assigned
tags.


H2: attr-list

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

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

H3: Summary
 
# BEGIN ############### attr_list Summary Tables ####################
!block example;
    C<$Tag-E<gt>attr_list($template, $hashref)>
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#attr_list_hash"]hash}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<NA> (Though the template is technically body text)
Has Subtags|I<No>
Nests|I<No>
!endblock


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

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

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

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

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

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

# END +++++++++++++++ attr_list End Summary Tables ++++++++++++++++++++


H3: Description

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

Tags according to the following rules:


H4: E<lbrace>key}

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

H4: E<lbrace>key|fallback string}

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

H4: E<lbrace>key true string}

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

H4: E<lbrace>key?} true text {/key?}

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

H4: E<lbrace>key:} false text {/key:}

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



# BEGIN ########### attr_list Subsections ##############
H4: {{CMD[id="attr_list_hash"]hash}}

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

# END ++++++++++++ attr_list Subsections +++++++++++++

H2: banner

Implements random or rotating banner ads. See also
{{CMD[jump="ictemplates.html#Banner/Ad rotation"]Banner/Ad rotation}}.


H3: Summary

!block example;
    [B<banner> category]
    [B<banner> category=my_category I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#banner_category"]category}}|<<
>>|default
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#banner_table"]table}}|banner
{{CMD[jump="#banner_r_field"]r_field}} (unweighted)|rotate
{{CMD[jump="#banner_b_field"]b_field}}|banner
{{CMD[jump="#banner_separator"]separator}} (unweighted)|':'
{{CMD[jump="#banner_delimiter"]delimiter}} (unweighted)|'{or}'
{{CMD[jump="#banner_weighted"]weighted}}|I<No>
{{CMD[jump="#banner_once"]once}} (weighted)|I<No>
{{CMD[jump="#banner_c_field"]c_field}} (weighted)|category
{{CMD[jump="#banner_w_field"]w_field}} (weighted)|weight
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<No>
Container tag|I<No>
!endblock

B<Tag expansion example:>

!block example
    [B<banner> category=my_category]
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->banner(  { category => $key, } );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->banner($category, $attribute_hash_reference);
!endblock

H4: See Also

{{CMD[jump="ictemplates.html#Banner/Ad rotation"]Banner/Ad rotation}}

H3: Description


Implements random or rotating banner ads. See
{{CMD[jump="ictemplates.html#Banner/Ad rotation"]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 N<example:>

!block table; colvaligns="TTTTT"
code|category|weight|rotate|banner
m_3|cat1|7|0|my banner 3
m_1|cat1|1|0|my banner 1
default|||1|Default 1{or}Default 2{or}Default 3
m_2|cat1|2|0|my banner 2
t_1|cat2|4|0|their banner 1
t_2|cat2|1|0|their banner 2
!endblock


H4: {{CMD[id="banner_category"]category}}

N<Default:> category="default"

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

H4: {{CMD[id="banner_table"]table}}

N<Default:> table="banner"

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


H4: {{CMD[id="banner_r_field"]r_field}}

N<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, 'DefaultE<nbspace>1', 'DefaultE<nbspace>2' and
'DefaultE<nbspace>3' would rotate.


H4: {{CMD[id="banner_b_field"]b_field}}

N<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
{{CMD[jump="#banner_delimiter"]delimiter}} below).

H4: {{CMD[id="banner_separator"]separator}}

N<Default:> separator=":"

Unweighted ads only.

This sets the separator within the table key (i.e., code) for
multi-level categorized ads. See
{{CMD[jump="ictemplates.html#Banner/Ad rotation"]Banner/Ad rotation}}.


H4: {{CMD[id="banner_delimiter"]delimiter}}

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

Unweighted ads only.

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


H4: {{CMD[id="banner_weighted"]weighted}}

The C<banner> tag will not apply weighting from the table unless you set
C<weighted>=1. Note that the tag will behave as if you gave it a
standard unweighted entryE<nbspace>E<emdash> it will look for a
matching row rather than a matching category.

H4: {{CMD[id="banner_once"]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 {{CMD[jump="ictemplates.html#Banner/Ad rotation"]Banner/Ad rotation}}.


H4: {{CMD[id="banner_c_field"]c_field}}

N<Default:> c_field="category"

Weighted ads only.

This specifies the column containing the banner category for weighted
ads. The C<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.


H4: {{CMD[id="banner_w_field"]w_field}}

N<Default:> w_field="weight"

Weighted ads only.

This specifies the column containing the banner weight.



H2: bounce


H3: Summary

\Parameters: B<href if>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

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

 

# BEGIN ############### bounce Summary Tables ####################
!block example;
    [B<bounce> href if]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#bounce_href"]href}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#bounce_if"]if}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [bounce href if]
---
    TAG RESULT
!endblock


B<ASP-like Perl call:>

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


# END +++++++++++++++ bounce End Summary Tables ++++++++++++++++++++


H3: 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 E<lbracket>{{C[jump="#area"]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]

The optional parameter 'if' allows the performance of the redirection to be
dependent on the outcome of a logical test.  This test might be a simple as
the presence or absence of a value, or as complex as multiple lines of Perl
within a [calc] or [perl] construct. The bounce will only occur if the
argument resolves to a non-false value:
 
> [bounce href=ord/basket if="[calc][nitems] > 2[/calc]"]
  
...redirects the user's browser to the basket page if there are more than
two items in his/her cart.





# BEGIN ########### bounce Subsections ##############
H4: {{CMD[id="bounce_href"]href}}



H4: {{CMD[id="bounce_if"]if}}



# END ++++++++++++ bounce Subsections +++++++++++++

H2: calc

Calculates the value of the enclosed arithmetic expression.


H3: Summary

!block example;
    [B<calc>] I<Expression> [/calc]
!endblock

B<No parameters>

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

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<No>
Has Subtags|I<No>
Container tag|I<Yes>
Nests|I<No>
!endblock

B<ASP-like Perl call:>

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

H3: Description

Calculates the value of the enclosed arithmetic expression.

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

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

>    [calc] 2 + 2 [/calc]

will expand to:

>    4

The [calc] tag is really the same as the E<lbracket>{{C[jump="#perl"]perl}}]
tag, except that it doesn't accept arguments, interpolates surrounded
Interchange tags by default, and is slightly more efficient to parse.

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

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


# END ++++++++++++ calc Subsections +++++++++++++

H2: calcn

Calculates the value of the enclosed arithmetic expression.


H3: Summary

!block example;
    [B<calcn>] I<Expression> [/calcn]
!endblock

B<No parameters>

B<No attributes>

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<No>
Has Subtags|I<No>
Container tag|I<Yes>
Nests|I<No>
!endblock

B<ASP-like Perl call:>

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

H3: Description

Equivalent to the E<lbracket>{{C[jump="#calc"]calc}}] tag, except that
it does not {{CMD[jump="#attr_interpolate"]interpolate}} by default.

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


# END ++++++++++++ calcn Subsections +++++++++++++


H2: cart


H3: Summary

\Parameters: B<name>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

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

 

# BEGIN ############### cart Summary Tables ####################
!block example;
    [B<cart> name]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#cart_name"]name}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [cart name]
---
    TAG RESULT
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->cart(  { name => VALUE_name
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->cart(name, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ cart End Summary Tables ++++++++++++++++++++


H3: Description


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




# BEGIN ########### cart Subsections ##############
H4: {{CMD[id="cart_name"]name}}



# END ++++++++++++ cart Subsections +++++++++++++

H2: catch

The page content contained within the E<lbracket>C<catch> I<label>]E<lbracket>C</catch>] block executes if the correspondingly labelled  {{C[jump="#try"]try}} block fails.

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

!block example
    [I<error message>]body text[/I<error message>]
!endblock

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


See also E<lbracket>{{C[jump="#try"]try}}].


H3: Summary


!block example;
    [B<try> I<my_label>]
        I<Body text to return if no error>
    [B</try>]
    .
    .
    .
    [B<catch> label=I<my_label> I<other_named_attributes>]
        [/I<Pattern matching error message 1>/]
            Return this if error 1 occurs
        [/I<Pattern matching error message 1>/]

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

        I<Default body text to process if try block caused an error>
    [B</catch>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#catch_label"]label}}|<<
The label shared by the paired {{C[jump="#try"]try}} and C<catch> blocks
>>|'default'
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<Yes>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<No>
Container tag|Yes
Has Subtags|<<
. E<lbracket>I<Error message text>]
.. body
. E<lbracket>I</Error message text>]
>>
!endblock

B<Tag expansion example>

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

!block example
    [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 {{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe}} error
        [/eval "string" trapped by operation mask/]
        Other division error
    [/catch]
---
   Perl {{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe}} error
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->catch(  { label => I<'my_label'>, },
                  $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->catch($label, $attribute_hash_reference, $body);
!endblock

H4: See Also

{{CMD[jump="#try"]try}}


# BEGIN ############### catch Summary Tables ####################
!block example;
    [catch]
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<No>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [catch]
---
    TAG RESULT
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->catch(  { 
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->catch(, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ catch End Summary Tables ++++++++++++++++++++


H3: Description

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

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

!block example
    [/I<error message>/]special catch block for the error[/I<error message>/]
!endblock

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:

!block example
   127.0.0.1 4cU3Pgsh:127.0.0.1 - [24/May/2001:14:45:07 -0400]\
   tag /cgi-bin/tag72/tag {{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe}}: Illegal division by zero\
   at (eval 526) line 2.
!endblock

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

H4: {{CMD[id="catch_label"]label}}

This is the label specifying the corresponding E<lbracket>{{C[jump="#try"]try}} block. Defaults to 'default'.



H2: cgi

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

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

# BEGIN ########### cgi Subsections ##############

H3: Summary

!block example;
    [B<cgi> name]
    [B<cgi> name=I<cgi_var_name> I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#cgi_name"]name}}|<<
This is the name of the CGI variable whose value you want.
>>|I<None>
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#cgi_set"]set}}|I<none>
{{CMD[jump="#cgi_hide"]hide}}|I<No>
{{CMD[jump="#cgi_filter"]filter}}|I<none>
{{CMD[jump="#cgi_keep"]keep}} (with filter)|I<No>
{{CMD[jump="#cgi_enable_html"]enable_html}}|I<No>
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<Yes>
!endblock

B<Tag expansion example:>

Assuming CGI variable 'foo' = 'bar',

!block example
    [cgi foo]
---
    bar
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->cgi( { name => var_name } );

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

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

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->cgi($name, $attribute_hash_reference);
!endblock


H3: Description

Displays the value of a CGI variable B<submitted to the current page>.
This is similar to E<lbracket>{{C[jump="#value"]value}} ...], except it
displays the transitory values that have been submitted with the current
request.

For instance, if you access the following URL:

>        http://VENDURL/pagename?foo=bar

C<bar> will be substituted for C<[cgi foo]>.

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

H4: {{CMD[id="cgi_name"]name}}

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

H4: {{CMD[id="cgi_set"]set}}

You can change a value with 'C<set>=I<new_value>'.
The tag will return the CGI value you set unless you also set the
{{CMD[jump="#cgi_hide"]hide}}=1 attribute.

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


H4: {{CMD[id="cgi_hide"]hide}}

Setting C<hide>=1 suppresses the tag's return value, which can be
useful with the {{C[jump="#cgi_set"]set}} attribute.


H4: {{CMD[id="cgi_filter"]filter}}

See the {{C[jump="#filter"]filter}} tag for a list of filters.

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


H4: {{CMD[id="cgi_keep"]keep}} (with filter)

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


H4: {{CMD[id="cgi_default"]default}}

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

!block example
    [cgi name=myname set=0 hide=1]
    [cgi name=myname default="Using default"]
!endblock


H4: {{CMD[id="cgi_enable_html"]enable_html}}

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


H2: checked

H3: Summary

\Parameters: B<name value>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

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

 

# BEGIN ############### checked Summary Tables ####################
!block example;
    [B<checked> name value I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#checked_case"]case}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#checked_cgi"]cgi}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#checked_default"]default}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#checked_name"]name}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#checked_multiple"]multiple}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#checked_value"]value}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

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


# END +++++++++++++++ checked End Summary Tables ++++++++++++++++++++


H3: 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 C<var_name> is equal to
C<value>. Not case sensitive unless the optional C<case=1> parameter is used.

The C<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 checkedE<nbspace>E<emdash> if you
want to use the volatile CGI space (i.e. [cgi foo]) use the option
C<cgi=1>.

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

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



# BEGIN ########### checked Subsections ##############
H4: {{CMD[id="checked_case"]case}}

H4: {{CMD[id="checked_cgi"]cgi}}

H4: {{CMD[id="checked_default"]default}}

H4: {{CMD[id="checked_name"]name}}

H4: {{CMD[id="checked_multiple"]multiple}}

H4: {{CMD[id="checked_value"]value}}

# END ++++++++++++ checked Subsections +++++++++++++

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


H3: Summary

!block example;
    [B<control> name default I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#control_default"]default}}|<<
Value to return if scratchpad variable missing or empty
>>|DEFAULT_VALUE
{{CMD[jump="#control_name"]name}}|<<
Name of scratchpad variable to set or return
>>|DEFAULT_VALUE
{{CMD[jump="#control_reset"]reset}}|<<
Resets scratchpad (i.e. $::Control array) by setting special scratch variable 'control_index' to 0. Control_index is an index into the $::Control == $Vend::Session->{control} array of hashrefs.
* (must not specify name; may specify default)
>>|DEFAULT_VALUE
{{CMD[jump="#control_set"]set}}|<<
Copies named scratch variable (i.e., from $::Scratch) to scratchpad with current control index.
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [control name default]
---
    TAG RESULT
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->control(  { default => VALUE_default
                      name => VALUE_name
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->control(name,default, $attribute_hash_reference, $body);
!endblock

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



# BEGIN ############ control Subsections ##############
H4: {{CMD[id="control_default"]default}}

Value to return if scratchpad variable missing or empty


H4: {{CMD[id="control_name"]name}}

Name of scratchpad variable to set or return


H4: {{CMD[id="control_reset"]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)


H4: {{CMD[id="control_set"]set}}

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


# END +++++++++++++ control Subsections ++++++++++++

H2: control_set

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

H3: Summary

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

!block example
    [control_set index=4]
        [var_one]I<var_one_value>[/var_one]
        [var_two]I<var_two_value>[/var_two]
        [var_three]I<var_three_value>[/var_three]
    [/control_set]
!endblock

\Parameters: B<index>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

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

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

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

 

# BEGIN ############### control_set Summary Tables ####################
!block example;
    [B<control_set> index I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#control_set_index"]index}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [control_set index]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->control_set(  { index => VALUE_index
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->control_set(index, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ control_set End Summary Tables ++++++++++++++++++++


H3: Description

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



# BEGIN ########### control_set Subsections ##############
H4: {{CMD[id="control_set_index"]index}}



# END ++++++++++++ control_set Subsections +++++++++++++

H2: counter


H3: Summary

\Parameters: B<file start date sql>

\Positional parameters: B<file>

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

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

Attribute aliases

>            name ==> file

# BEGIN ############### counter Summary Tables ####################
!block example;
    [B<counter> file]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#counter_file"]file}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#counter_file"]name}}|<<
Alias for file
>>|DEFAULT_VALUE
{{CMD[jump="#counter_file"]sql}}|<<
Asserts a SQL-based counter
>>|DEFAULT_VALUE
{{CMD[jump="#counter_file"]date}}|<<
Asserts a date-based counter
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [counter file]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->counter(  { file => VALUE_file, sql => 'table:seq', start => VALUE, }  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->counter(file, $attribute_hash_reference);
!endblock

# END +++++++++++++++ counter End Summary Tables ++++++++++++++++++++


H3: 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 C<etc/counter>. If the file does not exist, it is created and initialized to the value of the C<start> parameter.

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

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

\WARNING: This tag may not work under {{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe}}, i.e. in embedded Perl.

Additional parameters:


H4: {{CMD[id="counter_decrement"]decrement=1}}

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

H4: {{CMD[id="counter_start"]start=50}}

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

H4: {{CMD[id="counter_value"]value=1}}

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

H4: {{CMD[id="counter_sql"]sql="table:sequence"}}

The table and sequence name of the SQL counter.

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

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

H4: {{CMD[id="counter_date"]date="local"}}

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

H4: {{CMD[id="counter_date"]date="gmt"}}

Specifies the counter will be date-based with GMT.

# BEGIN ########### counter Subsections ##############
H4: {{CMD[id="counter_file"]file}}

H3: SQL Counter Examples

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

!block example
  CREATE SEQUENCE "foo" start 1 increment 1 maxvalue 2147483647 minvalue 1 cache 1 
!endblock

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

Then access it with:

!block example
    [counter sql="sometable:foo"]
!endblock

You can create as many sequences as you like.

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

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

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

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

Then access it with:

!block example
    [counter sql="sequence_name:sequence_name"]
!endblock

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

!block example
  mysql> create table sequence_name(id int NOT NULL AUTO_INCREMENT PRIMARY KEY);
!endblock

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

!block example
    [counter sql="products:sequence_name"]
!endblock

To set up an Oracle counter, create a sequence:

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

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

!block example
    [counter sql="sometable:foo"]
!endblock

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

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

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

Then access it with:

!block example
    [counter sql="sequence_name:sequence_name"]
!endblock

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

!block example
  mysql> create table sequence_name(id int NOT NULL AUTO_INCREMENT PRIMARY KEY);
!endblock

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

!block example
    [counter sql="products:sequence_name"]
!endblock

# END ++++++++++++ counter Subsections +++++++++++++

H2: currency


H3: Summary

\Parameters: B<convert noformat>

Positional parameters in same order.


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

Interpolates B<container text> by default.

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

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

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

 

# BEGIN ############### currency Summary Tables ####################
!block example;
    [B<currency> convert noformat]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#currency_convert"]convert}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#currency_noformat"]noformat}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [currency convert noformat]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->currency(  { convert => VALUE_convert
                       noformat => VALUE_noformat
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->currency(convert,noformat, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ currency End Summary Tables ++++++++++++++++++++


H3: Description


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

>    [currency]4[/currency]

will display:

>    4.00

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






# BEGIN ########### currency Subsections ##############
H4: {{CMD[id="currency_convert"]convert}}



H4: {{CMD[id="currency_noformat"]noformat}}



# END ++++++++++++ currency Subsections +++++++++++++

H2: data


H3: Summary

Main Parameters: B<table field key>

Positional parameters in same order.

Additional parameters: hash foreign value

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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

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

Attribute aliases

>            base ==> table
>            code ==> key
>            col ==> field
>            column ==> field
>            database ==> table
>            name ==> field
>            row ==> key


 

# BEGIN ############### data Summary Tables ####################
!block example;
    [B<data> table field key I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#data_table"]base}}|<<
Alias for table
>>|DEFAULT_VALUE
{{CMD[jump="#data_key"]code}}|<<
Alias for key
>>|DEFAULT_VALUE
{{CMD[jump="#data_field"]col}}|<<
Alias for field
>>|DEFAULT_VALUE
{{CMD[jump="#data_field"]column}}|<<
Alias for field
>>|DEFAULT_VALUE
{{CMD[jump="#data_table"]database}}|<<
Alias for table
>>|DEFAULT_VALUE
{{CMD[jump="#data_field"]field}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#data_hash"]hash}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#data_key"]key}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#data_field"]name}}|<<
Alias for field
>>|DEFAULT_VALUE
{{CMD[jump="#data_key"]row}}|<<
Alias for key
>>|DEFAULT_VALUE
{{CMD[jump="#data_table"]table}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [data table field key]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->data(  { field => VALUE_field
                   key => VALUE_key
                   table => VALUE_table
});
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->data(table,field,key, $attribute_hash_reference);
!endblock

# END +++++++++++++++ data End Summary Tables ++++++++++++++++++++


H3: Description


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

Returns the value of the field in a database table, or from the C<session>
namespace. If the optional B<value> is supplied, the entry will be
changed to that value. If the option increment* is present, the field
will be atomically incremented with the value in B<value>. Use negative
numbers in C<value> to decrement. The C<append> attribute causes the value
to be appended; and finally, the C<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 C<products> database writable, for example.
B<This must be done before ANY access to that table.>

In addition, the C<[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.






# BEGIN ########### data Subsections ##############
H4: {{CMD[id="data_field"]field}}

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

H4: {{CMD[id="data_foreign"]foreign}}

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

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

From this table named "foo":

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

These calls:

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

would both return "Item 1".

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

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

would return "Item 2".

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

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

also returns "Item 2".

H4: {{CMD[id="data_hash"]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:

!block example; lang="Perl"
	$row_hash = $Tag->data({
		table => 'products',
		key   => 'os28004',
		hash  => 1,
	});
!endblock

You could then access desired values this way:

!block example; lang="Perl"
	$out = 'Price: ' . $row_hash->{price};
!endblock

H4: {{CMD[id="data_key"]key}}

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


H4: {{CMD[id="data_table"]table}}

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


# END ++++++++++++ data Subsections +++++++++++++

H2: default


H3: Summary

\Parameters: B<name default>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

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

 

# BEGIN ############### default Summary Tables ####################
!block example;
    [B<default> name default I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#default_default"]default}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#default_name"]name}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [default name default]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->default(  { default => VALUE_default
                      name => VALUE_name
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->default(name,default, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ default End Summary Tables ++++++++++++++++++++


H3: Description


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






# BEGIN ########### default Subsections ##############
H4: {{CMD[id="default_default"]default}}



H4: {{CMD[id="default_name"]name}}



# END ++++++++++++ default Subsections +++++++++++++

H2: description


H3: Summary

\Parameters: B<code base>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

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

 

# BEGIN ############### description Summary Tables ####################
!block example;
    [B<description> code base]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#description_base"]base}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#description_code"]code}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [description code base]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->description(  { base => VALUE_base
                          code => VALUE_code
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->description(code,base, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ description End Summary Tables ++++++++++++++++++++


H3: 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 C<catalog.cfg> directive C<DescriptionField>. If there is more than one
products file defined, they will be searched in order unless constrained by the
optional argument B<base>.

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






# BEGIN ########### description Subsections ##############
H4: {{CMD[id="description_base"]base}}



H4: {{CMD[id="description_code"]code}}



# END ++++++++++++ description Subsections +++++++++++++

H2: discount


H3: Summary

\Parameters: B<code>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

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

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

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

 

# BEGIN ############### discount Summary Tables ####################
!block example;
    [B<discount> code]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#discount_code"]code}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [discount code]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->discount(  { code => VALUE_code
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->discount(code, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ discount End Summary Tables ++++++++++++++++++++


H3: Description


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

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

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

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

To apply a straight 20% discount to all items:

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

or with named attributes:

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

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

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

To subtract $5.00 from the customer's order:

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

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

>    [discount ALL_ITEMS][/discount]

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

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

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

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

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

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







# BEGIN ########### discount Subsections ##############
H4: {{CMD[id="discount_code"]code}}



# END ++++++++++++ discount Subsections +++++++++++++

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

H3: Summary

No parameters.

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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->dump(
>        {
>        }
>    )
>
> OR
>
>    $Tag->dump($);

 

# BEGIN ############### dump Summary Tables ####################
!block example;
    [B<dump>]
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [dump]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->dump(  { 
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->dump(, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ dump End Summary Tables ++++++++++++++++++++


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





H2: ecml

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

H3: Summary

!block example;
    [B<ecml> name function I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#ecml_function"]function}}|<<
ecml function (default = 'widget')
>>|DEFAULT_VALUE
{{CMD[jump="#ecml_name"]name}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [ecml name function]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->ecml(  { function => VALUE_function
                   name => VALUE_name
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->ecml(name,function, $attribute_hash_reference, $body);
!endblock

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

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

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 C<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 C<fname> and C<lname>, then it will not.



# BEGIN ############ ecml Subsections ##############
H4: {{CMD[id="ecml_function"]function}}

ecml function (default = 'widget')


H4: {{CMD[id="ecml_name"]name}}



# END +++++++++++++ ecml Subsections ++++++++++++

H2: either

The [either]this[or]that[/either] implements a check for the first
true, non-blank value. It splits on [or], then with each piece
Interpolates and strips leading and trailing whitespace. If a piece is
true (in the Perl sense) then it will be returned and subsequent pieces
will be discarded without interpolation.

H3: Summary

!block example
    [either]
        This
    [or]
        That
    [or]
        The other
    [/either]
!endblock

No parameters.

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

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

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->either(
>        {
>        },
>        BODY
>    )
>
> OR
>
>    $Tag->either($BODY);

 

# BEGIN ############### either Summary Tables ####################
!block example;
    [B<either>]
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [either]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->either(  { 
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->either(, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ either End Summary Tables ++++++++++++++++++++


H3: Description

B<NO Description>





H2: error


H3: Summary

\Parameters: B<name>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

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

 

# BEGIN ############### error Summary Tables ####################
!block example;
    [B<error> name I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#error_name"]name}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [error name]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->error(  { name => VALUE_name
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->error(name, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ error End Summary Tables ++++++++++++++++++++


H3: 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 C<submit> form processing action. It works in
conjunction with the definition set in C<mv_order_profile>, and can
generate error messages in any format you desire.

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

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

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

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

The options are:


H4: {{CMD[id="error_all"]all=1}}

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

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

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

H4: {{CMD[id="error_joiner"]joiner=I<char>}}

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

H4: {{CMD[id="error_keep"]keep=1}}

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

H4: {{CMD[id="error_show_error"]show_error=1}}

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

H4: {{CMD[id="error_show_label"]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:

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

H4: {{CMD[id="error_show_var"]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:

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

H4: {{CMD[id="error_std_label"]std_label}}

std_label=<label string for error message>

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

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

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

H4: {{CMD[id="error_required"]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.






# BEGIN ########### error Subsections ##############
H4: {{CMD[id="error_name"]name}}



# END ++++++++++++ error Subsections +++++++++++++

H2: export

Exports a database to a delimited text file (see also
{{C[jump="#import"]import}}).


H3: Summary

!block example;
    [B<export> table I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#export_table"]base}}|<<
Alias for table
>>|DEFAULT_VALUE
{{CMD[jump="#export_table"]database}}|<<
Alias for table
>>|DEFAULT_VALUE
{{CMD[jump="#export_delete"]delete}}|<<
If 'verify' attribute also set, deletes column specified by 'field' attribute rather than adding a column.
>>|DEFAULT_VALUE
{{CMD[jump="#export_field"]field}}|<<
The column to add (or delete if delete and verify are true)
>>|DEFAULT_VALUE
{{CMD[jump="#export_file"]file}}|<<
Filename to export to. Note that the NoAbsolute directive and other conditions may affect actual location of the output file. Default is taken from the catalog.cfg Database directive for this table.
>>|DEFAULT_VALUE
{{CMD[jump="#export_sort"]sort}}|<<
Output sorted rows (N<usage:> sort="I<sort_field>:I<sort_option>") (see search/form variable 'mv_sort_option' for sort options)
>>|DEFAULT_VALUE
{{CMD[jump="#export_table"]table}}|<<
The table to export
>>|DEFAULT_VALUE
{{CMD[jump="#export_type"]type}}|<<
Specifies the [line, record] delimiter types. Default is taken from the catalog.cfg Database directive for this table. 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")
>>|DEFAULT_VALUE
{{CMD[jump="#export_verify"]verify}}|<<
must be true when deleting a column
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [export table]
---
    1
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->export(  { table => VALUE_table
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->export(table, $attribute_hash_reference, $body);
!endblock

H3: Description

Exports 'table' to a delimited text file. See also {{C[jump="#import"]import}} tag which imports files into databases.



# BEGIN ############ export Subsections ##############
H4: {{CMD[id="export_delete"]delete}}

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


H4: {{CMD[id="export_field"]field}}

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


H4: {{CMD[id="export_file"]file}}

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


H4: {{CMD[id="export_sort"]sort}}

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


H4: {{CMD[id="export_table"]table}}

The table to export


H4: {{CMD[id="export_type"]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")


H4: {{CMD[id="export_verify"]verify}}

must be true when deleting a column


# END +++++++++++++ export Subsections ++++++++++++

H2: field


H3: Summary

\Parameters: B<name code>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

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

Attribute aliases

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


 

# BEGIN ############### field Summary Tables ####################
!block example;
    [B<field> name code]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#field_code"]code}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#field_name"]col}}|<<
Alias for name
>>|DEFAULT_VALUE
{{CMD[jump="#field_name"]column}}|<<
Alias for name
>>|DEFAULT_VALUE
{{CMD[jump="#field_name"]field}}|<<
Alias for name
>>|DEFAULT_VALUE
{{CMD[jump="#field_code"]key}}|<<
Alias for code
>>|DEFAULT_VALUE
{{CMD[jump="#field_name"]name}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#field_code"]row}}|<<
Alias for code
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [field name code]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->field(  { code => VALUE_code
                    name => VALUE_name
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->field(name,code, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ field End Summary Tables ++++++++++++++++++++


H3: Description


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

Note that if you only have one ProductFile C<products>, which is the default,
C<[field column key]> is the same as E<lbracket>{{C[jump="#data"]data}} products column key].






# BEGIN ########### field Subsections ##############
H4: {{CMD[id="field_code"]code}}



H4: {{CMD[id="field_name"]name}}



# END ++++++++++++ field Subsections +++++++++++++

H2: file


H3: Summary

\Parameters: B<name type>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

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

 

# BEGIN ############### file Summary Tables ####################
!block example;
    [B<file> name type]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#file_name"]name}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#file_type"]type}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [file name type]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->file(  { name => VALUE_name
                   type => VALUE_type
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->file(name,type, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ file End Summary Tables ++++++++++++++++++++


H3: Description


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

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






# BEGIN ########### file Subsections ##############
H4: {{CMD[id="file_name"]name}}



H4: {{CMD[id="file_type"]type}}



# END ++++++++++++ file Subsections +++++++++++++

H2: filter


H3: Summary

\Parameters: B<op>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. E<lbracket>filter] FOO E<lbracket>/filter].
\Nesting: NO

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

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

 

# BEGIN ############### filter Summary Tables ####################
!block example;
    [B<filter> op]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#filter_op"]op}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

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

    Produces:

		upper case you want to see as lower case

!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->filter(  { op => VALUE_op
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->filter(op, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ filter End Summary Tables ++++++++++++++++++++


H3: 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 C<cgi>, C<data>, and C<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:

H4: Length filter 

If you pass just a numeric argument, filter will return only first N characters.  For example:
!block example
[filter 5]Interchange[/filter]
!endblock
results in:

"Inter"

By appending a ".", you can direct Interchange to append an ellipsis:
!block example
[filter 5.]Interchange[/filter]
!endblock
results in:

"Inter..."

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

H4: {{CMD[id="filter_op_cgi"]cgi}}

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

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

H4: {{CMD[id="filter_op_digits"]digits}}

Returns only digits.

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

H4: {{CMD[id="filter_op_digits_dot"]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;
>                },

H4: {{CMD[id="filter_op_dos"]dos}}

Turns linefeeds into carriage-return / linefeed pairs.

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

H4: {{CMD[id="filter_op_entities"]entities}}

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

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



H4: {{CMD[id="filter_op_gate"]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;
>                },

H4: {{CMD[id="filter_op_lc"]lc}}

Lowercases the text.

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

H4: {{CMD[id="filter_op_lookup"]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;
>                },

H4: {{CMD[id="filter_op_mac"]mac}}

Changes newlines to carriage returns.

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

H4: {{CMD[id="filter_op_name"]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";
>                },

H4: {{CMD[id="filter_op_namecase"]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;
>                },

H4: {{CMD[id="filter_op_no_white"]no_white}}

Strips all whitespace.

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

H4: {{CMD[id="filter_op_pagefile"]pagefile}}

Strips leading slashes and dots.

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

H4: {{CMD[id="filter_op_sql"]sql}}

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

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

H4: {{CMD[id="filter_op_strip"]strip}}

Strips leading and trailing whitespace.

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

H4: {{CMD[id="filter_op_text2html"]text2html}}

Rudimentary HTMLizing of text.

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


H4: {{CMD[id="filter_op_uc"]uc}}

Uppercases the text.

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

H4: {{CMD[id="filter_op_unix"]unix}}

Removes those crufty carriage returns.

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

H4: {{CMD[id="filter_op_urlencode"]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;
>                },

H4: {{CMD[id="filter_op_value"]value}}

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

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

H4: {{CMD[id="filter_op_word"]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 {{CMD[jump="icconfig.html#GlobalSub *global*"]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 C<[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 C<foo> is C<bar>, the call
C<[value name=foo filter="lookup.products.price.extra"]> will send
('bar', 'foo', 'products', 'price', 'extra').







# BEGIN ########### filter Subsections ##############
H4: {{CMD[id="filter_op"]op}}



# END ++++++++++++ filter Subsections +++++++++++++

H2: flag

Controls Interchange flags. For example, flags affect database access
and transactions for those databases able to support these
features. See also the E<lbracket>{{C[jump="#tag"]tag}}] tag.

H3: Summary

!block example;
    [B<flag> type]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#flag_build"]build}}|<<
Forces build of static Interchange page specified by the C<name> attribute
>>|DEFAULT_VALUE
{{CMD[jump="#flag_checkhtml"]checkhtml}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#flag_commit"]commit}}|<<
Attempts to commit transactions
>>|DEFAULT_VALUE
{{CMD[jump="#flag_type"]flag}}|<<
Alias for type
>>|DEFAULT_VALUE
{{CMD[jump="#flag_type"]name}}|<<
Alias for type
>>|DEFAULT_VALUE
{{CMD[jump="#flag_read"]read}}|<<
Flags the table read-only
>>|DEFAULT_VALUE
{{CMD[jump="#flag_rollback"]rollback}}|<<
Attempts to rollback transactions
>>|DEFAULT_VALUE
{{CMD[jump="#flag_show"]show}}|<<
Normally, the E<lbracket>C<flag>] tag returns nothing to the
page. Setting 'C<show>=1' causes the tag to return status, if any.
>>|DEFAULT_VALUE
{{CMD[jump="#flag_tables"]table}}|<<
Alias for tables
>>|DEFAULT_VALUE
{{CMD[jump="#flag_tables"]tables}}|<<
The name of the table to flag
* 'C<table>' is an alias
>>|DEFAULT_VALUE
{{CMD[jump="#flag_transactions"]transactions}}|<<
Reopens the database in transactions mode if {{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe.pm}} is not active
(e.g., in a global subroutine, usertag or
E<lbracket>{{C[jump="#perl_global"]perl}}E<nbspace>global=1]
tag). The limitation exists because it is not possible to reopen a
database within {{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe.pm}}.
>>|DEFAULT_VALUE
{{CMD[jump="#flag_type"]type}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#flag_value"]value}}|<<
The boolean value of the flag
>>|DEFAULT_VALUE
{{CMD[jump="#flag_write"]write}}|<<
Flags the table writable by default (or read-only if you also set
the C<value>=0 attribute)
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [flag type]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->flag(  { type => VALUE_type
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->flag(type, $attribute_hash_reference, $body);
!endblock

H3: Description

The C<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

!block example
    [flag type=write value=1 table=products]
!endblock

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

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

Using E<lbracket>C<flag> build] forces static build of a page, even if
it contains dynamic elements.



# BEGIN ############ flag Subsections ##############
H4: {{CMD[id="flag_build"]build}}

Forces build of static Interchange page specified by the C<name> attribute


H4: {{CMD[id="flag_checkhtml"]checkhtml}}



H4: {{CMD[id="flag_commit"]commit}}

Attempts to commit transactions


H4: {{CMD[id="flag_read"]read}}

Flags the table read-only


H4: {{CMD[id="flag_rollback"]rollback}}

Attempts to rollback transactions


H4: {{CMD[id="flag_show"]show}}

Normally, the E<lbracket>C<flag>] tag returns nothing to the
page. Setting 'C<show>=1' causes the tag to return status, if any.


H4: {{CMD[id="flag_tables"]tables}}

The name of the table to flag
* 'C<table>' is an alias


H4: {{CMD[id="flag_transactions"]transactions}}

Reopens the database in transactions mode if {{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe.pm}} is not active
(e.g., in a global subroutine, usertag or
E<lbracket>{{C[jump="#perl_global"]perl}}E<nbspace>global=1]
tag). The limitation exists because it is not possible to reopen a
database within {{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe.pm}}.


H4: {{CMD[id="flag_type"]type}}



H4: {{CMD[id="flag_value"]value}}

The boolean value of the flag


H4: {{CMD[id="flag_write"]write}}

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


# END +++++++++++++ flag Subsections ++++++++++++

H2: fly-list


H3: Summary

\Parameters: B<code base>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

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

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

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

 

# BEGIN ############### fly-list Summary Tables ####################
!block example;
    [B<fly-list> code base]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#fly_list_base"]base}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#fly_list_code"]code}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [fly-list code base]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->fly_list(  { base => VALUE_base
                       code => VALUE_code
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->fly_list(code,base, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ fly-list End Summary Tables ++++++++++++++++++++


H3: 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 C<flypage2.html>, it will make these two calls
display identical pages:

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

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

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






# BEGIN ########### fly-list Subsections ##############
H4: {{CMD[id="fly_list_base"]base}}



H4: {{CMD[id="fly_list_code"]code}}



# END ++++++++++++ fly-list Subsections +++++++++++++

H2: fly-tax


H3: Summary

\Parameters: B<area>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

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

 

# BEGIN ############### fly-tax Summary Tables ####################
!block example;
    [fly-tax area]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#fly_tax_area"]area}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [fly-tax area]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->fly_tax(  { area => VALUE_area
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->fly_tax(area, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ fly-tax End Summary Tables ++++++++++++++++++++


H3: Description

Builds a tax rate from C<TAXAREA>, C<TAXRATE>, and C<TAXSHIPPING> {{CMD[jump="icconfig.html#Variable"]Variable}} values, and the {{CMD[jump="icconfig.html#SalesTax"]SalesTax}} directive value.




# BEGIN ########### fly-tax Subsections ##############
H4: {{CMD[id="fly_tax_area"]area}}



# END ++++++++++++ fly-tax Subsections +++++++++++++

H2: goto

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

H3: Summary

!block example
    [goto name=I<label_name> if=I<condition>]
        I<content to skip>
    [label name=I<label_name>]
!endblock

or positionally,

!block example
    [goto name if]
        I<content to skip>
    [label name]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#goto_name"]name}}|<<
The name set in the corresponding E<lbracket>label] tag
>>|I<none>
{{CMD[jump="#goto_if"]if}}|<<
Condition for C<goto>. Should evaluate to truth value before tag is parsed.
>>|I<true>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Container tag|<<
I<No>, but you use it like N<this:>
. E<lbracket>goto name=I<label_name> if=I<condition>]
..I<body text>
.E<lbracket>label I<label_name>]
>>
Has Subtags|E<lbracket>label] interpreted by C<goto>
!endblock


B<ASP-like Perl call:>

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


H3: Description

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

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

!block note; label="Technical note (Interchange 4.8): "
This tag may not work properly if you have more than one goto/label pair on a page.
!endblock


H4: {{CMD[id="goto_name"]name}}

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


H4:  {{CMD[id="goto_if"]if}}

Condition for goto. If the argument to 'C<if>' is true, the tag will skip the text between the C<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 C<goto> tag processes it.

For example, this will not execute the goto:

!block example
    [set go]0[/set]
    [goto name="there" if="[scratch go]"]
!endblock



H2: handling


H3: Summary

\Parameters: B<mode>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

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

Attribute aliases

>            carts ==> cart
>            modes ==> mode
>            name ==> mode
>            tables ==> table


 

# BEGIN ############### handling Summary Tables ####################
!block example;
    [B<handling> mode I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#handling_cart"]carts}}|<<
Alias for cart
>>|DEFAULT_VALUE
{{CMD[jump="#handling_mode"]mode}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#handling_mode"]modes}}|<<
Alias for mode
>>|DEFAULT_VALUE
{{CMD[jump="#handling_mode"]name}}|<<
Alias for mode
>>|DEFAULT_VALUE
{{CMD[jump="#handling_table"]tables}}|<<
Alias for table
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [handling mode]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->handling(  { mode => VALUE_mode
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->handling(mode, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ handling End Summary Tables ++++++++++++++++++++


H3: Description

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





# BEGIN ########### handling Subsections ##############
H4: {{CMD[id="handling_cart"]cart}}

H4: {{CMD[id="handling_mode"]mode}}

H4: {{CMD[id="handling_table"]table}}



# END ++++++++++++ handling Subsections +++++++++++++

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

H3: Summary

!block example;
    [B<harness> I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#harness_expected"]expected}}|<<
Tagname for delimiting your expected return value (default "OK")
>>|DEFAULT_VALUE
{{CMD[jump="#harness_name"]name}}|<<
This will appear in your output message (useful for distinguishing harness tags from one another) (default "testI<nnn>")
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [harness]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->harness(  { 
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->harness(, $attribute_hash_reference, $body);
!endblock

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



# BEGIN ############ harness Subsections ##############
H4: {{CMD[id="harness_expected"]expected}}

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


H4: {{CMD[id="harness_name"]name}}

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


# END +++++++++++++ harness Subsections ++++++++++++

H2: href

Alias for [{{CMD[jump="#area"]area}}] tag.


H2: html-table

Builds an HTML table

H3: Summary

!block example;
    [html-table I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#html_table_columns"]columns}}|<<
Whitespace-delimited list of columns
>>|DEFAULT_VALUE
{{CMD[jump="#html_table_delimiter"]delimiter}}|<<
Line delimiter to use if tag body is delimited text rather than an array reference (default "\t")
>>|DEFAULT_VALUE
{{CMD[jump="#html_table_fc"]fc}}|<<
HTML attributes for <TD> in the first cell
>>|DEFAULT_VALUE
{{CMD[jump="#html_table_fr"]fr}}|<<
HTML attributes for <TR> in the first row
>>|DEFAULT_VALUE
{{CMD[jump="#html_table_record_delim"]record_delim}}|<<
Record delimiter to use if tag body is delimited text rather than an array reference (default "\n")
>>|DEFAULT_VALUE
{{CMD[jump="#html_table_td"]td}}|<<
HTML attributes for <TD>
>>|DEFAULT_VALUE
{{CMD[jump="#html_table_th"]th}}|<<
HTML attributes for <TH>
>>|DEFAULT_VALUE
{{CMD[jump="#html_table_tr"]tr}}|<<
HTML attributes for <TR>
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [html-table]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->html_table(  { 
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->html_table(, $attribute_hash_reference, $body);
!endblock

H3: Description


Builds an HTML table




# BEGIN ############ html-table Subsections ##############
H4: {{CMD[id="html_table_columns"]columns}}

Whitespace-delimited list of columns


H4: {{CMD[id="html_table_delimiter"]delimiter}}

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


H4: {{CMD[id="html_table_fc"]fc}}

HTML attributes for <TD> in the first cell


H4: {{CMD[id="html_table_fr"]fr}}

HTML attributes for <TR> in the first row


H4: {{CMD[id="html_table_record_delim"]record_delim}}

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


H4: {{CMD[id="html_table_td"]td}}

HTML attributes for <TD>


H4: {{CMD[id="html_table_th"]th}}

HTML attributes for <TH>


H4: {{CMD[id="html_table_tr"]tr}}

HTML attributes for <TR>


# END +++++++++++++ html-table Subsections ++++++++++++

H2: if


H3: Summary

\Parameters: B<type term op compare>

THIS TAG HAS SPECIAL POSITIONAL PARAMETER HANDLING.



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

Must pass named parameter interpolate=1 to cause interpolation.

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

Invalidates cache: B<YES>

Called Routine: 

Called Routine for positional: 

B<ASP-like Perl call:>

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

Attribute aliases

>            base ==> type
>            comp ==> compare
>            condition ==> compare
>            operator ==> op
 

# BEGIN ############### if Summary Tables ####################

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#if_type"]base}}|<<
Alias for type
>>|DEFAULT_VALUE
{{CMD[jump="#if_compare"]comp}}|<<
Alias for compare
>>|DEFAULT_VALUE
{{CMD[jump="#if_compare"]compare}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#if_compare"]condition}}|<<
Alias for compare
>>|DEFAULT_VALUE
{{CMD[jump="#if_op"]op}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#if_op"]operator}}|<<
Alias for op
>>|DEFAULT_VALUE
{{CMD[jump="#if_term"]term}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#if_type"]type}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [if type term op compare]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->if(  { compare => VALUE_compare
                 op => VALUE_op
                 term => VALUE_term
                 type => VALUE_type
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->if(type,term,op,compare, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ if End Summary Tables ++++++++++++++++++++


H3: 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 E<lbracket>{{C[jump="#if"]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 E<lbracket>{{C[jump="#if"]if}} ...], it is more convenient
to use positional calls in most cases.
The only exception is if you are planning on doing a test on the 
results of another tag sequence:
    
>    [if value name =~ /[value b_name]/]
>        Shipping name matches billing name.
>    [/if]

Oops!  This will not work. You must do instead

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

or better yet

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

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

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

If you wish to do very complex AND and OR operations, you will have to use 
E<lbracket>{{C[jump="#if"]if}} explicit] or better yet embedded Perl/ASP. This allows complex
testing and parsing of values.

There are many test targets available:


H4: {{CMD[id="if_config"]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]

H4: {{CMD[id="if_data"]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]

H4: {{CMD[id="if_discount"]discount}}

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

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

H4: {{CMD[id="if_explicit"]explicit}}

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

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

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

This will work for I<Variable> values:

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

However, note that the 'compare' option is equivalent to the
\[condition] block in that both evaluate as Perl code. That means
you need to watch out when you put in user-supplied values (so that
users can't inject Perl code on your server) and data from your own
variables or tables which may look different than you expected.

For example, say you're in a loop checking whether at least one of the
fields 'foo' and 'bar' has a value ("true" according to Perl):

>    [if type=explicit compare="[loop-param foo][loop-param bar]"]

Most of the time this works fine. But if 'foo' contains a string
beginning with '0', such as '0009', Perl will try to interpret it as
an octal number, where the digit '9' is invalid, resulting in this
unexpected error in the catalog error log:

>    Bad if 'explicit   0009': Illegal octal digit '9' at (eval 155) line 1, at end of line

A safer way to check is:

>    [if type=explicit compare="q{[loop-param foo][loop-param bar]}"]

Although then your data should not contain a '}'. To be extra safe you
can surround your interpolated data with a [filter X] ... [/filter] tag
pair appropriate for the quoting method you've used.

H4: {{CMD[id="if_file"]file}}

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

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

H4: {{CMD[id="if_file_A"]file-A}}

Compares against a file's access time (in days).

> [if file-A foofile.ext > 1]
> foofile.ext has not been accessed in over a day.
> [/if]

Same as Perl's -A test.


H4: {{CMD[id="if_file_B"]file-B}}

Compares against a file's binary status.

> [if file-B foofile.ext]
> foofile.ext is a binary file.
> [/if]

Same as Perl's -B test. Note that the test only examines the first 1000
bytes or so, and it can be fooled.

H4: {{CMD[id="if_file_d"]file-d}}

Tests whether a file is a directory.

> [if file-d foodir/bardir]
> foodir/bardir is a directory.
> [/if]

Same as Perl's -d test.

H4: {{CMD[id="if_file_e"]file-e}}

Tests whether a file exists at all, whether file or directory.

> [if file-e foodir/bardir]
> foodir/bardir is some type of file.
> [/if]

Same as Perl's -e test.

H4: {{CMD[id="if_file_f"]file-f}}

Tests whether a file is a plain file (even following a symbolic link).

> [if file-f foodir/bardir]
> foodir/bardir is a file.
> [/if]

Same as Perl's -f test, and the default for C<[if file ...]>. The
following are the same:

> [if file-f error.log]
> error.log is a file.
> [/if]
>
> [if file error.log]
> error.log is a file.
> [/if]

H4: {{CMD[id="if_file_l"]file-l}}

Tests whether a file is a symbolic link.

> [if file-l foodir/bardir]
> foodir/bardir is a symbolic link.
> [/if]

Same as Perl's -l test.

H4: {{CMD[id="if_file_M"]file-M}}

Allows tests against the number of days since the file has been modified.

> [if file-M error.log > 0.5]
> There have been no errors in 12 hours.
> [/if]
> 
> [if file-M error.log < 1]
> There have been errors in the last day.
> [/if]

Same as Perl's -M test.

H4: {{CMD[id="if_file_r"]file-r}}

Tests whether file is readable by the Interchange user.

> [if file-r error.log]
> We can read error.log.
> [/if]

Same as Perl's -r test.

H4: {{CMD[id="if_file_s"]file-s}}

Allows tests against the size of a file.

> [if file-s error.log > 1024]
> There have been more than a kilobyte of errors.
> [/if]
>
> [if file-s error.log < 100000]
> There have been than less than 100,000 bytes of errors.
> [/if]

Same as Perl's -s test.

H4: {{CMD[id="if_file_T"]file-T}}

Tests whether a file is a text file.

> [if file-T error.log]
> error.log is a text file.
> [/if]

Same as Perl's -T test. Note that the test only examines the first 1000
bytes or so, and it can be fooled.

H4: {{CMD[id="if_file_w"]file-w}}

Tests whether file is writeable by the Interchange user.

> [if file-w error.log]
> We can log errors.
> [else]
> Danger, Will Robinson! We can't log errors.
> [/else]
> [/if]

Same as Perl's -w test.

H4: {{CMD[id="if_file_x"]file-x}}

Tests whether file is executable by the Interchange user.

> [if file-x error.log]
> error.log is not executable (not that it needs to be.
> [/if]
>
> [if !file-x pages]
> There is no way to use a page in the pages directory, as it is
> not searchable.
> [/if]

Same as Perl's -x test.

H4: {{CMD[id="if_items"]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]

H4: {{CMD[id="if_ordered"]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]

H4: {{CMD[id="if_pragma"]pragma}}

The Interchange Pragma settings, set with the L<catalog.cfg> directive
C<Pragma> or with C<[pragma name]>. 

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

H4: {{CMD[id="if_scratch"]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]

H4: {{CMD[id="if_session"]session}}

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

H4: {{CMD[id="if_validcc"]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 C<CreditCardAuto> variables
for targets if nothing else is passed.

H4: {{CMD[id="if_value"]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 I<field> term is the specifier for that area. For example, [if session
logged_in] would return true if the C<logged_in> session parameter was set.

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

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

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

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

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

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

Any simple perl test can be used, including some limited regex matching.
More complex tests are best done with E<lbracket>{{C[jump="#if"]if}} explicit].


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

H4: [elsif type field op* compare*]

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

Additional conditions for test, applied if the initial E<lbracket>{{C[jump="#if"]if}} ..] test
fails.

H4: [else] text [/else]

The optional else-text for an if or C<[if-field]> conditional.

H4: [condition] text [/condition]

Only used with the [if explicit] tag. Allows an arbitrary expression
B<in Perl> to be placed inside, with its return value interpreted as
the result of the test. If arguments are added to [if explicit args],
those will be passed as arguments are in the E<lbracket>{{I[jump="#perl"]perl}}] construct.







# BEGIN ########### if Subsections ##############
H4: {{CMD[id="if_compare"]compare}}



H4: {{CMD[id="if_op"]op}}



H4: {{CMD[id="if_term"]term}}



H4: {{CMD[id="if_type"]type}}



# END ++++++++++++ if Subsections +++++++++++++

H2: import


H3: Summary

\Parameters: B<table type>

Positional parameters in same order.


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

Interpolates B<container text> by default.

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

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

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

Attribute aliases

>            base ==> table
>            database ==> table


 

# BEGIN ############### import Summary Tables ####################
!block example;
    [B<import> table type I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#import_table"]base}}|<<
Alias for table
>>|DEFAULT_VALUE
{{CMD[jump="#import_table"]database}}|<<
Alias for table
>>|DEFAULT_VALUE
{{CMD[jump="#import_table"]table}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#import_type"]type}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [import table type]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->import(  { table => VALUE_table
                     type => VALUE_type
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->import(table,type, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ import End Summary Tables ++++++++++++++++++++


H3: 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 C<type> is any
of the valid Interchange delimiter types, with the default being defined
by the setting of the database I<DELIMITER>. The table must already be a defined
Interchange database table; it cannot be created on the fly. (If you need
that, it is time to use SQL.)

The C<type> of C<LINE> and C<continue> setting of C<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 C<code> or key must always be present, and is always named C<code>.

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

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






# BEGIN ########### import Subsections ##############
H4: {{CMD[id="import_table"]table}}



H4: {{CMD[id="import_type"]type}}



# END ++++++++++++ import Subsections +++++++++++++

H2: include


H3: Summary

\Parameters: B<file locale>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

Not applicable.
 

# BEGIN ############### include Summary Tables ####################
!block example;
    [B<include> file locale]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#include_file"]file}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#include_locale"]locale}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [include file locale]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->include(  { file => VALUE_file
                      locale => VALUE_locale
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->include(file,locale, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ include End Summary Tables ++++++++++++++++++++


H3: Description


Same as E<lbracket>{{C[jump="#file"]file}} name] except interpolates for all Interchange tags
and variables. Does NOT do locale translations.






# BEGIN ########### include Subsections ##############
H4: {{CMD[id="include_file"]file}}



H4: {{CMD[id="include_locale"]locale}}



# END ++++++++++++ include Subsections +++++++++++++

H2: index

Creates an index for the specified table.

H3: Summary

!block example;
    [B<index> table I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#index_table"]base}}|<<
Alias for table
>>|DEFAULT_VALUE
{{CMD[jump="#index_basefile"]basefile}}|<<
Database filename. Exports the table to this filename if old or missing before indexing. See also the {{C[jump="#export"]export}} tag for additional relevant attributes such as delimiter type, etc.
>>|DEFAULT_VALUE
{{CMD[jump="#index_col"]col}}|<<
alias for fields
>>|DEFAULT_VALUE
{{CMD[jump="#index_columns"]columns}}|<<
alias for fields
>>|DEFAULT_VALUE
{{CMD[jump="#index_table"]database}}|<<
Alias for table
>>|DEFAULT_VALUE
{{CMD[jump="#index_export_only"]export_only}}|<<
Just do the export if necessary (not the index).
>>|DEFAULT_VALUE
{{CMD[jump="#index_extension"]extension}}|<<
Index file extension (default "idx")
>>|DEFAULT_VALUE
{{CMD[jump="#index_fields"]fields}}|<<
field(s) to index
>>|DEFAULT_VALUE
{{CMD[jump="#index_fn"]fn}}|<<
alias for fields
>>|DEFAULT_VALUE
{{CMD[jump="#index_show_status"]show_status}}|<<
Return '1' to the page if successful
>>|DEFAULT_VALUE
{{CMD[jump="#index_spec"]spec}}|<<
The index specification
>>|DEFAULT_VALUE
{{CMD[jump="#index_table"]table}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [index table]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->index(  { table => VALUE_table
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->index(table, $attribute_hash_reference, $body);
!endblock

H3: Description

Creates an index for the specified table.




# BEGIN ############ index Subsections ##############
H4: {{CMD[id="index_basefile"]basefile}}

Database filename. Exports the table to this filename if old or missing before indexing. See also the {{C[jump="#export"]export}} tag for additional relevant attributes such as delimiter type, etc.


H4: {{CMD[id="index_col"]col}}

alias for fields


H4: {{CMD[id="index_columns"]columns}}

alias for fields


H4: {{CMD[id="index_export_only"]export_only}}

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


H4: {{CMD[id="index_extension"]extension}}

Index file extension (default "idx")


H4: {{CMD[id="index_fields"]fields}}

field(s) to index


H4: {{CMD[id="index_fn"]fn}}

alias for fields


H4: {{CMD[id="index_show_status"]show_status}}

Return '1' to the page if successful


H4: {{CMD[id="index_spec"]spec}}

The index specification


H4: {{CMD[id="index_table"]table}}



# END +++++++++++++ index Subsections ++++++++++++

H2: item-list


H3: Summary

\Parameters: B<name>

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

Must pass named parameter interpolate=1 to cause interpolation.

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

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

>    NOTE: This would not usually be used with embedded Perl -- a better
>    choice would normally be:
>
>		 for(@$Items) { CODE }
>
>    $Tag->item_list(
>        {
>         name => VALUE,
>        },
>        BODY
>    )
>
> OR
>
>    $Tag->item_list($name, $ATTRHASH, $BODY);

Attribute aliases

>            cart ==> name


 

# BEGIN ############### item-list Summary Tables ####################
!block example;
    [B<item-list> name I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#item_list_name"]cart}}|<<
Alias for name
>>|DEFAULT_VALUE
{{CMD[jump="#item_list_name"]name}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [item-list name]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->item_list(  { name => VALUE_name
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->item_list(name, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ item-list End Summary Tables ++++++++++++++++++++


H3: Description


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

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

Between the [C<item-list>] markers the following elements will return
information for the current item:


H4: E<lbracket>if-data table column]

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

H4: E<lbracket>if-data ! table column]

Reverses sense for C<[if-data]>.

H4: E<lbracket>/if-data]

Terminates an C<[if-data table column]> element.

H4: E<lbracket>if-field fieldname]

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

H4: E<lbracket>if-field ! fieldname]

Reverses sense for C<[if-field]>.

H4: E<lbracket>/if-field]

Terminates an C<[if-field fieldname]> element.

H4: E<lbracket>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.

H4: E<lbracket>item-code]

Evaluates to the product code for the current item.

H4: E<lbracket>item-data database fieldname]

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

H4: E<lbracket>item-description]

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

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

H4: E<lbracket>item-field fieldname]

Evaluates to the field name I<fieldname> in the products database,
for the current item. If the item is not found in the first of the
{{C[jump="icconfig.html#ProductFiles"]ProductFiles}},
all will be searched in sequence.

H4: E<lbracket>item-increment]

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

H4: E<lbracket>item-last]tags[/item-last]

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

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

If this is contained in your
E<lbracket>{{C[jump="#item-list"]item-list}}] (or
E<lbracket>{{C[jump="#search-list"]search-list}}] or
flypage) and the weight field is empty, then a numerical C<-1> will be
output from the [calc][/calc] tags; the list will end and the item
will B<not> be shown. If the product's weight field is less than 1, a
numerical 1 is output. The item will be shown, but will be the last
item shown. (If it is an
E<lbracket>{{C[jump="#item-list"]item-list}}], any price for
the item will still be added to the subtotal.)

H4: E<lbracket>item-modifier attribute]

Evaluates to the modifier value of C<attribute> for the current item.

H4: E<lbracket>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 E<lbracket>{{C[jump="#item-list"]item-list}}] (or E<lbracket>{{C[jump="#search-list"]search-list}}] or flypage)
and the product's weight field is less than 1, then a numerical C<1> will
be output from the [calc][/calc] operation. The item will not be shown. (If
it is an E<lbracket>{{C[jump="#item-list"]item-list}}], any price for the item will still be added to the
subtotal.)

H4: E<lbracket>item-price n* noformat*]

Evaluates to the price for quantity C<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.

H4: E<lbracket>item-discount-price n* noformat*]

Evaluates to the discount price for quantity C<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.

H4: E<lbracket>item-discount]

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

H4: E<lbracket>item-discount_subtotal]

Inserts the discounted subtotal of the ordered items.

H4: E<lbracket>item-quantity]

Evaluates to the quantity ordered for the current item.

H4: E<lbracket>item-subtotal]

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

H4: E<lbracket>item-modifier-name attribute]

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

H4: E<lbracket>quantity-name]

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




# BEGIN ########### item-list Subsections ##############
H4: {{CMD[id="item_list_name"]name}}



# END ++++++++++++ item-list Subsections +++++++++++++

H2: label

The page label for goto. See E<lbracket>{{C[jump="#goto"]goto}}] tag for description.  Note that this is not a standard tag, but is simply a marker used by {{C[jump="#goto"]goto}}.

\Parameter: B<name>

!block example
    [goto name=I<label_name> if=I<condition>]
        I<content to skip>
    [label name=I<label_name>]
!endblock


H3: Summary

NO SUMMARY SECTION


# BEGIN ############### label Summary Tables ####################
!block example;
    [B<label>]
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<No>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [label]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->label(  { 
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->label(, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ label End Summary Tables ++++++++++++++++++++


H3: Description

NO DESCRIPTION SECTION

H2: log

Log contained text to specified file.

H3: Summary

!block example;
    [B<log> file I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#log_file"]arg}}|<<
Alias for file
>>|DEFAULT_VALUE
{{CMD[jump="#log_create"]create}}|<<
Set create=1 to create the file if not present
>>|DEFAULT_VALUE
{{CMD[jump="#log_delim"]delim}}|<<
Line delimiter
>>|DEFAULT_VALUE
{{CMD[jump="#log_file"]file}}|<<
name of file to log to. 'file="E<gt>I<filename>"' also sets 'create' attribute.
>>|DEFAULT_VALUE
{{CMD[jump="#log_hide"]hide}}|<<
Suppress status otherwise returned by tag to the page.
>>|DEFAULT_VALUE
{{CMD[jump="#log_process"]process}}|<<
Processing (if any) to apply to the content while logging
* nostrip (don't strip leading/trailing whitespace and convert "\r\n" to "\n"
>>|DEFAULT_VALUE
{{CMD[jump="#log_record_delim"]record_delim}}|<<
Record delimiter
>>|DEFAULT_VALUE
{{CMD[jump="#log_type"]type}}|<<
Log type
* text (ordinary text file)
* quot (delimited entries)
* error (add Interchange error formatting and time/location stamps)
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [log file]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->log(  { file => VALUE_file
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->log(file, $attribute_hash_reference, $body);
!endblock

H3: Description

Log contained text to specified file.



# BEGIN ############ log Subsections ##############
H4: {{CMD[id="log_create"]create}}

Set create=1 to create the file if not present


H4: {{CMD[id="log_delim"]delim}}

Line delimiter


H4: {{CMD[id="log_file"]file}}

name of file to log to. 'file="E<gt>I<filename>"' also sets 'create' attribute.


H4: {{CMD[id="log_hide"]hide}}

Suppress status otherwise returned by tag to the page.


H4: {{CMD[id="log_process"]process}}

Processing (if any) to apply to the content while logging
* nostrip (don't strip leading/trailing whitespace and convert "\r\n" to "\n"


H4: {{CMD[id="log_record_delim"]record_delim}}

Record delimiter


H4: {{CMD[id="log_type"]type}}

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


# END +++++++++++++ log Subsections ++++++++++++

H2: loop


H3: Summary

\Parameters: B<list>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

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

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

>    NOTE: This would not usually be used with embedded Perl -- a better
>    choice would normally be:
>
>		 for(@list) { CODE }
>
>    $Tag->loop(
>        {
>         list => VALUE,
>        },
>        BODY
>    )
>
> OR
>
>    $Tag->loop($list, $ATTRHASH, $BODY);

Attribute aliases

>            arg ==> list
>            args ==> list


 

# BEGIN ############### loop Summary Tables ####################
!block example;
    [B<loop> list I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#loop_list"]arg}}|<<
Alias for list
>>|DEFAULT_VALUE
{{CMD[jump="#loop_list"]args}}|<<
Alias for list
>>|DEFAULT_VALUE
{{CMD[jump="#loop_list"]list}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [loop list]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->loop(  { list => VALUE_list
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->loop(list, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ loop End Summary Tables ++++++++++++++++++++


H3: Description


Returns a string consisting of the LIST, repeated for every item in a
comma-separated or space-separated list. Operates in the same fashion
as the [item-list] tag, except for order-item-specific values. Intended
to pull multiple attributes from an item modifierE<nbspace>E<emdash> 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 C<list> if you set the C<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 C<1..100>. You can mix regular sets -- C<1..5 10 20> would produce
the list C<1 2 3 4 5 10 20>.

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

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

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

A nice shortcut is available when using [loop] to generate <OPTION>
lists inside HTML <SELECT>...</SELECT> blocks, when you want the user's
last selection to be chosen by default on subsequent page views. Interchange
simplifies this with functions that output "SELECTED" (surrounded by
appropriate whitespace) for an <OPTION> if a certain value is set to
the <OPTION VALUE="...">. (It sounds more complicated than it really is.)

For example, consider:

!block example
<select name=search_cat>
[loop
	search="
		fi=cat
		st=db
		ra=yes
		rf=name
		tf=name
		un=1
	"
]
<option[selected search_cat [loop-code]>[loop-code]
[/loop]
</select>
!endblock

When the user returns to the page, their last selection will be chosen
as the default. (Assuming the value search_cat was set after the search,
which is normally is with standard searches.)

\[loop] offers the C<option> attribute, which can give loops that parse
faster and are easier to write. The following example is equivalent to
the one above:

!block example
<select name=search_cat>
[loop
	option=search_cat
	search="
		fi=cat
		st=db
		ra=yes
		rf=name
		tf=name
		un=1
	"
]
<option>[loop-code]
[/loop]
</select>
!endblock

It works equally well when option values are explicitly specified:

><option value="[loop-code]">So-called "[loop-code]"

See also the C<ictemplates> documentation in the section "Checks and Selections."


H4: E<lbracket>if-loop-data table column] IF [else] ELSE [/else][/if-loop-field]

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

See E<lbracket>{{CMD[jump="#if-PREFIX-data"]if-PREFIX-data}}E<rbracket>.

H4: E<lbracket>if-loop-field column] IF [else] ELSE [/else][/if-loop-field]

Outputs the B<IF> if the C<column> in the C<products> table is non-empty,
and the B<ELSE> (if any) otherwise. Will fall through to the first
non-empty field if there are multiple
{{C[jump="icconfig.html#ProductFiles"]ProductFiles}}.

See E<lbracket>{{CMD[jump="#if-PREFIX-field"]if-PREFIX-field}}E<rbracket>.

H4: E<lbracket>if-loop-param param] IF [else] ELSE [/else][/if-loop-param]

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

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

See C<[if-PREFIX-param]>.

H4: E<lbracket>if-loop-pos N] IF [else] ELSE [/else][/if-loop-pos]

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

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

Outputs the B<IF> if the returned positional parameter C<N> is
non-empty, and the B<ELSE> (if any) otherwise.

See C<[if-PREFIX-pos]>.

H4: E<lbracket>loop-accessories]

Outputs an [accessories ...] item.

See E<lbracket>{{CMD[jump="#PREFIX-accessories"]PREFIX-accessories}}E<rbracket>.

H4: E<lbracket>loop-change marker]

See E<lbracket>{{CMD[jump="#PREFIX-change"]PREFIX-change}}E<rbracket>.

H4: E<lbracket>loop-code]

Evaluates to the code for the current item.

See E<lbracket>{{CMD[jump="#PREFIX-code"]PREFIX-code}}E<rbracket>.

H4: E<lbracket>loop-data database fieldname]

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

See E<lbracket>{{CMD[jump="#PREFIX-data"]PREFIX-data}}E<rbracket>.

H4: E<lbracket>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 E<lbracket>{{CMD[jump="#PREFIX-description"]PREFIX-description}}E<rbracket>.

H4: E<lbracket>loop-field fieldname]

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

See E<lbracket>{{CMD[jump="#PREFIX-field"]PREFIX-field}}E<rbracket>.

H4: E<lbracket>loop-increment]

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

Starts from integer 1.

See E<lbracket>{{CMD[jump="#PREFIX-increment"]PREFIX-increment}}E<rbracket>.

H4: E<lbracket>loop-last]tags[/loop-last]

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

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

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

H4: E<lbracket>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 C<[loop list]> and the product's weight
field is less than 1, then a numerical C<1> will be output from the
\[calc][/calc] operation. The item will not be shown.

H4: E<lbracket>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.




# BEGIN ########### loop Subsections ##############
H4: {{CMD[id="loop_list"]list}}



# END ++++++++++++ loop Subsections +++++++++++++

H2: mail

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

H3: Summary

!block example;
    [B<mail> to I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#mail_extra"]extra}}|<<
Additional headers (these will also be added to 'raw' messages)
>>|DEFAULT_VALUE
{{CMD[jump="#mail_hide"]hide}}|<<
Suppress tag return value. This would otherwise be the 'success'
attribute setting.
>>|DEFAULT_VALUE
{{CMD[jump="#mail_raw"]raw}}|<<
Send it raw without creating headers and checking content, recipient,
subject, etc.
>>|DEFAULT_VALUE
{{CMD[jump="#mail_show"]show}}|<<
The tag will return the final message with headers in the page
>>|DEFAULT_VALUE
{{CMD[jump="#mail_success"]success}}|<<
Tag return value if successful (default is 1).
>>|DEFAULT_VALUE
{{CMD[jump="#mail_to"]to}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->mail(  { to => VALUE_to
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->mail(to, $attribute_hash_reference, $body);
!endblock

H3: Description


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



# BEGIN ############ mail Subsections ##############
H4: {{CMD[id="mail_extra"]extra}}

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


H4: {{CMD[id="mail_hide"]hide}}

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


H4: {{CMD[id="mail_raw"]raw}}

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


H4: {{CMD[id="mail_show"]show}}

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


H4: {{CMD[id="mail_success"]success}}

Tag return value if successful (default is 1).


H4: {{CMD[id="mail_to"]to}}



# END +++++++++++++ mail Subsections ++++++++++++

H2: mvasp

Executes the ASP-style perl code contained by the tag. The code will run under
the restrictions of the 
{{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe}}
module. This is very similar to the
E<lbracket>{{C[jump="#perl"]perl}}] tag, except that the standard '<%'
and '%>' ASP delimiters allow you to mix HTML and perl code.


H3: Summary

!block example;
    [B<mvasp> tables] I<ASP here> [/mvasp]
    [B<mvasp> tables="db1 db2 ..." I<other_named_attributes>] I<ASP here> [/mvasp]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
tables|<<
Database tables to be made available to ASP Perl code
>>|I<none>
table|Alias for C<tables>|I<none>
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#mvasp_failure"]failure}}|I<none>
{{CMD[jump="#mvasp_no_return"]no_return}}|I<Always true>
{{CMD[jump="#mvasp_subs"]subs}}|I<No>
{{CMD[jump="#mvasp_subs"]arg}}="subs"|I<Same as> C<subs>
{{CMD[jump="#mvasp_global"]global}}|I<No>
{{CMD[jump="#mvasp_file"]file}}|I<none>
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<Yes>
Has Subtags|E<lt>% I<and> %>
Container tag|I<Yes>
Nests|I<No>
!endblock

B<Tag expansion example:>

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

    <P>More HTMLE<lt>/p>
    Looked up SKU [[EXAMPLE_SKU]]. It is a [[EXAMPLE_DESCRIPTION]] <br>

    <P>Still more HTMLE<lt>/p>
!endblock


H4: See Also

{{CMD[jump="#perl"]perl}}, {{CMD[jump="ictemplates.html#Programming"]Interchange Programming}}


H3: Description

Executes the ASP-style perl code contained by the tag. The code will run under
the restrictions of the 
{{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe}}
module. This is very similar to the
E<lbracket>{{C[jump="#perl"]perl}} no_return=1] tag, except that the standard '<%'
and '%>' ASP delimiters allow you to mix HTML and perl code.

See the {{C[jump="#perl"]perl}} tag and
{{CMD[jump="ictemplates.html#ASP-Like Perl"]ASP-Like Perl}}
sections for more detail.

H4: {{CMD[id="mvasp_tables"]tables}}

Whitespace-separated list of database tables to make available within
the ASP-Perl code. See {{C[jump="#perl_tables"]perl}} tag.

H4: {{CMD[id="mvasp_failure"]failure}}

The value the tag should return in case the perl code fails the
eval. See {{C[jump="#perl_failure"]perl}} tag.

H4: {{CMD[id="mvasp_no_return"]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
C<E<lbracket>{{CMD[jump="#data"]data}}E<nbspace>sessionE<nbspace>mv_perl_result]>.
See {{C[jump="#perl_no_return"]perl}} tag.

H4: {{CMD[id="mvasp_subs"]subs}}

Enable {{CMD[jump="icconfig.html#GlobalSub *global*"]GlobalSub}} routines (requires catalog directive
{{C[jump="icconfig.html#AllowGlobal *global*"]AllowGlobal}}). See {{C[jump="#perl_subs"]perl}} tag.

H4: {{CMD[id="mvasp_global"]global}}

Turn off {{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe}}
protection (requires catalog directive
{{C[jump="icconfig.html#AllowGlobal *global*"]AllowGlobal}}). See
{{C[jump="#perl_global"]perl}} tag.

H4: {{CMD[id="mvasp_file"]file}}

Prepend the contents of the specified file or C<FileDatabase> entry to
the perl code before C<eval>'ing it. See {{C[jump="#perl_file"]perl}} tag.


H4: Examples

See the {{CMD[jump="ictemplates.html#ASP-Like Perl"]ASP-Like Perl}}
section of {{CMD[jump="ictemplates.html#Programming"]Interchange Programming}}.


H2: nitems

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


H3: Summary

!block example;
    [B<nitems> name]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#nitems_compare"]compare}}|<<
Regular expression the specified qualifier attribute's value must match
to be counted. This replaces the truth value comparison.
* N<Default:> None (uses truth value of the specified qualifier attribute)
>>|DEFAULT_VALUE
{{CMD[jump="#nitems_name"]name}}|<<
Cart name
* N<Default:> current cart
>>|DEFAULT_VALUE
{{CMD[jump="#nitems_qualifier"]qualifier}}|<<
An item attribute that must be true in order to count the item.
* N<Default:> None
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [nitems name]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->nitems(  { name => VALUE_name
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->nitems(name, $attribute_hash_reference, $body);
!endblock

H3: Description


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






# BEGIN ############ nitems Subsections ##############
H4: {{CMD[id="nitems_compare"]compare}}

Regular expression the specified qualifier attribute's value must match to be counted. This replaces the truth value comparison.
* N<Default:> None (uses truth value of the specified qualifier attribute)


H4: {{CMD[id="nitems_name"]name}}

Cart name
* N<Default:> current cart


H4: {{CMD[id="nitems_qualifier"]qualifier}}

An item attribute that must be true in order to count the item.
* N<Default:> None


# END +++++++++++++ nitems Subsections ++++++++++++

H2: 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 {{C[jump="#accessories"]accessories}} tag.

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

!block example
===
    [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>
===
!endblock

H3: Summary

!block example;
    [B<options> code]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#options_bold"]bold}}|<<
Boldfaces the labels if the C<'label'> option is set.
* N<Default:> False
>>|DEFAULT_VALUE
{{CMD[jump="#options_code"]code}}|<<
Product key (usually sku).
* No default
>>|DEFAULT_VALUE
{{CMD[jump="#options_joiner"]joiner}}|<<
The joiner for the widgets.
* N<Default:> E<lt>BR>
>>|DEFAULT_VALUE
{{CMD[jump="#options_label"]label}}|<<
Shows labels for the options with the widgets.

The following example (using another item from the 'tools' data)
illustrates the price and label N<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).

* N<Default:> False
>>|DEFAULT_VALUE
{{CMD[jump="#options_price"]price}}|<<
Boolean. If set and the options have prices, the HTML widget(s) will
show the prices. This is like the {{C[jump="#accessories_price"]price}}
attribute of the accessories tag.

. Note that the {{C[jump="#accessories_price_data"]price_data}} setting
comes from the 'price' column of the options table.

. Technical note-- If your options table has different mappings, you
can control this with $::Variable->{MV_OPTION_TABLE_MAP}
>>|False
{{CMD[jump="#options_table"]table}}|<<
Table to use for option attributes.  
* N<Default:> 'options'
>>|DEFAULT_VALUE
{{CMD[jump="#options_td"]td}}|<<
Results as table rows. For example, compare the following example from
the 'tools' sample data set with the earlier example:

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

(Note that the output was reformatted to fit this page)
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [options code]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->options(  { code => VALUE_code
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->options(code, $attribute_hash_reference, $body);
!endblock

H3: Description

NO DESCRIPTION SECTION



# BEGIN ############ options Subsections ##############
H4: {{CMD[id="options_bold"]bold}}

Boldfaces the labels if the C<'label'> option is set.
* N<Default:> False


H4: {{CMD[id="options_code"]code}}

Product key (usually sku).
* No default


H4: {{CMD[id="options_joiner"]joiner}}

The joiner for the widgets.
* N<Default:> E<lt>BR>


H4: {{CMD[id="options_label"]label}}

Shows labels for the options with the widgets.

The following example (using another item from the 'tools' data) illustrates the price and label N<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).

* N<Default:> False


H4: {{CMD[id="options_price"]price}}

Boolean. If set and the options have prices, the HTML widget(s) will show the prices. This is like the {{C[jump="#accessories_price"]price}} attribute of the accessories tag.

. Note that the {{C[jump="#accessories_price_data"]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}

* N<Default:> False

H4: {{CMD[id="options_table"]table}}

Table to use for option attributes.  
* N<Default:> 'options'


H4: {{CMD[id="options_td"]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)


# END +++++++++++++ options Subsections ++++++++++++

H2: or


H3: Summary

\Parameters: B<type term op compare>

THIS TAG HAS SPECIAL POSITIONAL PARAMETER HANDLING.



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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine: 

Called Routine for positional: 

B<ASP-like Perl call:>

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

Attribute aliases

>            base ==> type
>            comp ==> compare
>            operator ==> op


 

# BEGIN ############### or Summary Tables ####################
!block example;
    [B<or> type term op compare]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#or_type"]base}}|<<
Alias for type
>>|DEFAULT_VALUE
{{CMD[jump="#or_compare"]comp}}|<<
Alias for compare
>>|DEFAULT_VALUE
{{CMD[jump="#or_compare"]compare}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#or_op"]op}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#or_op"]operator}}|<<
Alias for op
>>|DEFAULT_VALUE
{{CMD[jump="#or_term"]term}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#or_type"]type}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [or type term op compare]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->or(  { compare => VALUE_compare
                 op => VALUE_op
                 term => VALUE_term
                 type => VALUE_type
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->or(type,term,op,compare, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ or End Summary Tables ++++++++++++++++++++


H3: Description

B<NO Description>



# BEGIN ########### or Subsections ##############
H4: {{CMD[id="or_compare"]compare}}



H4: {{CMD[id="or_op"]op}}



H4: {{CMD[id="or_term"]term}}



H4: {{CMD[id="or_type"]type}}



# END ++++++++++++ or Subsections +++++++++++++

H2: order

Expands into a hypertext link which will include the specified item
in the list of products to order and display the order page.

H3: Summary

!block example;
    [B<order> code quantity]I<Link Text>E<lt>/A>
    [B<order> code=[[EXAMPLE_SKU]] quantity=2]I<Link Text>E<lt>/A>
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
code|<<
This is the unique identifier for the item, typically the SKU in the
products table
>>|I<none>
quantity|Quantity to order|1
!endblock

!block table; colvaligns="TT"
Attributes|Default
code|I<No>
page|I<SpecialPage order>
cart|I<main cart>
base|I<ProductFiles array>
area|I<off>
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<No>
Container tag|I<No>
Has end tag|I<No> (C<[/order]> is a macro for C<E<lt>/AE<gt>>)
!endblock

B<Tag expansion example:>

!block example
    [order [[EXAMPLE_SKU]] 2]Buy [[EXAMPLE_DESCRIPTION]]E<lbracket>/order]
---
    <A HREF="http://localhost.localdomain/cgi-bin/tag72/ord/basket?\
    mv_session_id=[[EXAMPLE_SESSION]]&mv_pc=1&mv_action=refresh&\
    mv_order_item=[[EXAMPLE_SKU]]&mv_order_quantity=3">Buy [[EXAMPLE_DESCRIPTION]]</A>
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->order($code, $quantity);
!endblock


H3: Description


Expands into a hypertext link which will include the specified
code in the list of products to order and display the order page.

B<code> should be a product code listed in one of the "products"
databases. The optional argument B<base> constrains the order to
a particular products file. If not specified, all tables defined as
{{C[jump="icconfig.html#ProductFiles"]ProductFiles}}
will be searched in sequence for the item.

The optional argument B<cart> selects the shopping cart where the item
will be placed.

B<page> allows you to specify a different order page than the default
one specified by SpecialPage order.


H3: How to Order an Item

Interchange can either use a form-based order or a link-based order to
place an item in the shopping cart. The C<order> tag creates a
link-based order.

You can use the {{C[jump="#area"]area}} tag with form variables if you
need more control, for example, to change frames for the N<order:>

!block example
   <A HREF="[area href=ord/basket
                  form="mv_order_item=[[EXAMPLE_SKU]]
                        mv_order_quantity=2
                        mv_action=refresh"]"
    TARGET=newframe> Order [[EXAMPLE_DESCRIPTION]]</A>
!endblock

This can also be done more easily with the C<area> option to the C<order> tag:

!block example
    <A HREF="[order code=[[EXAMPLE_SKU]] quantity=2 area=1]"
         TARGET=newframe> Order [[EXAMPLE_DESCRIPTION]]</A>
!endblock

To order with a form, you set the form variable C<mv_order_item> to
the item-code/SKU and use the C<refresh> N<action:>

!block example
   <FORM ACTION="[process]" METHOD=POST>
   <INPUT TYPE=hidden  NAME="mv_todo"        VALUE="refresh">
   <INPUT TYPE=hidden  NAME="mv_order_item"  VALUE="[[EXAMPLE_SKU]]">

   Order <INPUT NAME="mv_order_quantity" SIZE=3 VALUE=1> [[EXAMPLE_DESCRIPTION]]

   <INPUT TYPE=submit VALUE="Order!">
   </FORM>
!endblock

Groups of items may be batched:

!block example
   <FORM ACTION="[process]" METHOD=POST>
   <INPUT TYPE=hidden  NAME="mv_todo"        VALUE="refresh">

   <INPUT TYPE=hidden  NAME="mv_order_item"  VALUE="TK112">
   <INPUT NAME="mv_order_quantity" SIZE=3> Standard Toaster

   <INPUT TYPE=hidden  NAME="mv_order_item"  VALUE="TK200">
   <INPUT NAME="mv_order_quantity" SIZE=3> Super Toaster

   <INPUT TYPE=submit VALUE="Order!">
   </FORM>
!endblock

Items that have a quantity of zero (or blank) will be skipped. Only
items with a positive quantity will be placed in the basket.

Attributes like size or color may be specified at time of order. See
the {{C[jump="#accessories"]accessories}} tag for detail.


H2: page

Expands to a hyperlink to an Interchange page or action, including
surrounding E<lt>AE<nbspace>HREFE<nbspace>...E<gt>. The URL within the
link includes the Interchange session ID and supplied arguments. The
optional [/page] is simply a macro for E<lt>/AE<gt>.

If you do not want the E<lt>AE<nbspace>HREFE<nbspace>...E<gt>, use the
{{CMD[jump="#area"]area}} tag insteadE<nbspace>E<emdash> these are
equivalent:
>    [page href=dir/page arg=mv_arg]TargetName</A>
>    <A HREF="[area href=dir/page arg=mv_arg]">TargetName</A>


H3: Summary

!block example;
    [B<page> href arg]
    [B<page> href=dir/page arg=page_arguments I<other_named_attributes>]
!endblock


#!block table; style="plain"; colvaligns="TTT"; format="262"
!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
href|<<
Path to Interchange page or action
. I<Special arguments>
** 'scan' treats B<arg> as a search argument
** 'http://...' external link (requires B<form> attribute)
>>|process
arg|Interchange arguments to page or action|I<none>
I<base>|alias for B<arg>|I<none>
!endblock

#!block table; style="plain"; colvaligns="TT"
!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#page_extra"]extra}}|I<none>
{{CMD[jump="#page_form"]form}}|I<none>
{{CMD[jump="#page_search"]search}}|I<No>
{{CMD[jump="#page_secure"]secure}}|I<No>
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

#!block table; style="plain";headings=1; colvaligns="TT"
!block table;headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<No>
Macro|I<No>
Has end tag|I<No> (C<[/page]> is a macro for C<E<lt>/AE<gt>>)
!endblock

B<Tag expansion example:>

!block example
    [page href=dir/page.html arg="arg1=AA/arg2=BB"]

    <a href="[[EXAMPLE_DOMAIN]]/cgi-bin/[[EXAMPLE_CATALOG]]/page.html?mv_session_id=[[EXAMPLE_SESSION]]&\
    mv_pc=1&mv_arg=arg1%3dAA/arg2%3dBB">
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->page(  { href => "dir/page",
                   arg  => "arguments", }  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->page($href, $arg, $attribute_hash_reference);
!endblock

Using arrayref for joined search (see also {{CMD[jump="#attr_array_hash"]Attribute Arrays and Hashes}})

!block example
    my $searchref = [ "se=hammer/fi=products/sf=description",
                      "se=plutonium/fi=products/sf=description", ];

    $Tag->page( { href   => 'scan',
                  search => $searchref, } );
!endblock


H4: See Also

{{CMD[jump="#area"]area}}
 

H3: Description


The C<page> tag inserts a hyperlink to the specified Interchange page
or action. For example, [C<page> shirts] will expand into
!block example
   <aE<nbspace>href="http://[[EXAMPLE_DOMAIN]]/cgi-bin/[[EXAMPLE_CATALOG]]/shirts?mv_session_id=[[EXAMPLE_SESSION]]&mv_pc=1">
!endblock
The catalog page displayed will come from "shirts.html" in the pages
directory.

The additional argument will be passed to Interchange and placed in the
{arg} session parameter. This allows programming of a conditional page
display based on where the link came from. The argument is then available
with the tag [data session arg], or the embedded Perl session variable
$Session->{arg}. Spaces and some other characters
will be escaped with the %NN HTTP-style notation and unescaped when the
argument is read back into the session.

For better performance, Interchange can prebuild and cache pages that
would otherwise be generated dynamically. If Interchange has built
such a static page for the target, the C<page> tag produces a link to
the cached page whenever the user has accepted and sent back a cookie
with the session ID. If the user did not accept the cookie,
Interchange cannot use the cache, since the link must then include the
I<mv_session_id> argument in order to preserve session.

H4: {{CMD[id="page_extra"]extra}}

H4: {{CMD[id="page_form"]form}}

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

!block example
        [page form="mv_order_item=[[EXAMPLE_SKU]]
                    mv_order_size=[[EXAMPLE_SIZE]]
                    mv_order_quantity=1
                    mv_separate_items=1
                    mv_todo=refresh"] Order [[EXAMPLE_SIZE]] [[EXAMPLE_DESCRIPTION]]</A>
!endblock

The two form values I<mv_session_id> and I<mv_arg> are automatically
added when appropriate. The form value I<mv_arg> receives the value
of the tag's C<arg> parameter.

This would generate a form that ordered quantity one of item number
C<[[EXAMPLE_SKU]]> with size C<[[EXAMPLE_SIZE]]>. The item would
appear on a separate line in the shopping cart, since
C<mv_separate_items> is set. Since the C<href> is not set, you will go
to the default shopping cart pageE<nbspace>E<emdash> alternatively,
you could have set C<mv_orderpage=yourpage> to go to C<yourpage>.

All normal Interchange form caveats applyE<nbspace>E<emdash> you must have an action,
you must supply a page if you don't want to go to the default,
etc.

You can theoretically submit any form with this, though none of the
included values can have newlines or trailing whitespace. If you want
to do something like that you will have to write a UserTag.

If the parameter C<href> is not supplied, I<process> is used, causing
normal Interchange form processing.

If the C<href> points to an http:// link, then no Interchange URL
processing will be done, but the URL will include mv_session_id,
mv_pc, and any arguments supplied with the C<arg> attribute:

!block example
       [page  href="http://www.elsewhere.net/cgi/script"
              form="cgi_1=ONE
                    cgi_2=TWO"
               arg="Interchange argument"]External link</A>

       <A HREF="http://www.elsewhere.net/cgi/script?\
        mv_session_id=[[EXAMPLE_SESSION]]&mv_pc=1&mv_arg=Interchange%20argument&\
        cgi_1=ONE&cgi_2=TWO">External link</A>
!endblock


H4: {{CMD[id="page_search"]search}}

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

^ Place the search specification in the named C<search> attribute.

** Interchange will ignore the C<href> parameter (the link will be set
to 'scan'.

** If you give the C<arg> parameter a value, that value will be
available as E<lbracket>{{C[jump="#value"]value}} mv_arg] within the
search display page.

+ Set the C<href> parameter to 'scan' and set C<arg> to the search
specification.

** Note that you can use this form positionallyE<nbspace>E<emdash> the
values go into C<href> and C<arg>, so you do not have to name
parameters.


These are identical:

!block example
    [page scan
          se=Impressionists
          sf=category]
        Impressionist Paintings
    </a>

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

    [page search="se=Impressionists
                  sf=category"]
        Impressionist Paintings
    </a>
!endblock

Here is the same thing from a non-Interchange page (e.g., a home
page), assuming '/cgi-bin/[[EXAMPLE_CATALOG]]' is the CGI path to Interchange's vlink):

!block example
     <A HREF="/cgi-bin/[[EXAMPLE_CATALOG]]/scan/se=Impressionists/sf=category">
        Impressionist Paintings
     </A>
!endblock

Sometimes, you will find that you need to pass characters that
will not be interpreted positionally. In that case, you should
quote the arguments:

>    [page href=scan
>          arg=|
>                se="Something with spaces"
>          |]

See the {{CMD[jump="#Search and Form Variables"]Search and Form Variables}}
appendix for a listing of the form variables along with two-letter
abbreviations and descriptions.


They can be treated just the same as form variables on the
page, except that they can't contain spaces, '/' in a file
name, or quote marks. These characters can be used
in URL hex encoding, i.e. %20 is a space, %2F is a
C</>, etc.E<nbspace>E<emdash> C<&sp;> or C<&#32;> will not be recognized.
If you use one of the methods below to escape these "unsafe"
characters, you won't have to worry about this.

You may specify a one-click search in three different ways. The first is as
used in previous versions, with the scan URL being specified completely as the
page name. The second two use the "argument" parameter to the C<[page ...]> or
E<lbracket>{{C[jump="#area"]area}} ...]> tags to specify the search
(an argument to a scan is never valid anyway).

H4: {{CMD[id="page_secure"]secure}}


H4: Original syntax

If you wish to do an OR search on the fields category and artist
for the strings "Surreal" and "Gogh", while matching substrings,
you would do:

> [page scan se=Surreal/se=Gogh/os=yes/su=yes/sf=artist/sf=category]
>    Van Gogh -- compare to surrealists
> </a>

In this method of specification, to replace a / (slash) in a file name
(for the sp, bd, or fi parameter) you must use the shorthand of ::,
i.e. sp=results::standard. (This may not work for some browsers, so you
should probably either put the page in the main pages directory or define
the page in a search profile.)

H4: Ampersand syntax

You can substitute & for / in the specification and be able to use / and
quotes and spaces in the specification.

> [page scan se="Van Gogh"&sp=lists/surreal&os=yes&su=yes&sf=artist&sf=category]
>    Van Gogh -- compare to surrealists
> </a>

Any "unsafe" characters will be escaped. 

H4: Multi-line syntax

You can specify parameters one to a line, as well. 

>    [page scan
>        se="Van Gogh"
>        sp=lists/surreal
>        os=yes
>        su=yes
>        sf=artist
>        sf=category
>    ] Van Gogh -- compare to surrealists </a>

Any "unsafe" characters will be escaped. You may not search for trailing
spaces in this method; it is allowed in the other notations.



H4: Joined searches

You can also specify a joined search using an attribute array (see
N<{{CMD[jump="#attr_array_hash"]Attribute Arrays and Hashes}}):>

!block example
    E<lbracket>page href=scan
      search.0="se=fragrant
                fi=products
                sf=smell"
      search.1="se=purple
                sf=color"
      search.2="se=perennial
                sf=type"]
!endblock

The search routine called by the page tag automatically adds the other
relevant search specification elements, including the 'co=yes' to
indicate a combined search
({{CMD[jump="icdatabase.html#Coordinated and Joined Searching"]joinedE<nbspace>searches}}
are described in the Interchange database documentation).


H4: E<lbracket>/page]

This is not an actual end tag, but simply a macro that expands to
</A>. The following two lines are equivalent:

>  [page shirts]Our shirt collection[/page]
>  [page shirts]Our shirt collection</A>

\Tip: In large pages, just use the </A> tag for a small performance improvement.


H2: perl


Executes the perl code contained by the tag. The code will run under
the restrictions of Perl's
{{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe}}
module by default. The tag expands to the value returned by the enclosed code
(i.e., printing to STDOUT or STDERR is useless).

See also {{CMD[jump="ictemplates.html#Programming"]Interchange Programming}}.

H3: Summary

!block example;
    [B<perl> tables] I<Code here> [/perl]
    [B<perl> tables="db1 db2 ..." I<other_named_attributes>] I<Code here> [/perl]
!endblock


!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
tables|<<
Database tables to be made available to ASP Perl code
>>|I<none>
table|Alias for C<tables>|I<none>
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#perl_failure"]failure}}|I<none>
{{CMD[jump="#perl_no_return"]no_return}}|I<No>
{{CMD[jump="#perl_subs"]subs}}|I<No>
{{CMD[jump="#perl_subs"]arg}}="subs"|I<Same as> C<subs>
{{CMD[jump="#perl_global"]global}}|I<No>
{{CMD[jump="#perl_file"]file}}|I<none>
{{CMD[jump="#perl_number_errors"]number_errors}}|I<none>
{{CMD[jump="#perl_eval_label"]eval_label}}|I<none>
{{CMD[jump="#perl_short_errors"]short_errors}}|I<none>
{{CMD[jump="#perl_trim_errors"]trim_errors}}|I<none>
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<Yes>
Has Subtags|I<No>
Container tag|I<Yes>
!endblock

B<Tag expansion example:>

!block example
    [perl tables="products" failure="Perl code error <BR>"]
!endblock

!block example; lang="Perl"
     my $result = "Looked up SKU $Values->{code}. It is a ";
     $result .= $Tag->data('products', 'description', $Values->{code} );
     return ("$result <br>\n");
!endblock
!block example
    [/perl]
---
    Looked up SKU [[EXAMPLE_SKU]]. It is a [[EXAMPLE_DESCRIPTION]] <br>
!endblock

B<ASP-like Perl call:> (e.g., to use it like a runtime eval() within your code)

!block example; lang="Perl"
    $Tag->perl(  { tables  => "products", },
                 $code  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->perl( $tables, $attribute_hash_reference );
!endblock

H4: See Also

See also {{CMD[jump="ictemplates.html#Programming"]Interchange Programming}},
E<lbracket>{{C[jump="#calc"]calc}}], and E<lbracket>{{C[jump="#mvasp"]mvasp}}].

H3: Description

This tag allows you to embed perl code within an Interchange page. The
code will run under the restrictions of Perl's 
{{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe}}
module by default. Perl's 'C<warnings>' and 'C<strict>' pragmas are
both turned off, and {{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe}} will block you from turning them on, since
it blocks Perl's 'C<use>' command. (This is not usually a problem,
since you should probably use an alternative such as a usertag if your
code is complex enough to need C<strict>.)

The tag expands to the value returned by the enclosed code
(i.e., printing to STDOUT or STDERR is useless).

!block example
    [perl]
!endblock
!block example; lang="Perl"
        $name    = $Values->{name};
        $browser = $Session->{browser};
        return "Hi, $name! How do you like your $browser?
!endblock
!block example
    [/perl]
!endblock

Object references are available for most Interchange tags and 
functions, as well as direct references to Interchange session and
configuration values.

!block table
Object|Description
$CGI->{key}|Hash reference to raw submitted values
$CGI_array->{key}|Arrays of submitted values
$Carts->{cartname}|Direct reference to shopping carts
$Config->{key}|Direct reference to $Vend::Cfg
$DbSearch->array(@args)|Do a DB search and get results
$Document->header()|Writes header lines
$Document->send()|Writes to output
$Document->write()|Writes to page
$Scratch->{key}|Direct reference to scratch area
$Session->{key}|Direct reference to session area
$Tag->tagname(@args)|Call a tag as a routine (UserTag too!)
$TextSearch->array(@args)|Do a text search and get results
$Values->{key}|Direct reference to user form values
$Variable->{key}|Config variables (same as $Config->{Variable});
&HTML($html)|Same as $Document->write($html);
&Log($msg)|Log to the error log
!endblock

For full descriptions of these objects, see
{{CMD[jump="ictemplates.html#Interchange Perl Objects"]Interchange Perl Objects}}.

H4: {{CMD[id="perl_tables"]tables}}

This should be a whitespace-separated list of database tables you want
to make available within the Perl code.

If you wish to use database values in your Perl code, the tag must
pre-open the table(s) you will be using. Here is an example using the
products N<table:>

!block example;
    [perl tables=products]
!endblock
!block example; lang="Perl"
        my $cost = $Tag->data('products', 'our_cost', $Values->{code});
        $min_price = $cost * ( 1 + $min_margin );
        return ($min_price > $sale_price) ? $min_price : $sale_price;
!endblock
!block example
    [/perl]
!endblock

If you do not do this, your code will fail with a runtime {{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe}}
error when it tries to look up 'our_cost' in the products database
with the {{C[jump="#data"]data}} tag.

Even if you properly specify the tables to pre-open, some database
operations will still be restricted because C<Safe> mode prohibits
creation of new objects. For SQL, most operations can be performed if
the C<Safe::Hole> module is installed. Otherwise, you may have to set
the {{C[jump="#perl_global"]global}}C<=1> attribute to use data from
SQL tables.

Interchange databases can always be accessed as long as they are
pre-opened by using an item first. 

Technical note:

{{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe}} objects (including database handles) may persist within
a page, and the C<perl> tag does not necessarily destroy objects
created earlier in the page. As a result, your code may work even
though you did not set 'C<tables>' properly, only to break later when
you change something elsewhere on the page.

For example, this will work because the first call to
E<lbracket>{{C[jump="#accessories"]accessories}}E<nbspace>...] opens
the (default) products table:

!block example;
    [accessories code=os28044 attribute=size]

    [perl]
        return $Tag->accessories( { attribute => 'size',
                                    code      => 'os28085' } );
    [/perl]
!endblock

If you remove the first E<lbracket>accessories ...] tag, then the
$Tag->accessories call will fail with a {{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe}} error unless you also set
'C<tables>=products' in the C<perl> tag.

The moral of this story is to ensure that you pass all necessary
tables in the C<perl> tag.


H4: {{CMD[id="perl_failure"]failure}}

If your code contains a compile or runtime error and fails to evaluate
(i.e., eval($code) would set $@), the tag will return the value set
for the C<failure> attribute. The error will be logged as usual.

For example,

!block example;
    [perl failure="It Broke"]
!endblock
!block example; lang="Perl"
        my $cost = $Tag->data('products', 'our_cost', $Values->{code});
        $min_price = $cost * ( 1 + $min_margin );
        return ($min_price > $sale_price) ? $min_price : $sale_price;
!endblock
!block example
    [/perl]
!endblock

will return 'It Broke' because the $Tag->Data(...) call will fail
under the {{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe}} module (see {{CMD[jump="#perl_tables"]tables}} above).

H4: {{CMD[id="perl_no_return"]no_return}}

If C<no_return=1>, this attribute suppresses the return value of the perl code.

You can retrieve the return value from the session hash via
C<E<lbracket>{{CMD[jump="#data"]data}}E<nbspace>sessionE<nbspace>mv_perl_result]>
until it gets overwritten by another C<perl> tag.

If C<no_return> is set, the C<perl> tag I<will> return any output
explicitly written with the &HTML or $Document->write() functions.

!block note; label="Note: "

If C<no_return> is I<not> set, then the $Document->write() buffer is
not returned (unless you use $Document->hot(1) or $Document->send(),
in which case the contents of the write buffer will probably appear
before anything else on the page). See
{{CMD[jump="ictemplates.html#Interchange Perl Objects"]Interchange Perl Objects}}
for more detail.
!endblock

Here is an example:

!block example;
    [perl tables=products no_return=1]
!endblock
!block example; lang="Perl"
        my $cost = $Tag->data('products', 'our_cost', $Values->{code});
        $min_price = $cost * ( 1 + $min_margin );
        &HTML( ($min_price > $sale_price) ? $min_price : $sale_price );
        return ($min_price > $sale_price) ? 'too low' : 'ok';
!endblock
!block example
    [/perl]
!endblock

This will put the same price on the page as our earlier example, but
#$Session->{mv_perl_result} will be either 'too low' or 'ok'.
C<$Session-E<gt>{mv_perl_result}> will be either 'too low' or 'ok'.

The [{{C[jump="#mvasp"]mvasp}}] tag is very similar to
E<lbracket>perlE<nbspace>no_return=1].

H4: {{CMD[id="perl_subs"]subs}}

If you have set the {{C[jump="icconfig.html#AllowGlobal *global*"]AllowGlobal}}
catalog directive, setting C<subs=1> will enable you to call
{{CMD[jump="icconfig.html#GlobalSub *global*"]GlobalSub}} routines
within the enclosed perl code. Note that this can compromise security.

H4: {{CMD[id="perl_global"]global}}

If you have set the {{C[jump="icconfig.html#AllowGlobal *global*"]AllowGlobal}}
catalog directive, setting C<global=1> will turn off
{{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe}}
protection within the tag.

The code within the tag will then be able to do anything the user ID
running Interchange can. This seriously compromises security, and
you should know what you are doing before using it in a public site. It
is especially dangerous if a single Interchange server is shared by
multiple companies or user IDs.

Also, full 'C<use strict>' checking is turned on by default when in
global mode. You can turn it off by using 'C<no strict;>' within your
code. Note that any C<strict> errors will go to the Interchange error
logs, and the tag itself will fail silently within the page.

H4: {{CMD[id="perl_file"]file}}

This prepends the contents of the specified file or C<FileDatabase> entry to
the enclosed perl code (if any), then executes as usual.

For example, 

!block example;
    [perl file="my_script.pl"][/perl]
!endblock

would execute myscript.pl and expand to its return value.

Absolute filenames (or filenames containing '../') are prohibited by
the {{C[jump="icconfig.html#NoAbsolute *global*"]NoAbsolute}}
catalog directive.

If the filename is not absolute, Interchange first looks for a file in
the current directory, then in the list set with the
{{C[jump="icconfig.html#TemplateDir *global*"]TemplateDir}} catalog
directive. If it fails to find a file by that name, it then looks for
an entry by that name in the database specified with the
C<FileDatabase> catalog directive.

H4: {{CMD[id="perl_number_errors"]file}}

Add line numbers to the source code displayed in the error.log, amazingly
useful if some of the perl is being generated elsewhere and interpolated.

H4: {{CMD[id="perl_eval_label"]eval_label}}

Set to a string, will replace the (eval ###) in the error message with
this label, handy to quickly track down bugs when you have more than
one perl block in the page, especially if you are using {{CMD[jump="#perl_short_errors"]short_errors}}.

H4: {{CMD[id="perl_short_errors"]short_errors}}

If set to a true value, syntax errors and the like in perl tags will
log just the error, not the whole source code of the block in question,
handy when you have the code open in an editor anyway and don't want
the error itself to get scrolled away when running 'tail -f error.log'.

H4: {{CMD[id="perl_trim_errors"]trim_errors}}

If set to a number, and the error produced includes a line number, then
only that number of lines before and after the broken line itself will be
displayed, instead of the whole block.



H2: price

H3: Summary

\Parameters: B<code>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->price(
>        {
>         code => VALUE,
>        }
>    )
>
> OR
>
>    $Tag->price($code, $ATTRHASH);

Attribute aliases

>            base ==> mv_ib


 

# BEGIN ############### price Summary Tables ####################
!block example;
    [B<price> code I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#price_base"]base}}|<<
Alias for mv_ib
>>|DEFAULT_VALUE
{{CMD[jump="#price_code"]code}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [price code]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->price(  { code => VALUE_code
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->price(code, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ price End Summary Tables ++++++++++++++++++++


H3: Description


\Arguments:

>        code       Product code/SKU
>        base       Only search in product table *base*
>        quantity   Price for a quantity
>        discount   If true(1), check discount coupons and apply
>        noformat   If true(1), don't apply currency formatting

Expands into the price of the product identified by code as found in
the products database. If there is more than one products file defined,
they will be searched in order unless constrained by the optional
argument B<base>. The optional argument B<quantity> selects an entry
from the quantity price list. To receive a raw number, with no currency
formatting, use the option C<noformat=1>.

Interchange maintains a price in its database for every product. The price
field is the one required field in the product databaseE<nbspace>E<emdash> it is necessary
to build the price routines.

For speed, Interchange builds the code that is used to determine a product's
price at catalog configuration time. If you choose to change a directive
that affects product pricing you must reconfigure the catalog.

Quantity price breaks are configured by means of the I<CommonAdjust>
directive. There are a number of CommonAdjust recipes which can be
used; the standard example in the demo calls for a separate pricing
table called C<pricing>. Observe the following:

>   CommonAdjust  pricing:q2,q5,q10,q25, ;products:price, ==size:pricing

This says to check quantity and find the applicable
column in the pricing database and apply it. In this case, it would be:

>    2-4      Column *q2*
>    5-9      Column *q5*
>    10-24    Column *q10*
>    25 up    Column *q25*

What happens if quantity is one? It "falls back" to the price that
is in the table C<products>, column C<price>.

After that, if there is a size attribute for the product, the column
in the pricing database corresponding to that column is checked for
additions or subtractions (or even percentage changes).

If you use this tag in the demo:

>    [price code=99-102 quantity=10 size=XL]

the price will be according to the C<q10> column, adjusted by what is in
the XL column. (The row is of course 99-102.) The following entry in
pricing:

>  code    q2   q5   q10  q25  XL
>  99-102  10   9    8    7    .50

Would yield 8.50 for the price. Quantity of 10 in the C<q10> column,
with 50 cents added for extra large (XL).

Following are several examples based on the above entry
as well as this the entry in the C<products> table:

>  code    description   price    size
>  99-102  T-Shirt       10.00    S=Small, M=Medium, L=Large*, XL=Extra Large

\NOTE: The examples below assume a US locale with 2 decimal places, use
of commas to separate, and a dollar sign ($) as the currency formatting.

>  TAG                                          DISPLAYS
>  ----------------------------------------     --------
>  [price 99-102]                               $10.00
>  [price code="99-102"]                        $10.00
>  [price code="99-102" quantity=1]             $10.00
>  [price code="99-102" noformat=1]             10
>  [price code="99-102" quantity=5]             $9.00
>  [price code="99-102" quantity=5 size=XL]     $9.50
>  [price code="99-102" size=XL]                $10.50
>  [price code="99-102" size=XL noformat=1]     10.5

Product discounts for specific products, all products, or the entire
order can be configured with the [discount ...] tag. Discounts are applied
on a per-user basisE<nbspace>E<emdash> you can gate the discount based on membership in a
club or other arbitrary means.

Adding [discount 99-102] $s * .9[/discount] deducts 10% from the
price at checkout, but the price tag will not show that unless you
add the discount=1 parameter.

>    [price code="99-102"]            -->   $10.00
>    [price code="99-102" discount=1] -->   $9.00

See I<Product Discounts>.




# BEGIN ########### price Subsections ##############
H4: {{CMD[id="price_base"]base}}

H4: {{CMD[id="price_code"]code}}



# END ++++++++++++ price Subsections +++++++++++++

H2: process

This is a shortcut for the 'process' action, expanding to your catalog URL and session ID. It is analogous to the {{C[jump="#area"]area}} tag for the 'process' page, but is more limited. The following expansion is N<illustrative:>

!block example
    [process target=targetframe]
---
    http://[[EXAMPLE_DOMAIN]]/cgi-bin/[[EXAMPLE_CATALOG]]/process.html?\
    id=[[EXAMPLE_SESSION]]" TARGET="targetframe
!endblock

(the trailing backslash indicates continuation, i.e., the result should be only one line)

Note the mismatched quotes in the expansion.  Your surrounding HTML should supply the containing quotes, like N<this:>

!block example
   <A HREF="[process target=targetframe]">...
!endblock

N:Aliases:  B<process_target>, B<process_order>


H3: Summary

!block example;
    [B<process> target secure]
    [B<process> target=I<targetframe> secure=1 I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
target|<<
The target frame or window
>>|I<None>
secure|<<
Boolean.  If true (secure=1), the URL will link to your secure server.
>>|I<No>
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<No>
Container tag|I<No>
!endblock

B<Tag expansion example:>

!block example
    [process targetframe 1]
---
    http://[[EXAMPLE_SECURE_DOMAIN]]/cgi-bin/[[EXAMPLE_CATALOG]]/process.html?\
    id=[[EXAMPLE_SESSION]]" TARGET="targetframe
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->process(  { target => 'frametarget',
                      secure => 1, } );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->process($target, $secure, $attribute_hash_reference);
!endblock


H2: process-search

This is an exact alias for E<lbracket>{{C[jump="#area"]area}}<C search>].


H2: query

Passes SQL statements through to SQL databases, or allows SQL queries
via Interchange's database abstraction into non-SQL databases and text
files. The latter requires the Perl
{{CMD[jump="http://search.cpan.org/doc/JWIED/SQL-Statement-0.1017/lib/SQL/Statement.pm"]SQL Statement}}
module (included with Bundle::Interchange from CPAN).

H3: Summary

!block example;
    [B<query> sql]
    [B<query> sql="SQL_query_text" I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#query_sql"]sql}}|<<
The SQL statement.
* Passed directly through to an SQL database.
* For a non-SQL table, the tag interprets your SQL first. See the
{{CMD[jump="http://search.cpan.org/doc/JWIED/SQL-Statement-0.1017/lib/SQL/Statement.pm"]SQL Statement}}
module for limitations and detail.
>>|I<none>
{{CMD[jump="#query_sql"]query}}|Alias for C<sql>|I<none>
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#query_table"]table}}|products
{{CMD[jump="#query_table"]base}} (alias for C<table>)|products
{{CMD[jump="#query_type"]type}} (row_count, html, list, textref)|I<none: uses arrayref="" if no type>
{{CMD[jump="#query_arrayref"]arrayref}}|I<arrayref="" if no> C<type> I<given>
{{CMD[jump="#query_arrayref"]hashref}}|I<none>
{{CMD[jump="#query_more"]more}} (type=list)|I<No>
{{CMD[jump="#query_form_variables"]xx}} form var. abbrev. (type=list)|I<see form variable>
{{CMD[jump="#query_prefix"]}} (type=list)|sql
{{CMD[jump="#query_list_prefix"]list_prefix}} (type=list)|list
{{CMD[jump="#query_random"]random}} (type=list)|I<No>
{{CMD[jump="#query_safe_data"]safe_data}} (type=list)|I<No>
{{CMD[jump="#query_label"]label}} (type=list)|current
{{CMD[jump="#query_form"]form}} (type=list)|I<none>
{{CMD[jump="#query_wantarray"]wantarray}}|I<No>
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<No>
Container tag|I<Yes>
Has {{CMD[jump="#query_subtags"]subtags}}|I<Yes>
Nests|I<No>
!endblock

B<Tag usage example:>

This will list sku, description and price for ten products per page,
followed by hyperlinks to the other pages of the list. Note that you
may interpolate Interchange tags in the usual way if you double-quote
the SQL statement.

!block example
    [query sql="select sku, description, price from products where price < [value mv_arg]"
         type=list
         more=1
           ml=10]

      [on_match]Matched<br>[/on_match]
      [no_match]Not Found<br>[/no_match]

      [list]
        [sql-code] [sql-param description] [sql-price]
      [/list]

      [more_list]
        Matches [matches] of [match-count] shown.<BR>
        [more]
      [/more_list]
    [/query]
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   my $sql = "select * from products order by price";
   my $result_array = $Tag->query( { sql => $sql,  },
                                   $body );
   my ($same_results, $col_name_hash, $col_name_array) =
                      $Tag->query( { sql => $sql,  },
                                   $body );

   my $result_hasharray = $Tag->query( { sql     => $sql,
                                         hashref => 'my_results',  },
                                       $body );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->query( $sql, $attribute_hash_reference, $body);
!endblock


H3: Description

The C<query> tag allows you to make SQL queries. If you are using an
SQL database table, the tag will pass your SQL statement directly to
the database and return the result.

If your table is not in an SQL database (for example, GDBM, text,
LDAP, and in-memory tables), Interchange will internally convert it to
an Interchange search specification with the Perl
{{CMD[jump="http://search.cpan.org/doc/JWIED/SQL-Statement-0.1017/lib/SQL/Statement.pm"]SQL Statement}}
module (included with Bundle::Interchange from CPAN). This means that
you can use simple SQL queries regardless of the underlying database
implementation.

H4: {{CMD[id="query_subtags"]Subtags}}

For list queries ({{C[jump="#query_type"]type}}=list), the following
subtags are available:

!block table; colvaligns="TT"
Subtag|Usage
on_match|<<
E: E<lbracket>on_match]
E:   I<do this if something matched>
E: E<lbracket>/on_match]
>>
no_match|<<
E: E<lbracket>no_match]
E:   I<do this if nothing matched>
E: E<lbracket>/no_match]
>>
list|<<
E: E<lbracket>{{I[jump="#query_list_prefix"]list_prefix}}]
E:   I<do this for each matched item>
E: E<lbracket>/I<list_prefix>]

The 'C<list>' subtag defines a region where you can use any of the
looping subtags that work in array-list context (see
{{CMD[jump="#Looping tags and Sub-tags"]Looping tags and Sub-tags}}).

The default looping tag prefix will be 'sql'. Note however that you
can override this by setting the {{C[jump="#query_prefix"]prefix}}
attribute in the enclosing C<query> tag.

Similarly, the C<list_prefix> attribute renames the E<lbracket>list]
subtag itself to the value you set (see
{{C[jump="#query_list_prefix"]list_prefix}} below).
>>
more_list|<<
E: E<lbracket>more_list]
E:   [more]
E: E<lbracket>/more_list]

The 'C<more_list>' and 'C<more>' subtags are used when paginating the
query results (see '{{C[jump="#query_more"]more}}' attribute). The
E<lbracket>C<more>] subtag will expand to a list of links to the other
pages of the query results.
>>
!endblock

See also the example at the end of the Summary section above.


H4: Perl and ASP usage

If you are calling $Tag->query within a C<perl> tag (or whenever the
code is secured by the {{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe.pm}} module), you must be sure to set the
{{C[jump="#perl_tables"]tables}} attribute properly in the enclosing
C<perl> tag (see the {{C[jump="#perl"]perl}} tag documentation for
detail).

The {{CMD[jump="#query_type"]types}} that return text to a page (i.e.,
row_count, html, and textref) work as usual, returning an appropriate
string. Note that you may also have access to the results as an array
reference in $Vend::Interpolate::Tmp->{''} for the life of the page.

If you do not set a {{CMD[jump="#query_type"]type}}, the tag will return a reference to an array of array references, since the default with no {{CMD[jump="#query_type"]type}} is C<arrayref="">.

If you call $Tag->query in scalar context and set
{{CMD[jump="#query_arrayref"]arrayref}} or
{{CMD[jump="#query_arrayref"]hashref}}, it will return your results as
a reference to an array of either arrayrefs or hashrefs,
respectively (i.e., the same data structures you would get from Perl's
DBI.pm module with fetchall_arrayref).

In list context, the first returned element is the aforementioned
reference to your results. The second element is a hash reference to
your column names, and the third element is an an array reference to the
list of column names.

The following examples should be N<illustrative:>

>  [perl tables=products]
!block example; lang="Perl"
    my $sql = "select sku, price, description from products
               where price < 10 order by price";

    my $results = $Tag->query( { sql => $sql, } );
    my ( $same_results, $col_name_hashref, $col_name_arrayref)
        = $Tag->query( { sql => $sql, } );

    my $hash_results = $Tag->query( {     sql => $sql,
                                      hashref => 'my_results' } );

    # $Vend::Interpolate::Tmp->{my_results} == $hash_results
    # $Vend::Interpolate::Tmp->{''} == $results == $same_results

    my $out = "The returned structure is\n";
        $out .= $Tag->uneval( $results );
    
    #loop through each row & display the fields
    foreach my $row (@$hash_results) {
       $out .= '<p>sku: ' . $row->{sku}
           $out .= '<br>price: ' . $row->{price};
           $out .= '<br>description: ' . $row->{description};
    }
    return $out;

!endblock
>  [/perl]

!block note; label="Technical Note: "
The $Tag->query() call works a bit differently in GlobalSubs and UserTags than within a {{C[jump="#perl"]perl}} tag.  Specifically, in a GlobalSub or global UserTag, if you call query() in list context and want the three references (i.e., results, column hash and column array), then you need to set the '{{CMD[jump="#query_wantarray"]wantarray}}=1' attribute in the query() call.  See the {{CMD[jump="#query_wantarray"]wantarray}} attribute.
!endblock

H4: {{CMD[id="query_sql"]sql}}

This is the text of your SQL statement. The standard Interchange
quoting rules apply. For example, use double quotes (") if you want to
interpolate Interchange tags within your SQL statement, backticks (`)
to calculate a value, I<etc.>

!block example
    [query sql="select description, price from products
               where price < [value mv_arg]" ...]
        ...
    [/query]
!endblock

H4: {{CMD[id="query_table"]table}}

The table attribute sets the database to use for the query. The
default will typically be the database containing the 'C<products>'
table (unless you have changed the first entry in
$Vend::Cfg->{ProductFiles}).


H4: {{CMD[id="query_type"]type}}

If you are not setting the '{{C[jump="#query_arrayref"]arrayref}}' or
'{{C[jump="#query_arrayref"]hashref}}' attributes, then the type
attribute defines the way the query will return its results. The
C<type> should be one of the N<following:>

!block table; colvaligns="TT"
Type|Returns
html|<<
The html type returns the results in an html table. You will need to
supply the enclosing <TABLE ...> and </TABLE> html tags. The following
is an example of typical N<usage:>

E: <TABLE>
E:   [query sql="select * from products
E:               where price > 12
E:               order by price"
E:         type=html]
E:   [/query]
E: </TABLE>
>>
list|<<
This allows you to use subtags to control the query output and
pagination. See the {{CMD[jump="#query_subtags"]Subtags}} section
above for detail.
>>
row_count|<<
This causes the tag to return the number of rows in the query result.
>>
textref|<<
This causes the tag to return a the query results as a serialized
array of arrays that Perl can evaluate with its B<eval()>
function. Here is an illustrative example:
E:  my $rows = eval( $Tag->query( { sql  => "select * from products"
E:                                  type => "textref" } )
E:                 );
E:
E:  my $r3_c0 = $rows->[3]->[0];
>>
!endblock

If you do not specify a type, the tag will create an arrayref as if you
had set 'arrayref=""'.

H4: {{CMD[id="query_arrayref"]arrayref and hashref}}

If you set 'C<arrayref>=I<keyname>' or 'C<hashref>=I<keyname>', the
query will not return results to the page. Instead, it will place the
results of your query in the $Vend::Interpolate::Tmp hash. Using
'C<arrayref>=my_query' sets $Vend::Interpolate::Tmp->{my_query} to
refer to an array of array references, while 'C<hashref>=my_query'
creates an array of hash references.

Note that this is useful only if you intend to access the results
within Perl code (for example, within a
E<lbracket>{{C[jump="#perl"]perl}}] tag), since there is no direct
output to the returned page.

The $Vend::Interpolate::Tmp hash persists only for the life of the
template page being processed. If you need the query results array
reference to outlive the page, you will have to save the reference
somewhere more persistent such as the $Session N<hash:>

E:   $Session->{my_query} = $Vend::Interpolate::Tmp->{my_query};

Beware the impact on performance if you do this with large result
sets.

Technical noteE<nbspace>E<emdash> the string returned by the 'C<textref>'
{{C[jump="#query_type"]type}} will B<eval>() to the 'C<arrayref>' data
structure.

H4: {{CMD[id="query_more"]more}}

Requires '{{C[jump="#query_type"]type}}=list'.

You must set C<more>=1 to properly paginate your results from C<list>
queries (see '{{C[jump="#query_type"]type}}=list' above. If you do not
set C<more>=1, then the links to later pages will merely redisplay
the first page of your results.

H4: {{CMD[id="query_form_variables"]form variable abbreviations}}

Requires '{{C[jump="#query_type"]type}}=list'.

See the {{CMD[jump="#Search and Form Variables"]Search and Form Variables}}
appendix for a list of form variables. Note that you must use the
two-letter abbreviation rather than the full form variable name.

A few deserve special N<mention:>

!block table; colvaligns="TTT"
Abbr|Name|Description
ml|mv_matchlimit|<<
Sets number of rows to return. If paginating
({{C[jump="#query_more"]more}}=1), sets rows returned per page.
>>
fm|mv_first_match|Start displaying search at specified match
sp|mv_search_page|Sets the page for search display
st|mv_searchtype|<<
Forces a specific search type (text, glimpse, db or sql), overriding
the default determined from your database implementation.
>>
!endblock

H4: {{CMD[id="query_prefix"]}}

Requires '{{C[jump="#query_type"]type}}=list'.

Setting 'C<prefix>=foo' overrides the default prefix of 'sql' for loop
subtags within a list region (see
{{CMD[jump="#Looping tags and Sub-tags"]Looping tags and Sub-tags}}). 

See the {{CMD[jump="#query_list_prefix"]list_prefix}} attribute below
for an illustrative example.

H4: {{CMD[id="query_list_prefix"]list_prefix}}

Requires '{{C[jump="#query_type"]type}}=list'.

Setting 'C<list_prefix>=bar' overrides the default region tagname of
'list'. The best way to show this is by example. Compare the
following two examples of list queries, the first using the defaults
and the second with explicitly set C<prefix> and C<list_prefix>.

!block example
    [query sql="select sku, description, price from products
               where price < 20"
         type=list
         more=1
           ml=10]

      [on_match]Matched<br>[/on_match]
      [no_match]Not Found<br>[/no_match]

      [list]
        [sql-code] [sql-param description] [sql-price]
      [/list]

      [more_list]
        [more]
      [/more_list]
    [/query]
---
    [query  sql="select sku, description, price from products
                where price < 20"
           type=list
         B<prefix=foo>
    B<list_prefix=bar>
           more=1
             ml=10]

      [on_match]Matched<br>[/on_match]
      [no_match]Not Found<br>[/no_match]

      [bar]
        [foo-code] [foo-param description] [foo-price]
      [/bar]

      [more_list]
        [more]
      [/more_list]
    [/query]
!endblock


H4: {{CMD[id="query_random"]random}}

Requires '{{C[jump="#query_type"]type}}=list'.

You can use the 'C<random>' attribute to randomly select a set of rows
from the whole result set of your query. In other words, setting
'C<random>=I<n>', where I<n> > 0, causes the E<lbracket>C<list>]
region to loop over I<n> randomly chosen rows rather than the full
query result set.

The example below would display three randomly chosen products
priced under 20.

!block example
    [query sql="select * from products
               where price < 20"
         type=list
       random=3]

      [list]
        [sql-code] [sql-param description] [sql-price]
      [/list]

    [/query]
!endblock


H4: {{CMD[id="query_safe_data"]safe_data}}

Requires '{{C[jump="#query_type"]type}}=list'.

NoteE<nbspace>E<emdash> you should not set this unless you need it and
know what you are doing.

Setting 'C<safe_data>=1' allows the E<lbracket>sql-data] tag to return
values containing the '[' character. See also
{{CMD[jump="#Looping tags and Sub-tags"]Looping tags and Sub-tags}}.

Beware of reparsing issues.

H4: {{CMD[id="query_label"]label}}

Requires '{{C[jump="#query_type"]type}}=list'.

If you are setting up multiple simultaneously active search objects
within a page, this allows you to distinguish them. The default label
is 'current'. Most people will not need this.


H4: {{CMD[id="query_form"]form}}

Requires '{{C[jump="#query_type"]type}}=list'.

You can use this to pass one CGI form variable in the pagination links
of a E<lbracket>more-list]. For example, 'C<form>="foo=bar"' to
include '&foo=bar' in the URL of each of the pagination links.

Note that the variable will not be available in the initial result set
since the query returns the first page directly (i.e., you did not
follow a pagination link).


H4: {{CMD[id="query_wantarray"]wantarray}}

This is relevant only when calling $Tag->query( ... ) within global
Perl code such as a globalsub or global usertag where $MVSAFE::Safe is
not defined. In these cases, setting 'C<wantarray>=1' allows the call
to

E:  $Tag->query( { wantarray => 1, ... }, ... ); 

to return references as it would if called within an ordinary
E<lbracket>{{C[jump="#perl"]perl}}] tag. Note that it does not force
list context if you call $Tag->query in scalar context.

Here is another example of the use of the array references, from a UserTag:

!block example
    my $sku = 'os28044';
    my $sql = qq{select description, price from products where sku = '$sku'};
    my $table = 'products';

    my ($results, $col_name_hashref, $col_name_arrayref) = $Tag->query({
            wantarray => 1,
            sql => "$sql",
            table => "$table"});

    my $out;

    # this will get the first field (description)..
    $out = 'description: ' . $results->[0]->[0];

    # and this the second field (price)..
    $out .= '<br>price: ' . $results->[0]->[1];

    # this will tell us the position in the $results array of the price field..
    $out .= '<br>position of price field: ' . $col_name_hashref->{price};
    return $out;
!endblock

If the [query] returns more than one row, the second row's description field would be:

>    $results->[1]->[0]

Technical noteE<nbspace>E<emdash> the ordinary
E<lbracket>C<query>E<nbspace>...]E<nbspace>...E<nbspace>E<lbracket>C</query>]
usage forces scalar context on the
query call and suppresses the return value for those
{{C[jump="#query_type"]types}} that would return references if
$Tag->query were called within a E<lbracket>{{C[jump="#perl"]perl}}]
tag. The wantarray option is needed because global subs and usertags
are also affected by this unless you set wantarray.

Example of a nested query:

!block example
    [query
        ml=99
        type=list
        sp="@@MV_PAGE@@"
        sql=|
            SELECT  foo1, foo2, foo3
            FROM    bar
            WHERE   someothercol = 'bang'
        |]
        [list]

            Here is [sql-param foo1] from outer <br>


           [query
               prefix=usr
               list_prefix=detail
               ml=1
               type=list
               sp="@@MV_PAGE@@"
               sql=|
                SELECT  flip
                FROM    flap
                WHERE   flog = 'flan'
              |]

             [usr-on-match]
                something was found in the inner!
             [/usr-on-match]

             [detail]

                Here is [usr-param flip] from inner <br>

                Here is [sql-param foo2] from outer!! <br>

             [/detail]
           [/query]

            Here is [sql-param foo3] from outer!!! <br>

        [/list]
        [on-match]
            Something was found in the outer query<br>
        [/on-match]
        [no-match]
            Nothing was found in the outer query<br>
        [/no-match]
        [more-list]
                <br>[matches] in the outer query<br>
        [/more-list]
    [/query]
!endblock

Notice the use of 'prefix' and 'list_prefix' on subsequent inner queries.

H2: read-cookie

Returns the value of the named cookie. Returns nothing if the cookie
does not exist.


H3: Summary

!block example;
    [read-cookie name]
    [read-cookie name=mycookie]
!endblock

!block table; colvaligns="TTT"; format="262"
Attributes|Description|Default
{{CMD[jump="#read_cookie_name"]name}}|<<
The name of the cookie whose value you want
>>|I<none>
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<Yes>
Container tag|I<No>
!endblock

B<Usage example:>

!block example
    [read-cookie name=MV_SESSION_ID]
---
    [[EXAMPLE_SESSION]]
!endblock



B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->read_cookie(  { name => $name, }  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->read_cookie( $name );
!endblock
 

H3: Description

This tag expands to the value of the named cookie (or nothing if the
cookie does not exist).

See the Netscape specification at
{{CMD[jump="http://www.netscape.com/newsref/std/cookie_spec.html"]http://www.netscape.com/newsref/std/cookie_spec.html}}
if you need more cookie-specific detail.

H4: {{CMD[id="read_cookie_name"]name}}

This is the name of the cookie whose value you want to retrieve.

H4: {{CMD[id="read_cookie_HTTP_COOKIE"]Parsing an HTTP_COOKIE string}}

If you pass this tag a second parameter within a Perl call, it will
use your value as the HTTP_COOKIE string (ignoring the real one). This
only applies if you pass the values positionally within a perl call
since there is no name for the HTTP_COOKIE string N<input:>

!block example; lang="Perl"
  $Tag->read_cookie('MV_SESSION_ID', "MV_SESSION_ID=UnHyaDQj:127.0.0.1; ...");
!endblock


H2: restrict

Restrict tag execution in a region. If a restricted tag
is encountered, it is simply output.


H3: Summary

!block example;
    [B<restrict> tag1 tag2]
    [B<restrict> policy=deny enable="page area value"]
!endblock

!block table; colvaligns="TTT"; format="262"
Attributes|Description|Default
{{CMD[jump="#restrict_policy"]policy}}|<<
Whether to allow or deny by default.
>>|B<deny>
{{CMD[jump="#restrict_enable"]enable}}|<<
Tags to enable when default policy is deny.
>>|I<none>
{{CMD[jump="#restrict_disable"]disable}}|<<
Tags to disable. Overrides enable.
>>|I<none>
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<Yes>
Container tag|I<No>
!endblock

B<Usage example:>

!block example
    [read-cookie name=MV_SESSION_ID]
---
    [[EXAMPLE_SESSION]]
!endblock



B<ASP-like Perl call:>

!block example; lang="Perl"
    N/A. Cannot be called effectively.
!endblock

H3: Description

Restrict tag execution in a region. If a restricted tag
is encountered, it is simply output. It can be used to allow certain tags
in a user-editable region, while denying dangerous tags. Or it can be used
to restrict all tag execution in a region.

H4: {{CMD[id="restrict_policy"]policy}}

Default is C<deny>, which makes most sense. You then specifically enable
certain ITL tags. If you set C<allow> by default, you must be very careful
that you really are disabling all of what you consider to be dangerous tags.

H4: {{CMD[id="restrict_enable"]enable}}

A space-separated or comma-separated list of tags to disable when the
default policy is C<deny>. Has no effect when the default policy is C<allow>,
and any tags passed in the disable parameter override the enable.

H4: {{CMD[id="restrict_disable"]disable}}

A space-separated or comma-separated list of tags to disable when the
default policy is C<allow>. If you have a list of tags that are enabled,
perhaps stored in a scratch variable, you can disable some of those tags
since this takes precedence over the enable.



H2: row


H3: Summary

\Parameters: B<width>

Positional parameters in same order.


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

Interpolates B<container text> by default.

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

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->row(
>        {
>         width => VALUE,
>        },
>        BODY
>    )
>
> OR
>
>    $Tag->row($width, $BODY);

 

# BEGIN ############### row Summary Tables ####################
!block example;
    [B<row> width]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#row_width"]width}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [row width]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->row(  { width => VALUE_width
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->row(width, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ row End Summary Tables ++++++++++++++++++++


H3: Description


Formats text in tables. Intended for use in emailed reports or <PRE></PRE> HTML
areas. The parameter I<nn> gives the number of columns to use. Inside the
row tag, [col param=value ...] tags may be used. 


H4: E<lbracket>col width=nn wrap=yes|no gutter=n align=left|right|input spacing=n]

Sets up a column for use in a [row]. This parameter can only be contained
inside a [row nn] [/row] tag pair. Any number of columns (that fit within
the size of the row) can be defined.

The parameters are:

>    width=nn        The column width, I<including the gutter>. Must be
>                    supplied, there is no default. A shorthand method
>                    is to just supply the number as the I<first> parameter,
>                    as in [col 20].
>
>    gutter=n        The number of spaces used to separate the column (on
>                    the right-hand side) from the next. Default is 2.
>
>    spacing=n       The line spacing used for wrapped text. Default is 1,
>                    or single-spaced.
>
>    wrap=(yes|no)   Determines whether text that is greater in length than
>                    the column width will be wrapped to the next line. Default
>                    is I<yes>.
>
>    align=(L|R|I)   Determines whether text is aligned to the left (the default),
>                    the right, or in a way that might display an HTML text
>                    input field correctly.

H4: E<lbracket>/col]

Terminates the column field.







# BEGIN ########### row Subsections ##############
H4: {{CMD[id="row_width"]width}}



# END ++++++++++++ row Subsections +++++++++++++

H2: salestax


H3: Summary

\Parameters: B<name noformat>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->salestax(
>        {
>         name => VALUE,
>         noformat => VALUE,
>        }
>    )
>
> OR
>
>    $Tag->salestax($name, $noformat);

Attribute aliases

>            cart ==> name


 

# BEGIN ############### salestax Summary Tables ####################
!block example;
    [B<salestax> name noformat]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#salestax_name"]cart}}|<<
Alias for name
>>|DEFAULT_VALUE
{{CMD[jump="#salestax_name"]name}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#salestax_noformat"]noformat}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [salestax name noformat]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->salestax(  { name => VALUE_name
                       noformat => VALUE_noformat
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->salestax(name,noformat, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ salestax End Summary Tables ++++++++++++++++++++


H3: Description


Expands into the sales tax on the subtotal of all the items ordered so
far for the cart, default cart is C<main>. If there is no key field to
derive the proper percentage, such as state or zip code, it is set to
0. If the noformat tag is present and non-zero, the raw number with no
currency formatting will be given.






# BEGIN ########### salestax Subsections ##############
H4: {{CMD[id="salestax_name"]name}}



H4: {{CMD[id="salestax_noformat"]noformat}}



# END ++++++++++++ salestax Subsections +++++++++++++

H2: scratch


H3: Summary

\Parameters: B<name>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->scratch(
>        {
>         name => VALUE,
>        }
>    )
>
> OR
>
>    $Tag->scratch($name);

 

# BEGIN ############### scratch Summary Tables ####################
!block example;
    [B<scratch> name]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#scratch_name"]name}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [scratch name]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->scratch(  { name => VALUE_name
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->scratch(name, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ scratch End Summary Tables ++++++++++++++++++++


H3: Description


Returns the contents of a scratch variable to the page. (A scratch
variable is set with a [set] value [/set] container pair.)



# BEGIN ########### scratch Subsections ##############
H4: {{CMD[id="scratch_name"]name}}



# END ++++++++++++ scratch Subsections +++++++++++++

H2: scratchd

Deletes the named scratch variable and returns its value before the deletion. For example,

!block example;
    [B<scratchd> I<varname_to_delete>]
!endblock

deletes the scratch variable I<varname_to_delete>.

See also the {{C[jump="#scratch"]scratch}} and {{C[jump="#set"]set}} tags.


H3: Summary

!block example;
    [B<scratchd> P_PARAM]
    [B<scratchd> N_PARAM I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
name|<<
Name of scratch variable to delete
>>|I<None>
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<Yes>
Container tag|I<No>
!endblock


B<Tag expansion example:>

!block example
    [set myvar]This is myvar[/set]
    .
    .
    .
    [scratchd myvar]
---
    This is myvar
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->scratchd($name, $attribute_hash_reference);
!endblock
 

H3: Description

Deletes the named scratch variable and returns its value before the deletion.


H2: search-list

Formats results returned by a search. Must be enclosed within a
{{C[jump="#search-region"]search-region}}. Has sub-tags (see
{{C[jump="#Looping tags and Sub-tags"]Looping tags and Sub-tags}}). 


H2: search-region


H3: Summary

\Parameters: B<arg>

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

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [search-region] FOO [/search-region].
\Nesting: NO

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->search_region(
>        {
>         arg => VALUE,
>        },
>        BODY
>    )
>
> OR
>
>    $Tag->search_region($arg, $ATTRHASH, $BODY);

Attribute aliases

>            args ==> arg
>            params ==> arg
>            search ==> arg


 

# BEGIN ############### search-region Summary Tables ####################
!block example;
    [search-region arg I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#search_region_arg"]arg}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#search_region_arg"]args}}|<<
Alias for arg
>>|DEFAULT_VALUE
{{CMD[jump="#search_region_arg"]params}}|<<
Alias for arg
>>|DEFAULT_VALUE
{{CMD[jump="#search_region_arg"]search}}|<<
Alias for arg
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [search-region arg]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->search_region(  { arg => VALUE_arg
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->search_region(arg, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ search-region End Summary Tables ++++++++++++++++++++


H3: Description

B<NO Description>





# BEGIN ########### search-region Subsections ##############
H4: {{CMD[id="search_region_arg"]arg}}



# END ++++++++++++ search-region Subsections +++++++++++++

H2: selected


H3: Summary

\Parameters: B<name value>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->selected(
>        {
>         name => VALUE,
>         value => VALUE,
>        }
>    )
>
> OR
>
>    $Tag->selected($name, $value, $ATTRHASH);

 

# BEGIN ############### selected Summary Tables ####################
!block example;
    [B<selected> name value I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#selected_case"]case}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#selected_cgi"]cgi}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#selected_default"]default}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#selected_name"]name}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#selected_multiple"]multiple}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#selected_value"]value}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [value name=example set=neato]
    <OPTION[selected example neato]>Neato
    <OPTION[selected example silly]>Silly
---
    <OPTION SELECTED>Neato
    <OPTION>Silly
!endblock

# END +++++++++++++++ selected End Summary Tables ++++++++++++++++++++


H3: Description


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

This will output SELECTED if the variable C<var_name> is equal to
C<value>. If the optional MULTIPLE argument is present, it will
look for any of a variety of values. Not case sensitive unless
the optional C<case=1> parameter is used.

Here is a drop-down menu that remembers an item-modifier
color selection:

>    <SELECT NAME="color">
>    <OPTION [selected color blue]> Blue
>    <OPTION [selected color green]> Green
>    <OPTION [selected color red]> Red
>    </SELECT>

Here is the same thing, but for a shopping-basket color selection:

>    <SELECT NAME="[item-modifier-name color]">
>    <OPTION [selected [item-modifier-name color] blue]> Blue
>    <OPTION [selected [item-modifier-name color] green]> Green
>    <OPTION [selected [item-modifier-name color] red]> Red
>    </SELECT>

By default, the Values space (i.e. [value foo]) is checkedE<nbspace>E<emdash> if you
want to use the volatile CGI space (i.e. [cgi foo]) use the parameter
C<cgi=1>.

Use the parameter C<default=1> to specify the option that should be
marked SELECTED if the value/CGI variable has never been set.

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



# BEGIN ########### selected Subsections ##############
H4: {{CMD[id="selected_case"]case}}

H4: {{CMD[id="selected_cgi"]cgi}}

H4: {{CMD[id="selected_default"]default}}

H4: {{CMD[id="selected_name"]name}}

H4: {{CMD[id="selected_multiple"]multiple}}

H4: {{CMD[id="selected_value"]value}}

# END ++++++++++++ selected Subsections +++++++++++++


H2: set


H3: Summary

\Parameters: B<name>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

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

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->set(
>        {
>         name => VALUE,
>        },
>        BODY
>    )
>
> OR
>
>    $Tag->set($name, $BODY);

 

# BEGIN ############### set Summary Tables ####################
!block example;
    [B<set> name]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#set_name"]name}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->set(  { name => VALUE_name
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->set(name, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ set End Summary Tables ++++++++++++++++++++


H3: Description


Sets a scratch variable to I<value>.

Most of the mv_* variables that are used for search and order conditionals are
in another namespaceE<nbspace>E<emdash> they can be set by means of hidden fields in a
form.

You can set an order profile with:

>  [set checkout]
>  name=required
>  address=required
>  [/set]
>  <INPUT TYPE=hidden NAME=mv_order_profile VALUE="checkout">

A search profile would be set with:

>  [set substring_case]
>  mv_substring_match=yes
>  mv_case=yes
>  [/set]
>  <INPUT TYPE=hidden NAME=mv_profile VALUE="substring_case">

Any of these profile values can be set in the OrderProfile files
as well.




# BEGIN ########### set Subsections ##############
H4: {{CMD[id="set_name"]name}}



# END ++++++++++++ set Subsections +++++++++++++

H2: set-cookie

Sets browser cookie(s) with the specified attributes.

H3: Summary

!block example;
    [set-cookie I<named_attributes>]
!endblock

Parameters must be named (no positional usage except in Perl call)

!block table; colvaligns="TTT"; format="262"
Attributes|Description|Default
{{CMD[jump="#set_cookie_name"]name}}|<<
The name you give the cookie
>>|I<none>
{{CMD[jump="#set_cookie_value"]value}}|<<
The value (automatically html-escaped by Interchange)
>>|I<none>
{{CMD[jump="#set_cookie_expire"]expire}}|<<
Expiration date as
. "Wdy, DD-Mon-YYYY HH:MM:SS GMT"
>>|I<none>
{{CMD[jump="#set_cookie_domain"]domain}}|<<
Overrides the domain(s) set in {{C[jump="icconfig.html#CookieDomain"]CookieDomain}}
>>|<<
I<Domain(s), if any, defined in the> {{C[jump="icconfig.html#CookieDomain"]CookieDomain}} I<directive>
>>
{{CMD[jump="#set_cookie_path"]path}}|<<
legal URL paths for the cookie
>>|I<URL path(s) to your catalog, including aliases>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<Yes>
Container tag|I<No>
!endblock

B<Usage example:>

!block example
    [set-cookie name=mycookie
               value="the value"
              expire="Tue, 03-Apr-2001 17:00:00 GMT"]
---
    I<This tag returns no value in the page>
!endblock



B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->set_cookie(  { name   => $name,
                         value  => $value,
                         expire => $expire,
                         domain => $domain,
                         path   => $path, }  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->set_cookie( $name, $value, $expire, $domain, $path );
!endblock
 

H3: Description

This tag sets one or more browser cookies with your specified name,
value, and expiration. (Interchange will set more than one cookie if
needed to ensure that the cookie is visible from all 
{{C[jump="icconfig.html#Catalog *global*"]Catalog}} URL path
aliases and {{C[jump="icconfig.html#CookieDomain"]CookieDomains}}.)

See the Netscape specification at
{{CMD[jump="http://www.netscape.com/newsref/std/cookie_spec.html"]http://www.netscape.com/newsref/std/cookie_spec.html}}
for more cookie-specific detail.

If you need access to the cookie from outside of your Interchange
catalog, you can also set the domain and URL paths for which the
cookie will be valid. If you need the cookie only within your catalog
and the domains specified by the
{{C[jump="icconfig.html#CookieDomain"]CookieDomain}} directive, you
probably should not override the Interchange domain and path defaults.


H4:  {{CMD[id="set_cookie_name"]name}}

This is the name of the cookie. This is the key you will use when reading the
cookie later.

H4:  {{CMD[id="set_cookie_value"]value}}

This is the value to store in the cookie.

H4:  {{CMD[id="set_cookie_expire"]expire}}

Persistent cookies (that outlive a browser session) require an
expiration date. There are two ways to set it -- relative times
and absolute times.

LI2: absolute

The date must be a string of the N<form:>

. "Wdy,E<nbspace>DD-Mon-YYYYE<nbspace>HH:MM:SSE<nbspace>GMT"

and the timezone must be GMT.

LI2: relative

Supply a period in the form C<NN> C<sec|min|hours|days|weeks>.

\Example:

> [set-cookie name=THE_COOKIE value=foo expire="7 days"]

If you do not supply a date (either absolute or relative), the cookie will disappear when the user
closes the browser.

H4:  {{CMD[id="set_cookie_domain"]domain}}

The value you set will override the Interchange default
domain(s). You might set this if you need access to the cookie from
outside the Interchange catalog, but it is usually better to set the
{{C[jump="icconfig.html#CookieDomain"]CookieDomain}} directive in your
catalog.

The default is to use your catalog's domain or all
{{C[jump="icconfig.html#CookieDomain"]CookieDomain}} values.

H4:  {{CMD[id="set_cookie_path"]path}}

The value you set will override the Interchange default URL path(s).

The default is to set a cookie with a path for each catalog alias (see
the {{C[jump="icconfig.html#Catalog *global*"]Catalog}} directive).
This ensures that the cookie will be visible regardless of how the end
user returns to your catalog. 

H3: Tips

You can use the time tag in conjunction with the set-cookie tag to set
the expiration date to an absolute date.

>   [set-cookie
>     name=mycookie
>     value="the value"
>     expire="[time gmt=1 adjust='+2190']%a, %m-%b-%Y %H:%M:%S GMT[/time]"
>   ]

In the example above, the adjustment of +2190 will set a cookie
expiration of 2190 hours forward from the current date.

You can use the 

H2: seti


H3: Summary

\Parameters: B<name>

Positional parameters in same order.


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

Interpolates B<container text> by default.

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

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->seti(
>        {
>         name => VALUE,
>        },
>        BODY
>    )
>
> OR
>
>    $Tag->seti($name, $BODY);

 

# BEGIN ############### seti Summary Tables ####################
!block example;
    [B<seti> name]value[/seti]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#seti_name"]name}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [seti name]value[/seti]
---
    TODO: (tag result)
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->seti(  { name => VALUE_name
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->seti(name, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ seti End Summary Tables ++++++++++++++++++++


H3: Description

Equivalent to the E<lbracket>{{C[jump="#set"]set}}] tag, except that
it {{CMD[jump="#attr_interpolate"]interpolates}} by default.



# BEGIN ########### seti Subsections ##############
H4: {{CMD[id="seti_name"]name}}



# END ++++++++++++ seti Subsections +++++++++++++

H2: setlocale

Sets locale and/or currency for the current page. Can be made persistent for the user with the 'persist' option. Resets default locale if called without arguments.  See also {{CMD[jump="ic_i18n.html#Setting the Locale"]Setting the Locale}} in the template documentation.


H3: Summary

!block example;
    [B<setlocale>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#setlocale_currency"]currency}}|<<
The currency format to use.
* N<Default:> [scratch mv_currency] (see also 'persist' attribute)
>>|DEFAULT_VALUE
{{CMD[jump="#setlocale_locale"]locale}}|<<
The locale to use.
* N<Default:> [scratch mv_locale] (see also 'persist' attribute)
>>|DEFAULT_VALUE
{{CMD[jump="#setlocale_persist"]persist}}|<<
Setting 'C<persist=1>' also sets the scratch variables, B<mv_locale> and B<mv_currency> to specified locale and currency. This makes the locale settings persistent for the user's session. Otherwise (C<persist=0>), the C<setlocale> tag affects the remainder of the current page only.
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [setlocale]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->setlocale(  { 
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->setlocale(, $attribute_hash_reference, $body);
!endblock

H3: Description

Immediately sets the locale to C<locale>, and will cause it to persist in future user pages if the C<persist> is set to a non-zero, non-blank value. If the C<currency> attribute is set, the pricing and currency-specific locale keys and Interchange configuration directives are modified to that locale. If there are no arguments, it sets it back to the user's default locale as defined in the scratch variables C<mv_locale> and C<mv_currency>.

This N<allows:>

!block example
    Dollar Pricing:

    [setlocale en_US]
    [item-list]
    [item-code]: [item-price]<BR>
    [/item-list]

    Franc Pricing:

    [setlocale fr_FR]
    [item-list]
    [item-code]: [item-price]<BR>
    [/item-list]

    [comment] Return to the user's default locale [/comment]
    [setlocale]
!endblock



# BEGIN ############ setlocale Subsections ##############
H4: {{CMD[id="setlocale_currency"]currency}}

The currency format to use.
* N<Default:> [scratch mv_currency] (see also 'persist' attribute)


H4: {{CMD[id="setlocale_locale"]locale}}

The locale to use.
* N<Default:> [scratch mv_locale] (see also 'persist' attribute)


H4: {{CMD[id="setlocale_persist"]persist}}

Setting 'C<persist=1>' also sets the scratch variables, B<mv_locale> and B<mv_currency> to specified locale and currency. This makes the locale settings persistent for the user's session. Otherwise (C<persist=0>), the C<setlocale> tag affects the remainder of the current page only.


# END +++++++++++++ setlocale Subsections ++++++++++++

H2: shipping

Returns the cost of shipping the items in the cart via the shipping mode set with the B<mode> parameter. See also the {{CMD[jump="icdatabase.html#Shipping"]Shipping}} section of the Database documentation.


H3: Summary

!block example;
    [B<shipping> mode]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#shipping_add"]add}}|<<
Adds the argument to B<add> as data for a shipping.asc file (in $Vend::Cfg->{ScratchDir}/) and sets it.
>>|DEFAULT_VALUE
{{CMD[jump="#shipping_cart"]cart}}|<<
* N<Alias:> B<carts>
Space- and/or comma-delimited list of names of carts to calculate aggregate shipping cost for.
* N<Default:> current cart
>>|DEFAULT_VALUE
{{CMD[jump="#shipping_cart"]carts}}|<<
Alias for cart
>>|DEFAULT_VALUE
{{CMD[jump="#shipping_convert"]convert}}|<<
Applies the conversion (if any) set with the {{C[jump="icconfig.html#PriceDivide"]PriceDivide}} catalog configuration directive.
* N<Default:> True
>>|DEFAULT_VALUE
{{CMD[jump="#shipping_default"]default}}|<<
Resets shipping mode to default of [value mv_shipmode]
>>|DEFAULT_VALUE
{{CMD[jump="#shipping_file"]file}}|<<
Filename to read shipping from (default is usual shipping database, e.g., shipping.asc)
>>|DEFAULT_VALUE
{{CMD[jump="#shipping_format"]format}}|<<
Format for results with B<label> attribute.
* N<Default:> '<OPTION VALUE="%M"%S>%D (%F)'
* For example,
>    [shipping mode="FLAT"
>             label=1
>            format="My Format Desc %D Price %F"]
>>|DEFAULT_VALUE
{{CMD[jump="#shipping_handling"]handling}}|<<
Boolean-- use [value mv_handling] rather than [value mv_shipping] as
first default for B<mode>. Note that this attribute matters only if you
do not specify the B<mode> in the tag.
* Note that this is set by the E<lbracket>{{C[jump="#handling"]handling}}
tag (which calls the C<shipping> tag internally).  You should probably
use the handling tag rather than setting this directly.
* N<Default:> False
>>|DEFAULT_VALUE
{{CMD[jump="#shipping_hide"]hide}}|<<
Suppresses output
>>|DEFAULT_VALUE
{{CMD[jump="#shipping_label"]label}}|<<
By default, returns HTML <OPTION ...> widget for shipping mode(s),
including description and cost. You can override the widget with the
B<format> attribute.  Note that B<label> overrides B<noformat>.
* Here is an example from the foundation checkout.html page:
> [shipping
>     label=1
>     mode=|[data
>            table=country
>			 key='[default country US]'
>			 col=shipmodes]|
> ]
>>|DEFAULT_VALUE
{{CMD[jump="#shipping_mode"]mode}}|<<
* N<Aliases:> B<name>, B<modes>
Whitespace, null or comma delimited list of modes for which to calculate shipping cost.  See also mv_shipmode.
* N<Default:> E<lbracket>value mv_handling] if B<handling=1> or E<lbracket>value mv_shipmode] or 'default'
>>|DEFAULT_VALUE
{{CMD[jump="#shipping_mode"]modes}}|<<
Alias for mode
>>|DEFAULT_VALUE
{{CMD[jump="#shipping_mode"]name}}|<<
Alias for mode
>>|DEFAULT_VALUE
{{CMD[jump="#shipping_noformat"]noformat}}|<<
Returns result as a number rather than a string formatted for the current locale's currency.
* N<Default:> True
>>|DEFAULT_VALUE
{{CMD[jump="#shipping_reset_message"]reset_message}}|<<
Boolean. Blanks the session's current shipping message (i.e., $Session->{ship_message}).
>>|DEFAULT_VALUE
{{CMD[jump="#shipping_reset_modes"]reset_modes}}|<<
Clears list of modes in $Vend::Cfg->{Shipping_line}
* N<Default:> False
>>|DEFAULT_VALUE
{{CMD[jump="#shipping_table"]table}}|<<
* N<Alias:> B<tables>
Whitespace-delimited list of tables containing shipping data required for perl or query calculations (I<e.g.>, in the 'PERL' field of your shipping databaseE<nbspace>E<emdash> see {{CMD[jump="icdatabase.html#Shipping"]Shipping}}). You must specify the tables to get past the Perl '{{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe.pm}}' protection. For example, you will get '{{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe}}' errors if you refer to an SQL table without specifying it here.
* N<Default:> None
>>|DEFAULT_VALUE
{{CMD[jump="#shipping_table"]tables}}|<<
Alias for table
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [shipping mode]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->shipping(  { mode => VALUE_mode
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->shipping(mode, $attribute_hash_reference, $body);
!endblock

H3: Description

This tag calculates the shipping cost for items in the current cart via the specified shipping mode (usually set in the mv_shipmode variable).  See the {{CMD[jump="icdatabase.html#Shipping"]Shipping}} section of the Database documentation for detail.

It also has options to build a selection widget (usually SELECT or RADIO types) with embedded cost data.

H4: Rounding

Note that the tag rounds the calculated shipping cost to a locale-specific
number of fractional digits (e.g., to the nearest penny, or 2 digits
after the decimal point in the USA).




# BEGIN ############ shipping Subsections ##############
H4: {{CMD[id="shipping_add"]add}}

Adds the argument to B<add> as data for a shipping.asc file (in $Vend::Cfg->{ScratchDir}/) and sets it.


H4: {{CMD[id="shipping_cart"]cart}}

* N<Alias:> B<carts>
Comma-delimited list of names of carts to calculate shipping cost for.
* N<Default:> current cart


H4: {{CMD[id="shipping_convert"]convert}}

Applies the conversion (if any) set with the {{C[jump="icconfig.html#PriceDivide"]PriceDivide}} catalog configuration directive.
* N<Default:> True


H4: {{CMD[id="shipping_default"]default}}

Resets shipping mode to default of [value mv_shipmode]


H4: {{CMD[id="shipping_file"]file}}

Filename to read shipping from (default is usual shipping database, e.g., shipping.asc)


H4: {{CMD[id="shipping_format"]format}}

Format for results with B<label> attribute.
* N<Default:> '<OPTION VALUE="%M"%S>%D (%F)'
* For example,
>    [shipping mode="FLAT"
>             label=1
>            format="My Format Desc %D Price %F"]


H4: {{CMD[id="shipping_handling"]handling}}

Boolean-- use [value mv_handling] rather than [value mv_shipping] as first default for B<mode>. Note that this attribute matters only if you do not specify the B<mode> in the tag.
* Note that this is set by the E<lbracket>{{C[jump="#handling"]handling}} tag (which calls the C<shipping> tag internally).  You should probably use the handling tag rather than setting this directly.
* N<Default:> False


H4: {{CMD[id="shipping_hide"]hide}}

Suppresses output


H4: {{CMD[id="shipping_label"]label}}

By default, returns HTML <OPTION ...> widget for shipping mode(s), including description and cost. You can override the widget with the B<format> attribute.  Note that B<label> overrides B<noformat>.
* Here is an example from the foundation checkout.html page:
>    [shipping
>        label=1
>        mode=|[data table=country key='[default country US]' col=shipmodes]|
>    ]


H4: {{CMD[id="shipping_mode"]mode}}

* N<Aliases:> B<name>, B<modes>
Whitespace, null or comma delimited list of modes for which to calculate shipping cost.  See also mv_shipmode.
* N<Default:> E<lbracket>value mv_handling] if B<handling=1> or E<lbracket>value mv_shipmode] or 'default'


H4: {{CMD[id="shipping_noformat"]noformat}}

Returns result as a number rather than a string formatted for the current locale's currency.
* N<Default:> True

H4: {{CMD[id="shipping_no_state"]no_state}}

Bypasses the state lookup for [shipping widget=TYPE] and [shipping possible=1].

H4: {{CMD[id="shipping_possible"]possible}}

Returns all possible modes for the selected country and state, based on
the C<country> and C<state> tables.

Does a query to find the C<shipmodes> column of the state based on the
user value C<state>, and/or the C<shipmodes> column of the country based
on the value C<country>

\NOTE: You can set the following, though most will use the Interchange
defaults:

!block example
 state_table         state table for lookup (default "state")
 country_table       country table for lookup (default "country")
 state_modes_field   shipmodes field in state table (default "shipmodes")
 country_modes_field shipmodes field in country table (default "shipmodes")
 country_table       country table for lookup (default "country")
 state_var           state variable in user session (default "state")
 country_var         country variable in user session (default "country")
 shipmode_var        shipmode variable in user session (default "mv_shipmode")
!endblock

H4: {{CMD[id="shipping_reset_message"]reset_message}}

Boolean. Blanks the session's current shipping message (i.e., $Session->{ship_message}).


H4: {{CMD[id="shipping_reset_modes"]reset_modes}}

Clears list of modes in $Vend::Cfg->{Shipping_line}
* N<Default:> False


H4: {{CMD[id="shipping_resolve"]resolve}}

Returns the one shipping mode to set as a default, based on the best
information available. Usually selects the first in the list based
on country or state.

H4: {{CMD[id="shipping_table"]table}}

* N<Alias:> B<tables>
Whitespace-delimited list of tables containing shipping data required for perl or query calculations (I<e.g.>, in the 'PERL' field of your shipping databaseE<nbspace>E<emdash> see {{CMD[jump="icdatabase.html#Shipping"]Shipping}}). You must specify the tables to get past the Perl '{{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe.pm}}' protection. For example, you will get '{{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe}}' errors if you refer to an SQL table without specifying it here.
* N<Default:> None

H4: {{CMD[id="shipping_widget"]widget}}

Returns a pre-configured widget for shipping mode selection. Will select
the modes from [shipping possible=1], but will also do shipping calculations
to see if they are valid.

If there is no weight, zip, country, or other needed information, it will return
"not enough information".

In other words, [shipping widget=select] might return to the page:

!block example;
 <select name="mv_shipmode">
 	<option value="upsg" SELECTED>UPS Ground (&#36;4.20)
	<option value="upsb">UPS 2nd Day Air (&#36;8.76)
 </select>
!endblock

# END +++++++++++++ shipping Subsections ++++++++++++

H2: shipping-desc

Returns the shipping description for the specified shipping B<mode>.  See the {{CMD[jump="icdatabase.html#Shipping"]Shipping}} section of the Database documentation.  See also shipping.asc database for shipping modes.

N<Alias:> B<shipping-description>

The two tags below are identical in N<operation:>

>   [shipping-desc mode]
>   [shipping-description mode]


H3: Summary

!block example;
    [B<shipping-desc> mode]
    [B<shipping-desc> mode=I<shipping_mode>]
!endblock

!block table; colvaligns="TTT"; format="244"
Parameters|Description|Default
mode|<<
Shipping mode. This is a key into the shipping.asc database. See {{CMD[jump="icdatabase.html#Shipping"]Shipping}} documentation.
>>|C<mv_shipmode>, or 'default' if C<mv_shipmode> not set
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|Yes, but only if no B<mode> given
Container tag|I<No>
!endblock

B<Tag expansion example:>

!block example
    [shipping-desc 1DM]
---
    UPS Next Day Air Early AM
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->shipping_desc( $mode );
!endblock



H2: soap


H3: Summary

\Parameters: B<call uri proxy>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->soap(
>        {
>         call => VALUE,
>         uri => VALUE,
>         proxy => VALUE,
>        }
>    )
>
> OR
>
>    $Tag->soap($call, $uri, $proxy, $ATTRHASH);

 

# BEGIN ############### soap Summary Tables ####################
!block example;
    [B<soap> call uri proxy I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#soap_call"]call}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#soap_proxy"]proxy}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#soap_uri"]uri}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [soap call uri proxy]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->soap(  { call => VALUE_call
                   proxy => VALUE_proxy
                   uri => VALUE_uri
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->soap(call,uri,proxy, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ soap End Summary Tables ++++++++++++++++++++


H3: Description

B<NO Description>




# BEGIN ########### soap Subsections ##############
H4: {{CMD[id="soap_call"]call}}



H4: {{CMD[id="soap_proxy"]proxy}}



H4: {{CMD[id="soap_uri"]uri}}



# END ++++++++++++ soap Subsections +++++++++++++

H2: strip

Strips leading and trailing whitespace from the contained body text.

H3: Summary

!block example;
    [B<strip>]
       Body text to strip
    [B</strip>]
!endblock

No parameters.

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<No>
Container tag|I<Yes>
Has Subtags|I<No>
!endblock

B<ASP-like Perl call:>

E:   $Tag->strip($BODY);

or even better, just do it directly like this

!block example; lang="Perl"
   $BODY =~ s/^\s+//;
   $BODY =~ s/\s+$//;
!endblock



H2: subtotal


H3: Summary

\Parameters: B<name noformat>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->subtotal(
>        {
>         name => VALUE,
>         noformat => VALUE,
>        }
>    )
>
> OR
>
>    $Tag->subtotal($name, $noformat);

Attribute aliases

>            cart ==> name


 

# BEGIN ############### subtotal Summary Tables ####################
!block example;
    [B<subtotal> name noformat]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#subtotal_name"]cart}}|<<
Alias for name
>>|DEFAULT_VALUE
{{CMD[jump="#subtotal_name"]name}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#subtotal_noformat"]noformat}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [subtotal name noformat]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->subtotal(  { name => VALUE_name
                       noformat => VALUE_noformat
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->subtotal(name,noformat, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ subtotal End Summary Tables ++++++++++++++++++++


H3: Description


\Positional: [subtotal cart* noformat*]

mandatory: NONE

optional: cart noformat

Expands into the subtotal cost, exclusive of sales tax, of
all the items ordered so far for the optional C<cart>. If the noformat
tag is present and non-zero, the raw number with no currency formatting
will be given.




# BEGIN ########### subtotal Subsections ##############
H4: {{CMD[id="subtotal_name"]name}}



H4: {{CMD[id="subtotal_noformat"]noformat}}



# END ++++++++++++ subtotal Subsections +++++++++++++

H2: tag


H3: Summary

\Parameters: B<op arg>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

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

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->tag(
>        {
>         op => VALUE,
>         arg => VALUE,
>        },
>        BODY
>    )
>
> OR
>
>    $Tag->tag($op, $arg, $ATTRHASH, $BODY);

Attribute aliases

>            description ==> arg


 

# BEGIN ############### tag Summary Tables ####################
!block example;
    [B<tag> op arg I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#tag_arg"]arg}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#tag_arg"]description}}|<<
Alias for arg
>>|DEFAULT_VALUE
{{CMD[jump="#tag_op"]op}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
{{CMD[jump="#attr_attachonly"]attach_only}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [tag op arg]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->tag(  { arg => VALUE_arg
                  op => VALUE_op
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->tag(op,arg, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ tag End Summary Tables ++++++++++++++++++++


H3: Description


Performs any of a number of operations, based on the presence of C<arg>.
The arguments that may be given are:


H4: {{CMD[id="tag_export"]export database file* type*}}

Exports a complete Interchange database to its text source file (or any
specified file). The integer C<n>, if specified, will select export in
one of the enumerated Interchange export formats. The following tag will
export the products database to products.txt (or whatever you have
defined its source file as), in the format specified by the
I<Database> directive:

>    [tag export products][/tag]

Same thing, except to the file products/new_products.txt:

>    [tag export products products/newproducts.txt][/tag]

Same thing, except the export is done with a PIPE delimiter:

>    [tag export products products/newproducts.txt 5][/tag]

The file is relative to the catalog directory, and only may be
an absolute path name if I<NoAbsolute> is set to C<No>.

H4: {{CMD[id="tag_flag"]flag arg}}

Sets an Interchange condition.

The following enables writes on the C<products> and C<sizes> databases
held in Interchange internal DBM format:

>    [tag flag write]products sizes[/tag]

SQL databases are always writable if allowed by the SQL database itselfE<nbspace>E<emdash>
in-memory databases will never be written.

The [tag flag build][/tag] and [tag flag cache][/tag] combinations available
in former versions of Interchange have been removed in conjunction with
the static page building code.

H4: {{CMD[id="tag_log"]log dir/file}}

Logs a message to a file, fully interpolated for Interchange tags.
The following tag will send every item code and description in the user's
shopping cart to the file logs/transactions.txt:

>    [tag log logs/transactions.txt]
>    [item-list][item-code]  [item-description]
>    [/item-list][/tag]

The file is relative to the catalog directory, and only may be
an absolute path name if I<NoAbsolute> is set to C<No>.

H4: {{CMD[id="tag_mime_description_string"]mime description_string}}

Returns a MIME-encapsulated message with the boundary as employed
in the other mime tags, and the C<description_string> used as the 
Content-Description. For example

>   [tag mime My Plain Text]Your message here.[/tag]

will return

>  Content-Type: TEXT/PLAIN; CHARSET=US-ASCII
>  Content-ID: [sequential, lead as in mime boundary]
>  Content-Description: My Plain Text
>
>  Your message here.

When used in concert with [tag mime boundary], [tag mime header], and
\[tag mime id], allows MIME attachments to be includedE<nbspace>E<emdash> typically with
PGP-encrypted credit card numbers. See the demo page etc/report
for an example. Adding the attribute attach_only=1 to the tag call will set the content
disposition to "attachment" (vs. inline).

H4: {{CMD[id="tag_mime_boundary"]mime boundary}}

Returns a MIME message boundary with unique string keyed on
session ID, page count, and time.

H4: {{CMD[id="tag_mime_header"]mime header}}

Returns a MIME message header with the proper boundary for that
session ID, page count, and time.

H4: {{CMD[id="tag_mime_id"]mime id}}

Returns a MIME message id with the proper boundary for that
session ID, page count, and time.

H4: {{CMD[id="tag_show_tags"]show_tags}}

The encased text will not be substituted for with Interchange tags, 
with < and [ characters changed to C<&>#lt; and C<&>#91; respectively.

>    [tag show_tags][value whatever][/tag]

H4: {{CMD[id="tag_time"]time}}

Formats the current time according to POSIX strftime arguments.
The following is the string for Thursday, April 30, 1997.

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

H4: {{CMD[id="tag_touch"]touch}}

Touches a database to allow use of the tag_data() routine in 
user-defined subroutines. If this is not done, the routine
will error out if the database has not previously been accessed
on the page.

>    [tag touch products][/tag]







# BEGIN ########### tag Subsections ##############
H4: {{CMD[id="tag_arg"]arg}}



H4: {{CMD[id="tag_op"]op}}



# END ++++++++++++ tag Subsections +++++++++++++

H2: time


H3: Summary

\Parameters: B<locale>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

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

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->time(
>        {
>         locale => VALUE,
>        },
>        BODY
>    )
>
> OR
>
>    $Tag->time($locale, $ATTRHASH, $BODY);

 

# BEGIN ############### time Summary Tables ####################
!block example;
    [B<time> locale I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#time_adjust"]adjust}}|<<
Temporarily adjust the time for display purposes.
>>|I<none>
{{CMD[jump="#time_gmt"]gmt}}|<<
Display time as GMT.
>>|I<none>
{{CMD[jump="#time_locale"]locale}}|<<
Format the time according to the named locale.
>>|I<none>
{{CMD[jump="#time_tz"]tz}}|<<
Use the passed timezone to display the time.
>>|I<none>
{{CMD[jump="#time_zerofix"]zerofix}}|<<
Strips leading zeroes from numbers.
>>|I<none>
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [time locale]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->time(  { locale => VALUE_locale
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->time(locale, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ time End Summary Tables ++++++++++++++++++++


H3: Description

Formats the current time according to POSIX strftime arguments.
The following is the string for Monday, January 1, 2001.

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

See the C<strftime> man page for information on the arguments (which are
the same as modern UNIX date commands).

Accepts the following options:

# BEGIN ########### time Subsections ##############

H4: {{CMD[id="time_adjust"]adjust}}

If you wish to temporarily adjust the time for display purposes, you can
pass an C<adjust> parameter with the number of hours (plus or minus).

>        [time]%c[/time]
>        [time adjust="-3"]%c[/time]

Will display:

> Mon 01 Jan 2001 11:29:03 AM EST
> Mon 01 Jan 2001 08:29:03 AM EST

If the number ends in zero and has 3 digits or more, it is assumed that
the number is in timezone format (i.e +500) the local time or from GMT:

>        [time]%c[/time]
>        [time adjust="-330"]%c[/time]
>        [time adjust="-300"]%c[/time]

Will display:

> Mon 01 Jan 2001 11:29:03 AM EST
> Mon 01 Jan 2001 07:59:03 AM EST
> Mon 01 Jan 2001 08:29:03 AM EST

If you want to force the number to be just a number of hours, add
the C<hours> parameter:

>        [time]%c[/time]
>        [time adjust="100" hours=1]%c[/time]

Will display:

> Mon 01 Jan 2001 11:29:03 AM EST
> Fri 05 Jan 2001 15:29:03 PM EST

If C<adjust> is an Interchange time duration with a suffix of
C<sec>, C<min>, C<hrs>, C<days>, or C<weeks>, that will be used.

>        [time]%c[/time]
>        [time adjust="2 days"]%c[/time]

Will display:

> Mon 01 Jan 2001 11:29:03 AM EST
> Wed 03 Jan 2001 11:29:03 AM EST

Note that the time zone does not changeE<nbspace>E<emdash> you should
either pick a format which doesn't display zone, use the C<tz>
parameter, or manage it yourself.

\NOTE: You can adjust time globally for an Interchange installation by
setting the $ENV{TZ} variable on many systems. Set TZ in your environment
and then restart Interchange:

>        ## bash/ksh/sh
>        TZ=PST7PDT; export TZ
>        interchange -restart
>
>        ## csh/tcsh
>        setenv TZ PST7PDT
>        interchange -restart

On most modern UNIX systems, all times will now be in the PST zone.

H4: {{CMD[id="time_gmt"]gmt}}

If you want to display time as GMT, use the C<gmt> parameter:

>        [time]%c[/time]
>        [time gmt=1]%c[/time]

will display:

>        Mon 01 Jan 2001 11:33:26 AM EST
>        Mon 01 Jan 2001 04:33:26 PM EST

Once again, the zone will not be set to GMT, so you should pick a format
string which doesn't use zone, use the C<tz> parameter, or manage it yourself.

H4: {{CMD[id="time_locale"]locale}}

Format the time according to the named C<locale>, assuming that locale is
available on your operating system. For example, the following:

>        [time locale=en_US]%B %d, %Y[/time]
>        [time locale=fr_FR]%B %d, %Y[/time]

should display:

>        January 01, 2001
>        janvier 01, 2001

H4: {{CMD[id="time_tz"]tz}}

Use the passed timezone to display the time. Will adjust for hours difference.

\Example:

>        [time tz=GMT0]
>        [time tz=CST6CDT]
>        [time tz=PST8PDT]

will display:

>        Mon 01 Jan 2001 04:43:02 PM GMT
>        Mon 01 Jan 2001 10:43:02 AM CST
>        Mon 01 Jan 2001 08:43:02 AM PST

Note that the first alphabetical string is the zone name when not under daylight
savings time, the digit is the number of hours displacement from GMT, and
the second alphabetical string is the zone name when in daylight savings
time. NOTE: This may not work on all operating systems.

H4: {{CMD[id="time_zerofix"]zerofix}}

Strips leading zeroes from numbers.


# END ++++++++++++ time Subsections +++++++++++++

H2: timed-build


H3: Summary

\Parameters: B<file>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [timed-build] FOO [/timed-build].
\Nesting: NO

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->timed_build(
>        {
>         file => VALUE,
>        },
>        BODY
>    )
>
> OR
>
>    $Tag->timed_build($file, $ATTRHASH, $BODY);

 

# BEGIN ############### timed-build Summary Tables ####################
!block example;
    [timed-build file I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#timed_build_auto"]auto}}|<<
Turn on automatic region processing.
>>|I<none>
{{CMD[jump="#timed_build_file"]file}}|<<
Name of the cache file.
>>|I<none>
{{CMD[jump="#timed_build_if"]if}}|<<
Conditional display of the cached region.
>>|I<none>
{{CMD[jump="#timed_build_minutes"]minutes}}|<<
Number of minutes after which the timed build should be repeated.
>>|60
{{CMD[jump="#timed_build_period"]period}}|<<
Alternative way of expressing time.
>>|I<none>
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [timed-build file]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->timed_build(  { file => VALUE_file
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->timed_build(file, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ timed-build End Summary Tables ++++++++++++++++++++


H3: Description


Allows you to build CPU-intensive regions of ITL tags on a timed basis.

In the simplest case, surround a region of ITL with E<lbracket>{{C[jump="#timed-build"]timed-build}}]
and C<[/timed-build]>:

>        [timed-build]
>                Built at [time]%c[/time].
>        [/timed-build]

If a C<file> parameter is not passed, saves to the directory I<timed> in
catalog root, with the file name of the current page. If the C<minutes>
parameter is not passed specifying how often the page should be rebuilt,
then it will not be rebuilt until the output file is removed.

Accepts the following parameters:

# BEGIN ########### timed-build Subsections ##############


H4: {{CMD[id="timed_build_auto"]auto}}

Turns on automatic region processing. The text of the timed-build region
is processed to determine a unique checksum or digest (using MD5), and
that file name is checked in the directory tmp/auto-timed (assuming
C<ScratchDir> is set to C<tmp>). If no number of minutes is supplied,
C<60> is assumed.

This is designed to automatically build regions of commonly used areas
without having to manage the file name yourself.

Implies C<login=1>, but will still abort if no session ID cookie has been
sent. Use C<force=1> to ignore cookie status.

H4: {{CMD[id="timed_build_file"]file}}

Name of the file to save the results in. Relative to catalog root.
The directory must exist.

H4: {{CMD[id="timed_build_if"]if}}

Allows you to to only display the cached region when the C<if> parameter
is true. For example, you can do:

>        [timed-build if="[value timed]"]
>        ITL tags....
>        [/timed-build]

The cached region will only be displayed if the variable C<timed> is set
to a non-zero, non-blank value. Otherwise, the ITL tags will be re-interpreted
every time.

H4: {{CMD[id="timed_build_minutes"]minutes}}

The number of minutes after which the timed build should be repeated.
If set to 0, it will be built once and then not rebuilt until the output
file is removed.

H4: {{CMD[id="timed_build_period"]period}}

Alternative way of expressing time. You can pass a string describing
the rebuild time period:

>        [timed-build period="4 hours"] 
>        ITL tags....
>        [/timed-build]

This is really the same as C<minutes=240>. Useful for passing seconds:

>        [timed-build period="5 seconds"] 
>        ITL tags....
>        [/timed-build]

The region will be rebuilt every 5 seconds.

Performance N<Tip:> use minutes
of .08 instead; avoids having to parse the period string.


If you have the StaticDir catalog.cfg parameter set to a writable path,
you can build a cached static version of your catalog over time. Simply
place a [timed-build] tag at the top of pages you wish to build statically.
Assuming the catalog is not busy and write lock can be obtained, the
StaticDBM database will be updated to mark the page as static and the
next time a link is made for that page the static version will be presented.



# END ++++++++++++ timed-build Subsections +++++++++++++

H2: tmp


H3: Summary

\Parameters: B<name>

Positional parameters in same order.


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

Interpolates B<container text> by default.

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

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->tmp(
>        {
>         name => VALUE,
>        },
>        BODY
>    )
>
> OR
>
>    $Tag->tmp($name, $BODY);
>
 

# BEGIN ############### tmp Summary Tables ####################
!block example;
    [B<tmp> name]value[/tmp]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#tmp_name"]name}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<Yes>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [tmp name]value[/tmp]
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->tmp(  { name => VALUE_name
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->tmp(name, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ tmp End Summary Tables ++++++++++++++++++++


H3: Description


Sets a C<Scratch> variable to the value specified in the tag body.
This is just as the
E<lbracket>{{C[jump="#seti"]seti}}] tag would do it,
except that the I<name> is added to the list of C<Scratch> keys that are to
be deleted immediately after the current page has been processed and served.
This saves session write time in many cases.

This tag interpolates automatically. (Interpolation
can be turned off with C<interpolate=0>.)
See also: E<lbracket>{{C[jump="#tmpn"]tmpn}}].

IMPORTANT NOTE: the [tmp ...][/tmp] tag is not appropriate for setting
order profiles or C<mv_click> actions. If you want to avoid that, use
a profile stored via the catalog.cfg directive C<OrderProfile>.






# BEGIN ########### tmp Subsections ##############
H4: {{CMD[id="tmp_name"]name}}



# END ++++++++++++ tmp Subsections +++++++++++++

H2: tmpn


H3: Summary

\Parameters: B<name>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

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

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->tmpn(
>        {
>         name => VALUE,
>        },
>        BODY
>    )
>
> OR
>
>    $Tag->tmpn($name, $BODY);
>
 

# BEGIN ############### tmpn Summary Tables ####################
!block example;
    [B<tmpn> name]value[/tmp]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#tmpn_name"]name}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->tmpn(  { name => VALUE_name
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->tmpn(name, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ tmpn End Summary Tables ++++++++++++++++++++


H3: Description


Equivalent to the E<lbracket>{{C[jump="#tmp"]tmp}}] tag, except that
it does not {{CMD[jump="#attr_interpolate"]interpolate}} by default.

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


# BEGIN ########### tmp Subsections ##############

H4: {{CMD[id="tmpn_name"]name}}



# END ++++++++++++ tmpn Subsections +++++++++++++


H2: total-cost


H3: Summary

\Parameters: B<name noformat>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->total_cost(
>        {
>         name => VALUE,
>         noformat => VALUE,
>        }
>    )
>
> OR
>
>    $Tag->total_cost($name, $noformat);

Attribute aliases

>            cart ==> name


 

# BEGIN ############### total-cost Summary Tables ####################
!block example;
    [total-cost name noformat]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#total_cost_name"]cart}}|<<
Alias for name
>>|DEFAULT_VALUE
{{CMD[jump="#total_cost_name"]name}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#total_cost_noformat"]noformat}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [total-cost name noformat]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->total_cost(  { name => VALUE_name
                         noformat => VALUE_noformat
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->total_cost(name,noformat, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ total-cost End Summary Tables ++++++++++++++++++++


H3: Description


Expands into the total cost of all the items in the current shopping cart,
including sales tax (if any).






# BEGIN ########### total-cost Subsections ##############
H4: {{CMD[id="total_cost_name"]name}}



H4: {{CMD[id="total_cost_noformat"]noformat}}



# END ++++++++++++ total-cost Subsections +++++++++++++

H2: tree


H3: Summary

\Parameters: B<table master subordinate start>


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

Must pass named parameter interpolate=1 to cause interpolation.

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

Invalidates cache: B<no>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->tree(
>        {
>         table => VALUE,
>         master => VALUE,
>         subordinate => VALUE,
>         start => VALUE,
>        },
>        BODY
>    )
>
> OR
>
>    $Tag->tree($table, $master, $subordinate, $start, $ATTRHASH, $BODY);

Attribute aliases

>            sub ==> subordinate


 

# BEGIN ############### tree Summary Tables ####################
!block example;
    [B<tree> table master subordinate start I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#tree_master"]master}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#tree_start"]start}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#tree_subordinate"]sub}}|<<
Alias for subordinate
>>|DEFAULT_VALUE
{{CMD[jump="#tree_subordinate"]subordinate}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#tree_table"]table}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate}}|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<no>
Container tag|I<Yes>
Has Subtags|I<No>
Nests|I<No>
!endblock


B<Tag expansion example:>

!block example
    [tree table master subordinate start]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->tree(  { master => VALUE_master
                   start => VALUE_start
                   subordinate => VALUE_subordinate
                   table => VALUE_table
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->tree(table,master,subordinate,start, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ tree End Summary Tables ++++++++++++++++++++


H3: Description

Provides iterative list capability for binary trees. It produces
hash-based rows use the same tags as E<lbracket>{{C[jump="#item-list"]item-list}}]; sets some additional
hash key entries to describe the tree and provide display control.

Works on a data set with the structure:

>    parent  child
>    99      a
>    a       b
>    a       c
>    a       d
>    a       x
>    x       y
>    x       z
>    99      m
>    99      n
>    99      o
>    o       e
>    o       f
>    o       g

Sets several keys which assist in walking and displaying the
tree.


H4: {{CMD[id="tree_key_mv_level"]mv_level}}

Level of the item. If it is in the first level, it is 0. Sublevels are
infinite (except for performance).

H4: {{CMD[id="tree_key_mv_increment"]mv_increment}}

Increment label for the item. Normally goes from 1...n, but can be changed to
A...Z or a...z in outline mode.

H4: {{CMD[id="tree_key_mv_children"]mv_children}}

If in autodetect mode, set to the number of children this branch has. If a
leaf, set to 0.

H4: {{CMD[id="tree_key_mv_spacing"]mv_spacing}}

A multiple of level times the spacing option. Useful for setting width of
spacer images.

The above sample data placed in a table named "tree" would produce:

>    a           mv_level=0, mv_increment=1, mv_children=4
>        b       mv_level=1, mv_increment=1, mv_children=0
>        c       mv_level=1, mv_increment=2, mv_children=0
>        d       mv_level=1, mv_increment=3, mv_children=0
>        x       mv_level=1, mv_increment=4, mv_children=2
>            y   mv_level=2, mv_increment=1, mv_children=0
>            z   mv_level=2, mv_increment=2, mv_children=0
>    m           mv_level=0, mv_increment=1, mv_children=0
>    n           mv_level=0, mv_increment=2, mv_children=0
>    o           mv_level=0, mv_increment=3, mv_children=3
>        e       mv_level=1, mv_increment=1, mv_children=0
>        f       mv_level=1, mv_increment=2, mv_children=0
>        g       mv_level=1, mv_increment=3, mv_children=0

from the tag call:

>        <table>
>    [tree   start=99
>            table=tree
>            master=parent
>            subordinate=child
>            autodetect=1
>            spacing=4
>            full=1]
>        <tr>
>        <td>
>        [if-item-param mv_level]
>                [item-calc]
>                        return '&nbsp' x [item-param mv_spacing];
>                [/item-calc]
>        [/if-item-param]
>        [item-param child]
>        </td>
>        <td>
>                mv_level=[item-param mv_level],
>                mv_increment=[item-param mv_increment],
>                mv_children=[item-param mv_children]
>        </td>
>        </tr>
>        [/tree]
>        </table>

Accepts the following parameters:


H4: {{CMD[id="tree_table"]table}}

Database table which contains the tree. Must be a valid Interchange
table identifier.

H4: {{CMD[id="tree_master"]master}}

The column which is used to determine the parent of the item.

H4: {{CMD[id="tree_subordinate"]subordinate}}

The child column, which determines which items are sub-items of
the current one. Used to re-query for items with its value in
C<master>.

H4: {{CMD[id="tree_start_item"]start_item}}

The first item to be followed, i.e. the C<master> value of all the top-level
items.

H4: {{CMD[id="tree_autodetect"]autodetect}}

Specifies that the next level should be followed to detect the number
of child items contained. Not recursive; only follows far enough to
determine the children of the current item.

H4: {{CMD[id="tree_full"]full}}

Specifies that all items should be followed. Essentially the same as
specifying C<memo> and passing the C<explode> variable, but not dependent
on them. Useful for building lists for inclusion in embedded Perl, among
other things.

H4: {{CMD[id="tree_stop"]stop}}

An optional C<stop> field which, when the value is true, can stop the
following of the branch.

H4: {{CMD[id="tree_continue"]continue}}

An optional C<continue> field which, when the value is true, can force
the branch to be followed.

H4: {{CMD[id="tree_sort"]sort}}

The column which should be used for ordering the itemsE<nbspace>E<emdash> determines the
order in which they will be displayed under the current parent.

H4: {{CMD[id="tree_outline"]outline}}

Sets outline mode, where C<mv_increment> will be displayed with
letter values or numeral values. If set to specifically C<1>, will
produced outline increments like:

>    1
>        A
>        B
>            1
>            2
>        C
>            1 
>            2
>                a
>                b
>                    1
>                    2
>                        a
>                        b
>    2

H4: {{CMD[id="tree_memo"]memo}}

Indicates that the collapse/explode/toggle features are to be used, and
names a C<Scratch> variable where the values should be stored.

H4: {{CMD[id="tree_collapse"]collapse}}

The name of a variable in the user's session which will determine that the
tree should be "collapsed". When collapsed, the child items will not be 
followed unless they are set to be followed with C<toggle>. Zeros all
toggles.

Requires C<memo> to be set if values are to be retained.

H4: {{CMD[id="tree_toggle"]toggle}}

The name of a variable in the user's session which will determine that the
current item should be either followed or not followed. The first time the
C<toggle> variable corresponding to its primary key is passed, the item will
be expanded. The next call will "collapse" the item.

Requires C<memo> to be set if values are to be retained.

H4: {{CMD[id="tree_explode"]explode}}

The name of a variable in the user's session which will determine that the
tree should be "exploded". When exploded, all child items are followed and 
the full tree can be displayed.

Requires C<memo> to be set if values are to be retained.

H4: {{CMD[id="tree_pedantic"]pedantic}}

When set to a true value, and an endless tree is detected (i.e. the
child branch contains a parent) then the error will be logged to the
catalog error log and the tree call will return with an error.

If C<pedantic> is not set (the default), the current leaf will be shown
but never followed. This allows partial display of the tree.

H4: {{CMD[id="tree_log_error"]log_error}}

When set to a true value, and an endless tree is detected (i.e. the
child branch contains a parent) then the error will be logged to the
catalog error log. No logging done by default.

H4: {{CMD[id="tree_show_error"]show_error}}

When set to a true value, and an endless tree is detected (i.e. the
child branch contains a parent) then the error will be returned in the
page. Errors are NOT shown by default.


In addition to the above values, all valid options for a list tag are
in force. For example, you can set a "SELECTED" value on an option list
with C<option=1>, set the tag prefix with C<prefix>, etc.



# BEGIN ########### tree Subsections ##############
H4: {{CMD[id="tree_master"]master}}



H4: {{CMD[id="tree_start"]start}}



H4: {{CMD[id="tree_subordinate"]subordinate}}



H4: {{CMD[id="tree_table"]table}}



# END ++++++++++++ tree Subsections +++++++++++++

H2: try

Allows you to trap errors. Interchange processes the body text of the E<lbracket>C<try>]E<lbracket>C</try>] block and returns it normally if it does not generate an error. If it does generate an error, Interchange executes the E<lbracket>C<catch>]E<lbracket>C</catch>] block.

See also '{{C[jump="#catch"]catch}}'.

H3: Summary

!block example;
    [B<try> label=I<my_label> I<other_named_attributes>]
        I<Body text to return if no error>
    [B</try>]
    .
    .
    .
    [B<catch> I<my_label>]
        I<Body text to return if try block caused an error>
    [B</catch>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#try_label"]label}}|<<
The label shared by the paired C<try> and {{C[jump="#catch"]catch}} blocks
>>|'default'
!endblock

!block table; colvaligns="TTT"
Attributes|Description|Default
{{CMD[jump="#try_status"]status}}|<<
Returns 0 (failed) or 1 (succeeded) instead of page output
>>|I<none>
{{CMD[jump="#try_hide"]hide}}|Suppresses page output|I<No>
{{CMD[jump="#try_clean"]clean}}|Suppress C<try> block output if it has an error|I<No>
{{CMD[jump="#attr_interpolate"]interpolate}}|<<
See {{CMD[jump="#attr_interpolate"]Interpolating Parameters}}
>>|I<No>
{{CMD[jump="#attr_reparse"]reparse}}|<<
See {{CMD[jump="#attr_reparse"]Interpolating Parameters}}
>>|I<Yes>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<No>
Container tag|I<Yes>
!endblock

B<Tag expansion example:>

!block example
    [set divisor]0[/set]
    [try label=div]
        [calc] 1 / [scratch divisor] [/calc]
    [/try]
    [catch div]Division error[/catch]
---
    Division Error
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->try(    { label  => I<'try_catch_label'>,
                    status => 1, },
                  $try_body  );

    $Tag->catch(  { label  => I<'try_catch_label'>, },
                  $catch_body )
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->try($label, $attribute_hash_reference, $try_body);
    $Tag->catch($label, $attribute_hash_reference, $catch_body);
!endblock

H4: See Also

{{C[jump="#catch"]catch}}


H3: Description

Allows you to trap errors. Interchange processes the body text of the E<lbracket>C<try>]E<lbracket>C</try>] block and returns it normally if it does not generate an error. If it does generate an error, interchange executes the E<lbracket>C<catch>]E<lbracket>C</catch>] block. The catch block executes where it is on the page (I<i.e.>, it does not replace the output of the try block).

Note that the C<catch> block must occur after the [try] block in the document.

H4: {{CMD[id="try_label"]label}}

The try and catch blocks are matched by this label.

Technical N<note:>

The try tag will also place a result in the $Session object.  For example, the following returns the 'Illegal division by zero...' error message if it N<occurs:>

!block example
    [try label=divide][calc] 1 / [scratch divisor] [/calc][/try]

    [catch divide]
        [calc]$Session->{try}{divide}[/calc]
    [/catch]
!endblock

The $Session->{try}{divide} object will be set to the empty string ('') if there was no error, or it will contain the error message if there was an error.

The E<lbracket>{{C[jump="#perl"]perl}}] and E<lbracket>{{C[jump="#calc"]calc}}] tags also set $Session->{try}->{I<active_label>} on errors.


H4: {{CMD[id="try_status"]status}}

Suppresses C<try> block output and returns 1 if no error or 0 if an error occurred instead.  Executes the C<catch> block as usual in case of an error.

H4: {{CMD[id="try_hide"]hide}}

Suppresses C<try> block output (regardless of success or failure).  Executes the C<catch> block as usual in case of an error.


H4: {{CMD[id="try_clean"]clean}}

Setting 'C<clean=1>' will cause the C<try> block to suppress its output only if it has an error. Otherwise (C<clean=0> or not set), the C<try> block will return whatever partial output it has completed before the error.  The {{C[jump="#catch"]catch}} block will work as usual.



H2: update

Forces an update of the specified interchange function. Function may be one of the N<following:>
* B<cart> (updates current or named cart)
* B<process> (updates order or search)
* B<values> (updates user-entered fields)
* B<data> (updates database, using current B<mv_> CGI form variables)

H3: Summary

!block example;
    [B<update> function]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#update_function"]function}}|<<
* cart
** Updates current or named cart (see C<name> attribute)

* process
** Updates an order or a search page

* values
** Updates user-entered fields

* data
** Updates database, using current B<mv_> CGI form variables, for N<example:>
*** B<mv_data_table> Table to update
*** B<mv_data_key> Key into table
*** B<mv_data_fields> Fields to update (space or null delimited)
*** B<mv_data_function> One of the N<following:>
**** delete
**** update
**** insert
**** delete
*** etc.
>>|DEFAULT_VALUE
{{CMD[jump="#update_name"]name}}|<<
Cart name to update (if 'function=cart')
* N<Default:> current cart
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [update function]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->update(  { function => VALUE_function
}, $body  );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->update(function, $attribute_hash_reference, $body);
!endblock

H3: Description

Forces an update of the specified interchange function. Function may be one of the N<following:>
* B<cart> (updates current or named cart)
* B<process> (updates order or search)
* B<values> (updates user-entered fields)
* B<data> (updates database, using current B<mv_> CGI form variables)



# BEGIN ############ update Subsections ##############
H4: {{CMD[id="update_function"]function}}

* cart
** Updates current or named cart (see C<name> attribute)

* process
** Updates an order or a search page

* values
** Updates user-entered fields

* data
** Updates database, using current B<mv_> CGI form variables, for N<example:>
*** B<mv_data_table> Table to update
*** B<mv_data_key> Key into table
*** B<mv_data_fields> Fields to update (space or null delimited)
*** B<mv_data_function> One of the N<following:>
**** delete
**** update
**** insert
**** delete
*** etc.


H4: {{CMD[id="update_name"]name}}

Cart name to update (if 'function=cart')
* N<Default:> current cart


# END +++++++++++++ update Subsections ++++++++++++

H2: userdb


H3: Summary

\Parameters: B<function>

Positional parameters in same order.


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

Invalidates cache: B<YES>

Attribute aliases

>            name ==> nickname
>            table ==> db


 

# BEGIN ############### userdb Summary Tables ####################
!block example;
    [B<userdb> function I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#userdb_function"]function}}|<<
>>|DEFAULT_VALUE
{{CMD[jump="#userdb_nickname"]name}}|<<
Alias for nickname
>>|DEFAULT_VALUE
{{CMD[jump="#userdb_db"]table}}|<<
Alias for db
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [userdb function]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->userdb({
       function => VALUE
   });
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->userdb(function, $attribute_hash_reference);
!endblock

# END +++++++++++++++ userdb End Summary Tables ++++++++++++++++++++


H3: Description


Interchange provides a C<[userdb ...]> tag to access the UserDB functions.

>    [userdb
>        function=function_name
>        username="username"*
>        password="password"*
>        verify="password"*
>        oldpass="old password"*
>        shipping="fields for shipping save"
>        billing="fields for billing save"
>        preferences="fields for preferences save"
>        force_lower=1
>        param1=value*
>        param2=value*
>        hide=1
>        show=1
>        ...
>    ]

\* Optional

It is normally called in an C<mv_click> or C<mv_check> setting, as in:

>    [set Login]
>    mv_todo=return
>    mv_nextpage=welcome
>    [userdb function=login]
>    [/set]
>
>    <FORM ACTION="[process]" METHOD=POST>
>    <INPUT TYPE=hidden NAME=mv_click VALUE=Login>
>    Username <INPUT NAME=mv_username SIZE=10>
>    Password <INPUT NAME=mv_password SIZE=10>
>    </FORM>

There are several global parameters that apply to any use of
the C<userdb> functions. Most importantly, by default the database
table is set to be I<userdb>. If you must use another table name,
then you should include a C<database=table> parameter with any
call to C<userdb>. The global parameters (default in parentheses):

>    database     Sets user database table (userdb)
>    hide         Hide the return value of certain functions
>                 (including login, new_account, save, load)
>    show         Show the return value of certain functions
>                 or the error message, if any (0)
>    force_lower  Force possibly upper-case database fields
>                 to lower case session variable names (0)
>    billing      Set the billing fields (see Accounts)
>    shipping     Set the shipping fields (see Address Book)
>    preferences  Set the preferences fields (see Preferences)
>    bill_field   Set field name for accounts (accounts)
>    addr_field   Set field name for address book (address_book)
>    pref_field   Set field name for preferences (preferences)
>    cart_field   Set field name for cart storage (carts)
>    pass_field   Set field name for password (password)
>    time_field   Set field for storing last login time (time)
>    expire_field Set field for expiration date (expire_date)
>    acl          Set field for simple access control storage (acl)
>    file_acl     Set field for file access control storage (file_acl)
>    db_acl       Set field for database access control storage (db_acl)




# BEGIN ########### userdb Subsections ##############
H4: {{CMD[id="userdb_function"]function}}

H4: {{CMD[id="userdb_nickname"]name}}

H4: {{CMD[id="userdb_db"]table}}



# END ++++++++++++ userdb Subsections +++++++++++++

H2: value

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

Can also set a new value within the current page.


H3: Summary

!block example;
    [B<value> name]
    [B<value> name=I<form_var_name> I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#value_name"]name}}|<<
This is the name of the form variable whose value you want.
>>|I<None>
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#value_set"]set}}|I<none>
{{CMD[jump="#value_hide"]hide}}|I<No>
{{CMD[jump="#value_filter"]filter}}|I<none>
{{CMD[jump="#value_keep"]keep}} (with filter)|I<No>
{{CMD[jump="#value_scratch"]scratch}}|I<No>
{{CMD[jump="#value_default"]default}}|I<none>
{{CMD[jump="#value_enable_html"]enable_html}}|I<No>
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<Yes>
!endblock

B<Tag expansion example:>

Assuming form variable 'foo' = 'bar',

!block example
    [value foo]
---
    bar
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->value( { name => var_name } );

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

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->value($name, $attribute_hash_reference);
!endblock


H3: Description

Usage example:

>   <INPUT TYPE="text" NAME="name" VALUE="[value name]">
>   <INPUT TYPE="text" NAME="name" VALUE="[value name=name]">

Expands into the current value of the {{C[jump="#value_name"]named}}
customer/form input field. When the value is returned, any Interchange
tags present in the value will be escaped. This prevents users from
entering Interchange tags in form values, which would be a serious
security risk.


H4: {{CMD[id="value_name"]name}}

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


H4: {{CMD[id="value_set"]set}}

You can change a value with 'C<set>=I<new_value>'. The tag will return
the value you set unless you also set the
{{CMD[jump="#value_hide"]hide}}=1 attribute.

Use this to "uncheck" a checkbox or set other form variable values to
defaults. If you simply want a place to store your own data, use the
{{C[jump="#set"]set}} and {{C[jump="#scratch"]scratch}} tags
instead.

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


H4: {{CMD[id="value_hide"]hide}}

Setting C<hide>=1 suppresses the tag's return value, which can be
useful with the {{C[jump="#value_set"]set}} attribute.


H4: {{CMD[id="value_filter"]filter}}

See the {{C[jump="#filter"]filter}} tag for a list of filters.

Setting 'C<filter>="I<filter>"' modifies the named value with the specified
filter.


H4: {{CMD[id="value_keep"]keep}} (with filter)

Set C<keep>=1 if you want the tag to return a filtered result but do
not want the filter to modify the form value itself in the $::Values
hash.


H4: {{CMD[id="value_scratch"]scratch}}

Setting 'C<scratch>=1' places a copy of the value in the $::Scratch
hash. An illustrative N<example:>

!block example
   foo is [value name=foo scratch=1] in the Values hash
   foo is now also [scratch foo] in the Scratch hash
!endblock


H4: {{CMD[id="value_default"]default}}

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

!block example
    [value name=myname set=0 hide=1]
    [value name=myname default="Using default"]
!endblock


H4: {{CMD[id="value_enable_html"]enable_html}}

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


H2: value-extended


H3: Summary

\Parameters: B<name>

Positional parameters in same order.


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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: B<YES>

Called Routine: 

B<ASP-like Perl call:>

>    $Tag->value_extended(
>        {
>         name => VALUE,
>        }
>    )
>
> OR
>
>    $Tag->value_extended($name, $ATTRHASH);



# BEGIN ############### value-extended Summary Tables ####################
!block example;
    [value-extended name I<other_named_attributes>]
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#value_extended_name"]name}}|<<
>>|DEFAULT_VALUE
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#value_extended_umask"]umask}}|I<none>
{{CMD[jump="#attr_interpolate"]interpolate (reparse)}}|I<No>
!endblock

!block table; headings=1; colvaligns="TT"
A|B
Other_Characteristics|
Invalidates cache|I<YES>
Container tag|I<No>
Has Subtags|I<No>
Nests|I<Yes>
!endblock


B<Tag expansion example:>

!block example
    [value-extended name]
---
    TODO: (tag result)
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
   $Tag->value_extended( { name => VALUE_name }, $body );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->value_extended(name, $attribute_hash_reference, $body);
!endblock

# END +++++++++++++++ value-extended End Summary Tables ++++++++++++++++++++



H3: Description


Named call example:

>   [value-extended 
>            name=formfield
>            outfile=filename*
>            umask=octal*
>            ascii=1*
>            yes="Yes"*
>            no="No"*
>            joiner="char|string"*
>            test="isfile|length|defined"*
>            index="N|N..N|*"
>            file_contents=1*
>            maxsize=length*
>            elements=1*
>   ]

Expands into the current value of the customer/form input field named
by field. If there are multiple elements of that variable, it will return
the value at C<index>; by default all joined together with a space.

If the variable is a file variable coming from a multipart/form-data
file upload, then the contents of that upload can be returned to the 
page or optionally written to the C<outfile>.

# BEGIN ########### value-extended Subsections ##############

H4: {{CMD[id="value_extended_name"]name}}

Specify which value variable to deal with. If no other parameters are
present, then the value of the variable will be returned. If there are
multiple elements, then by default they will all be returned joined by
a space. If C<joiner> is present, then they will be joined by its value.

In the special case of a file upload, the value returned is the name
of the file as passed for upload.

H4: {{CMD[id="value_extended_joiner"]joiner}}

The character or string that will join the elements of the array. Will
accept string literals such as "\n" or "\r".

H4: {{CMD[id="value_extended_test"]test}}

Three tests: C<isfile> returns true if the variable is a file upload.
C<length> returns the length. C<defined> returns whether the value
has ever been set at all on a form.

H4: {{CMD[id="value_extended_index"]index}}

The index of the element to return if not all are wanted. This is
useful especially for pre-setting multiple search variables. If set
to C<*>, will return all (joined by C<joiner>). If a range, such
as C<0 .. 2>, will return multiple elements.

H4: {{CMD[id="value_extended_file_contents"]file_contents}}

Returns the contents of a file upload if set to a non-blank, non-zero value.
If the variable is not a file, returns nothing.

H4: {{CMD[id="value_extended_maxsize"]maxsize}}

The maximum file size allowed, in bytes. If a file of greater size than
maxsize is uploaded, the tag will return false and an error will be logged.

H4: {{CMD[id="value_extended_outfile"]outfile}}

Names a file to write the contents of a file upload to. It will not
accept an absolute file name; the name must be relative to the catalog
directory. If you wish to write images or other files that would go to
HTML space, you must use the HTTP server's C<Alias> facilities or 
make a symbolic link.

H4: {{CMD[id="value_extended_umask"]umask}}

Permission mask (in octal) to apply to the uploaded file's permission bits.
You may want to set this to make a file world-readable, or to keep it from
being group-readable. See the UNIX chmod(1) manpage for details.

H4: {{CMD[id="value_extended_ascii"]ascii}}

To do an auto-ASCII translation before writing the C<outfile>, set
the C<ascii> parameter to a non-blank, non-zero value. Default is no
translation.

H4: {{CMD[id="value_extended_yes"]yes}}

The value that will be returned if a test is true or a file is
written successfully. Defaults to C<1> for tests and the empty
string for uploads.

H4: {{CMD[id="value_extended_no"]no}}

The value that will be returned if a test is false or a file write
fails. Defaults to the empty string.

# END ++++++++++++ value-extended Subsections +++++++++++++



H1: User-defined Tags

To define a tag that is catalog-specific, place I<UserTag> directives in
your catalog.cfg file. For server-wide tags, define them in interchange.cfg.
Catalog-specific tags take precedence if both are definedE<nbspace>E<emdash> in fact,
you can override the base Interchange tag set with them. The directive
takes the form:

>   UserTag  tagname  property  value

where C<tagname> is the name of the tag, C<property> is the attribute
(described below), and C<value> is the value of the property for that
tagname.

The user tags can either be based on Perl subroutines or just be
aliases for existing tags. Some quick examples are below.

An alias:

>    UserTag product_name Alias     data products title

This will change [product_name 99-102] into [data products title 99-102],
which will output the C<title> database field for product code C<99-102>.
Don't use this with C<[item-data ...]> and C<[item-field ...]>, as they
are parsed separately. You can do C<[product-name [item-code]]>, though.

A simple subroutine:

>    UserTag company_name Routine   sub { "Your company name" }

When you place a [company-name] tag in an Interchange page, the text 
C<Your company name> will be substituted.

A subroutine with a passed text as an argument:

>    UserTag caps   Routine   sub { return "\U@_" }
>    UserTag caps   HasEndTag 

The tag [caps]This text should be all upper case[/caps] will become
C<THIS TEXT SHOULD BE ALL UPPER CASE>.

Here is a useful one you might wish to use:

>    UserTag quick_table HasEndTag
>    UserTag quick_table Interpolate
>    UserTag quick_table Order   border
>    UserTag quick_table Routine <<EOF
>    sub {
>        my ($border,$input) = @_;
>        $border = " BORDER=$border" if $border;
>        my $out = "<TABLE ALIGN=LEFT$border>";
>        my @rows = split /\n+/, $input;
>        my ($left, $right);
>        for(@rows) {
>            $out .= '<TR><TD ALIGN=RIGHT VALIGN=TOP>';
>            ($left, $right) = split /\s*:\s*/, $_, 2;
>            $out .= '<B>' unless $left =~ /</;
>            $out .= $left;
>            $out .= '</B>' unless $left =~ /</;
>            $out .= '</TD><TD VALIGN=TOP>';
>            $out .= $right;
>            $out .= '</TD></TR>';
>            $out .= "\n";
>        }
>        $out .= '</TABLE>';
>    }
>    EOF

Called with:

>    [quick-table border=2]
>    Name: [value name]
>    City: [value city][if value state], [value state][/if] [value country]
>    [/quick_table]

As is the case with E<lbracket>{{C[jump="#perl"]perl}}] tag, user tags
run under the Perl {{CMD[jump="http://www.perl.com/pub/doc/manual/html/lib/Safe.html"]Safe.pm}} module with warnings disabled. Unlike
E<lbracket>{{C[jump="#perl"]perl}}] tags, however, user tags use Perl's 'C<strict>' pragma.


The properties for UserTag are:



H2: Alias

An alias for an existing (or other user-defined) tag. It takes the
form:

>    UserTag tagname Alias    tag to insert

An Alias is the only property that does not require a I<Routine>
to process the tag.

H2: attrAlias

An alias for an existing attribute for defined tag. It takes the
form:

>    UserTag tagname attrAlias   alias attr

As an example, the standard Interchange C<value> tag takes a named
attribute of C<name> for the variable name, meaning that E<lbracket>{{C[jump="#value"]value}} name=var]
will display the value of form field C<var>. If you put this line
in catalog.cfg:

>    UserTag value attrAlias   identifier name

then E<lbracket>{{C[jump="#value"]value}} identifier=var] will be an equivalent tag.

H2: CanNest

Notifies Interchange that this tag must be checked for nesting.
Only applies to tags that have I<HasEndTag> defined, of course.
\NOTE: Your routine must handle the subtleties of nesting, so
don't use this unless you are quite conversant with parsing
routines. See the routines C<tag_loop_list> and C<tag_if> in 
lib/Vend/Interpolate.pm for an example of a nesting tag.

>    UserTag tagname CanNest

H2: HasEndTag

Defines an ending [/tag] to encapsulate your textE<nbspace>E<emdash> the text in
between the beginning C<[tagname]> and ending C<[/tagname]> will
be the last argument sent to the defined subroutine.

>    UserTag tagname HasEndTag

H2: Implicit

This defines a tag as implicit, meaning it can just be an C<attribute> 
instead of an C<attribute=value> pair. It must be a recognized attribute
in the tag definition, or there will be big problems. Use this with caution!

>    UserTag tagname Implicit attribute value

If you want to set a standard include file to a fixed value by default,
but don't want to have to specify E<lbracket>{{C[jump="#include"]include}} file="/long/path/to/file"]
every time, you can just put:

>    UserTag include Implicit file file=/long/path/to/file

and E<lbracket>{{C[jump="#include"]include}} file] will be the equivalent. You can still specify
another value with E<lbracket>{{C[jump="#include"]include}} file="/another/path/to/file"].

H2: Interpolate

The behavior for this attribute depends on whether the tag is a container
(i.e. C<HasEndTag> is defined). If it is not a container, the C<Interpolate>
attribute causes the B<the resulting HTML> from the C<UserTag> to be
re-parsed for more Interchange tags. If it is a container, C<Interpolate>
causes the contents of the tag to be parsed B<before> the tag routine
is run.

>    UserTag tagname Interpolate

H2: InvalidateCache

If this is defined, the presence of the tag on a page will prevent
search cache, page cache, and static builds from operating on the
page.

>    UserTag tagname InvalidateCache

It does not override [tag flag build][/tag], though.

H2: Order

The optional arguments that can be sent to the tag. This defines not only
the order in which they will be passed to I<Routine>, but the name of
the tags. If encapsulated text is appropriate (I<HasEndTag> is set),
it will be the last argument.

>    UserTag tagname Order param1 param2

H2: PosRoutine

Identical to the Routine argumentE<nbspace>E<emdash> a subroutine that will be called when
the new syntax is not used for the call, i.e. C<[usertag argument]> instead
of C<[usertag ARG=argument]>. If not defined, I<Routine> is used, and Interchange
will usually do the right thing.

H2: Routine

An inline subroutine that will be used to process the arguments of the tag. It
must not be named, and will be allowed to access unsafe elements only if
the C<interchange.cfg> parameter I<AllowGlobal> is set for the catalog.

>    UserTag tagname Routine  sub { "your perl code here!" }

The routine may use a "here" document for readability:

>    UserTag tagname Routine <<EOF
>    sub {
>        my ($param1, $param2, $text) = @_;
>        return "Parameter 1 is $param1, Parameter 2 is $param2";
>    }
>    EOF

The usual I<here documents> caveats apply.

Parameters defined with the I<Order> property will be sent to the routine
first, followed by any encapsulated text (I<HasEndTag> is set).


Note that the UserTag facility, combined with AllowGlobal, allows the
user to define tags just as powerful as the standard Interchange tags.
This is not recommended for the novice, thoughE<nbspace>E<emdash> keep it simple. 8-)


H1: Standard Usertags

The distribution includes a number of prebuilt usertags in the C<usertag>
directory in the Interchange software directory. Some of these are used
by the foundation catalog or its administrative interface.


H2: bar_button

Displays content based on current page. Could be used for building e.g. menu bars.

H3: Summary

!block example;
    [B<bar-button> page current]...[selected]...[/selected][/bar-button]
    [B<bar-button> page=page current=current-page]...[selected]...[/selected][/bar-button]
!endblock

!block note; label="Positional parameters: "
The first line shows the usage with positional parameters (given in
order). The second line shows usage with named parameters.
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#bar_button_page"]page}}|Name of page for which this bar-button is defined|I<none>
{{CMD[jump="#bar_button_current"]current}}|Name of the current page|Current page: MV_PAGE
!endblock

!block table;headings=1
A|B
Other_Characteristics|
Invalidates cache|I<No>
Macro|I<No>
Has end tag|[/bar-button]
!endblock

B<Tag expansion example:>

To build a simple '3-button' menu bar one could put the following on
each of the pages. The results of this code for page2 are shown below.

!block example
        <table><tr>
        [bar-button page=page1]
        <TD><A HREF="[area page1]">PAGE-1</A></TD>
        [selected]
        <TD bgcolor="red"><A HREF="[area page1]"><B>PAGE-1-selected</B></A></TD>
        [/selected]
        [/bar-button]
        [bar-button page=page2]
        <TD><A HREF="[area page2]">PAGE-2</A></TD>
        [selected]
        <TD bgcolor="red"><A HREF="[area page2]"><B>PAGE-2-selected</B></A></TD>
        [/selected]
        [/bar-button]
        [bar-button page=page3]
        <TD><A HREF="[area page3]">PAGE-3</A></TD>
        [selected]
        <TD bgcolor="red"><A HREF="[area page3]"><B>PAGE-3-selected</B></A></TD>
        [/selected]
        [/bar-button]
        </tr></table>
---
        PAGE-1    PAGE-2-selected    PAGE-3
!endblock


B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->button_bar(  { page => $page,
                     current  => $current, 
                         body => $body}  );
!endblock

or similarly,

!block example; lang="Perl"
    $Tag->area($page, $current, $body);
!endblock


H4: See Also

bar_link routine


H3: Description

Displays content based on current page. The content between the
E<lbracket>selected][/selected] tags will be displayed only if the name
of the current page matches the name that was passed to the page parameter
(page=page-name). The default content will be displayed when there is
no match.

H4: {{CMD[id="bar_button_page"]page}}

The name of the page for which this definition of the bar-button 
is defined.

H4: {{CMD[id="bar_button_current"]current}}

The name of the current page. Defaults to current page MV_PAGE.


H2: button


H2: convert_date

This tag converts a given date format into another format.

H3: Summary

!block example;
    [B<convert_date> day* I<other_named_attributes>[/convert_date]
    [B<convert_date> day=n* I<other_named_attributes>[/convert_date]
!endblock

!block note; label="Positional parameters: "
The first line shows the usage with positional parameters (given in
order). The second line shows usage with named parameters.
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
days|The number of days from or before today|I<none>
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#convert_date_format"]format}}|'%d-%b-%Y %I:%M%p' or '%d-%b-%Y'
fmt - Alias for format|I<none>
{{CMD[jump="#convert_date_raw"]raw}}|I<none>
{{CMD[jump="#convert_date_zerofix"]zerofix}}|I<none>
!endblock

!block table;headings=1
A|B
Other_Characteristics|
Invalidates cache|I<No>
Macro|I<No>
Has end tag|[/convert_date]
!endblock

B<Tag expansion example:>

!block example
  a. [convert-date][/convert-date]
  b. [convert-date 1][/convert-date]
  c. [convert-date -1][/convert-date]
  d. [convert-date]2001-5-1[/convert-date]
  e. [convert-date]2001-05-01[/convert-date]
  f. [convert-date]20010515[/convert-date]
  g. [convert-date raw=1]2001-05-18[/convert-date]
  h. [convert-date fmt="%d-%m-%Y"]2001-05-18[/convert-date]
  i. [convert-date]200 1 -  --051 =9[/convert-date]
  j. [convert-date]2001 -  --05 -20 11 1 5[/convert-date]
  k. [convert-date raw=1]2001-05-21 11:15[/convert-date]
---
  a. 18-May-2001 03:15AM (todays day and time)
  b. 19-May-2001 03:15AM (today + 1 day)
  c. 17-May-2001 03:15AM (today - 1 day)
  d. 01-May-2001
  e. 01-May-2001
  f. 15-May-2001
  g. 20010518
  h. 18-05-2001
  i. 19-May-2001
  j. 20-May-2001 11:15AM
  k. 200105211115
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->convert_date( { days => 1 } );
                                           
    $Tag->convert_date( { body => "2001-05-19 15:35",
                       format => "%d-%m-%Y %H:%M", } );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->convert_date( 1 );
!endblock

H3: Description

This tag converts almost any given date format into another, 
possibly user defined, format.

H4: {{CMD[id="convert_date_days"]days}}

Number of days from or before today's date and time. Will only be 
used if nothing is supplied between the tags.

H4: {{CMD[id="convert_date_format"]format}}

POSIX time format string of your choice. See Unix strftime(3) manpage
for complete details.

H4: {{CMD[id="convert_date_raw"]raw}}

If this option is set to true, will display given date in raw 
format, e.g. yyyymmdd or yyyymmddHHMM.

H4: {{CMD[id="convert_date_zerofix"]zerofix}}

Strips leading zeroes from numbers.


H2: db_date

This tag returns the time of last access of the database source file. 

H3: Summary

!block example;
    [B<db_date> table* format*]
!endblock

!block note; label="Positional parameters: "
The first line shows the usage with positional parameters (given in
order). The second line shows usage with named parameters.
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#db_date_table"]table}}|Table name.|products
{{CMD[jump="#db_date_format"]format}}|POSIX time format string|%A %d %b %Y
!endblock

!block table;headings=1
A|B
Other_Characteristics|
Invalidates cache|I<No>
Macro|I<No>
Has end tag|I<No>
!endblock

B<Tag expansion example:>

!block example
    [db-date]
    [db-date cat]
    [db-date table=cat format="%d %b %Y"]
---
    Wednesday 02 May 2001 (products.txt)
    Wednesday 03 May 2001 (cat.txt)
    03 May 2001 (cat.txt)
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->db_date( { table => cat,
                    format => "%d %b %Y", } );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->db_date( "cat", "%d %b %Y" );
!endblock

H3: Description

This tag returns the time of last access of the database source file. 

H4: {{CMD[id="db_date_table"]table}}

Table name. Defaults to products if not specified.

H4: {{CMD[id="db_date_format"]format}}

POSIX time format string. See Unix strftime(3) manpage for details.
Defaults to '%A %d %b %Y' when not specified.


H2: delete_cart

This tag deletes a cart from the userdb.

H3: Summary

!block example;
    [B<delete_cart> nickname]
    [B<delete_cart> nickname="cart-name"]
!endblock

!block note; label="Positional parameters: "
The first line shows the usage with positional parameters (given in
order). The second line shows usage with named parameters.
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#delete_cart_nickname"]nickname}}|Must be an existing nickname|I<none>
!endblock

!block table;headings=1
A|B
Other_Characteristics|
Invalidates cache|I<No>
Macro|I<No>
Has end tag|I<No>
!endblock

B<Tag expansion example:>

!block example
    [delete_cart mycart]
    [delete_cart nickname="mycart"]
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->delete_cart( { nickname => "mycart", } );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->delete_cart( "mycart" );
!endblock

H4: See Also

{{CMD[jump="#userdb"]userdb}}, {{CMD[jump="#load_cart"]load_cart}}, 
{{CMD[jump="#save_cart"]save_cart}} and pages templates/components/saved_carts_list_small,
pages/saved_carts.html for more examples.

H3: Description

Deletes a cart with name nickname from the user database. Basically 
the same as E<lbracket>userdb function=delete_cart nickname=mycart].

H4: {{CMD[id="delete_cart_nickname"]nickname}}

Nickname of cart to be deleted.


H2: email

This tag takes a recipient address and a body text and uses the 
SendmailProgram with -t option to send email.

H3: Summary

!block example;
    [B<email> to subject* reply* from* extra*]Your message[/email]
    [B<email> to=to_address subject=subject reply=reply_address 
        from=from_address extra=extra_headers]Your message[/email]
!endblock

!block note; label="Positional parameters: "
The first line shows the usage with positional parameters (given in
order). The second line shows usage with named parameters.
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
to|Email address of recipient|I<none>
subject|Subject line|String: <no subject>
reply|Email address to be used for the reply-to header|I<none>
from|Senders email address|First address in MailOrderTo configuration variable
extra|Additional headers to be included|I<none>
!endblock

!block table;headings=1
A|B
Other_Characteristics|
Invalidates cache|I<No>
Macro|I<No>
Has end tag|[/email]
!endblock

B<Tag expansion example:>

!block example
    [email
           to="foo@bar.com"
      subject="Greetings"
         from="bar@foo.com"
    ]
    Hello World
    [/email]
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->email(  { to => $to,
                  from => $from, 
               subject => $subject,
                 reply => $reply,
                 extra => $extra,
                  body => $body }  );
!endblock

or similarly,

!block example; lang="Perl"
    $Tag->email($to, $subject, $reply, $from, $extra, $body);
!endblock

H4: See Also

{{CMD[jump="#email_raw"]email_raw}} and
etc/mail_receipt, pages/process_return.html, pages/stock-alert-added.html for examples.

H3: Description

Will send the content between the E<lbracket>email][/email] tags as 
an email to the recipient (to) using the SendmailProgram with -t option.

H4: extra

Extra headers to be included. Example:
Errors-To: errors@yourdomain.com 

H4: from

Email address identifying the sender of the message. Will use the 
first email address of the MailOrderTo configuration variable if 
it is not supplied.

H4: reply

Email address to be used for the Reply-to header. No Reply-to header 
will be present if this parameter is omitted.

H4: subject

Short text describing the content of the message. The Subject line of an email message.
The string <no subject> will be substituted if this parameter is omitted.

H4: to

Valid email address(es) of the recipient(s). This parameter is required.


H2: email_raw

This tag takes a raw email message, B<including headers>, and
uses the SendmailProgram with -t option.

H3: Summary

!block example;
    [B<email_raw>]Your message including headers[/email_raw]
!endblock

!block table;headings=1
A|B
Other_Characteristics|
Invalidates cache|I<No>
Macro|I<No>
Has end tag|[/email_raw]
!endblock

B<Tag expansion example:>

!block example
    [email_raw]
From: foo@bar.com
To: bar@foo.com
Subject: baz

The text of the message.
    [/email_raw]
!endblock

The headers must be at the beginning of the line, and the header
must have a valid To: or it will not be delivered.

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->email_raw(  { body => $body }  );
!endblock

or similarly,

!block example; lang="Perl"
    $Tag->email_raw($body);
!endblock

H4: See Also

{{CMD[jump="#email"]email}}

H3: Description

Will send the content between the E<lbracket>email_raw][/email_raw] 
tags as a raw email message to the recipient specified in the supplied 
headers using the SendmailProgram with -t option.


H2: fedex_query


H2: formel


H2: fortune

This tag uses the {{EX:fortune(1)}} command to display a random saying.

!block example
Options:

        short=yes|no* Select only short (< 160 chars) fortunes
        a=1           Select from all fortunes, even potentially offensive ones.
        o=1           Select only from potentially offensive fortunes.
        raw=1         Don't do any HTML formatting

Example:

        [fortune short=yes]

!endblock

H2: get-url

Fetch a URL and return the contents.

H3: Summary

!block example;
    [B<get-url> url]
    [B<get-url> url="valid-url" strip=1*]
!endblock

!block note; label="Positional parameters: "
The first line shows the usage with positional parameters (given in
order). The second line shows usage with named parameters.
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#get_url_url"]url}}|<<
Must be a valid URL. Meaning, you have to supply the protocol.  Example 
** http://demo.icdevgroup.org/
** ftp://ftp.icdevgroup.org/
>>|I<none>
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#get_url_strip"]strip}}|I<none>
!endblock

!block table;headings=1
A|B
Other_Characteristics|
Invalidates cache|I<No>
Macro|I<No>
Has end tag|I<No>
!endblock

B<Tag expansion example:>

!block example
    [get-url http://demo.icdevgroup.org/]
    [get-url url="http://demo.icdevgroup.org/" strip=1]
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->get_url( { url => "http://demo.icdevgroup.org/", } );
                                           
    $Tag->get_url( { url => "http://demo.icdevgroup.org/",
                   strip => 1, } );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->get_url( "http://demo.icdevgroup.org/" );
!endblock

H3: Description

Uses the LWP libraries (LWP::Simple) to fetch a URL and returns
the contents.

H4: {{CMD[id="get_url_strip"]strip}}

If the strip option is set, strips everything up 
to E<lt>body> and everything after E<lt>/body>.

H4: {{CMD[id="get_url_url"]url}}

Must be a valid URL (including protocol).



H2: load_cart

This tag loads a cart by name from the userdb.

H3: Summary

!block example;
    [B<load_cart> nickname]
    [B<load_cart> nickname="cart-name"]
!endblock

!block note; label="Positional parameters: "
The first line shows the usage with positional parameters (given in
order). The second line shows usage with named parameters.
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#load_cart_nickname"]nickname}}|<<
Must be an existing nickname.
. Nickname is constructed from:
** a name part
** time modified (time the cart was saved by save_cart tag)
** type (c for cart, r for recurring) 
>>|I<none>
!endblock

!block table;headings=1
A|B
Other_Characteristics|
Invalidates cache|I<No>
Macro|I<No>
Has end tag|I<No>
!endblock

B<Tag expansion example:>

!block example
    [load_cart mycart:990102732:c]
    [load_cart nickname="mycart:990102732:c"]
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->load_cart( { nickname => "mycart:990102732:c", } );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->load_cart( "mycart:990102732:c" );
!endblock

H4: See Also

{{CMD[jump="#userdb"]userdb}}, {{CMD[jump="#delete_cart"]delete_cart}}, 
{{CMD[jump="#save_cart"]save_cart}} and pages templates/components/saved_carts_list_small,
pages/saved_carts.html for more examples.

H3: Description

Loads a cart with name nickname from the user database. It will 
be merged with the current cart. Basically the same as
E<lbracket>userdb function=get_cart nickname=cartname merge=1].

H4: {{CMD[id="load_cart_nickname"]nickname}}

Nickname of cart to be loaded. See above.



H2: loc


H2: rand


H2: reconfig


H2: reconfig_time


H2: reconfig_wait


H2: save_cart

This tag saves the current cart or recurring order in the userdb under
a given name.

H3: Summary

!block example;
    [B<save_cart> nickname recurring]
    [B<save_cart> nickname="cart-name" recurring=1]
!endblock

!block note; label="Positional parameters: "
The first line shows the usage with positional parameters (given in
order). The second line shows usage with named parameters.
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#save_cart_nickname"]nickname}}|Label for the cart.|I<none>
{{CMD[jump="#save_cart_recurring"]recurring}}|Set to true if recurring. Set to false, or omit if cart.|I<none>
!endblock

!block table;headings=1
A|B
Other_Characteristics|
Invalidates cache|I<No>
Macro|I<No>
Has end tag|I<No>
!endblock

B<Tag expansion example:>

!block example
    [save_cart mycart]
    [save_cart nickname=mycart recurring=1]
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->save_cart( { nickname => mycart,
                      recurring => 1, } );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->save_cart( "mycart", "1" );
!endblock

H4: See Also

{{CMD[jump="#userdb"]userdb}}, {{CMD[jump="#delete_cart"]delete_cart}}, 
{{CMD[jump="#load_cart"]load_cart}} and pages templates/components/saved_carts_list_small,
pages/saved_carts.html for more examples.

H3: Description

Saves the current cart with name nickname in the user database. Basically 
the same as E<lbracket>userdb function=set_cart nickname=cartname]

H4: {{CMD[id="save_cart_nickname"]nickname}}

Nickname for the current cart to be saved. You can use same nickname for 
different carts. An index will be added if there are more carts 
with the same nickname.  

H4: {{CMD[id="save_cart_recurring"]recurring}}

Set to true if recurring. Set to false, or simply omit it, if it 
is a cart.


H2: summary

This tag calculates column totals.

H3: Summary

!block example;
    [B<summary> amount]
    [B<summary> amount=n.nn I<other_named_attributes>]
!endblock

!block note; label="Positional parameters: "
The first line shows the usage with positional parameters (given in
order). The second line shows usage with named parameters.
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
amount|Numerical value to be added to previous total|I<none>
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#summary_currency"]currency}}|I<none>
{{CMD[jump="#summary_format"]format}}|I<none>
{{CMD[jump="#summary_hide"]hide}}|I<none>, no hiding
{{CMD[jump="#summary_name"]name}}|ONLY0000, internal use only
{{CMD[jump="#summary_reset"]reset}}|I<none>
{{CMD[jump="#summary_total"]total}}|I<none>
!endblock

!block table;headings=1
A|B
Other_Characteristics|
Invalidates cache|I<No>
Macro|I<No>
Has end tag|I<No>
!endblock

B<Tag expansion example:>

!block example
    [loop list="10 20 30.5"]
        [summary amount="[loop-code]" hide=1]
    [/loop]
    [summary total=1 format="%.3f"]
    [summary total=1 currency=1]
---
    60.500
    $60.50
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->summary( { amount => 10.5,
                       hide => 1, } );
                                           
    $Tag->summary( { amount => 25,
                       name => mytotal,
                   currency => 1, } );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->summary( 10.5, $attribute_hash_reference );
!endblock

H4: See Also

templates/components/cart, pages/ord/checkout.html for more examples.

H3: Description

The summary tag provides you with an easy way to calculate and 
display totals. The display of the amounts is fully customizable. 
You can hide display, or you can show the amounts with the proper 
currency formatting according to the locale, or you can define 
your own formatting. Any number of summaries can be kept on a page.

H4: {{CMD[id="summary_currency"]currency}}

The amount or total will be displayed according to the currency 
formatting of the current locale if this attribute is set to 
true (non blank or zero).

H4: {{CMD[id="summary_format"]format}}

You can choose any formatting of the amount you like. Just set 
the format attribute to the desired formatting string (%s, %.2f 
etc.). When both, currency and format attributes are set, the 
format attribute will take precedence. So it doesn't make much 
sense to set them both at the same time.

H4: {{CMD[id="summary_hide"]hide}}

Will suppress the display of amount when set to true.

H4: {{CMD[id="summary_name"]name}}

You can calculate as many totals as you like on the same 
page. Just supply a different label for each summary.

H4: {{CMD[id="summary_reset"]reset}}

Will erase the total(s) if set to true. Be careful tough.
It will reset ALL totals when you have no name attribute supplied.
If you have provided a label for the name attribute then it will 
only reset the total for that particular label. All others won't be 
touched.

H4: {{CMD[id="summary_total"]total}}

Will show the total instead of the amount if set to true.


H2: table_organize

Takes an unorganized set of table cells and organizes them into
rows based on the number of columns.

H3: Summary

!block example;
    [B<table-organize> cols* I<other_named_attributes>]
             [loop ....] <td> [loop-tags] </td> [/loop]
        [/table-organize]
        
    [B<table-organize> cols=n* I<other_named_attributes>]
             [loop ....] <td> [loop-tags] </td> [/loop]
        [/table-organize]
!endblock

!block note; label="Positional parameters: "
The first line shows the usage with positional parameters (given in
order). The second line shows usage with named parameters.
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#table_organize_cols"]cols}}|Number of columns.|2
columns|Alias for cols.|2
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#table_organize_caption"]caption}}|I<none>
{{CMD[jump="#table_organize_columnize"]columnize}}|I<none>
{{CMD[jump="#table_organize_embed"]embed}}|I<none>
{{CMD[jump="#table_organize_filler"]filler}}|&nbsp;
{{CMD[jump="#table_organize_limit"]limit}}|I<none>
{{CMD[jump="#table_organize_pretty"]pretty}}|I<none>
{{CMD[jump="#table_organize_rows"]rows}}|I<none>
{{CMD[jump="#table_organize_table"]table}}|I<none>
{{CMD[jump="#table_organize_td"]td}}|I<none>
{{CMD[jump="#table_organize_tr"]tr}}|I<none>
!endblock

!block table;headings=1
A|B
Other_Characteristics|
Invalidates cache|I<No>
Macro|I<No>
Has end tag|[/table-organize]
!endblock

B<Tag expansion example:>

This example produces a table that (1) alternates rows with background
colors "#EEEEEE" and "#FFFFFF", and (2) aligns the columns right,
center, left:

!block example
        [table-organize
            cols=3
            pretty=1
            tr.0='bgcolor="#EEEEEE"'
            tr.1='bgcolor="#FFFFFF"'
            td.0='align=right'
            td.1='align=center'
            td.2='align=left'
        ]
            [loop list="1 2 3 1a 2a 3a 1b"] <td> [loop-code] </td> [/loop]
        [/table-organize]
---
        <tr bgcolor="#EEEEEE">
                <td align=right>1</td>
                <td align=center>2</td>
                <td align=left>3</td>
        </tr>
        <tr bgcolor="#FFFFFF">
                <td align=right>1a</td>
                <td align=center>2a</td>
                <td align=left>3a</td>
        </tr>
        <tr bgcolor="#EEEEEE">
                <td align=right>1b</td>
                <td align=center>&nbsp;</td>
                <td align=left>&nbsp;</td>
        </tr>
!endblock

If the attribute columnize=1 is present, the result will look like:

!block example
            <tr bgcolor="#EEEEEE">
                    <td align=right>1</td>
                    <td align=center>1a</td>
                    <td align=left>1b</td>
            </tr>
            <tr bgcolor="#FFFFFF">
                    <td align=right>2</td>
                    <td align=center>2a</td>
                    <td align=left>&nbsp;</td>
            </tr>
            <tr bgcolor="#EEEEEE">
                    <td align=right>3</td>
                    <td align=center>3a</td>
                    <td align=left>&nbsp;</td>
            </tr>
!endblock

See the source for more ideas on how to extend this tag.

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->table_organize( { cols => 3,
                            pretty => 1, }, $BODY );
!endblock

or similarly with positional parameters:

!block example; lang="Perl"
    $Tag->table_organize( $cols, $attribute_hash_reference, $BODY );
!endblock

H4: See Also

pages/flypage.html, pages/quantity.html, templates/components/best_horizontal,
templates/components/cart, templates/components/cross_horizontal,
templates/components/random, templates/components/random_vertical,
templates/components/upsell

H3: Description

Takes an unorganized set of table cells and organizes them into
rows based on the number of columns; it will also break them into
separate tables.

If the number of cells are not on an even modulus of the number of columns,
then "filler" cells are pushed on.

H4: {{CMD[id="table_organize_cols"]cols (or columns)}}

Number of columns. This argument defaults to 2 if not present.

H4: {{CMD[id="table_organize_rows"]rows}}

Optional number of rows. Implies "table" parameter.

H4: {{CMD[id="table_organize_table"]table}}

If present, will cause a surrounding E<lt>TABLE> E<lt>/TABLE> pair with the attributes
specified in this option.

H4: {{CMD[id="table_organize_caption"]caption}}

Table E<lt>CAPTION> container text, if any. Can be an array.

H4: {{CMD[id="table_organize_td"]td}}

Attributes for table cells. Can be an array.

H4: {{CMD[id="table_organize_tr"]tr}}

Attributes for table rows. Can be an array.

H4: {{CMD[id="table_organize_columnize"]columnize}}

Will display cells in (newspaper) column order, i.e. rotated.

H4: {{CMD[id="table_organize_pretty"]pretty}}

Adds newline and tab characters to provide some reasonable indenting.

H4: {{CMD[id="table_organize_filler"]filler}}

Contents to place in empty cells put on as filler. Defaults to "&nbsp;".

H4: {{CMD[id="table_organize_limit"]limit}}

Maximum number of cells to use. Truncates extra cells silently.

H4: {{CMD[id="table_organize_embed"]embed}}

If you want to embed other tables inside, make sure they are 
called with lower case E<lt>td> elements, then set the embed 
tag and make the cells you wish to organize be E<lt>TD> elements. 
To switch that sense, and make the upper-case or mixed case be 
the ignored cells, set the embed parameter to "lc".

!block example
    [table-organize embed=lc]
                <td>
                        <TABLE>
                                <TR>
                                <TD> something 
                                </TD>
                                </TR>
                        </TABLE>
                </td>
    [/table-organize]
!endblock

or

!block example
    [table-organize embed=uc]
                <TD>
                        <table>
                                <tr>
                                <td> something 
                                </td>
                                </tr>
                        </table>
                </TD>
    [/table-organize]
!endblock

The "tr", "td", and "caption" attributes can be specified with 
indexes; if they are, then they will alternate according to the 
modulus.

The "td" option array size should probably always equal the number 
of columns; if it is bigger, then trailing elements are ignored. 
If it is smaller, no attribute is used.


H2: title_bar

Creates a quick title bar.

H3: Summary

!block example;
    [B<title-bar> width size color]My title[/title-bar]
    [B<title-bar> width=600 size=5 color="#ff0000"]My title[/title-bar]
!endblock

!block note; label="Positional parameters: "
The first line shows the usage with positional parameters (given in
order). The second line shows usage with named parameters.
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#title_bar_color"]color}}|<<
Background color the bar. 
. Defaults to 
** variable HEADERBG or 
** #444444
>>|HEADERBG or #444444
{{CMD[jump="#title_bar_size"]size}}|Font size|6
{{CMD[jump="#title_bar_width"]width}}|Width of the title bar|500
!endblock

!block table;headings=1
A|B
Other_Characteristics|
Invalidates cache|I<No>
Macro|I<No>
Has end tag|[/title-bar]
!endblock

B<Tag expansion example:>

!block example
    [title-bar 600 5 red]My title[/title-bar]
    [title-bar width=600 size=5 color="#ff0000"]My title[/title-bar]
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->title_bar( { body => "My Title", } );
                                           
    $Tag->title_bar( { width => 400,
                       color => "#0000ff",
                        body => "My title", } );
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->title_bar( 600, 5, "red", "My title" );
!endblock


H3: Description

Quickly adds a title bar to your pages without having to type the 
html each time. Background color, width of the bar and size of the 
text can be customized by setting the appropriate parameter. The 
text color defaults to variable HEADERTEXT or when its not present 
to white.

H4: {{CMD[id="title_bar_color"]color}}

Sets the background color of the bar. You can set the color as 'red', 
'#ff0000', or 'bgcolor="#ff0000"'.

H4: {{CMD[id="title_bar_size"]size}}

Determines the size of the text. Parameter should be set to a value accepted 
by the HTML <font> tag size attribute.

H4: {{CMD[id="title_bar_width"]width}}

Sets the width of the bar.


H2: ups_query


H2: usertrack


H2: var


H2: xml-generator

This is a quick and dirty tag that generates XML tags based upon one of
two types of data (delimited and session).

H3: Summary

!block example;
    [B<xml-generator> type* I<other_named_attributes>][/xml-generator]
    [B<xml-generator> type=value* I<other_named_attributes>][/xml-generator]
    [B<xml-generator> type=value* I<other_named_attributes>][][/xml-generator]

*Optional
!endblock

!block note; label="Positional parameters: "
The first line shows the usage with positional parameters (given in
order). The second line shows usage with named parameters.
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
{{CMD[jump="#xml_generator_type"]type}}|Data type. Delimited or session|delimited
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#xml_generator_attributes"]attributes}}|I<none>
{{CMD[jump="#xml_generator_dbdump"]dbdump}}|I<none>
{{CMD[jump="#xml_generator_delimiter"]delimiter}}|\t
{{CMD[jump="#xml_generator_field_names"]field_names}}|&nbsp;
{{CMD[jump="#xml_generator_separator"]separator}}|\n
{{CMD[jump="#xml_generator_toplevel_tag"]toplevel_tag}}|'table' for delimited type and 'session' for other type
{{CMD[jump="#xml_generator_record_tag"]record_tag}}|record
{{CMD[jump="#xml_generator_field_tag"]field_tag}}|field
{{CMD[jump="#xml_generator_key_name"]key_name}}|I<none>
{{CMD[jump="#xml_generator_spacer"]spacer}}|[\s,]+
{{CMD[jump="#xml_generator_no_second"]no_second}}|I<none>
{{CMD[jump="#xml_generator_skip_empty"]skip_empty}}|I<none>
!endblock

!block table;headings=1
A|B
Other_Characteristics|
Invalidates cache|I<No>
Macro|I<No>
Has end tag|[/xml-generator]
!endblock

B<Tag expansion example:>

!block example
    [xml-generator type=delimited 
             attributes="date" 
                   date="[tag time]%d-%b-%Y[/tag]"
           toplevel_tag=products
    ]code       description     price
        [query list=1
                        sql="select sku, description, price from products"
                        prefix=xml][xml-code]  [xml-param description] [xml-param price]
        [/query]
    [/xml-generator]
---
    <products date="18-May-2001">
            <record key="os28113">
                    <code>os28113</code>
                    <description>The Claw Hand Rake</description>
                    <price>14.99</price>
            </record>
            <record key="os28006">
                    <code>os28006</code>
                    <description>Painters Brush Set</description>
                    <price>29.99</price>
            </record>
            ...
    </products>
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->xml_generator( {type => delimited,
                      toplevel_tag => apex,  }, $BODY );
                                           
!endblock

or similarly with positional parameters,

!block example; lang="Perl"
    $Tag->xml_generator( $type, $attribute_hash_reference, $BODY );
!endblock

H3: Description

H4: {{CMD[id="xml_generator_type"]type}}

delimited

Accepts a delimited and separated (default is TAB delimiter and 
newline separator) list of records such as that generated by an 
'[item-list]', '[sql]', or '[loop search=""]' ITL tag.

session

When the type is not delimited, it can contain any hash reference into
the Interchange session. Examples are:

!block example
        values       The form values
        scratch      Scratch values
        errors       Error values
        other        Any other Session key, for example "source" for
                     [data session source]
!endblock

If the value is a hash, then it will be sent as an XML record with the
top level equal to "session", and a second_level tag equal to the hash
name, and keys as separate XML container tags. If the parameter "that is equal
to the type" is given, only those fields will be shown. Otherwise the
entire hash will be shown. For example, this tag:

!block example
        [xml-generator type="values" values="fname lname"][/xml-generator]

will generate:

        <session>
                <values>
                        <fname>First</fname>
                        <lname>Last</lname>
                </values>
        </session>

if it is a scalar, then only the second level will be done:

        [xml-generator type="cybercash_id"][/xml-generator]

will do the equivalent of:

        <session>
                <cybercash_id>[data session cybercash_id]</cybercash_id>
        </session>

So bringing it all together, the following:

        [xml-generator type="values scratch source"
                       values="fname lname"
                       scratch="downloads"][/xml-generator]
will generate:

        <session>
                <values>
                        <fname>First</fname>
                        <lname>Last</lname>
                </values>
                <scratch>
                        <downloads>0</downloads>
                </scratch>
                <source>Partner1</source>
        </session>
!endblock

H4: {{CMD[id="xml_generator_no_second"]no_second}}

Prevents the second-level tags from being generated. Extending the
last example in the "session" type above, this

!block example
        [xml-generator  type="values scratch source"
                        no_second=1
                        values="fname lname"
                        scratch="downloads"][/xml-generator]
will generate:

        <session>
                <fname>First</fname>
                <lname>Last</lname>
                <downloads>0</downloads>
                <source>Partner1</source>
        </session>
!endblock

H4: {{CMD[id="xml_generator_attributes"]attributes}}

The attributes (if any) to pass on to the top level tag. For instance,
!block example
    [xml-generator
          attributes="date"
                date="[tag time]%d-%b-%Y[/tag]"
        toplevel_tag=order
    ][/xml-generator]

will generate a toplevel tag pair of:

        <order date="18-Mar-2001">
        </order>
!endblock

H4: {{CMD[id="xml_generator_dbdump"]dbdump}}

Will dump all tables in the catalog when this attribute is set 
true. Used attributes are "toplevel_tag", "record_tag", 
"field_tag", and "skip_empty" or default values ('table', 
'record', 'field' respectively).

!block example
Output format:
    <database name="catalogname">
        <toplevel_tag name="tablename1">
            <record_tag key="value of first field-1">
                <field_tag name="fieldname1">fieldvalue1</field_tag>
                <field_tag name="fieldname2">fieldvalue2</field_tag>
                        </record_tag>
            <record_tag key="value of first field-2">
                <field_tag name="fieldname1">fieldvalue1</field_tag>
                <field_tag name="fieldname2">fieldvalue2</field_tag>
                        </record_tag>
                </toplevel_tag>
        <toplevel_tag name="tablename2">
            <record_tag key="value of first field-1">
                <field_tag name="fieldname1">fieldvalue1</field_tag>
                <field_tag name="fieldname2">fieldvalue2</field_tag>
                        </record_tag>
                </toplevel_tag>
        </database>
!endblock

B<Important note:> All tables are read into memory. So be warned, this
could be a real memory hog.

N:Ton Verhagen's proposal: 

^ Add option to select tables. E.g. dump_tables="products cat area" and/or

+ Add option to select an output file. E.g. dump_file="tabledump.XML". Send 
   output to file line by line.

H4: {{CMD[id="xml_generator_delimiter"]delimiter}}

Character used as delimiter of fields in delimited data type. 
Defaults to a tab character.

H4: {{CMD[id="xml_generator_field_names"]field_names}}

Space or comma-delimited list of field names to be used for
delimited data type. Should be in the same order as in the data 
list provided (between the tags).

Another way of providing the field names would be:

!block example
    [xml-generator .....]fieldname-1    fieldname-2     fieldname-3
        [field value list 
         delimited by option delimiter and 
         separated by option separator][/xml-generator]
!endblock

.Note: Field name list B<must> be tab delimited. 

N:Ton Verhagen's humble opinion: This should change in future versions! Use option delimiter instead.

H4: {{CMD[id="xml_generator_separator"]separator}}

Character used as line separator in list between 
E<lbracket>xml-separator]E<lbracket>xml-separator] tags and 
in output 'session' data type. Defaults to a newline, "\n".

H4: {{CMD[id="xml_generator_toplevel_tag"]toplevel_tag}}

The toplevel tag name to use. Defaults to "table" for the 
'dbdump mode' and delimited type, and "session" for the other.

H4: {{CMD[id="xml_generator_record_tag"]record_tag}}

Defines the tag name for the record tag. Defaults to 'record'.
Used for 'dbdump mode' and delimited type.

H4: {{CMD[id="xml_generator_field_tag"]field_tag}}

Defines the tag name for the field tag. Defaults to 'field'.
Only used in 'dbdump mode'.

H4: {{CMD[id="xml_generator_key_name"]key_name}}

Only used in delimited data type.
Defines fieldname to determine key value in "record_tag".
!block example
    <record_tag key="value of field with name defined by key_name"> ....
!endblock

H4: {{CMD[id="xml_generator_spacer"]spacer}}

Character used as delimiter in type parameter definition and 
corresponding attributes. Defaults to '[\s,]+' (one or more 
whitespace or comma).

!block example
    [xml-generator type="values|scratch" 
                 values="value1|value2" 
                scratch="scratch1|scratch2"
                 spacer="|"
    ][/xml-generator]
!endblock

H4: {{CMD[id="xml_generator_skip_empty"]skip_empty}}

Only used in {{CMD[jump="#xml_generator_dbdump"]dbdump}} mode 
(dbdump=1). Will skip empty fields if this attribute is set true.


!block comment

A1: Tag Entry Format

H2[notoc] dummy

N:Alias: B<pedagogy>, B<dummy_alias>
!block note;
E<lbracket>B<dummy>E<nbspace>...], [B<pedagogy>E<nbspace>...] and [B<dummy-alias>E<nbspace>...] are equivalent. If the tag has an endtag, you must not mix aliases between the tag and its endtag (i.e., E<lbracket>dummy] ... E<lbracket>/pedagogy] would not work).
!endblock

A short description of the tag goes here. This example (B<dummy>) is
not an actual tag.


A3: Summary

!block example;
    [B<dummy> first second][/dummy]
    [B<dummy> first=first_args second=second_args I<other_named_attributes>][/dummy]
!endblock

!block note; label="Positional parameters: "
The first line shows the usage with positional parameters (given in
order). The second line shows usage with named parameters.
!endblock

!block table; colvaligns="TTT"; format="262"
Parameters|Description|Default
first|<<
The first positional parameter
. I<Special arguments>
** '{{CMD[jump="#dummy_special_value"]special_value}}'E<nbspace>E<emdash>
any special arguments to the parameter that cause the tag to behave
differently are listed here and described in detail in the
B<Description> section below.
** 'pig_latin'E<nbspace>E<emdash> For this dummy tag, let's suppose
that an argument of 'pig_latin' rewrites the body text in pig latin.

>>|default value if the parameter is not given
second|Another example parameter|I<none>
I<alias1>|<<
alias for B<first>E<nbspace>E<emdash> some parameters have
aliasesE<nbspace>E<emdash> [dummyE<nbspace>alias1="X"] is equivalent
to [dummyE<nbspace>first="X"]
>>|Same default as B<first>, of course
!endblock

!block table; colvaligns="TT"
Attributes|Default
{{CMD[jump="#dummy_more"]more}}|I<none>
{{CMD[jump="#dummy_still_more"]still-more}}|I<none> (requires B<more>)
{{CMD[jump="#dummy_other"]other}}|I<none>
{{CMD[jump="#attr_interpolate"]interpolate (body)}}|I<Yes>
{{CMD[jump="#attr_reparse"]reparse}}|I<No>
!endblock

!block table;headings=1
A|B
Other_Characteristics|
Invalidates cache|I<No>
Macro|I<No>
Has end tag|[/dummy]
!endblock

B<Tag expansion example:>

!block example
    [dummy first=pig_latin second="Capitalize"]\
    Body text acted on by the tag goes here.[/dummy]
---
    OdyBay ExtTaY ActedAy OnAy YBay EThay AgTay OesGay \
    EreHay.
!endblock

!block note; label="Reading the tag expansion example: "

. B<format:> The tag is listed first. A blank line separates it from
the expanded return value.

. B<long lines:> When this document must break a line from an example
because it is too wide for the page, a trailing backslash indicates
the continuation. Note that such a trailing backslash is *not* part of
the actual tag syntax or expansion.
!endblock

B<ASP-like Perl call:>

!block example; lang="Perl"
    $Tag->dummy(  { first  => 'goober',
                    second => 'foobar',
                    more   => $snafu, },  $body_text  );

!endblock

or similarly,

!block example; lang="Perl"
    $Tag->dummy($first, $second, $attribute_hash_reference, $body_text);
!endblock


A3: Description

More detailed tag description

A4: first

Section describing the first parameter

A5: {{CMD[id="dummy_special_value"]special_value}}

Description of treatment of the special argument. For example, giving
the {{CMD[jump="#page"]page}} tag an B<href> of 'scan' causes it to
link to a search specification rather than a page.

A4: {{CMD[id="dummy_more"]more}}

C<more> is a named attribute that applies to this tag.

A4: {{CMD[id="dummy_still_more"]still-more}}

C<still-more> is a named attribute that applies to this tag only when
the C<more> attribute has been given. It would be an error to use the
C<still-more> attribute without specifying a value for C<more>

A4: {{CMD[id="dummy_other"]other}}

'other' is another named attribute that applies to this tag.

!endblock


A1: Template Parsing Order


A2: Standard Parsing

Under normal circumstances, the template page containing tags and HTML
is parsed in the following order:

^ Any content in MV_AUTOLOAD is prepended to the template page.

..{{}}

.{{}}

+ Any C<[pragma]> tags anywhere
in the text are processed, and the specified pragmas are set.

** Since C<[pragma]> tags are preprocessed before any other content,
{{C[jump="#attr_reparse"]reparse}} will not catch them, nor
will they work if included in variables. Also, the specified pragma
will apply to the entire template (not just the section after the tag).

** If you want to apply a pragma with a variable or only to part of a
document, you must use E<lbracket>{{C[jump="#tag"]tag}}E<nbspace>pragma="..."]
instead.

.{{}}

+ Variables (macros) are processed in the following order:
++ @@VARNAME@@ global variables
++ @_VARNAME_@ local or global variables
++ __VARNAME__ local variables

.{{}}

+ Interchange comments are stripped.

..{{}}

.{{}}

+ False-endtag macros are expanded (e.g.,
E<lbracket>{{C[jump="#page"]/page}}] and
E<lbracket>{{C[jump="#order"]/order}}]).

..{{}}

.{{}}

+ '<!--[tagname]-->' escapes are converted to E<lbracket>tagname]

** This can be a convenience for your HTML editor if it has trouble
with tags using the standard E<lbracket>tagname] syntax.

** However, if you want to HTML-comment out an Interchange tag in content
that will be fed raw to a browser, you must include whitespace between
the HTML comment delimiters and the tag, like this, '<!--E<nbspace>E<nbspace>E<lbracket>tagname]E<nbspace>E<nbspace>-->'.

.{{}}

+ The main tag parser is called.

** Some tags parse recursively (depending upon
{{C[jump="#attr_reparse"]reparse}} and
{{C[jump="#attr_interpolate"]interpolate}} settings, of course).

** Some tags (e.g., E<lbracket>{{C[jump="#loop"]loop}}])
process PREFIX-tags in their contained body text. Hence, the PREFIX-tags are
not handled recursively.

** Some tags are interpreted in the lib/Vend/Parse.pm:start routine. You cannot call them with the '$Tag->I<tagname>()' syntax. They N<are:>
*** The E<lbracket>{{C[jump="#goto"]goto}}] tag. Note also that the E<lbracket>{{C[jump="#goto"]goto}}] tag handles the E<lbracket>{{C[jump="#label"]label}}] tag.
*** The E<lbracket>{{C[jump="#bounce"]bounce}}] tag.

.{{}}

+ Image paths substitution on the HTML output occurs.

..{{}}

.{{}}


A2: Nonstandard parsing within the admin interface

Parsing of content via the specialized C<[regenerate]> usertag included
with the administrative interface does not obey the above order. The
MV_AUTOLOAD and '<!--[tagname]-->' escapes are skipped. There are
some other more subtle differences as well; in the very unlikely event
that you need to check this in the source code, compare the
'interpolate_html' and 'cache_html' routines in Interpolate.pm.


A2: Nonstandard parsing of Subtags

Subtags are parsed within the containing array-list or hash-list
context created by the containing tag (see
{{CMD[jump="#Looping tags and Sub-tags"]Looping tags and Sub-tags}}).

* All subtags at an earlier precedence level are treated before any in
the next level.
* Within the same level, tags are processed in the order the appear on
the page.
* Any standard tags are processed during 'interpolate' (before) or
'reparse' (after) phases of processing the containing tag.

!block note; label="Technical note"

Processing within a hash- or array-list is actually done as a series
of global regular expression substitutions on the page. Each
substitution replaces one tag with the output of the subroutine(s)
associated with it.
!endblock

In array-list context, subtags are processed in the following N<order:>

^ Check for PREFIX-B<line> and prepare for it if present (does not process PREFIX-B<line> at this time)
+ PREFIX-B<sub> definitions processed
+ B<if>-PREFIX-I<*> nesting resolved
+ PREFIX-B<alternate> processed
+ B<if>-PREFIX-B<param>  processed
+ B<if>-PREFIX-B<pos>  processed
+ PREFIX-B<pos>  processed
+ B<if>-PREFIX-B<field>  processed
+ PREFIX-B<line>  processed
+ PREFIX-B<increment>  processed
+ PREFIX-B<accessories>  processed
+ PREFIX-B<options>  processed
+ PREFIX-B<code>  processed
+ PREFIX-B<description>  processed
+ PREFIX-B<field>  processed
+ PREFIX-B<price>  processed
+ PREFIX-B<change>  processed
+ PREFIX-B<calc>  processed
+ PREFIX-B<exec>  processed
+ PREFIX-B<filter>  processed
+ PREFIX-B<last>  processed
+ PREFIX-B<next>  processed
+ User's previous HTML widget SELECTED settings restored
+ Reparse standard tags in output of above (if reparse enabled for the containing tag)


In hash-list context, subtags are processed in the following N<order:>

^ PREFIX-B<sub> definitions processed
+ B<if>-PREFIX-I<*> nesting resolved
+ PREFIX-B<alternate> processed
+ PREFIX-B<line>  processed
+ B<if>-PREFIX-B<param>  processed
+ B<if>-PREFIX-B<field>  processed
+ B<if>-PREFIX-B<modifier>  processed (B<if>-PREFIX-B<param> and B<if>-PREFIX-B<modifier> are functionally identical except for parse order)
+ PREFIX-B<increment>  processed
+ PREFIX-B<accessories>  processed
+ PREFIX-B<options>  processed
+ PREFIX-B<sku>  processed
+ PREFIX-B<code>  processed
+ PREFIX-B<quantity>  processed
+ PREFIX-B<modifier>  processed
+ PREFIX-B<param>  processed
+ PREFIX-B<quantity-name>  processed
+ PREFIX-B<modifier-name>  processed
+ PREFIX-B<subtotal>  processed
+ PREFIX-B<discount-subtotal>  processed
+ PREFIX-B<code>  processed again differently (operating on new instances of PREFIX-B<code> in output of above?)
+ PREFIX-B<field>  processed
+ PREFIX-B<description>  processed
+ PREFIX-B<price>  processed
+ PREFIX-B<discount-price>  processed
+ PREFIX-B<difference>  processed
+ PREFIX-B<discount>  processed
+ PREFIX-B<change>  processed
+ PREFIX-B<tag>  processed (*** CHECK THIS TAG NAME ***)
+ PREFIX-B<calc>  processed
+ PREFIX-B<exec>  processed
+ PREFIX-B<filter>  processed
+ PREFIX-B<last>  processed
+ PREFIX-B<next>  processed
+ User's previous HTML widget SELECTED settings restored
+ Reparse standard tags in output of above (if reparse enabled for the containing tag)


A1: Search and Form Variables

A2: Variable Names

A4: {{CMD[id="dummy_other"]other}}
!block table; colvaligns="TTTT"; format="3115"
Name|scan|Type|Description
{{CMD[id="mv_all_chars"]mv_all_chars}}|ac|S|Turns on punctuation matching
{{CMD[id="mv_arg"]mv_arg[0-9]+}}||A|Parameters for mv_subroutine (mv_arg0,mv_arg1,...)
{{CMD[id="mv_base_directory"]mv_base_directory}}|bd|S|Sets base directory for search file names
{{CMD[id="mv_begin_string"]mv_begin_string}}|bs|S|Pattern must match beginning of field
{{CMD[id="mv_case"]mv_case}}|cs|S|Turns on case sensitivity
{{CMD[id="mv_cartname"]mv_cartname}}||O|Sets the shopping cart name
{{CMD[id="mv_check"]mv_check}}||A|Any form, sets multiple user variables after update
{{CMD[id="mv_click"]mv_click}}||A|Any form, sets multiple form variables before update
{{CMD[id="mv_click"]mv_click}}||XA|Default mv_click routine, click is mv_click_arg
{{CMD[id="mv_click_NAME"]mv_click I<name>}}||XA|Routine for a click I<name>, sends click as arg
{{CMD[id="mv_click_arg"]mv_click_arg}}||XA|Argument name in scratch space
{{CMD[id="mv_coordinate"]mv_coordinate}}|co|S|Enables field/spec matching coordination
{{CMD[id="mv_column_op"]mv_column_op}}|op|S|Operation for coordinated search
{{CMD[id="mv_credit_card*"]mv_credit_card*}}||O|Discussed in order security (some are read-only)
{{CMD[id="mv_dict_end"]mv_dict_end}}|de|S|Upper bound for binary search
{{CMD[id="mv_dict_fold"]mv_dict_fold}}|df|S|Non-case sensitive binary search
{{CMD[id="mv_dict_limit"]mv_dict_limit}}|di|S|Sets upper bound based on character position
{{CMD[id="mv_dict_look"]mv_dict_look}}|dl|S|Search specification for binary search
{{CMD[id="mv_dict_order"]mv_dict_order}}|do|S|Sets dictionary order mode
{{CMD[id="mv_doit"]mv_doit}}||A|Sets default action
{{CMD[id="mv_email"]mv_email}}||O|Reply-to address for orders
{{CMD[id="mv_exact_match"]mv_exact_match}}|em|S|Sets word-matching mode
{{CMD[id="mv_failpage"]mv_failpage}}|fp|O,S|Sets page to display on failed order check/search
{{CMD[id="mv_field_file"]mv_field_file}}|ff|S|Sets file to find field names for Glimpse
{{CMD[id="mv_field_names"]mv_field_names}}|fn|S|Sets field names for search, starting at 1
{{CMD[id="mv_first_match"]mv_first_match}}|fm|S|Start displaying search at specified match
{{CMD[id="mv_head_skip"]mv_head_skip}}|hs|S|Sets skipping of header line(s) in index
{{CMD[id="mv_index_delim"]mv_index_delim}}|id|S|Delimiter for search fields (TAB default)
{{CMD[id="mv_matchlimit"]mv_matchlimit}}|ml|S|Sets match page size
{{CMD[id="mv_max_matches"]mv_max_matches}}|mm|S|Sets maximum match return
{{CMD[id="mv_min_string"]mv_min_string}}|ms|S|Sets minimum search spec size
{{CMD[id="mv_negate"]mv_negate}}|ne|S|Records NOT matching will be found
{{CMD[id="mv_nextpage"]mv_nextpage}}|np|A|Sets next page user will go to
{{CMD[id="mv_numeric"]mv_numeric}}|nu|S|Comparison numeric in coordinated search
{{CMD[id="mv_order_group"]mv_order_group}}||O|Allows grouping of master item/sub item
{{CMD[id="mv_order_item"]mv_order_item}}||O|Causes the order of an item
{{CMD[id="mv_order_number"]mv_order_number}}||O|Order number of the last order (read-only)
{{CMD[id="mv_order_quantity"]mv_order_quantity}}||O|Sets the quantity of an ordered item
{{CMD[id="mv_order_profile"]mv_order_profile}}||O|Selects the order check profile
{{CMD[id="mv_order_receipt"]mv_order_receipt}}||O|Sets the receipt displayed
{{CMD[id="mv_order_report"]mv_order_report}}||O|Sets the order report sent
{{CMD[id="mv_order_subject"]mv_order_subject}}||O|Sets the subject line of order email
{{CMD[id="mv_orsearch"]mv_orsearch}}|os|S|Selects AND/OR of search words
{{CMD[id="mv_profile"]mv_profile}}|mp|S|Selects search profile
{{CMD[id="mv_record_delim"]mv_record_delim}}|dr|S|Search index record delimiter
{{CMD[id="mv_return_all"]mv_return_all}}|ra|S|Return all lines found (subject to range search)
{{CMD[id="mv_return_delim"]mv_return_delim}}|rd|S|Return record delimiter
{{CMD[id="mv_return_fields"]mv_return_fields}}|rf|S|Fields to return on a search
{{CMD[id="mv_return_file_name"]mv_return_file_name}}|rn|S|Set return of file name for searches
{{CMD[id="mv_return_spec"]mv_return_spec}}|rs|S|Return the search string as the only result
{{CMD[id="mv_save_session"]mv_save_session}}||C|Set to non-zero to prevent expiration of user session
{{CMD[id="mv_search_field"]mv_search_field}}|sf|S|Sets the fields to be searched
{{CMD[id="mv_search_file"]mv_search_file}}|fi|S|Sets the file(s) to be searched
{{CMD[id="mv_search_line_return"]mv_search_line_return}}|lr|S|Each line is a return code (loop search)
{{CMD[id="mv_search_match_count"]mv_search_match_count}}||S|Returns the number of matches found (read-only)
{{CMD[id="mv_search_page"]mv_search_page}}|sp|S|Sets the page for search display
{{CMD[id="mv_searchspec"]mv_searchspec}}|se|S|Search specification
{{CMD[id="mv_searchtype"]mv_searchtype}}|st|S|Sets search type (text, glimpse, db or sql)
{{CMD[id="mv_separate_items"]mv_separate_items}}||O|Sets separate order lines (one per item ordered)
{{CMD[id="mv_session_id"]mv_session_id}}|id|A|Suggests user session id (overridden by cookie)
{{CMD[id="mv_shipmode"]mv_shipmode}}||O|Sets shipping mode for custom shipping
{{CMD[id="mv_sort_field"]mv_sort_field}}|tf|S|Field(s) to sort on
{{CMD[id="mv_sort_option"]mv_sort_option}}|to|S|Options for sort
{{CMD[id="mv_spelling_errors"]mv_spelling_errors}}|er|S|Number of spelling errors for Glimpse
{{CMD[id="mv_substring_match"]mv_substring_match}}|su|S|Turns off word-matching mode
{{CMD[id="mv_successpage"]mv_successpage}}||O|Page to display on successful order check
{{CMD[id="mv_todo"]mv_todo}}||A|Common to all forms, sets form action
{{CMD[id="mv_todo.map"]mv_todo.map}}||A|Contains form imagemap
{{CMD[id="mv_todo.checkout.x"]mv_todo.checkout.x}}||O|Causes checkout action on click of image
{{CMD[id="mv_todo.return.x"]mv_todo.return.x}}||O|Causes return action on click of image
{{CMD[id="mv_todo.submit.x"]mv_todo.submit.x}}||O|Causes submit action on click of image
{{CMD[id="mv_todo.x"]mv_todo.x}}||A|Set by form imagemap
{{CMD[id="mv_todo.y"]mv_todo.y}}||A|Set by form imagemap
{{CMD[id="mv_unique"]mv_unique}}|un|S|Return unique search results only
{{CMD[id="mv_value"]mv_value}}|va|S|Sets value on one-click search (va=var=value)
!endblock

A2: Abbreviations

The two-letter abbreviations are mapped with these letters:

!block table; colvaligns="TT"; format="19"
Abbr|Long name
DL|mv_raw_dict_look
MM|mv_more_matches
ac|mv_all_chars
ar|mv_arg
bd|mv_base_directory
bs|mv_begin_string
ck|mv_cache_key
co|mv_coordinate
cs|mv_case
cv|mv_verbatim_columns
de|mv_dict_end
df|mv_dict_fold
di|mv_dict_limit
dl|mv_dict_look
do|mv_dict_order
dr|mv_record_delim
em|mv_exact_match
er|mv_spelling_errors
fi|mv_search_file
fm|mv_first_match
fn|mv_field_names
hs|mv_head_skip
id|mv_session_id
il|mv_index_delim
ix|mv_index_delim
lb|mv_search_label
lo|mv_list_only
lr|mv_line_return
lr|mv_search_line_return
ml|mv_matchlimit
mm|mv_max_matches
mp|mv_profile
ms|mv_min_string
ne|mv_negate
np|mv_nextpage
nu|mv_numeric
op|mv_column_op
os|mv_orsearch
pc|mv_pc
ra|mv_return_all
rd|mv_return_delim
rf|mv_return_fields
rn|mv_return_file_name
rr|mv_return_reference
rs|mv_return_spec
se|mv_searchspec
sf|mv_search_field
si|mv_search_immediate
sp|mv_search_page
sq|mv_sql_query
st|mv_searchtype
su|mv_substring_match
tf|mv_sort_field
to|mv_sort_option
un|mv_unique
va|mv_value
!endblock

Line:

N:Copyright 2002-2004 Interchange Development Group. Copyright 2001-2002 Red Hat, Inc. Freely redistributable under terms of the GNU General Public License.