.\" Automatically generated by Pod::Man version 1.15 .\" Wed May 5 11:41:33 2004 .\" .\" Standard preamble: .\" ====================================================================== .de Sh \" Subsection heading .br .if t .Sp .ne 5 .PP \fB\\$1\fR .PP .. .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Ip \" List item .br .ie \\n(.$>=3 .ne \\$3 .el .ne 3 .IP "\\$1" \\$2 .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. | will give a .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used .\" to do unbreakable dashes and therefore won't be available. \*(C` and .\" \*(C' expand to `' in nroff, nothing in troff, for use with C<> .tr \(*W-|\(bv\*(Tr .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" If the F register is turned on, we'll generate index entries on stderr .\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and .\" index entries marked with X<> in POD. Of course, you'll have to process .\" the output yourself in some meaningful fashion. .if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .\" .\" For nroff, turn off justification. Always turn off hyphenation; it .\" makes way too many mistakes in technical documents. .hy 0 .if n .na .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. .bd B 3 . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ====================================================================== .\" .IX Title "ictags 8" .TH ictags 8 "Interchange 5.2.0" "2004-05-05" "Interchange" .UC .SH "NAME" ictags \- Interchange Tags Reference .SH "DESCRIPTION" .IX Header "DESCRIPTION" .SH "Interchange Tag Reference" .IX Header "Interchange Tag Reference" Interchange functions are accessed via the Interchange Tag Language (\s-1ITL\s0). The pages in a catalog may be mostly \s-1HTML\s0, but they will use \&\s-1ITL\s0 tags to provide access to Interchange's functions. \s-1ITL\s0 is a superset of \s-1MML\s0, or Minivend Markup Language. Minivend was the predecessor to Interchange. .PP 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. .PP This document covers Interchange versions 4.7 through 4.9. .SH "Tag Syntax" .IX Header "Tag Syntax" \&\s-1ITL\s0 tags are similar to \s-1HTML\s0 in syntax, in that they accept parameters or attributes and that there are both \fIstandalone\fR and \fIcontainer\fR tags. .PP We will call an attribute a \fIparameter\fR if it may be called positionally or if it must be included (see the \fIparameter\fR and \&\fIattribute\fR sections below). .PP A standalone tag has no ending element, e.g.: .PP .Vb 1 \& [value name] .Ve 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: .PP .Vb 3 \& [if value name] \& You have a name. It is [value name]. \& [/if] .Ve .Sh "Standard Syntax" .IX Subsection "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: .PP .Vb 1 \& [tagname parameters attributes]Contained Body Text[/tagname] .Ve \&\fBCaveat \- macros: \fRSome macros look like tags or end tags. For example, [/page] is a macro for . This allows you to conveniently write [page \fIhref\fR]Target[/page], but 'Target' is not treated as contained body text. .PP When using the [tagname ...] syntax, there must be no whitespace between the left bracket ('[') and the tagname. .PP If a tag name includes an underscore or dash, as in [\fIitem_list\fR], 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]). .Sh "HTML-Comment" .IX Subsection "HTML-Comment" \&\s-1ITL\s0 also allows you to use '' as interchangeable alternatives to plain square brackets: [tagname] and \&\f(CW\*(C`\*(C'\fR are equivalent. .PP This allows you make your raw tags appear as comments to \s-1HTML\s0 browsers or editors. You might want to do this if your editor has trouble with \&\s-1ITL\s0 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. .PP To properly HTML-comment contained body text, place your comment-style brackets appropriately, for example: .PP .Vb 1 \& .Ve Note that you must include whitespace between the \s-1HTML\s0 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': .PP .Vb 2 \& '' becomes 'Bill' \& '' becomes '' .Ve Technical notes .PP While '' with ']' unless it also sees 'routine( { search => $arrayref, } ); .Ve Similarly to use a hash reference for the 'entry' attribute: .PP .Vb 2 \& my $hashref = { name => "required", \& date => 'default="%B %d, %Y"', }; .Ve .Vb 1 \& $Tag->routine( { entry => $hashref } ); .Ve .SH "Looping tags and Sub-tags" .IX Header "Looping tags and Sub-tags" Certain tags are not standalone; these are the ones that are interpreted as part of a surrounding looping tag like [\fIloop\fR], [\fIitem-list\fR], [\fIquery\fR], or [\fIsearch-region\fR]. .Ip "" 4 [\fIPREFIX-accessories\fR] .Sp [\fIPREFIX-alternate\fR] .Sp [\fIPREFIX-calc\fR] .Sp [\fIPREFIX-change\fR] .Sp [\fIPREFIX-code\fR] .Sp [\fIPREFIX-data\fR] .Sp [\fIPREFIX-description\fR] (Note safe-data and \fIed()\fR escape) .Sp [\fIPREFIX-discount\fR] .Sp [\fIPREFIX-discount-subtotal\fR] .Sp [\fIPREFIX-field\fR] (Optimization note\-\- one query per field if you use this; we optimize around this if only one products table) .Sp [\fIPREFIX-increment\fR] .Sp [\fIPREFIX-last\fR] .Sp [\fIPREFIX-line\fR] (tab-delimited list of parameters returned) .Sp [\fIPREFIX-modifier\fR] .Sp [\fIPREFIX-next\fR] .Sp [\fIPREFIX-param\fR] .Sp [\fIPREFIX-pos\fR] .Sp [\fIPREFIX-price\fR] .Sp [\fIPREFIX-quantity\fR] .Sp [\fIPREFIX-subtotal\fR] .Sp [\fIif-PREFIX-data\fR] .Sp [\fIif-PREFIX-field\fR] .Sp [if-PREFIX-param] .Sp [if-PREFIX-pos] .Sp [\fImodifier-name\fR] .Sp [\fIquantity-name\fR] .PP \&\s-1PREFIX\s0 represents the prefix that is used in that looping tag. They are only interpreted within their container and only accept positional parameters. The default prefixes: .PP .Vb 5 \& Tag Prefix Examples \& [loop] loop [loop-code], [loop-field price], [loop-increment] \& [item-list] item [item-code], [item-field price], [item-increment] \& [search-list] item [item-code], [item-field price], [item-increment] \& [query] sql [sql-code], [sql-field price], [sql-increment] .Ve Sub-tag behavior is consistent among the looping tags. Subtags are parsed during evaluation of the enclosing loop, \fIbefore\fR any regular tags within the loop. .PP There are two types of looping lists: \s-1ARRAY\s0 and \s-1HASH\s0. .PP An array list is the normal output of a [query], a search, or a [loop] tag. It returns from 1 to N return fields, defined in the mv_return_fields or rf variable or implicitly by means of a \s-1SQL\s0 field list. The two queries below are essentially identical: .PP .Vb 2 \& [query sql="select foo, bar from products"] \& [/query] .Ve .Vb 5 \& [loop search=" \& ra=yes \& fi=products \& rf=foo,bar \& "] .Ve Both will return an array of arrays consisting of the foo column and the bar column. The Perl data structure would look like: .PP .Vb 6 \& [ \& ['foo0', 'bar0'], \& ['foo1', 'bar1'], \& ['foo2', 'bar2'], \& ['fooN', 'barN'], \& ] .Ve A hash list is the normal output of the [item-list] tag. It returns the value of all return fields in an array of hashes. A normal [item-list] return might look like: .PP .Vb 15 \& [ \& { \& code => '99-102', \& quantity => 1, \& size => 'XL', \& color => 'blue', \& mv_ib => 'products', \& }, \& { \& code => '00-341', \& quantity => 2, \& size => undef, \& color => undef, \& mv_ib => 'products', \& }, .Ve .Vb 1 \& ] .Ve You can also return hash lists in queries: .PP .Vb 2 \& [query sql="select foo, bar from products" type=hashref] \& [/query] .Ve Now the data structure will look like: .PP .Vb 6 \& [ \& { foo => 'foo0', bar => 'bar0' }, \& { foo => 'foo1', bar => 'bar1' }, \& { foo => 'foo2', bar => 'bar2' }, \& { foo => 'fooN', bar => 'barN' }, \& ] .Ve .Sh "PREFIX-accessories" .IX Subsection "PREFIX-accessories" .Vb 1 \& [PREFIX-accessories arglist] .Ve Except for the usual differences that apply to all subtags (such as parsing order), these are more or less equivalent for an array-type list: .PP .Vb 2 \& [accessories code=current_item_code arg=arglist] \& [item-accessories arglist] .Ve See the [accessories] tag for more detail. Note that you must use the comma-delimited list to set attributes \- you cannot set named attributes with the usual 'attribute=value' syntax. .PP If the list is a hash list, i.e. an [item-list], then the value of the current item hash is passed so that a value default can be established. .Sh "PREFIX-alternate" .IX Subsection "PREFIX-alternate" .Vb 1 \& [PREFIX-alternate N] DIVISIBLE [else] NOT DIVISIBLE [/else][/PREFIX-alternate] .Ve Set up an alternation sequence. If the item-increment is divisible by `N', the text will be displayed. If an `[else]NOT \s-1DIVISIBLE\s0 TEXT[/else]' is present, then the \s-1NOT\s0 \s-1DIVISIBLE\s0 \s-1TEXT\s0 will be displayed. .PP For example: .PP .Vb 2 \& [item-alternate 2]EVEN[else]ODD[/else][/item-alternate] \& [item-alternate 3]BY 3[else]NOT by 3[/else][/item-alternate] .Ve There are some additional primitives: .PP .Vb 7 \& Tag Description \& [item-alternate first_only] Only true on first item \& [item-alternate last_only] Only true on last item \& [item-alternate except_last] True except on last item \& [item-alternate except_first] True except on last item \& [item-alternate 0] Same as "first_only" \& [item-alternate -1] Same as "except_last" .Ve In the common case where you want to separate by a comma or other joiner: .PP .Vb 4 \& You have the following items: \& [item-list] \& [item-code][item-alternate except_last], [/item-alternate] \& [/item-list] .Ve .Sh "PREFIX-calc" .IX Subsection "PREFIX-calc" .Vb 1 \& [PREFIX-calc] 2 + [item-field price] [/PREFIX-calc] .Ve Executes Perl code in the tag body. This is equivalent to the [calc] ... [/calc] tag pair, except it's calculated at loop time instead of later when the rest of the page is parsed. .Sh "PREFIX-change" .IX Subsection "PREFIX-change" .Vb 1 \& [PREFIX-change][condition] ... [/condition] TEXT [/PREFIX-change] .Ve Sets up a breaking sequence that occurs when the contents of [condition] [/condition] change. The most common one is a category break to nest or place headers. .PP The region is only output when a field or other repeating value between [condition] and [/condition] changes its value. This allows indented lists similar to database reports to be easily formatted. The repeating value must be a tag interpolated in the search process, such as [PREFIX-field] or [PREFIX-field database field]. If you need access to \s-1ITL\s0 tags, you can use [PREFIX-calc] with a \&\f(CW$Tag\fR-\fIfoo()\fR> call. .PP Of course, this will only work as you expect when the search results are properly sorted. .PP The value to be tested is contained within a [condition]value[/condition] tag pair. The [PREFIX-change] tag also processes an [else] [/else] pair for output when the value does not change. .PP Here is a simple example for a search list that has a field category and subcategory associated with each item: .PP .Vb 6 \& \& \& [search-list] \& \& \& \& \& [/search-list] \&
CategorySubcategoryProduct
\& [item-change cat] .Ve .Vb 1 \& [condition][item-field category][/condition] .Ve .Vb 8 \& [item-field category] \& [else] \&   \& [/else] \& [/item-change cat] \& \& [item-change sub] .Ve .Vb 1 \& [condition][item-field subcategory][/condition] .Ve .Vb 9 \& [item-field subcategory] \& [else] \&   \& [/else] \& [/item-change sub] \& [item-field name]
.Ve The above should put out a table that only shows the category and subcategory once, while showing the name for every product. (The   will prevent blanked table cells if you use a border.) .Sh "PREFIX-code" .IX Subsection "PREFIX-code" .Vb 1 \& [PREFIX-code] .Ve The key or code of the current loop. In an [item-list] this is always the product code; in a loop list it is the value of the current argument; in a search it is whatever you have defined as the first mv_return_field (rf). .Sh "PREFIX-data" .IX Subsection "PREFIX-data" .Vb 1 \& [PREFIX-data table field] .Ve Calls the column field in database table table for the current [PREFIX-code] This may or may not be equivalent to [PREFIX-field field] depending upon whether your search table is defined as one of the ProductFiles. .Sh "PREFIX-description" .IX Subsection "PREFIX-description" .Vb 1 \& [PREFIX-description] .Ve The description of the current item, as defined in the catalog.cfg directive DescriptionField. In the demo, it would be the value of the field description in the table products. .PP If the list is a hash list, and the lookup of DescriptionField fails, then the attribute description will be substituted. This is useful to supply shopping cart descriptions for on-the-fly items. .Sh "PREFIX-discount" .IX Subsection "PREFIX-discount" .Vb 1 \& [PREFIX-discount] .Ve The price of the current item is calculated, and the difference between that price and the list price (quantity one) price is output. This may have different behavior than you expect if you set the [discount] tag along with quantity pricing. .Sh "PREFIX-discount-subtotal" .IX Subsection "PREFIX-discount-subtotal" .Vb 1 \& [PREFIX-discount-subtotal] .Ve Inserts the discounted subtotal of the ordered items. .Sh "PREFIX-field" .IX Subsection "PREFIX-field" .Vb 1 \& [PREFIX-field] .Ve Looks up a field value for the current item in one of several places, in this order: .PP .Vb 4 \& 1. The first ProductFiles entry. \& 2. Additional ProductFiles in the order they occur. \& 3. The attribute value for the item in a hash list. \& 4. Blank .Ve A common user error is to do this: .PP .Vb 4 \& [loop search=" \& fi=foo \& se=bar \& "] .Ve .Vb 2 \& [loop-field foo_field] \& [/loop] .Ve In this case, you are searching the table foo for a string of bar. When it is found, you wish to display the value of foo_field. Unless foo is in ProductFiles and the code is not present in a previous product file, you will get a blank or some value you don't want. What you really want is [loop-data foo field], which specifically addresses the table foo. See also [PREFIX-param] and [PREFIX-pos]. .Sh "PREFIX-increment" .IX Subsection "PREFIX-increment" .Vb 1 \& [PREFIX-increment] .Ve The current count on the list, starting from either 1 in a zero-anchored list like [loop] or [item-list], or from the match count in a search list. .PP If you skip items with [PREFIX-last] or [PREFIX-next], the count is \s-1NOT\s0 adjusted. .Sh "PREFIX-last" .IX Subsection "PREFIX-last" .Vb 1 \& [PREFIX-last] CONDITION [/PREFIX-last] .Ve If \s-1CONDITION\s0 evaluates true (a non-whitespace value that is not specifically zero) then this will be the last item displayed. .Sh "PREFIX-line" .IX Subsection "PREFIX-line" .Vb 1 \& [PREFIX-line start_column] .Ve Returns all array values from the current looping row in a single string, with each value separated by a tab, roughly equivalent to this: .PP .Vb 1 \& [PREFIX-pos 0](tab)[PREFIX-pos 1](tab)[PREFIX-pos 2](tab)[...] .Ve for however many fields were returned in that row. .PP This is useful as a quick way to see all your results at a glance and verify your search specification. .PP If the optional start_column attribute is given, the output starts with that column instead of column 0. .Sh "PREFIX-modifier" .IX Subsection "PREFIX-modifier" .Vb 1 \& [PREFIX-modifier attribute] .Ve If the item is a hash list (i.e. [item-list]), this will return the value of the attribute. .Sh "PREFIX-next" .IX Subsection "PREFIX-next" .Vb 1 \& [PREFIX-next] CONDITION [/PREFIX-next] .Ve If \s-1CONDITION\s0 evaluates true (a non-whitespace value that is not specifically zero) then this item is skipped. .Sh "PREFIX-param" .IX Subsection "PREFIX-param" .Vb 1 \& [PREFIX-param name] .Ve Returns the value of the column name associated with the looping tag row. Each looping list returns an array of return fields, set in searches with mv_return_field or rf. The default is only to return the code of the search result, but by setting those parameters you can return whichever columns you wish. .PP In a [query] \s-1ITL\s0 tag you can select multiple return fields with something like: .PP .Vb 3 \& [query prefix=prefix sql="select foo, bar from baz where foo='buz'"] \& [prefix-code] [prefix-param foo] [prefix-param bar] \& [/query] .Ve In this case, [prefix-code] and [prefix-param foo] are synonyms, as foo is the first returned parameter and becomes the code for this row. Another synonym is [prefix-pos 0]. .PP Mixed case field names in your \s-1SQL\s0 tables will be forced to lower case in the [prefix-param name] tag if the underlying Database does that (as with most \s-1SQL\s0 types). For example if your query is .PP .Vb 1 \& [query prefix=prefix sql="select Foo, Bar from baz where Foo='buz'"] .Ve then you must use: .PP .Vb 1 \& [prefix-param foo] and [prefix-param bar] .Ve to display your results, rather than: .PP .Vb 1 \& [prefix-param Foo] and [prefix-param Bar] .Ve Note that the following code is invalid: .PP .Vb 9 \& [query prefix=prefix sql=| \& SELECT table1.foo, \& table2.bar \& FROM table1, table2 \& WHERE table1.code = table2.code \& AND table1.foo = 'buz' \& |] \& [prefix-param table1.foo] [prefix-param table2.bar] \& [/query] .Ve The problem with the above code is that \s-1DBI\s0 doesn't support column names such as table1.foo in its resultsets. The following query syntax is fully supported by \s-1DBI\s0 and therefore by Interchange: .PP .Vb 9 \& [query prefix=prefix sql=| \& SELECT table1.foo AS foo, \& table2.bar AS bar \& FROM table1, table2 \& WHERE table1.code = table2.code \& AND table1.foo = 'buz' \& |] \& [prefix-param foo] [prefix-param bar] \& [/query] .Ve .Sh "PREFIX-pos" .IX Subsection "PREFIX-pos" .Vb 1 \& [PREFIX-pos N] .Ve Returns the value of the array parameter associated with the looping tag row. Each looping list returns an array of return fields, set in searches with mv_return_field or rf. The default is only to return the code of the search result, but by setting those parameters you can return whichever columns you wish. .PP [PREFIX-pos N] outputs the data from the \fIN\fRth column as returned (starting with zero). [PREFIX-param] lets you access the data by column name instead of by number. .PP In a [query ...] \s-1ITL\s0 tag you can select multiple return fields with something like: .PP .Vb 3 \& [query prefix=prefix sql="select foo, bar from baz where foo='buz'"] \& [prefix-code] [prefix-param foo] [prefix-param bar] \& [/query] .Ve In this case, [prefix-code] and [prefix-param foo] are synonyms, as foo is the first returned parameter and becomes the code for this row. Another synonym is [prefix-pos 0]. [prefix-pos 1] is the same as [prefix-param bar]. The following code will produce exactly the same output as the above: .PP .Vb 3 \& [query prefix=prefix sql="select foo, bar from baz where foo='buz'"] \& [prefix-pos 0] [prefix-pos 0] [prefix-pos 1] \& [/query] .Ve Note that if you use the [PREFIX-pos] tag, you may have to review your column numbers whenever you modify the columns you select. For this reason, queries that make use of the [PREFIX-param] tag may be easier to maintain and will be less prone to future surprises. .Sh "PREFIX-price" .IX Subsection "PREFIX-price" .Vb 1 \& [PREFIX-price] .Ve The price of the product identified by the current code, formatted for currency. If Interchange's pricing routines cannot determine the price (i.e. it is not a valid product or on-the-fly item) then zero is returned. If the list is a hash list, the price will be modified by its quantity or other applicable attributes (like size in the demo). .Sh "PREFIX-quantity" .IX Subsection "PREFIX-quantity" .Vb 1 \& [PREFIX-quantity] .Ve The value of the quantity attribute in a hash list. Most commonly used to display the quantity of an item in a shopping cart [item-list]. .Sh "PREFIX-subtotal" .IX Subsection "PREFIX-subtotal" .Vb 1 \& [PREFIX-subtotal] .Ve The [PREFIX-quantity] times the [PREFIX-price]. This does take discounts into account. .Sh "if-PREFIX-data" .IX Subsection "if-PREFIX-data" .Vb 1 \& [if-PREFIX-data table field] IF text [else] ELSE text [/else] [/if-PREFIX-data] .Ve Examines the data field, i.e. [PREFIX-data table field], and if it is non-blank and non-zero then the \s-1IF\s0 text will be returned. If it is false, i.e. blank or zero, the \s-1ELSE\s0 text will be returned to the page. .PP This is much more efficient than the otherwise equivalent [if type=data term=table::field::[PREFIX-code]]. .PP You cannot place a condition; i.e. [if-PREFIX-data table field eq \&'something']. Use [if type=data ...] for that. .PP Careful, a space is not a false value! .Sh "if-PREFIX-field" .IX Subsection "if-PREFIX-field" .Vb 1 \& [if-PREFIX-field field] IF text [else] ELSE text [/else] [/if-PREFIX-field] .Ve Same as [if-PREFIX-data ...] except uses the same data rules as [PREFIX-field]. .Sh "PREFIX-modifier-name" .IX Subsection "PREFIX-modifier-name" .Vb 1 \& [PREFIX-modifier-name attribute] .Ve Outputs a variable name which will set an appropriate variable name for setting the attribute in a form (usually a shopping cart). Outputs for successive items in the list: .PP .Vb 3 \& 1. attribute0 \& 2. attribute1 \& 3. attribute2 .Ve etc. .PP [PREFIX-modifier-name quantity] would be the same as [PREFIX-quantity-name]. .Sh "PREFIX-quantity-name" .IX Subsection "PREFIX-quantity-name" .Vb 1 \& [item-quantity-name] .Ve Outputs for successive items in the list: .PP .Vb 3 \& 1. quantity0 \& 2. quantity1 \& 3. quantity2 .Ve etc. .PP [PREFIX-modifier-name quantity] would be the same as [PREFIX-quantity-name]. .SH "Tags" .IX Header "Tags" Each \s-1ITL\s0 tag is show below. Calling information is defined for the main tag, sub-tags are described in \fILooping tags and Sub-tags\fR. .Sh "accessories" .IX Subsection "accessories" A Swiss-army-knife widget builder, this provides access to Interchange's product option attributes (e.g., to choose or access product options such as a shirt's size or color). .PP Can build selection objects (radio, check, select boxes, etc), forms or hyperlinks, or can simply return a value. .PP Or more \- see also \fILooping tags and Sub-tags\fR. .PP Summary .PP .Vb 3 \& [accessories code arg] \& [accessories code=os28044 arg="size, radio, ... " other_named_attributes] deprecated \& [accessories code=os28044 attribute=size type=radio ... other_named_attributes] .Ve .Vb 3 \& Parameters Description Default \& code Value of the master key in the product (or specified other) tablenone \& arg Positionally interpreted comma-delimited list of values for the following attributes:"attribute, type, column, table, name, outboard, passed"none .Ve .Vb 35 \& Attributes Default \& attribute none \& typeOne of select, value, text, textarea, hidden, password, combo, move_combo, reverse_combo, show, options, labels, checkbox, radio, linksselect \& column attribute \& table products \& name mv_order_attribute \& outboard none \& passed none \& key (alias for code) none \& row (alias for code) none \& base (alias for table) products \& database (alias for table) products \& db (alias for table) products \& col (alias for column attribute \& field (alias for column attribute \& delimiter comma (',') \& prepend none \& append none \& extra none \& js none \& rows varies with type; often 4 \& cols varies with type; often 40 \& width none \& default none \& price none \& price_data none \& contains (type=radio or check) none \& joiner (type=links) none \& href (type=links) none \& template (type=links) none \& form (type=links) mv_action=return \& empty (type=links) none \& secure (type=links) none \& new none \& interpolate (reparse) No .Ve .Vb 4 \& Other_Characteristics \& Invalidates cache No \& Container tag No \& Has Subtags No .Ve \&\fBTag expansion example:\fR .PP .Vb 4 \& [accessories os28044 size] \&--- \& .Ve \&\fBASP-like Perl call:\fR .PP .Vb 3 \& $Tag->accessories( { code => '[[EXAMPLE_SKU]]', \& arg => 'color, radio' \& table => 'special_products', } ); .Ve or similarly with positional parameters, .PP .Vb 1 \& $Tag->accessories($code, $arg, $attribute_hash_reference); .Ve See Also .PP \&\fILooping tags and Sub-tags\fR. .PP Description .PP This is the swiss-army-knife widget builder for providing access to Interchange's product option attributes (e.g., to choose or access product options such as a shirt's size or color). .PP Interchange allows you to choose item attribute values for each ordered item \- you can attach a size, color, or other modifier to a line item in the shopping cart. You can also resubmit previous attribute values via hidden fields on a form. .PP The catalog.cfg file directive \fIUseModifier\fR is used to set the name of the modifier or modifiers. For example .PP .Vb 1 \& UseModifier size color .Ve will attach both a size and color attribute to each item code that is ordered. .PP \&\fBImportant Note \*(-- \fRYou may not use the following names for attributes: .PP item group quantity code mv_ib mv_mi mv_si .PP You can also set modifier names with the mv_UseModifier scratch variable \- [setEmv_UseModifier] size color [/set] has the same effect as above. This allows multiple options to be set for products. Whichever one is in effect at order time will be used. Be careful; you cannot set it more than once on the same page. Setting the mv_separate_items or global directive \fISeparateItems\fR places each ordered item on a separate line, simplifying attribute handling. The scratch setting for mv_separate_items has the same effect. .PP The modifier value is accessed in the [item-list] loop with the [item-param attribute] tag, and form input fields are placed with the [modifier-name attribute] tag. This is similar to the way that quantity is handled. .PP \&\fBNote: \fRYou must be sure that no fields in your forms have digits appended to their names if the variable is the same name as the attribute name you select, as the [PREFIX-modifier-name size] variables will be placed in the user session as the form variables size0, size1, size2, etc. .PP Interchange will automatically generate the select boxes when the [accessories code=\*(L"os28044\*(R" attribute=\*(L"size\*(R"] or [item-accessories size] tags are called. They have the syntax: .PP .Vb 1 \& [item-accessories attribute, type, column, table, name, outboard, passed] .Ve .Vb 8 \& [accessories code=sku \& attribute=modifier \& type=select \& column=db_table_column_name \& table=db_table \& name=varname \& outboard=key \& passed="value=label, value2*, value3=label 3"] .Ve .Vb 4 \& [accessories js=| onChange="set_description(simple_options, variant)"; | \& type=select \& name="[item-param o_group]" \& passed="=--choose--,[item-param o_value]"] .Ve \&\fBNotes: \fR .Ip "1." 4 The 'attribute' attribute is required. .Ip "2." 4 See the type attribute for a list of types. .Ip "3." 4 The trailing '*' in value2 will mark it as the default ('\s-1SELECTED\s0') value in the select widget (see below). .PP When called with an attribute, the database is consulted and looks for a comma-separated list of item attribute options. They take the form: .PP .Vb 1 \& name_a=Label Text1, default_name=Default Label Text*, name_b, etc. .Ve The label text is optional \- if none is given, the \fBname\fR will be used (as in 'name_b' above). .PP If an asterisk is the last character of the label text, the item is the default selection. If no default is specified, the first will be the default. An example: .PP .Vb 1 \& [item-accessories color] .Ve This will search the product database for a field named \*(L"color\*(R". If an entry \*(L"beige=Almond, gold=Harvest Gold, White*, green=Avocado\*(R" is found, a select box like this will be built: .PP .Vb 6 \& .Ve In combination with the mv_order_item and mv_order_quantity session variables, you can use this to allow a customer to enter an item attribute during an order. .PP If used in an item list, and the user has changed the value, the generated select box will automatically retain the current value the user has selected. .PP The value can then be displayed with [item-modifier color] on the order report, order receipt, or any other page containing an [item-list]. .PP Emulating with a loop .PP You can also build widgets directly, without using the accessories tag. You may have to do so if you need more control of the content than the tag offers. Below is a fragment from a shopping basket display form which shows a selectable size with \*(L"sticky\*(R" setting and a price that changes based upon the modifier setting. (Note that this example would normally be contained within the [item-list][/item-list] pair.) .PP .Vb 5 \& .Ve The output of the above would be similar to the output of [item-accessories size, select] if the product database field size contained the value S, M, L, \s-1XL\s0. The difference is that the options in the loop emulation show the adjusted price in addition to the size within each option value. .PP \&\fIHash Lists\fR \- Technical Note .PP As a technical note, some of the features of this tag work differently depending upon whether it was called with an '$item' hash reference, for example, as [item-accessories] within an [item-list]. .PP In this context, the tag will have access to ancillary data from the item (including, perhaps, a user's chosen item attribute value). For example, if building a \s-1TEXTAREA\s0 widget within an [item-list], the widget will show the chosen item attribute value. On the other hand, within an array list such as a [search-list] in a [search-region], the widget would be empty. .PP If you really know what you're doing, you can pass it the item hash reference within a [perl] tag like this: .PP .Vb 4 \& $Tag->accessories( $code, \& undef, # 'arg' parameter value \& $named_attribute_hashref, \& $item_hashref ); .Ve See also Looping tags and Sub-tags for information about hash-context and array-context in looping tags. .PP \&\fIcode\fR .PP This is the master key of the specified table (commonly sku in a product table). If no table is specified, the tag uses the products table by default. .PP You should not specify a code when looping on [item_accessories] because it internally sets 'code' to the key for the current item in the loop. .PP \&\fIarg\fR .PP \&\fBDeprecated after Interchange 4.6\fR .PP This allows you to pass values for some of the more commonly used attributes in the manner of the [item-accessories] tag, as a comma-delimited positional list: .PP .Vb 1 \& arg="attribute, type, column, table, name, outboard, passed" .Ve Whitespace within the list is optional. .PP If you leave out one or more of the above attributes, be sure to keep the \fIcomma\fR\|(s) if you are setting anything after it in the list: .PP .Vb 1 \& arg="attribute, type, , table" .Ve The above examples show the attribute names for clarity; you would actually use the values. Hence, the previous example might actually be something like the following: .PP .Vb 1 \& arg="color, radio, , products" .Ve Although you must use such a comma-delimited list to pass attributes to the [item-accessories] tag, please use named attributes instead for the [accessories] tag. The 'arg' attribute is deprecated. .PP For detail about a specific attribute, please see its subheading below. .PP \&\fIattribute\fR .PP Despite the name, this has nothing to do with tag attributes. You can set attributes for \fIitems\fR in a database table (typically the products table) with the UseModifier configuration directive. Typical are size or color. .PP This selects the item attribute the tag will work with. .PP \&\fItype\fR .PP This determines the action to be taken. One of: .PP .Vb 25 \& Action Description \& select Builds a dropdown menu). \& show Returns the list of possible attributes for the item (without labels or any HTML widget). For example, if sku os28044 is available in several sizes:[accessories os28044 size,show]-----------------------------------------Sm=10oz, Med=15oz*, Lg=20oz \& options This shows the attribute options as a newline delimited list:[accessories os28044 size,options]-----------------------------------------SmMedLg \& labels This shows the attribute option labels:[accessories os28044 size,options]-----------------------------------------10oz15oz*20oz \& radio Builds a radio box group for the item, with spaces separating the elements. \& radio nbsp Builds a radio box group for the item, with   separating the elements. \& radio break Builds a radio box group for the item, with '
' separating the radio button/label pairs from one another. \& radio left n Builds a radio box group for the item, inside a table, with the checkbox on the left side. If "n" is present and is a digit from 2 to 9, it will align the options in that many columns.You can also set FONT SIZE like this: type="radio left n fontsizem"where -9 <= m <= 9 \& radio right n Builds a radio box group for the item, inside a table, with the checkbox on the right side. If "n" is present and is a digit from 2 to 9, it will align the options in that many columns.You can also set FONT SIZE like this: type="radio right n fontsizem"where -9 <= m <= 9 \& check Builds a checkbox group for the item, with spaces separating the elements. \& check nbsp Builds a checkbox group for the item, with ' ' separating the checkbox/label pairs from one another. \& check break Builds a checkbox group for the item, with '
' separating the checkbox/label pairs from one another. \& check left n Builds a checkbox group for the item, inside a table, with the checkbox on the left side. If "n" is present and is a digit from 2 to 9, it will align the options in that many columns.You can also set FONT SIZE like this: type="check left n fontsizem"where -9 <= m <= 9 \& check right n Builds a checkbox group for the item, inside a table, with the checkbox on the right side. If "n" is present and is a digit from 2 to 9, it will align the options in that many columns.You can also set FONT SIZE like this: type="check right n fontsizem"where -9 <= m <= 9 \& textarea_XX_YY A textarea with XX columns and YY rows. The textarea will contain the selected item attribute value if used in Hash List context (e.g., within an [item-list]).If you simply use 'type=textarea', the size will default to 4 rows by 40 columns, unless you have set the rows or cols tag attributes. \& text_YY A text box with YY width in characters. The HTML tag's VALUE will be set to the selected item attribute value if used in Hash List context (e.g., within an [item-list]).If you simply use 'type=text', the width will default to 60, unless you have set the cols tag attribute. \& combo Special type, used with nullselect filter, for selecting from a list or inputting a new value \& reverse_combo Special type, used with last_non_null filter, for selecting from a list or inputting a new value - differs from combo in order of presentation \& move_combo Special type, used with null_to_space or null_to_comma filter, for selecting multiple non-ordered values from a list or inputting into a textarea \& links Produces a series of links based on the option values. The base form value is passed via the form parameter, just like in an [area ...] or [page ...] tag, and the value is named with the passed NAME attribute. \& value Returns the selected value if called in Hash List context (e.g., within an [item-list]), or nothing otherwise. \& hidden Creates a hidden form field. The hidden field's VALUE will be set to the selected item attribute value if used in Hash List context (e.g., within an [item-list]). \& password_YY A password box with YY width in characters. The HTML tag's VALUE will be set to the selected item attribute value if used in Hash List context (e.g., within an [item-list]).If you simply use 'type=password', the width will default to 12, unless you have set the cols tag attribute. .Ve The default is 'select', which builds an \s-1HTML\s0 select form entry for the attribute. .PP Some types build widgets that use the ROWS=\fIm\fR, COLS=\fIn\fR, or certain other \s-1HTML\s0 attributes. For these, you can define widget rows and columns within the string that sets the type; for example, type=\*(L"textarea_6_33_wrap=virtual\*(R" specifies a \s-1TEXTAREA\s0 widget with ROWS=6, COLS=33, and WRAP=virtual. You should resort to this only when you cannot use the named parameters, for example within an [item-accessories] tag. Otherwise, use the rows=\fIm\fR and cols=\fIn\fR tag attributes instead. .PP The result of setting conflicting values in the type string and the rows or cols attributes is undefined. .PP The following list shows syntax for type strings, where \fIrows\fR is the number of rows and \fIcols\fR is the number of columns. .Ip "\(bu" 4 \&\fBtext\fR .RS 4 .Ip "\(bu" 8 textarea \fI(default is 4 rows, 40 columns, like 'textarea_4_40')\fR .Ip "\(bu" 8 textarea_\fIrows\fR_\fIcols\fR .Ip "\(bu" 8 text_\fIcols\fR .Ip "\(bu" 8 textarea rows=\fIrows\fR cols=\fIcols\fR wrap=\fI\s-1WRAP\s0 value\fR .RE .RS 4 .RE .Ip "\(bu" 4 \&\fBpassword\fR .RS 4 .Ip "\(bu" 8 password \fI(default is 12 columns, like 'password_12')\fR .Ip "\(bu" 8 password_\fIcols\fR .RE .RS 4 .RE .Ip "\(bu" 4 \&\fBcombo\fR (similarly for \fBreverse_combo\fR and \fBmove_combo\fR) .RS 4 .Ip "\(bu" 8 combo \fI(default is 1 row, 16 columns, like 'combo_1_16')\fR .RE .RS 4 .RE .PP In any of the option building types, you can append the string ranges and a special option processing will be done \*(-- any option matching the pattern [A-Za-z0\-0]..[A-Za-z0\-0] will be expanded into a comma separated range between the bounds. The same behavior is accomplished by passing the accessories tag option ranges. For example: .PP .Vb 3 \& [accessories name=foo type=select ranges=1 "A..C,1..5,10,20"] \& and \& [accessories name=foo type="select ranges" passed="A..C,1..5,10,20"] .Ve .Vb 1 \& will both output: .Ve .Vb 13 \& .Ve The above applies to any of the option building types \*(-- check, combo, combo_move, labels, multiple, options, radio, reverse_combo, and select. It will refuse to produce more than 5000 options \*(-- that limit can be changed with Limit option_list N in catalog.cfg, where N is an integer greater than 0. .PP \&\fIcolumn\fR .PP The column of the table corresponding to the attribute will traditionally have the same name as the attribute, though it need not. .PP This specifies the table column that contains an item's attribute values. The tag will find item attribute names and values in a comma-delimited list of name=value pairs stored in this field of an item's table entry. If unspecified, the column name will default to the name given for the 'attribute' attribute. .PP For example, if an item in the products table has a 'size' attribute, and each item's comma-delimited list of available sizes is stored in the 'how_big' column, then you would need to specify \&\*(L"column=how_big\*(R" because the tag's default column choice (size) would be missing or used for some other purpose. .PP \&\fItable\fR .PP This is the database table containing the item's attribute values. It defaults to the first products file where the item code is found. .PP If you have configured your database so that the attributes are kept in a different table from other item data, 'code' should be set to the master key in this table. See 'outboard') if you are using [item-accessories] and cannot specify code=key. .PP \&\fIname\fR .PP This sets the name of the form variable to use if appropriate for the widget being built. Defaults to 'mv_order_\fBattribute\fR' \- i.e. if the attribute is \fBsize\fR, the form variable will be named \&\fBmv_order_size\fR. .PP If the variable is set in the user session, the widget will \*(L"remember\*(R" its previous setting. In other words, [value \fIname\fR] will contain the previous setting, which the widget will use as its default setting. See also the default attribute. .PP \&\fIoutboard\fR .PP If calling the item-accessories tag, and you wish to select from an outboard database table whose master key is different from the item code, you can pass the key the tag should use to find the accessory data. .PP \&\fIpassed\fR .PP You can use this to pass your own values to the widget the tag will build. If you have set passed to a list of widget options, then the tag will simply build a widget of the specified \fItype\fR with your values instead of fetching an attribute value list from the database. .PP For example, to generate a select box with a blank option (perhaps forcing a select), the value of blue with a label of \fBBlue\fR, and the value of green with a label of \fBSea Green\fR, do: .PP .Vb 3 \& [accessories type=select \& name=color \& passed="=--select--*, blue=Blue, green=Sea Green"] .Ve This will generate: .PP .Vb 3 \& .Ve Note: trailing backslashes ('\e') in the above example indicate line continuation and are not part of the tag output. .PP \&\fIdelimiter\fR .PP The list of attribute values will be a delimited string. This allows you to specify an alternative delimiter if the list is not comma-delimited (the default). .PP \&\fIprepend\fR .PP You can set a string to prepend to the returned output of the tag. Note that this is \fInot\fR a list to prepend to the fetched attribute value list, which is treated within the tag. .PP For example, .PP .Vb 10 \& [accessories code=os28044 \& type=select \& attribute=size \& append="Append Me
" \& prepend="Prepend Me"] \&--- \& Prepend MeAppend Me
.Ve \&\fIappend\fR .PP You can set a string to append to the returned output of the tag. Note that this is \fInot\fR a list to append to the fetched attribute value list, which is treated within the tag. .PP \&\fIextra\fR .PP Setting the 'extra' attribute appends its value as the last attribute of the \s-1HTML\s0 output tag. The following example illustrates the append, extra and js options: .PP .Vb 11 \& [accessories code=os28044 \& type=select \& attribute=size \& append="Append Me
" \& extra="Last=Extra" \& js="javascript_here"] \&--- \& Append Me
.Ve \&\fIjs\fR .PP This allows you to place javascript within the start tag of the \s-1HTML\s0 output. See the example given above for extra. .PP js has no default, except when 'type=move_combo', where the default is: .PP .Vb 1 \& onChange="addItem(this.form.Xname,this.form.name)" .Ve \&\fIrows\fR .PP The tag will pass the number you choose through to the \s-1HTML\s0 \&'ROWS=\fIn\fR' attribute in \s-1HTML\s0 widgets that accept it. .PP For some types, you can also define widget rows and columns within the string that sets the type; for example, type=\*(L"textarea_6_33_wrap=virtual\*(R" specifies a \s-1TEXTAREA\s0 widget with ROWS=6, COLS=33, and WRAP=virtual. You should resort to this only when you cannot use the named parameters, for example within an [item-accessories] tag. .PP The result of setting conflicting values in the type string and the rows=\fIn\fR attribute is undefined. .PP \&\fIcols\fR .PP The tag will pass the number you choose through to the \s-1HTML\s0 \&'COLS=\fIn\fR' attribute in \s-1HTML\s0 widgets that accept it. .PP See also 'rows' above. .PP \&\fIwidth\fR .PP This is a quasi-alias for 'cols' that only works with the 'text' and '' types. Use 'cols' instead. .PP \&\fIdefault\fR .PP Sets the default attribute option in the widget returned by the tag. This will override a default indicated with a trailing '*' in the database or 'passed' string. This will also override the default of a user's previous selection when the tag would otherwise have preserved it. .PP For example the following selects blue by default rather than green as it would otherwise have done, .PP .Vb 8 \& [accessories type=select \& name=color \& passed="blue=blue, green=Sea Green*" \& default="blue"] \&--- \& \&--- .Ve Obscure technical note: the tag ignores the 'default' attribute if it has an item hash reference \- see Hash Lists above. .PP \&\fIprice\fR .PP When combined with the price_data tag attribute, this allows you to force prices for item attributes. You probably do not want to use this; just let the tag pick up prices from your database \fItable\fR\|(s) when appropriate. .PP If you are passing attribute values, you can use this to control the displayed price in the widget. .PP .Vb 10 \& [accessories type=check \& name=color \& price=1 \& price_data="blue=20, green=50" \& passed="blue=Blue, green=Sea Green*"] \&--- \&  Blue ($20.00) \&  Sea Green ($50.00) .Ve \&\fIprice_data\fR .PP \&\fIcontains\fR .PP Requires 'type=radio' or 'type=check'. .PP Used to determine whether a substring match of the value will cause a radio box or check box to be selected. If true, the match will happen whether the value is on a word boundary or not \*(-- if false, the value must be on a word boundary. (When we speak of a word boundary, it is in the Perl sense \*(-- a word character [A-Za-z0\-9_] followed or preceded by a non-word character, or beginning or end of the string.) .PP \&\fIjoiner\fR .PP Requires '\fItype\fR=links'. .PP With type=links, the accessories tag returns a link for each option. This allows you to override the default string ('<\s-1BR\s0>') that joins these links. You can use Perl's metacharacter escapes, such as \&'\en' for newline or '\et' for tab. .PP \&\fIhref\fR .PP Requires '\fItype\fR=links'. .PP This sets the base \s-1HREF\s0 for the link in a links type. Default is the current page. .PP \&\fItemplate\fR .PP Requires '\fItype\fR=links'. .PP Allows you to override the standard Interchange template for a hyperlink. You probably don't need to use this \- grep the code to grok it if you do (see 'sub build_accessory_links'). .PP \&\fIform\fR .PP Requires '\fItype\fR=links'. .PP This sets the base value for the form in a links type. Default is mv_action=return, which will simply set the variable value in the link. .PP For example, to generate a series of links \- one per item attribute value passed \- that set the variable \*(L"color\*(R" to the corresponding passed value (blank, blue, or green), do this: .PP .Vb 3 \& [accessories type=links \& name=color \& passed="=--select--, blue=Blue, green=Sea Green"] .Ve This will generate something like the following: .PP .Vb 2 \& Blue
\& Sea Green .Ve where \s-1VENDURL\s0 is your Interchange \s-1URL\s0 for the catalog \s-1MV_PAGE\s0 is the current page. .PP If you want the empty \*(L"\-\-select\-\-\*(R" option to show up, pass an empty=1 parameter. .PP \&\fIempty\fR .PP Requires '\fItype\fR=links'. .PP Setting 'empty=1' includes a hyperlink for the empty \*(L"\-\-select\-\-\*(R" option. See the example in form above; if empty=1 had been specified, three links would have been generated. .PP \&\fIsecure\fR .PP Requires '\fItype\fR=links'. .PP Setting secure=1 causes the generated \fIlink\fR\|(s) to point to your secure Interchange \s-1URL\s0. .PP \&\fInew\fR .PP Requires '\fItype\fR=combo' or 'reverse_combo'. .PP You can use this to set a value in place of the 'New' or 'Current' option in a combo box. For example, if item 'os28044' has size attribute values of \*(L"Sm=10oz, Med=15oz, Lg=20oz\*(R": .PP .Vb 8 \& [accessories code=os28044 attribute=size type=combo new="my_new_value"] \&--- \& \& .Ve Or, with the default new value: .PP .Vb 8 \& [accessories code=os28044 attribute=size type=combo] \&--- \& \& .Ve Default is no \s-1VALUE\s0 with option text set to '<\-\- New' for a combo box or 'Current \-\->' for a reverse_combo box. .Sh "and" .IX Subsection "and" Summary .PP Parameters: \fBtype term op compare\fR .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 \&\fBNote: \fRThis tag has special positional parameter handling. .PP .Vb 1 \& [and 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 2 \& [value name=fname set="Mike" hide=1] \& [value name=lname set="" hide=1] .Ve .Vb 1 \& ... .Ve .Vb 9 \& [if value fname] \& [and value lname] \& Both first and last name are present. \& [else] \& Missing one of "fname" and "lname" from $Values. \& [/else] \& [/if] \&--- \& Missing one of "fname" and "lname" from $Values. .Ve \&\fBASP-like Perl call:\fR .PP Not applicable. The [and ...] tag only is used with [if ...], and Perl logic obviates the [if ...] tag. .PP Description .PP The [and ...] tag is only used in conjunction with [if ...]. Example: .PP .Vb 7 \& [if value fname] \& [and value lname] \& Both first and last name are present. \& [else] \& Missing one of "fname" and "lname" from $Values. \& [/else] \& [/if] .Ve See the description of the [if] tag. .PP \&\fIcompare\fR .PP \&\fIop\fR .PP \&\fIterm\fR .PP \&\fItype\fR .Sh "area" .IX Subsection "area" Alias: \fBhref\fR .PP Expands to the \s-1URL\s0 for an Interchange page or action, including the Interchange session \s-1ID\s0 and supplied arguments. This is very similar to the \fIpage\fR tag \- these are equivalent: .PP .Vb 2 \& [page href=dir/page arg=mv_arg]TargetName \& TargetName .Ve Summary .PP .Vb 2 \& [area href arg] \& [area href=dir/page arg=page_arguments other_named_attributes] .Ve .Vb 3 \& Parameters Description Default \& href Path to Interchange page or actionSpecial arguments'scan' links to a search (using search arguments in arg)'http://...' external link (requires form attribute)process \& arg Interchange arguments to page or action none .Ve .Vb 5 \& Attributes Default \& form none \& search No \& secure No \& interpolate (reparse) No .Ve .Vb 4 \& Other_Characteristics \& Invalidates cache No \& Macro No \& Has end tag No .Ve \&\fBTag expansion example:\fR .PP .Vb 1 \& [area href=dir/page.html arg="arg1=AA/arg2=BB"] .Ve .Vb 2 \& www.here.com/cgi-bin/mycatalog/page.html?mv_session_id=6CZ2whqo&\e \& mv_pc=1&mv_arg=arg1%3dAA/arg2%3dBB .Ve \&\fBASP-like Perl call:\fR .PP .Vb 2 \& $Tag->area( { href => "dir/page", \& arg => "arguments", } ); .Ve or similarly with positional parameters, .PP .Vb 1 \& $Tag->area($href, $arg, $attribute_hash_reference); .Ve See Also .PP \&\fIpage\fR .PP Description .PP The area tag is very similar to the [page] tag. It produces the \&\s-1URL\s0 to call an Interchange page, but it differs from page in that it does not supply the surrounding notation. This can be used to get control of your \s-1HREF\s0 items, perhaps to place an \s-1ALT\s0 string or a Javascript construct. .PP It was originally named area because it also can be used in a client-side image map. .PP The area tag has an alias of href. The two links below are identical in operation: .PP .Vb 2 \& Catalog Home \& Catalog Home .Ve The optional \fIarg\fR is used just as in the \fIpage\fR tag. .PP \&\fIform\fR .PP The optional form argument allows you to encode a form in the link. .PP .Vb 5 \& Order 15oz Framing Hammer .Ve See the description of the [page] tag for more detail. .PP \&\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 3 \& Impressionist Paintings .Ve .Vb 3 \& Impressionist Paintings .Ve .Vb 2 \& Impressionist Paintings .Ve See the description of the \fIpage\fR tag for more detail. .PP \&\fIsecure\fR .PP Examples .PP \&\fBTag expansion example:\fR .PP .Vb 1 \& [area href=dir/page.html arg="arg1=AA/arg2=BB"] .Ve .Vb 2 \& www.here.com/cgi-bin/mycatalog/page.html?mv_session_id=6CZ2whqo&\e \& mv_pc=1&mv_arg=arg1%3dAA/arg2%3dBB .Ve Positional call example: .PP .Vb 1 \& Check basket .Ve Named call example: .PP .Vb 1 \& Check basket .Ve .Sh "assign" .IX Subsection "assign" Allows you to assign numeric values to preempt calculation of one or more of the following tags: .PP [handling], [salestax], [shipping], and [subtotal] .PP The assignment is persistent within a user's session until you clear it, an assigned tag will return your value instead of calculating a value. .PP Warning \- please be sure you understand the dependencies within the pricing system before using the assign tag. In particular, you must have the value mv_shipmode set to assign to shipping, and likewise you must set mv_handling to assign to handling. The salestax and subtotal settings don't require any session variables be set. .PP Summary .PP .Vb 2 \& [assign tag_name=value tag_name=value ...] \& [assign clear=1] .Ve .Vb 6 \& Attributes Description Default \& clear Clears all pending 'assign' tag assignmentsnone \& handling Assigns an override value for [handling] tagsnone \& salestax Assigns an override value for [salestax] tagsnone \& shipping Assigns an override value for [shipping] tagsnone \& subtotal Assigns an override value for [subtotal] tagsnone .Ve .Vb 3 \& Other_Characteristics \& Invalidates cache No \& Container tag No .Ve \&\fBASP-like Perl call:\fR .PP .Vb 1 \& $Tag->assign( { shipping => 2.99, } ); .Ve See Also .PP [handling], [salestax], [shipping], [subtotal], [Shipping] .PP Description .PP The assign tag allows you to assign numeric override values to one or more of the following tags: .PP [handling], [salestax], [shipping], and [subtotal] .PP An assigned tag will return your value rather than calculating its own until you clear the assignment. .PP Assignment is persistent within the user's session (unless cleared) and affects only that user. .PP Assigning an empty string clears the tag's assignment. You can also clear all pending assignments at once with the clear attribute. .PP For example, the following eliminates salestax and sets shipping to \&\f(CW$4\fR.99 regardless of weight and destination: .PP .Vb 1 \& [assign salestax=0 shipping=4.99] .Ve This restores the [salestax] tag and eliminates handling charges: .PP .Vb 1 \& [assign salestax="" handling=0] .Ve This restores the normal behavior to the [shipping] and [handling] tags: .PP .Vb 1 \& [assign clear=1] .Ve Assignment affects only the value returned by a tag. Other behavior, such as formatting for the local currency, is not affected by the assignment. .PP Note \- you will get an error in the error log (and any pending assignment for the specified tag will be cleared) if you try to assign a value other than a number or the empty string (""). .PP \&\fIclear\fR .PP Setting this to a true value clears all pending assignments (i.e., all assignable tags return to normal behavior). .PP \&\fIshipping\fR .PP This sets the total value of shipping, rounded to locale-specific fractional digits. Always active if assigned a numeric value. See the [shipping] tag for detail about rounding, etc. .PP \&\fIhandling\fR .PP This option sets the total value of handling, rounded to fractional digits. .PP \&\fBImportant note\fR .PP The [handling] tag is unlike the others in that it will be inactive (despite your assignment) unless the [value \fBmv_handling\fR] variable is true (i.e., a nonzero, non-blank value). .PP \&\fIsalestax\fR .PP This preempts the salestax calculation. The assigned value is not rounded. .PP \&\fIsubtotal\fR .PP This preempts the cart subtotal derived from prices. The assigned value is not rounded. .PP Note that you cannot assign to [total-cost] \- it will always be the sum of the four above. .PP Before using the assign tag, please be sure you understand the dependencies within the pricing system, such as the relationship between [total-cost] and assigned tags. .Sh "attr-list" .IX Subsection "attr-list" This tag is intended for use within embedded perl rather than as a standalone tag within a template (i.e., the [attr-list ...] syntax does not apply). .PP The \f(CW$Tag\fR->attr_list($template, \f(CW$hashref\fR) usage provides a shorthand for accessing values of a hash within embedded perl. It also allows you to control defaults or set up conditional values. .PP Summary .PP .Vb 1 \& $Tag->attr_list($template, $hashref) .Ve .Vb 2 \& Parameters Description Default \& hash DEFAULT_VALUE .Ve .Vb 3 \& Attributes Default \& interpolate No \& reparse Yes .Ve .Vb 5 \& Other_Characteristics \& Invalidates cache no \& Container tag NA (Though the template is technically body text) \& Has Subtags No \& Nests No .Ve \&\fBTag expansion example\fR (ASP-like Perl call): .PP .Vb 3 \& [perl tables=products] \& my %opt = ( hashref => 1, \& sql => 'select * from products', ); .Ve .Vb 1 \& my $ary_of_hash = $Db{products}->query(\e%opt); .Ve .Vb 8 \& my $template = <{/image?} \& {image:}No image available{/image:} \&
\& More body Text here \&
\&EOF .Ve .Vb 8 \& foreach my $ref (@$ary_of_hash) { \& $out .= $Tag->attr_list($template, $ref); \& } \& return $out; \& [/perl] \&--- \& os28113 - The Claw Hand Rake - Call for price \& .Ve .Vb 5 \&
\& More body Text here \&
\& os28006 - Painters Brush Set - 29.99 \& No image available .Ve .Vb 4 \&
\& More body Text here \&
\& ... .Ve Description .PP Tags an attribute list with values from a hash. Designed for use in embedded Perl. .PP Tags according to the following rules: .PP {key} .PP Inserts the value of the key for the reference. In a database query, this is the column name. .PP {key|fallback string} .PP Displays the value of {key} or if it is zero or blank, the fallback string (i.e., default). .PP {key true string} .PP Displays true string if the value of {key} is non-blank, non-zero, or displays nothing if the key is false. .PP {key?} true text {/key?} .PP Displays true text if the value of {key} is non-blank, non-zero, and nothing otherwise. .PP {key:} false text {/key:} .PP Displays false text if the value of {key} is blank or zero, and nothing otherwise. .PP \&\fIhash\fR .PP This is the hash reference whose keys will be expanded within the template (see above). .Sh "banner" .IX Subsection "banner" Implements random or rotating banner ads. See also \fIBanner/Ad rotation\fR. .PP Summary .PP .Vb 2 \& [banner category] \& [banner category=my_category other_named_attributes] .Ve .Vb 2 \& Parameters Description Default \& category default .Ve .Vb 11 \& Attributes Default \& table banner \& r_field (unweighted) rotate \& b_field banner \& separator (unweighted) ':' \& delimiter (unweighted) '{or}' \& weighted No \& once (weighted) No \& c_field (weighted) category \& w_field (weighted) weight \& interpolate (reparse) No .Ve .Vb 3 \& Other_Characteristics \& Invalidates cache No \& Container tag No .Ve \&\fBTag expansion example:\fR .PP .Vb 1 \& [banner category=my_category] .Ve \&\fBASP-like Perl call:\fR .PP .Vb 1 \& $Tag->banner( { category => $key, } ); .Ve or similarly with positional parameters, .PP .Vb 1 \& $Tag->banner($category, $attribute_hash_reference); .Ve See Also .PP \&\fIBanner/Ad rotation\fR .PP Description .PP Implements random or rotating banner ads. See \fIBanner/Ad rotation\fR in the Interchange Template documentation. .PP You will need a banner ad table (typically called 'banner') which contains banner data. The following is an example: .PP .Vb 7 \& code category weight rotate banner \& m_3 cat1 7 0 my banner 3 \& m_1 cat1 1 0 my banner 1 \& default 1 Default 1{or}Default 2{or}Default 3 \& m_2 cat1 2 0 my banner 2 \& t_1 cat2 4 0 their banner 1 \& t_2 cat2 1 0 their banner 2 .Ve \&\fIcategory\fR .PP Default: category=\*(L"default\*(R" .PP This specifies the category for weighted ad, or the table row (i.e., code value) for an unweighted ad. .PP \&\fItable\fR .PP Default: table=\*(L"banner\*(R" .PP Setting 'table=\*(L"my_banner_table\*(R"' forces the tag to refer to \&'my_banner_table' rather than the default 'banner' table for banner ad information. .PP \&\fIr_field\fR .PP Default: r_field=\*(L"rotate\*(R" .PP Unweighted ads only. .PP A table row may include multiple banners in the 'banner' column. The column specified by r_field contains a boolean that determines whether to rotate banners. In the above table example, 'Default 1', 'Default 2' and 'Default 3' would rotate. .PP \&\fIb_field\fR .PP Default: b_field=\*(L"banner\*(R" .PP This specifies the column containing the banner \fIdescriptor\fR\|(s). The default is 'banner'. Note that an entry might be a delimited list of banner descriptors to rotate (see \fIdelimiter\fR below). .PP \&\fIseparator\fR .PP Default: separator=\*(L":\*(R" .PP Unweighted ads only. .PP This sets the separator within the table key (i.e., code) for multi-level categorized ads. See \fIBanner/Ad rotation\fR. .PP \&\fIdelimiter\fR .PP Default: delimiter=\*(L"{or}\*(R" .PP Unweighted ads only. .PP This specifies the delimiter between rotating banner descriptors in the 'banner' column. .PP \&\fIweighted\fR .PP The banner tag will not apply weighting from the table unless you set weighted=1. Note that the tag will behave as if you gave it a standard unweighted entry \- it will look for a matching row rather than a matching category. .PP \&\fIonce\fR .PP Weighted ads only. .PP If the option once is passed (i.e., [banner once=1 weighted=1], then the banners will not be rebuilt until the total_weight file is removed. See \fIBanner/Ad rotation\fR. .PP \&\fIc_field\fR .PP Default: c_field=\*(L"category\*(R" .PP Weighted ads only. .PP This specifies the column containing the banner category for weighted ads. The banner tag will display ads from rows in the table whose category matches the category given in the tag, with frequency corresponding to the weights in the table. .PP \&\fIw_field\fR .PP Default: w_field=\*(L"weight\*(R" .PP Weighted ads only. .PP This specifies the column containing the banner weight. .Sh "bounce" .IX Subsection "bounce" Summary .PP Parameters: \fBhref if\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 None. This tag doesn't work with embedded Perl due to special processing. .PP .Vb 1 \& [bounce href if] .Ve .Vb 3 \& Parameters Description Default \& href DEFAULT_VALUE \& if 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 \& [bounce href if] \&--- \& TAG RESULT .Ve \&\fBASP-like Perl call:\fR .PP None. This tag doesn't work with embedded Perl due to special processing. .PP Description .PP The [bounce ...] tag is designed to send an \s-1HTTP\s0 redirect (302 status code) to the browser and redirect it to another (possibly Interchange-parsed) page. .PP It will stop \s-1ITL\s0 code execution at that point; further tags will not be run through the parser. Bear in mind that if you are inside a looping list, that list will run to completion and the [bounce] tag will not be seen until the loop is complete. .PP Example of bouncing to an Interchange parsed page: .PP .Vb 3 \& [if !scratch real_user] \& [bounce href="[area violation]"] \& [/if] .Ve Note the \s-1URL\s0 is produced by the [area ...] \s-1ITL\s0 tag. .PP Since the \s-1HTTP\s0 says the \s-1URL\s0 needs to be absolute, this one might cause a browser warning: .PP .Vb 3 \& [if value go_home] \& [bounce href="/"] \& [/if] .Ve But running something like one of the Interchange demos you can do: .PP .Vb 3 \& [if value go_home] \& [bounce href="__SERVER_NAME__/"] \& [/if] .Ve .Vb 3 \& [if value go_home] \& [bounce href="/"] \& [/if] .Ve \&\fIhref\fR .PP \&\fIif\fR .Sh "calc" .IX Subsection "calc" Calculates the value of the enclosed arithmetic expression. .PP Summary .PP .Vb 1 \& [calc] Expression [/calc] .Ve \&\fBNo parameters\fR .PP \&\fBNo attributes\fR (though you can break it if you set \&'interpolate=0') .PP .Vb 5 \& Other_Characteristics \& Invalidates cache No \& Has Subtags No \& Container tag Yes \& Nests No .Ve \&\fBASP-like Perl call:\fR .PP There is never a reason to call this tag from within Perl or \s-1ASP\s0 code. Simply do the calculation directly. .PP Description .PP Calculates the value of the enclosed arithmetic expression. .PP Use it as follows: [calc] \fIExpression\fR [/calc] .PP The enclosed region where the arguments are calculated according to normal arithmetic symbols. For instance: .PP .Vb 1 \& [calc] 2 + 2 [/calc] .Ve will expand to: .PP .Vb 1 \& 4 .Ve The [calc] tag is really the same as the [perl] tag, except that it doesn't accept arguments, interpolates surrounded Interchange tags by default, and is slightly more efficient to parse. .PP Tip: The [calc] tag will remember variable values inside one page, so you can do the equivalent of a memory store and memory recall for a loop. .PP \&\s-1ASP\s0 Note: There is never a reason to call this tag from within Perl or \&\s-1ASP\s0 code. .Sh "calcn" .IX Subsection "calcn" Calculates the value of the enclosed arithmetic expression. .PP Summary .PP .Vb 1 \& [calcn] Expression [/calcn] .Ve \&\fBNo parameters\fR .PP \&\fBNo attributes\fR .PP .Vb 5 \& Other_Characteristics \& Invalidates cache No \& Has Subtags No \& Container tag Yes \& Nests No .Ve \&\fBASP-like Perl call:\fR .PP There is never a reason to call this tag from within Perl or \s-1ASP\s0 code. Simply do the calculation directly. .PP Description .PP Equivalent to the [calc] 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. .Sh "cart" .IX Subsection "cart" 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->cart( \& { \& name => VALUE, \& } \& ) .Ve .Vb 1 \& OR .Ve .Vb 2 \& $Tag->cart($name); \& [cart 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 \& [cart name] \&--- \& TAG RESULT .Ve \&\fBASP-like Perl call:\fR .PP .Vb 2 \& $Tag->cart( { name => VALUE_name \&}, $body ); .Ve or similarly with positional parameters, .PP .Vb 1 \& $Tag->cart(name, $attribute_hash_reference, $body); .Ve Description .PP Sets the name of the current shopping cart for display of shipping, price, total, subtotal, shipping, and nitems tags. .PP \&\fIname\fR .Sh "catch" .IX Subsection "catch" The page content contained within the [catch \fIlabel\fR][/catch] block executes if the correspondingly labelled try block fails. .PP You can also return a result based on the error message caught in the try block with paired subtags, like this: .PP .Vb 1 \& [error message]body text[/error message] .Ve Note that this feature excises \fIall\fR tag/endtag pairs if interpolation is turned off, so the catch tag interpolates by default. .PP See also [try]. .PP Summary .PP .Vb 10 \& [try my_label] \& Body text to return if no error \& [/try] \& . \& . \& . \& [catch label=my_label other_named_attributes] \& [/Pattern matching error message 1/] \& Return this if error 1 occurs \& [/Pattern matching error message 1/] .Ve .Vb 3 \& [/Pattern matching error message 2/] \& Return this if error 2 occurs, etc. \& [/Pattern matching error message 2/] .Ve .Vb 2 \& Default body text to process 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 3 \& Attributes Default \& interpolate Yes \& reparse Yes .Ve .Vb 4 \& Other_Characteristics \& Invalidates cache No \& Container tag Yes \& Has Subtags [Error message text]body[/Error message text] .Ve \&\fBTag expansion example\fR .PP Ignoring whitespace, the following would return division result if successful, 0 on a division by zero, or an error message: .PP .Vb 15 \& [set divisor]0[/set] \& [try label=div] \& [perl] eval(1 / [scratch divisor]) [/perl] \& [/try] \& [catch div] \& [/Illegal division by zero/] \& 0 \& [/Illegal division by zero/] \& [/eval "string" trapped by operation mask/] \& Perl Safe error \& [/eval "string" trapped by operation mask/] \& Other division error \& [/catch] \&--- \& Perl Safe error .Ve \&\fBASP-like Perl call:\fR .PP .Vb 2 \& $Tag->catch( { label => I<'my_label'>, }, \& $body ); .Ve or similarly with positional parameters, .PP .Vb 1 \& $Tag->catch($label, $attribute_hash_reference, $body); .Ve See Also .PP \&\fItry\fR .PP .Vb 1 \& [catch] .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 \& [catch] \&--- \& TAG RESULT .Ve \&\fBASP-like Perl call:\fR .PP .Vb 2 \& $Tag->catch( { \&}, $body ); .Ve or similarly with positional parameters, .PP .Vb 1 \& $Tag->catch(, $attribute_hash_reference, $body); .Ve Description .PP The page content contained within the [catch \fIlabel\fR][/catch] block executes if the correspondingly labelled try block fails. The catch block executes in place on the page if triggered (\fIi.e.\fR, it does not return its result in place of the try block). .PP You can also return a result based on the error message caught in the try block with paired subtags, like this: .PP .Vb 1 \& [/error message/]special catch block for the error[/error message/] .Ve The error message to use in the special block will generally be part of the entry the error generates in your error log. For example, a division by zero error generates something like the following in the error log: .PP .Vb 3 \& 127.0.0.1 4cU3Pgsh:127.0.0.1 - [24/May/2001:14:45:07 -0400]\e \& tag /cgi-bin/tag72/tag Safe: Illegal division by zero\e \& at (eval 526) line 2. .Ve (note that trailing backslashes in the example indicate a continued line). .PP \&\fIlabel\fR .PP This is the label specifying the corresponding [try block. Defaults to 'default'. .Sh "cgi" .IX Subsection "cgi" Returns the the current value of the named \s-1CGI\s0 input variable. HTML-escapes Interchange tags in the result for security. .PP Can also set a new \s-1CGI\s0 value within the current page. .PP Summary .PP .Vb 2 \& [cgi name] \& [cgi name=cgi_var_name other_named_attributes] .Ve .Vb 2 \& Parameters Description Default \& name This is the name of the CGI variable whose value you want.None .Ve .Vb 7 \& Attributes Default \& set none \& hide No \& filter none \& keep (with filter) No \& enable_html No \& interpolate (reparse) No .Ve .Vb 2 \& Other_Characteristics \& Invalidates cache Yes .Ve \&\fBTag expansion example:\fR .PP Assuming \s-1CGI\s0 variable 'foo' = 'bar', .PP .Vb 3 \& [cgi foo] \&--- \& bar .Ve \&\fBASP-like Perl call:\fR .PP .Vb 1 \& $Tag->cgi( { name => var_name } ); .Ve .Vb 2 \& # or if you simply want the value: \& $CGI->{var_name}; .Ve .Vb 2 \& # or: \& $CGI::values{var_name}; .Ve or similarly with positional parameters, .PP .Vb 1 \& $Tag->cgi($name, $attribute_hash_reference); .Ve Description .PP Displays the value of a \s-1CGI\s0 variable \fBsubmitted to the current page\fR. This is similar to [value ...], except it displays the transitory values that have been submitted with the current request. .PP For instance, if you access the following \s-1URL:\s0 .PP .Vb 1 \& http://VENDURL/pagename?foo=bar .Ve bar will be substituted for [cgi foo]. .PP This is the same as \f(CW$CGI\fR->{foo} in embedded Perl. .PP \&\fIname\fR .PP This is the name of the \s-1CGI\s0 variable whose value you want. .PP \&\fIset\fR .PP You can change a value with 'set=\fInew_value\fR'. The tag will return the \s-1CGI\s0 value you set unless you also set the \fIhide\fR=1 attribute. .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 \s-1CGI\s0 variable 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 \s-1CGI\s0 value itself in the \f(CW$CGI::values\fR hash. .PP \&\fIdefault\fR .PP This sets a return value in case the named \s-1CGI\s0 variable is missing or otherwise false. The following will expand to \*(L"Using\ default\*(R": .PP .Vb 2 \& [cgi name=myname set=0 hide=1] \& [cgi 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 "checked" .IX Subsection "checked" 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->checked( \& { \& name => VALUE, \& value => VALUE, \& } \& ) .Ve .Vb 1 \& OR .Ve .Vb 2 \& $Tag->checked($name, $value, $ATTRHASH); \& [checked 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 5 \& [value name=example set=neato] \& \& \& \& .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 .Vb 4 \& \& .Ve This will output \s-1CHECKED\s0 if the variable var_name is equal to value. Not case sensitive unless the optional case=1 parameter is used. .PP The default parameter, if true (non-zero and non-blank), will cause the box to be checked if the variable has never been defined. .PP Note that \s-1CHECKBOX\s0 items will never submit their value if not checked, so the box will not be reset. You must do something like: .PP .Vb 3 \& \& [value name=foo set=""] .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 option cgi=1. .PP Use the parameter default=1 to specify that this checkbox should be marked \s-1CHECKED\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 checked, 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 "control" .IX Subsection "control" Returns named scratchpad field or copies named scratch variable to scratchpad. Returns value specified by 'default' attribute if scratchpad variable is undefined or empty. Calling without a name moves to next scratchpad. Calling without a name and 'reset=1' returns to first scratchpad page. .PP Summary .PP .Vb 1 \& [control name default other_named_attributes] .Ve .Vb 5 \& Parameters Description Default \& default Value to return if scratchpad variable missing or emptyDEFAULT_VALUE \& name Name of scratchpad variable to set or returnDEFAULT_VALUE \& reset Resets scratchpad (i.e. $::Control array) by setting special scratch variable 'control_index' to 0. Control_index is an index into the $::Control == $Vend::Session->{control} array of hashrefs.(must not specify name; may specify default)DEFAULT_VALUE \& set Copies named scratch variable (i.e., from $::Scratch) to scratchpad with current control index.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 \& [control name default] \&--- \& TAG RESULT .Ve \&\fBASP-like Perl call:\fR .PP .Vb 3 \& $Tag->control( { default => VALUE_default \& name => VALUE_name \&}, $body ); .Ve or similarly with positional parameters, .PP .Vb 1 \& $Tag->control(name,default, $attribute_hash_reference, $body); .Ve Description .PP Returns named scratchpad field or copies named scratch variable to scratchpad. Returns value specified by 'default' attribute if scratchpad variable is undefined or empty. Calling without a name moves to next scratchpad. Calling without a name and 'reset=1' returns to first scratchpad page. .PP \&\fIdefault\fR .PP Value to return if scratchpad variable missing or empty .PP \&\fIname\fR .PP Name of scratchpad variable to set or return .PP \&\fIreset\fR .PP Resets scratchpad (i.e. \f(CW$::Control\fR array) by setting special scratch variable 'control_index' to 0. Control_index is an index into the \&\f(CW$::Control\fR == \f(CW$Vend::Session\fR->{control} array of hashrefs. .Ip "\(bu" 4 (must not specify name; may specify default) .PP \&\fIset\fR .PP Copies named scratch variable (i.e., from \f(CW$::Scratch\fR) to scratchpad with current control index. .Sh "control_set" .IX Subsection "control_set" Bulk-sets scratchpad variables on the scratchpad page specified by \&'index'. Note that, unlike [control], this does not copy values from scratch. .PP Summary .PP This example sets var_one, var_two and var_three in the scratchpad on page 5 (index begins with 0). .PP .Vb 5 \& [control_set index=4] \& [var_one]var_one_value[/var_one] \& [var_two]var_two_value[/var_two] \& [var_three]var_three_value[/var_three] \& [/control_set] .Ve Parameters: \fBindex\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. [control_set] \s-1FOO\s0 [/control_set]. Nesting: \s-1NO\s0 .PP Invalidates cache: \fBno\fR .PP Called Routine: .PP \&\fBASP-like Perl call:\fR .PP .Vb 6 \& $Tag->control_set( \& { \& index => VALUE, \& }, \& BODY \& ) .Ve .Vb 1 \& OR .Ve .Vb 2 \& $Tag->control_set($index, $ATTRHASH, $BODY); \& [control_set index other_named_attributes] .Ve .Vb 2 \& Parameters Description Default \& index 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 \& [control_set index] \&--- \& TODO: (tag result) .Ve \&\fBASP-like Perl call:\fR .PP .Vb 2 \& $Tag->control_set( { index => VALUE_index \&}, $body ); .Ve or similarly with positional parameters, .PP .Vb 1 \& $Tag->control_set(index, $attribute_hash_reference, $body); .Ve Description .PP Bulk-sets scratchpad variables on the scratchpad page specified by \&'index'. Note that, unlike [control], this does not copy values from scratch. .PP \&\fIindex\fR .Sh "counter" .IX Subsection "counter" Summary .PP Parameters: \fBfile start date sql\fR .PP Positional parameters: \fBfile\fR .PP Invalidates cache: \fB\s-1YES\s0\fR .PP Called Routine: .PP \&\fBASP-like Perl call:\fR .PP .Vb 8 \& $Tag->counter( \& { \& file => VALUE, \& sql => VALUE, \& start => VALUE, \& date => 'local' || 'gmt', \& } \& ) .Ve .Vb 1 \& OR .Ve .Vb 1 \& $Tag->counter($file, $ATTRHASH); .Ve Attribute aliases .PP .Vb 2 \& name ==> file \& [counter file] .Ve .Vb 5 \& Parameters Description Default \& file DEFAULT_VALUE \& name Alias for file DEFAULT_VALUE \& sql Asserts a SQL-based counter DEFAULT_VALUE \& date Asserts a date-based counter 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 \& [counter file] \&--- \& TODO: (tag result) .Ve \&\fBASP-like Perl call:\fR .PP .Vb 1 \& $Tag->counter( { file => VALUE_file, sql => 'table:seq', start => VALUE, } ); .Ve or similarly with positional parameters, .PP .Vb 1 \& $Tag->counter(file, $attribute_hash_reference); .Ve Description .PP Manipulates a persistent counter, by default incrementing it and returning the new value. .PP The counter value is stored in the specified file. If the file name begins with a \*(L"/\*(R" then it is an absolute path. Otherwise, it is relative to VendRoot. The default file is etc/counter. If the file does not exist, it is created and initialized to the value of the start parameter. .PP If the optional sql attribute is used, a \s-1SQL\s0 sequence will be used. Currently MySQL and Postgres are supported. The sequence must already exist. If no bypass parameter is sent, the table in the sequence callout (explained below) will be used and must be an Interchange table (i.e. set up with Database setting). If bypass is set, then the \s-1DSN\s0 for the sequence will be passed in the dsn parameter. .PP If the optional date attribute is used, a date-based counter will be made. It takes the form of the date in \s-1YYYYMMDD\s0 followed by the start value, by default 0001. When the date changes, the counter will flip over to the next day and the beginning start value. .PP \&\s-1WARNING:\s0 This tag may not work under \fISafe\fR, i.e. in embedded Perl. .PP Additional parameters: .PP \&\fIdecrement=1\fR .PP Causes the counter to count down instead of up. This option is not applicable to \s-1SQL\s0 counters. .PP \&\fIstart=50\fR .PP Causes a new counter to be created and to start from 50 (for example) if it did not exist before. This option is not applicable to \s-1SQL\s0 counters. .PP \&\fIvalue=1\fR .PP Shows the value of the counter without incrementing or decrementing it. This option is not applicable to \s-1SQL\s0 counters. .PP \&\fIsql=\*(L"table:sequence\*(R"\fR .PP The table and sequence name of the \s-1SQL\s0 counter. .PP If the type of database is Postgres, the table is used to derive the database and the sequence will be a named sequence independent of the table; the sequence is incremented and accessed by \*(L"\s-1SELECT\s0 nextval('sequence_name')\*(R". .PP If the type of database is MySQL, an \s-1AUTO_INCREMENT\s0 key column is assumed and an insert of 0 followed by \*(L"select \fIlast_insert_id()\fR\*(R" will increment then access the counter. .PP \&\fIdate=\*(L"local\*(R"\fR .PP Specifies the counter will be date-based with local time. .PP \&\fIdate=\*(L"gmt\*(R"\fR .PP Specifies the counter will be date-based with \s-1GMT\s0. .PP \&\fIfile\fR .PP \&\s-1SQL\s0 Counter Examples .PP To set up a Postgres counter, simply create a named sequence in the database: .PP .Vb 1 \& CREATE SEQUENCE "foo" start 1 increment 1 maxvalue 2147483647 minvalue 1 cache 1 .Ve You will want to make sure you have an Interchange table that uses that database (\*(L"sometable\*(R" in the below example). .PP Then access it with: .PP .Vb 1 \& [counter sql="sometable:foo"] .Ve You can create as many sequences as you like. .PP To set up a MySQL counter, add a table to your MySQL database in catalog.cfg or other place like dbconf/mysql: .PP .Vb 2 \& Database sequence_name sequence_name.txt dbi:mysql:test_foundation \& Database sequence_name COLUMN_DEF "id=int NOT NULL AUTO_INCREMENT PRIMARY KEY" .Ve Make sure you set up the sequence.txt file if you want Interchange to create the table for you. Otherwise you can create the table yourself from a mysql client: .PP mysql> create table sequence_name(id int \s-1NOT\s0 \s-1NULL\s0 \s-1AUTO_INCREMENT\s0 \&\s-1PRIMARY\s0 \s-1KEY\s0); .PP Then access it with: .PP .Vb 1 \& [counter sql="sequence_name:sequence_name"] .Ve Alternatively, you can create the table without Interchange definition as long as it is in the same database as an Interchange table: .PP .Vb 1 \& mysql> create table sequence_name(id int NOT NULL AUTO_INCREMENT PRIMARY KEY); .Ve Then access it by calling the Interchange-defined table name followed by the table that has the \s-1AUTO_INCREMENT\s0 key: .PP .Vb 1 \& [counter sql="products:sequence_name"] .Ve To set up an Oracle counter, create a sequence: .PP .Vb 2 \& SQL> CREATE SEQUENCE foo START WITH 10000 INCREMENT BY 1 \& MAXVALUE 2147483647 MINVALUE 1 CACHE 2; .Ve Then access via a table already connected to Oracle, in below sometable: .PP .Vb 3 \& [counter sql="sometable:foo"] \& Database sequence_name sequence_name.txt dbi:mysql:test_foundation \& Database sequence_name COLUMN_DEF "id=int NOT NULL AUTO_INCREMENT PRIMARY KEY" .Ve Make sure you set up the sequence.txt file if you want Interchange to create the table for you. Otherwise you can create the table yourself from a mysql client: .PP mysql> create table sequence_name(id int \s-1NOT\s0 \s-1NULL\s0 \s-1AUTO_INCREMENT\s0 \&\s-1PRIMARY\s0 \s-1KEY\s0); .PP Then access it with: .PP .Vb 1 \& [counter sql="sequence_name:sequence_name"] .Ve Alternatively, you can create the table without Interchange definition as long as it is in the same database as an Interchange table: .PP .Vb 1 \& mysql> create table sequence_name(id int NOT NULL AUTO_INCREMENT PRIMARY KEY); .Ve Then access it by calling the Interchange-defined table name followed by the table that has the \s-1AUTO_INCREMENT\s0 key: .PP .Vb 1 \& [counter sql="products:sequence_name"] .Ve .Sh "currency" .IX Subsection "currency" Summary .PP Parameters: \fBconvert noformat\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. [currency] \s-1FOO\s0 [/currency]. Nesting: \s-1NO\s0 .PP Invalidates cache: \fBno\fR .PP Called Routine: .PP \&\fBASP-like Perl call:\fR .PP .Vb 7 \& $Tag->currency( \& { \& convert => VALUE, \& noformat => VALUE, \& }, \& BODY \& ) .Ve .Vb 1 \& OR .Ve .Vb 2 \& $Tag->currency($convert, $noformat, $BODY); \& [currency convert noformat] .Ve .Vb 3 \& Parameters Description Default \& convert DEFAULT_VALUE \& noformat 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 \& [currency convert noformat] \&--- \& TODO: (tag result) .Ve \&\fBASP-like Perl call:\fR .PP .Vb 3 \& $Tag->currency( { convert => VALUE_convert \& noformat => VALUE_noformat \&}, $body ); .Ve or similarly with positional parameters, .PP .Vb 1 \& $Tag->currency(convert,noformat, $attribute_hash_reference, $body); .Ve Description .PP When passed a value of a single number, formats it according to the currency specification. For instance: .PP .Vb 1 \& [currency]4[/currency] .Ve will display: .PP .Vb 1 \& 4.00 .Ve or something else depending on the \fILocale\fR and PriceCommas settings. It can contain a [calc] region. If the optional \*(L"convert\*(R" parameter is set, it will convert the value according to PriceDivide> for the current locale. If Locale is set to fr_FR, and \fIPriceDivide\fR for fr_FR is 0.167, the following sequence .PP .Vb 1 \& [currency convert=1] [calc] 500.00 + 1000.00 [/calc] [/currency] .Ve will cause the number 8.982,04 to be displayed. .PP \&\fIconvert\fR .PP \&\fInoformat\fR .Sh "data" .IX Subsection "data" Summary .PP Main Parameters: \fBtable field key\fR .PP Positional parameters in same order. .PP Additional parameters: hash foreign value .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 7 \& $Tag->data( \& { \& table => VALUE, \& field => VALUE, \& key => VALUE, \& } \& ) .Ve .Vb 1 \& OR .Ve .Vb 1 \& $Tag->data($table, $field, $key, $ATTRHASH); .Ve Attribute aliases .PP .Vb 8 \& base ==> table \& code ==> key \& col ==> field \& column ==> field \& database ==> table \& name ==> field \& row ==> key \& [data table field key other_named_attributes] .Ve .Vb 12 \& Parameters Description Default \& base Alias for table DEFAULT_VALUE \& code Alias for key DEFAULT_VALUE \& col Alias for field DEFAULT_VALUE \& column Alias for field DEFAULT_VALUE \& database Alias for table DEFAULT_VALUE \& field DEFAULT_VALUE \& hash DEFAULT_VALUE \& key DEFAULT_VALUE \& name Alias for field DEFAULT_VALUE \& row Alias for key DEFAULT_VALUE \& table 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 \& [data table field key] \&--- \& TODO: (tag result) .Ve \&\fBASP-like Perl call:\fR .PP .Vb 4 \& $Tag->data( { field => VALUE_field \& key => VALUE_key \& table => VALUE_table \&}); .Ve or similarly with positional parameters, .PP .Vb 1 \& $Tag->data(table,field,key, $attribute_hash_reference); .Ve Description .PP Syntax: [data table=db_table column=column_name key=key filter=\*(L"uc|lc|name|namecase|no_white|etc.\*(R"* append=1* foreign=\*(L"foreign_key_column\*(R"* value=\*(L"value to set to\*(R"* increment=1*] .PP Returns the value of the field in a database table, or from the session namespace. If the optional \fBvalue\fR is supplied, the entry will be changed to that value. If the option increment* is present, the field will be atomically incremented with the value in \fBvalue\fR. Use negative numbers in value to decrement. The append attribute causes the value to be appended; and finally, the filter attribute is a set of Interchange filters that are applied to the data 1) after it is read; or 2)before it is placed in the table. .PP If a DBM-based database is to be modified, it must be flagged writable on the page calling the write tag. Use [tag flag write]products[/tag] to mark the products database writable, for example. \fBThis must be done before \s-1ANY\s0 access to that table.\fR .PP In addition, the [data ...] tag can access a number of elements in the Interchange session database: .PP .Vb 17 \& accesses Accesses within the last 30 seconds \& arg The argument passed in a [page ...] or [area ...] tag \& browser The user browser string \& cybercash_error Error from last CyberCash operation \& cybercash_result Hash of results from CyberCash (access with usertag) \& host Interchange's idea of the host (modified by DomainTail) \& last_error The last error from the error logging \& last_url The current Interchange path_info \& logged_in Whether the user is logged in (add-on UserDB feature) \& pageCount Number of unique URLs generated \& prev_url The previous path_info \& referer HTTP_REFERER string \& ship_message The last error messages from shipping \& source Source of original entry to Interchange \& time Time (seconds since Jan 1, 1970) of last access \& user The REMOTE_USER string \& username User name logged in as (UserDB feature) .Ve Note: Databases will hide session values, so don't name a database \&\*(L"session\*(R". or you won't be able to use the [data ...] tag to read them. Case is sensitive, so in a pinch you could call the database \&\*(L"Session\*(R", but it would be better not to use that name at all. .PP \&\fIfield\fR .PP The name of the field whose value you want to fetch. Required unless returning the entire row in combination with the hash option. .PP \&\fIforeign\fR .PP To select a data element based on a foreign key, specify the foreign key column in this field. Allows selection of a data element or record based on a column that is not the primary key. .PP If the key is not unique, returns the first selected element. .PP From this table named \*(L"foo\*(R": .PP .Vb 5 \& sku name partno group subgroup \& AB Item 1 1 A 1 \& AC Item 2 2 A 2 \& AD Item 3 3 B 1 \& AE Item 4 4 C 1 .Ve These calls: .PP .Vb 2 \& [data table=foo col=name key=AB] \& [data table=foo col=name key=1 foreign=partno] .Ve would both return \*(L"Item 1\*(R". .PP If the foreign parameter is a hash value, a single value matching the query-by-example set up by the hash is returned. For instance, from our example table \*(L"foo\*(R", the following .PP .Vb 1 \& [data table=foo col=name key=1 foreign.group=A foreign.subgroup=2] .Ve would return \*(L"Item 2\*(R". .PP If the query needs to be optimized in a particular order, you need to use custom code or the array form of foreign. In our table \*(L"foo\*(R", the following .PP .Vb 1 \& [data table=foo col=name key=1 foreign.0="group=A" foreign.1="subgroup=2"] .Ve also returns \*(L"Item 2\*(R". .PP \&\fIhash\fR .PP The hash option causes the data tag to return its results (the entire row, if you omit the field parameter) as a reference to a hash with column names as keys into the values of the row. .PP An example: .PP .Vb 5 \& $row_hash = $Tag->data({ \& table => 'products', \& key => 'os28004', \& hash => 1, \& }); .Ve You could then access desired values this way: .PP .Vb 1 \& $out = 'Price: ' . $row_hash->{price}; .Ve \&\fIkey\fR .PP The key that identifies the row containing the \fIvalue\fR\|(s) you want to fetch. Required. .PP \&\fItable\fR .PP The name of the Interchange-defined table you want to fetch data from. Required. .Sh "default" .IX Subsection "default" Summary .PP Parameters: \fBname default\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->default( \& { \& name => VALUE, \& default => VALUE, \& } \& ) .Ve .Vb 1 \& OR .Ve .Vb 2 \& $Tag->default($name, $default, $ATTRHASH); \& [default name default other_named_attributes] .Ve .Vb 3 \& Parameters Description Default \& default DEFAULT_VALUE \& 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 \& [default name default] \&--- \& TODO: (tag result) .Ve \&\fBASP-like Perl call:\fR .PP .Vb 3 \& $Tag->default( { default => VALUE_default \& name => VALUE_name \&}, $body ); .Ve or similarly with positional parameters, .PP .Vb 1 \& $Tag->default(name,default, $attribute_hash_reference, $body); .Ve Description .PP Returns the value of the user form variable variable if it is non-empty. Otherwise returns default, which is the string \*(L"default\*(R" if there is no default supplied. Got that? This tag is \s-1DEPRECATED\s0 anyway. .PP \&\fIdefault\fR .PP \&\fIname\fR .Sh "description" .IX Subsection "description" 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 Invalidates cache: \fBno\fR .PP Called Routine: .PP \&\fBASP-like Perl call:\fR .PP .Vb 6 \& $Tag->description( \& { \& code => VALUE, \& base => VALUE, \& } \& ) .Ve .Vb 1 \& OR .Ve .Vb 2 \& $Tag->description($code, $base); \& [description code base] .Ve .Vb 3 \& Parameters Description Default \& base 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 \& [description code base] \&--- \& TODO: (tag result) .Ve \&\fBASP-like Perl call:\fR .PP .Vb 3 \& $Tag->description( { base => VALUE_base \& code => VALUE_code \&}, $body ); .Ve or similarly with positional parameters, .PP .Vb 1 \& $Tag->description(code,base, $attribute_hash_reference, $body); .Ve Description .PP Expands into the description of the product identified by code as found in the products database. This is the value of the database field that corresponds to the catalog.cfg directive DescriptionField. If there is more than one products file defined, they will be searched in order unless constrained by the optional argument \fBbase\fR. .PP This tag is especially useful for multi-language catalogs. The DescriptionField directive can be set for each locale and point to a different database field; for example desc_en for English, desc_fr for French, etc. .PP \&\fIbase\fR .PP \&\fIcode\fR .Sh "discount" .IX Subsection "discount" Summary .PP Parameters: \fBcode\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. [discount] \s-1FOO\s0 [/discount]. 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->discount( \& { \& code => VALUE, \& }, \& BODY \& ) .Ve .Vb 1 \& OR .Ve .Vb 2 \& $Tag->discount($code, $BODY); \& [discount code] .Ve .Vb 2 \& Parameters Description Default \& code 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 \& [discount code] \&--- \& TODO: (tag result) .Ve \&\fBASP-like Perl call:\fR .PP .Vb 2 \& $Tag->discount( { code => VALUE_code \&}, $body ); .Ve or similarly with positional parameters, .PP .Vb 1 \& $Tag->discount(code, $attribute_hash_reference, $body); .Ve Description .PP Product discounts can be set upon display of any page. The discounts apply only to the customer receiving them, and are of one of three types: .PP .Vb 4 \& 1. A discount for one particular item code (code/key is the item-code) \& 2. A discount applying to all item codes (code/key is ALL_ITEMS) \& 3. A discount applied after all items are totaled \& (code/key is ENTIRE_ORDER) .Ve The discounts are specified via a formula. The formula is scanned for the variables \f(CW$q\fR and \f(CW$s\fR, which are substituted for with the item \&\fIquantity\fR and \fIsubtotal\fR respectively. In the case of the item and all items discount, the formula must evaluate to a new subtotal for all items \fIof that code\fR that are ordered. The discount for the entire order is applied to the entire order, and would normally be a monetary amount to subtract or a flat percentage discount. .PP Discounts are applied to the effective price of the product, including any quantity discounts. .PP To apply a straight 20% discount to all items: .PP .Vb 1 \& [discount ALL_ITEMS] $s * .8 [/discount] .Ve or with named attributes: .PP .Vb 1 \& [discount code=ALL_ITEMS] $s * .8 [/discount] .Ve To take 25% off of only item 00\-342: .PP .Vb 1 \& [discount 00-342] $s * .75 [/discount] .Ve To subtract \f(CW$5\fR.00 from the customer's order: .PP .Vb 1 \& [discount ENTIRE_ORDER] $s - 5 [/discount] .Ve To reset a discount, set it to the empty string: .PP .Vb 1 \& [discount ALL_ITEMS][/discount] .Ve Perl code can be used to apply the discounts. Here is an example of a discount for item code 00\-343 which prices the \fIsecond\fR one ordered at 1 cent: .PP .Vb 7 \& [discount 00-343] \& return $s if $q == 1; \& my $p = $s/$q; \& my $t = ($q - 1) * $p; \& $t .= 0.01; \& return $t; \& [/discount] .Ve If you want to display the discount amount, use the [item-discount] tag. .PP .Vb 3 \& [item-list] \& Discount for [item-code]: [item-discount] \& [/item-list] .Ve Finally, if you want to display the discounted subtotal in a way that doesn't correspond to a standard Interchange tag, you can use the [calc] tag: .PP .Vb 5 \& [item-list] \& Discounted subtotal for [item-code]: [currency][calc] \& [item-price noformat] * [item-quantity] \& [/calc][/currency] \& [/item-list] .Ve \&\fIcode\fR .Sh "dump" .IX Subsection "dump" Dumps client connection information, cart contents, query value, contents of environment, session, and \s-1CGI\s0 with Data::Dumper to the page. This is useful for debugging. .PP Summary .PP No parameters. .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 4 \& $Tag->dump( \& { \& } \& ) .Ve .Vb 1 \& OR .Ve .Vb 2 \& $Tag->dump($); \& [dump] .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 \& [dump] \&--- \& TODO: (tag result) .Ve \&\fBASP-like Perl call:\fR .PP .Vb 2 \& $Tag->dump( { \&}, $body ); .Ve or similarly with positional parameters, .PP .Vb 1 \& $Tag->dump(, $attribute_hash_reference, $body); .Ve Description .PP Dumps client connection information, cart contents, query value, contents of environment, session, and \s-1CGI\s0 with Data::Dumper to the page. This is useful for debugging. .Sh "ecml" .IX Subsection "ecml" Uses \s-1ECML\s0 (Electronic Commerce Markup Language) module to map Interchange forms/userdb to \s-1ECML\s0 checkout .PP Summary .PP .Vb 1 \& [ecml name function other_named_attributes] .Ve .Vb 3 \& Parameters Description Default \& function ecml function (default = 'widget') DEFAULT_VALUE \& name 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 \& [ecml name function] \&--- \& TODO: (tag result) .Ve \&\fBASP-like Perl call:\fR .PP .Vb 3 \& $Tag->ecml( { function => VALUE_function \& name => VALUE_name \&}, $body ); .Ve or similarly with positional parameters, .PP .Vb 1 \& $Tag->ecml(name,function, $attribute_hash_reference, $body); .Ve Description .PP This package implements the \s-1ECML\s0 standard for the Interchange demo. \&\s-1ECML\s0 stands for \*(L"Electronic Commerce Modeling Language\*(R", but at this writing it is a simple standard for naming variables so that \&\*(L"electronic wallets\*(R" can pre-fill-in your checkout form based on users past purchase from other companies. .PP It translates into \s-1ECML\s0 from the following Interchange variables: .PP .Vb 55 \& ECML Interchange variable \& Ecom_BillTo_Online_Email b_email \& Ecom_BillTo_Postal_City b_city \& Ecom_BillTo_Postal_CountryCode b_country \& Ecom_BillTo_Postal_Name_First b_fname \& Ecom_BillTo_Postal_Name_Last b_lname \& Ecom_BillTo_Postal_Name_Middle b_mname \& Ecom_BillTo_Postal_Name_Prefix b_title \& Ecom_BillTo_Postal_Name_Suffix b_name_suffix \& Ecom_BillTo_Postal_PostalCode b_zip \& Ecom_BillTo_Postal_StateProv b_state \& Ecom_BillTo_Postal_Street_Line1 b_address1 \& Ecom_BillTo_Postal_Street_Line2 b_address2 \& Ecom_BillTo_Postal_Street_Line3 b_address3 \& Ecom_BillTo_Telecom_Phone_Number b_phone_day \& Ecom_ConsumerOrderID mv_o