4.45. loop

4.45.1. Summary

Parameters: list

Positional parameters in same order.

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

Must pass named parameter interpolate=1 to cause interpolation.

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

Invalidates cache: no

Called Routine:

ASP-like Perl call:

    NOTE: This would not usually be used with embedded Perl -- a better
    choice would normally be:

                 for(@list) { CODE }

    $Tag->loop(
        {
         list => VALUE,
        },
        BODY
    )

 OR

    $Tag->loop($list, $ATTRHASH, $BODY);

Attribute aliases

            arg ==> list
            args ==> list
    [loop list other_named_attributes]
Parameters Description Default
arg Alias for list DEFAULT_VALUE
args Alias for list DEFAULT_VALUE
list   DEFAULT_VALUE
Attributes Default
interpolate No
reparse Yes
Other_Characteristics  
Invalidates cache no
Container tag Yes
Has Subtags No
Nests No

Tag expansion example:

    [loop list]
---
    TODO: (tag result)

ASP-like Perl call:

   $Tag->loop(  { list => VALUE_list
}, $body  );

or similarly with positional parameters,

    $Tag->loop(list, $attribute_hash_reference, $body);

4.45.2. Description

Returns a string consisting of the LIST, repeated for every item in a comma-separated or space-separated list. Operates in the same fashion as the [item-list] tag, except for order-item-specific values. Intended to pull multiple attributes from an item modifier -- but can be useful for other things, like building a pre-ordained product list on a page.

Loop lists can be nested reliably in Interchange by using the prefix="tag" parameter. New syntax:

    [loop list="A B C"]
        [loop prefix=mid list="[loop-code]1 [loop-code]2 [loop-code]3"]
            [loop prefix=inner list="X Y Z"]
                [mid-code]-[inner-code]
            [/loop]
        [/loop]
    [/loop]

You can do an arbitrary search with the search="args" parameter, just as in a one-click search:

    [loop search="se=Americana/sf=category"]
        [loop-code] [loop-field title]
    [/loop]

The above will show all items with a category containing the whole world "Americana", and will work the same in both old and new syntax.

Ranges are accepted when you pass a list if you set the ranges option:

    [loop list="A..Z" ranges=1][loop-code] [/loop]

The above lists all of the characters from A to Z. Any Perl incrementing variable list will work, but most commonly a range would be something like 1..100. You can mix regular sets -- 1..5 10 20 would produce the list 1 2 3 4 5 10 20.

If you surround the repeating text section with a [list] [/list] anchor, the more-list, ml=N, and on-match / no-match processing is done just as in [query] and [search-region].

Using the acclist option will parse Interchange option lists, as used in product options. The value is available with [loop-code], the label with [loop-param label]. If the size data for SKU TS-007 was set to the string S=Small, M=Medium, L=Large, XL=Extra Large then you could produce a select list of options this way:

    [loop list="[data products size TS-007]" acclist=1]
            [on-match]<SELECT NAME=mv_order_size>[/on-match]
                [list]<OPTION VALUE="[loop-code]"> [loop-param label]</OPTION>[/list]
        [on-match]</SELECT>[/on-match]
    [/loop]

