.PP
used with 'required' to display a standardized error format. The \s-1HTML\s0
formatting can be set via the global variable \s-1MV_ERROR_STD_LABEL\s0 with
the default being:
.PP
.Vb 1
\& {LABEL}(%s)
.Ve
where {\s-1LABEL\s0} is what you set std_label to and \f(CW%s\fR is substituted with
the error message. This option can not be used with the text= option.
.PP
\&\fIrequired=1\fR
.PP
Specifies that this is a required field for formatting purposes. In
the std_label format, it means the field will be bolded. If you
specify your own label string, it will insert \s-1HTML\s0 anywhere you have
{\s-1REQUIRED:\s0 \s-1HTML\s0}, but only when the field is required.
.PP
\&\fIname\fR
.Sh "export"
.IX Subsection "export"
Exports a database to a delimited text file (see also import).
.PP
Summary
.PP
.Vb 1
\& [export table other_named_attributes]
.Ve
.Vb 10
\& Parameters Description Default
\& base Alias for table DEFAULT_VALUE
\& database Alias for table DEFAULT_VALUE
\& delete If 'verify' attribute also set, deletes column specified by 'field' attribute rather than adding a column.DEFAULT_VALUE
\& field The column to add (or delete if delete and verify are true)DEFAULT_VALUE
\& file Filename to export to. Note that the NoAbsolute directive and other conditions may affect actual location of the output file.DEFAULT_VALUE
\& sort Output sorted rows (usage: sort="sort_field:sort_option") (see search/form variable 'mv_sort_option' for sort options)DEFAULT_VALUE
\& table The table to export DEFAULT_VALUE
\& type Specifies the [line, record] delimiter types. Either NOTES or one of the following: my %Delimiter = ( 2 => ["\en", "\en\en"], 3 => ["\en%%\en", "\en%%%\en"], 4 => ["CSV","\en"], 5 => ['|', "\en"], 6 => ["\et", "\en"], 7 => ["\et", "\en"], 8 => ["\et", "\en"], LINE => ["\en", "\en\en"], '%%%' => ["\en%%\en", "\en%%%\en"], '%%' => ["\en%%\en", "\en%%%\en"], CSV => ["CSV","\en"], PIPE => ['|', "\en"], TAB => ["\et", "\en"], );If using NOTESnotes_separator (defaults to "\ef")notes_field (defaults to "notes_field")DEFAULT_VALUE
\& verify must be true when deleting a column DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [export table]
\&---
\& 1
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->export( { table => VALUE_table
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->export(table, $attribute_hash_reference, $body);
.Ve
Description
.PP
Exports 'table' to a delimited text file. See also import tag which
imports files into databases.
.PP
\&\fIdelete\fR
.PP
If 'verify' attribute also set, deletes column specified by 'field'
attribute rather than adding a column.
.PP
\&\fIfield\fR
.PP
The column to add (or delete if delete and verify are true)
.PP
\&\fIfile\fR
.PP
Filename to export to. Note that the NoAbsolute directive and other
conditions may affect actual location of the output file.
.PP
\&\fIsort\fR
.PP
Output sorted rows (usage: sort="\fIsort_field\fR:\fIsort_option\fR")
(see search/form variable 'mv_sort_option' for sort options)
.PP
\&\fItable\fR
.PP
The table to export
.PP
\&\fItype\fR
.PP
Specifies the [line, record] delimiter types. Either \s-1NOTES\s0 or one of
the following:
.PP
.Vb 15
\& my %Delimiter = (
\& 2 => ["\en", "\en\en"],
\& 3 => ["\en%%\en", "\en%%%\en"],
\& 4 => ["CSV","\en"],
\& 5 => ['|', "\en"],
\& 6 => ["\et", "\en"],
\& 7 => ["\et", "\en"],
\& 8 => ["\et", "\en"],
\& LINE => ["\en", "\en\en"],
\& '%%%' => ["\en%%\en", "\en%%%\en"],
\& '%%' => ["\en%%\en", "\en%%%\en"],
\& CSV => ["CSV","\en"],
\& PIPE => ['|', "\en"],
\& TAB => ["\et", "\en"],
\& );
.Ve
.Ip "\(bu" 4
If using \s-1NOTES\s0
.RS 4
.Ip "\(bu" 8
notes_separator (defaults to \*(L"\ef\*(R")
.Ip "\(bu" 8
notes_field (defaults to \*(L"notes_field\*(R")
.RE
.RS 4
.RE
.PP
\&\fIverify\fR
.PP
must be true when deleting a column
.Sh "field"
.IX Subsection "field"
Summary
.PP
Parameters: \fBname code\fR
.PP
Positional parameters in same order.
.PP
Pass attribute hash as last to subroutine: \fBno\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
Invalidates cache: \fBno\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 6
\& $Tag->field(
\& {
\& name => VALUE,
\& code => VALUE,
\& }
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 1
\& $Tag->field($name, $code);
.Ve
Attribute aliases
.PP
.Vb 6
\& col ==> name
\& column ==> name
\& field ==> name
\& key ==> code
\& row ==> code
\& [field name code]
.Ve
.Vb 8
\& Parameters Description Default
\& code DEFAULT_VALUE
\& col Alias for name DEFAULT_VALUE
\& column Alias for name DEFAULT_VALUE
\& field Alias for name DEFAULT_VALUE
\& key Alias for code DEFAULT_VALUE
\& name DEFAULT_VALUE
\& row Alias for code DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [field name code]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 3
\& $Tag->field( { code => VALUE_code
\& name => VALUE_name
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->field(name,code, $attribute_hash_reference, $body);
.Ve
Description
.PP
Expands into the value of the field \fIname\fR for the product identified
by \fIcode\fR as found by searching the products database. It will return
the first entry found in the series of \fIProduct Files\fR. the products
database. If you want to constrain it to a particular database, use
the [data base name code] tag.
.PP
Note that if you only have one ProductFile products, which is the
default, [field column key] is the same as [data products column
key].
.PP
\&\fIcode\fR
.PP
\&\fIname\fR
.Sh "file"
.IX Subsection "file"
Summary
.PP
Parameters: \fBname type\fR
.PP
Positional parameters in same order.
.PP
Pass attribute hash as last to subroutine: \fBno\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
Invalidates cache: \fBno\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 6
\& $Tag->file(
\& {
\& name => VALUE,
\& type => VALUE,
\& }
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 2
\& $Tag->file($name, $type);
\& [file name type]
.Ve
.Vb 3
\& Parameters Description Default
\& name DEFAULT_VALUE
\& type DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [file name type]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 3
\& $Tag->file( { name => VALUE_name
\& type => VALUE_type
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->file(name,type, $attribute_hash_reference, $body);
.Ve
Description
.PP
Inserts the contents of the named file. The file should normally be
relative to the catalog directory \- file names beginning with / or ..
are not allowed if the Interchange server administrator has set
\&\fINoAbsolute\fR to Yes.
.PP
The optional type parameter will do an appropriate \s-1ASCII\s0
translation on the file before it is sent.
.PP
\&\fIname\fR
.PP
\&\fItype\fR
.Sh "filter"
.IX Subsection "filter"
Summary
.PP
Parameters: \fBop\fR
.PP
Positional parameters in same order.
.PP
Pass attribute hash as last to subroutine: \fBno\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
This is a container tag, i.e. [filter] \s-1FOO\s0 [/filter]. Nesting: \s-1NO\s0
.PP
Invalidates cache: \fBno\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 6
\& $Tag->filter(
\& {
\& op => VALUE,
\& },
\& BODY
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 2
\& $Tag->filter($op, $BODY);
\& [filter op]
.Ve
.Vb 2
\& Parameters Description Default
\& op DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 1
\& [filter lc]UPPER CASE YOU WANT TO SEE AS LOWER CASE[/filter]
.Ve
.Vb 1
\& Produces:
.Ve
.Vb 1
\& upper case you want to see as lower case
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->filter( { op => VALUE_op
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->filter(op, $attribute_hash_reference, $body);
.Ve
Description
.PP
Applies any of Interchange's standard filters to an arbitrary value,
or you may define your own. The filters are also available as
parameters to the cgi, data, and value tags.
.PP
Filters can be applied in sequence and as many as needed can be
applied.
.PP
Here is an example. If you store your author or artist names in the
database \*(L"\s-1LAST\s0, First\*(R" so that they sort properly, you still might
want to display them normally as \*(L"First Last\*(R". This call
.PP
.Vb 1
\& [filter op="name namecase"]WOOD, Grant[/filter]
.Ve
will display as
.PP
.Vb 1
\& Grant Wood
.Ve
Another way to do this would be:
.PP
.Vb 1
\& [data table=products column=artist key=99-102 filter="name namecase"]
.Ve
Filters available include:
.PP
Length filter
.PP
If you pass just a numeric argument, filter will return only first N
characters. For example:
.PP
.Vb 1
\& [filter 5]Interchange[/filter]
.Ve
results in:
.PP
\&\*(L"Inter\*(R"
.PP
By appending a \*(L".\*(R", you can direct Interchange to append an ellipsis:
.PP
.Vb 1
\& [filter 5.]Interchange[/filter]
.Ve
results in:
.PP
\&\*(L"Inter...\*(R"
.PP
.Vb 5
\& if (/^(\ed+)(\e.?)$/) {
\& substr($value, $1) = $2 ? '...' : ''
\& if length($value) > $1;
\& next;
\& }
.Ve
\&\fIcgi\fR
.PP
Returns the value of the \s-1CGI\s0 variable. Useful for starting a filter
sequence with a seed value.
.PP
.Vb 3
\& 'cgi' => sub {
\& return $CGI::values(shift);
\& },
.Ve
\&\fIdigits\fR
.PP
Returns only digits.
.PP
.Vb 5
\& 'digits' => sub {
\& my $val = shift;
\& $val =~ s/\eD+//g;
\& return $val;
\& },
.Ve
\&\fIdigits_dot\fR
.PP
Returns only digits and periods, i.e. [.0\-9]. Useful for decommifying
numbers.
.PP
.Vb 5
\& 'digits_dot' => sub {
\& my $val = shift;
\& $val =~ s/[^\ed.]+//g;
\& return $val;
\& },
.Ve
\&\fIdos\fR
.PP
Turns linefeeds into carriage-return / linefeed pairs.
.PP
.Vb 5
\& 'dos' => sub {
\& my $val = shift;
\& $val =~ s/\er?\en/\er\en/g;
\& return $val;
\& },
.Ve
\&\fIentities\fR
.PP
Changes \f(CW\*(C`<\*(C'\fR to <, " to ", etc.
.PP
.Vb 3
\& 'entities' => sub {
\& return HTML::Entities::encode(shift);
\& },
.Ve
\&\fIgate\fR
.PP
Performs a security screening by testing to make sure a corresponding
scratch variable has been set.
.PP
.Vb 5
\& 'gate' => sub {
\& my ($val, $var) = @_;
\& return '' unless $::Scratch->{$var};
\& return $val;
\& },
.Ve
\&\fIlc\fR
.PP
Lowercases the text.
.PP
.Vb 3
\& 'lc' => sub {
\& return lc(shift);
\& },
.Ve
\&\fIlookup\fR
.PP
Looks up an item in a database based on the passed table and column.
Call would be:
.PP
.Vb 1
\& [filter op="uc lookup.country.name"]US[/filter]
.Ve
This would be the equivalent of [data table=country column=name
key=US].
.PP
.Vb 4
\& 'lookup' => sub {
\& my ($val, $tag, $table, $column) = @_;
\& return tag_data($table, $column, $val) || $val;
\& },
.Ve
\&\fImac\fR
.PP
Changes newlines to carriage returns.
.PP
.Vb 5
\& 'mac' => sub {
\& my $val = shift;
\& $val =~ s/\er?\en|\er\en?/\er/g;
\& return $val;
\& },
.Ve
\&\fIname\fR
.PP
Transposes a \s-1LAST\s0, First name pair.
.PP
.Vb 6
\& 'name' => sub {
\& my $val = shift;
\& return $val unless $val =~ /,/;
\& my($last, $first) = split /\es*,\es*/, $val, 2;
\& return "$first $last";
\& },
.Ve
\&\fInamecase\fR
.PP
Namecases the text. Only works on values that are uppercase in the
first letter, i.e. [filter op=namecase]LEONARDO da Vinci[/filter] will
return \*(L"Leonardo da Vinci\*(R".
.PP
.Vb 5
\& 'namecase' => sub {
\& my $val = shift;
\& $val =~ s/([A-Z]\ew+)/\eL\eu$1/g;
\& return $val;
\& },
.Ve
\&\fIno_white\fR
.PP
Strips all whitespace.
.PP
.Vb 5
\& 'no_white' => sub {
\& my $val = shift;
\& $val =~ s/\es+//g;
\& return $val;
\& },
.Ve
\&\fIpagefile\fR
.PP
Strips leading slashes and dots.
.PP
.Vb 4
\& 'pagefile' => sub {
\& $_[0] =~ s:^[./]+::;
\& return $_[0];
\& },
.Ve
\&\fIsql\fR
.PP
Change single-quote characters into doubled versions, i.e. ' becomes
\&''.
.PP
.Vb 5
\& 'sql' => sub {
\& my $val = shift;
\& $val =~ s:':'':g; # '
\& return $val;
\& },
.Ve
\&\fIstrip\fR
.PP
Strips leading and trailing whitespace.
.PP
.Vb 6
\& 'strip' => sub {
\& my $val = shift;
\& $val =~ s/^\es+//;
\& $val =~ s/\es+$//;
\& return $val;
\& },
.Ve
\&\fItext2html\fR
.PP
Rudimentary HTMLizing of text.
.PP
.Vb 6
\& 'text2html' => sub {
\& my $val = shift;
\& $val =~ s|\er?\en\er?\en||;
\& $val =~ s|\er?\en| |;
\& return $val;
\& },
.Ve
\&\fIuc\fR
.PP
Uppercases the text.
.PP
.Vb 3
\& 'uc' => sub {
\& return uc(shift);
\& },
.Ve
\&\fIunix\fR
.PP
Removes those crufty carriage returns.
.PP
.Vb 5
\& 'unix' => sub {
\& my $val = shift;
\& $val =~ s/\er?\en/\en/g;
\& return $val;
\& },
.Ve
\&\fIurlencode\fR
.PP
Changes non-word characters (except colon) to \f(CW%3c\fR notation.
.PP
.Vb 5
\& 'urlencode' => sub {
\& my $val = shift;
\& $val =~ s|[^\ew:]|sprintf "%%%02x", ord $1|eg;
\& return $val;
\& },
.Ve
\&\fIvalue\fR
.PP
Returns the value of the user session variable. Useful for starting a
filter sequence with a seed value.
.PP
.Vb 3
\& 'value' => sub {
\& return $::Values->(shift);
\& },
.Ve
\&\fIword\fR
.PP
Only returns word characters. Locale does apply if collation is
properly set.
.PP
.Vb 5
\& 'word' => sub {
\& my $val = shift;
\& $val =~ s/\eW+//g;
\& return $val;
\& },
.Ve
You can define your own filters in a \fIGlobalSub\fR (or Sub or
ActionMap):
.PP
.Vb 1
\& package Vend::Interpolate;
.Ve
.Vb 1
\& $Filter{reverse} = sub { $val = shift; return scalar reverse $val };
.Ve
That filter will reverse the characters sent.
.PP
The arguments sent to the subroutine are the value to be filtered, any
associated variable or tag name, and any arguments appended to the
filter name with periods as the separator.
.PP
A [filter op=lookup.products.price]99\-102[/filter] will send
('99\-102', undef, 'products', 'price') as the parameters. Assuming the
value of the user variable foo is bar, the call [value
name=foo filter=\*(L"lookup.products.price.extra\*(R"] will send ('bar',
\&'foo', 'products', 'price', 'extra').
.PP
\&\fIop\fR
.Sh "flag"
.IX Subsection "flag"
Controls Interchange flags. For example, flags affect database access
and transactions for those databases able to support these features.
See also the [tag] tag.
.PP
Summary
.PP
.Vb 1
\& [flag type]
.Ve
.Vb 15
\& Parameters Description Default
\& build Forces build of static Interchange page specified by the name attributeDEFAULT_VALUE
\& checkhtml DEFAULT_VALUE
\& commit Attempts to commit transactions DEFAULT_VALUE
\& flag Alias for type DEFAULT_VALUE
\& name Alias for type DEFAULT_VALUE
\& read Flags the table read-only DEFAULT_VALUE
\& rollback Attempts to rollback transactions DEFAULT_VALUE
\& show Normally, the [flag] tag returns nothing to the page. Setting 'show=1' causes the tag to return status, if any.DEFAULT_VALUE
\& table Alias for tables DEFAULT_VALUE
\& tables The name of the table to flag'table' is an aliasDEFAULT_VALUE
\& transactions Reopens the database in transactions mode if Safe.pm is not active (e.g., in a global subroutine, usertag or [perl global=1] tag). The limitation exists because it is not possible to reopen a database within Safe.pm.DEFAULT_VALUE
\& type DEFAULT_VALUE
\& value The boolean value of the flag DEFAULT_VALUE
\& write Flags the table writable by default (or read-only if you also set the value=0 attribute)DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [flag type]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->flag( { type => VALUE_type
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->flag(type, $attribute_hash_reference, $body);
.Ve
Description
.PP
The flag tag controls database access and transactions.
.PP
If a DBM-based database is to be modified, it must be flagged writable
on the page calling the write tag.
.PP
For example, you can call
.PP
.Vb 1
\& [flag type=write value=1 table=products]
.Ve
to mark the products \s-1DBM\s0 database writable. \fBThis must be done
before \s-1ANY\s0 access to that table.\fR
.PP
Note that \s-1SQL\s0 databases are always writable if allowed by the \s-1SQL\s0
database itself, and in-memory databases will never be written.
.PP
Using [flag build] forces static build of a page, even if it
contains dynamic elements.
.PP
\&\fIbuild\fR
.PP
Forces build of static Interchange page specified by the name
attribute
.PP
\&\fIcheckhtml\fR
.PP
\&\fIcommit\fR
.PP
Attempts to commit transactions
.PP
\&\fIread\fR
.PP
Flags the table read-only
.PP
\&\fIrollback\fR
.PP
Attempts to rollback transactions
.PP
\&\fIshow\fR
.PP
Normally, the [flag] tag returns nothing to the page. Setting
\&'show=1' causes the tag to return status, if any.
.PP
\&\fItables\fR
.PP
The name of the table to flag
.Ip "\(bu" 4
\&'table' is an alias
.PP
\&\fItransactions\fR
.PP
Reopens the database in transactions mode if \fISafe.pm\fR is not active
(e.g., in a global subroutine, usertag or [perl global=1] tag). The
limitation exists because it is not possible to reopen a database
within \fISafe.pm\fR.
.PP
\&\fItype\fR
.PP
\&\fIvalue\fR
.PP
The boolean value of the flag
.PP
\&\fIwrite\fR
.PP
Flags the table writable by default (or read-only if you also set the
value=0 attribute)
.Sh "fly-list"
.IX Subsection "fly-list"
Summary
.PP
Parameters: \fBcode base\fR
.PP
Positional parameters in same order.
.PP
Pass attribute hash as last to subroutine: \fBno\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
This is a container tag, i.e. [fly-list] \s-1FOO\s0 [/fly-list]. Nesting: \s-1NO\s0
.PP
Invalidates cache: \fBno\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 7
\& $Tag->fly_list(
\& {
\& code => VALUE,
\& base => VALUE,
\& },
\& BODY
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 2
\& $Tag->fly_list($code, $base, $BODY);
\& [fly-list code base]
.Ve
.Vb 3
\& Parameters Description Default
\& base DEFAULT_VALUE
\& code DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [fly-list code base]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 3
\& $Tag->fly_list( { base => VALUE_base
\& code => VALUE_code
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->fly_list(code,base, $attribute_hash_reference, $body);
.Ve
Description
.PP
Syntax: [fly-list prefix=tag_prefix* code=code*]
.PP
Defines an area in a random page which performs the flypage lookup
function, implementing the tags below.
.PP
.Vb 3
\& [fly-list]
\& (contents of flypage.html)
\& [/fly-list]
.Ve
If you place the above around the contents of the demo flypage, in a
file named flypage2.html, it will make these two calls display
identical pages:
.PP
.Vb 2
\& [page 00-0011] One way to display the Mona Lisa
\& [page flypage2 00-0011] Another way to display the Mona Lisa
.Ve
If you place a [fly-list] tag alone at the top of the page, it will
cause any page to act as a flypage.
.PP
By default, the prefix is item, meaning the [item-code] tag will
display the code of the item, the [item-price] tag will display
price, etc. But if you use the prefix, i.e. [fly-list prefix=fly],
then it will be [fly-code]; prefix=foo would cause [foo-code],
etc.
.PP
\&\fIbase\fR
.PP
\&\fIcode\fR
.Sh "fly-tax"
.IX Subsection "fly-tax"
Summary
.PP
Parameters: \fBarea\fR
.PP
Positional parameters in same order.
.PP
Pass attribute hash as last to subroutine: \fBno\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
Invalidates cache: \fBno\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 5
\& $Tag->fly_tax(
\& {
\& area => VALUE,
\& }
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 2
\& $Tag->fly_tax($area);
\& [fly-tax area]
.Ve
.Vb 2
\& Parameters Description Default
\& area DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [fly-tax area]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->fly_tax( { area => VALUE_area
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->fly_tax(area, $attribute_hash_reference, $body);
.Ve
Description
.PP
Builds a tax rate from \s-1TAXAREA\s0, \s-1TAXRATE\s0, and \s-1TAXSHIPPING\s0
\&\fIVariable\fR values, and the \fISalesTax\fR directive value.
.PP
\&\fIarea\fR
.Sh "goto"
.IX Subsection "goto"
Skips page content between [goto \fIname\fR] and [label \fIname\fR].
Note that the goto tag is not interpreted in the standard way, and
you cannot use the '$Tag->\fIgoto()\fR' Perl syntax. Note also that skipping
endtags with goto will probably break your page.
.PP
Summary
.PP
.Vb 3
\& [goto name=label_name if=condition]
\& content to skip
\& [label name=label_name]
.Ve
or positionally,
.PP
.Vb 3
\& [goto name if]
\& content to skip
\& [label name]
.Ve
.Vb 3
\& Parameters Description Default
\& name The name set in the corresponding [label] tagnone
\& if Condition for goto. Should evaluate to truth value before tag is parsed.true
.Ve
.Vb 3
\& Other_Characteristics
\& Container tag No, but you use it like this:[goto name=label_name if=condition]body text[label label_name]
\& Has Subtags [label] interpreted by goto
.Ve
\&\fBASP-like Perl call:\fR
.PP
No Perl call available (Note that this tag is not parsed in the
standard way).
.PP
Description
.PP
Skips page content between [goto \fIname\fR] and [label \fIname\fR].
Note that the goto tag is not interpreted in the standard way, and
you cannot use the '$Tag->\fIgoto()\fR' Perl syntax. Note also that skipping
endtags with goto will probably break your page.
.PP
The correspondingly named [label] tag marks the end of the page
content the goto should skip. Note that the [label] tag is not
an end tag, but simply a marker for the end of the text to skip.
.PP
\&\fBTechnical note (Interchange 4.8): \fRThis tag may not work properly if
you have more than one goto/label pair on a page.
.PP
\&\fIname\fR
.PP
This should match the name set in a [label] tag \fIafter\fR the goto tag
in the page (i.e., don't create loops).
.PP
\&\fIif\fR
.PP
Condition for goto. If the argument to 'if' is true, the tag will
skip the text between the goto and . Note that the tag
itself does not evaluate the condition. The condition must evaluate to
a true or false value before the goto tag processes it.
.PP
For example, this will not execute the goto:
.PP
.Vb 2
\& [set go]0[/set]
\& [goto name="there" if="[scratch go]"]
.Ve
.Sh "handling"
.IX Subsection "handling"
Summary
.PP
Parameters: \fBmode\fR
.PP
Positional parameters in same order.
.PP
\&\fBThe attribute hash reference is passed\fR to the subroutine after the
parameters as the last argument. \fBThis may mean that there are
parameters not shown here.\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
Invalidates cache: \fB\s-1YES\s0\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 5
\& $Tag->handling(
\& {
\& mode => VALUE,
\& }
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 1
\& $Tag->handling($mode, $ATTRHASH);
.Ve
Attribute aliases
.PP
.Vb 5
\& carts ==> cart
\& modes ==> mode
\& name ==> mode
\& tables ==> table
\& [handling mode other_named_attributes]
.Ve
.Vb 6
\& Parameters Description Default
\& carts Alias for cart DEFAULT_VALUE
\& mode DEFAULT_VALUE
\& modes Alias for mode DEFAULT_VALUE
\& name Alias for mode DEFAULT_VALUE
\& tables Alias for table DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [handling mode]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->handling( { mode => VALUE_mode
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->handling(mode, $attribute_hash_reference, $body);
.Ve
Description
.PP
Calculates and inserts handling costs. Accepts the same noformat and
convert arguments as the shipping tag.
.PP
\&\fIcart\fR
.PP
\&\fImode\fR
.PP
\&\fItable\fR
.Sh "harness"
.IX Subsection "harness"
Test harness block. Similar to try/catch. Interprets the body text and
checks the return value against expected and explicitly bad cases.
.PP
Returns \s-1DIED\s0, \s-1OK\s0, or \s-1NOT\s0 \s-1OK\s0 message along with your result if not the
expected value.
.PP
Summary
.PP
.Vb 1
\& [harness other_named_attributes]
.Ve
.Vb 3
\& Parameters Description Default
\& expected Tagname for delimiting your expected return value (default "OK")DEFAULT_VALUE
\& name This will appear in your output message (useful for distinguishing harness tags from one another) (default "testnnn")DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [harness]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->harness( {
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->harness(, $attribute_hash_reference, $body);
.Ve
Description
.PP
Test harness block. Similar to try/catch. Interprets the body text and
checks the return value against expected and explicitly bad cases.
.PP
Returns \s-1DIED\s0, \s-1OK\s0, or \s-1NOT\s0 \s-1OK\s0 message along with the harness name and
your result if not the expected value.
.PP
\&\fIexpected\fR
.PP
Tagname for delimiting your expected return value (default \*(L"\s-1OK\s0\*(R")
.PP
\&\fIname\fR
.PP
This will appear in your output message (useful for distinguishing
harness tags from one another) (default "test\fInnn\fR")
.Sh "href"
.IX Subsection "href"
Alias for [\fIarea\fR] tag.
.Sh "html-table"
.IX Subsection "html-table"
Builds an \s-1HTML\s0 table
.PP
Summary
.PP
.Vb 1
\& [html-table other_named_attributes]
.Ve
.Vb 9
\& Parameters Description Default
\& columns Whitespace-delimited list of columns DEFAULT_VALUE
\& delimiter Line delimiter to use if tag body is delimited text rather than an array reference (default "\et")DEFAULT_VALUE
\& fc HTML attributes for in the first cellDEFAULT_VALUE
\& fr HTML attributes for in the first row DEFAULT_VALUE
\& record_delim Record delimiter to use if tag body is delimited text rather than an array reference (default "\en")DEFAULT_VALUE
\& td HTML attributes for DEFAULT_VALUE
\& th HTML attributes for DEFAULT_VALUE
\& tr HTML attributes for DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [html-table]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->html_table( {
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->html_table(, $attribute_hash_reference, $body);
.Ve
Description
.PP
Builds an \s-1HTML\s0 table
.PP
\&\fIcolumns\fR
.PP
Whitespace-delimited list of columns
.PP
\&\fIdelimiter\fR
.PP
Line delimiter to use if tag body is delimited text rather than an
array reference (default \*(L"\et\*(R")
.PP
\&\fIfc\fR
.PP
\&\s-1HTML\s0 attributes for <\s-1TD\s0> in the first cell
.PP
\&\fIfr\fR
.PP
\&\s-1HTML\s0 attributes for <\s-1TR\s0> in the first row
.PP
\&\fIrecord_delim\fR
.PP
Record delimiter to use if tag body is delimited text rather than an
array reference (default \*(L"\en\*(R")
.PP
\&\fItd\fR
.PP
\&\s-1HTML\s0 attributes for <\s-1TD\s0>
.PP
\&\fIth\fR
.PP
\&\s-1HTML\s0 attributes for <\s-1TH\s0>
.PP
\&\fItr\fR
.PP
\&\s-1HTML\s0 attributes for <\s-1TR\s0>
.Sh "if"
.IX Subsection "if"
Summary
.PP
Parameters: \fBtype term op compare\fR
.PP
\&\s-1THIS\s0 \s-1TAG\s0 \s-1HAS\s0 \s-1SPECIAL\s0 \s-1POSITIONAL\s0 \s-1PARAMETER\s0 \s-1HANDLING\s0.
.PP
Pass attribute hash as last to subroutine: \fBno\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
This is a container tag, i.e. [if] \s-1FOO\s0 [/if]. Nesting: \s-1NO\s0
.PP
Invalidates cache: \fB\s-1YES\s0\fR
.PP
Called Routine:
.PP
Called Routine for positional:
.PP
\&\fBASP-like Perl call:\fR
.PP
Not applicable. Any [if ...] call can be better and more efficiently
done with Perl.
.PP
Attribute aliases
.PP
.Vb 4
\& base ==> type
\& comp ==> compare
\& condition ==> compare
\& operator ==> op
.Ve
.Vb 9
\& Parameters Description Default
\& base Alias for type DEFAULT_VALUE
\& comp Alias for compare DEFAULT_VALUE
\& compare DEFAULT_VALUE
\& condition Alias for compare DEFAULT_VALUE
\& op DEFAULT_VALUE
\& operator Alias for op DEFAULT_VALUE
\& term DEFAULT_VALUE
\& type DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [if type term op compare]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 5
\& $Tag->if( { compare => VALUE_compare
\& op => VALUE_op
\& term => VALUE_term
\& type => VALUE_type
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->if(type,term,op,compare, $attribute_hash_reference, $body);
.Ve
Description
.PP
Named call example: [if type=\*(L"type\*(R" term=\*(L"field\*(R" op=\*(L"op\*(R"
compare=\*(L"compare\*(R"]
.PP
Positional call example: [if type field op compare]
.PP
negated: [if type=\*(L"!type\*(R" term=\*(L"field\*(R" op=\*(L"op\*(R" compare=\*(L"compare\*(R"]
.PP
Positional call example: [if !type field op compare]
.PP
Allows conditional building of \s-1HTML\s0 based on the setting of various
Interchange session and database values. The general form is:
.PP
.Vb 15
\& [if type term op compare]
\& [then]
\& If true, this is printed on the document.
\& The [then] [/then] is optional in most
\& cases. If ! is prepended to the type
\& setting, the sense is reversed and
\& this will be output for a false condition.
\& [/then]
\& [elsif type term op compare]
\& Optional, tested when if fails
\& [/elsif]
\& [else]
\& Optional, printed when all above fail
\& [/else]
\& [/if]
.Ve
The [if] tag can also have some variants:
.PP
.Vb 3
\& [if type=explicit compare=`$perl_code`]
\& Displayed if valid Perl CODE returns a true value.
\& [/if]
.Ve
You can do some Perl-style regular expressions:
.PP
.Vb 12
\& [if value name =~ /^mike/]
\& This is the if with Mike.
\& [elsif value name =~ /^sally/]
\& This is an elsif with Sally.
\& [/elsif]
\& [elsif value name =~ /^pat/]
\& This is an elsif with Pat.
\& [/elsif]
\& [else]
\& This is the else, no name I know.
\& [/else]
\& [/if]
.Ve
While named parameter tag syntax works for [if ...], it is more
convenient to use positional calls in most cases. The only exception
is if you are planning on doing a test on the results of another tag
sequence:
.PP
.Vb 3
\& [if value name =~ /[value b_name]/]
\& Shipping name matches billing name.
\& [/if]
.Ve
Oops! This will not work. You must do instead
.PP
.Vb 3
\& [if base=value term=name op="=~" compare="/[value b_name]/"]
\& Shipping name matches billing name.
\& [/if]
.Ve
or better yet
.PP
.Vb 5
\& [if type=explicit compare=`
\& $Values->{name} =~ /$Values->{b_name}/
\& `]
\& Shipping name matches billing name.
\& [/if]
.Ve
Interchange also supports a limited [and ...] and [or ...] capability:
.PP
.Vb 4
\& [if value name =~ /Mike/]
\& [or value name =~ /Jean/]
\& Your name is Mike or Jean.
\& [/if]
.Ve
.Vb 4
\& [if value name =~ /Mike/]
\& [and value state =~ /OH/]
\& Your name is Mike and you live in Ohio.
\& [/if]
.Ve
If you wish to do very complex \s-1AND\s0 and \s-1OR\s0 operations, you will have to
use [if explicit] or better yet embedded Perl/ASP. This allows
complex testing and parsing of values.
.PP
There are many test targets available:
.PP
\&\fIconfig Directive\fR
.PP
The Interchange configuration variables. These are set by the
directives in your Interchange configuration file (or the defaults).
.PP
.Vb 3
\& [if config CreditCardAuto]
\& Auto credit card validation is enabled.
\& [/if]
.Ve
\&\fIdata database::field::key\fR
.PP
The Interchange databases. Retrieves a field in the database and
returns true or false based on the value.
.PP
.Vb 6
\& [if data products::size::99-102]
\& There is size information.
\& [else]
\& No size information.
\& [/else]
\& [/if]
.Ve
.Vb 6
\& [if data products::size::99-102 =~ /small/i]
\& There is a small size available.
\& [else]
\& No small size available.
\& [/else]
\& [/if]
.Ve
\&\fIdiscount\fR
.PP
Checks to see if a discount is present for an item.
.PP
.Vb 3
\& [if discount 99-102]
\& Item is discounted.
\& [/if]
.Ve
\&\fIexplicit\fR
.PP
A test for an explicit value. If Perl code is placed between a
[condition] [/condition] tag pair, it will be used to make the
comparison. Arguments can be passed to import data from user space,
just as with the [perl] tag.
.PP
.Vb 11
\& [if explicit]
\& [condition]
\& $country = '[value country]';
\& return 1 if $country =~ /u\e.?s\e.?a?/i;
\& return 0;
\& [/condition]
\& You have indicated a US address.
\& [else]
\& You have indicated a non-US address.
\& [/else]
\& [/if]
.Ve
This example is a bit contrived, as the same thing could be
accomplished with [if value country =~ /u\e.?s\e.?a?/i], but you will
run into many situations where it is useful.
.PP
This will work for \fIVariable\fR values:
.PP
.Vb 1
\& [if type=explicit compare="__MYVAR__"] .. [/if]
.Ve
However, note that the 'compare' option is equivalent to the
[condition] block in that both evaluate as Perl code. That means you
need to watch out when you put in user-supplied values (so that users
can't inject Perl code on your server) and data from your own
variables or tables which may look different than you expected.
.PP
For example, say you're in a loop checking whether at least one of the
fields 'foo' and 'bar' has a value (\*(L"true\*(R" according to Perl):
.PP
.Vb 1
\& [if type=explicit compare="[loop-param foo][loop-param bar]"]
.Ve
Most of the time this works fine. But if 'foo' contains a string
beginning with '0', such as '0009', Perl will try to interpret it as
an octal number, where the digit '9' is invalid, resulting in this
unexpected error in the catalog error log:
.PP
.Vb 1
\& Bad if 'explicit 0009': Illegal octal digit '9' at (eval 155) line 1, at end of line
.Ve
A safer way to check is:
.PP
.Vb 1
\& [if type=explicit compare="q{[loop-param foo][loop-param bar]}"]
.Ve
Although then your data should not contain a '}'. To be extra safe you
can surround your interpolated data with a [filter X] ... [/filter]
tag pair appropriate for the quoting method you've used.
.PP
\&\fIfile\fR
.PP
Tests for existence of a file. Useful for placing image tags only if
the image is present.
.PP
.Vb 3
\& [if type=file term="/home/user/www/images/[item-code].gif"]
\&
\& [/if]
.Ve
The file test requires that the \fISafeUntrap\fR directive contains
ftfile (which is the default).
.PP
\&\fIitems\fR
.PP
The Interchange shopping carts. If not specified, the cart used is the
main cart. Usually used as a litmus test to see if anything is in the
cart, for example:
.PP
.Vb 1
\& [if items]You have items in your shopping cart.[/if]
.Ve
.Vb 1
\& [if items layaway]You have items on layaway.[/if]
.Ve
\&\fIordered\fR
.PP
Order status of individual items in the Interchange shopping carts. If
not specified, the cart used is the main cart. The following items
refer to a part number of 99\-102.
.PP
.Vb 3
\& [if ordered 99-102] Item 99-102 is in your cart. [/if]
\& Checks the status of an item on order, true if item
\& 99-102 is in the main cart.
.Ve
.Vb 3
\& [if ordered 99-102 layaway] ... [/if]
\& Checks the status of an item on order, true if item
\& 99-102 is in the layaway cart.
.Ve
.Vb 3
\& [if ordered 99-102 main size] ... [/if]
\& Checks the status of an item on order in the main cart,
\& true if it has a size attribute.
.Ve
.Vb 3
\& [if ordered 99-102 main size =~ /large/i] ... [/if]
\& Checks the status of an item on order in the main cart,
\& true if it has a size attribute containing 'large'.
.Ve
.Vb 1
\& To make sure it is exactly large, you could use:
.Ve
.Vb 1
\& [if ordered 99-102 main size eq 'large'] ... [/if]
.Ve
\&\fIpragma\fR
.PP
The Interchange Pragma settings, set with the the catalog.cfg manpage directive
Pragma or with [pragma name].
.PP
.Vb 6
\& [if pragma dynamic_variables]
\& __THE_VARIABLE__
\& [else]
\& [data table=variable column=Variable key=THE_VARIABLE]
\& [/else]
\& [/if]
.Ve
\&\fIscratch\fR
.PP
The Interchange scratchpad variables, which can be set with the [set
name]value[/set] element.
.PP
.Vb 6
\& [if scratch mv_separate_items]
\& ordered items will be placed on a separate line.
\& [else]
\& ordered items will be placed on the same line.
\& [/else]
\& [/if]
.Ve
\&\fIsession\fR
.PP
the Interchange session variables. of particular interest are
\&\fIlogin\fR, \fIframes\fR, \fIsecure\fR, and \fIbrowser\fR.
.PP
\&\fIvalidcc\fR
.PP
a special case, takes the form [if validcc no type exp_date].
evaluates to true if the supplied credit card number, type of card,
and expiration date pass a validity test. does a Luhn-10 calculation
to weed out typos or phony card numbers. Uses the standard
CreditCardAuto variables for targets if nothing else is passed.
.PP
\&\fIvalue\fR
.PP
the Interchange user variables, typically set in search, control, or
order forms. Variables beginning with mv_ are Interchange special
values, and should be tested/used with caution.
.PP
The \fIfield\fR term is the specifier for that area. For example, [if
session logged_in] would return true if the logged_in session
parameter was set.
.PP
As an example, consider buttonbars for frame-based setups. It would be
nice to display a different buttonbar (with no frame targets) for
sessions that are not using frames:
.PP
.Vb 6
\& [if scratch frames]
\& __BUTTONBAR_FRAMES__
\& [else]
\& __BUTTONBAR__
\& [/else]
\& [/if]
.Ve
Another example might be the when search matches are displayed. If you
use the string '[value mv_match_count] titles found', it will display
a plural for only one match. Use:
.PP
.Vb 6
\& [if value mv_match_count != 1]
\& [value mv_match_count] matches found.
\& [else]
\& Only one match was found.
\& [/else]
\& [/if]
.Ve
The \fIop\fR term is the compare operation to be used. Compare operations
are as in Perl:
.PP
.Vb 8
\& == numeric equivalence
\& eq string equivalence
\& > numeric greater-than
\& gt string greater-than
\& < numeric less-than
\& lt string less-than
\& != numeric non-equivalence
\& ne string non-equivalence
.Ve
Any simple perl test can be used, including some limited regex
matching. More complex tests are best done with [if explicit].
.PP
[then] text [/then]
.PP
This is optional if you are not nesting if conditions, as the text
immediately following the [if ..] tag is used as the conditionally
substituted text. If nesting [if ...] tags you should use a
[then][/then] on any outside conditions to ensure proper
interpolation.
.PP
[elsif type field op* compare*]
.PP
named attributes: [elsif type=\*(L"type\*(R" term=\*(L"field\*(R" op=\*(L"op\*(R"
compare=\*(L"compare\*(R"]
.PP
Additional conditions for test, applied if the initial [if ..] test
fails.
.PP
[else] text [/else]
.PP
The optional else-text for an if or [if-field] conditional.
.PP
[condition] text [/condition]
.PP
Only used with the [if explicit] tag. Allows an arbitrary expression
\&\fBin Perl\fR to be placed inside, with its return value interpreted as
the result of the test. If arguments are added to [if explicit args],
those will be passed as arguments are in the [\fIperl\fR] construct.
.PP
\&\fIcompare\fR
.PP
\&\fIop\fR
.PP
\&\fIterm\fR
.PP
\&\fItype\fR
.Sh "import"
.IX Subsection "import"
Summary
.PP
Parameters: \fBtable type\fR
.PP
Positional parameters in same order.
.PP
\&\fBThe attribute hash reference is passed\fR after the parameters but
before the container text argument. \fBThis may mean that there are
parameters not shown here.\fR
.PP
Interpolates \fBcontainer text\fR by default.
.PP
This is a container tag, i.e. [import] \s-1FOO\s0 [/import]. Nesting: \s-1NO\s0
.PP
Invalidates cache: \fB\s-1YES\s0\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 7
\& $Tag->import(
\& {
\& table => VALUE,
\& type => VALUE,
\& },
\& BODY
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 1
\& $Tag->import($table, $type, $ATTRHASH, $BODY);
.Ve
Attribute aliases
.PP
.Vb 3
\& base ==> table
\& database ==> table
\& [import table type other_named_attributes]
.Ve
.Vb 5
\& Parameters Description Default
\& base Alias for table DEFAULT_VALUE
\& database Alias for table DEFAULT_VALUE
\& table DEFAULT_VALUE
\& type DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [import table type]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 3
\& $Tag->import( { table => VALUE_table
\& type => VALUE_type
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->import(table,type, $attribute_hash_reference, $body);
.Ve
Description
.PP
Named attributes:
.PP
.Vb 4
\& [import table=table_name
\& type=(TAB|PIPE|CSV|%%|LINE)
\& continue=(NOTES|UNIX|DITTO)
\& separator=c]
.Ve
Import one or more records into a database. The type is any of the
valid Interchange delimiter types, with the default being defined by
the setting of the database \fI\s-1DELIMITER\s0\fR. The table must already be a
defined Interchange database table; it cannot be created on the fly.
(If you need that, it is time to use \s-1SQL\s0.)
.PP
The type of \s-1LINE\s0 and continue setting of \s-1NOTES\s0 is
particularly useful, for it allows you to name your fields and not
have to remember the order in which they appear in the database. The
following two imports are identical in effect:
.PP
.Vb 5
\& [import table=orders]
\& code: [value mv_order_number]
\& shipping_mode: [shipping-description]
\& status: pending
\& [/import]
.Ve
.Vb 5
\& [import table=orders]
\& shipping_mode: [shipping-description]
\& status: pending
\& code: [value mv_order_number]
\& [/import]
.Ve
The code or key must always be present, and is always named
code.
.PP
If you do not use \s-1NOTES\s0 mode, you must import the fields in the
same order as they appear in the \s-1ASCII\s0 source file.
.PP
The [import ....] \s-1TEXT\s0 [/import] region may contain multiple
records. If using \s-1NOTES\s0 mode, you must use a separator, which by
default is a form-feed character (^L).
.PP
\&\fItable\fR
.PP
\&\fItype\fR
.Sh "include"
.IX Subsection "include"
Summary
.PP
Parameters: \fBfile locale\fR
.PP
Positional parameters in same order.
.PP
Pass attribute hash as last to subroutine: \fBno\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
Invalidates cache: \fBno\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
Not applicable.
.PP
.Vb 1
\& [include file locale]
.Ve
.Vb 3
\& Parameters Description Default
\& file DEFAULT_VALUE
\& locale DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [include file locale]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 3
\& $Tag->include( { file => VALUE_file
\& locale => VALUE_locale
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->include(file,locale, $attribute_hash_reference, $body);
.Ve
Description
.PP
Same as [file name] except interpolates for all Interchange tags
and variables. Does \s-1NOT\s0 do locale translations.
.PP
\&\fIfile\fR
.PP
\&\fIlocale\fR
.Sh "index"
.IX Subsection "index"
Creates an index for the specified table.
.PP
Summary
.PP
.Vb 1
\& [index table other_named_attributes]
.Ve
.Vb 13
\& Parameters Description Default
\& base Alias for table DEFAULT_VALUE
\& basefile Database filename. Exports the table to this filename if old or missing before indexing. See also the export tag for additional relevant attributes such as delimiter type, etc.DEFAULT_VALUE
\& col alias for fields DEFAULT_VALUE
\& columns alias for fields DEFAULT_VALUE
\& database Alias for table DEFAULT_VALUE
\& export_only Just do the export if necessary (not the index).DEFAULT_VALUE
\& extension Index file extension (default "idx") DEFAULT_VALUE
\& fields field(s) to index DEFAULT_VALUE
\& fn alias for fields DEFAULT_VALUE
\& show_status Return '1' to the page if successful DEFAULT_VALUE
\& spec The index specification DEFAULT_VALUE
\& table DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [index table]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->index( { table => VALUE_table
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->index(table, $attribute_hash_reference, $body);
.Ve
Description
.PP
Creates an index for the specified table.
.PP
\&\fIbasefile\fR
.PP
Database filename. Exports the table to this filename if old or
missing before indexing. See also the export tag for additional
relevant attributes such as delimiter type, etc.
.PP
\&\fIcol\fR
.PP
alias for fields
.PP
\&\fIcolumns\fR
.PP
alias for fields
.PP
\&\fIexport_only\fR
.PP
Just do the export if necessary (not the index).
.PP
\&\fIextension\fR
.PP
Index file extension (default \*(L"idx\*(R")
.PP
\&\fIfields\fR
.PP
\&\fIfield\fR\|(s) to index
.PP
\&\fIfn\fR
.PP
alias for fields
.PP
\&\fIshow_status\fR
.PP
Return '1' to the page if successful
.PP
\&\fIspec\fR
.PP
The index specification
.PP
\&\fItable\fR
.Sh "item-list"
.IX Subsection "item-list"
Summary
.PP
Parameters: \fBname\fR
.PP
\&\fBThe attribute hash reference is passed\fR after the parameters but
before the container text argument. \fBThis may mean that there are
parameters not shown here.\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
This is a container tag, i.e. [item-list] \s-1FOO\s0 [/item-list]. Nesting:
\&\s-1NO\s0
.PP
Invalidates cache: \fB\s-1YES\s0\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& NOTE: This would not usually be used with embedded Perl -- a better
\& choice would normally be:
.Ve
.Vb 1
\& for(@$Items) { CODE }
.Ve
.Vb 6
\& $Tag->item_list(
\& {
\& name => VALUE,
\& },
\& BODY
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 1
\& $Tag->item_list($name, $ATTRHASH, $BODY);
.Ve
Attribute aliases
.PP
.Vb 2
\& cart ==> name
\& [item-list name other_named_attributes]
.Ve
.Vb 3
\& Parameters Description Default
\& cart Alias for name DEFAULT_VALUE
\& name DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [item-list name]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->item_list( { name => VALUE_name
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->item_list(name, $attribute_hash_reference, $body);
.Ve
Description
.PP
Within any page, the [item-list cart*] element shows a list of all
the items ordered by the customer so far. It works by repeating the
source between [item-list] and [/item-list] once for each item
ordered.
.PP
\&\s-1NOTE:\s0 The special tags that reference item within the list are not
normal Interchange tags, do not take named attributes, and cannot be
contained in an \s-1HTML\s0 tag (other than to substitute for one of its
values or provide a conditional container). They are interpreted only
inside their corresponding list container. Normal Interchange tags can
be interspersed, though they will be interpreted \fIafter\fR all of the
list-specific tags.
.PP
Between the [item-list] markers the following elements will return
information for the current item:
.PP
[if-data table column]
.PP
If the database field column in table \fItable\fR is non-blank, the
following text up to the [/if-data] tag is substituted. This can be
used to substitute \s-1IMG\s0 or other tags only if the corresponding source
item is present. Also accepts an [else]else text[/else] pair for
the opposite condition.
.PP
[if-data ! table column]
.PP
Reverses sense for [if-data].
.PP
[/if-data]
.PP
Terminates an [if-data table column] element.
.PP
[if-field fieldname]
.PP
If the products database field \fIfieldname\fR is non-blank, the
following text up to the [/if-field] tag is substituted. If you
have more than one products database table (see ProductFiles), it
will check them in order until a matching key is found. This can be
used to substitute \s-1IMG\s0 or other tags only if the corresponding source
item is present. Also accepts an [else]else text[/else] pair for
the opposite condition.
.PP
[if-field ! fieldname]
.PP
Reverses sense for [if-field].
.PP
[/if-field]
.PP
Terminates an [if-field fieldname] element.
.PP
[item-accessories attribute*, type*, field*, database*, name*]
.PP
Evaluates to the value of the Accessories database entry for the item.
If passed any of the optional arguments, initiates special processing
of item attributes based on entries in the product database.
.PP
[item-code]
.PP
Evaluates to the product code for the current item.
.PP
[item-data database fieldname]
.PP
Evaluates to the field name \fIfieldname\fR in the arbitrary database
table \fIdatabase\fR, for the current item.
.PP
[item-description]
.PP
Evaluates to the product description (from the products file) for the
current item.
.PP
In support of OnFly, if the description field is not found in the
database, the description setting in the shopping cart will be used
instead.
.PP
[item-field fieldname]
.PP
Evaluates to the field name \fIfieldname\fR in the products database, for
the current item. If the item is not found in the first of the
ProductFiles, all will be searched in sequence.
.PP
[item-increment]
.PP
Evaluates to the number of the item in the match list. Used for
numbering search matches or order items in the list.
.PP
[item-last]tags[/item-last]
.PP
Evaluates the output of the Interchange tags encased inside the tags,
and if it evaluates to a numerical non-zero number (i.e. 1, 23, or \-1)
then the list iteration will terminate. If the evaluated number is
\&\fBnegative\fR, then the item itself will be skipped. If the evaluated
number is \fBpositive\fR, then the item itself will be shown but will be
last on the list.
.PP
.Vb 5
\& [item-last][calc]
\& return -1 if '[item-field weight]' eq '';
\& return 1 if '[item-field weight]' < 1;
\& return 0;
\& [/calc][/item-last]
.Ve
If this is contained in your [item-list] (or [search-list] or
flypage) and the weight field is empty, then a numerical \-1 will be
output from the [calc][/calc] tags; the list will end and the item
will \fBnot\fR be shown. If the product's weight field is less than 1, a
numerical 1 is output. The item will be shown, but will be the last
item shown. (If it is an [item-list], any price for the item will
still be added to the subtotal.)
.PP
[item-modifier attribute]
.PP
Evaluates to the modifier value of attribute for the current item.
.PP
[item-next]tags[/item_next]
.PP
Evaluates the output of the Interchange tags encased inside, and if it
evaluates to a numerical non-zero number (i.e. 1, 23, or \-1) then the
item will be skipped with no output. Example:
.PP
.Vb 1
\& [item-next][calc][item-field weight] < 1[/calc][/item-next]
.Ve
If this is contained in your [item-list] (or [search-list] or
flypage) and the product's weight field is less than 1, then a
numerical 1 will be output from the [calc][/calc] operation. The
item will not be shown. (If it is an [item-list], any price for the
item will still be added to the subtotal.)
.PP
[item-price n* noformat*]
.PP
Evaluates to the price for quantity n (from the products file) of
the current item, with currency formatting. If the optional \*(L"noformat\*(R"
is set, then currency formatting will not be applied.
.PP
[item-discount-price n* noformat*]
.PP
Evaluates to the discount price for quantity n (from the products
file) of the current item, with currency formatting. If the optional
\&\*(L"noformat\*(R" is set, then currency formatting will not be applied.
Returns regular price if not discounted.
.PP
[item-discount]
.PP
Returns the difference between the regular price and the discounted
price.
.PP
[item-discount_subtotal]
.PP
Inserts the discounted subtotal of the ordered items.
.PP
[item-quantity]
.PP
Evaluates to the quantity ordered for the current item.
.PP
[item-subtotal]
.PP
Evaluates to the subtotal (quantity * price) for the current item.
Quantity price breaks are taken into account.
.PP
[item-modifier-name attribute]
.PP
Evaluates to the name to give an input box in which the customer can
specify the modifier to the ordered item.
.PP
[quantity-name]
.PP
Evaluates to the name to give an input box in which the customer can
enter the quantity to order.
.PP
\&\fIname\fR
.Sh "label"
.IX Subsection "label"
The page label for goto. See [goto] tag for description. Note that
this is not a standard tag, but is simply a marker used by goto.
.PP
Parameter: \fBname\fR
.PP
.Vb 3
\& [goto name=label_name if=condition]
\& content to skip
\& [label name=label_name]
.Ve
Summary
.PP
\&\s-1NO\s0 \s-1SUMMARY\s0 \s-1SECTION\s0
.PP
.Vb 1
\& [label]
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache No
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [label]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->label( {
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->label(, $attribute_hash_reference, $body);
.Ve
Description
.PP
\&\s-1NO\s0 \s-1DESCRIPTION\s0 \s-1SECTION\s0
.Sh "log"
.IX Subsection "log"
Log contained text to specified file.
.PP
Summary
.PP
.Vb 1
\& [log file other_named_attributes]
.Ve
.Vb 9
\& Parameters Description Default
\& arg Alias for file DEFAULT_VALUE
\& create Set create=1 to create the file if not presentDEFAULT_VALUE
\& delim Line delimiter DEFAULT_VALUE
\& file name of file to log to. 'file=">filename"' also sets 'create' attribute.DEFAULT_VALUE
\& hide Suppress status otherwise returned by tag to the page.DEFAULT_VALUE
\& process Processing (if any) to apply to the content while loggingnostrip (don't strip leading/trailing whitespace and convert "\er\en" to "\en"DEFAULT_VALUE
\& record_delim Record delimiter DEFAULT_VALUE
\& type Log typetext (ordinary text file)quot (delimited entries)error (add Interchange error formatting and time/location stamps)DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [log file]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->log( { file => VALUE_file
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->log(file, $attribute_hash_reference, $body);
.Ve
Description
.PP
Log contained text to specified file.
.PP
\&\fIcreate\fR
.PP
Set create=1 to create the file if not present
.PP
\&\fIdelim\fR
.PP
Line delimiter
.PP
\&\fIfile\fR
.PP
name of file to log to. 'file=">\fIfilename\fR"' also sets 'create'
attribute.
.PP
\&\fIhide\fR
.PP
Suppress status otherwise returned by tag to the page.
.PP
\&\fIprocess\fR
.PP
Processing (if any) to apply to the content while logging
.Ip "\(bu" 4
nostrip (don't strip leading/trailing whitespace and convert \*(L"\er\en\*(R" to
\&\*(L"\en\*(R"
.PP
\&\fIrecord_delim\fR
.PP
Record delimiter
.PP
\&\fItype\fR
.PP
Log type
.Ip "\(bu" 4
text (ordinary text file)
.Ip "\(bu" 4
quot (delimited entries)
.Ip "\(bu" 4
error (add Interchange error formatting and time/location stamps)
.Sh "loop"
.IX Subsection "loop"
Summary
.PP
Parameters: \fBlist\fR
.PP
Positional parameters in same order.
.PP
\&\fBThe attribute hash reference is passed\fR after the parameters but
before the container text argument. \fBThis may mean that there are
parameters not shown here.\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
This is a container tag, i.e. [loop] \s-1FOO\s0 [/loop]. Nesting: \s-1NO\s0
.PP
Invalidates cache: \fBno\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& NOTE: This would not usually be used with embedded Perl -- a better
\& choice would normally be:
.Ve
.Vb 1
\& for(@list) { CODE }
.Ve
.Vb 6
\& $Tag->loop(
\& {
\& list => VALUE,
\& },
\& BODY
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 1
\& $Tag->loop($list, $ATTRHASH, $BODY);
.Ve
Attribute aliases
.PP
.Vb 3
\& arg ==> list
\& args ==> list
\& [loop list other_named_attributes]
.Ve
.Vb 4
\& Parameters Description Default
\& arg Alias for list DEFAULT_VALUE
\& args Alias for list DEFAULT_VALUE
\& list DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [loop list]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->loop( { list => VALUE_list
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->loop(list, $attribute_hash_reference, $body);
.Ve
Description
.PP
Returns a string consisting of the \s-1LIST\s0, repeated for every item in a
comma-separated or space-separated list. Operates in the same fashion
as the [item-list] tag, except for order-item-specific values.
Intended to pull multiple attributes from an item modifier \- but can
be useful for other things, like building a pre-ordained product list
on a page.
.PP
Loop lists can be nested reliably in Interchange by using the
prefix=\*(L"tag\*(R" parameter. New syntax:
.PP
.Vb 7
\& [loop list="A B C"]
\& [loop prefix=mid list="[loop-code]1 [loop-code]2 [loop-code]3"]
\& [loop prefix=inner list="X Y Z"]
\& [mid-code]-[inner-code]
\& [/loop]
\& [/loop]
\& [/loop]
.Ve
You can do an arbitrary search with the search=\*(L"args\*(R" parameter, just
as in a one-click search:
.PP
.Vb 3
\& [loop search="se=Americana/sf=category"]
\& [loop-code] [loop-field title]
\& [/loop]
.Ve
The above will show all items with a category containing the whole
world \*(L"Americana\*(R", and will work the same in both old and new syntax.
.PP
Ranges are accepted when you pass a list if you set the ranges
option:
.PP
.Vb 1
\& [loop list="A..Z" ranges=1][loop-code] [/loop]
.Ve
The above lists all of the characters from A to Z. Any Perl
incrementing variable list will work, but most commonly a range would
be something like 1..100. You can mix regular sets \*(-- 1..5 10 20
would produce the list 1 2 3 4 5 10 20.
.PP
If you surround the repeating text section with a [list] [/list]
anchor, the more-list, ml=N, and on-match / no-match processing is
done just as in [query] and [search-region].
.PP
Using the acclist option will parse Interchange option lists, as
used in product options. The value is available with [loop-code],
the label with [loop-param label]. If the size data for \s-1SKU\s0
\&\s-1TS-007\s0 was set to the string S=Small, M=Medium, L=Large, XL=Extra
Large then you could produce a select list of options this way:
.PP
.Vb 5
\& [loop list="[data products size TS-007]" acclist=1]
\& [on-match][/on-match]
\& [list] [loop-param label] [/list]
\& [on-match] [/on-match]
\& [/loop]
.Ve
Of course the above is probably more easily produced with
[accessories code=TS-007 attribute=size], but there will be other
uses for the capability. For instance:
.PP
.Vb 9
\&
\& [loop acclist=1
\& list="
\& Q1=Winter,
\& Q2=Spring,
\& Q3=Summer,
\& Q4=Fall
\& "]> [loop-param label]
\& [/loop]
.Ve
If your parameter list needs to have spaces in the parameters,
surround them with double or single quotes and set the quoted=1
option: in product options. If the size data for \s-1SKU\s0 \s-1TS-007\s0 was set
to the string S=Small, M=Medium, L=Large, XL=Extra Large then you
could produce a select list of options this way:
.PP
.Vb 5
\& [loop list="[data products size TS-007]" acclist=1]
\& [on-match][/on-match]
\& [list] [loop-param label] [/list]
\& [on-match] [/on-match]
\& [/loop]
.Ve
A nice shortcut is available when using [loop] to generate <\s-1OPTION\s0>
lists inside \s-1HTML\s0 <\s-1SELECT\s0>... blocks, when you want the
user's last selection to be chosen by default on subsequent page
views. Interchange simplifies this with functions that output
\&\*(L"\s-1SELECTED\s0\*(R" (surrounded by appropriate whitespace) for an <\s-1OPTION\s0> if a
certain value is set to the <\s-1OPTION\s0 VALUE=\*(L"...\*(R">. (It sounds more
complicated than it really is.)
.PP
For example, consider:
.PP
.Vb 14
\&
\&[loop
\& search="
\& fi=cat
\& st=db
\& ra=yes
\& rf=name
\& tf=name
\& un=1
\& "
\&]
\&[loop-code]
\&[/loop]
\&
.Ve
When the user returns to the page, their last selection will be chosen
as the default. (Assuming the value search_cat was set after the
search, which is normally is with standard searches.)
.PP
[loop] offers the option attribute, which can give loops that parse
faster and are easier to write. The following example is equivalent to
the one above:
.PP
.Vb 15
\&
\&[loop
\& option=search_cat
\& search="
\& fi=cat
\& st=db
\& ra=yes
\& rf=name
\& tf=name
\& un=1
\& "
\&]
\&[loop-code]
\&[/loop]
\&
.Ve
It works equally well when option values are explicitly specified:
.PP
.Vb 1
\& So-called "[loop-code]"
.Ve
See also the ictemplates documentation in the section \*(L"Checks and
Selections.\*(R"
.PP
[if-loop-data table column] \s-1IF\s0 [else] \s-1ELSE\s0 [/else][/if-loop-field]
.PP
Outputs the \s-1IF\s0 if the column in table is non-empty, and the \s-1ELSE\s0
(if any) otherwise.
.PP
See [\fIif-PREFIX-data\fR].
.PP
[if-loop-field column] \s-1IF\s0 [else] \s-1ELSE\s0 [/else][/if-loop-field]
.PP
Outputs the \fB\s-1IF\s0\fR if the column in the products table is
non-empty, and the \fB\s-1ELSE\s0\fR (if any) otherwise. Will fall through to
the first non-empty field if there are multiple ProductFiles.
.PP
See [\fIif-PREFIX-field\fR].
.PP
[if-loop-param param] \s-1IF\s0 [else] \s-1ELSE\s0 [/else][/if-loop-param]
.PP
Only works if you have named return fields from a search (or from a
passed list with the lr=1 parameter).
.PP
Outputs the \fB\s-1IF\s0\fR if the returned param is non-empty, and the
\&\fB\s-1ELSE\s0\fR (if any) otherwise.
.PP
See [if-PREFIX-param].
.PP
[if-loop-pos N] \s-1IF\s0 [else] \s-1ELSE\s0 [/else][/if-loop-pos]
.PP
Only works if you have multiple return fields from a search (or from a
passed list with the lr=1 parameter).
.PP
Parameters are numbered from ordinal 0, with [loop-pos 0] being the
equivalent of [loop-code].
.PP
Outputs the \fB\s-1IF\s0\fR if the returned positional parameter N is
non-empty, and the \fB\s-1ELSE\s0\fR (if any) otherwise.
.PP
See [if-PREFIX-pos].
.PP
[loop-accessories]
.PP
Outputs an [accessories ...] item.
.PP
See [\fIPREFIX-accessories\fR].
.PP
[loop-change marker]
.PP
See [\fIPREFIX-change\fR].
.PP
[loop-code]
.PP
Evaluates to the code for the current item.
.PP
See [\fIPREFIX-code\fR].
.PP
[loop-data database fieldname]
.PP
Evaluates to the field name \fIfieldname\fR in the arbitrary database
table \fIdatabase\fR, for the current item.
.PP
See [\fIPREFIX-data\fR].
.PP
[loop-description]
.PP
Evaluates to the product description (from the products file, passed
description in on-fly item, or description attribute in cart) for the
current item.
.PP
See [\fIPREFIX-description\fR].
.PP
[loop-field fieldname]
.PP
Evaluates to the field name \fIfieldname\fR in the database, for the
current item.
.PP
See [\fIPREFIX-field\fR].
.PP
[loop-increment]
.PP
Evaluates to the number of the item in the list. Used for numbering
items in the list.
.PP
Starts from integer 1.
.PP
See [\fIPREFIX-increment\fR].
.PP
[loop-last]tags[/loop-last]
.PP
Evaluates the output of the Interchange tags encased inside, and if it
evaluates to a numerical non-zero number (i.e. 1, 23, or \-1) then the
loop iteration will terminate. If the evaluated number is \fBnegative\fR,
then the item itself will be skipped. If the evaluated number is
\&\fBpositive\fR, then the item itself will be shown but will be last on
the list.
.PP
.Vb 5
\& [loop-last][calc]
\& return -1 if '[loop-field weight]' eq '';
\& return 1 if '[loop-field weight]' < 1;
\& return 0;
\& [/calc][/loop-last]
.Ve
If this is contained in your [loop list] and the weight field is
empty, then a numerical \-1 will be output from the [calc][/calc]
tags; the list will end and the item will \fBnot\fR be shown. If the
product's weight field is less than 1, a numerical 1 is output. The
item will be shown, but will be the last item shown.
.PP
[loop-next]tags[/loop-next]
.PP
Evaluates the output of the Interchange tags encased inside, and if it
evaluates to a numerical non-zero number (i.e. 1, 23, or \-1) then the
loop will be skipped with no output. Example:
.PP
.Vb 1
\& [loop-next][calc][loop-field weight] < 1[/calc][/loop-next]
.Ve
If this is contained in your [loop list] and the product's weight
field is less than 1, then a numerical 1 will be output from the
[calc][/calc] operation. The item will not be shown.
.PP
[loop-price n* noformat*]
.PP
Evaluates to the price for optional quantity n (from the products
file) of the current item, with currency formatting. If the optional
\&\*(L"noformat\*(R" is set, then currency formatting will not be applied.
.PP
\&\fIlist\fR
.Sh "mail"
.IX Subsection "mail"
Mail contained text to recipient specified by 'to' using the program
specified with the SendMailProgram catalog directive.
.PP
Summary
.PP
.Vb 1
\& [mail to other_named_attributes]
.Ve
.Vb 7
\& Parameters Description Default
\& extra Additional headers (these will also be added to 'raw' messages)DEFAULT_VALUE
\& hide Suppress tag return value. This would otherwise be the 'success' attribute setting.DEFAULT_VALUE
\& raw Send it raw without creating headers and checking content, recipient, subject, etc.DEFAULT_VALUE
\& show The tag will return the final message with headers in the pageDEFAULT_VALUE
\& success Tag return value if successful (default is 1).DEFAULT_VALUE
\& to DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->mail( { to => VALUE_to
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->mail(to, $attribute_hash_reference, $body);
.Ve
Description
.PP
Mail contained text to recipient specified by 'to' using the program
specified with the SendMailProgram catalog directive.
.PP
\&\fIextra\fR
.PP
Additional headers (these will also be added to 'raw' messages)
.PP
\&\fIhide\fR
.PP
Suppress tag return value. This would otherwise be the 'success'
attribute setting.
.PP
\&\fIraw\fR
.PP
Send it raw without creating headers and checking content, recipient,
subject, etc.
.PP
\&\fIshow\fR
.PP
The tag will return the final message with headers in the page
.PP
\&\fIsuccess\fR
.PP
Tag return value if successful (default is 1).
.PP
\&\fIto\fR
.Sh "mvasp"
.IX Subsection "mvasp"
Executes the ASP-style perl code contained by the tag. The code will
run under the restrictions of the \fISafe\fR module. This is very similar
to the [perl] tag, except that the standard '<%' and '%>' \s-1ASP\s0
delimiters allow you to mix \s-1HTML\s0 and perl code.
.PP
Summary
.PP
.Vb 2
\& [mvasp tables] ASP here [/mvasp]
\& [mvasp tables="db1 db2 ..." other_named_attributes] ASP here [/mvasp]
.Ve
.Vb 3
\& Parameters Description Default
\& tables Database tables to be made available to ASP Perl codenone
\& table Alias for tables none
.Ve
.Vb 9
\& Attributes Default
\& failure none
\& no_return Always true
\& subs No
\& arg="subs" Same as subs
\& global No
\& file none
\& interpolate No
\& reparse No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache Yes
\& Has Subtags <% and %>
\& Container tag Yes
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 11
\& [mvasp tables="products" failure="ASP Broke "]
\& This is HTML
\& <% my $sku = $Values->{code}; %>
\& More HTML
\& <% my $result = "Looked up SKU $sku. It is a ";
\& $result .= $Tag->data('products', 'description', $sku );
\& $Document->write( "$result \en" ); %>
\& Still more HTML
\& [/mvasp]
\&---
\& This is HTML
.Ve
.Vb 2
\& More HTML
\& Looked up SKU os28044. It is a Framing Hammer
.Ve
.Vb 1
\& Still more HTML
.Ve
See Also
.PP
\&\fIperl\fR, \fIInterchange Programming\fR
.PP
Description
.PP
Executes the ASP-style perl code contained by the tag. The code will
run under the restrictions of the \fISafe\fR module. This is very similar
to the [perl no_return=1] tag, except that the standard '<%' and
\&'%>' \s-1ASP\s0 delimiters allow you to mix \s-1HTML\s0 and perl code.
.PP
See the perl tag and \fIASP-Like Perl\fR sections for more detail.
.PP
\&\fItables\fR
.PP
Whitespace-separated list of database tables to make available within
the ASP-Perl code. See perl tag.
.PP
\&\fIfailure\fR
.PP
The value the tag should return in case the perl code fails the eval.
See perl tag.
.PP
\&\fIno_return\fR
.PP
The return value of the perl code is always suppressed. If you want
output from the \s-1ASP\s0 code sections, you must explicitly write it with
the &HTML or \f(CW$Document\fR->\fIwrite()\fR functions.
.PP
You can also retrieve the return value of the perl code from the
session hash via [\fIdata\fR session mv_perl_result]. See perl tag.
.PP
\&\fIsubs\fR
.PP
Enable \fIGlobalSub\fR routines (requires catalog directive
AllowGlobal). See perl tag.
.PP
\&\fIglobal\fR
.PP
Turn off \fISafe\fR protection (requires catalog directive
AllowGlobal). See perl tag.
.PP
\&\fIfile\fR
.PP
Prepend the contents of the specified file or FileDatabase entry to
the perl code before eval'ing it. See perl tag.
.PP
Examples
.PP
See the \fIASP-Like Perl\fR section of \fIInterchange Programming\fR.
.Sh "nitems"
.IX Subsection "nitems"
Returns the total number of items ordered. Uses the current cart if
none specified.
.PP
Summary
.PP
.Vb 1
\& [nitems name]
.Ve
.Vb 4
\& Parameters Description Default
\& compare Regular expression the specified qualifier attribute's value must match to be counted. This replaces the truth value comparison.Default: None (uses truth value of the specified qualifier attribute)DEFAULT_VALUE
\& name Cart nameDefault: current cart DEFAULT_VALUE
\& qualifier An item attribute that must be true in order to count the item.Default: NoneDEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [nitems name]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->nitems( { name => VALUE_name
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->nitems(name, $attribute_hash_reference, $body);
.Ve
Description
.PP
Expands into the total number of items ordered so far. Takes an
optional cart name as a parameter.
.PP
\&\fIcompare\fR
.PP
Regular expression the specified qualifier attribute's value must
match to be counted. This replaces the truth value comparison.
.Ip "\(bu" 4
Default: None (uses truth value of the specified qualifier
attribute)
.PP
\&\fIname\fR
.PP
Cart name
.Ip "\(bu" 4
Default: current cart
.PP
\&\fIqualifier\fR
.PP
An item attribute that must be true in order to count the item.
.Ip "\(bu" 4
Default: None
.Sh "options"
.IX Subsection "options"
Builds \s-1HTML\s0 widgets as defined in the options table for selecting
options associated with a given product. This tag handles simple,
matrix or modular options. See also the accessories tag.
.PP
Here is an illustrative example from the 'tools' sample data set of
the foundation catalog:
.PP
.Vb 16
\& ===
\& [options code=os28005]
\&---
\&
\&
\& Construct Something
\& Your Logo
\&
\& Black
\& Beige
\& White
\&
\&
\& Synthetic
\& Camel Hair
\&Z<>===
.Ve
Summary
.PP
.Vb 1
\& [options code]
.Ve
.Vb 8
\& Parameters Description Default
\& bold Boldfaces the labels if the 'label' option is set.Default: FalseDEFAULT_VALUE
\& code Product key (usually sku).No default DEFAULT_VALUE
\& joiner The joiner for the widgets.Default: DEFAULT_VALUE
\& label Shows labels for the options with the widgets.The following example (using another item from the 'tools' data) illustrates the price and label attributes:=== [options code=os28011 label=1 price=1]--- Handle Wood handle Ebony handle ($20.00) Blade material Plastic blade ($-1.22) Steel blade Titanium blade ($100.00) ===(again, the output has been reformatted to fit the page).Default: FalseDEFAULT_VALUE
\& price Boolean. If set and the options have prices, the HTML widget(s) will show the prices. This is like the price attribute of the accessories tag.Note that the price_data setting comes from the 'price' column of the options table.Technical note-- If your options table has different mappings, you can control this with $::Variable->{MV_OPTION_TABLE_MAP}False
\& table Table to use for option attributes.Default: 'options'DEFAULT_VALUE
\& td Results as table rows. For example, compare the following example from the 'tools' sample data set with the earlier example:=== [options code=os28005 td=1]--- Construct Something Your Logo Black Beige White Synthetic Camel Hair ===(Note that the output was reformatted to fit this page)DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [options code]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->options( { code => VALUE_code
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->options(code, $attribute_hash_reference, $body);
.Ve
Description
.PP
\&\s-1NO\s0 \s-1DESCRIPTION\s0 \s-1SECTION\s0
.PP
\&\fIbold\fR
.PP
Boldfaces the labels if the 'label' option is set.
.Ip "\(bu" 4
Default: False
.PP
\&\fIcode\fR
.PP
Product key (usually sku).
.Ip "\(bu" 4
No default
.PP
\&\fIjoiner\fR
.PP
The joiner for the widgets.
.Ip "\(bu" 4
Default: <\s-1BR\s0>
.PP
\&\fIlabel\fR
.PP
Shows labels for the options with the widgets.
.PP
The following example (using another item from the 'tools' data)
illustrates the price and label attributes:
.PP
.Vb 15
\& ===
\& [options code=os28011 label=1 price=1]
\&---
\& Handle
\&
\&
\& Wood handle
\& Ebony handle ($20.00)
\& Blade material
\&
\&
\& Plastic blade ($-1.22)
\& Steel blade
\& Titanium blade ($100.00)
\&Z<>===
.Ve
(again, the output has been reformatted to fit the page).
.Ip "\(bu" 4
Default: False
.PP
\&\fIprice\fR
.PP
Boolean. If set and the options have prices, the \s-1HTML\s0 \fIwidget\fR\|(s) will
show the prices. This is like the price attribute of the
accessories tag.
.Ip "" 4
Note that the price_data setting comes from the 'price' column of
the options table.
.Sp
Technical note\-\- If your options table has different mappings, you can
control this with \f(CW$::Variable\fR->{\s-1MV_OPTION_TABLE_MAP\s0}
.Ip "\(bu" 4
Default: False
.PP
\&\fItable\fR
.PP
Table to use for option attributes.
.Ip "\(bu" 4
Default: 'options'
.PP
\&\fItd\fR
.PP
Results as table rows. For example, compare the following example from
the 'tools' sample data set with the earlier example:
.PP
.Vb 16
\& ===
\& [options code=os28005 td=1]
\&---
\&
\&
\& Construct Something
\& Your Logo
\&
\& Black
\& Beige
\& White
\&
\&
\& Synthetic
\& Camel Hair
\&Z<>===
.Ve
(Note that the output was reformatted to fit this page)
.Sh "or"
.IX Subsection "or"
Summary
.PP
Parameters: \fBtype term op compare\fR
.PP
\&\s-1THIS\s0 \s-1TAG\s0 \s-1HAS\s0 \s-1SPECIAL\s0 \s-1POSITIONAL\s0 \s-1PARAMETER\s0 \s-1HANDLING\s0.
.PP
Pass attribute hash as last to subroutine: \fBno\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
Invalidates cache: \fBno\fR
.PP
Called Routine:
.PP
Called Routine for positional:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 8
\& $Tag->or(
\& {
\& type => VALUE,
\& term => VALUE,
\& op => VALUE,
\& compare => VALUE,
\& }
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 1
\& $Tag->or($type, $term, $op, $compare);
.Ve
Attribute aliases
.PP
.Vb 4
\& base ==> type
\& comp ==> compare
\& operator ==> op
\& [or type term op compare]
.Ve
.Vb 8
\& Parameters Description Default
\& base Alias for type DEFAULT_VALUE
\& comp Alias for compare DEFAULT_VALUE
\& compare DEFAULT_VALUE
\& op DEFAULT_VALUE
\& operator Alias for op DEFAULT_VALUE
\& term DEFAULT_VALUE
\& type DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [or type term op compare]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 5
\& $Tag->or( { compare => VALUE_compare
\& op => VALUE_op
\& term => VALUE_term
\& type => VALUE_type
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->or(type,term,op,compare, $attribute_hash_reference, $body);
.Ve
Description
.PP
\&\fB\s-1NO\s0 Description\fR
.PP
\&\fIcompare\fR
.PP
\&\fIop\fR
.PP
\&\fIterm\fR
.PP
\&\fItype\fR
.Sh "order"
.IX Subsection "order"
Expands into a hypertext link which will include the specified item in
the list of products to order and display the order page.
.PP
Summary
.PP
.Vb 2
\& [order code quantity]Link Text
\& [order code=os28044 quantity=2]Link Text
.Ve
.Vb 3
\& Parameters Description Default
\& code This is the unique identifier for the item, typically the SKU in the products tablenone
\& quantity Quantity to order 1
.Ve
.Vb 7
\& Attributes Default
\& code No
\& page SpecialPage order
\& cart main cart
\& base ProductFiles array
\& area off
\& interpolate (reparse) No
.Ve
.Vb 4
\& Other_Characteristics
\& Invalidates cache No
\& Container tag No
\& Has end tag No ([/order] is a macro for )
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 5
\& [order os28044 2]Buy Framing Hammer[/order]
\&---
\& Buy Framing Hammer
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 1
\& $Tag->order($code, $quantity);
.Ve
Description
.PP
Expands into a hypertext link which will include the specified code in
the list of products to order and display the order page.
.PP
\&\fBcode\fR should be a product code listed in one of the \*(L"products\*(R"
databases. The optional argument \fBbase\fR constrains the order to a
particular products file. If not specified, all tables defined as
ProductFiles will be searched in sequence for the item.
.PP
The optional argument \fBcart\fR selects the shopping cart where the item
will be placed.
.PP
\&\fBpage\fR allows you to specify a different order page than the default
one specified by SpecialPage order.
.PP
How to Order an Item
.PP
Interchange can either use a form-based order or a link-based order to
place an item in the shopping cart. The order tag creates a
link-based order.
.PP
You can use the area tag with form variables if you need more
control, for example, to change frames for the order:
.PP
.Vb 5
\& Order Framing Hammer
.Ve
This can also be done more easily with the area option to the
order tag:
.PP
.Vb 2
\& Order Framing Hammer
.Ve
To order with a form, you set the form variable mv_order_item to
the item-code/SKU and use the refresh action:
.PP
.Vb 3
\&
.Ve
Groups of items may be batched:
.PP
.Vb 2
\&
.Ve
Items that have a quantity of zero (or blank) will be skipped. Only
items with a positive quantity will be placed in the basket.
.PP
Attributes like size or color may be specified at time of order. See
the accessories tag for detail.
.Sh "page"
.IX Subsection "page"
Expands to a hyperlink to an Interchange page or action, including
surrounding . The \s-1URL\s0 within the link includes the
Interchange session \s-1ID\s0 and supplied arguments. The optional [/page] is
simply a macro for .
.PP
If you do not want the , use the \fIarea\fR tag instead \-
these are equivalent:
.PP
.Vb 2
\& [page href=dir/page arg=mv_arg]TargetName
\& TargetName
.Ve
Summary
.PP
.Vb 2
\& [page href arg]
\& [page href=dir/page arg=page_arguments other_named_attributes]
.Ve
.Vb 4
\& Parameters Description Default
\& href Path to Interchange page or actionSpecial arguments'scan' treats arg as a search argument'http://...' external link (requires form attribute)process
\& arg Interchange arguments to page or action none
\& base alias for arg none
.Ve
.Vb 6
\& Attributes Default
\& extra none
\& form none
\& search No
\& secure No
\& interpolate (reparse) No
.Ve
.Vb 4
\& Other_Characteristics
\& Invalidates cache No
\& Macro No
\& Has end tag No ([/page] is a macro for )
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 1
\& [page href=dir/page.html arg="arg1=AA/arg2=BB"]
.Ve
.Vb 2
\&
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->page( { href => "dir/page",
\& arg => "arguments", } );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->page($href, $arg, $attribute_hash_reference);
.Ve
Using arrayref for joined search (see also \fIAttribute Arrays and
Hashes\fR)
.PP
.Vb 2
\& my $searchref = [ "se=hammer/fi=products/sf=description",
\& "se=plutonium/fi=products/sf=description", ];
.Ve
.Vb 2
\& $Tag->page( { href => 'scan',
\& search => $searchref, } );
.Ve
See Also
.PP
\&\fIarea\fR
.PP
Description
.PP
The page tag inserts a hyperlink to the specified Interchange page
or action. For example, [page shirts] will expand into
.PP
.Vb 1
\&
.Ve
The catalog page displayed will come from \*(L"shirts.html\*(R" in the pages
directory.
.PP
The additional argument will be passed to Interchange and placed in
the {arg} session parameter. This allows programming of a conditional
page display based on where the link came from. The argument is then
available with the tag [data session arg], or the embedded Perl
session variable \f(CW$Session\fR->{arg}. Spaces and some other characters
will be escaped with the \f(CW%NN\fR HTTP-style notation and unescaped when
the argument is read back into the session.
.PP
For better performance, Interchange can prebuild and cache pages that
would otherwise be generated dynamically. If Interchange has built
such a static page for the target, the page tag produces a link to
the cached page whenever the user has accepted and sent back a cookie
with the session \s-1ID\s0. If the user did not accept the cookie,
Interchange cannot use the cache, since the link must then include the
\&\fImv_session_id\fR argument in order to preserve session.
.PP
\&\fIextra\fR
.PP
\&\fIform\fR
.PP
The optional form argument allows you to encode a form in the link.
.PP
.Vb 5
\& [page form="mv_order_item=os28044
\& mv_order_size=15oz
\& mv_order_quantity=1
\& mv_separate_items=1
\& mv_todo=refresh"] Order 15oz Framing Hammer
.Ve
The two form values \fImv_session_id\fR and \fImv_arg\fR are automatically
added when appropriate. The form value \fImv_arg\fR receives the value of
the tag's arg parameter.
.PP
This would generate a form that ordered quantity one of item number
os28044 with size 15oz. The item would appear on a separate line
in the shopping cart, since mv_separate_items is set. Since the
href is not set, you will go to the default shopping cart page \-
alternatively, you could have set mv_orderpage=yourpage to go to
yourpage.
.PP
All normal Interchange form caveats apply \- you must have an action,
you must supply a page if you don't want to go to the default, etc.
.PP
You can theoretically submit any form with this, though none of the
included values can have newlines or trailing whitespace. If you want
to do something like that you will have to write a UserTag.
.PP
If the parameter href is not supplied, \fIprocess\fR is used, causing
normal Interchange form processing.
.PP
If the href points to an http:// link, then no Interchange \s-1URL\s0
processing will be done, but the \s-1URL\s0 will include mv_session_id,
mv_pc, and any arguments supplied with the arg attribute:
.PP
.Vb 4
\& [page href="http://www.elsewhere.net/cgi/script"
\& form="cgi_1=ONE
\& cgi_2=TWO"
\& arg="Interchange argument"]External link
.Ve
.Vb 3
\& External link
.Ve
\&\fIsearch\fR
.PP
Interchange allows you to pass a search in a \s-1URL\s0. There are two ways
to do this:
.Ip "1." 4
Place the search specification in the named search attribute.
.RS 4
.Ip "\(bu" 8
Interchange will ignore the href parameter (the link will be set to
\&'scan'.
.Ip "\(bu" 8
If you give the arg parameter a value, that value will be available
as [value mv_arg] within the search display page.
.RE
.RS 4
.RE
.Ip "2." 4
Set the href parameter to 'scan' and set arg to the search
specification.
.RS 4
.Ip "\(bu" 8
Note that you can use this form positionally \- the values go into
href and arg, so you do not have to name parameters.
.RE
.RS 4
.RE
.PP
These are identical:
.PP
.Vb 5
\& [page scan
\& se=Impressionists
\& sf=category]
\& Impressionist Paintings
\&
.Ve
.Vb 5
\& [page href=scan
\& arg="se=Impressionists
\& sf=category"]
\& Impressionist Paintings
\&
.Ve
.Vb 4
\& [page search="se=Impressionists
\& sf=category"]
\& Impressionist Paintings
\&
.Ve
Here is the same thing from a non-Interchange page (e.g., a home
page), assuming '/cgi-bin/mycatalog' is the \s-1CGI\s0 path to Interchange's
vlink):
.PP
.Vb 3
\&
\& Impressionist Paintings
\&
.Ve
Sometimes, you will find that you need to pass characters that will
not be interpreted positionally. In that case, you should quote the
arguments:
.PP
.Vb 4
\& [page href=scan
\& arg=|
\& se="Something with spaces"
\& |]
.Ve
See the \fISearch and Form Variables\fR appendix for a listing of the
form variables along with two-letter abbreviations and descriptions.
.PP
They can be treated just the same as form variables on the page,
except that they can't contain spaces, '/' in a file name, or quote
marks. These characters can be used in \s-1URL\s0 hex encoding, i.e. \f(CW%20\fR is a
space, \f(CW%2F\fR is a /, etc. \- &sp; or will not be
recognized. If you use one of the methods below to escape these
\&\*(L"unsafe\*(R" characters, you won't have to worry about this.
.PP
You may specify a one-click search in three different ways. The first
is as used in previous versions, with the scan \s-1URL\s0 being specified
completely as the page name. The second two use the \*(L"argument\*(R"
parameter to the [page ...] or [area ...]> tags to specify the
search (an argument to a scan is never valid anyway).
.PP
\&\fIsecure\fR
.PP
Original syntax
.PP
If you wish to do an \s-1OR\s0 search on the fields category and artist for
the strings \*(L"Surreal\*(R" and \*(L"Gogh\*(R", while matching substrings, you would
do:
.PP
.Vb 3
\& [page scan se=Surreal/se=Gogh/os=yes/su=yes/sf=artist/sf=category]
\& Van Gogh -- compare to surrealists
\&
.Ve
In this method of specification, to replace a / (slash) in a file name
(for the sp, bd, or fi parameter) you must use the shorthand of ::,
i.e. sp=results::standard. (This may not work for some browsers, so
you should probably either put the page in the main pages directory or
define the page in a search profile.)
.PP
Ampersand syntax
.PP
You can substitute & for / in the specification and be able to use /
and quotes and spaces in the specification.
.PP
.Vb 3
\& [page scan se="Van Gogh"&sp=lists/surreal&os=yes&su=yes&sf=artist&sf=category]
\& Van Gogh -- compare to surrealists
\&
.Ve
Any \*(L"unsafe\*(R" characters will be escaped.
.PP
Multi-line syntax
.PP
You can specify parameters one to a line, as well.
.PP
.Vb 8
\& [page scan
\& se="Van Gogh"
\& sp=lists/surreal
\& os=yes
\& su=yes
\& sf=artist
\& sf=category
\& ] Van Gogh -- compare to surrealists
.Ve
Any \*(L"unsafe\*(R" characters will be escaped. You may not search for
trailing spaces in this method; it is allowed in the other notations.
.PP
Joined searches
.PP
You can also specify a joined search using an attribute array (see
\&\fIAttribute\ Arrays\ and\ Hashes\fR):
.PP
.Vb 8
\& [page href=scan
\& search.0="se=fragrant
\& fi=products
\& sf=smell"
\& search.1="se=purple
\& sf=color"
\& search.2="se=perennial
\& sf=type"]
.Ve
The search routine called by the page tag automatically adds the other
relevant search specification elements, including the 'co=yes' to
indicate a combined search (\fIjoined searches\fR are described in the
Interchange database documentation).
.PP
[/page]
.PP
This is not an actual end tag, but simply a macro that expands to
. The following two lines are equivalent:
.PP
.Vb 2
\& [page shirts]Our shirt collection[/page]
\& [page shirts]Our shirt collection
.Ve
Tip: In large pages, just use the tag for a small performance
improvement.
.Sh "perl"
.IX Subsection "perl"
Executes the perl code contained by the tag. The code will run under
the restrictions of Perl's \fISafe\fR module by default. The tag expands
to the value returned by the enclosed code (i.e., printing to \s-1STDOUT\s0
or \s-1STDERR\s0 is useless).
.PP
See also \fIInterchange Programming\fR.
.PP
Summary
.PP
.Vb 2
\& [perl tables] Code here [/perl]
\& [perl tables="db1 db2 ..." other_named_attributes] Code here [/perl]
.Ve
.Vb 3
\& Parameters Description Default
\& tables Database tables to be made available to ASP Perl codenone
\& table Alias for tables none
.Ve
.Vb 13
\& Attributes Default
\& failure none
\& no_return No
\& subs No
\& arg="subs" Same as subs
\& global No
\& file none
\& number_errors none
\& eval_label none
\& short_errors none
\& trim_errors none
\& interpolate No
\& reparse Yes
.Ve
.Vb 4
\& Other_Characteristics
\& Invalidates cache Yes
\& Has Subtags No
\& Container tag Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 7
\& [perl tables="products" failure="Perl code error "]
\& my $result = "Looked up SKU $Values->{code}. It is a ";
\& $result .= $Tag->data('products', 'description', $Values->{code} );
\& return ("$result \en");
\& [/perl]
\&---
\& Looked up SKU os28044. It is a Framing Hammer
.Ve
\&\fBASP-like Perl call:\fR (e.g., to use it like a runtime \fIeval()\fR within
your code)
.PP
.Vb 2
\& $Tag->perl( { tables => "products", },
\& $code );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->perl( $tables, $attribute_hash_reference );
.Ve
See Also
.PP
See also \fIInterchange Programming\fR, [calc], and [mvasp].
.PP
Description
.PP
This tag allows you to embed perl code within an Interchange page. The
code will run under the restrictions of Perl's \fISafe\fR module by
default. Perl's 'warnings' and 'strict' pragmas are both turned
off, and \fISafe\fR will block you from turning them on, since it blocks
Perl's 'use' command. (This is not usually a problem, since you
should probably use an alternative such as a usertag if your code is
complex enough to need strict.)
.PP
The tag expands to the value returned by the enclosed code (i.e.,
printing to \s-1STDOUT\s0 or \s-1STDERR\s0 is useless).
.PP
.Vb 5
\& [perl]
\& $name = $Values->{name};
\& $browser = $Session->{browser};
\& return "Hi, $name! How do you like your $browser?
\& [/perl]
.Ve
Object references are available for most Interchange tags and
functions, as well as direct references to Interchange session and
configuration values.
.PP
.Vb 17
\& Object Description
\& $CGI->{key} Hash reference to raw submitted values
\& $CGI_array->{key} Arrays of submitted values
\& $Carts->{cartname} Direct reference to shopping carts
\& $Config->{key} Direct reference to $Vend::Cfg
\& $DbSearch->array(@args) Do a DB search and get results
\& $Document->header() Writes header lines
\& $Document->send() Writes to output
\& $Document->write() Writes to page
\& $Scratch->{key} Direct reference to scratch area
\& $Session->{key} Direct reference to session area
\& $Tag->tagname(@args) Call a tag as a routine (UserTag too!)
\& $TextSearch->array(@args) Do a text search and get results
\& $Values->{key} Direct reference to user form values
\& $Variable->{key} Config variables (same as $Config->{Variable});
\& &HTML($html) Same as $Document->write($html);
\& &Log($msg) Log to the error log
.Ve
For full descriptions of these objects, see \fIInterchange Perl
Objects\fR.
.PP
\&\fItables\fR
.PP
This should be a whitespace-separated list of database tables you want
to make available within the Perl code.
.PP
If you wish to use database values in your Perl code, the tag must
pre-open the \fItable\fR\|(s) you will be using. Here is an example using the
products table:
.PP
.Vb 5
\& [perl tables=products]
\& my $cost = $Tag->data('products', 'our_cost', $Values->{code});
\& $min_price = $cost * ( 1 + $min_margin );
\& return ($min_price > $sale_price) ? $min_price : $sale_price;
\& [/perl]
.Ve
If you do not do this, your code will fail with a runtime \fISafe\fR
error when it tries to look up 'our_cost' in the products database
with the data tag.
.PP
Even if you properly specify the tables to pre-open, some database
operations will still be restricted because Safe mode prohibits
creation of new objects. For \s-1SQL\s0, most operations can be performed if
the Safe::Hole module is installed. Otherwise, you may have to set
the global=1 attribute to use data from \s-1SQL\s0 tables.
.PP
Interchange databases can always be accessed as long as they are
pre-opened by using an item first.
.PP
Technical note:
.PP
\&\fISafe\fR objects (including database handles) may persist within a
page, and the perl tag does not necessarily destroy objects created
earlier in the page. As a result, your code may work even though you
did not set 'tables' properly, only to break later when you change
something elsewhere on the page.
.PP
For example, this will work because the first call to [accessories
\&...] opens the (default) products table:
.PP
.Vb 1
\& [accessories code=os28044 attribute=size]
.Ve
.Vb 4
\& [perl]
\& return $Tag->accessories( { attribute => 'size',
\& code => 'os28085' } );
\& [/perl]
.Ve
If you remove the first [accessories ...] tag, then the
\&\f(CW$Tag\fR->accessories call will fail with a \fISafe\fR error unless you also
set 'tables=products' in the perl tag.
.PP
The moral of this story is to ensure that you pass all necessary
tables in the perl tag.
.PP
\&\fIfailure\fR
.PP
If your code contains a compile or runtime error and fails to evaluate
(i.e., eval($code) would set $@), the tag will return the value set
for the failure attribute. The error will be logged as usual.
.PP
For example,
.PP
.Vb 5
\& [perl failure="It Broke"]
\& my $cost = $Tag->data('products', 'our_cost', $Values->{code});
\& $min_price = $cost * ( 1 + $min_margin );
\& return ($min_price > $sale_price) ? $min_price : $sale_price;
\& [/perl]
.Ve
will return 'It Broke' because the \f(CW$Tag\fR->Data(...) call will fail
under the \fISafe\fR module (see \fItables\fR above).
.PP
\&\fIno_return\fR
.PP
If no_return=1, this attribute suppresses the return value of the
perl code.
.PP
You can retrieve the return value from the session hash via [\fIdata\fR
session mv_perl_result] until it gets overwritten by another perl
tag.
.PP
If no_return is set, the perl tag \fIwill\fR return any output
explicitly written with the &HTML or \f(CW$Document\fR->\fIwrite()\fR functions.
.PP
\&\fBNote: \fR
.PP
If no_return is \fInot\fR set, then the \f(CW$Document\fR->\fIwrite()\fR buffer is
not returned (unless you use \f(CW$Document\fR->\fIhot\fR\|(1) or \f(CW$Document\fR->\fIsend()\fR,
in which case the contents of the write buffer will probably appear
before anything else on the page). See \fIInterchange Perl Objects\fR for
more detail.
.PP
Here is an example:
.PP
.Vb 6
\& [perl tables=products no_return=1]
\& my $cost = $Tag->data('products', 'our_cost', $Values->{code});
\& $min_price = $cost * ( 1 + $min_margin );
\& &HTML( ($min_price > $sale_price) ? $min_price : $sale_price );
\& return ($min_price > $sale_price) ? 'too low' : 'ok';
\& [/perl]
.Ve
This will put the same price on the page as our earlier example, but
.PP
$Session->{mv_perl_result} will be either 'too low' or 'ok'.
.PP
The [mvasp] tag is very similar to [perl no_return=1].
.PP
\&\fIsubs\fR
.PP
If you have set the AllowGlobal catalog directive, setting
subs=1 will enable you to call \fIGlobalSub\fR routines within the
enclosed perl code. Note that this can compromise security.
.PP
\&\fIglobal\fR
.PP
If you have set the AllowGlobal catalog directive, setting
global=1 will turn off \fISafe\fR protection within the tag.
.PP
The code within the tag will then be able to do anything the user \s-1ID\s0
running Interchange can. This seriously compromises security, and you
should know what you are doing before using it in a public site. It is
especially dangerous if a single Interchange server is shared by
multiple companies or user IDs.
.PP
Also, full 'use strict' checking is turned on by default when in
global mode. You can turn it off by using 'no strict;' within your
code. Note that any strict errors will go to the Interchange error
logs, and the tag itself will fail silently within the page.
.PP
\&\fIfile\fR
.PP
This prepends the contents of the specified file or FileDatabase
entry to the enclosed perl code (if any), then executes as usual.
.PP
For example,
.PP
.Vb 1
\& [perl file="my_script.pl"][/perl]
.Ve
would execute myscript.pl and expand to its return value.
.PP
Absolute filenames (or filenames containing '../') are prohibited by
the NoAbsolute catalog directive.
.PP
If the filename is not absolute, Interchange first looks for a file in
the current directory, then in the list set with the TemplateDir
catalog directive. If it fails to find a file by that name, it then
looks for an entry by that name in the database specified with the
FileDatabase catalog directive.
.PP
\&\fIfile\fR
.PP
Add line numbers to the source code displayed in the error.log,
amazingly useful if some of the perl is being generated elsewhere and
interpolated.
.PP
\&\fIeval_label\fR
.PP
Set to a string, will replace the (eval ###) in the error message with
this label, handy to quickly track down bugs when you have more than
one perl block in the page, especially if you are using
\&\fIshort_errors\fR.
.PP
\&\fIshort_errors\fR
.PP
If set to a true value, syntax errors and the like in perl tags will
log just the error, not the whole source code of the block in
question, handy when you have the code open in an editor anyway and
don't want the error itself to get scrolled away when running 'tail \-f
error.log'.
.PP
\&\fItrim_errors\fR
.PP
If set to a number, and the error produced includes a line number,
then only that number of lines before and after the broken line itself
will be displayed, instead of the whole block.
.Sh "price"
.IX Subsection "price"
Summary
.PP
Parameters: \fBcode\fR
.PP
Positional parameters in same order.
.PP
\&\fBThe attribute hash reference is passed\fR to the subroutine after the
parameters as the last argument. \fBThis may mean that there are
parameters not shown here.\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
Invalidates cache: \fBno\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 5
\& $Tag->price(
\& {
\& code => VALUE,
\& }
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 1
\& $Tag->price($code, $ATTRHASH);
.Ve
Attribute aliases
.PP
.Vb 2
\& base ==> mv_ib
\& [price code other_named_attributes]
.Ve
.Vb 3
\& Parameters Description Default
\& base Alias for mv_ib DEFAULT_VALUE
\& code DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [price code]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->price( { code => VALUE_code
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->price(code, $attribute_hash_reference, $body);
.Ve
Description
.PP
Arguments:
.PP
.Vb 5
\& code Product code/SKU
\& base Only search in product table *base*
\& quantity Price for a quantity
\& discount If true(1), check discount coupons and apply
\& noformat If true(1), don't apply currency formatting
.Ve
Expands into the price of the product identified by code as found in
the products database. If there is more than one products file
defined, they will be searched in order unless constrained by the
optional argument \fBbase\fR. The optional argument \fBquantity\fR selects
an entry from the quantity price list. To receive a raw number, with
no currency formatting, use the option noformat=1.
.PP
Interchange maintains a price in its database for every product. The
price field is the one required field in the product database \- it is
necessary to build the price routines.
.PP
For speed, Interchange builds the code that is used to determine a
product's price at catalog configuration time. If you choose to change
a directive that affects product pricing you must reconfigure the
catalog.
.PP
Quantity price breaks are configured by means of the \fICommonAdjust\fR
directive. There are a number of CommonAdjust recipes which can be
used; the standard example in the demo calls for a separate pricing
table called pricing. Observe the following:
.PP
.Vb 1
\& CommonAdjust pricing:q2,q5,q10,q25, ;products:price, ==size:pricing
.Ve
This says to check quantity and find the applicable column in the
pricing database and apply it. In this case, it would be:
.PP
.Vb 4
\& 2-4 Column *q2*
\& 5-9 Column *q5*
\& 10-24 Column *q10*
\& 25 up Column *q25*
.Ve
What happens if quantity is one? It \*(L"falls back\*(R" to the price that is
in the table products, column price.
.PP
After that, if there is a size attribute for the product, the column
in the pricing database corresponding to that column is checked for
additions or subtractions (or even percentage changes).
.PP
If you use this tag in the demo:
.PP
.Vb 1
\& [price code=99-102 quantity=10 size=XL]
.Ve
the price will be according to the q10 column, adjusted by what is
in the \s-1XL\s0 column. (The row is of course 99\-102.) The following entry
in pricing:
.PP
.Vb 2
\& code q2 q5 q10 q25 XL
\& 99-102 10 9 8 7 .50
.Ve
Would yield 8.50 for the price. Quantity of 10 in the q10 column,
with 50 cents added for extra large (\s-1XL\s0).
.PP
Following are several examples based on the above entry as well as
this the entry in the products table:
.PP
.Vb 2
\& code description price size
\& 99-102 T-Shirt 10.00 S=Small, M=Medium, L=Large*, XL=Extra Large
.Ve
\&\s-1NOTE:\s0 The examples below assume a \s-1US\s0 locale with 2 decimal places, use
of commas to separate, and a dollar sign ($) as the currency
formatting.
.PP
.Vb 10
\& TAG DISPLAYS
\& ---------------------------------------- --------
\& [price 99-102] $10.00
\& [price code="99-102"] $10.00
\& [price code="99-102" quantity=1] $10.00
\& [price code="99-102" noformat=1] 10
\& [price code="99-102" quantity=5] $9.00
\& [price code="99-102" quantity=5 size=XL] $9.50
\& [price code="99-102" size=XL] $10.50
\& [price code="99-102" size=XL noformat=1] 10.5
.Ve
Product discounts for specific products, all products, or the entire
order can be configured with the [discount ...] tag. Discounts are
applied on a per-user basis \- you can gate the discount based on
membership in a club or other arbitrary means.
.PP
Adding [discount 99\-102] \f(CW$s\fR * .9[/discount] deducts 10% from the price
at checkout, but the price tag will not show that unless you add the
discount=1 parameter.
.PP
.Vb 2
\& [price code="99-102"] --> $10.00
\& [price code="99-102" discount=1] --> $9.00
.Ve
See \fIProduct Discounts\fR.
.PP
\&\fIbase\fR
.PP
\&\fIcode\fR
.Sh "process"
.IX Subsection "process"
This is a shortcut for the 'process' action, expanding to your catalog
\&\s-1URL\s0 and session \s-1ID\s0. It is analogous to the area tag for the
\&'process' page, but is more limited. The following expansion is
illustrative:
.PP
.Vb 4
\& [process target=targetframe]
\&---
\& http://www.here.com/cgi-bin/mycatalog/process.html?\e
\& id=6CZ2whqo" TARGET="targetframe
.Ve
(the trailing backslash indicates continuation, i.e., the result
should be only one line)
.PP
Note the mismatched quotes in the expansion. Your surrounding \s-1HTML\s0
should supply the containing quotes, like this:
.PP
.Vb 1
\& ...
.Ve
Aliases: \fBprocess_target\fR, \fBprocess_order\fR
.PP
Summary
.PP
.Vb 2
\& [process target secure]
\& [process target=targetframe secure=1 other_named_attributes]
.Ve
.Vb 3
\& Parameters Description Default
\& target The target frame or window None
\& secure Boolean. If true (secure=1), the URL will link to your secure server.No
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 3
\& Other_Characteristics
\& Invalidates cache No
\& Container tag No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 4
\& [process targetframe 1]
\&---
\& http://secure.here.com/cgi-bin/mycatalog/process.html?\e
\& id=6CZ2whqo" TARGET="targetframe
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->process( { target => 'frametarget',
\& secure => 1, } );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->process($target, $secure, $attribute_hash_reference);
.Ve
.Sh "process-search"
.IX Subsection "process-search"
This is an exact alias for [area].
.Sh "query"
.IX Subsection "query"
Passes \s-1SQL\s0 statements through to \s-1SQL\s0 databases, or allows \s-1SQL\s0 queries
via Interchange's database abstraction into non-SQL databases and text
files. The latter requires the Perl \fI\s-1SQL\s0 Statement\fR module (included
with Bundle::Interchange from \s-1CPAN\s0).
.PP
Summary
.PP
.Vb 2
\& [query sql]
\& [query sql="SQL_query_text" other_named_attributes]
.Ve
.Vb 3
\& Parameters Description Default
\& sql The SQL statement.Passed directly through to an SQL database.For a non-SQL table, the tag interprets your SQL first. See the SQL Statement module for limitations and detail.none
\& query Alias for sql none
.Ve
.Vb 17
\& Attributes Default
\& table products
\& base (alias for table) products
\& type (row_count, html, list, textref)none: uses arrayref="" if no type
\& arrayref arrayref="" if no type given
\& hashref none
\& more (type=list) No
\& xx form var. abbrev. (type=list) see form variable
\& (type=list) sql
\& list_prefix (type=list) list
\& random (type=list) No
\& safe_data (type=list) No
\& label (type=list) current
\& form (type=list) none
\& wantarray No
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache No
\& Container tag Yes
\& Has subtags Yes
\& Nests No
.Ve
\&\fBTag usage example:\fR
.PP
This will list sku, description and price for ten products per page,
followed by hyperlinks to the other pages of the list. Note that you
may interpolate Interchange tags in the usual way if you double-quote
the \s-1SQL\s0 statement.
.PP
.Vb 4
\& [query sql="select sku, description, price from products where price < [value mv_arg]"
\& type=list
\& more=1
\& ml=10]
.Ve
.Vb 2
\& [on_match]Matched [/on_match]
\& [no_match]Not Found [/no_match]
.Ve
.Vb 3
\& [list]
\& [sql-code] [sql-param description] [sql-price]
\& [/list]
.Ve
.Vb 5
\& [more_list]
\& Matches [matches] of [match-count] shown.
\& [more]
\& [/more_list]
\& [/query]
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 6
\& my $sql = "select * from products order by price";
\& my $result_array = $Tag->query( { sql => $sql, },
\& $body );
\& my ($same_results, $col_name_hash, $col_name_array) =
\& $Tag->query( { sql => $sql, },
\& $body );
.Ve
.Vb 3
\& my $result_hasharray = $Tag->query( { sql => $sql,
\& hashref => 'my_results', },
\& $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->query( $sql, $attribute_hash_reference, $body);
.Ve
Description
.PP
The query tag allows you to make \s-1SQL\s0 queries. If you are using an
\&\s-1SQL\s0 database table, the tag will pass your \s-1SQL\s0 statement directly to
the database and return the result.
.PP
If your table is not in an \s-1SQL\s0 database (for example, \s-1GDBM\s0, text,
\&\s-1LDAP\s0, and in-memory tables), Interchange will internally convert it to
an Interchange search specification with the Perl \fI\s-1SQL\s0 Statement\fR
module (included with Bundle::Interchange from \s-1CPAN\s0). This means that
you can use simple \s-1SQL\s0 queries regardless of the underlying database
implementation.
.PP
\&\fISubtags\fR
.PP
For list queries (type=list), the following subtags are available:
.PP
.Vb 5
\& Subtag Usage
\& on_match [on_match] do this if something matched [/on_match]
\& no_match [no_match] do this if nothing matched [/no_match]
\& list [list_prefix] do this for each matched item [/list_prefix]The 'list' subtag defines a region where you can use any of the looping subtags that work in array-list context (see Looping tags and Sub-tags).The default looping tag prefix will be 'sql'. Note however that you can override this by setting the prefix attribute in the enclosing query tag.Similarly, the list_prefix attribute renames the [list] subtag itself to the value you set (see list_prefix below).
\& more_list [more_list] [more] [/more_list]The 'more_list' and 'more' subtags are used when paginating the query results (see 'more' attribute). The [more] subtag will expand to a list of links to the other pages of the query results.
.Ve
See also the example at the end of the Summary section above.
.PP
Perl and \s-1ASP\s0 usage
.PP
If you are calling \f(CW$Tag\fR->query within a perl tag (or whenever the
code is secured by the \fISafe.pm\fR module), you must be sure to set the
tables attribute properly in the enclosing perl tag (see the
perl tag documentation for detail).
.PP
The \fItypes\fR that return text to a page (i.e., row_count, html, and
textref) work as usual, returning an appropriate string. Note that you
may also have access to the results as an array reference in
\&\f(CW$Vend::Interpolate::Tmp\fR->{''} for the life of the page.
.PP
If you do not set a \fItype\fR, the tag will return a reference to an
array of array references, since the default with no \fItype\fR is
arrayref="".
.PP
If you call \f(CW$Tag\fR->query in scalar context and set \fIarrayref\fR or
\&\fIhashref\fR, it will return your results as a reference to an array of
either arrayrefs or hashrefs, respectively (i.e., the same data
structures you would get from Perl's \s-1DBI\s0.pm module with
fetchall_arrayref).
.PP
In list context, the first returned element is the aforementioned
reference to your results. The second element is a hash reference to
your column names, and the third element is an an array reference to
the list of column names.
.PP
The following examples should be illustrative:
.PP
.Vb 3
\& [perl tables=products]
\& my $sql = "select sku, price, description from products
\& where price < 10 order by price";
.Ve
.Vb 3
\& my $results = $Tag->query( { sql => $sql, } );
\& my ( $same_results, $col_name_hashref, $col_name_arrayref)
\& = $Tag->query( { sql => $sql, } );
.Ve
.Vb 2
\& my $hash_results = $Tag->query( { sql => $sql,
\& hashref => 'my_results' } );
.Ve
.Vb 2
\& # $Vend::Interpolate::Tmp->{my_results} == $hash_results
\& # $Vend::Interpolate::Tmp->{''} == $results == $same_results
.Ve
.Vb 2
\& my $out = "The returned structure is\en";
\& $out .= $Tag->uneval( $results );
.Ve
.Vb 7
\& #loop through each row & display the fields
\& foreach my $row (@$hash_results) {
\& $out .= 'sku: ' . $row->{sku}
\& $out .= ' price: ' . $row->{price};
\& $out .= ' description: ' . $row->{description};
\& }
\& return $out;
.Ve
.Vb 1
\& [/perl]
.Ve
\&\fBTechnical Note: \fRThe \f(CW$Tag\fR->\fIquery()\fR call works a bit differently in
GlobalSubs and UserTags than within a perl tag. Specifically, in a
GlobalSub or global UserTag, if you call \fIquery()\fR in list context and
want the three references (i.e., results, column hash and column
array), then you need to set the '\fIwantarray\fR=1' attribute in the
\&\fIquery()\fR call. See the \fIwantarray\fR attribute.
.PP
\&\fIsql\fR
.PP
This is the text of your \s-1SQL\s0 statement. The standard Interchange
quoting rules apply. For example, use double quotes (") if you want to
interpolate Interchange tags within your \s-1SQL\s0 statement, backticks (`)
to calculate a value, \fIetc.\fR
.PP
.Vb 4
\& [query sql="select description, price from products
\& where price < [value mv_arg]" ...]
\& ...
\& [/query]
.Ve
\&\fItable\fR
.PP
The table attribute sets the database to use for the query. The
default will typically be the database containing the 'products'
table (unless you have changed the first entry in
\&\f(CW$Vend::Cfg\fR->{ProductFiles}).
.PP
\&\fItype\fR
.PP
If you are not setting the 'arrayref' or 'hashref' attributes,
then the type attribute defines the way the query will return its
results. The type should be one of the following:
.PP
.Vb 5
\& Type Returns
\& html The html type returns the results in an html table. You will need to supply the enclosing
html tags. The following is an example of typical usage: [query sql="select * from products where price > 12 order by price" type=html] [/query]
\& list This allows you to use subtags to control the query output and pagination. See the Subtags section above for detail.
\& row_count This causes the tag to return the number of rows in the query result.
\& textref This causes the tag to return a the query results as a serialized array of arrays that Perl can evaluate with its eval() function. Here is an illustrative example: my $rows = eval( $Tag->query( { sql => "select * from products" type => "textref" } ) ); my $r3_c0 = $rows->[3]->[0];
.Ve
If you do not specify a type, the tag will create an arrayref as if
you had set 'arrayref=""'.
.PP
\&\fIarrayref and hashref\fR
.PP
If you set 'arrayref=\fIkeyname\fR' or 'hashref=\fIkeyname\fR', the
query will not return results to the page. Instead, it will place the
results of your query in the \f(CW$Vend::Interpolate::Tmp\fR hash. Using
\&'arrayref=my_query' sets \f(CW$Vend::Interpolate::Tmp\fR->{my_query} to
refer to an array of array references, while 'hashref=my_query'
creates an array of hash references.
.PP
Note that this is useful only if you intend to access the results
within Perl code (for example, within a [perl] tag), since there is
no direct output to the returned page.
.PP
The \f(CW$Vend::Interpolate::Tmp\fR hash persists only for the life of the
template page being processed. If you need the query results array
reference to outlive the page, you will have to save the reference
somewhere more persistent such as the \f(CW$Session\fR hash:
.PP
.Vb 1
\& $Session->{my_query} = $Vend::Interpolate::Tmp->{my_query};
.Ve
Beware the impact on performance if you do this with large result
sets.
.PP
Technical note \- the string returned by the 'textref' type will
\&\fBeval\fR() to the 'arrayref' data structure.
.PP
\&\fImore\fR
.PP
Requires 'type=list'.
.PP
You must set more=1 to properly paginate your results from list
queries (see 'type=list' above. If you do not set more=1, then
the links to later pages will merely redisplay the first page of your
results.
.PP
\&\fIform variable abbreviations\fR
.PP
Requires 'type=list'.
.PP
See the \fISearch and Form Variables\fR appendix for a list of form
variables. Note that you must use the two-letter abbreviation rather
than the full form variable name.
.PP
A few deserve special mention:
.PP
.Vb 5
\& Abbr Name Description
\& ml mv_matchlimit Sets number of rows to return. If paginating (more=1), sets rows returned per page.
\& fm mv_first_match Start displaying search at specified match
\& sp mv_search_page Sets the page for search display
\& st mv_searchtype Forces a specific search type (text, glimpse, db or sql), overriding the default determined from your database implementation.
.Ve
.PP
Requires 'type=list'.
.PP
Setting 'prefix=foo' overrides the default prefix of 'sql' for loop
subtags within a list region (see \fILooping tags and Sub-tags\fR).
.PP
See the \fIlist_prefix\fR attribute below for an illustrative example.
.PP
\&\fIlist_prefix\fR
.PP
Requires 'type=list'.
.PP
Setting 'list_prefix=bar' overrides the default region tagname of
\&'list'. The best way to show this is by example. Compare the following
two examples of list queries, the first using the defaults and the
second with explicitly set prefix and list_prefix.
.PP
.Vb 5
\& [query sql="select sku, description, price from products
\& where price < 20"
\& type=list
\& more=1
\& ml=10]
.Ve
.Vb 2
\& [on_match]Matched [/on_match]
\& [no_match]Not Found [/no_match]
.Ve
.Vb 3
\& [list]
\& [sql-code] [sql-param description] [sql-price]
\& [/list]
.Ve
.Vb 12
\& [more_list]
\& [more]
\& [/more_list]
\& [/query]
\&---
\& [query sql="select sku, description, price from products
\& where price < 20"
\& type=list
\& prefix=foo
\& list_prefix=bar
\& more=1
\& ml=10]
.Ve
.Vb 2
\& [on_match]Matched [/on_match]
\& [no_match]Not Found [/no_match]
.Ve
.Vb 3
\& [bar]
\& [foo-code] [foo-param description] [foo-price]
\& [/bar]
.Ve
.Vb 4
\& [more_list]
\& [more]
\& [/more_list]
\& [/query]
.Ve
\&\fIrandom\fR
.PP
Requires 'type=list'.
.PP
You can use the 'random' attribute to randomly select a set of rows
from the whole result set of your query. In other words, setting
\&'random=\fIn\fR', where \fIn\fR > 0, causes the [list] region to loop
over \fIn\fR randomly chosen rows rather than the full query result set.
.PP
The example below would display three randomly chosen products priced
under 20.
.PP
.Vb 4
\& [query sql="select * from products
\& where price < 20"
\& type=list
\& random=3]
.Ve
.Vb 3
\& [list]
\& [sql-code] [sql-param description] [sql-price]
\& [/list]
.Ve
.Vb 1
\& [/query]
.Ve
\&\fIsafe_data\fR
.PP
Requires 'type=list'.
.PP
Note \- you should not set this unless you need it and know what you
are doing.
.PP
Setting 'safe_data=1' allows the [sql-data] tag to return values
containing the '[' character. See also \fILooping tags and Sub-tags\fR.
.PP
Beware of reparsing issues.
.PP
\&\fIlabel\fR
.PP
Requires 'type=list'.
.PP
If you are setting up multiple simultaneously active search objects
within a page, this allows you to distinguish them. The default label
is 'current'. Most people will not need this.
.PP
\&\fIform\fR
.PP
Requires 'type=list'.
.PP
You can use this to pass one \s-1CGI\s0 form variable in the pagination links
of a [more-list]. For example, 'form=\*(L"foo=bar\*(R"' to include
\&'&foo=bar' in the \s-1URL\s0 of each of the pagination links.
.PP
Note that the variable will not be available in the initial result set
since the query returns the first page directly (i.e., you did not
follow a pagination link).
.PP
\&\fIwantarray\fR
.PP
This is relevant only when calling \f(CW$Tag\fR->query( ... ) within global
Perl code such as a globalsub or global usertag where \f(CW$MVSAFE::Safe\fR is
not defined. In these cases, setting 'wantarray=1' allows the call
to
.PP
.Vb 1
\& $Tag->query( { wantarray => 1, ... }, ... );
.Ve
to return references as it would if called within an ordinary
[perl] tag. Note that it does not force list context if you call
\&\f(CW$Tag\fR->query in scalar context.
.PP
Here is another example of the use of the array references, from a
UserTag:
.PP
.Vb 3
\& my $sku = 'os28044';
\& my $sql = qq{select description, price from products where sku = '$sku'};
\& my $table = 'products';
.Ve
.Vb 4
\& my ($results, $col_name_hashref, $col_name_arrayref) = $Tag->query({
\& wantarray => 1,
\& sql => "$sql",
\& table => "$table"});
.Ve
.Vb 1
\& my $out;
.Ve
.Vb 2
\& # this will get the first field (description)..
\& $out = 'description: ' . $results->[0]->[0];
.Ve
.Vb 2
\& # and this the second field (price)..
\& $out .= ' price: ' . $results->[0]->[1];
.Ve
.Vb 3
\& # this will tell us the position in the $results array of the price field..
\& $out .= ' position of price field: ' . $col_name_hashref->{price};
\& return $out;
.Ve
If the [query] returns more than one row, the second row's description
field would be:
.PP
.Vb 1
\& $results->[1]->[0]
.Ve
Technical note \- the ordinary [query ...] ... [/query] usage
forces scalar context on the query call and suppresses the return
value for those types that would return references if \f(CW$Tag\fR->query
were called within a [perl] tag. The wantarray option is needed
because global subs and usertags are also affected by this unless you
set wantarray.
.PP
Example of a nested query:
.PP
.Vb 10
\& [query
\& ml=99
\& type=list
\& sp="@@MV_PAGE@@"
\& sql=|
\& SELECT foo1, foo2, foo3
\& FROM bar
\& WHERE someothercol = 'bang'
\& |]
\& [list]
.Ve
.Vb 1
\& Here is [sql-param foo1] from outer
.Ve
.Vb 11
\& [query
\& prefix=usr
\& list_prefix=detail
\& ml=1
\& type=list
\& sp="@@MV_PAGE@@"
\& sql=|
\& SELECT flip
\& FROM flap
\& WHERE flog = 'flan'
\& |]
.Ve
.Vb 3
\& [usr-on-match]
\& something was found in the inner!
\& [/usr-on-match]
.Ve
.Vb 1
\& [detail]
.Ve
.Vb 1
\& Here is [usr-param flip] from inner
.Ve
.Vb 1
\& Here is [sql-param foo2] from outer!!
.Ve
.Vb 2
\& [/detail]
\& [/query]
.Ve
.Vb 1
\& Here is [sql-param foo3] from outer!!!
.Ve
.Vb 11
\& [/list]
\& [on-match]
\& Something was found in the outer query
\& [/on-match]
\& [no-match]
\& Nothing was found in the outer query
\& [/no-match]
\& [more-list]
\& [matches] in the outer query
\& [/more-list]
\& [/query]
.Ve
Notice the use of 'prefix' and 'list_prefix' on subsequent inner
queries.
.Sh "read-cookie"
.IX Subsection "read-cookie"
Returns the value of the named cookie. Returns nothing if the cookie
does not exist.
.PP
Summary
.PP
.Vb 2
\& [read-cookie name]
\& [read-cookie name=mycookie]
.Ve
.Vb 2
\& Attributes Description Default
\& name The name of the cookie whose value you wantnone
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 3
\& Other_Characteristics
\& Invalidates cache Yes
\& Container tag No
.Ve
\&\fBUsage example:\fR
.PP
.Vb 3
\& [read-cookie name=MV_SESSION_ID]
\&---
\& 6CZ2whqo
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 1
\& $Tag->read_cookie( { name => $name, } );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->read_cookie( $name );
.Ve
Description
.PP
This tag expands to the value of the named cookie (or nothing if the
cookie does not exist).
.PP
See the Netscape specification at
\&\fIhttp://www.netscape.com/newsref/std/cookie_spec.html\fR if you need
more cookie-specific detail.
.PP
\&\fIname\fR
.PP
This is the name of the cookie whose value you want to retrieve.
.PP
\&\fIParsing an \s-1HTTP_COOKIE\s0 string\fR
.PP
If you pass this tag a second parameter within a Perl call, it will
use your value as the \s-1HTTP_COOKIE\s0 string (ignoring the real one). This
only applies if you pass the values positionally within a perl call
since there is no name for the \s-1HTTP_COOKIE\s0 string input:
.PP
.Vb 1
\& $Tag->read_cookie('MV_SESSION_ID', "MV_SESSION_ID=UnHyaDQj:127.0.0.1; ...");
.Ve
.Sh "restrict"
.IX Subsection "restrict"
Restrict tag execution in a region. If a restricted tag is
encountered, it is simply output.
.PP
Summary
.PP
.Vb 2
\& [restrict tag1 tag2]
\& [restrict policy=deny enable="page area value"]
.Ve
.Vb 4
\& Attributes Description Default
\& policy Whether to allow or deny by default. deny
\& enable Tags to enable when default policy is deny.none
\& disable Tags to disable. Overrides enable. none
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 3
\& Other_Characteristics
\& Invalidates cache Yes
\& Container tag No
.Ve
\&\fBUsage example:\fR
.PP
.Vb 3
\& [read-cookie name=MV_SESSION_ID]
\&---
\& 6CZ2whqo
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 1
\& N/A. Cannot be called effectively.
.Ve
Description
.PP
Restrict tag execution in a region. If a restricted tag is
encountered, it is simply output. It can be used to allow certain tags
in a user-editable region, while denying dangerous tags. Or it can be
used to restrict all tag execution in a region.
.PP
\&\fIpolicy\fR
.PP
Default is deny, which makes most sense. You then specifically
enable certain \s-1ITL\s0 tags. If you set allow by default, you must be
very careful that you really are disabling all of what you consider to
be dangerous tags.
.PP
\&\fIenable\fR
.PP
A space-separated or comma-separated list of tags to disable when the
default policy is deny. Has no effect when the default policy is
allow, and any tags passed in the disable parameter override the
enable.
.PP
\&\fIdisable\fR
.PP
A space-separated or comma-separated list of tags to disable when the
default policy is allow. If you have a list of tags that are
enabled, perhaps stored in a scratch variable, you can disable some of
those tags since this takes precedence over the enable.
.Sh "row"
.IX Subsection "row"
Summary
.PP
Parameters: \fBwidth\fR
.PP
Positional parameters in same order.
.PP
Pass attribute hash as last to subroutine: \fBno\fR
.PP
Interpolates \fBcontainer text\fR by default.
.PP
This is a container tag, i.e. [row] \s-1FOO\s0 [/row]. Nesting: \s-1NO\s0
.PP
Invalidates cache: \fBno\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 6
\& $Tag->row(
\& {
\& width => VALUE,
\& },
\& BODY
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 2
\& $Tag->row($width, $BODY);
\& [row width]
.Ve
.Vb 2
\& Parameters Description Default
\& width DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [row width]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->row( { width => VALUE_width
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->row(width, $attribute_hash_reference, $body);
.Ve
Description
.PP
Formats text in tables. Intended for use in emailed reports or
<\s-1PRE\s0> \s-1HTML\s0 areas. The parameter \fInn\fR gives the number of
columns to use. Inside the row tag, [col param=value ...] tags may be
used.
.PP
[col width=nn wrap=yes|no gutter=n align=left|right|input spacing=n]
.PP
Sets up a column for use in a [row]. This parameter can only be
contained inside a [row nn] [/row] tag pair. Any number of columns
(that fit within the size of the row) can be defined.
.PP
The parameters are:
.PP
.Vb 4
\& width=nn The column width, I. Must be
\& supplied, there is no default. A shorthand method
\& is to just supply the number as the I parameter,
\& as in [col 20].
.Ve
.Vb 2
\& gutter=n The number of spaces used to separate the column (on
\& the right-hand side) from the next. Default is 2.
.Ve
.Vb 2
\& spacing=n The line spacing used for wrapped text. Default is 1,
\& or single-spaced.
.Ve
.Vb 3
\& wrap=(yes|no) Determines whether text that is greater in length than
\& the column width will be wrapped to the next line. Default
\& is I.
.Ve
.Vb 3
\& align=(L|R|I) Determines whether text is aligned to the left (the default),
\& the right, or in a way that might display an HTML text
\& input field correctly.
.Ve
[/col]
.PP
Terminates the column field.
.PP
\&\fIwidth\fR
.Sh "salestax"
.IX Subsection "salestax"
Summary
.PP
Parameters: \fBname noformat\fR
.PP
Positional parameters in same order.
.PP
Pass attribute hash as last to subroutine: \fBno\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
Invalidates cache: \fB\s-1YES\s0\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 6
\& $Tag->salestax(
\& {
\& name => VALUE,
\& noformat => VALUE,
\& }
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 1
\& $Tag->salestax($name, $noformat);
.Ve
Attribute aliases
.PP
.Vb 2
\& cart ==> name
\& [salestax name noformat]
.Ve
.Vb 4
\& Parameters Description Default
\& cart Alias for name DEFAULT_VALUE
\& name DEFAULT_VALUE
\& noformat DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [salestax name noformat]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 3
\& $Tag->salestax( { name => VALUE_name
\& noformat => VALUE_noformat
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->salestax(name,noformat, $attribute_hash_reference, $body);
.Ve
Description
.PP
Expands into the sales tax on the subtotal of all the items ordered so
far for the cart, default cart is main. If there is no key field to
derive the proper percentage, such as state or zip code, it is set to
0. If the noformat tag is present and non-zero, the raw number with no
currency formatting will be given.
.PP
\&\fIname\fR
.PP
\&\fInoformat\fR
.Sh "scratch"
.IX Subsection "scratch"
Summary
.PP
Parameters: \fBname\fR
.PP
Positional parameters in same order.
.PP
Pass attribute hash as last to subroutine: \fBno\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
Invalidates cache: \fB\s-1YES\s0\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 5
\& $Tag->scratch(
\& {
\& name => VALUE,
\& }
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 2
\& $Tag->scratch($name);
\& [scratch name]
.Ve
.Vb 2
\& Parameters Description Default
\& name DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [scratch name]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->scratch( { name => VALUE_name
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->scratch(name, $attribute_hash_reference, $body);
.Ve
Description
.PP
Returns the contents of a scratch variable to the page. (A scratch
variable is set with a [set] value [/set] container pair.)
.PP
\&\fIname\fR
.Sh "scratchd"
.IX Subsection "scratchd"
Deletes the named scratch variable and returns its value before the
deletion. For example,
.PP
.Vb 1
\& [scratchd varname_to_delete]
.Ve
deletes the scratch variable \fIvarname_to_delete\fR.
.PP
See also the scratch and set tags.
.PP
Summary
.PP
.Vb 2
\& [scratchd P_PARAM]
\& [scratchd N_PARAM other_named_attributes]
.Ve
.Vb 2
\& Parameters Description Default
\& name Name of scratch variable to delete None
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 3
\& Other_Characteristics
\& Invalidates cache Yes
\& Container tag No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 7
\& [set myvar]This is myvar[/set]
\& .
\& .
\& .
\& [scratchd myvar]
\&---
\& This is myvar
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 1
\& $Tag->scratchd($name, $attribute_hash_reference);
.Ve
Description
.PP
Deletes the named scratch variable and returns its value before the
deletion.
.Sh "search-list"
.IX Subsection "search-list"
Formats results returned by a search. Must be enclosed within a
search-region. Has sub-tags (see Looping tags and Sub-tags).
.Sh "search-region"
.IX Subsection "search-region"
Summary
.PP
Parameters: \fBarg\fR
.PP
\&\fBThe attribute hash reference is passed\fR after the parameters but
before the container text argument. \fBThis may mean that there are
parameters not shown here.\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
This is a container tag, i.e. [search-region] \s-1FOO\s0 [/search-region].
Nesting: \s-1NO\s0
.PP
Invalidates cache: \fBno\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 6
\& $Tag->search_region(
\& {
\& arg => VALUE,
\& },
\& BODY
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 1
\& $Tag->search_region($arg, $ATTRHASH, $BODY);
.Ve
Attribute aliases
.PP
.Vb 4
\& args ==> arg
\& params ==> arg
\& search ==> arg
\& [search-region arg other_named_attributes]
.Ve
.Vb 5
\& Parameters Description Default
\& arg DEFAULT_VALUE
\& args Alias for arg DEFAULT_VALUE
\& params Alias for arg DEFAULT_VALUE
\& search Alias for arg DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [search-region arg]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->search_region( { arg => VALUE_arg
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->search_region(arg, $attribute_hash_reference, $body);
.Ve
Description
.PP
\&\fB\s-1NO\s0 Description\fR
.PP
\&\fIarg\fR
.Sh "selected"
.IX Subsection "selected"
Summary
.PP
Parameters: \fBname value\fR
.PP
Positional parameters in same order.
.PP
\&\fBThe attribute hash reference is passed\fR to the subroutine after the
parameters as the last argument. \fBThis may mean that there are
parameters not shown here.\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
Invalidates cache: \fB\s-1YES\s0\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 6
\& $Tag->selected(
\& {
\& name => VALUE,
\& value => VALUE,
\& }
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 2
\& $Tag->selected($name, $value, $ATTRHASH);
\& [selected name value other_named_attributes]
.Ve
.Vb 7
\& Parameters Description Default
\& case DEFAULT_VALUE
\& cgi DEFAULT_VALUE
\& default DEFAULT_VALUE
\& name DEFAULT_VALUE
\& multiple DEFAULT_VALUE
\& value DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 6
\& [value name=example set=neato]
\& Neato
\& Silly
\&---
\& Neato
\& Silly
.Ve
Description
.PP
You can provide a \*(L"memory\*(R" for drop-down menus, radio buttons, and
checkboxes with the [checked] and [selected] tags.
.PP
This will output \s-1SELECTED\s0 if the variable var_name is equal to
value. If the optional \s-1MULTIPLE\s0 argument is present, it will look
for any of a variety of values. Not case sensitive unless the optional
case=1 parameter is used.
.PP
Here is a drop-down menu that remembers an item-modifier color
selection:
.PP
.Vb 5
\&
\& Blue
\& Green
\& Red
\&
.Ve
Here is the same thing, but for a shopping-basket color selection:
.PP
.Vb 5
\&
\& Blue
\& Green
\& Red
\&
.Ve
By default, the Values space (i.e. [value foo]) is checked \- if you
want to use the volatile \s-1CGI\s0 space (i.e. [cgi foo]) use the parameter
cgi=1.
.PP
Use the parameter default=1 to specify the option that should be
marked \s-1SELECTED\s0 if the value/CGI variable has never been set.
.PP
If the parameter multiple=1 is set, the value parameter can
contain multiple (stacked) values that should be selected, separated
by \s-1ASCII\s0 null characters (\*(L"\e0\*(R" in Perl).
.PP
\&\fIcase\fR
.PP
\&\fIcgi\fR
.PP
\&\fIdefault\fR
.PP
\&\fIname\fR
.PP
\&\fImultiple\fR
.PP
\&\fIvalue\fR
.Sh "set"
.IX Subsection "set"
Summary
.PP
Parameters: \fBname\fR
.PP
Positional parameters in same order.
.PP
Pass attribute hash as last to subroutine: \fBno\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
This is a container tag, i.e. [set] \s-1FOO\s0 [/set]. Nesting: \s-1NO\s0
.PP
Invalidates cache: \fB\s-1YES\s0\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 6
\& $Tag->set(
\& {
\& name => VALUE,
\& },
\& BODY
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 2
\& $Tag->set($name, $BODY);
\& [set name]
.Ve
.Vb 2
\& Parameters Description Default
\& name DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->set( { name => VALUE_name
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->set(name, $attribute_hash_reference, $body);
.Ve
Description
.PP
Sets a scratch variable to \fIvalue\fR.
.PP
Most of the mv_* variables that are used for search and order
conditionals are in another namespace \- they can be set by means of
hidden fields in a form.
.PP
You can set an order profile with:
.PP
.Vb 5
\& [set checkout]
\& name=required
\& address=required
\& [/set]
\&
.Ve
A search profile would be set with:
.PP
.Vb 5
\& [set substring_case]
\& mv_substring_match=yes
\& mv_case=yes
\& [/set]
\&
.Ve
Any of these profile values can be set in the OrderProfile files as
well.
.PP
\&\fIname\fR
.Sh "set-cookie"
.IX Subsection "set-cookie"
Sets browser \fIcookie\fR\|(s) with the specified attributes.
.PP
Summary
.PP
.Vb 1
\& [set-cookie named_attributes]
.Ve
Parameters must be named (no positional usage except in Perl call)
.PP
.Vb 6
\& Attributes Description Default
\& name The name you give the cookie none
\& value The value (automatically html-escaped by Interchange)none
\& expire Expiration date as"Wdy, DD-Mon-YYYY HH:MM:SS GMT"none
\& domain Overrides the domain(s) set in CookieDomainDomain(s), if any, defined in the CookieDomain directive
\& path legal URL paths for the cookie URL path(s) to your catalog, including aliases
.Ve
.Vb 3
\& Other_Characteristics
\& Invalidates cache Yes
\& Container tag No
.Ve
\&\fBUsage example:\fR
.PP
.Vb 5
\& [set-cookie name=mycookie
\& value="the value"
\& expire="Tue, 03-Apr-2001 17:00:00 GMT"]
\&---
\& This tag returns no value in the page
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 5
\& $Tag->set_cookie( { name => $name,
\& value => $value,
\& expire => $expire,
\& domain => $domain,
\& path => $path, } );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->set_cookie( $name, $value, $expire, $domain, $path );
.Ve
Description
.PP
This tag sets one or more browser cookies with your specified name,
value, and expiration. (Interchange will set more than one cookie if
needed to ensure that the cookie is visible from all Catalog \s-1URL\s0
path aliases and CookieDomains.)
.PP
See the Netscape specification at
\&\fIhttp://www.netscape.com/newsref/std/cookie_spec.html\fR for more
cookie-specific detail.
.PP
If you need access to the cookie from outside of your Interchange
catalog, you can also set the domain and \s-1URL\s0 paths for which the
cookie will be valid. If you need the cookie only within your catalog
and the domains specified by the CookieDomain directive, you
probably should not override the Interchange domain and path defaults.
.PP
\&\fIname\fR
.PP
This is the name of the cookie. This is the key you will use when
reading the cookie later.
.PP
\&\fIvalue\fR
.PP
This is the value to store in the cookie.
.PP
\&\fIexpire\fR
.PP
Persistent cookies (that outlive a browser session) require an
expiration date. There are two ways to set it \*(-- relative times and
absolute times.
.RS 4
.Ip "absolute" 8
.IX Item "absolute"
.RE
.RS 4
.RE
.PP
The date must be a string of the form:
.Ip "" 4
\&\*(L"Wdy, DD-Mon-YYYY \s-1HH:MM:SS\s0 \s-1GMT\s0\*(R"
.PP
and the timezone must be \s-1GMT\s0.
.RS 4
.Ip "relative" 8
.IX Item "relative"
.RE
.RS 4
.RE
.PP
Supply a period in the form \s-1NN\s0 sec|min|hours|days|weeks.
.PP
Example:
.PP
.Vb 1
\& [set-cookie name=THE_COOKIE value=foo expire="7 days"]
.Ve
If you do not supply a date (either absolute or relative), the cookie
will disappear when the user closes the browser.
.PP
\&\fIdomain\fR
.PP
The value you set will override the Interchange default \fIdomain\fR\|(s). You
might set this if you need access to the cookie from outside the
Interchange catalog, but it is usually better to set the
CookieDomain directive in your catalog.
.PP
The default is to use your catalog's domain or all CookieDomain
values.
.PP
\&\fIpath\fR
.PP
The value you set will override the Interchange default \s-1URL\s0 \fIpath\fR\|(s).
.PP
The default is to set a cookie with a path for each catalog alias (see
the Catalog directive). This ensures that the cookie will be
visible regardless of how the end user returns to your catalog.
.PP
Tips
.PP
You can use the time tag in conjunction with the set-cookie tag to set
the expiration date to an absolute date.
.PP
.Vb 5
\& [set-cookie
\& name=mycookie
\& value="the value"
\& expire="[time gmt=1 adjust='+2190']%a, %m-%b-%Y %H:%M:%S GMT[/time]"
\& ]
.Ve
In the example above, the adjustment of +2190 will set a cookie
expiration of 2190 hours forward from the current date.
.PP
You can use the
.Sh "seti"
.IX Subsection "seti"
Summary
.PP
Parameters: \fBname\fR
.PP
Positional parameters in same order.
.PP
Pass attribute hash as last to subroutine: \fBno\fR
.PP
Interpolates \fBcontainer text\fR by default.
.PP
This is a container tag, i.e. [seti] \s-1FOO\s0 [/seti]. Nesting: \s-1NO\s0
.PP
Invalidates cache: \fB\s-1YES\s0\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 6
\& $Tag->seti(
\& {
\& name => VALUE,
\& },
\& BODY
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 2
\& $Tag->seti($name, $BODY);
\& [seti name]value[/seti]
.Ve
.Vb 2
\& Parameters Description Default
\& name DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [seti name]value[/seti]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->seti( { name => VALUE_name
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->seti(name, $attribute_hash_reference, $body);
.Ve
Description
.PP
Equivalent to the [set] tag, except that it \fIinterpolates\fR by
default.
.PP
\&\fIname\fR
.Sh "setlocale"
.IX Subsection "setlocale"
Sets locale and/or currency for the current page. Can be made
persistent for the user with the 'persist' option. Resets default
locale if called without arguments. See also \fISetting the Locale\fR in
the template documentation.
.PP
Summary
.PP
.Vb 1
\& [setlocale]
.Ve
.Vb 4
\& Parameters Description Default
\& currency The currency format to use.Default: [scratch mv_currency] (see also 'persist' attribute)DEFAULT_VALUE
\& locale The locale to use.Default: [scratch mv_locale] (see also 'persist' attribute)DEFAULT_VALUE
\& persist Setting 'persist=1' also sets the scratch variables, mv_locale and mv_currency to specified locale and currency. This makes the locale settings persistent for the user's session. Otherwise (persist=0), the setlocale tag affects the remainder of the current page only.DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [setlocale]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->setlocale( {
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->setlocale(, $attribute_hash_reference, $body);
.Ve
Description
.PP
Immediately sets the locale to locale, and will cause it to persist
in future user pages if the persist is set to a non-zero, non-blank
value. If the currency attribute is set, the pricing and
currency-specific locale keys and Interchange configuration directives
are modified to that locale. If there are no arguments, it sets it
back to the user's default locale as defined in the scratch variables
mv_locale and mv_currency.
.PP
This allows:
.PP
.Vb 1
\& Dollar Pricing:
.Ve
.Vb 4
\& [setlocale en_US]
\& [item-list]
\& [item-code]: [item-price]
\& [/item-list]
.Ve
.Vb 1
\& Franc Pricing:
.Ve
.Vb 4
\& [setlocale fr_FR]
\& [item-list]
\& [item-code]: [item-price]
\& [/item-list]
.Ve
.Vb 2
\& [comment] Return to the user's default locale [/comment]
\& [setlocale]
.Ve
\&\fIcurrency\fR
.PP
The currency format to use.
.Ip "\(bu" 4
Default: [scratch mv_currency] (see also 'persist' attribute)
.PP
\&\fIlocale\fR
.PP
The locale to use.
.Ip "\(bu" 4
Default: [scratch mv_locale] (see also 'persist' attribute)
.PP
\&\fIpersist\fR
.PP
Setting 'persist=1' also sets the scratch variables, \fBmv_locale\fR
and \fBmv_currency\fR to specified locale and currency. This makes the
locale settings persistent for the user's session. Otherwise
(persist=0), the setlocale tag affects the remainder of the
current page only.
.Sh "shipping"
.IX Subsection "shipping"
Returns the cost of shipping the items in the cart via the shipping
mode set with the \fBmode\fR parameter. See also the \fIShipping\fR section
of the Database documentation.
.PP
Summary
.PP
.Vb 1
\& [shipping mode]
.Ve
.Vb 19
\& Parameters Description Default
\& add Adds the argument to add as data for a shipping.asc file (in $Vend::Cfg->{ScratchDir}/) and sets it.DEFAULT_VALUE
\& cart Alias: carts Comma-delimited list of names of carts to calculate shipping cost for.Default: current cartDEFAULT_VALUE
\& carts Alias for cart DEFAULT_VALUE
\& convert Applies the conversion (if any) set with the PriceDivide catalog configuration directive.Default: TrueDEFAULT_VALUE
\& default Resets shipping mode to default of [value mv_shipmode]DEFAULT_VALUE
\& file Filename to read shipping from (default is usual shipping database, e.g., shipping.asc)DEFAULT_VALUE
\& format Format for results with label attribute.Default: ' %D (%F)'For example, [shipping mode="FLAT" label=1 format="My Format Desc %D Price %F"]DEFAULT_VALUE
\& handling Boolean-- use [value mv_handling] rather than [value mv_shipping] as first default for mode. Note that this attribute matters only if you do not specify the mode in the tag.Note that this is set by the [handling tag (which calls the shipping tag internally). You should probably use the handling tag rather than setting this directly.Default: FalseDEFAULT_VALUE
\& hide Suppresses output DEFAULT_VALUE
\& label By default, returns HTML widget for shipping mode(s), including description and cost. You can override the widget with the format attribute. Note that label overrides noformat.Here is an example from the foundation checkout.html page: [shipping label=1 mode=|[data table=country key='[default country US]' col=shipmodes]| ]DEFAULT_VALUE
\& mode Aliases: name, modes Whitespace, null or comma delimited list of modes for which to calculate shipping cost. See also mv_shipmode.Default: [value mv_handling] if handling=1 or [value mv_shipmode] or 'default'DEFAULT_VALUE
\& modes Alias for mode DEFAULT_VALUE
\& name Alias for mode DEFAULT_VALUE
\& noformat Returns result as a number rather than a string formatted for the current locale's currency.Default: TrueDEFAULT_VALUE
\& reset_messageBoolean. Blanks the session's current shipping message (i.e., $Session->{ship_message}).DEFAULT_VALUE
\& reset_modes Clears list of modes in $Vend::Cfg->{Shipping_line}Default: FalseDEFAULT_VALUE
\& table Alias: tables Whitespace-delimited list of tables containing shipping data required for perl or query calculations (e.g., in the 'PERL' field of your shipping database - see Shipping). You must specify the tables to get past the Perl 'Safe.pm' protection. For example, you will get 'Safe' errors if you refer to an SQL table without specifying it here.Default: NoneDEFAULT_VALUE
\& tables Alias for table DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [shipping mode]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->shipping( { mode => VALUE_mode
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->shipping(mode, $attribute_hash_reference, $body);
.Ve
Description
.PP
This tag calculates the shipping cost for items in the current cart
via the specified shipping mode (usually set in the mv_shipmode
variable). See the \fIShipping\fR section of the Database documentation
for detail.
.PP
It also has options to build a selection widget (usually \s-1SELECT\s0 or
\&\s-1RADIO\s0 types) with embedded cost data.
.PP
Rounding
.PP
Note that the tag rounds the calculated shipping cost to a
locale-specific number of fractional digits (e.g., to the nearest
penny, or 2 digits after the decimal point in the \s-1USA\s0).
.PP
\&\fIadd\fR
.PP
Adds the argument to \fBadd\fR as data for a shipping.asc file (in
\&\f(CW$Vend::Cfg\fR->{ScratchDir}/) and sets it.
.PP
\&\fIcart\fR
.Ip "\(bu" 4
Alias: \fBcarts\fR Comma-delimited list of names of carts to calculate
shipping cost for.
.Ip "\(bu" 4
Default: current cart
.PP
\&\fIconvert\fR
.PP
Applies the conversion (if any) set with the PriceDivide catalog
configuration directive.
.Ip "\(bu" 4
Default: True
.PP
\&\fIdefault\fR
.PP
Resets shipping mode to default of [value mv_shipmode]
.PP
\&\fIfile\fR
.PP
Filename to read shipping from (default is usual shipping database,
e.g., shipping.asc)
.PP
\&\fIformat\fR
.PP
Format for results with \fBlabel\fR attribute.
.Ip "\(bu" 4
Default: '<\s-1OPTION\s0 VALUE=\*(L"%M\*(R"%S>%D (%F)'
.Ip "\(bu" 4
For example,
.Sp
.Vb 1
\& [shipping mode="FLAT"
.Ve
.PP
\&\fIhandling\fR
.PP
Boolean\-\- use [value mv_handling] rather than [value mv_shipping] as
first default for \fBmode\fR. Note that this attribute matters only if
you do not specify the \fBmode\fR in the tag.
.Ip "\(bu" 4
Note that this is set by the [handling tag (which calls the
shipping tag internally). You should probably use the handling tag
rather than setting this directly.
.Ip "\(bu" 4
Default: False
.PP
\&\fIhide\fR
.PP
Suppresses output
.PP
\&\fIlabel\fR
.PP
By default, returns \s-1HTML\s0 <\s-1OPTION\s0 ...> widget for shipping \fImode\fR\|(s),
including description and cost. You can override the widget with the
\&\fBformat\fR attribute. Note that \fBlabel\fR overrides \fBnoformat\fR.
.Ip "\(bu" 4
Here is an example from the foundation checkout.html page:
.Sp
.Vb 1
\& [shipping
.Ve
.PP
\&\fImode\fR
.Ip "\(bu" 4
Aliases: \fBname\fR, \fBmodes\fR Whitespace, null or comma delimited list
of modes for which to calculate shipping cost. See also mv_shipmode.
.Ip "\(bu" 4
Default: [value mv_handling] if \fBhandling=1\fR or [value
mv_shipmode] or 'default'
.PP
\&\fInoformat\fR
.PP
Returns result as a number rather than a string formatted for the
current locale's currency.
.Ip "\(bu" 4
Default: True
.PP
\&\fIno_state\fR
.PP
Bypasses the state lookup for [shipping widget=TYPE] and [shipping
possible=1].
.PP
\&\fIpossible\fR
.PP
Returns all possible modes for the selected country and state, based
on the country and state tables.
.PP
Does a query to find the shipmodes column of the state based on the
user value state, and/or the shipmodes column of the country
based on the value country
.PP
\&\s-1NOTE:\s0 You can set the following, though most will use the Interchange
defaults:
.PP
.Vb 8
\& state_table state table for lookup (default "state")
\& country_table country table for lookup (default "country")
\& state_modes_field shipmodes field in state table (default "shipmodes")
\& country_modes_field shipmodes field in country table (default "shipmodes")
\& country_table country table for lookup (default "country")
\& state_var state variable in user session (default "state")
\& country_var country variable in user session (default "country")
\& shipmode_var shipmode variable in user session (default "mv_shipmode")
.Ve
\&\fIreset_message\fR
.PP
Boolean. Blanks the session's current shipping message (i.e.,
\&\f(CW$Session\fR->{ship_message}).
.PP
\&\fIreset_modes\fR
.PP
Clears list of modes in \f(CW$Vend::Cfg\fR->{Shipping_line}
.Ip "\(bu" 4
Default: False
.PP
\&\fIresolve\fR
.PP
Returns the one shipping mode to set as a default, based on the best
information available. Usually selects the first in the list based on
country or state.
.PP
\&\fItable\fR
.Ip "\(bu" 4
Alias: \fBtables\fR Whitespace-delimited list of tables containing
shipping data required for perl or query calculations (\fIe.g.\fR, in the
\&'\s-1PERL\s0' field of your shipping database \- see \fIShipping\fR). You must
specify the tables to get past the Perl '\fISafe.pm\fR' protection. For
example, you will get '\fISafe\fR' errors if you refer to an \s-1SQL\s0 table
without specifying it here.
.Ip "\(bu" 4
Default: None
.PP
\&\fIwidget\fR
.PP
Returns a pre-configured widget for shipping mode selection. Will
select the modes from [shipping possible=1], but will also do shipping
calculations to see if they are valid.
.PP
If there is no weight, zip, country, or other needed information, it
will return \*(L"not enough information\*(R".
.PP
In other words, [shipping widget=select] might return to the page:
.PP
.Vb 4
\&
\& UPS Ground ($4.20)
\& UPS 2nd Day Air ($8.76)
\&
.Ve
.Sh "shipping-desc"
.IX Subsection "shipping-desc"
Returns the shipping description for the specified shipping \fBmode\fR.
See the \fIShipping\fR section of the Database documentation. See also
shipping.asc database for shipping modes.
.PP
Alias: \fBshipping-description\fR
.PP
The two tags below are identical in operation:
.PP
.Vb 2
\& [shipping-desc mode]
\& [shipping-description mode]
.Ve
Summary
.PP
.Vb 2
\& [shipping-desc mode]
\& [shipping-desc mode=shipping_mode]
.Ve
.Vb 2
\& Parameters Description Default
\& mode Shipping mode. This is a key into the shipping.asc database. See Shipping documentation.mv_shipmode, or 'default' if mv_shipmode not set
.Ve
.Vb 3
\& Other_Characteristics
\& Invalidates cache Yes, but only if no mode given
\& Container tag No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [shipping-desc 1DM]
\&---
\& UPS Next Day Air Early AM
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 1
\& $Tag->shipping_desc( $mode );
.Ve
.Sh "soap"
.IX Subsection "soap"
Summary
.PP
Parameters: \fBcall uri proxy\fR
.PP
Positional parameters in same order.
.PP
\&\fBThe attribute hash reference is passed\fR to the subroutine after the
parameters as the last argument. \fBThis may mean that there are
parameters not shown here.\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
Invalidates cache: \fB\s-1YES\s0\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 7
\& $Tag->soap(
\& {
\& call => VALUE,
\& uri => VALUE,
\& proxy => VALUE,
\& }
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 2
\& $Tag->soap($call, $uri, $proxy, $ATTRHASH);
\& [soap call uri proxy other_named_attributes]
.Ve
.Vb 4
\& Parameters Description Default
\& call DEFAULT_VALUE
\& proxy DEFAULT_VALUE
\& uri DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [soap call uri proxy]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 4
\& $Tag->soap( { call => VALUE_call
\& proxy => VALUE_proxy
\& uri => VALUE_uri
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->soap(call,uri,proxy, $attribute_hash_reference, $body);
.Ve
Description
.PP
\&\fB\s-1NO\s0 Description\fR
.PP
\&\fIcall\fR
.PP
\&\fIproxy\fR
.PP
\&\fIuri\fR
.Sh "strip"
.IX Subsection "strip"
Strips leading and trailing whitespace from the contained body text.
.PP
Summary
.PP
.Vb 3
\& [strip]
\& Body text to strip
\& [/strip]
.Ve
No parameters.
.PP
.Vb 4
\& Other_Characteristics
\& Invalidates cache No
\& Container tag Yes
\& Has Subtags No
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 1
\& $Tag->strip($BODY);
.Ve
or even better, just do it directly like this
.PP
.Vb 2
\& $BODY =~ s/^\es+//;
\& $BODY =~ s/\es+$//;
.Ve
.Sh "subtotal"
.IX Subsection "subtotal"
Summary
.PP
Parameters: \fBname noformat\fR
.PP
Positional parameters in same order.
.PP
Pass attribute hash as last to subroutine: \fBno\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
Invalidates cache: \fB\s-1YES\s0\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 6
\& $Tag->subtotal(
\& {
\& name => VALUE,
\& noformat => VALUE,
\& }
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 1
\& $Tag->subtotal($name, $noformat);
.Ve
Attribute aliases
.PP
.Vb 2
\& cart ==> name
\& [subtotal name noformat]
.Ve
.Vb 4
\& Parameters Description Default
\& cart Alias for name DEFAULT_VALUE
\& name DEFAULT_VALUE
\& noformat DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [subtotal name noformat]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 3
\& $Tag->subtotal( { name => VALUE_name
\& noformat => VALUE_noformat
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->subtotal(name,noformat, $attribute_hash_reference, $body);
.Ve
Description
.PP
Positional: [subtotal cart* noformat*]
.PP
mandatory: \s-1NONE\s0
.PP
optional: cart noformat
.PP
Expands into the subtotal cost, exclusive of sales tax, of all the
items ordered so far for the optional cart. If the noformat tag is
present and non-zero, the raw number with no currency formatting will
be given.
.PP
\&\fIname\fR
.PP
\&\fInoformat\fR
.Sh "tag"
.IX Subsection "tag"
Summary
.PP
Parameters: \fBop arg\fR
.PP
Positional parameters in same order.
.PP
\&\fBThe attribute hash reference is passed\fR after the parameters but
before the container text argument. \fBThis may mean that there are
parameters not shown here.\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
This is a container tag, i.e. [tag] \s-1FOO\s0 [/tag]. Nesting: \s-1NO\s0
.PP
Invalidates cache: \fBno\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 7
\& $Tag->tag(
\& {
\& op => VALUE,
\& arg => VALUE,
\& },
\& BODY
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 1
\& $Tag->tag($op, $arg, $ATTRHASH, $BODY);
.Ve
Attribute aliases
.PP
.Vb 2
\& description ==> arg
\& [tag op arg other_named_attributes]
.Ve
.Vb 4
\& Parameters Description Default
\& arg DEFAULT_VALUE
\& description Alias for arg DEFAULT_VALUE
\& op DEFAULT_VALUE
.Ve
.Vb 4
\& Attributes Default
\& interpolate No
\& reparse Yes
\& attach_only No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [tag op arg]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 3
\& $Tag->tag( { arg => VALUE_arg
\& op => VALUE_op
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->tag(op,arg, $attribute_hash_reference, $body);
.Ve
Description
.PP
Performs any of a number of operations, based on the presence of
arg. The arguments that may be given are:
.PP
\&\fIexport database file* type*\fR
.PP
Exports a complete Interchange database to its text source file (or
any specified file). The integer n, if specified, will select
export in one of the enumerated Interchange export formats. The
following tag will export the products database to products.txt (or
whatever you have defined its source file as), in the format specified
by the \fIDatabase\fR directive:
.PP
.Vb 1
\& [tag export products][/tag]
.Ve
Same thing, except to the file products/new_products.txt:
.PP
.Vb 1
\& [tag export products products/newproducts.txt][/tag]
.Ve
Same thing, except the export is done with a \s-1PIPE\s0 delimiter:
.PP
.Vb 1
\& [tag export products products/newproducts.txt 5][/tag]
.Ve
The file is relative to the catalog directory, and only may be an
absolute path name if \fINoAbsolute\fR is set to No.
.PP
\&\fIflag arg\fR
.PP
Sets an Interchange condition.
.PP
The following enables writes on the products and sizes databases
held in Interchange internal \s-1DBM\s0 format:
.PP
.Vb 1
\& [tag flag write]products sizes[/tag]
.Ve
\&\s-1SQL\s0 databases are always writable if allowed by the \s-1SQL\s0 database
itself \- in-memory databases will never be written.
.PP
The [tag flag build][/tag] combination forces static build of a page,
even if dynamic elements are contained. Similarly, the [tag flag
cache][/tag] forces search or page caching (not usually wise).
.PP
\&\fIlog dir/file\fR
.PP
Logs a message to a file, fully interpolated for Interchange tags. The
following tag will send every item code and description in the user's
shopping cart to the file logs/transactions.txt:
.PP
.Vb 3
\& [tag log logs/transactions.txt]
\& [item-list][item-code] [item-description]
\& [/item-list][/tag]
.Ve
The file is relative to the catalog directory, and only may be an
absolute path name if \fINoAbsolute\fR is set to No.
.PP
\&\fImime description_string\fR
.PP
Returns a MIME-encapsulated message with the boundary as employed in
the other mime tags, and the description_string used as the
Content-Description. For example
.PP
.Vb 1
\& [tag mime My Plain Text]Your message here.[/tag]
.Ve
will return
.PP
.Vb 3
\& Content-Type: TEXT/PLAIN; CHARSET=US-ASCII
\& Content-ID: [sequential, lead as in mime boundary]
\& Content-Description: My Plain Text
.Ve
.Vb 1
\& Your message here.
.Ve
When used in concert with [tag mime boundary], [tag mime header], and
[tag mime id], allows \s-1MIME\s0 attachments to be included \- typically with
PGP-encrypted credit card numbers. See the demo page etc/report for an
example. Adding the attribute attach_only=1 to the tag call will set
the content disposition to \*(L"attachment\*(R" (vs. inline).
.PP
\&\fImime boundary\fR
.PP
Returns a \s-1MIME\s0 message boundary with unique string keyed on session
\&\s-1ID\s0, page count, and time.
.PP
\&\fImime header\fR
.PP
Returns a \s-1MIME\s0 message header with the proper boundary for that
session \s-1ID\s0, page count, and time.
.PP
\&\fImime id\fR
.PP
Returns a \s-1MIME\s0 message id with the proper boundary for that session
\&\s-1ID\s0, page count, and time.
.PP
\&\fIshow_tags\fR
.PP
The encased text will not be substituted for with Interchange tags,
with < and [ characters changed to lt; and [ respectively.
.PP
.Vb 1
\& [tag show_tags][value whatever][/tag]
.Ve
\&\fItime\fR
.PP
Formats the current time according to \s-1POSIX\s0 strftime arguments. The
following is the string for Thursday, April 30, 1997.
.PP
.Vb 1
\& [tag time]%A, %B %d, %Y[/tag]
.Ve
\&\fItouch\fR
.PP
Touches a database to allow use of the \fItag_data()\fR routine in
user-defined subroutines. If this is not done, the routine will error
out if the database has not previously been accessed on the page.
.PP
.Vb 1
\& [tag touch products][/tag]
.Ve
\&\fIarg\fR
.PP
\&\fIop\fR
.Sh "time"
.IX Subsection "time"
Summary
.PP
Parameters: \fBlocale\fR
.PP
Positional parameters in same order.
.PP
\&\fBThe attribute hash reference is passed\fR after the parameters but
before the container text argument. \fBThis may mean that there are
parameters not shown here.\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
This is a container tag, i.e. [time] \s-1FOO\s0 [/time]. Nesting: \s-1NO\s0
.PP
Invalidates cache: \fBno\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 6
\& $Tag->time(
\& {
\& locale => VALUE,
\& },
\& BODY
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 2
\& $Tag->time($locale, $ATTRHASH, $BODY);
\& [time locale other_named_attributes]
.Ve
.Vb 6
\& Parameters Description Default
\& adjust Temporarily adjust the time for display purposes.none
\& gmt Display time as GMT. none
\& locale Format the time according to the named locale.none
\& tz Use the passed timezone to display the time.none
\& zerofix Strips leading zeroes from numbers. none
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [time locale]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->time( { locale => VALUE_locale
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->time(locale, $attribute_hash_reference, $body);
.Ve
Description
.PP
Formats the current time according to \s-1POSIX\s0 strftime arguments. The
following is the string for Monday, January 1, 2001.
.PP
.Vb 1
\& [time]%A, %B %d, %Y[/time]
.Ve
See the strftime man page for information on the arguments (which
are the same as modern \s-1UNIX\s0 date commands).
.PP
Accepts the following options:
.PP
\&\fIadjust\fR
.PP
If you wish to temporarily adjust the time for display purposes, you
can pass an adjust parameter with the number of hours (plus or
minus).
.PP
.Vb 2
\& [time]%c[/time]
\& [time adjust="-3"]%c[/time]
.Ve
Will display:
.PP
.Vb 2
\& Mon 01 Jan 2001 11:29:03 AM EST
\& Mon 01 Jan 2001 08:29:03 AM EST
.Ve
If the number ends in zero and has 3 digits or more, it is assumed
that the number is in timezone format (i.e +500) the local time or
from \s-1GMT:\s0
.PP
.Vb 3
\& [time]%c[/time]
\& [time adjust="-330"]%c[/time]
\& [time adjust="-300"]%c[/time]
.Ve
Will display:
.PP
.Vb 3
\& Mon 01 Jan 2001 11:29:03 AM EST
\& Mon 01 Jan 2001 07:59:03 AM EST
\& Mon 01 Jan 2001 08:29:03 AM EST
.Ve
If you want to force the number to be just a number of hours, add the
hours parameter:
.PP
.Vb 2
\& [time]%c[/time]
\& [time adjust="100" hours=1]%c[/time]
.Ve
Will display:
.PP
.Vb 2
\& Mon 01 Jan 2001 11:29:03 AM EST
\& Fri 05 Jan 2001 15:29:03 PM EST
.Ve
If adjust is an Interchange time duration with a suffix of sec,
min, hrs, days, or weeks, that will be used.
.PP
.Vb 2
\& [time]%c[/time]
\& [time adjust="2 days"]%c[/time]
.Ve
Will display:
.PP
.Vb 2
\& Mon 01 Jan 2001 11:29:03 AM EST
\& Wed 03 Jan 2001 11:29:03 AM EST
.Ve
Note that the time zone does not change \- you should either pick a
format which doesn't display zone, use the tz parameter, or manage
it yourself.
.PP
\&\s-1NOTE:\s0 You can adjust time globally for an Interchange installation by
setting the \f(CW$ENV\fR{\s-1TZ\s0} variable on many systems. Set \s-1TZ\s0 in your
environment and then restart Interchange:
.PP
.Vb 3
\& ## bash/ksh/sh
\& TZ=PST7PDT; export TZ
\& interchange -restart
.Ve
.Vb 3
\& ## csh/tcsh
\& setenv TZ PST7PDT
\& interchange -restart
.Ve
On most modern \s-1UNIX\s0 systems, all times will now be in the \s-1PST\s0 zone.
.PP
\&\fIgmt\fR
.PP
If you want to display time as \s-1GMT\s0, use the gmt parameter:
.PP
.Vb 2
\& [time]%c[/time]
\& [time gmt=1]%c[/time]
.Ve
will display:
.PP
.Vb 2
\& Mon 01 Jan 2001 11:33:26 AM EST
\& Mon 01 Jan 2001 04:33:26 PM EST
.Ve
Once again, the zone will not be set to \s-1GMT\s0, so you should pick a
format string which doesn't use zone, use the tz parameter, or
manage it yourself.
.PP
\&\fIlocale\fR
.PP
Format the time according to the named locale, assuming that locale
is available on your operating system. For example, the following:
.PP
.Vb 2
\& [time locale=en_US]%B %d, %Y[/time]
\& [time locale=fr_FR]%B %d, %Y[/time]
.Ve
should display:
.PP
.Vb 2
\& January 01, 2001
\& janvier 01, 2001
.Ve
\&\fItz\fR
.PP
Use the passed timezone to display the time. Will adjust for hours
difference.
.PP
Example:
.PP
.Vb 3
\& [time tz=GMT0]
\& [time tz=CST6CDT]
\& [time tz=PST8PDT]
.Ve
will display:
.PP
.Vb 3
\& Mon 01 Jan 2001 04:43:02 PM GMT
\& Mon 01 Jan 2001 10:43:02 AM CST
\& Mon 01 Jan 2001 08:43:02 AM PST
.Ve
Note that the first alphabetical string is the zone name when not
under daylight savings time, the digit is the number of hours
displacement from \s-1GMT\s0, and the second alphabetical string is the zone
name when in daylight savings time. \s-1NOTE:\s0 This may not work on all
operating systems.
.PP
\&\fIzerofix\fR
.PP
Strips leading zeroes from numbers.
.Sh "timed-build"
.IX Subsection "timed-build"
Summary
.PP
Parameters: \fBfile\fR
.PP
Positional parameters in same order.
.PP
\&\fBThe attribute hash reference is passed\fR after the parameters but
before the container text argument. \fBThis may mean that there are
parameters not shown here.\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
This is a container tag, i.e. [timed-build] \s-1FOO\s0 [/timed-build].
Nesting: \s-1NO\s0
.PP
Invalidates cache: \fBno\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 6
\& $Tag->timed_build(
\& {
\& file => VALUE,
\& },
\& BODY
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 2
\& $Tag->timed_build($file, $ATTRHASH, $BODY);
\& [timed-build file other_named_attributes]
.Ve
.Vb 6
\& Parameters Description Default
\& auto Turn on automatic region processing. none
\& file Name of the cache file. none
\& if Conditional display of the cached region. none
\& minutes Number of minutes after which the timed build should be repeated.60
\& period Alternative way of expressing time. none
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [timed-build file]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->timed_build( { file => VALUE_file
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->timed_build(file, $attribute_hash_reference, $body);
.Ve
Description
.PP
Allows you to build CPU-intensive regions of \s-1ITL\s0 tags on a timed
basis.
.PP
In the simplest case, surround a region of \s-1ITL\s0 with [timed-build]
and [/timed-build]:
.PP
.Vb 3
\& [timed-build]
\& Built at [time]%c[/time].
\& [/timed-build]
.Ve
If a file parameter is not passed, saves to the directory \fItimed\fR
in catalog root, with the file name of the current page. If the
minutes parameter is not passed specifying how often the page
should be rebuilt, then it will not be rebuilt until the output file
is removed.
.PP
Accepts the following parameters:
.PP
\&\fIauto\fR
.PP
Turns on automatic region processing. The text of the timed-build
region is processed to determine a unique checksum or digest (using
\&\s-1MD5\s0), and that file name is checked in the directory tmp/auto-timed
(assuming ScratchDir is set to tmp). If no number of minutes is
supplied, 60 is assumed.
.PP
This is designed to automatically build regions of commonly used areas
without having to manage the file name yourself.
.PP
Implies login=1, but will still abort if no session \s-1ID\s0 cookie has
been sent. Use force=1 to ignore cookie status.
.PP
\&\fIfile\fR
.PP
Name of the file to save the results in. Relative to catalog root. The
directory must exist.
.PP
\&\fIif\fR
.PP
Allows you to to only display the cached region when the if
parameter is true. For example, you can do:
.PP
.Vb 3
\& [timed-build if="[value timed]"]
\& ITL tags....
\& [/timed-build]
.Ve
The cached region will only be displayed if the variable timed is
set to a non-zero, non-blank value. Otherwise, the \s-1ITL\s0 tags will be
re-interpreted every time.
.PP
\&\fIminutes\fR
.PP
The number of minutes after which the timed build should be repeated.
If set to 0, it will be built once and then not rebuilt until the
output file is removed.
.PP
\&\fIperiod\fR
.PP
Alternative way of expressing time. You can pass a string describing
the rebuild time period:
.PP
.Vb 3
\& [timed-build period="4 hours"]
\& ITL tags....
\& [/timed-build]
.Ve
This is really the same as minutes=240. Useful for passing seconds:
.PP
.Vb 3
\& [timed-build period="5 seconds"]
\& ITL tags....
\& [/timed-build]
.Ve
The region will be rebuilt every 5 seconds.
.PP
Performance Tip: use minutes of .08 instead; avoids having to parse
the period string.
.PP
If you have the StaticDir catalog.cfg parameter set to a writable
path, you can build a cached static version of your catalog over time.
Simply place a [timed-build] tag at the top of pages you wish to build
statically. Assuming the catalog is not busy and write lock can be
obtained, the StaticDBM database will be updated to mark the page as
static and the next time a link is made for that page the static
version will be presented.
.Sh "tmp"
.IX Subsection "tmp"
Summary
.PP
Parameters: \fBname\fR
.PP
Positional parameters in same order.
.PP
Pass attribute hash as last to subroutine: \fBno\fR
.PP
Interpolates \fBcontainer text\fR by default.
.PP
This is a container tag, i.e. [tmp] \s-1FOO\s0 [/tmp]. Nesting: \s-1NO\s0
.PP
Invalidates cache: \fB\s-1YES\s0\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 6
\& $Tag->tmp(
\& {
\& name => VALUE,
\& },
\& BODY
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 1
\& $Tag->tmp($name, $BODY);
.Ve
.Vb 1
\& [tmp name]value[/tmp]
.Ve
.Vb 2
\& Parameters Description Default
\& name DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& interpolate Yes
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 1
\& [tmp name]value[/tmp]
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->tmp( { name => VALUE_name
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->tmp(name, $attribute_hash_reference, $body);
.Ve
Description
.PP
Sets a Scratch variable to the value specified in the tag body.
This is just as the [seti] tag would do it, except that the \fIname\fR
is added to the list of Scratch keys that are to be deleted
immediately after the current page has been processed and served. This
saves session write time in many cases.
.PP
This tag interpolates automatically. (Interpolation can be turned off
with interpolate=0.) See also: [tmpn].
.PP
\&\s-1IMPORTANT\s0 \s-1NOTE:\s0 the [tmp ...][/tmp] tag is not appropriate for setting
order profiles or mv_click actions. If you want to avoid that, use
a profile stored via the catalog.cfg directive OrderProfile.
.PP
\&\fIname\fR
.Sh "tmpn"
.IX Subsection "tmpn"
Summary
.PP
Parameters: \fBname\fR
.PP
Positional parameters in same order.
.PP
Pass attribute hash as last to subroutine: \fBno\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
This is a container tag, i.e. [tmpn] \s-1FOO\s0 [/tmpn]. Nesting: \s-1NO\s0
.PP
Invalidates cache: \fB\s-1YES\s0\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 6
\& $Tag->tmpn(
\& {
\& name => VALUE,
\& },
\& BODY
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 1
\& $Tag->tmpn($name, $BODY);
.Ve
.Vb 1
\& [tmpn name]value[/tmp]
.Ve
.Vb 2
\& Parameters Description Default
\& name DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->tmpn( { name => VALUE_name
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->tmpn(name, $attribute_hash_reference, $body);
.Ve
Description
.PP
Equivalent to the [tmp] tag, except that it does not \fIinterpolate\fR
by default.
.PP
\&\s-1NOTE:\s0 This tag was introduced in Interchange 4.9 and is therefore not
available in earlier versions.
.PP
\&\fIname\fR
.Sh "total-cost"
.IX Subsection "total-cost"
Summary
.PP
Parameters: \fBname noformat\fR
.PP
Positional parameters in same order.
.PP
Pass attribute hash as last to subroutine: \fBno\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
Invalidates cache: \fB\s-1YES\s0\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 6
\& $Tag->total_cost(
\& {
\& name => VALUE,
\& noformat => VALUE,
\& }
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 1
\& $Tag->total_cost($name, $noformat);
.Ve
Attribute aliases
.PP
.Vb 2
\& cart ==> name
\& [total-cost name noformat]
.Ve
.Vb 4
\& Parameters Description Default
\& cart Alias for name DEFAULT_VALUE
\& name DEFAULT_VALUE
\& noformat DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [total-cost name noformat]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 3
\& $Tag->total_cost( { name => VALUE_name
\& noformat => VALUE_noformat
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->total_cost(name,noformat, $attribute_hash_reference, $body);
.Ve
Description
.PP
Expands into the total cost of all the items in the current shopping
cart, including sales tax (if any).
.PP
\&\fIname\fR
.PP
\&\fInoformat\fR
.Sh "tree"
.IX Subsection "tree"
Summary
.PP
Parameters: \fBtable master subordinate start\fR
.PP
\&\fBThe attribute hash reference is passed\fR after the parameters but
before the container text argument. \fBThis may mean that there are
parameters not shown here.\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
This is a container tag, i.e. [tree] \s-1FOO\s0 [/tree]. Nesting: \s-1NO\s0
.PP
Invalidates cache: \fBno\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 9
\& $Tag->tree(
\& {
\& table => VALUE,
\& master => VALUE,
\& subordinate => VALUE,
\& start => VALUE,
\& },
\& BODY
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 1
\& $Tag->tree($table, $master, $subordinate, $start, $ATTRHASH, $BODY);
.Ve
Attribute aliases
.PP
.Vb 2
\& sub ==> subordinate
\& [tree table master subordinate start other_named_attributes]
.Ve
.Vb 6
\& Parameters Description Default
\& master DEFAULT_VALUE
\& start DEFAULT_VALUE
\& sub Alias for subordinate DEFAULT_VALUE
\& subordinate DEFAULT_VALUE
\& table DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& interpolate No
\& reparse Yes
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache no
\& Container tag Yes
\& Has Subtags No
\& Nests No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [tree table master subordinate start]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 5
\& $Tag->tree( { master => VALUE_master
\& start => VALUE_start
\& subordinate => VALUE_subordinate
\& table => VALUE_table
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->tree(table,master,subordinate,start, $attribute_hash_reference, $body);
.Ve
Description
.PP
Provides iterative list capability for binary trees. It produces
hash-based rows use the same tags as [item-list]; sets some
additional hash key entries to describe the tree and provide display
control.
.PP
Works on a data set with the structure:
.PP
.Vb 14
\& parent child
\& 99 a
\& a b
\& a c
\& a d
\& a x
\& x y
\& x z
\& 99 m
\& 99 n
\& 99 o
\& o e
\& o f
\& o g
.Ve
Sets several keys which assist in walking and displaying the tree.
.PP
\&\fImv_level\fR
.PP
Level of the item. If it is in the first level, it is 0. Sublevels are
infinite (except for performance).
.PP
\&\fImv_increment\fR
.PP
Increment label for the item. Normally goes from 1...n, but can be
changed to A...Z or a...z in outline mode.
.PP
\&\fImv_children\fR
.PP
If in autodetect mode, set to the number of children this branch has.
If a leaf, set to 0.
.PP
\&\fImv_spacing\fR
.PP
A multiple of level times the spacing option. Useful for setting width
of spacer images.
.PP
The above sample data placed in a table named \*(L"tree\*(R" would produce:
.PP
.Vb 13
\& a mv_level=0, mv_increment=1, mv_children=4
\& b mv_level=1, mv_increment=1, mv_children=0
\& c mv_level=1, mv_increment=2, mv_children=0
\& d mv_level=1, mv_increment=3, mv_children=0
\& x mv_level=1, mv_increment=4, mv_children=2
\& y mv_level=2, mv_increment=1, mv_children=0
\& z mv_level=2, mv_increment=2, mv_children=0
\& m mv_level=0, mv_increment=1, mv_children=0
\& n mv_level=0, mv_increment=2, mv_children=0
\& o mv_level=0, mv_increment=3, mv_children=3
\& e mv_level=1, mv_increment=1, mv_children=0
\& f mv_level=1, mv_increment=2, mv_children=0
\& g mv_level=1, mv_increment=3, mv_children=0
.Ve
from the tag call:
.PP
.Vb 25
\&
\& [tree start=99
\& table=tree
\& master=parent
\& subordinate=child
\& autodetect=1
\& spacing=4
\& full=1]
\&
\&
\& [if-item-param mv_level]
\& [item-calc]
\& return ' ' x [item-param mv_spacing];
\& [/item-calc]
\& [/if-item-param]
\& [item-param child]
\&
\&
\& mv_level=[item-param mv_level],
\& mv_increment=[item-param mv_increment],
\& mv_children=[item-param mv_children]
\&
\&
\& [/tree]
\&
.Ve
Accepts the following parameters:
.PP
\&\fItable\fR
.PP
Database table which contains the tree. Must be a valid Interchange
table identifier.
.PP
\&\fImaster\fR
.PP
The column which is used to determine the parent of the item.
.PP
\&\fIsubordinate\fR
.PP
The child column, which determines which items are sub-items of the
current one. Used to re-query for items with its value in master.
.PP
\&\fIstart_item\fR
.PP
The first item to be followed, i.e. the master value of all the
top-level items.
.PP
\&\fIautodetect\fR
.PP
Specifies that the next level should be followed to detect the number
of child items contained. Not recursive; only follows far enough to
determine the children of the current item.
.PP
\&\fIfull\fR
.PP
Specifies that all items should be followed. Essentially the same as
specifying memo and passing the explode variable, but not
dependent on them. Useful for building lists for inclusion in embedded
Perl, among other things.
.PP
\&\fIstop\fR
.PP
An optional stop field which, when the value is true, can stop the
following of the branch.
.PP
\&\fIcontinue\fR
.PP
An optional continue field which, when the value is true, can force
the branch to be followed.
.PP
\&\fIsort\fR
.PP
The column which should be used for ordering the items \- determines
the order in which they will be displayed under the current parent.
.PP
\&\fIoutline\fR
.PP
Sets outline mode, where mv_increment will be displayed with letter
values or numeral values. If set to specifically 1, will produced
outline increments like:
.PP
.Vb 15
\& 1
\& A
\& B
\& 1
\& 2
\& C
\& 1
\& 2
\& a
\& b
\& 1
\& 2
\& a
\& b
\& 2
.Ve
\&\fImemo\fR
.PP
Indicates that the collapse/explode/toggle features are to be used,
and names a Scratch variable where the values should be stored.
.PP
\&\fIcollapse\fR
.PP
The name of a variable in the user's session which will determine that
the tree should be \*(L"collapsed\*(R". When collapsed, the child items will
not be followed unless they are set to be followed with toggle.
Zeros all toggles.
.PP
Requires memo to be set if values are to be retained.
.PP
\&\fItoggle\fR
.PP
The name of a variable in the user's session which will determine that
the current item should be either followed or not followed. The first
time the toggle variable corresponding to its primary key is
passed, the item will be expanded. The next call will \*(L"collapse\*(R" the
item.
.PP
Requires memo to be set if values are to be retained.
.PP
\&\fIexplode\fR
.PP
The name of a variable in the user's session which will determine that
the tree should be \*(L"exploded\*(R". When exploded, all child items are
followed and the full tree can be displayed.
.PP
Requires memo to be set if values are to be retained.
.PP
\&\fIpedantic\fR
.PP
When set to a true value, and an endless tree is detected (i.e. the
child branch contains a parent) then the error will be logged to the
catalog error log and the tree call will return with an error.
.PP
If pedantic is not set (the default), the current leaf will be
shown but never followed. This allows partial display of the tree.
.PP
\&\fIlog_error\fR
.PP
When set to a true value, and an endless tree is detected (i.e. the
child branch contains a parent) then the error will be logged to the
catalog error log. No logging done by default.
.PP
\&\fIshow_error\fR
.PP
When set to a true value, and an endless tree is detected (i.e. the
child branch contains a parent) then the error will be returned in the
page. Errors are \s-1NOT\s0 shown by default.
.PP
In addition to the above values, all valid options for a list tag are
in force. For example, you can set a \*(L"\s-1SELECTED\s0\*(R" value on an option
list with option=1, set the tag prefix with prefix, etc.
.PP
\&\fImaster\fR
.PP
\&\fIstart\fR
.PP
\&\fIsubordinate\fR
.PP
\&\fItable\fR
.Sh "try"
.IX Subsection "try"
Allows you to trap errors. Interchange processes the body text of the
[try][/try] block and returns it normally if it does not
generate an error. If it does generate an error, Interchange executes
the [catch][/catch] block.
.PP
See also 'catch'.
.PP
Summary
.PP
.Vb 9
\& [try label=my_label other_named_attributes]
\& Body text to return if no error
\& [/try]
\& .
\& .
\& .
\& [catch my_label]
\& Body text to return if try block caused an error
\& [/catch]
.Ve
.Vb 2
\& Parameters Description Default
\& label The label shared by the paired try and catch blocks'default'
.Ve
.Vb 6
\& Attributes Description Default
\& status Returns 0 (failed) or 1 (succeeded) instead of page outputnone
\& hide Suppresses page output No
\& clean Suppress try block output if it has an errorNo
\& interpolate See Interpolating ParametersNo
\& reparse See Interpolating ParametersYes
.Ve
.Vb 3
\& Other_Characteristics
\& Invalidates cache No
\& Container tag Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 7
\& [set divisor]0[/set]
\& [try label=div]
\& [calc] 1 / [scratch divisor] [/calc]
\& [/try]
\& [catch div]Division error[/catch]
\&---
\& Division Error
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 3
\& $Tag->try( { label => I<'try_catch_label'>,
\& status => 1, },
\& $try_body );
.Ve
.Vb 2
\& $Tag->catch( { label => I<'try_catch_label'>, },
\& $catch_body )
.Ve
or similarly with positional parameters,
.PP
.Vb 2
\& $Tag->try($label, $attribute_hash_reference, $try_body);
\& $Tag->catch($label, $attribute_hash_reference, $catch_body);
.Ve
See Also
.PP
catch
.PP
Description
.PP
Allows you to trap errors. Interchange processes the body text of the
[try][/try] block and returns it normally if it does not
generate an error. If it does generate an error, interchange executes
the [catch][/catch] block. The catch block executes where it is
on the page (\fIi.e.\fR, it does not replace the output of the try
block).
.PP
Note that the catch block must occur after the [try] block in the
document.
.PP
\&\fIlabel\fR
.PP
The try and catch blocks are matched by this label.
.PP
Technical note:
.PP
The try tag will also place a result in the \f(CW$Session\fR object. For
example, the following returns the 'Illegal division by zero...' error
message if it occurs:
.PP
.Vb 1
\& [try label=divide][calc] 1 / [scratch divisor] [/calc][/try]
.Ve
.Vb 3
\& [catch divide]
\& [calc]$Session->{try}{divide}[/calc]
\& [/catch]
.Ve
The \f(CW$Session\fR->{try}{divide} object will be set to the empty string
('') if there was no error, or it will contain the error message if
there was an error.
.PP
The [perl] and [calc] tags also set
\&\f(CW$Session\fR->{try}\->{\fIactive_label\fR} on errors.
.PP
\&\fIstatus\fR
.PP
Suppresses try block output and returns 1 if no error or 0 if an
error occurred instead. Executes the catch block as usual in case
of an error.
.PP
\&\fIhide\fR
.PP
Suppresses try block output (regardless of success or failure).
Executes the catch block as usual in case of an error.
.PP
\&\fIclean\fR
.PP
Setting 'clean=1' will cause the try block to suppress its
output only if it has an error. Otherwise (clean=0 or not set), the
try block will return whatever partial output it has completed
before the error. The catch block will work as usual.
.Sh "update"
.IX Subsection "update"
Forces an update of the specified interchange function. Function may
be one of the following:
.Ip "\(bu" 4
\&\fBcart\fR (updates current or named cart)
.Ip "\(bu" 4
\&\fBprocess\fR (updates order or search)
.Ip "\(bu" 4
\&\fBvalues\fR (updates user-entered fields)
.Ip "\(bu" 4
\&\fBdata\fR (updates database, using current \fBmv_\fR \s-1CGI\s0 form variables)
.PP
Summary
.PP
.Vb 1
\& [update function]
.Ve
.Vb 3
\& Parameters Description Default
\& function cartUpdates current or named cart (see name attribute)processUpdates an order or a search pagevaluesUpdates user-entered fieldsdataUpdates database, using current mv_ CGI form variables, for example:mv_data_table Table to updatemv_data_key Key into tablemv_data_fields Fields to update (space or null delimited)mv_data_function One of the following:deleteupdateinsertdeleteetc.DEFAULT_VALUE
\& name Cart name to update (if 'function=cart')Default: current cartDEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [update function]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->update( { function => VALUE_function
\&}, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->update(function, $attribute_hash_reference, $body);
.Ve
Description
.PP
Forces an update of the specified interchange function. Function may
be one of the following:
.Ip "\(bu" 4
\&\fBcart\fR (updates current or named cart)
.Ip "\(bu" 4
\&\fBprocess\fR (updates order or search)
.Ip "\(bu" 4
\&\fBvalues\fR (updates user-entered fields)
.Ip "\(bu" 4
\&\fBdata\fR (updates database, using current \fBmv_\fR \s-1CGI\s0 form variables)
.PP
\&\fIfunction\fR
.Ip "\(bu" 4
cart
.RS 4
.Ip "\(bu" 8
Updates current or named cart (see name attribute)
.RE
.RS 4
.RE
.Ip "\(bu" 4
process
.RS 4
.Ip "\(bu" 8
Updates an order or a search page
.RE
.RS 4
.RE
.Ip "\(bu" 4
values
.RS 4
.Ip "\(bu" 8
Updates user-entered fields
.RE
.RS 4
.RE
.Ip "\(bu" 4
data
.RS 4
.Ip "\(bu" 8
Updates database, using current \fBmv_\fR \s-1CGI\s0 form variables, for
example:
.RS 8
.Ip "\(bu" 12
\&\fBmv_data_table\fR Table to update
.Ip "\(bu" 12
\&\fBmv_data_key\fR Key into table
.Ip "\(bu" 12
\&\fBmv_data_fields\fR Fields to update (space or null delimited)
.Ip "\(bu" 12
\&\fBmv_data_function\fR One of the following:
.RS 12
.Ip "\(bu" 16
delete
.Ip "\(bu" 16
update
.Ip "\(bu" 16
insert
.Ip "\(bu" 16
delete
.RE
.RS 12
.RE
.Ip "\(bu" 12
etc.
.RE
.RS 8
.RE
.RE
.RS 4
.RE
.PP
\&\fIname\fR
.PP
Cart name to update (if 'function=cart')
.Ip "\(bu" 4
Default: current cart
.Sh "userdb"
.IX Subsection "userdb"
Summary
.PP
Parameters: \fBfunction\fR
.PP
Positional parameters in same order.
.PP
\&\fBThe attribute hash reference is passed\fR to the subroutine after the
parameters as the last argument. \fBThis may mean that there are
parameters not shown here.\fR
.PP
Invalidates cache: \fB\s-1YES\s0\fR
.PP
Attribute aliases
.PP
.Vb 3
\& name ==> nickname
\& table ==> db
\& [userdb function other_named_attributes]
.Ve
.Vb 4
\& Parameters Description Default
\& function DEFAULT_VALUE
\& name Alias for nickname DEFAULT_VALUE
\& table Alias for db DEFAULT_VALUE
.Ve
.Vb 2
\& Attributes Default
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [userdb function]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 3
\& $Tag->userdb({
\& function => VALUE
\& });
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->userdb(function, $attribute_hash_reference);
.Ve
Description
.PP
Interchange provides a [userdb ...] tag to access the UserDB
functions.
.PP
.Vb 16
\& [userdb
\& function=function_name
\& username="username"*
\& password="password"*
\& verify="password"*
\& oldpass="old password"*
\& shipping="fields for shipping save"
\& billing="fields for billing save"
\& preferences="fields for preferences save"
\& force_lower=1
\& param1=value*
\& param2=value*
\& hide=1
\& show=1
\& ...
\& ]
.Ve
* Optional
.PP
It is normally called in an mv_click or mv_check setting, as in:
.PP
.Vb 5
\& [set Login]
\& mv_todo=return
\& mv_nextpage=welcome
\& [userdb function=login]
\& [/set]
.Ve
.Vb 5
\&
.Ve
There are several global parameters that apply to any use of the
userdb functions. Most importantly, by default the database table
is set to be \fIuserdb\fR. If you must use another table name, then you
should include a database=table parameter with any call to
userdb. The global parameters (default in parentheses):
.PP
.Vb 20
\& database Sets user database table (userdb)
\& hide Hide the return value of certain functions
\& (including login, new_account, save, load)
\& show Show the return value of certain functions
\& or the error message, if any (0)
\& force_lower Force possibly upper-case database fields
\& to lower case session variable names (0)
\& billing Set the billing fields (see Accounts)
\& shipping Set the shipping fields (see Address Book)
\& preferences Set the preferences fields (see Preferences)
\& bill_field Set field name for accounts (accounts)
\& addr_field Set field name for address book (address_book)
\& pref_field Set field name for preferences (preferences)
\& cart_field Set field name for cart storage (carts)
\& pass_field Set field name for password (password)
\& time_field Set field for storing last login time (time)
\& expire_field Set field for expiration date (expire_date)
\& acl Set field for simple access control storage (acl)
\& file_acl Set field for file access control storage (file_acl)
\& db_acl Set field for database access control storage (db_acl)
.Ve
\&\fIfunction\fR
.PP
\&\fIname\fR
.PP
\&\fItable\fR
.Sh "value"
.IX Subsection "value"
Returns the the current value of the named form input field.
HTML-escapes Interchange tags in the result for security.
.PP
Can also set a new value within the current page.
.PP
Summary
.PP
.Vb 2
\& [value name]
\& [value name=form_var_name other_named_attributes]
.Ve
.Vb 2
\& Parameters Description Default
\& name This is the name of the form variable whose value you want.None
.Ve
.Vb 9
\& Attributes Default
\& set none
\& hide No
\& filter none
\& keep (with filter) No
\& scratch No
\& default none
\& enable_html No
\& interpolate (reparse) No
.Ve
.Vb 2
\& Other_Characteristics
\& Invalidates cache Yes
.Ve
\&\fBTag expansion example:\fR
.PP
Assuming form variable 'foo' = 'bar',
.PP
.Vb 3
\& [value foo]
\&---
\& bar
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 1
\& $Tag->value( { name => var_name } );
.Ve
.Vb 2
\& # or if you simply want the value:
\& $Values->{var_name};
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->value($name, $attribute_hash_reference);
.Ve
Description
.PP
Usage example:
.PP
.Vb 2
\&
\&
.Ve
Expands into the current value of the named customer/form input
field. When the value is returned, any Interchange tags present in the
value will be escaped. This prevents users from entering Interchange
tags in form values, which would be a serious security risk.
.PP
\&\fIname\fR
.PP
This is the name of the form variable whose value you want.
.PP
\&\fIset\fR
.PP
You can change a value with 'set=\fInew_value\fR'. The tag will return
the value you set unless you also set the \fIhide\fR=1 attribute.
.PP
Use this to \*(L"uncheck\*(R" a checkbox or set other form variable values to
defaults. If you simply want a place to store your own data, use the
set and scratch tags instead.
.PP
Note that this is only available in new-style tags, for safety
reasons.
.PP
\&\fIhide\fR
.PP
Setting hide=1 suppresses the tag's return value, which can be
useful with the set attribute.
.PP
\&\fIfilter\fR
.PP
See the filter tag for a list of filters.
.PP
Setting 'filter="\fIfilter\fR"' modifies the named value with the
specified filter.
.PP
\&\fIkeep\fR (with filter)
.PP
Set keep=1 if you want the tag to return a filtered result but do
not want the filter to modify the form value itself in the \f(CW$::Values\fR
hash.
.PP
\&\fIscratch\fR
.PP
Setting 'scratch=1' places a copy of the value in the \f(CW$::Scratch\fR
hash. An illustrative example:
.PP
.Vb 2
\& foo is [value name=foo scratch=1] in the Values hash
\& foo is now also [scratch foo] in the Scratch hash
.Ve
\&\fIdefault\fR
.PP
This sets a return value in case the named value is missing or
otherwise false. The following will expand to \*(L"Using\ default\*(R":
.PP
.Vb 2
\& [value name=myname set=0 hide=1]
\& [value name=myname default="Using default"]
.Ve
\&\fIenable_html\fR
.PP
Any '<' characters will normally be converted into '<' for safety
reasons. This conversion can be disabled using 'enable_html=1'.
.Sh "value-extended"
.IX Subsection "value-extended"
Summary
.PP
Parameters: \fBname\fR
.PP
Positional parameters in same order.
.PP
\&\fBThe attribute hash reference is passed\fR to the subroutine after the
parameters as the last argument. \fBThis may mean that there are
parameters not shown here.\fR
.PP
Must pass named parameter interpolate=1 to cause interpolation.
.PP
Invalidates cache: \fB\s-1YES\s0\fR
.PP
Called Routine:
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 5
\& $Tag->value_extended(
\& {
\& name => VALUE,
\& }
\& )
.Ve
.Vb 1
\& OR
.Ve
.Vb 2
\& $Tag->value_extended($name, $ATTRHASH);
\& [value-extended name other_named_attributes]
.Ve
.Vb 2
\& Parameters Description Default
\& name DEFAULT_VALUE
.Ve
.Vb 3
\& Attributes Default
\& umask none
\& interpolate (reparse) No
.Ve
.Vb 5
\& Other_Characteristics
\& Invalidates cache YES
\& Container tag No
\& Has Subtags No
\& Nests Yes
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 3
\& [value-extended name]
\&---
\& TODO: (tag result)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 1
\& $Tag->value_extended( { name => VALUE_name }, $body );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->value_extended(name, $attribute_hash_reference, $body);
.Ve
Description
.PP
Named call example:
.PP
.Vb 14
\& [value-extended
\& name=formfield
\& outfile=filename*
\& umask=octal*
\& ascii=1*
\& yes="Yes"*
\& no="No"*
\& joiner="char|string"*
\& test="isfile|length|defined"*
\& index="N|N..N|*"
\& file_contents=1*
\& maxsize=length*
\& elements=1*
\& ]
.Ve
Expands into the current value of the customer/form input field named
by field. If there are multiple elements of that variable, it will
return the value at index; by default all joined together with a
space.
.PP
If the variable is a file variable coming from a multipart/form-data
file upload, then the contents of that upload can be returned to the
page or optionally written to the outfile.
.PP
\&\fIname\fR
.PP
Specify which value variable to deal with. If no other parameters are
present, then the value of the variable will be returned. If there are
multiple elements, then by default they will all be returned joined by
a space. If joiner is present, then they will be joined by its
value.
.PP
In the special case of a file upload, the value returned is the name
of the file as passed for upload.
.PP
\&\fIjoiner\fR
.PP
The character or string that will join the elements of the array. Will
accept string literals such as \*(L"\en\*(R" or \*(L"\er\*(R".
.PP
\&\fItest\fR
.PP
Three tests: isfile returns true if the variable is a file upload.
length returns the length. defined returns whether the value has
ever been set at all on a form.
.PP
\&\fIindex\fR
.PP
The index of the element to return if not all are wanted. This is
useful especially for pre-setting multiple search variables. If set to
*, will return all (joined by joiner). If a range, such as 0
\&.. 2, will return multiple elements.
.PP
\&\fIfile_contents\fR
.PP
Returns the contents of a file upload if set to a non-blank, non-zero
value. If the variable is not a file, returns nothing.
.PP
\&\fImaxsize\fR
.PP
The maximum file size allowed, in bytes. If a file of greater size
than maxsize is uploaded, the tag will return false and an error will
be logged.
.PP
\&\fIoutfile\fR
.PP
Names a file to write the contents of a file upload to. It will not
accept an absolute file name; the name must be relative to the catalog
directory. If you wish to write images or other files that would go to
\&\s-1HTML\s0 space, you must use the \s-1HTTP\s0 server's Alias facilities or make
a symbolic link.
.PP
\&\fIumask\fR
.PP
Permission mask (in octal) to apply to the uploaded file's permission
bits. You may want to set this to make a file world-readable, or to
keep it from being group-readable. See the \s-1UNIX\s0 \fIchmod\fR\|(1) manpage for
details.
.PP
\&\fIascii\fR
.PP
To do an auto-ASCII translation before writing the outfile, set the
ascii parameter to a non-blank, non-zero value. Default is no
translation.
.PP
\&\fIyes\fR
.PP
The value that will be returned if a test is true or a file is written
successfully. Defaults to 1 for tests and the empty string for
uploads.
.PP
\&\fIno\fR
.PP
The value that will be returned if a test is false or a file write
fails. Defaults to the empty string.
.SH "User-defined Tags"
.IX Header "User-defined Tags"
To define a tag that is catalog-specific, place \fIUserTag\fR directives
in your catalog.cfg file. For server-wide tags, define them in
interchange.cfg. Catalog-specific tags take precedence if both are
defined \- in fact, you can override the base Interchange tag set with
them. The directive takes the form:
.PP
.Vb 1
\& UserTag tagname property value
.Ve
where tagname is the name of the tag, property is the attribute
(described below), and value is the value of the property for that
tagname.
.PP
The user tags can either be based on Perl subroutines or just be
aliases for existing tags. Some quick examples are below.
.PP
An alias:
.PP
.Vb 1
\& UserTag product_name Alias data products title
.Ve
This will change [product_name 99\-102] into [data products title
99\-102], which will output the title database field for product
code 99\-102. Don't use this with [item-data ...] and
[item-field ...], as they are parsed separately. You can do
[product-name [item-code]], though.
.PP
A simple subroutine:
.PP
.Vb 1
\& UserTag company_name Routine sub { "Your company name" }
.Ve
When you place a [company-name] tag in an Interchange page, the text
Your company name will be substituted.
.PP
A subroutine with a passed text as an argument:
.PP
.Vb 2
\& UserTag caps Routine sub { return "\eU@_" }
\& UserTag caps HasEndTag
.Ve
The tag [caps]This text should be all upper case[/caps] will become
\&\s-1THIS\s0 \s-1TEXT\s0 \s-1SHOULD\s0 \s-1BE\s0 \s-1ALL\s0 \s-1UPPER\s0 \s-1CASE\s0.
.PP
Here is a useful one you might wish to use:
.PP
.Vb 24
\& UserTag quick_table HasEndTag
\& UserTag quick_table Interpolate
\& UserTag quick_table Order border
\& UserTag quick_table Routine <";
\& my @rows = split /\en+/, $input;
\& my ($left, $right);
\& for(@rows) {
\& $out .= '';
\& ($left, $right) = split /\es*:\es*/, $_, 2;
\& $out .= '' unless $left =~ /;
\& $out .= $left;
\& $out .= ' ' unless $left =~ /;
\& $out .= ' ';
\& $out .= $right;
\& $out .= ' ';
\& $out .= "\en";
\& }
\& $out .= '';
\& }
\& EOF
.Ve
Called with:
.PP
.Vb 4
\& [quick-table border=2]
\& Name: [value name]
\& City: [value city][if value state], [value state][/if] [value country]
\& [/quick_table]
.Ve
As is the case with [perl] tag, user tags run under the Perl
\&\fISafe.pm\fR module with warnings disabled. Unlike [perl] tags,
however, user tags use Perl's 'strict' pragma.
.PP
The properties for UserTag are:
.Sh "Alias"
.IX Subsection "Alias"
An alias for an existing (or other user-defined) tag. It takes the
form:
.PP
.Vb 1
\& UserTag tagname Alias tag to insert
.Ve
An Alias is the only property that does not require a \fIRoutine\fR to
process the tag.
.Sh "attrAlias"
.IX Subsection "attrAlias"
An alias for an existing attribute for defined tag. It takes the form:
.PP
.Vb 1
\& UserTag tagname attrAlias alias attr
.Ve
As an example, the standard Interchange value tag takes a named
attribute of name for the variable name, meaning that [value
name=var] will display the value of form field var. If you put this
line in catalog.cfg:
.PP
.Vb 1
\& UserTag value attrAlias identifier name
.Ve
then [value identifier=var] will be an equivalent tag.
.Sh "CanNest"
.IX Subsection "CanNest"
Notifies Interchange that this tag must be checked for nesting. Only
applies to tags that have \fIHasEndTag\fR defined, of course. \s-1NOTE:\s0 Your
routine must handle the subtleties of nesting, so don't use this
unless you are quite conversant with parsing routines. See the
routines tag_loop_list and tag_if in lib/Vend/Interpolate.pm for
an example of a nesting tag.
.PP
.Vb 1
\& UserTag tagname CanNest
.Ve
.Sh "HasEndTag"
.IX Subsection "HasEndTag"
Defines an ending [/tag] to encapsulate your text \- the text in
between the beginning [tagname] and ending [/tagname] will be
the last argument sent to the defined subroutine.
.PP
.Vb 1
\& UserTag tagname HasEndTag
.Ve
.Sh "Implicit"
.IX Subsection "Implicit"
This defines a tag as implicit, meaning it can just be an attribute
instead of an attribute=value pair. It must be a recognized
attribute in the tag definition, or there will be big problems. Use
this with caution!
.PP
.Vb 1
\& UserTag tagname Implicit attribute value
.Ve
If you want to set a standard include file to a fixed value by
default, but don't want to have to specify [include
file=\*(L"/long/path/to/file\*(R"] every time, you can just put:
.PP
.Vb 1
\& UserTag include Implicit file file=/long/path/to/file
.Ve
and [include file] will be the equivalent. You can still specify
another value with [include file=\*(L"/another/path/to/file\*(R"].
.Sh "Interpolate"
.IX Subsection "Interpolate"
The behavior for this attribute depends on whether the tag is a
container (i.e. HasEndTag is defined). If it is not a container,
the Interpolate attribute causes the \fBthe resulting \s-1HTML\s0\fR from the
UserTag to be re-parsed for more Interchange tags. If it is a
container, Interpolate causes the contents of the tag to be parsed
\&\fBbefore\fR the tag routine is run.
.PP
.Vb 1
\& UserTag tagname Interpolate
.Ve
.Sh "InvalidateCache"
.IX Subsection "InvalidateCache"
If this is defined, the presence of the tag on a page will prevent
search cache, page cache, and static builds from operating on the
page.
.PP
.Vb 1
\& UserTag tagname InvalidateCache
.Ve
It does not override [tag flag build][/tag], though.
.Sh "Order"
.IX Subsection "Order"
The optional arguments that can be sent to the tag. This defines not
only the order in which they will be passed to \fIRoutine\fR, but the
name of the tags. If encapsulated text is appropriate (\fIHasEndTag\fR is
set), it will be the last argument.
.PP
.Vb 1
\& UserTag tagname Order param1 param2
.Ve
.Sh "PosRoutine"
.IX Subsection "PosRoutine"
Identical to the Routine argument \- a subroutine that will be called
when the new syntax is not used for the call, i.e. [usertag
argument] instead of [usertag ARG=argument]. If not defined,
\&\fIRoutine\fR is used, and Interchange will usually do the right thing.
.Sh "Routine"
.IX Subsection "Routine"
An inline subroutine that will be used to process the arguments of the
tag. It must not be named, and will be allowed to access unsafe
elements only if the interchange.cfg parameter \fIAllowGlobal\fR is
set for the catalog.
.PP
.Vb 1
\& UserTag tagname Routine sub { "your perl code here!" }
.Ve
The routine may use a \*(L"here\*(R" document for readability:
.PP
.Vb 6
\& UserTag tagname Routine <
\& [bar-button page=page1]
\& PAGE-1
\& [selected]
\& PAGE-1-selected
\& [/selected]
\& [/bar-button]
\& [bar-button page=page2]
\& PAGE-2
\& [selected]
\& PAGE-2-selected
\& [/selected]
\& [/bar-button]
\& [bar-button page=page3]
\& PAGE-3
\& [selected]
\& PAGE-3-selected
\& [/selected]
\& [/bar-button]
\&
\&---
\& PAGE-1 PAGE-2-selected PAGE-3
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 3
\& $Tag->button_bar( { page => $page,
\& current => $current,
\& body => $body} );
.Ve
or similarly,
.PP
.Vb 1
\& $Tag->area($page, $current, $body);
.Ve
See Also
.PP
bar_link routine
.PP
Description
.PP
Displays content based on current page. The content between the
[selected][/selected] tags will be displayed only if the name of the
current page matches the name that was passed to the page parameter
(page=page-name). The default content will be displayed when there is
no match.
.PP
\&\fIpage\fR
.PP
The name of the page for which this definition of the bar-button is
defined.
.PP
\&\fIcurrent\fR
.PP
The name of the current page. Defaults to current page \s-1MV_PAGE\s0.
.Sh "button"
.IX Subsection "button"
.Sh "convert_date"
.IX Subsection "convert_date"
This tag converts a given date format into another format.
.PP
Summary
.PP
.Vb 2
\& [convert_date day* other_named_attributes[/convert_date]
\& [convert_date day=n* other_named_attributes[/convert_date]
.Ve
\&\fBPositional parameters: \fRThe first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.
.PP
.Vb 2
\& Parameters Description Default
\& days The number of days from or before today none
.Ve
.Vb 5
\& Attributes Default
\& format '%d-%b-%Y %I:%M%p' or '%d-%b-%Y'
\& fmt - Alias for format none
\& raw none
\& zerofix none
.Ve
.Vb 4
\& Other_Characteristics
\& Invalidates cache No
\& Macro No
\& Has end tag [/convert_date]
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 23
\& a. [convert-date][/convert-date]
\& b. [convert-date 1][/convert-date]
\& c. [convert-date -1][/convert-date]
\& d. [convert-date]2001-5-1[/convert-date]
\& e. [convert-date]2001-05-01[/convert-date]
\& f. [convert-date]20010515[/convert-date]
\& g. [convert-date raw=1]2001-05-18[/convert-date]
\& h. [convert-date fmt="%d-%m-%Y"]2001-05-18[/convert-date]
\& i. [convert-date]200 1 - --051 =9[/convert-date]
\& j. [convert-date]2001 - --05 -20 11 1 5[/convert-date]
\& k. [convert-date raw=1]2001-05-21 11:15[/convert-date]
\&---
\& a. 18-May-2001 03:15AM (todays day and time)
\& b. 19-May-2001 03:15AM (today + 1 day)
\& c. 17-May-2001 03:15AM (today - 1 day)
\& d. 01-May-2001
\& e. 01-May-2001
\& f. 15-May-2001
\& g. 20010518
\& h. 18-05-2001
\& i. 19-May-2001
\& j. 20-May-2001 11:15AM
\& k. 200105211115
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 1
\& $Tag->convert_date( { days => 1 } );
.Ve
.Vb 2
\& $Tag->convert_date( { body => "2001-05-19 15:35",
\& format => "%d-%m-%Y %H:%M", } );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->convert_date( 1 );
.Ve
Description
.PP
This tag converts almost any given date format into another, possibly
user defined, format.
.PP
\&\fIdays\fR
.PP
Number of days from or before today's date and time. Will only be used
if nothing is supplied between the tags.
.PP
\&\fIformat\fR
.PP
\&\s-1POSIX\s0 time format string of your choice. See Unix \fIstrftime\fR\|(3) manpage
for complete details.
.PP
\&\fIraw\fR
.PP
If this option is set to true, will display given date in raw format,
e.g. yyyymmdd or yyyymmddHHMM.
.PP
\&\fIzerofix\fR
.PP
Strips leading zeroes from numbers.
.Sh "db_date"
.IX Subsection "db_date"
This tag returns the time of last access of the database source file.
.PP
Summary
.PP
.Vb 1
\& [db_date table* format*]
.Ve
\&\fBPositional parameters: \fRThe first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.
.PP
.Vb 3
\& Parameters Description Default
\& table Table name. products
\& format POSIX time format string %A %d %b %Y
.Ve
.Vb 4
\& Other_Characteristics
\& Invalidates cache No
\& Macro No
\& Has end tag No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 7
\& [db-date]
\& [db-date cat]
\& [db-date table=cat format="%d %b %Y"]
\&---
\& Wednesday 02 May 2001 (products.txt)
\& Wednesday 03 May 2001 (cat.txt)
\& 03 May 2001 (cat.txt)
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->db_date( { table => cat,
\& format => "%d %b %Y", } );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->db_date( "cat", "%d %b %Y" );
.Ve
Description
.PP
This tag returns the time of last access of the database source file.
.PP
\&\fItable\fR
.PP
Table name. Defaults to products if not specified.
.PP
\&\fIformat\fR
.PP
\&\s-1POSIX\s0 time format string. See Unix \fIstrftime\fR\|(3) manpage for details.
Defaults to '%A \f(CW%d\fR \f(CW%b\fR \f(CW%Y\fR' when not specified.
.Sh "delete_cart"
.IX Subsection "delete_cart"
This tag deletes a cart from the userdb.
.PP
Summary
.PP
.Vb 2
\& [delete_cart nickname]
\& [delete_cart nickname="cart-name"]
.Ve
\&\fBPositional parameters: \fRThe first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.
.PP
.Vb 2
\& Parameters Description Default
\& nickname Must be an existing nickname none
.Ve
.Vb 4
\& Other_Characteristics
\& Invalidates cache No
\& Macro No
\& Has end tag No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 2
\& [delete_cart mycart]
\& [delete_cart nickname="mycart"]
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 1
\& $Tag->delete_cart( { nickname => "mycart", } );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->delete_cart( "mycart" );
.Ve
See Also
.PP
\&\fIuserdb\fR, \fIload_cart\fR, \fIsave_cart\fR and pages
templates/components/saved_carts_list_small, pages/saved_carts.html
for more examples.
.PP
Description
.PP
Deletes a cart with name nickname from the user database. Basically
the same as [userdb function=delete_cart nickname=mycart].
.PP
\&\fInickname\fR
.PP
Nickname of cart to be deleted.
.Sh "email"
.IX Subsection "email"
This tag takes a recipient address and a body text and uses the
SendmailProgram with \-t option to send email.
.PP
Summary
.PP
.Vb 3
\& [email to subject* reply* from* extra*]Your message[/email]
\& [email to=to_address subject=subject reply=reply_address
\& from=from_address extra=extra_headers]Your message[/email]
.Ve
\&\fBPositional parameters: \fRThe first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.
.PP
.Vb 6
\& Parameters Description Default
\& to Email address of recipient none
\& subject Subject line String:
\& reply Email address to be used for the reply-to headernone
\& from Senders email address First address in MailOrderTo configuration variable
\& extra Additional headers to be included none
.Ve
.Vb 4
\& Other_Characteristics
\& Invalidates cache No
\& Macro No
\& Has end tag [/email]
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 7
\& [email
\& to="foo@bar.com"
\& subject="Greetings"
\& from="bar@foo.com"
\& ]
\& Hello World
\& [/email]
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 6
\& $Tag->email( { to => $to,
\& from => $from,
\& subject => $subject,
\& reply => $reply,
\& extra => $extra,
\& body => $body } );
.Ve
or similarly,
.PP
.Vb 1
\& $Tag->email($to, $subject, $reply, $from, $extra, $body);
.Ve
See Also
.PP
\&\fIemail_raw\fR and etc/mail_receipt, pages/process_return.html,
pages/stock-alert-added.html for examples.
.PP
Description
.PP
Will send the content between the [email][/email] tags as an email to
the recipient (to) using the SendmailProgram with \-t option.
.PP
extra
.PP
Extra headers to be included. Example: Errors-To:
errors@yourdomain.com
.PP
from
.PP
Email address identifying the sender of the message. Will use the
first email address of the MailOrderTo configuration variable if it is
not supplied.
.PP
reply
.PP
Email address to be used for the Reply-to header. No Reply-to header
will be present if this parameter is omitted.
.PP
subject
.PP
Short text describing the content of the message. The Subject line of
an email message. The string will be substituted if this
parameter is omitted.
.PP
to
.PP
Valid email address(es) of the \fIrecipient\fR\|(s). This parameter is
required.
.Sh "email_raw"
.IX Subsection "email_raw"
This tag takes a raw email message, \fBincluding headers\fR, and uses the
SendmailProgram with \-t option.
.PP
Summary
.PP
.Vb 1
\& [email_raw]Your message including headers[/email_raw]
.Ve
.Vb 4
\& Other_Characteristics
\& Invalidates cache No
\& Macro No
\& Has end tag [/email_raw]
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 4
\& [email_raw]
\&From: foo@bar.com
\&To: bar@foo.com
\&Subject: baz
.Ve
The text of the message.
[/email_raw]
.PP
The headers must be at the beginning of the line, and the header must
have a valid To: or it will not be delivered.
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 1
\& $Tag->email_raw( { body => $body } );
.Ve
or similarly,
.PP
.Vb 1
\& $Tag->email_raw($body);
.Ve
See Also
.PP
\&\fIemail\fR
.PP
Description
.PP
Will send the content between the [email_raw][/email_raw] tags as a
raw email message to the recipient specified in the supplied headers
using the SendmailProgram with \-t option.
.Sh "fedex_query"
.IX Subsection "fedex_query"
.Sh "formel"
.IX Subsection "formel"
.Sh "fortune"
.IX Subsection "fortune"
This tag uses the \fIfortune\fR\|(1) command to display a random saying.
.PP
.Vb 1
\& Options:
.Ve
.Vb 4
\& short=yes|no* Select only short (< 160 chars) fortunes
\& a=1 Select from all fortunes, even potentially offensive ones.
\& o=1 Select only from potentially offensive fortunes.
\& raw=1 Don't do any HTML formatting
.Ve
Example:
.PP
.Vb 1
\& [fortune short=yes]
.Ve
.Sh "get-url"
.IX Subsection "get-url"
Fetch a \s-1URL\s0 and return the contents.
.PP
Summary
.PP
.Vb 2
\& [get-url url]
\& [get-url url="valid-url" strip=1*]
.Ve
\&\fBPositional parameters: \fRThe first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.
.PP
.Vb 2
\& Parameters Description Default
\& url Must be a valid URL. Meaning, you have to supply the protocol. Examplehttp://demo.icdevgroup.org/ftp://ftp.icdevgroup.org/none
.Ve
.Vb 2
\& Attributes Default
\& strip none
.Ve
.Vb 4
\& Other_Characteristics
\& Invalidates cache No
\& Macro No
\& Has end tag No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 2
\& [get-url http://demo.icdevgroup.org/]
\& [get-url url="http://demo.icdevgroup.org/" strip=1]
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 1
\& $Tag->get_url( { url => "http://demo.icdevgroup.org/", } );
.Ve
.Vb 2
\& $Tag->get_url( { url => "http://demo.icdevgroup.org/",
\& strip => 1, } );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->get_url( "http://demo.icdevgroup.org/" );
.Ve
Description
.PP
Uses the \s-1LWP\s0 libraries (\s-1LWP:\s0:Simple) to fetch a \s-1URL\s0 and returns the
contents.
.PP
\&\fIstrip\fR
.PP
If the strip option is set, strips everything up to and
everything after .
.PP
\&\fIurl\fR
.PP
Must be a valid \s-1URL\s0 (including protocol).
.Sh "load_cart"
.IX Subsection "load_cart"
This tag loads a cart by name from the userdb.
.PP
Summary
.PP
.Vb 2
\& [load_cart nickname]
\& [load_cart nickname="cart-name"]
.Ve
\&\fBPositional parameters: \fRThe first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.
.PP
.Vb 2
\& Parameters Description Default
\& nickname Must be an existing nickname.Nickname is constructed from:a name parttime modified (time the cart was saved by save_cart tag)type (c for cart, r for recurring)none
.Ve
.Vb 4
\& Other_Characteristics
\& Invalidates cache No
\& Macro No
\& Has end tag No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 2
\& [load_cart mycart:990102732:c]
\& [load_cart nickname="mycart:990102732:c"]
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 1
\& $Tag->load_cart( { nickname => "mycart:990102732:c", } );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->load_cart( "mycart:990102732:c" );
.Ve
See Also
.PP
\&\fIuserdb\fR, \fIdelete_cart\fR, \fIsave_cart\fR and pages
templates/components/saved_carts_list_small, pages/saved_carts.html
for more examples.
.PP
Description
.PP
Loads a cart with name nickname from the user database. It will be
merged with the current cart. Basically the same as [userdb
function=get_cart nickname=cartname merge=1].
.PP
\&\fInickname\fR
.PP
Nickname of cart to be loaded. See above.
.Sh "loc"
.IX Subsection "loc"
.Sh "rand"
.IX Subsection "rand"
.Sh "reconfig"
.IX Subsection "reconfig"
.Sh "reconfig_time"
.IX Subsection "reconfig_time"
.Sh "reconfig_wait"
.IX Subsection "reconfig_wait"
.Sh "save_cart"
.IX Subsection "save_cart"
This tag saves the current cart or recurring order in the userdb under
a given name.
.PP
Summary
.PP
.Vb 2
\& [save_cart nickname recurring]
\& [save_cart nickname="cart-name" recurring=1]
.Ve
\&\fBPositional parameters: \fRThe first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.
.PP
.Vb 3
\& Parameters Description Default
\& nickname Label for the cart. none
\& recurring Set to true if recurring. Set to false, or omit if cart.none
.Ve
.Vb 4
\& Other_Characteristics
\& Invalidates cache No
\& Macro No
\& Has end tag No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 2
\& [save_cart mycart]
\& [save_cart nickname=mycart recurring=1]
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->save_cart( { nickname => mycart,
\& recurring => 1, } );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->save_cart( "mycart", "1" );
.Ve
See Also
.PP
\&\fIuserdb\fR, \fIdelete_cart\fR, \fIload_cart\fR and pages
templates/components/saved_carts_list_small, pages/saved_carts.html
for more examples.
.PP
Description
.PP
Saves the current cart with name nickname in the user database.
Basically the same as [userdb function=set_cart nickname=cartname]
.PP
\&\fInickname\fR
.PP
Nickname for the current cart to be saved. You can use same nickname
for different carts. An index will be added if there are more carts
with the same nickname.
.PP
\&\fIrecurring\fR
.PP
Set to true if recurring. Set to false, or simply omit it, if it is a
cart.
.Sh "summary"
.IX Subsection "summary"
This tag calculates column totals.
.PP
Summary
.PP
.Vb 2
\& [summary amount]
\& [summary amount=n.nn other_named_attributes]
.Ve
\&\fBPositional parameters: \fRThe first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.
.PP
.Vb 2
\& Parameters Description Default
\& amount Numerical value to be added to previous totalnone
.Ve
.Vb 7
\& Attributes Default
\& currency none
\& format none
\& hide none, no hiding
\& name ONLY0000, internal use only
\& reset none
\& total none
.Ve
.Vb 4
\& Other_Characteristics
\& Invalidates cache No
\& Macro No
\& Has end tag No
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 8
\& [loop list="10 20 30.5"]
\& [summary amount="[loop-code]" hide=1]
\& [/loop]
\& [summary total=1 format="%.3f"]
\& [summary total=1 currency=1]
\&---
\& 60.500
\& $60.50
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->summary( { amount => 10.5,
\& hide => 1, } );
.Ve
.Vb 3
\& $Tag->summary( { amount => 25,
\& name => mytotal,
\& currency => 1, } );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->summary( 10.5, $attribute_hash_reference );
.Ve
See Also
.PP
templates/components/cart, pages/ord/checkout.html for more examples.
.PP
Description
.PP
The summary tag provides you with an easy way to calculate and display
totals. The display of the amounts is fully customizable. You can hide
display, or you can show the amounts with the proper currency
formatting according to the locale, or you can define your own
formatting. Any number of summaries can be kept on a page.
.PP
\&\fIcurrency\fR
.PP
The amount or total will be displayed according to the currency
formatting of the current locale if this attribute is set to true (non
blank or zero).
.PP
\&\fIformat\fR
.PP
You can choose any formatting of the amount you like. Just set the
format attribute to the desired formatting string (%s, %.2f etc.).
When both, currency and format attributes are set, the format
attribute will take precedence. So it doesn't make much sense to set
them both at the same time.
.PP
\&\fIhide\fR
.PP
Will suppress the display of amount when set to true.
.PP
\&\fIname\fR
.PP
You can calculate as many totals as you like on the same page. Just
supply a different label for each summary.
.PP
\&\fIreset\fR
.PP
Will erase the \fItotal\fR\|(s) if set to true. Be careful tough. It will
reset \s-1ALL\s0 totals when you have no name attribute supplied. If you have
provided a label for the name attribute then it will only reset the
total for that particular label. All others won't be touched.
.PP
\&\fItotal\fR
.PP
Will show the total instead of the amount if set to true.
.Sh "table_organize"
.IX Subsection "table_organize"
Takes an unorganized set of table cells and organizes them into rows
based on the number of columns.
.PP
Summary
.PP
.Vb 3
\& [table-organize cols* other_named_attributes]
\& [loop ....] [loop-tags] [/loop]
\& [/table-organize]
.Ve
.Vb 3
\& [table-organize cols=n* other_named_attributes]
\& [loop ....] [loop-tags] [/loop]
\& [/table-organize]
.Ve
\&\fBPositional parameters: \fRThe first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.
.PP
.Vb 3
\& Parameters Description Default
\& cols Number of columns. 2
\& columns Alias for cols. 2
.Ve
.Vb 11
\& Attributes Default
\& caption none
\& columnize none
\& embed none
\& filler
\& limit none
\& pretty none
\& rows none
\& table none
\& td none
\& tr none
.Ve
.Vb 4
\& Other_Characteristics
\& Invalidates cache No
\& Macro No
\& Has end tag [/table-organize]
.Ve
\&\fBTag expansion example:\fR
.PP
This example produces a table that (1) alternates rows with background
colors \*(L"#EEEEEE\*(R" and \*(L"#FFFFFF\*(R", and (2) aligns the columns right,
center, left:
.PP
.Vb 27
\& [table-organize
\& cols=3
\& pretty=1
\& tr.0='bgcolor="#EEEEEE"'
\& tr.1='bgcolor="#FFFFFF"'
\& td.0='align=right'
\& td.1='align=center'
\& td.2='align=left'
\& ]
\& [loop list="1 2 3 1a 2a 3a 1b"] [loop-code] [/loop]
\& [/table-organize]
\&---
\&
\& 1
\& 2
\& 3
\&
\&
\& 1a
\& 2a
\& 3a
\&
\&
\& 1b
\&
\&
\&
.Ve
If the attribute columnize=1 is present, the result will look like:
.PP
.Vb 15
\&
\& 1
\& 1a
\& 1b
\&
\&
\& 2
\& 2a
\&
\&
\&
\& 3
\& 3a
\&
\&
.Ve
See the source for more ideas on how to extend this tag.
.PP
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->table_organize( { cols => 3,
\& pretty => 1, }, $BODY );
.Ve
or similarly with positional parameters:
.PP
.Vb 1
\& $Tag->table_organize( $cols, $attribute_hash_reference, $BODY );
.Ve
See Also
.PP
pages/flypage.html, pages/quantity.html,
templates/components/best_horizontal, templates/components/cart,
templates/components/cross_horizontal, templates/components/random,
templates/components/random_vertical, templates/components/upsell
.PP
Description
.PP
Takes an unorganized set of table cells and organizes them into rows
based on the number of columns; it will also break them into separate
tables.
.PP
If the number of cells are not on an even modulus of the number of
columns, then \*(L"filler\*(R" cells are pushed on.
.PP
\&\fIcols (or columns)\fR
.PP
Number of columns. This argument defaults to 2 if not present.
.PP
\&\fIrows\fR
.PP
Optional number of rows. Implies \*(L"table\*(R" parameter.
.PP
\&\fItable\fR
.PP
If present, will cause a surrounding <\s-1TABLE\s0> pair with the
attributes specified in this option.
.PP
\&\fIcaption\fR
.PP
Table <\s-1CAPTION\s0> container text, if any. Can be an array.
.PP
\&\fItd\fR
.PP
Attributes for table cells. Can be an array.
.PP
\&\fItr\fR
.PP
Attributes for table rows. Can be an array.
.PP
\&\fIcolumnize\fR
.PP
Will display cells in (newspaper) column order, i.e. rotated.
.PP
\&\fIpretty\fR
.PP
Adds newline and tab characters to provide some reasonable indenting.
.PP
\&\fIfiller\fR
.PP
Contents to place in empty cells put on as filler. Defaults to
\&\*(L" \*(R".
.PP
\&\fIlimit\fR
.PP
Maximum number of cells to use. Truncates extra cells silently.
.PP
\&\fIembed\fR
.PP
If you want to embed other tables inside, make sure they are called
with lower case elements, then set the embed tag and make the
cells you wish to organize be <\s-1TD\s0> elements. To switch that sense, and
make the upper-case or mixed case be the ignored cells, set the embed
parameter to \*(L"lc\*(R".
.PP
.Vb 10
\& [table-organize embed=lc]
\&
\&
\&
\& [/table-organize]
.Ve
or
.PP
.Vb 10
\& [table-organize embed=uc]
\&
\&
\&
\& [/table-organize]
.Ve
The \*(L"tr\*(R", \*(L"td\*(R", and \*(L"caption\*(R" attributes can be specified with
indexes; if they are, then they will alternate according to the
modulus.
.PP
The \*(L"td\*(R" option array size should probably always equal the number of
columns; if it is bigger, then trailing elements are ignored. If it is
smaller, no attribute is used.
.Sh "title_bar"
.IX Subsection "title_bar"
Creates a quick title bar.
.PP
Summary
.PP
.Vb 2
\& [title-bar width size color]My title[/title-bar]
\& [title-bar width=600 size=5 color="#ff0000"]My title[/title-bar]
.Ve
\&\fBPositional parameters: \fRThe first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.
.PP
.Vb 4
\& Parameters Description Default
\& color Background color the bar.Defaults tovariable HEADERBG or#444444HEADERBG or #444444
\& size Font size 6
\& width Width of the title bar 500
.Ve
.Vb 4
\& Other_Characteristics
\& Invalidates cache No
\& Macro No
\& Has end tag [/title-bar]
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 2
\& [title-bar 600 5 red]My title[/title-bar]
\& [title-bar width=600 size=5 color="#ff0000"]My title[/title-bar]
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 1
\& $Tag->title_bar( { body => "My Title", } );
.Ve
.Vb 3
\& $Tag->title_bar( { width => 400,
\& color => "#0000ff",
\& body => "My title", } );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->title_bar( 600, 5, "red", "My title" );
.Ve
Description
.PP
Quickly adds a title bar to your pages without having to type the html
each time. Background color, width of the bar and size of the text can
be customized by setting the appropriate parameter. The text color
defaults to variable \s-1HEADERTEXT\s0 or when its not present to white.
.PP
\&\fIcolor\fR
.PP
Sets the background color of the bar. You can set the color as 'red',
\&'#ff0000', or 'bgcolor=\*(L"#ff0000\*(R"'.
.PP
\&\fIsize\fR
.PP
Determines the size of the text. Parameter should be set to a value
accepted by the \s-1HTML\s0 tag size attribute.
.PP
\&\fIwidth\fR
.PP
Sets the width of the bar.
.Sh "ups_query"
.IX Subsection "ups_query"
.Sh "usertrack"
.IX Subsection "usertrack"
.Sh "var"
.IX Subsection "var"
.Sh "xml-generator"
.IX Subsection "xml-generator"
This is a quick and dirty tag that generates \s-1XML\s0 tags based upon one
of two types of data (delimited and session).
.PP
Summary
.PP
.Vb 3
\& [xml-generator type* other_named_attributes][/xml-generator]
\& [xml-generator type=value* other_named_attributes][/xml-generator]
\& [xml-generator type=value* other_named_attributes][][/xml-generator]
.Ve
*Optional
.PP
\&\fBPositional parameters: \fRThe first line shows the usage with
positional parameters (given in order). The second line shows usage
with named parameters.
.PP
.Vb 2
\& Parameters Description Default
\& type Data type. Delimited or session delimited
.Ve
.Vb 13
\& Attributes Default
\& attributes none
\& dbdump none
\& delimiter \et
\& field_names
\& separator \en
\& toplevel_tag 'table' for delimited type and 'session' for other type
\& record_tag record
\& field_tag field
\& key_name none
\& spacer [\es,]+
\& no_second none
\& skip_empty none
.Ve
.Vb 4
\& Other_Characteristics
\& Invalidates cache No
\& Macro No
\& Has end tag [/xml-generator]
.Ve
\&\fBTag expansion example:\fR
.PP
.Vb 24
\& [xml-generator type=delimited
\& attributes="date"
\& date="[tag time]%d-%b-%Y[/tag]"
\& toplevel_tag=products
\& ]code description price
\& [query list=1
\& sql="select sku, description, price from products"
\& prefix=xml][xml-code] [xml-param description] [xml-param price]
\& [/query]
\& [/xml-generator]
\&---
\&
\&
\& os28113
\& The Claw Hand Rake
\& 14.99
\&
\&
\& os28006
\& Painters Brush Set
\& 29.99
\&
\& ...
\&
.Ve
\&\fBASP-like Perl call:\fR
.PP
.Vb 2
\& $Tag->xml_generator( {type => delimited,
\& toplevel_tag => apex, }, $BODY );
.Ve
or similarly with positional parameters,
.PP
.Vb 1
\& $Tag->xml_generator( $type, $attribute_hash_reference, $BODY );
.Ve
Description
.PP
\&\fItype\fR
.PP
delimited
.PP
Accepts a delimited and separated (default is \s-1TAB\s0 delimiter and
newline separator) list of records such as that generated by an
\&'[item-list]', '[sql]', or '[loop search=""]' \s-1ITL\s0 tag.
.PP
session
.PP
When the type is not delimited, it can contain any hash reference into
the Interchange session. Examples are:
.PP
.Vb 5
\& values The form values
\& scratch Scratch values
\& errors Error values
\& other Any other Session key, for example "source" for
\& [data session source]
.Ve
If the value is a hash, then it will be sent as an \s-1XML\s0 record with the
top level equal to \*(L"session\*(R", and a second_level tag equal to the hash
name, and keys as separate \s-1XML\s0 container tags. If the parameter \*(L"that
is equal to the type\*(R" is given, only those fields will be shown.
Otherwise the entire hash will be shown. For example, this tag:
.PP
.Vb 1
\& [xml-generator type="values" values="fname lname"][/xml-generator]
.Ve
will generate:
.PP
.Vb 6
\&
\&
\& First
\& Last
\&
\&
.Ve
if it is a scalar, then only the second level will be done:
.PP
.Vb 1
\& [xml-generator type="cybercash_id"][/xml-generator]
.Ve
will do the equivalent of:
.PP
.Vb 3
\&
\& [data session cybercash_id]
\&
.Ve
So bringing it all together, the following:
.PP
.Vb 4
\& [xml-generator type="values scratch source"
\& values="fname lname"
\& scratch="downloads"][/xml-generator]
\&will generate:
.Ve
.Vb 10
\&
\&
\& First
\& Last
\&
\&
\& 0
\&
\& Partner1
\&
.Ve
\&\fIno_second\fR
.PP
Prevents the second-level tags from being generated. Extending the
last example in the \*(L"session\*(R" type above, this
.PP
.Vb 5
\& [xml-generator type="values scratch source"
\& no_second=1
\& values="fname lname"
\& scratch="downloads"][/xml-generator]
\&will generate:
.Ve
.Vb 6
\&
\& First
\& Last
\& 0
\& Partner1
\&
.Ve
\&\fIattributes\fR
.PP
The attributes (if any) to pass on to the top level tag. For instance,
.PP
.Vb 5
\& [xml-generator
\& attributes="date"
\& date="[tag time]%d-%b-%Y[/tag]"
\& toplevel_tag=order
\& ][/xml-generator]
.Ve
will generate a toplevel tag pair of:
.PP
.Vb 2
\&
\&
.Ve
\&\fIdbdump\fR
.PP
Will dump all tables in the catalog when this attribute is set true.
Used attributes are \*(L"toplevel_tag\*(R", \*(L"record_tag\*(R", \*(L"field_tag\*(R", and
\&\*(L"skip_empty\*(R" or default values ('table', 'record', 'field'
respectively).
.PP
.Vb 19
\& Output format:
\&
\&
\&
\& fieldvalue1
\& fieldvalue2
\&
\&
\& fieldvalue1
\& fieldvalue2
\&
\&
\&
\&
\& fieldvalue1
\& fieldvalue2
\&
\&
\&
.Ve
\&\fBImportant note:\fR All tables are read into memory. So be warned, this
could be a real memory hog.
.PP
Ton Verhagen's proposal:
.Ip "1." 4
Add option to select tables. E.g. dump_tables=\*(L"products cat area\*(R"
and/or
.Ip "2." 4
Add option to select an output file. E.g. dump_file=\*(L"tabledump.XML\*(R".
Send output to file line by line.
.PP
\&\fIdelimiter\fR
.PP
Character used as delimiter of fields in delimited data type. Defaults
to a tab character.
.PP
\&\fIfield_names\fR
.PP
Space or comma-delimited list of field names to be used for delimited
data type. Should be in the same order as in the data list provided
(between the tags).
.PP
Another way of providing the field names would be:
.PP
.Vb 4
\& [xml-generator .....]fieldname-1 fieldname-2 fieldname-3
\& [field value list
\& delimited by option delimiter and
\& separated by option separator][/xml-generator]
.Ve
\&\fBNote: \fRField name list \fBmust\fR be tab delimited.
.PP
Ton Verhagen's humble opinion: This should change in future versions!
Use option delimiter instead.
.PP
\&\fIseparator\fR
.PP
Character used as line separator in list between
[xml-separator][xml-separator] tags and in output 'session' data type.
Defaults to a newline, \*(L"\en\*(R".
.PP
\&\fItoplevel_tag\fR
.PP
The toplevel tag name to use. Defaults to \*(L"table\*(R" for the 'dbdump
mode' and delimited type, and \*(L"session\*(R" for the other.
.PP
\&\fIrecord_tag\fR
.PP
Defines the tag name for the record tag. Defaults to 'record'. Used
for 'dbdump mode' and delimited type.
.PP
\&\fIfield_tag\fR
.PP
Defines the tag name for the field tag. Defaults to 'field'. Only used
in 'dbdump mode'.
.PP
\&\fIkey_name\fR
.PP
Only used in delimited data type. Defines fieldname to determine key
value in \*(L"record_tag\*(R".
.PP
.Vb 1
\& ....
.Ve
\&\fIspacer\fR
.PP
Character used as delimiter in type parameter definition and
corresponding attributes. Defaults to '[\es,]+' (one or more whitespace
or comma).
.PP
.Vb 5
\& [xml-generator type="values|scratch"
\& values="value1|value2"
\& scratch="scratch1|scratch2"
\& spacer="|"
\& ][/xml-generator]
.Ve
\&\fIskip_empty\fR
.PP
Only used in \fIdbdump\fR mode (dbdump=1). Will skip empty fields if this
attribute is set true.
.PP
Template Parsing Order
.PP
Standard Parsing
.PP
Under normal circumstances, the template page containing tags and \s-1HTML\s0
is parsed in the following order:
.Ip "1." 4
Any content in \s-1MV_AUTOLOAD\s0 is prepended to the template page.
.RS 4
.Ip "" 8
.RE
.RS 4
.Sp
.RE
.Ip "2." 4
Any [pragma] tags anywhere in the text are processed, and the
specified pragmas are set.
.RS 4
.Ip "\(bu" 8
Since [pragma] tags are preprocessed before any other content,
reparse will not catch them, nor will they work if included in
variables. Also, the specified pragma will apply to the entire
template (not just the section after the tag).
.Ip "\(bu" 8
If you want to apply a pragma with a variable or only to part of a
document, you must use [tag pragma=\*(L"...\*(R"] instead.
.RE
.RS 4
.Sp
.RE
.Ip "3." 4
Variables (macros) are processed in the following order:
.RS 4
.Ip "4." 8
@@VARNAME@@ global variables
.Ip "5." 8
@_VARNAME_@ local or global variables
.Ip "6." 8
_\|_VARNAME_\|_ local variables
.RE
.RS 4
.Sp
.RE
.Ip "7." 4
Interchange comments are stripped.
.RS 4
.Ip "" 8
.RE
.RS 4
.Sp
.RE
.Ip "8." 4
False-endtag macros are expanded (e.g., [/page] and [/order]).
.RS 4
.Ip "" 8
.RE
.RS 4
.Sp
.RE
.Ip "9." 4
\&'' escapes are converted to [tagname]
.RS 4
.Ip "\(bu" 8
This can be a convenience for your \s-1HTML\s0 editor if it has trouble with
tags using the standard [tagname] syntax.
.Ip "\(bu" 8
However, if you want to HTML-comment out an Interchange tag in content
that will be fed raw to a browser, you must include whitespace between
the \s-1HTML\s0 comment delimiters and the tag, like this, ''.
.RE
.RS 4
.Sp
.RE
.Ip "10." 4
.IX Item "10."
The main tag parser is called.
.RS 4
.Ip "\(bu" 8
Some tags parse recursively (depending upon reparse and
interpolate settings, of course).
.Ip "\(bu" 8
Some tags (e.g., [loop]) process PREFIX-tags in their contained
body text. Hence, the PREFIX-tags are not handled recursively.
.Ip "\(bu" 8
Some tags are interpreted in the lib/Vend/Parse.pm:start routine. You
cannot call them with the '$Tag->\fItagname\fR()' syntax. They are:
.RS 8
.Ip "\(bu" 12
The [goto] tag. Note also that the [goto] tag handles the
[label] tag.
.Ip "\(bu" 12
The [bounce] tag.
.RE
.RS 8
.RE
.RE
.RS 4
.Sp
.RE
.Ip "11." 4
.IX Item "11."
Image paths substitution on the \s-1HTML\s0 output occurs.
.RS 4
.Ip "" 8
.RE
.RS 4
.Sp
.RE
.PP
Nonstandard parsing within the admin interface
.PP
Parsing of content via the specialized [regenerate] usertag
included with the administrative interface does not obey the above
order. The \s-1MV_AUTOLOAD\s0 and '' escapes are skipped.
There are some other more subtle differences as well; in the very
unlikely event that you need to check this in the source code, compare
the 'interpolate_html' and 'cache_html' routines in Interpolate.pm.
.PP
Nonstandard parsing of Subtags
.PP
Subtags are parsed within the containing array-list or hash-list
context created by the containing tag (see \fILooping tags and
Sub-tags\fR).
.Ip "\(bu" 4
All subtags at an earlier precedence level are treated before any in
the next level.
.Ip "\(bu" 4
Within the same level, tags are processed in the order the appear on
the page.
.Ip "\(bu" 4
Any standard tags are processed during 'interpolate' (before) or
\&'reparse' (after) phases of processing the containing tag.
.PP
\&\fBTechnical note\fR
.PP
Processing within a hash- or array-list is actually done as a series
of global regular expression substitutions on the page. Each
substitution replaces one tag with the output of the \fIsubroutine\fR\|(s)
associated with it.
.PP
In array-list context, subtags are processed in the following
order:
.Ip "1." 4
Check for \s-1PREFIX-\s0\fBline\fR and prepare for it if present (does not
process \s-1PREFIX-\s0\fBline\fR at this time)
.Ip "2." 4
\&\s-1PREFIX-\s0\fBsub\fR definitions processed
.Ip "3." 4
\&\fBif\fR\-PREFIX-\fI*\fR nesting resolved
.Ip "4." 4
\&\s-1PREFIX-\s0\fBalternate\fR processed
.Ip "5." 4
\&\fBif\fR\-PREFIX-\fBparam\fR processed
.Ip "6." 4
\&\fBif\fR\-PREFIX-\fBpos\fR processed
.Ip "7." 4
\&\s-1PREFIX-\s0\fBpos\fR processed
.Ip "8." 4
\&\fBif\fR\-PREFIX-\fBfield\fR processed
.Ip "9." 4
\&\s-1PREFIX-\s0\fBline\fR processed
.Ip "10." 4
.IX Item "10."
\&\s-1PREFIX-\s0\fBincrement\fR processed
.Ip "11." 4
.IX Item "11."
\&\s-1PREFIX-\s0\fBaccessories\fR processed
.Ip "12." 4
.IX Item "12."
\&\s-1PREFIX-\s0\fBoptions\fR processed
.Ip "13." 4
.IX Item "13."
\&\s-1PREFIX-\s0\fBcode\fR processed
.Ip "14." 4
.IX Item "14."
\&\s-1PREFIX-\s0\fBdescription\fR processed
.Ip "15." 4
.IX Item "15."
\&\s-1PREFIX-\s0\fBfield\fR processed
.Ip "16." 4
.IX Item "16."
\&\s-1PREFIX-\s0\fBprice\fR processed
.Ip "17." 4
.IX Item "17."
\&\s-1PREFIX-\s0\fBchange\fR processed
.Ip "18." 4
.IX Item "18."
\&\s-1PREFIX-\s0\fBcalc\fR processed
.Ip "19." 4
.IX Item "19."
\&\s-1PREFIX-\s0\fBexec\fR processed
.Ip "20." 4
.IX Item "20."
\&\s-1PREFIX-\s0\fBfilter\fR processed
.Ip "21." 4
.IX Item "21."
\&\s-1PREFIX-\s0\fBlast\fR processed
.Ip "22." 4
.IX Item "22."
\&\s-1PREFIX-\s0\fBnext\fR processed
.Ip "23." 4
.IX Item "23."
User's previous \s-1HTML\s0 widget \s-1SELECTED\s0 settings restored
.Ip "24." 4
.IX Item "24."
Reparse standard tags in output of above (if reparse enabled for the
containing tag)
.PP
In hash-list context, subtags are processed in the following order:
.Ip "1." 4
\&\s-1PREFIX-\s0\fBsub\fR definitions processed
.Ip "2." 4
\&\fBif\fR\-PREFIX-\fI*\fR nesting resolved
.Ip "3." 4
\&\s-1PREFIX-\s0\fBalternate\fR processed
.Ip "4." 4
\&\s-1PREFIX-\s0\fBline\fR processed
.Ip "5." 4
\&\fBif\fR\-PREFIX-\fBparam\fR processed
.Ip "6." 4
\&\fBif\fR\-PREFIX-\fBfield\fR processed
.Ip "7." 4
\&\fBif\fR\-PREFIX-\fBmodifier\fR processed (\fBif\fR\-PREFIX-\fBparam\fR and
\&\fBif\fR\-PREFIX-\fBmodifier\fR are functionally identical except for parse
order)
.Ip "8." 4
\&\s-1PREFIX-\s0\fBincrement\fR processed
.Ip "9." 4
\&\s-1PREFIX-\s0\fBaccessories\fR processed
.Ip "10." 4
.IX Item "10."
\&\s-1PREFIX-\s0\fBoptions\fR processed
.Ip "11." 4
.IX Item "11."
\&\s-1PREFIX-\s0\fBsku\fR processed
.Ip "12." 4
.IX Item "12."
\&\s-1PREFIX-\s0\fBcode\fR processed
.Ip "13." 4
.IX Item "13."
\&\s-1PREFIX-\s0\fBquantity\fR processed
.Ip "14." 4
.IX Item "14."
\&\s-1PREFIX-\s0\fBmodifier\fR processed
.Ip "15." 4
.IX Item "15."
\&\s-1PREFIX-\s0\fBparam\fR processed
.Ip "16." 4
.IX Item "16."
\&\s-1PREFIX-\s0\fBquantity-name\fR processed
.Ip "17." 4
.IX Item "17."
\&\s-1PREFIX-\s0\fBmodifier-name\fR processed
.Ip "18." 4
.IX Item "18."
\&\s-1PREFIX-\s0\fBsubtotal\fR processed
.Ip "19." 4
.IX Item "19."
\&\s-1PREFIX-\s0\fBdiscount-subtotal\fR processed
.Ip "20." 4
.IX Item "20."
\&\s-1PREFIX-\s0\fBcode\fR processed again differently (operating on new
instances of \s-1PREFIX-\s0\fBcode\fR in output of above?)
.Ip "21." 4
.IX Item "21."
\&\s-1PREFIX-\s0\fBfield\fR processed
.Ip "22." 4
.IX Item "22."
\&\s-1PREFIX-\s0\fBdescription\fR processed
.Ip "23." 4
.IX Item "23."
\&\s-1PREFIX-\s0\fBprice\fR processed
.Ip "24." 4
.IX Item "24."
\&\s-1PREFIX-\s0\fBdiscount-price\fR processed
.Ip "25." 4
.IX Item "25."
\&\s-1PREFIX-\s0\fBdifference\fR processed
.Ip "26." 4
.IX Item "26."
\&\s-1PREFIX-\s0\fBdiscount\fR processed
.Ip "27." 4
.IX Item "27."
\&\s-1PREFIX-\s0\fBchange\fR processed
.Ip "28." 4
.IX Item "28."
\&\s-1PREFIX-\s0\fBtag\fR processed (*** \s-1CHECK\s0 \s-1THIS\s0 \s-1TAG\s0 \s-1NAME\s0 ***)
.Ip "29." 4
.IX Item "29."
\&\s-1PREFIX-\s0\fBcalc\fR processed
.Ip "30." 4
.IX Item "30."
\&\s-1PREFIX-\s0\fBexec\fR processed
.Ip "31." 4
.IX Item "31."
\&\s-1PREFIX-\s0\fBfilter\fR processed
.Ip "32." 4
.IX Item "32."
\&\s-1PREFIX-\s0\fBlast\fR processed
.Ip "33." 4
.IX Item "33."
\&\s-1PREFIX-\s0\fBnext\fR processed
.Ip "34." 4
.IX Item "34."
User's previous \s-1HTML\s0 widget \s-1SELECTED\s0 settings restored
.Ip "35." 4
.IX Item "35."
Reparse standard tags in output of above (if reparse enabled for the
containing tag)
.PP
Search and Form Variables
.PP
Variable Names
.PP
\&\fIother\fR
.PP
.Vb 76
\& Name scan Type Description
\& mv_all_chars ac S Turns on punctuation matching
\& mv_arg[0-9]+ A Parameters for mv_subroutine (mv_arg0,mv_arg1,...)
\& mv_base_directory bd S Sets base directory for search file names
\& mv_begin_string bs S Pattern must match beginning of field
\& mv_case cs S Turns on case sensitivity
\& mv_cartname O Sets the shopping cart name
\& mv_check A Any form, sets multiple user variables after update
\& mv_click A Any form, sets multiple form variables before update
\& mv_click XA Default mv_click routine, click is mv_click_arg
\& mv_click name XA Routine for a click name, sends click as arg
\& mv_click_arg XA Argument name in scratch space
\& mv_coordinate co S Enables field/spec matching coordination
\& mv_column_op op S Operation for coordinated search
\& mv_credit_card* O Discussed in order security (some are read-only)
\& mv_dict_end de S Upper bound for binary search
\& mv_dict_fold df S Non-case sensitive binary search
\& mv_dict_limit di S Sets upper bound based on character position
\& mv_dict_look dl S Search specification for binary search
\& mv_dict_order do S Sets dictionary order mode
\& mv_doit A Sets default action
\& mv_email O Reply-to address for orders
\& mv_exact_match em S Sets word-matching mode
\& mv_failpage fp O,S Sets page to display on failed order check/search
\& mv_field_file ff S Sets file to find field names for Glimpse
\& mv_field_names fn S Sets field names for search, starting at 1
\& mv_first_match fm S Start displaying search at specified match
\& mv_head_skip hs S Sets skipping of header line(s) in index
\& mv_index_delim id S Delimiter for search fields (TAB default)
\& mv_matchlimit ml S Sets match page size
\& mv_max_matches mm S Sets maximum match return
\& mv_min_string ms S Sets minimum search spec size
\& mv_negate ne S Records NOT matching will be found
\& mv_nextpage np A Sets next page user will go to
\& mv_numeric nu S Comparison numeric in coordinated search
\& mv_order_group O Allows grouping of master item/sub item
\& mv_order_item O Causes the order of an item
\& mv_order_number O Order number of the last order (read-only)
\& mv_order_quantity O Sets the quantity of an ordered item
\& mv_order_profile O Selects the order check profile
\& mv_order_receipt O Sets the receipt displayed
\& mv_order_report O Sets the order report sent
\& mv_order_subject O Sets the subject line of order email
\& mv_orsearch os S Selects AND/OR of search words
\& mv_profile mp S Selects search profile
\& mv_record_delim dr S Search index record delimiter
\& mv_return_all ra S Return all lines found (subject to range search)
\& mv_return_delim rd S Return record delimiter
\& mv_return_fields rf S Fields to return on a search
\& mv_return_file_name rn S Set return of file name for searches
\& mv_return_spec rs S Return the search string as the only result
\& mv_save_session C Set to non-zero to prevent expiration of user session
\& mv_search_field sf S Sets the fields to be searched
\& mv_search_file fi S Sets the file(s) to be searched
\& mv_search_line_returnlr S Each line is a return code (loop search)
\& mv_search_match_count S Returns the number of matches found (read-only)
\& mv_search_page sp S Sets the page for search display
\& mv_searchspec se S Search specification
\& mv_searchtype st S Sets search type (text, glimpse, db or sql)
\& mv_separate_items O Sets separate order lines (one per item ordered)
\& mv_session_id id A Suggests user session id (overridden by cookie)
\& mv_shipmode O Sets shipping mode for custom shipping
\& mv_sort_field tf S Field(s) to sort on
\& mv_sort_option to S Options for sort
\& mv_spelling_errors er S Number of spelling errors for Glimpse
\& mv_substring_match su S Turns off word-matching mode
\& mv_successpage O Page to display on successful order check
\& mv_todo A Common to all forms, sets form action
\& mv_todo.map A Contains form imagemap
\& mv_todo.checkout.x O Causes checkout action on click of image
\& mv_todo.return.x O Causes return action on click of image
\& mv_todo.submit.x O Causes submit action on click of image
\& mv_todo.x A Set by form imagemap
\& mv_todo.y A Set by form imagemap
\& mv_unique un S Return unique search results only
\& mv_value va S Sets value on one-click search (va=var=value)
.Ve
Abbreviations
.PP
The two-letter abbreviations are mapped with these letters:
.PP
.Vb 57
\& Abbr Long name
\& DL mv_raw_dict_look
\& MM mv_more_matches
\& ac mv_all_chars
\& ar mv_arg
\& bd mv_base_directory
\& bs mv_begin_string
\& ck mv_cache_key
\& co mv_coordinate
\& cs mv_case
\& cv mv_verbatim_columns
\& de mv_dict_end
\& df mv_dict_fold
\& di mv_dict_limit
\& dl mv_dict_look
\& do mv_dict_order
\& dr mv_record_delim
\& em mv_exact_match
\& er mv_spelling_errors
\& fi mv_search_file
\& fm mv_first_match
\& fn mv_field_names
\& hs mv_head_skip
\& id mv_session_id
\& il mv_index_delim
\& ix mv_index_delim
\& lb mv_search_label
\& lo mv_list_only
\& lr mv_line_return
\& lr mv_search_line_return
\& ml mv_matchlimit
\& mm mv_max_matches
\& mp mv_profile
\& ms mv_min_string
\& ne mv_negate
\& np mv_nextpage
\& nu mv_numeric
\& op mv_column_op
\& os mv_orsearch
\& pc mv_pc
\& ra mv_return_all
\& rd mv_return_delim
\& rf mv_return_fields
\& rn mv_return_file_name
\& rr mv_return_reference
\& rs mv_return_spec
\& se mv_searchspec
\& sf mv_search_field
\& si mv_search_immediate
\& sp mv_search_page
\& sq mv_sql_query
\& st mv_searchtype
\& su mv_substring_match
\& tf mv_sort_field
\& to mv_sort_option
\& un mv_unique
\& va mv_value
.Ve
.Vb 1
\& ________________________________________
.Ve
Copyright 2002\-2004 Interchange Development Group. Copyright 2001\-2002
Red Hat, Inc. Freely redistributable under terms of the \s-1GNU\s0 General
Public License.