loop

Summary

[loop list] ... [/loop]

Parameter	Description	Default
list	List of items to iterate through.	None
arg	Alias for list.	None
args	Alias for list.	None
acclist	Treat the list as an option list, with items in the "code=text" format.	No
delimiter	Character used to separate items in the list.	See parameter description
extended	Read Table::Editor metadata.	No
extended_only		No
file	Fill the list by reading the named file.	None
head_skip	Read column names from one of the rows at the top of the file.	0
lr	The list has multiple rows, delimited with record_delim characters.	No
more	Allow search results to be paginated.	No
object
ranges	Allow the list to contain ranges, such as "1..10".	No
record_delim	Character used to delimit rows in the list (if lr is true).	\n
search	Initiate an arbitrary search, just as you would with a one-click search.	None
quoted	Allows you to use quotes to surround list items that contain spaces.	No
hide	Suppress any output text that would ordinarily be returned from this tag. (This universal parameter was introduced with Interchange version 5.5.2.)	No
interpolate	Parse Interchange tags, included in the body text, before this container tag executes.	No
reparse	Process any Interchange tags found in the text output from this tag.	Yes

The following parameters are also available to this tag:

Parameter	Description	Default
form	Arguments for use in [more-list] URIs.	None
label	Label for use with multiple simultaneously-active search objects.	current
more_template	Override the default [more-list] display template.
prefix	Override the "PREFIX" used by the various [PREFIX-*] sub-tags.	loop
safe_data	Allow the "[" character to remain intact in returned data.	No

See the search parameters page for more parameters. Note that you must use the two-character short code, rather than the full name, with parameters listed on that page. Here is a quick list of some of the search parameters that are useful in this context:

Parameter	Description	Default
fm	Return results starting from the specified row number.	0
ml	Number of results to display on each page.	50
mm	Maximum number of results to display.	None
sp	Page that should be used to display the results.	results
st	Set to "db" for a database search or "text" for a text file search.	None

Examples

Tag usage example

[loop list="A B C"]
*[loop-code]*<br>
[/loop]

*A*
*B*
*C*

Description

Loops through the template, contained this tag's the body text, for every item in the comma-separated or space-separated list. Operates in the same fashion as the [item-list] tag, except for order-item-specific values. This tag is intended to allow you to pull multiple attributes from an item modifier, but can be useful for other tasks, such as building a pre-ordained product list on a page.

Loop lists can be nested reliably by using the "prefix=whatever" parameter. For example:

[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]
<br>
[/loop]
[/loop]

A1-X A1-Y A1-Z
A2-X A2-Y A2-Z
A3-X A3-Y A3-Z
B1-X B1-Y B1-Z
B2-X B2-Y B2-Z
B3-X B3-Y B3-Z
C1-X C1-Y C1-Z
C2-X C2-Y C2-Z
C3-X C3-Y C3-Z

You can initiate an arbitrary search with the use of the search="args" parameter, just as you would with a one-click search. For example:

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

The above will show all items with a category containing the whole word "Americana".

Ranges are accepted, when you pass a list, if you set the ranges parameter, as follows:

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

A, B, C, D, E, F,

Any Perl incrementing variable list will work, but most commonly a range would look something like "1..100". You can also mix sets. For instance, "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] container, then [more-list] and [on-match] processing (etc.) can be performed just the same as with the [query] and [search-region] tags.

A nice shortcut is available when using the [loop] tag to generate <option> lists inside HTML <select> lists, when you want the user's last selection to be chosen by default on subsequent page views. Interchange simplifies this with a sub-tag that outputs "selected="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 the following:

<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]</option>
[/loop]
</select>

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

The order in which the list is displayed can be influenced by using the [sort] pseudo-tag.

Parameters

list

Comma-separated list of items to iterate through.

The list can include ranges, such as "1..10", if the ranges parameter is true. The list will be treated as a "key=value" option list if the acclist parameter is true.

acclist

Using the acclist parameter will cause this tag to treat the list as an option list, with items in the "key=value" format, as sometimes used in product options.

The value is available with [loop-code] and the label with [loop-param label]. For instance, if the size data for product code TS-007 was set to "S=Small, M=Medium, L=Large, XL=Extra Large", then you could produce a <select> list of options like this:

[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 always be other uses for the capability, such as:

<select name="season">
[loop
acclist=1
list=|
Q1=Winter,
Q2=Spring,
Q3=Summer,
Q4=Autumn
|]<option value="[loop-code]">[loop-param label]</option>
[/loop]
</select>

delimiter

Override the column separator character.

If the lr parameter is true then the default separator is a tab character (\t).

If the lr parameter is false then the default separator is one or more commas (,) whitespace characters. The delimiter can be expressed as a regular expression, such as the default "[,\s]+" expression.

extended

Read Table::Editor metadata using this parameter's value, which is expected to be in the "view::table::key" format.

extended_only

file

Reads the list from the named file, which must be relative to the website's home directory (as specified using the Catalog global configuration directive).

If this parameter is used then the lr parameter will be set true to allow the file content to be parsed as a series of rows and columns. Set "lr=0" to override this behaviour.

head_skip

This parameter is only useful if lr and/or file is in use, and the list is filled with multiple rows.

Head_skip pulls rows off the top of the list, and uses the last row pulled to set the column names. All of the columns will be made available for use with the [loop-param] sub-tag.

lr

If this parameter is true then the list is treated as if it has multiple rows as well as multiple columns.

Rows are separated with the record_delim character ("\n" by default), and columns are separated with the delimiter character ("\t" by default).

The first column will be made available for use with the [loop-code] sub-tag. All of the columns will be made available for use with the [loop-pos] sub-tag.

object

ranges

Allow the list to contain ranges, such as "1..10", which would be taken to mean "one through ten".

Note

Ranges are parsed into individual items before the loop iteration begins. To avoid the possibility of unexpectedly large ranges, you can set a limit using the Limit tag's "option_list" setting.

record_delim

This parameter is used to override the default row separator, which is an ASCII LF character (\n), and is only used if the lr parameter is set true.

search

Initiate an arbitrary search, just as you would with a one-click search.

quoted

If your list needs to have spaces in the individual items, then surround them with double or single quotes and set this parameter true.

form

You can use this to pass one or more form variables in the pagination links of a [more-list]. For example, use form="foo=bar" to include "foo=bar", as a URI argument in each of the pagination links.

Warning

Form variables, specified using this parameter, will not be available to the [cgi] tag in the initial result set. This is because the query returns the first page directly and no pagination link will have been followed.

label

If you are setting up multiple simultaneously-active search objects within a page, then this allows you to distinguish between them. The default label is "current". Most people will not need this.

more_template

Override the default display template value, used by the [more-list] sub-tag.

prefix

Setting "prefix=foo" overrides the "PREFIX" used by the various [PREFIX-*] sub-tags, and also by the [PREFIX-quote] container.

The default "prefix" is "loop".

safe_data

Setting "safe_data=1" allows the [sql-data] and [sql-param] sub-tag (etc.) to return values containing the "[" character.

Warning

Beware of reparsing issues. You should not use "safe_data" unless you really need it and you know what you're doing.