[docs] docs - jon modified ictags.sdf
docs@interchange.redhat.com
docs@interchange.redhat.com
Tue Oct 9 20:50:30 2001
User: jon
Date: 2001-10-10 00:47:34 GMT
Modified: . ictags.sdf
Log:
Clarify PREFIX-pos/param/line.
Comment out tag documentation format section (for internal use).
Give PREFIX-tags their own table of contents entries.
Revision Changes Path
1.62 +72 -63 docs/ictags.sdf
rev 1.62, prev_rev 1.61
Index: ictags.sdf
===================================================================
RCS file: /var/cvs/docs/ictags.sdf,v
retrieving revision 1.61
retrieving revision 1.62
diff -u -u -r1.61 -r1.62
--- ictags.sdf 2001/09/29 19:45:52 1.61
+++ ictags.sdf 2001/10/10 00:47:33 1.62
@@ -1,10 +1,10 @@
!init OPT_LOOK="akopia"; OPT_STYLE="manual"
-# $Id: ictags.sdf,v 1.61 2001/09/29 19:45:52 jon Exp $
+# $Id: ictags.sdf,v 1.62 2001/10/10 00:47:33 jon Exp $
!define DOC_NAME "Interchange Tags Reference"
!define DOC_TYPE ""
!define DOC_CODE "ictags"
-!define DOC_VERSION substr('$Revision: 1.61 $', 11, -2)
+!define DOC_VERSION substr('$Revision: 1.62 $', 11, -2)
!define DOC_STATUS "Draft"
!define DOC_PROJECT "Interchange"
!define DOC_URL "http://interchange.redhat.com/doc/ictags.html"
@@ -26,11 +26,11 @@
H1:Interchange Tag Reference
-Interchange functions are accessed via ITL, the Interchange Tag Language.
+Interchange functions are accessed via the Interchange Tag Language (ITL).
The pages in a catalog may be mostly HTML, but they will use ITL tags
to provide access to Interchange's functions. ITL is a superset of
MML, or Minivend Markup Language. Minivend was the predecessor to
-Interchange.
+Interchange.
These tags perform various display and modification operations for
the user session. There nearly 100 standard predefined tags, and the
@@ -39,7 +39,7 @@
This document covers Interchange versions 4.7-4.8.
-H2: Tag Syntax
+H1:Tag Syntax
ITL tags are similar to HTML in syntax, in that they accept
parameters or attributes and that there are both I<standalone> and
@@ -64,10 +64,8 @@
E<lbracket>/if]
!endblock
-We will usually call the ITL tags B<Interchange tags> or just B<tags>.
+H2:Standard Syntax
-H3: Standard Syntax
-
The most common syntax is to enclose the tag with its parameters and
attributes in C<[square brackets]>. If the tag has an end tag, the tag and
its end tag will delimit contained body text:
@@ -93,7 +91,7 @@
ending tag must match the tag (i.e., don't use
C<E<lbracket>item-list]E<nbspace>listE<nbspace>[/item_list]>).
-H4: HTML-Comment
+H2: HTML-Comment
ITL also allows you to use 'E<lt>!--[' and ']--E<gt>' as
interchangeable alternatives to plain square brackets:
@@ -120,7 +118,7 @@
E: 'E<lt>!--[value name]-->' becomes 'Bill'
E: 'E<lt>!-- [value name] -->' becomes '<!-- Bill -->'
-H5: Technical notes
+H3: Technical notes
While '<!--[' and '[' are completely interchangeable, the Interchange
parser does not replace ']-->' with ']' unless it also sees '<!--['
@@ -131,7 +129,7 @@
pages and intend to use this syntax.
-H3: HTML-Embedded
+H2: HTML-Embedded
As an alternative syntax, you can usually embed an Interchange tag as
an attribute within an HTML tag. This allows some HTML editors to
@@ -183,7 +181,7 @@
!endblock
-H3: {{CMD[id="parameters"]Named vs. Positional Parameters}}
+H2: {{CMD[id="parameters"]Named vs. Positional Parameters}}
There are two styles of supplying parameters to a tag: named and positional.
@@ -218,7 +216,7 @@
+When you need to use the output of a tag as the parameter or attribute
for another tag.
-H4: Interpolating parameters
+H3: Interpolating parameters
If you wish to use the value of a tag within a parameter of another
tag, you cannot use a positional call. You must also double-quote the
@@ -235,7 +233,7 @@
Note that the argument to B<href> ('scan') did not need to be quoted;
only the argument to B<arg>, which contained a tag, needed the quotes.
-H3: {{CMD[id="attributes"]Universal Attributes}}
+H2: {{CMD[id="attributes"]Universal Attributes}}
Universal attributes apply to all tags, though each tag specifies
its own default for the attribute. The code implementing universal
@@ -243,7 +241,7 @@
tags.
-H4: {{CMD[id="attr_interpolate"]interpolate}}
+H3: {{CMD[id="attr_interpolate"]interpolate}}
This attribute behaves differently depending on whether the tag is a
I<container> or I<standalone> tag. A container tag is one which has
@@ -306,7 +304,7 @@
E: Monday, January 1, 2001
-H4: {{CMD[id="attr_reparse"]reparse}}
+H3: {{CMD[id="attr_reparse"]reparse}}
If true ("reparse=1"), the server will process any tags in the text
output by the reparsed tag.
@@ -347,19 +345,19 @@
!endblock
-H4: {{CMD[id="attr_send"]send}}
+H3: {{CMD[id="attr_send"]send}}
Deprecated
-H3: Tag-specific Attributes
+H2: Tag-specific Attributes
Each tag may accept additional named attributes which vary from tag to
tag. Please see the entry for the tag in question for details about
tag-specific attributes.
-H3: {{CMD[id="attr_array_hash"]Attribute Arrays and Hashes}}
+H2: {{CMD[id="attr_array_hash"]Attribute Arrays and Hashes}}
Some tags allow you to pass an array or hash as the value of an
attribute. For an ordinary tag, the syntax is as follows:
@@ -396,7 +394,7 @@
properly. See the documentation for the specific tag before passing
it an attribute array or hash value.
-H4: Perl calls
+H3: Perl calls
Before passing attributes to a tag, the Interchange parser would
convert the above example to an anonymous array reference. It would
@@ -425,7 +423,7 @@
!endblock
-H2: Looping tags and Sub-tags
+H1: Looping tags and Sub-tags
{{CMD[id="subtags"]}}Certain tags are not standalone; these are the
ones that are interpreted as part of a surrounding looping tag
@@ -448,20 +446,21 @@
. E<lbracket>{{C[jump="#sub_PREFIX-filter"]PREFIX-filter}}] (like filter tag but doesn't interpolate)
. E<lbracket>{{C[jump="#sub_PREFIX-increment"]PREFIX-increment}}]
. E<lbracket>{{C[jump="#sub_PREFIX-last"]PREFIX-last}}]
-. E<lbracket>{{C[jump="#sub_PREFIX-line"]PREFIX-line}}] (tab-delimited list of parameters returned, can do tail-slice)
+. E<lbracket>{{C[jump="#sub_PREFIX-line"]PREFIX-line}}] (tab-delimited list of parameters returned)
. E<lbracket>{{C[jump="#sub_PREFIX-match"]PREFIX-match}}]
. E<lbracket>{{C[jump="#sub_PREFIX-modifier"]PREFIX-modifier}}]
. E<lbracket>{{C[jump="#sub_PREFIX-next"]PREFIX-next}}]
-. E<lbracket>{{C[jump="#sub_PREFIX-param"]PREFIX-param}}]
. E<lbracket>{{C[jump="#sub_PREFIX-options"]PREFIX-options}}]
+. E<lbracket>{{C[jump="#sub_PREFIX-param"]PREFIX-param}}]
+. E<lbracket>{{C[jump="#sub_PREFIX-pos"]PREFIX-pos}}]
. E<lbracket>{{C[jump="#sub_PREFIX-price"]PREFIX-price}}]
. E<lbracket>{{C[jump="#sub_PREFIX-quantity"]PREFIX-quantity}}]
. E<lbracket>{{C[jump="#sub_PREFIX-sub"]PREFIX-sub}}]
. E<lbracket>{{C[jump="#sub_PREFIX-subtotal"]PREFIX-subtotal}}]
. E<lbracket>{{C[jump="#sub_if-PREFIX-data"]if-PREFIX-data}}]
. E<lbracket>{{C[jump="#sub_if-PREFIX-field"]if-PREFIX-field}}]
-. E<lbracket>{{C[jump="#sub_if-PREFIX-param"]if-PREFIX-param}}]
. E<lbracket>{{C[jump="#sub_if-PREFIX-modifier"]if-PREFIX-modifier}}] (hash list only)
+. E<lbracket>{{C[jump="#sub_if-PREFIX-param"]if-PREFIX-param}}]
. E<lbracket>{{C[jump="#sub_if-PREFIX-pos"]if-PREFIX-pos}}]
. E<lbracket>{{C[jump="#sub_modifier-name"]modifier-name}}]
. E<lbracket>{{C[jump="#sub_quantity-name"]quantity-name}}]
@@ -479,8 +478,10 @@
!endblock
Sub-tag behavior is consistent among the looping tags.
+Subtags are parsed during evaluation of the enclosing loop, I<before>
+any regular tags within the loop.
-There are two types of looping lists; ARRAY and HASH.
+There are two types of looping lists: ARRAY and HASH.
An array list is the normal output of a E<lbracket>{{C[jump="#query"]query}}], a search, or a E<lbracket>{{C[jump="#loop"]loop}}]
tag. It returns from 1 to N C<return fields>, defined in the C<mv_return_fields>
@@ -542,16 +543,9 @@
> { foo => 'fooN', bar => 'barN' },
> ]
-H3: Parse Order
-
-Subtags are parsed during evaluation of the enclosing loop, I<before>
-any regular tags within the loop
-
-
+H2: E<lbracket>{{CMD[id="sub_PREFIX-accessories"]PREFIX-accessories}} arglist]
-H3: E<lbracket>{{CMD[id="sub_PREFIX-accessories"]PREFIX-accessories}} arglist]
-
Except for the usual differences that apply to all subtags (such as
parsing order), these are more or less equivalent for an array-type
N<list:>
@@ -570,7 +564,7 @@
the current item hash is passed so that a value default can be established.
-H3: E<lbracket>{{CMD[id="sub_PREFIX-alternate"]PREFIX-alternate}} N] DIVISIBLE [else] NOT DIVISIBLE [/else][/PREFIX-alternate]
+H2: E<lbracket>{{CMD[id="sub_PREFIX-alternate"]PREFIX-alternate}} N] DIVISIBLE [else] NOT DIVISIBLE [/else][/PREFIX-alternate]
Set up an alternation sequence. If the item-increment is divisible by
`N', the text will be displayed. If an `[else]NOT DIVISIBLE TEXT[/else]'
@@ -581,12 +575,11 @@
> [item-alternate 2]EVEN[else]ODD[/else][/item-alternate]
> [item-alternate 3]BY 3[else]NOT by 3[/else][/item-alternate]
-H3: E<lbracket>{{CMD[id="sub_PREFIX-calc"]PREFIX-calc}}] 2 + [item-field price] [/PREFIX-calc]
+H2: E<lbracket>{{CMD[id="sub_PREFIX-calc"]PREFIX-calc}}] 2 + [item-field price] [/PREFIX-calc]
-Calls perl via the equivalent of the [calc] [/calc] tag pair. Much
-faster to execute.
+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.
-H3: E<lbracket>{{CMD[id="sub_PREFIX-change"]PREFIX-change}}][condition] .. [/condition] TEXT [/PREFIX-change]
+H2: E<lbracket>{{CMD[id="sub_PREFIX-change"]PREFIX-change}}][condition] .. [/condition] TEXT [/PREFIX-change]
Sets up a breaking sequence that occurs when the contents of
\[condition] [/condition] change. The most common one is a category
@@ -645,19 +638,19 @@
subcategory once, while showing the name for every product. (The C< >
will prevent blanked table cells if you use a border.)
-H3: E<lbracket>{{CMD[id="sub_PREFIX-code"]PREFIX-code}}]
+H2: E<lbracket>{{CMD[id="sub_PREFIX-code"]PREFIX-code}}]
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).
-H3: E<lbracket>{{CMD[id="sub_PREFIX-data"]PREFIX-data}} table field]
+H2: E<lbracket>{{CMD[id="sub_PREFIX-data"]PREFIX-data}} table field]
Calls the column C<field> in database table C<table> for the current
\[PREFIX-code]. This may or may not be equivalent to C<[PREFIX-field field]>
depending on whether your search table is defined as one of the C<ProductFiles>.
-H3: E<lbracket>{{CMD[id="sub_PREFIX-description"]PREFIX-description}}]
+H2: E<lbracket>{{CMD[id="sub_PREFIX-description"]PREFIX-description}}]
The description of the current item, as defined in the C<catalog.cfg> directive
C<DescriptionField>. In the demo, it would be the value of the field C<description>
@@ -667,7 +660,7 @@
then the attribute C<description> will be substituted. This is useful to
supply shopping cart descriptions for on-the-fly items.
-H3: E<lbracket>{{CMD[id="sub_PREFIX-discount"]PREFIX-discount}}]
+H2: E<lbracket>{{CMD[id="sub_PREFIX-discount"]PREFIX-discount}}]
The price of the current item is calculated, and the difference between
that price and the list price (quantity one) price is output. This may have
@@ -675,12 +668,12 @@
tag along with quantity pricing.
-H3: E<lbracket>{{CMD[id="sub_PREFIX-discount_subtotal"]PREFIX-discount_subtotal}}]
+H2: E<lbracket>{{CMD[id="sub_PREFIX-discount_subtotal"]PREFIX-discount_subtotal}}]
Inserts the discounted subtotal of the ordered items.
-H3: E<lbracket>{{CMD[id="sub_PREFIX-field"]PREFIX-field}}]
+H2: E<lbracket>{{CMD[id="sub_PREFIX-field"]PREFIX-field}}]
Looks up a field value for the current item in one of several places,
in this order:
@@ -705,10 +698,11 @@
Unless C<foo> is in C<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 C<[loop-data foo foo_field]>, which specifically
-addresses the table C<foo>.
+addresses the table C<foo>. See also E<lbracket>{{C[jump="#sub_PREFIX-param"]PREFIX-param}}]>
+and E<lbracket>{{C[jump="#sub_PREFIX-pos"]PREFIX-pos}}]>.
-H3: E<lbracket>{{CMD[id="sub_PREFIX-increment"]PREFIX-increment}}]
+H2: E<lbracket>{{CMD[id="sub_PREFIX-increment"]PREFIX-increment}}]
The current count on the list, starting from either 1 in a zero-anchored
list like E<lbracket>{{C[jump="#loop"]loop}}] or E<lbracket>{{C[jump="#item_list"]item-list}}], or from the match count in a
@@ -717,32 +711,44 @@
If you skip items with [PREFIX-last] or [PREFIX-next], the count is NOT
adjusted.
-H3: E<lbracket>{{CMD[id="sub_PREFIX-last"]PREFIX-last}}] CONDITION [/PREFIX-last]
+H2: E<lbracket>{{CMD[id="sub_PREFIX-last"]PREFIX-last}}] CONDITION [/PREFIX-last]
If CONDITION evaluates true (a non-whitespace value that is not specifically
zero) then this will be the last item displayed.
+
+H2: E<lbracket>{{CMD[id="sub_PREFIX-line"]PREFIX-line}} start_column]
+
+Returns all array values from the current looping row in a single string, with each value separated by a tab, roughly equivalent to this:
+
+> [PREFIX-pos 0](tab)[PREFIX-pos 1](tab)[PREFIX-pos 2](tab)[...]
+
+for however many fields were returned in that row.
-H3: E<lbracket>{{CMD[id="sub_PREFIX-modifier"]PREFIX-modifier}} attribute]
+This is useful as a quick way to see all your results at a glance and verify your search specification.
+If the optional C<start_column> attribute is given, the output starts with that column instead of column 0.
+
+H2: E<lbracket>{{CMD[id="sub_PREFIX-modifier"]PREFIX-modifier}} attribute]
+
If the item is a hash list (i.e. [item-list]), this will return the value
of the C<attribute>.
-H3: E<lbracket>{{CMD[id="sub_PREFIX-next"]PREFIX-next}}] CONDITION [/PREFIX-next]
+H2: E<lbracket>{{CMD[id="sub_PREFIX-next"]PREFIX-next}}] CONDITION [/PREFIX-next]
If CONDITION evaluates true (a non-whitespace value that is not specifically
zero) then this item is skipped.
-H3: E<lbracket>{{CMD[id="sub_PREFIX-param"]PREFIX-param}} name]
+H2: E<lbracket>{{CMD[id="sub_PREFIX-param"]PREFIX-param}} name]
-H3: E<lbracket>{{CMD[id="sub_PREFIX-param"]PREFIX-pos}} N]
+H2: E<lbracket>{{CMD[id="sub_PREFIX-param"]PREFIX-pos}} N]
-Returns the array parameter associated with the looping tag row. Each
+Returns the value of the array parameter associated with the looping tag row. Each
looping list returns an array of C<return fields>, set in searches with
C<mv_return_field> or C<rf>. The default is only to return the code of
-the search result, but by setting those parameters you can return more
-than one item.
+the search result, but by setting those parameters you can return
+whichever columns you wish.
-E<lbracket>PREFIX-pos N] outputs the I<N>th field as returned; E<lbracket>PREFIX-param] returns it by name.
+E<lbracket>PREFIX-pos N] outputs the data from the I<N>th field as returned (starting with 0); E<lbracket>PREFIX-param] lets you access the data by field name instead of number.
In a E<lbracket>query ...] ITL tag you can select multiple return fields with
something like:
@@ -756,25 +762,25 @@
Another synonym is [prefix-pos 0]; and [prefix-pos 1] is the same
as [prefix-param bar].
-H3: E<lbracket>{{CMD[id="sub_PREFIX-price"]PREFIX-price}}]
+H2: E<lbracket>{{CMD[id="sub_PREFIX-price"]PREFIX-price}}]
-The price of the current code, formatted for currency. If
+The price of the product identified by the current code, formatted for currency. If
Interchange's pricing routines cannot determine the price (i.e. it is not
a valid product or on-the-fly item) then zero is returned. If the list
is a hash list, the price will be modified by its C<quantity> or other
applicable attributes (like C<size> in the demo).
-H3: E<lbracket>{{CMD[id="sub_PREFIX-quantity"]PREFIX-quantity}}]
+H2: E<lbracket>{{CMD[id="sub_PREFIX-quantity"]PREFIX-quantity}}]
The value of the C<quantity> attribute in a hash list. Most commonly
used to display the quantity of an item in a shopping cart [item-list].
-H3: E<lbracket>{{CMD[id="sub_PREFIX-subtotal"]PREFIX-subtotal}}]
+H2: E<lbracket>{{CMD[id="sub_PREFIX-subtotal"]PREFIX-subtotal}}]
The [PREFIX-quantity] times the [PREFIX-price]. This does take discounts
into effect.
-H3: E<lbracket>{{CMD[id="sub_if-PREFIX-data"]if-PREFIX-data}} table field] IF text [else] ELSE text [/else] [/if-PREFIX-data]
+H2: E<lbracket>{{CMD[id="sub_if-PREFIX-data"]if-PREFIX-data}} table field] IF text [else] ELSE text [/else] [/if-PREFIX-data]
Examines the data field, i.e. [PREFIX-data table field], and if it is
non-blank and non-zero then the C<IF text> will be returned. If it is false,
@@ -788,11 +794,11 @@
Careful, a space is not a false value!
-H3: E<lbracket>{{CMD[id="sub_if-PREFIX-field"]if-PREFIX-field}} field] IF text [else] ELSE text [/else] [/if-PREFIX-field]
+H2: E<lbracket>{{CMD[id="sub_if-PREFIX-field"]if-PREFIX-field}} field] IF text [else] ELSE text [/else] [/if-PREFIX-field]
Same as [if-PREFIX-data ...] except uses the same data rules as C<[PREFIX-field]>.
-H3: E<lbracket>{{CMD[id="sub_modifier-name"]modifier-name}} attribute]
+H2: E<lbracket>{{CMD[id="sub_modifier-name"]modifier-name}} attribute]
Outputs a variable name which will set an appropriate variable name for setting
the attribute in a form (usually a shopping cart). Outputs for successive items
@@ -804,7 +810,7 @@
etc.
-H3: E<lbracket>{{CMD[id="sub_quantity-name"]quantity-name}}]
+H2: E<lbracket>{{CMD[id="sub_quantity-name"]quantity-name}}]
Outputs for successive items in the list:
@@ -12025,6 +12031,7 @@
(dbdump=1). Will skip empty fields if this attribute is set true.
+!block comment
A1: Tag Entry Format
@@ -12153,6 +12160,8 @@
A4: {{CMD[id="dummy_other"]other}}
'other' is another named attribute that applies to this tag.
+
+!endblock
A1: Template Parsing Order