Permalink
Fetching contributors…
Cannot retrieve contributors at this time
17364 lines (12075 sloc) 455 KB
!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