Interchange Tags Reference ========================== ictags.1.118 (Draft) 1. Interchange Tag Reference ============================ Interchange functions are accessed via the Interchange Tag Language (ITL). The pages in a catalog may be mostly HTML, but they will use ITL tags to provide access to Interchange's functions. ITL is a superset of MML, or Minivend Markup Language. Minivend was the predecessor to Interchange. These tags perform various display and modification operations for the user session. There nearly 100 standard predefined tags, and the UserTag facility allows you to create tags that perform your own functions and can be just as powerful as the built-in tags. This document covers Interchange versions 4.7 through 4.9. 2. Tag Syntax ============= ITL tags are similar to HTML in syntax, in that they accept parameters or attributes and that there are both standalone and container tags. We will call an attribute a parameter if it may be called positionally or if it must be included (see the parameter and attribute sections below). A standalone tag has no ending element, e.g.: [value name] This tag will insert the user's name, providing they have given it to you in a form. A container tag has both a beginning and an ending element, as in: [if value name] You have a name. It is [value name]. [/if] 2.1. Standard Syntax -------------------- The most common syntax is to enclose the tag with its parameters and attributes in [square brackets]. If the tag has an end tag, the tag and its end tag will delimit contained body text: [tagname parameters attributes]Contained Body Text[/tagname] Caveat - macros: Some macros look like tags or end tags. For example, [/page] is a macro for . This allows you to conveniently write [page href]Target[/page], but 'Target' is not treated as contained body text. When using the [tagname ...] syntax, there must be no whitespace between the left bracket ('[') and the tagname. If a tag name includes an underscore or dash, as in [item_list], a dash is just as appropriate (i.e. [item-list]). The two forms are interchangeable, except that an ending tag must match the tag (i.e., don't use [item-list] list [/item_list]). 2.2. HTML-Comment ----------------- ITL also allows you to use '' as interchangeable alternatives to plain square brackets: [tagname] and are equivalent. This allows you make your raw tags appear as comments to HTML browsers or editors. You might want to do this if your editor has trouble with ITL tags when editing Interchange page templates, or alternatively, if you want to use one .html file both as an Interchange template and as a static page delivered directly by your web server, without Interchange processing. To properly HTML-comment contained body text, place your comment-style brackets appropriately, for example: Note that you must include whitespace between the HTML comment delimiters and the square brackets if you wish to actually comment out tag output in the browser. For example, if [value name] expands to 'Bill': '' becomes 'Bill' '' becomes '' 2.2.1. Technical notes ---------------------- While '' with ']' unless it also sees ' $10.00 [price code="99-102" discount=1] --> $9.00 See Product Discounts. 4.54.2.1. base -------------- 4.54.2.2. code -------------- 4.55. process ------------- This is a shortcut for the 'process' action, expanding to your catalog URL and session ID. It is analogous to the area tag for the 'process' page, but is more limited. The following expansion is illustrative: [process target=targetframe] --- http://www.here.com/cgi-bin/mycatalog/process.html?\ id=6CZ2whqo" TARGET="targetframe (the trailing backslash indicates continuation, i.e., the result should be only one line) Note the mismatched quotes in the expansion. Your surrounding HTML should supply the containing quotes, like this: ... Aliases: process_target, process_order 4.55.1. Summary --------------- [process target secure] [process target=targetframe secure=1 other_named_attributes] Parameters Description Default ............. ......................................... ............. target The target frame or window None secure Boolean. If true (secure=1), the URL will No link to your secure server. Attributes Default .................................. .................................. interpolate (reparse) No Other_Characteristics .................................. .................................. Invalidates cache No Container tag No Tag expansion example: [process targetframe 1] --- http://secure.here.com/cgi-bin/mycatalog/process.html?\ id=6CZ2whqo" TARGET="targetframe ASP-like Perl call: $Tag->process( { target => 'frametarget', secure => 1, } ); or similarly with positional parameters, $Tag->process($target, $secure, $attribute_hash_reference); 4.56. process-search -------------------- This is an exact alias for [area]. 4.57. query ----------- Passes SQL statements through to SQL databases, or allows SQL queries via Interchange's database abstraction into non-SQL databases and text files. The latter requires the Perl SQL Statement module (included with Bundle::Interchange from CPAN). 4.57.1. Summary --------------- [query sql] [query sql="SQL_query_text" other_named_attributes] Parameters Description Default ............. ......................................... ............. sql The SQL statement.Passed directly through none to an SQL database.For a non-SQL table, the tag interprets your SQL first. See the SQL Statement module for limitations and detail. query Alias for sql none Attributes Default .................................. .................................. table products base (alias for table) products type (row_count, html, list, none: uses arrayref="" if no type textref) 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 Other_Characteristics .................................. .................................. Invalidates cache No Container tag Yes Has subtags Yes Nests No Tag usage example: This will list sku, description and price for ten products per page, followed by hyperlinks to the other pages of the list. Note that you may interpolate Interchange tags in the usual way if you double-quote the SQL statement. [query sql="select sku, description, price from products where price < [value mv_arg]" type=list more=1 ml=10] [on_match]Matched
[/on_match] [no_match]Not Found
[/no_match] [list] [sql-code] [sql-param description] [sql-price] [/list] [more_list] Matches [matches] of [match-count] shown.
[more] [/more_list] [/query] ASP-like Perl call: my $sql = "select * from products order by price"; my $result_array = $Tag->query( { sql => $sql, }, $body ); my ($same_results, $col_name_hash, $col_name_array) = $Tag->query( { sql => $sql, }, $body ); my $result_hasharray = $Tag->query( { sql => $sql, hashref => 'my_results', }, $body ); or similarly with positional parameters, $Tag->query( $sql, $attribute_hash_reference, $body); 4.57.2. Description ------------------- The query tag allows you to make SQL queries. If you are using an SQL database table, the tag will pass your SQL statement directly to the database and return the result. If your table is not in an SQL database (for example, GDBM, text, LDAP, and in-memory tables), Interchange will internally convert it to an Interchange search specification with the Perl SQL Statement module (included with Bundle::Interchange from CPAN). This means that you can use simple SQL queries regardless of the underlying database implementation. 4.57.2.1. Subtags ----------------- For list queries (type=list), the following subtags are available: 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. See also the example at the end of the Summary section above. 4.57.2.2. Perl and ASP usage ---------------------------- If you are calling $Tag->query within a perl tag (or whenever the code is secured by the Safe.pm module), you must be sure to set the tables attribute properly in the enclosing perl tag (see the perl tag documentation for detail). The types that return text to a page (i.e., row_count, html, and textref) work as usual, returning an appropriate string. Note that you may also have access to the results as an array reference in $Vend::Interpolate::Tmp->{''} for the life of the page. If you do not set a type, the tag will return a reference to an array of array references, since the default with no type is arrayref="". If you call $Tag->query in scalar context and set arrayref or hashref, it will return your results as a reference to an array of either arrayrefs or hashrefs, respectively (i.e., the same data structures you would get from Perl's DBI.pm module with fetchall_arrayref). In list context, the first returned element is the aforementioned reference to your results. The second element is a hash reference to your column names, and the third element is an an array reference to the list of column names. The following examples should be illustrative: [perl tables=products] my $sql = "select sku, price, description from products where price < 10 order by price"; my $results = $Tag->query( { sql => $sql, } ); my ( $same_results, $col_name_hashref, $col_name_arrayref) = $Tag->query( { sql => $sql, } ); my $hash_results = $Tag->query( { sql => $sql, hashref => 'my_results' } ); # $Vend::Interpolate::Tmp->{my_results} == $hash_results # $Vend::Interpolate::Tmp->{''} == $results == $same_results my $out = "The returned structure is\n"; $out .= $Tag->uneval( $results ); #loop through each row & display the fields foreach my $row (@$hash_results) { $out .= '

sku: ' . $row->{sku} $out .= '
price: ' . $row->{price}; $out .= '
description: ' . $row->{description}; } return $out; [/perl] Technical Note: The $Tag->query() call works a bit differently in GlobalSubs and UserTags than within a perl tag. Specifically, in a GlobalSub or global UserTag, if you call query() in list context and want the three references (i.e., results, column hash and column array), then you need to set the 'wantarray=1' attribute in the query() call. See the wantarray attribute. 4.57.2.3. sql ------------- This is the text of your SQL statement. The standard Interchange quoting rules apply. For example, use double quotes (") if you want to interpolate Interchange tags within your SQL statement, backticks (`) to calculate a value, etc. [query sql="select description, price from products where price < [value mv_arg]" ...] ... [/query] 4.57.2.4. table --------------- 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 $Vend::Cfg->{ProductFiles}). 4.57.2.5. type -------------- 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: Type Returns .................................. .................................. html The html type returns the results in an html table. You will need to supply the enclosing and
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]; If you do not specify a type, the tag will create an arrayref as if you had set 'arrayref=""'. 4.57.2.6. arrayref and hashref ------------------------------ If you set 'arrayref=keyname' or 'hashref=keyname', the query will not return results to the page. Instead, it will place the results of your query in the $Vend::Interpolate::Tmp hash. Using 'arrayref=my_query' sets $Vend::Interpolate::Tmp->{my_query} to refer to an array of array references, while 'hashref=my_query' creates an array of hash references. Note that this is useful only if you intend to access the results within Perl code (for example, within a [perl] tag), since there is no direct output to the returned page. The $Vend::Interpolate::Tmp hash persists only for the life of the template page being processed. If you need the query results array reference to outlive the page, you will have to save the reference somewhere more persistent such as the $Session hash: $Session->{my_query} = $Vend::Interpolate::Tmp->{my_query}; Beware the impact on performance if you do this with large result sets. Technical note - the string returned by the 'textref' type will eval() to the 'arrayref' data structure. 4.57.2.7. more -------------- Requires 'type=list'. 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. 4.57.2.8. form variable abbreviations ------------------------------------- Requires 'type=list'. See the Search and Form Variables appendix for a list of form variables. Note that you must use the two-letter abbreviation rather than the full form variable name. A few deserve special mention: 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. 4.57.2.9. ---------- Requires 'type=list'. Setting 'prefix=foo' overrides the default prefix of 'sql' for loop subtags within a list region (see Looping tags and Sub-tags). See the list_prefix attribute below for an illustrative example. 4.57.2.10. list_prefix ---------------------- Requires 'type=list'. 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. [query sql="select sku, description, price from products where price < 20" type=list more=1 ml=10] [on_match]Matched
[/on_match] [no_match]Not Found
[/no_match] [list] [sql-code] [sql-param description] [sql-price] [/list] [more_list] [more] [/more_list] [/query] --- [query sql="select sku, description, price from products where price < 20" type=list prefix=foo list_prefix=bar more=1 ml=10] [on_match]Matched
[/on_match] [no_match]Not Found
[/no_match] [bar] [foo-code] [foo-param description] [foo-price] [/bar] [more_list] [more] [/more_list] [/query] 4.57.2.11. random ----------------- Requires 'type=list'. 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=n', where n > 0, causes the [list] region to loop over n randomly chosen rows rather than the full query result set. The example below would display three randomly chosen products priced under 20. [query sql="select * from products where price < 20" type=list random=3] [list] [sql-code] [sql-param description] [sql-price] [/list] [/query] 4.57.2.12. safe_data -------------------- Requires 'type=list'. Note - you should not set this unless you need it and know what you are doing. Setting 'safe_data=1' allows the [sql-data] tag to return values containing the '[' character. See also Looping tags and Sub-tags. Beware of reparsing issues. 4.57.2.13. label ---------------- Requires 'type=list'. If you are setting up multiple simultaneously active search objects within a page, this allows you to distinguish them. The default label is 'current'. Most people will not need this. 4.57.2.14. form --------------- Requires 'type=list'. You can use this to pass one CGI form variable in the pagination links of a [more-list]. For example, 'form="foo=bar"' to include '&foo=bar' in the URL of each of the pagination links. Note that the variable will not be available in the initial result set since the query returns the first page directly (i.e., you did not follow a pagination link). 4.57.2.15. wantarray -------------------- This is relevant only when calling $Tag->query( ... ) within global Perl code such as a globalsub or global usertag where $MVSAFE::Safe is not defined. In these cases, setting 'wantarray=1' allows the call to $Tag->query( { wantarray => 1, ... }, ... ); to return references as it would if called within an ordinary [perl] tag. Note that it does not force list context if you call $Tag->query in scalar context. Here is another example of the use of the array references, from a UserTag: my $sku = 'os28044'; my $sql = qq{select description, price from products where sku = '$sku'}; my $table = 'products'; my ($results, $col_name_hashref, $col_name_arrayref) = $Tag->query({ wantarray => 1, sql => "$sql", table => "$table"}); my $out; # this will get the first field (description).. $out = 'description: ' . $results->[0]->[0]; # and this the second field (price).. $out .= '
price: ' . $results->[0]->[1]; # 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; If the [query] returns more than one row, the second row's description field would be: $results->[1]->[0] 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 $Tag->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. Example of a nested query: [query ml=99 type=list sp="@@MV_PAGE@@" sql=| SELECT foo1, foo2, foo3 FROM bar WHERE someothercol = 'bang' |] [list] Here is [sql-param foo1] from outer
[query prefix=usr list_prefix=detail ml=1 type=list sp="@@MV_PAGE@@" sql=| SELECT flip FROM flap WHERE flog = 'flan' |] [usr-on-match] something was found in the inner! [/usr-on-match] [detail] Here is [usr-param flip] from inner
Here is [sql-param foo2] from outer!!
[/detail] [/query] Here is [sql-param foo3] from outer!!!
[/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] Notice the use of 'prefix' and 'list_prefix' on subsequent inner queries. 4.58. read-cookie ----------------- Returns the value of the named cookie. Returns nothing if the cookie does not exist. 4.58.1. Summary --------------- [read-cookie name] [read-cookie name=mycookie] Attributes Description Default ............. ......................................... ............. name The name of the cookie whose value you none want Attributes Default .................................. .................................. interpolate (reparse) No Other_Characteristics .................................. .................................. Invalidates cache Yes Container tag No Usage example: [read-cookie name=MV_SESSION_ID] --- 6CZ2whqo ASP-like Perl call: $Tag->read_cookie( { name => $name, } ); or similarly with positional parameters, $Tag->read_cookie( $name ); 4.58.2. Description ------------------- This tag expands to the value of the named cookie (or nothing if the cookie does not exist). See the Netscape specification at http://www.netscape.com/newsref/std/cookie_spec.html if you need more cookie-specific detail. 4.58.2.1. name -------------- This is the name of the cookie whose value you want to retrieve. 4.58.2.2. Parsing an HTTP_COOKIE string --------------------------------------- If you pass this tag a second parameter within a Perl call, it will use your value as the HTTP_COOKIE string (ignoring the real one). This only applies if you pass the values positionally within a perl call since there is no name for the HTTP_COOKIE string input: $Tag->read_cookie('MV_SESSION_ID', "MV_SESSION_ID=UnHyaDQj:127.0.0.1; ..."); 4.59. restrict -------------- Restrict tag execution in a region. If a restricted tag is encountered, it is simply output. 4.59.1. Summary --------------- [restrict tag1 tag2] [restrict policy=deny enable="page area value"] Attributes Description Default ............. ......................................... ............. policy Whether to allow or deny by default. deny enable Tags to enable when default policy is none deny. disable Tags to disable. Overrides enable. none Attributes Default .................................. .................................. interpolate (reparse) No Other_Characteristics .................................. .................................. Invalidates cache Yes Container tag No Usage example: [read-cookie name=MV_SESSION_ID] --- 6CZ2whqo ASP-like Perl call: N/A. Cannot be called effectively. 4.59.2. Description ------------------- Restrict tag execution in a region. If a restricted tag is encountered, it is simply output. It can be used to allow certain tags in a user-editable region, while denying dangerous tags. Or it can be used to restrict all tag execution in a region. 4.59.2.1. policy ---------------- Default is deny, which makes most sense. You then specifically enable certain ITL 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. 4.59.2.2. enable ---------------- 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. 4.59.2.3. disable ----------------- 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. 4.60. row --------- 4.60.1. Summary --------------- Parameters: width Positional parameters in same order. Pass attribute hash as last to subroutine: no Interpolates container text by default. This is a container tag, i.e. [row] FOO [/row]. Nesting: NO Invalidates cache: no Called Routine: ASP-like Perl call: $Tag->row( { width => VALUE, }, BODY ) OR $Tag->row($width, $BODY); [row width] Parameters Description Default ............. ......................................... ............. width DEFAULT_VALUE Attributes Default .................................. .................................. interpolate No reparse Yes Other_Characteristics .................................. .................................. Invalidates cache no Container tag Yes Has Subtags No Nests No Tag expansion example: [row width] --- TODO: (tag result) ASP-like Perl call: $Tag->row( { width => VALUE_width }, $body ); or similarly with positional parameters, $Tag->row(width, $attribute_hash_reference, $body); 4.60.2. Description ------------------- Formats text in tables. Intended for use in emailed reports or

 HTML areas. The parameter nn gives the number of columns
to use. Inside the row tag, [col param=value ...] tags may be used.

4.60.2.1. [col width=nn wrap=yes|no gutter=n align=left|right|input spacing=n]
------------------------------------------------------------------------------

Sets up a column for use in a [row]. This parameter can only be
contained inside a [row nn] [/row] tag pair. Any number of columns
(that fit within the size of the row) can be defined.

The parameters are:

    width=nn        The column width, I. Must be
                    supplied, there is no default. A shorthand method
                    is to just supply the number as the I parameter,
                    as in [col 20].

    gutter=n        The number of spaces used to separate the column (on
                    the right-hand side) from the next. Default is 2.

    spacing=n       The line spacing used for wrapped text. Default is 1,
                    or single-spaced.

    wrap=(yes|no)   Determines whether text that is greater in length than
                    the column width will be wrapped to the next line. Default
                    is I.

    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.

4.60.2.2. [/col]
----------------

Terminates the column field.

4.60.2.3. width
---------------

4.61. salestax
--------------

4.61.1. Summary
---------------

Parameters: name noformat

Positional parameters in same order.

Pass attribute hash as last to subroutine: no

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: YES

Called Routine:

ASP-like Perl call:

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

 OR

    $Tag->salestax($name, $noformat);

Attribute aliases

            cart ==> name
    [salestax name noformat]

Parameters    Description                               Default
............. ......................................... ............. 
cart          Alias for name                            DEFAULT_VALUE
name                                                    DEFAULT_VALUE
noformat                                                DEFAULT_VALUE

Attributes                         Default
.................................. .................................. 
interpolate (reparse)              No

Other_Characteristics
.................................. .................................. 
Invalidates cache                  YES
Container tag                      No
Has Subtags                        No
Nests                              Yes

Tag expansion example:

    [salestax name noformat]
---
    TODO: (tag result)

ASP-like Perl call:

   $Tag->salestax(  { name => VALUE_name
                       noformat => VALUE_noformat
}, $body  );

or similarly with positional parameters,

    $Tag->salestax(name,noformat, $attribute_hash_reference, $body);

4.61.2. Description
-------------------

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.

4.61.2.1. name
--------------

4.61.2.2. noformat
------------------

4.62. scratch
-------------

4.62.1. Summary
---------------

Parameters: name

Positional parameters in same order.

Pass attribute hash as last to subroutine: no

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: YES

Called Routine:

ASP-like Perl call:

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

 OR

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

Parameters    Description                               Default
............. ......................................... ............. 
name                                                    DEFAULT_VALUE

Attributes                         Default
.................................. .................................. 
interpolate (reparse)              No

Other_Characteristics
.................................. .................................. 
Invalidates cache                  YES
Container tag                      No
Has Subtags                        No
Nests                              Yes

Tag expansion example:

    [scratch name]
---
    TODO: (tag result)

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.62.2. Description
-------------------

Returns the contents of a scratch variable to the page. (A scratch
variable is set with a [set] value [/set] container pair.)

4.62.2.1. name
--------------

4.63. scratchd
--------------

Deletes the named scratch variable and returns its value before the
deletion. For example,

    [scratchd varname_to_delete]

deletes the scratch variable varname_to_delete.

See also the scratch and set tags.

4.63.1. Summary
---------------

    [scratchd P_PARAM]
    [scratchd N_PARAM other_named_attributes]

Parameters    Description                               Default
............. ......................................... ............. 
name          Name of scratch variable to delete        None

Attributes                         Default
.................................. .................................. 
interpolate (reparse)              No

Other_Characteristics
.................................. .................................. 
Invalidates cache                  Yes
Container tag                      No

Tag expansion example:

    [set myvar]This is myvar[/set]
    .
    .
    .
    [scratchd myvar]
---
    This is myvar

ASP-like Perl call:

    $Tag->scratchd($name, $attribute_hash_reference);

4.63.2. Description
-------------------

Deletes the named scratch variable and returns its value before the
deletion.

4.64. search-list
-----------------

Formats results returned by a search. Must be enclosed within a
search-region. Has sub-tags (see Looping tags and Sub-tags).

4.65. search-region
-------------------

4.65.1. Summary
---------------

Parameters: arg

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

Must pass named parameter interpolate=1 to cause interpolation.

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

Invalidates cache: no

Called Routine:

ASP-like Perl call:

    $Tag->search_region(
        {
         arg => VALUE,
        },
        BODY
    )

 OR

    $Tag->search_region($arg, $ATTRHASH, $BODY);

Attribute aliases

            args ==> arg
            params ==> arg
            search ==> arg
    [search-region arg other_named_attributes]

Parameters    Description                               Default
............. ......................................... ............. 
arg                                                     DEFAULT_VALUE
args          Alias for arg                             DEFAULT_VALUE
params        Alias for arg                             DEFAULT_VALUE
search        Alias for arg                             DEFAULT_VALUE

Attributes                         Default
.................................. .................................. 
interpolate                        No
reparse                            Yes

Other_Characteristics
.................................. .................................. 
Invalidates cache                  no
Container tag                      Yes
Has Subtags                        No
Nests                              No

Tag expansion example:

    [search-region arg]
---
    TODO: (tag result)

ASP-like Perl call:

   $Tag->search_region(  { arg => VALUE_arg
}, $body  );

or similarly with positional parameters,

    $Tag->search_region(arg, $attribute_hash_reference, $body);

4.65.2. Description
-------------------

NO Description

4.65.2.1. arg
-------------

4.66. selected
--------------

4.66.1. Summary
---------------

Parameters: name value

Positional parameters in same order.

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

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: YES

Called Routine:

ASP-like Perl call:

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

 OR

    $Tag->selected($name, $value, $ATTRHASH);
    [selected name value other_named_attributes]

Parameters    Description                               Default
............. ......................................... ............. 
case                                                    DEFAULT_VALUE
cgi                                                     DEFAULT_VALUE
default                                                 DEFAULT_VALUE
name                                                    DEFAULT_VALUE
multiple                                                DEFAULT_VALUE
value                                                   DEFAULT_VALUE

Attributes                         Default
.................................. .................................. 
interpolate (reparse)              No

Other_Characteristics
.................................. .................................. 
Invalidates cache                  YES
Container tag                      No
Has Subtags                        No
Nests                              Yes

Tag expansion example:

    [value name=example set=neato]
    Neato
    Silly
---
    
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 ASP-like Perl call: $Tag->button_bar( { page => $page, current => $current, body => $body} ); or similarly, $Tag->area($page, $current, $body); 6.1.1.1. See Also ----------------- bar_link routine 6.1.2. Description ------------------ 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. 6.1.2.1. page ------------- The name of the page for which this definition of the bar-button is defined. 6.1.2.2. current ---------------- The name of the current page. Defaults to current page MV_PAGE. 6.2. button ----------- 6.3. convert_date ----------------- This tag converts a given date format into another format. 6.3.1. Summary -------------- [convert_date day* other_named_attributes[/convert_date] [convert_date day=n* other_named_attributes[/convert_date] Positional parameters: The first line shows the usage with positional parameters (given in order). The second line shows usage with named parameters. Parameters Description Default ............. ......................................... ............. days The number of days from or before today none Attributes Default .................................. .................................. format '%d-%b-%Y %I:%M%p' or '%d-%b-%Y' fmt - Alias for format none raw none zerofix none Other_Characteristics .................................. .................................. Invalidates cache No Macro No Has end tag [/convert_date] Tag expansion example: a. [convert-date][/convert-date] b. [convert-date 1][/convert-date] c. [convert-date -1][/convert-date] d. [convert-date]2001-5-1[/convert-date] e. [convert-date]2001-05-01[/convert-date] f. [convert-date]20010515[/convert-date] g. [convert-date raw=1]2001-05-18[/convert-date] h. [convert-date fmt="%d-%m-%Y"]2001-05-18[/convert-date] i. [convert-date]200 1 - --051 =9[/convert-date] j. [convert-date]2001 - --05 -20 11 1 5[/convert-date] k. [convert-date raw=1]2001-05-21 11:15[/convert-date] --- a. 18-May-2001 03:15AM (todays day and time) b. 19-May-2001 03:15AM (today + 1 day) c. 17-May-2001 03:15AM (today - 1 day) d. 01-May-2001 e. 01-May-2001 f. 15-May-2001 g. 20010518 h. 18-05-2001 i. 19-May-2001 j. 20-May-2001 11:15AM k. 200105211115 ASP-like Perl call: $Tag->convert_date( { days => 1 } ); $Tag->convert_date( { body => "2001-05-19 15:35", format => "%d-%m-%Y %H:%M", } ); or similarly with positional parameters, $Tag->convert_date( 1 ); 6.3.2. Description ------------------ This tag converts almost any given date format into another, possibly user defined, format. 6.3.2.1. days ------------- Number of days from or before today's date and time. Will only be used if nothing is supplied between the tags. 6.3.2.2. format --------------- POSIX time format string of your choice. See Unix strftime(3) manpage for complete details. 6.3.2.3. raw ------------ If this option is set to true, will display given date in raw format, e.g. yyyymmdd or yyyymmddHHMM. 6.3.2.4. zerofix ---------------- Strips leading zeroes from numbers. 6.4. db_date ------------ This tag returns the time of last access of the database source file. 6.4.1. Summary -------------- [db_date table* format*] Positional parameters: The first line shows the usage with positional parameters (given in order). The second line shows usage with named parameters. Parameters Description Default ............. ......................................... ............. table Table name. products format POSIX time format string %A %d %b %Y Other_Characteristics .................................. .................................. Invalidates cache No Macro No Has end tag No Tag expansion example: [db-date] [db-date cat] [db-date table=cat format="%d %b %Y"] --- Wednesday 02 May 2001 (products.txt) Wednesday 03 May 2001 (cat.txt) 03 May 2001 (cat.txt) ASP-like Perl call: $Tag->db_date( { table => cat, format => "%d %b %Y", } ); or similarly with positional parameters, $Tag->db_date( "cat", "%d %b %Y" ); 6.4.2. Description ------------------ This tag returns the time of last access of the database source file. 6.4.2.1. table -------------- Table name. Defaults to products if not specified. 6.4.2.2. format --------------- POSIX time format string. See Unix strftime(3) manpage for details. Defaults to '%A %d %b %Y' when not specified. 6.5. delete_cart ---------------- This tag deletes a cart from the userdb. 6.5.1. Summary -------------- [delete_cart nickname] [delete_cart nickname="cart-name"] Positional parameters: The first line shows the usage with positional parameters (given in order). The second line shows usage with named parameters. Parameters Description Default ............. ......................................... ............. nickname Must be an existing nickname none Other_Characteristics .................................. .................................. Invalidates cache No Macro No Has end tag No Tag expansion example: [delete_cart mycart] [delete_cart nickname="mycart"] ASP-like Perl call: $Tag->delete_cart( { nickname => "mycart", } ); or similarly with positional parameters, $Tag->delete_cart( "mycart" ); 6.5.1.1. See Also ----------------- userdb, load_cart, save_cart and pages templates/components/saved_carts_list_small, pages/saved_carts.html for more examples. 6.5.2. Description ------------------ Deletes a cart with name nickname from the user database. Basically the same as [userdb function=delete_cart nickname=mycart]. 6.5.2.1. nickname ----------------- Nickname of cart to be deleted. 6.6. email ---------- This tag takes a recipient address and a body text and uses the SendmailProgram with -t option to send email. 6.6.1. Summary -------------- [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] Positional parameters: The first line shows the usage with positional parameters (given in order). The second line shows usage with named parameters. Parameters Description Default ............. ......................................... ............. to Email address of recipient none subject Subject line String: reply Email address to be used for the reply-to none header from Senders email address First address in MailOrderTo configuration variable extra Additional headers to be included none Other_Characteristics .................................. .................................. Invalidates cache No Macro No Has end tag [/email] Tag expansion example: [email to="foo@bar.com" subject="Greetings" from="bar@foo.com" ] Hello World [/email] ASP-like Perl call: $Tag->email( { to => $to, from => $from, subject => $subject, reply => $reply, extra => $extra, body => $body } ); or similarly, $Tag->email($to, $subject, $reply, $from, $extra, $body); 6.6.1.1. See Also ----------------- email_raw and etc/mail_receipt, pages/process_return.html, pages/stock-alert-added.html for examples. 6.6.2. Description ------------------ Will send the content between the [email][/email] tags as an email to the recipient (to) using the SendmailProgram with -t option. 6.6.2.1. extra -------------- Extra headers to be included. Example: Errors-To: errors@yourdomain.com 6.6.2.2. from ------------- Email address identifying the sender of the message. Will use the first email address of the MailOrderTo configuration variable if it is not supplied. 6.6.2.3. reply -------------- Email address to be used for the Reply-to header. No Reply-to header will be present if this parameter is omitted. 6.6.2.4. subject ---------------- 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. 6.6.2.5. to ----------- Valid email address(es) of the recipient(s). This parameter is required. 6.7. email_raw -------------- This tag takes a raw email message, including headers, and uses the SendmailProgram with -t option. 6.7.1. Summary -------------- [email_raw]Your message including headers[/email_raw] Other_Characteristics .................................. .................................. Invalidates cache No Macro No Has end tag [/email_raw] Tag expansion example: [email_raw] From: foo@bar.com To: bar@foo.com Subject: baz The text of the message. [/email_raw] The headers must be at the beginning of the line, and the header must have a valid To: or it will not be delivered. ASP-like Perl call: $Tag->email_raw( { body => $body } ); or similarly, $Tag->email_raw($body); 6.7.1.1. See Also ----------------- email 6.7.2. Description ------------------ 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. 6.8. fedex_query ---------------- 6.9. formel ----------- 6.10. fortune ------------- This tag uses the fortune(1) command to display a random saying. Options: short=yes|no* Select only short (< 160 chars) fortunes a=1 Select from all fortunes, even potentially offensive ones. o=1 Select only from potentially offensive fortunes. raw=1 Don't do any HTML formatting Example: [fortune short=yes] 6.11. get-url ------------- Fetch a URL and return the contents. 6.11.1. Summary --------------- [get-url url] [get-url url="valid-url" strip=1*] Positional parameters: The first line shows the usage with positional parameters (given in order). The second line shows usage with named parameters. Parameters Description Default ............. ......................................... ............. url Must be a valid URL. Meaning, you have to none supply the protocol. Examplehttp://demo.icdevgroup.org/ftp://ftp.icdevgroup.org/ Attributes Default .................................. .................................. strip none Other_Characteristics .................................. .................................. Invalidates cache No Macro No Has end tag No Tag expansion example: [get-url http://demo.icdevgroup.org/] [get-url url="http://demo.icdevgroup.org/" strip=1] ASP-like Perl call: $Tag->get_url( { url => "http://demo.icdevgroup.org/", } ); $Tag->get_url( { url => "http://demo.icdevgroup.org/", strip => 1, } ); or similarly with positional parameters, $Tag->get_url( "http://demo.icdevgroup.org/" ); 6.11.2. Description ------------------- Uses the LWP libraries (LWP::Simple) to fetch a URL and returns the contents. 6.11.2.1. strip --------------- If the strip option is set, strips everything up to and everything after . 6.11.2.2. url ------------- Must be a valid URL (including protocol). 6.12. load_cart --------------- This tag loads a cart by name from the userdb. 6.12.1. Summary --------------- [load_cart nickname] [load_cart nickname="cart-name"] Positional parameters: The first line shows the usage with positional parameters (given in order). The second line shows usage with named parameters. Parameters Description Default ............. ......................................... ............. nickname Must be an existing nickname.Nickname is none constructed from:a name parttime modified (time the cart was saved by save_cart tag)type (c for cart, r for recurring) Other_Characteristics .................................. .................................. Invalidates cache No Macro No Has end tag No Tag expansion example: [load_cart mycart:990102732:c] [load_cart nickname="mycart:990102732:c"] ASP-like Perl call: $Tag->load_cart( { nickname => "mycart:990102732:c", } ); or similarly with positional parameters, $Tag->load_cart( "mycart:990102732:c" ); 6.12.1.1. See Also ------------------ userdb, delete_cart, save_cart and pages templates/components/saved_carts_list_small, pages/saved_carts.html for more examples. 6.12.2. Description ------------------- 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]. 6.12.2.1. nickname ------------------ Nickname of cart to be loaded. See above. 6.13. loc --------- 6.14. rand ---------- 6.15. reconfig -------------- 6.16. reconfig_time ------------------- 6.17. reconfig_wait ------------------- 6.18. save_cart --------------- This tag saves the current cart or recurring order in the userdb under a given name. 6.18.1. Summary --------------- [save_cart nickname recurring] [save_cart nickname="cart-name" recurring=1] Positional parameters: The first line shows the usage with positional parameters (given in order). The second line shows usage with named parameters. Parameters Description Default ............. ......................................... ............. nickname Label for the cart. none recurring Set to true if recurring. Set to false, none or omit if cart. Other_Characteristics .................................. .................................. Invalidates cache No Macro No Has end tag No Tag expansion example: [save_cart mycart] [save_cart nickname=mycart recurring=1] ASP-like Perl call: $Tag->save_cart( { nickname => mycart, recurring => 1, } ); or similarly with positional parameters, $Tag->save_cart( "mycart", "1" ); 6.18.1.1. See Also ------------------ userdb, delete_cart, load_cart and pages templates/components/saved_carts_list_small, pages/saved_carts.html for more examples. 6.18.2. Description ------------------- Saves the current cart with name nickname in the user database. Basically the same as [userdb function=set_cart nickname=cartname] 6.18.2.1. nickname ------------------ Nickname for the current cart to be saved. You can use same nickname for different carts. An index will be added if there are more carts with the same nickname. 6.18.2.2. recurring ------------------- Set to true if recurring. Set to false, or simply omit it, if it is a cart. 6.19. summary ------------- This tag calculates column totals. 6.19.1. Summary --------------- [summary amount] [summary amount=n.nn other_named_attributes] Positional parameters: The first line shows the usage with positional parameters (given in order). The second line shows usage with named parameters. Parameters Description Default ............. ......................................... ............. amount Numerical value to be added to previous none total Attributes Default .................................. .................................. currency none format none hide none, no hiding name ONLY0000, internal use only reset none total none Other_Characteristics .................................. .................................. Invalidates cache No Macro No Has end tag No Tag expansion example: [loop list="10 20 30.5"] [summary amount="[loop-code]" hide=1] [/loop] [summary total=1 format="%.3f"] [summary total=1 currency=1] --- 60.500 $60.50 ASP-like Perl call: $Tag->summary( { amount => 10.5, hide => 1, } ); $Tag->summary( { amount => 25, name => mytotal, currency => 1, } ); or similarly with positional parameters, $Tag->summary( 10.5, $attribute_hash_reference ); 6.19.1.1. See Also ------------------ templates/components/cart, pages/ord/checkout.html for more examples. 6.19.2. Description ------------------- The summary tag provides you with an easy way to calculate and display totals. The display of the amounts is fully customizable. You can hide display, or you can show the amounts with the proper currency formatting according to the locale, or you can define your own formatting. Any number of summaries can be kept on a page. 6.19.2.1. currency ------------------ The amount or total will be displayed according to the currency formatting of the current locale if this attribute is set to true (non blank or zero). 6.19.2.2. format ---------------- You can choose any formatting of the amount you like. Just set the format attribute to the desired formatting string (%s, %.2f etc.). When both, currency and format attributes are set, the format attribute will take precedence. So it doesn't make much sense to set them both at the same time. 6.19.2.3. hide -------------- Will suppress the display of amount when set to true. 6.19.2.4. name -------------- You can calculate as many totals as you like on the same page. Just supply a different label for each summary. 6.19.2.5. reset --------------- Will erase the total(s) if set to true. Be careful tough. It will reset ALL totals when you have no name attribute supplied. If you have provided a label for the name attribute then it will only reset the total for that particular label. All others won't be touched. 6.19.2.6. total --------------- Will show the total instead of the amount if set to true. 6.20. table_organize -------------------- Takes an unorganized set of table cells and organizes them into rows based on the number of columns. 6.20.1. Summary --------------- [table-organize cols* other_named_attributes] [loop ....] [loop-tags] [/loop] [/table-organize] [table-organize cols=n* other_named_attributes] [loop ....] [loop-tags] [/loop] [/table-organize] Positional parameters: The first line shows the usage with positional parameters (given in order). The second line shows usage with named parameters. Parameters Description Default ............. ......................................... ............. cols Number of columns. 2 columns Alias for cols. 2 Attributes Default .................................. .................................. caption none columnize none embed none filler   limit none pretty none rows none table none td none tr none Other_Characteristics .................................. .................................. Invalidates cache No Macro No Has end tag [/table-organize] Tag expansion example: This example produces a table that (1) alternates rows with background colors "#EEEEEE" and "#FFFFFF", and (2) aligns the columns right, center, left: [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     If the attribute columnize=1 is present, the result will look like: 1 1a 1b 2 2a   3 3a   See the source for more ideas on how to extend this tag. ASP-like Perl call: $Tag->table_organize( { cols => 3, pretty => 1, }, $BODY ); or similarly with positional parameters: $Tag->table_organize( $cols, $attribute_hash_reference, $BODY ); 6.20.1.1. See Also ------------------ pages/flypage.html, pages/quantity.html, templates/components/best_horizontal, templates/components/cart, templates/components/cross_horizontal, templates/components/random, templates/components/random_vertical, templates/components/upsell 6.20.2. Description ------------------- Takes an unorganized set of table cells and organizes them into rows based on the number of columns; it will also break them into separate tables. If the number of cells are not on an even modulus of the number of columns, then "filler" cells are pushed on. 6.20.2.1. cols (or columns) --------------------------- Number of columns. This argument defaults to 2 if not present. 6.20.2.2. rows -------------- Optional number of rows. Implies "table" parameter. 6.20.2.3. table --------------- If present, will cause a surrounding
pair with the attributes specified in this option. 6.20.2.4. caption ----------------- Table container text, if any. Can be an array. 6.20.2.5. td ------------ Attributes for table cells. Can be an array. 6.20.2.6. tr ------------ Attributes for table rows. Can be an array. 6.20.2.7. columnize ------------------- Will display cells in (newspaper) column order, i.e. rotated. 6.20.2.8. pretty ---------------- Adds newline and tab characters to provide some reasonable indenting. 6.20.2.9. filler ---------------- Contents to place in empty cells put on as filler. Defaults to " ". 6.20.2.10. limit ---------------- Maximum number of cells to use. Truncates extra cells silently. 6.20.2.11. embed ---------------- 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 elements. To switch that sense, and make the upper-case or mixed case be the ignored cells, set the embed parameter to "lc". [table-organize embed=lc]
something
[/table-organize] or [table-organize embed=uc]
something
[/table-organize] The "tr", "td", and "caption" attributes can be specified with indexes; if they are, then they will alternate according to the modulus. The "td" option array size should probably always equal the number of columns; if it is bigger, then trailing elements are ignored. If it is smaller, no attribute is used. 6.21. title_bar --------------- Creates a quick title bar. 6.21.1. Summary --------------- [title-bar width size color]My title[/title-bar] [title-bar width=600 size=5 color="#ff0000"]My title[/title-bar] Positional parameters: The first line shows the usage with positional parameters (given in order). The second line shows usage with named parameters. Parameters Description Default ............. ......................................... ............. color Background color the bar.Defaults HEADERBG or tovariable HEADERBG or#444444 #444444 size Font size 6 width Width of the title bar 500 Other_Characteristics .................................. .................................. Invalidates cache No Macro No Has end tag [/title-bar] Tag expansion example: [title-bar 600 5 red]My title[/title-bar] [title-bar width=600 size=5 color="#ff0000"]My title[/title-bar] ASP-like Perl call: $Tag->title_bar( { body => "My Title", } ); $Tag->title_bar( { width => 400, color => "#0000ff", body => "My title", } ); or similarly with positional parameters, $Tag->title_bar( 600, 5, "red", "My title" ); 6.21.2. Description ------------------- Quickly adds a title bar to your pages without having to type the html each time. Background color, width of the bar and size of the text can be customized by setting the appropriate parameter. The text color defaults to variable HEADERTEXT or when its not present to white. 6.21.2.1. color --------------- Sets the background color of the bar. You can set the color as 'red', '#ff0000', or 'bgcolor="#ff0000"'. 6.21.2.2. size -------------- Determines the size of the text. Parameter should be set to a value accepted by the HTML tag size attribute. 6.21.2.3. width --------------- Sets the width of the bar. 6.22. ups_query --------------- 6.23. usertrack --------------- 6.24. var --------- 6.25. xml-generator ------------------- This is a quick and dirty tag that generates XML tags based upon one of two types of data (delimited and session). 6.25.1. Summary --------------- [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] *Optional Positional parameters: The first line shows the usage with positional parameters (given in order). The second line shows usage with named parameters. Parameters Description Default ............. ......................................... ............. type Data type. Delimited or session delimited Attributes Default .................................. .................................. attributes none dbdump none delimiter \t field_names   separator \n toplevel_tag 'table' for delimited type and 'session' for other type record_tag record field_tag field key_name none spacer [\s,]+ no_second none skip_empty none Other_Characteristics .................................. .................................. Invalidates cache No Macro No Has end tag [/xml-generator] Tag expansion example: [xml-generator type=delimited attributes="date" date="[tag time]%d-%b-%Y[/tag]" toplevel_tag=products ]code description price [query list=1 sql="select sku, description, price from products" prefix=xml][xml-code] [xml-param description] [xml-param price] [/query] [/xml-generator] --- os28113 The Claw Hand Rake 14.99 os28006 Painters Brush Set 29.99 ... ASP-like Perl call: $Tag->xml_generator( {type => delimited, toplevel_tag => apex, }, $BODY ); or similarly with positional parameters, $Tag->xml_generator( $type, $attribute_hash_reference, $BODY ); 6.25.2. Description ------------------- 6.25.2.1. type -------------- delimited Accepts a delimited and separated (default is TAB delimiter and newline separator) list of records such as that generated by an '[item-list]', '[sql]', or '[loop search=""]' ITL tag. session When the type is not delimited, it can contain any hash reference into the Interchange session. Examples are: values The form values scratch Scratch values errors Error values other Any other Session key, for example "source" for [data session source] If the value is a hash, then it will be sent as an XML record with the top level equal to "session", and a second_level tag equal to the hash name, and keys as separate XML container tags. If the parameter "that is equal to the type" is given, only those fields will be shown. Otherwise the entire hash will be shown. For example, this tag: [xml-generator type="values" values="fname lname"][/xml-generator] will generate: First Last if it is a scalar, then only the second level will be done: [xml-generator type="cybercash_id"][/xml-generator] will do the equivalent of: [data session cybercash_id] So bringing it all together, the following: [xml-generator type="values scratch source" values="fname lname" scratch="downloads"][/xml-generator] will generate: First Last 0 Partner1 6.25.2.2. no_second ------------------- Prevents the second-level tags from being generated. Extending the last example in the "session" type above, this [xml-generator type="values scratch source" no_second=1 values="fname lname" scratch="downloads"][/xml-generator] will generate: First Last 0 Partner1 6.25.2.3. attributes -------------------- The attributes (if any) to pass on to the top level tag. For instance, [xml-generator attributes="date" date="[tag time]%d-%b-%Y[/tag]" toplevel_tag=order ][/xml-generator] will generate a toplevel tag pair of: 6.25.2.4. dbdump ---------------- Will dump all tables in the catalog when this attribute is set true. Used attributes are "toplevel_tag", "record_tag", "field_tag", and "skip_empty" or default values ('table', 'record', 'field' respectively). Output format: fieldvalue1 fieldvalue2 fieldvalue1 fieldvalue2 fieldvalue1 fieldvalue2 Important note: All tables are read into memory. So be warned, this could be a real memory hog. Ton Verhagen's proposal: 1. Add option to select tables. E.g. dump_tables="products cat area" and/or 2. Add option to select an output file. E.g. dump_file="tabledump.XML". Send output to file line by line. 6.25.2.5. delimiter ------------------- Character used as delimiter of fields in delimited data type. Defaults to a tab character. 6.25.2.6. field_names --------------------- Space or comma-delimited list of field names to be used for delimited data type. Should be in the same order as in the data list provided (between the tags). Another way of providing the field names would be: [xml-generator .....]fieldname-1 fieldname-2 fieldname-3 [field value list delimited by option delimiter and separated by option separator][/xml-generator] Note: Field name list must be tab delimited. Ton Verhagen's humble opinion: This should change in future versions! Use option delimiter instead. 6.25.2.7. separator ------------------- Character used as line separator in list between [xml-separator][xml-separator] tags and in output 'session' data type. Defaults to a newline, "\n". 6.25.2.8. toplevel_tag ---------------------- The toplevel tag name to use. Defaults to "table" for the 'dbdump mode' and delimited type, and "session" for the other. 6.25.2.9. record_tag -------------------- Defines the tag name for the record tag. Defaults to 'record'. Used for 'dbdump mode' and delimited type. 6.25.2.10. field_tag -------------------- Defines the tag name for the field tag. Defaults to 'field'. Only used in 'dbdump mode'. 6.25.2.11. key_name ------------------- Only used in delimited data type. Defines fieldname to determine key value in "record_tag". .... 6.25.2.12. spacer ----------------- Character used as delimiter in type parameter definition and corresponding attributes. Defaults to '[\s,]+' (one or more whitespace or comma). [xml-generator type="values|scratch" values="value1|value2" scratch="scratch1|scratch2" spacer="|" ][/xml-generator] 6.25.2.13. skip_empty --------------------- Only used in dbdump mode (dbdump=1). Will skip empty fields if this attribute is set true. A. Template Parsing Order ========================= A.1. Standard Parsing --------------------- Under normal circumstances, the template page containing tags and HTML is parsed in the following order: 1. Any content in MV_AUTOLOAD is prepended to the template page. 2. Any [pragma] tags anywhere in the text are processed, and the specified pragmas are set. o 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). o If you want to apply a pragma with a variable or only to part of a document, you must use [tag pragma="..."] instead. 3. Variables (macros) are processed in the following order: 1. @@VARNAME@@ global variables 2. @_VARNAME_@ local or global variables 3. __VARNAME__ local variables 4. Interchange comments are stripped. 5. False-endtag macros are expanded (e.g., [/page] and [/order]). 6. '' escapes are converted to [tagname] o This can be a convenience for your HTML editor if it has trouble with tags using the standard [tagname] syntax. o However, if you want to HTML-comment out an Interchange tag in content that will be fed raw to a browser, you must include whitespace between the HTML comment delimiters and the tag, like this, ''. 7. The main tag parser is called. o Some tags parse recursively (depending upon reparse and interpolate settings, of course). o Some tags (e.g., [loop]) process PREFIX-tags in their contained body text. Hence, the PREFIX-tags are not handled recursively. o Some tags are interpreted in the lib/Vend/Parse.pm:start routine. You cannot call them with the '$Tag->tagname()' syntax. They are: o The [goto] tag. Note also that the [goto] tag handles the [label] tag. o The [bounce] tag. 8. Image paths substitution on the HTML output occurs. A.2. Nonstandard parsing within the admin interface --------------------------------------------------- Parsing of content via the specialized [regenerate] usertag included with the administrative interface does not obey the above order. The MV_AUTOLOAD 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. A.3. Nonstandard parsing of Subtags ----------------------------------- Subtags are parsed within the containing array-list or hash-list context created by the containing tag (see Looping tags and Sub-tags). o All subtags at an earlier precedence level are treated before any in the next level. o Within the same level, tags are processed in the order the appear on the page. o Any standard tags are processed during 'interpolate' (before) or 'reparse' (after) phases of processing the containing tag. Technical note Processing within a hash- or array-list is actually done as a series of global regular expression substitutions on the page. Each substitution replaces one tag with the output of the subroutine(s) associated with it. In array-list context, subtags are processed in the following order: 1. Check for PREFIX-line and prepare for it if present (does not process PREFIX-line at this time) 2. PREFIX-sub definitions processed 3. if-PREFIX-* nesting resolved 4. PREFIX-alternate processed 5. if-PREFIX-param processed 6. if-PREFIX-pos processed 7. PREFIX-pos processed 8. if-PREFIX-field processed 9. PREFIX-line processed 10. PREFIX-increment processed 11. PREFIX-accessories processed 12. PREFIX-options processed 13. PREFIX-code processed 14. PREFIX-description processed 15. PREFIX-field processed 16. PREFIX-price processed 17. PREFIX-change processed 18. PREFIX-calc processed 19. PREFIX-exec processed 20. PREFIX-filter processed 21. PREFIX-last processed 22. PREFIX-next processed 23. User's previous HTML widget SELECTED settings restored 24. Reparse standard tags in output of above (if reparse enabled for the containing tag) In hash-list context, subtags are processed in the following order: 1. PREFIX-sub definitions processed 2. if-PREFIX-* nesting resolved 3. PREFIX-alternate processed 4. PREFIX-line processed 5. if-PREFIX-param processed 6. if-PREFIX-field processed 7. if-PREFIX-modifier processed (if-PREFIX-param and if-PREFIX-modifier are functionally identical except for parse order) 8. PREFIX-increment processed 9. PREFIX-accessories processed 10. PREFIX-options processed 11. PREFIX-sku processed 12. PREFIX-code processed 13. PREFIX-quantity processed 14. PREFIX-modifier processed 15. PREFIX-param processed 16. PREFIX-quantity-name processed 17. PREFIX-modifier-name processed 18. PREFIX-subtotal processed 19. PREFIX-discount-subtotal processed 20. PREFIX-code processed again differently (operating on new instances of PREFIX-code in output of above?) 21. PREFIX-field processed 22. PREFIX-description processed 23. PREFIX-price processed 24. PREFIX-discount-price processed 25. PREFIX-difference processed 26. PREFIX-discount processed 27. PREFIX-change processed 28. PREFIX-tag processed (*** CHECK THIS TAG NAME ***) 29. PREFIX-calc processed 30. PREFIX-exec processed 31. PREFIX-filter processed 32. PREFIX-last processed 33. PREFIX-next processed 34. User's previous HTML widget SELECTED settings restored 35. Reparse standard tags in output of above (if reparse enabled for the containing tag) B. Search and Form Variables ============================ B.1. Variable Names ------------------- B.1..1. other ------------- 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_return lr 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) B.2. Abbreviations ------------------ The two-letter abbreviations are mapped with these letters: 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 ______________________________________________________________________ Copyright 2002-2004 Interchange Development Group. Copyright 2001-2002 Red Hat, Inc. Freely redistributable under terms of the GNU General Public License.