=head1 NAME ictags - Interchange Tags Reference =head1 DESCRIPTION =head1 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. =head1 Tag Syntax ITL tags are similar to HTML in syntax, in that they accept parameters or attributes and that there are both I and I tags. We will call an attribute a I if it may be called positionally or if it must be included (see the I and I 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] =head2 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] BSome macros look like tags or end tags. For example, [/page] is a macro for . This allows you to conveniently write [page I]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 [I], 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]). =head2 HTML-Comment ITL also allows you to use '' as interchangeable alternatives to plain square brackets: [tagname] and C< 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 '' Technical notes While '' with ']' unless it also sees ' $10.00 [price code="99-102" discount=1] --> $9.00 See I. I I =head2 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 S [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 S ... Aliases: B, B 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 link to your secure server.No Attributes Default interpolate (reparse) No Other_Characteristics Invalidates cache No Container tag No B [process targetframe 1] --- http://secure.here.com/cgi-bin/mycatalog/process.html?\ id=6CZ2whqo" TARGET="targetframe B $Tag->process( { target => 'frametarget', secure => 1, } ); or similarly with positional parameters, $Tag->process($target, $secure, $attribute_hash_reference); =head2 process-search This is an exact alias for [area]. =head2 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 I module (included with Bundle::Interchange from CPAN). Summary [query sql] [query sql="SQL_query_text" other_named_attributes] 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 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 Other_Characteristics Invalidates cache No Container tag Yes Has subtags Yes Nests No B 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] B 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); 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 I module (included with Bundle::Interchange from CPAN). This means that you can use simple SQL queries regardless of the underlying database implementation. I 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. Perl and ASP usage If you are calling $Tag->query within a perl tag (or whenever the code is secured by the I module), you must be sure to set the tables attribute properly in the enclosing perl tag (see the perl tag documentation for detail). The I 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 I, the tag will return a reference to an array of array references, since the default with no I is arrayref="". If you call $Tag->query in scalar context and set I or I, 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 S [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] BThe $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 'I=1' attribute in the query() call. See the I attribute. I This is the text of your SQL statement. The standard Interchange quoting rules apply. For example, use double quotes (") if you want to interpolate Interchange tags within your SQL statement, backticks (`) to calculate a value, I [query sql="select description, price from products where price < [value mv_arg]" ...] ... [/query] I 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}). I 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 S 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]; If you do not specify a type, the tag will create an arrayref as if you had set 'arrayref=""'. I If you set 'arrayref=I' or 'hashref=I', 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 S $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 B() to the 'arrayref' data structure. I 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. I

Requires 'type=list'. See the I 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 S 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. I<> Requires 'type=list'. Setting 'prefix=foo' overrides the default prefix of 'sql' for loop subtags within a list region (see I). See the I attribute below for an illustrative example. I 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] I 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=I', where I > 0, causes the [list] region to loop over I 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] I 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 I. Beware of reparsing issues. I