Of course the above is probably more easily produced with [accessories code=TS-007 attribute=size], but there will be other uses for the capability. For instance:

         <SELECT NAME=Season>
    [loop acclist=1
                list="
                        Q1=Winter,
                        Q2=Spring,
                        Q3=Summer,
                        Q4=Fall
                "]> <OPTION VALUE="[loop-code]"> [loop-param label]</OPTION>
    [/loop]

If your parameter list needs to have spaces in the parameters, surround them with double or single quotes and set the quoted=1 option: in product options. If the size data for SKU TS-007 was set to the string S=Small, M=Medium, L=Large, XL=Extra Large then you could produce a select list of options this way:

    [loop list="[data products size TS-007]" acclist=1]
            [on-match]<SELECT NAME=mv_order_size>[/on-match]
                [list]<OPTION VALUE="[loop-code]"> [loop-param label]</OPTION>[/list]
        [on-match]</SELECT>[/on-match]
    [/loop]

A nice shortcut is available when using [loop] to generate <OPTION> lists inside HTML <SELECT>...</SELECT> blocks, when you want the user's last selection to be chosen by default on subsequent page views. Interchange simplifies this with functions that output "SELECTED" (surrounded by appropriate whitespace) for an <OPTION> if a certain value is set to the <OPTION VALUE="...">. (It sounds more complicated than it really is.)

For example, consider:

<select name=search_cat>
[loop
        search="
                fi=cat
                st=db
                ra=yes
                rf=name
                tf=name
                un=1
        "
]
<option[selected search_cat [loop-code]>[loop-code]
[/loop]
</select>

When the user returns to the page, their last selection will be chosen as the default. (Assuming the value search_cat was set after the search, which is normally is with standard searches.)

[loop] offers the option attribute, which can give loops that parse faster and are easier to write. The following example is equivalent to the one above:

<select name=search_cat>
[loop
        option=search_cat
        search="
                fi=cat
                st=db
                ra=yes
                rf=name
                tf=name
                un=1
        "
]
<option>[loop-code]
[/loop]
</select>

It works equally well when option values are explicitly specified:

<option value="[loop-code]">So-called "[loop-code]"

See also the ictemplates documentation in the section "Checks and Selections."

4.45.2.1. [if-loop-data table column] IF [else] ELSE [/else][/if-loop-field]

Outputs the IF if the column in table is non-empty, and the ELSE (if any) otherwise.

See [if-PREFIX-data].

4.45.2.2. [if-loop-field column] IF [else] ELSE [/else][/if-loop-field]

Outputs the IF if the column in the products table is non-empty, and the ELSE (if any) otherwise. Will fall through to the first non-empty field if there are multiple ProductFiles.

See [if-PREFIX-field].

4.45.2.3. [if-loop-param param] IF [else] ELSE [/else][/if-loop-param]

Only works if you have named return fields from a search (or from a passed list with the lr=1 parameter).

Outputs the IF if the returned param is non-empty, and the ELSE (if any) otherwise.

See [if-PREFIX-param].

4.45.2.4. [if-loop-pos N] IF [else] ELSE [/else][/if-loop-pos]

Only works if you have multiple return fields from a search (or from a passed list with the lr=1 parameter).

Parameters are numbered from ordinal 0, with [loop-pos 0] being the equivalent of [loop-code].

Outputs the IF if the returned positional parameter N is non-empty, and the ELSE (if any) otherwise.

See [if-PREFIX-pos].

4.45.2.5. [loop-accessories]

Outputs an [accessories ...] item.

See [PREFIX-accessories].

4.45.2.6. [loop-change marker]

See [PREFIX-change].

4.45.2.7. [loop-code]

Evaluates to the code for the current item.

See [PREFIX-code].

4.45.2.8. [loop-data database fieldname]

Evaluates to the field name fieldname in the arbitrary database table database, for the current item.

See [PREFIX-data].

4.45.2.9. [loop-description]

Evaluates to the product description (from the products file, passed description in on-fly item, or description attribute in cart) for the current item.

See [PREFIX-description].

4.45.2.10. [loop-field fieldname]

Evaluates to the field name fieldname in the database, for the current item.

See [PREFIX-field].

4.45.2.11. [loop-increment]

Evaluates to the number of the item in the list. Used for numbering items in the list.

Starts from integer 1.

See [PREFIX-increment].

4.45.2.12. [loop-last]tags[/loop-last]

Evaluates the output of the Interchange tags encased inside, and if it evaluates to a numerical non-zero number (i.e. 1, 23, or -1) then the loop iteration will terminate. If the evaluated number is negative, then the item itself will be skipped. If the evaluated number is positive, then the item itself will be shown but will be last on the list.

      [loop-last][calc]
        return -1 if '[loop-field weight]' eq '';
        return 1 if '[loop-field weight]' < 1;
        return 0;
        [/calc][/loop-last]

If this is contained in your [loop list] and the weight field is empty, then a numerical -1 will be output from the [calc][/calc] tags; the list will end and the item will not be shown. If the product's weight field is less than 1, a numerical 1 is output. The item will be shown, but will be the last item shown.

4.45.2.13. [loop-next]tags[/loop-next]

Evaluates the output of the Interchange tags encased inside, and if it evaluates to a numerical non-zero number (i.e. 1, 23, or -1) then the loop will be skipped with no output. Example:

      [loop-next][calc][loop-field weight] < 1[/calc][/loop-next]

If this is contained in your [loop list] and the product's weight field is less than 1, then a numerical 1 will be output from the [calc][/calc] operation. The item will not be shown.

4.45.2.14. [loop-price n* noformat*]

Evaluates to the price for optional quantity n (from the products file) of the current item, with currency formatting. If the optional "noformat" is set, then currency formatting will not be applied.

4.45.2.15. list