Basics

<txp:rah_repeat range="min, max, step" value="value1, value2, ..." assign="variable1, variable2, ...">
	...contained statement...
</txp:rah_repeat>

Rah_repeat’s main job is primely iterating over values. Its iteration power can used to create lists or extract subsets of data. The plugin can come very handy when you have a custom field that contains comma-separated list of values which you want to present as a HTML list or extract as individual separate values.

The values you want to iterate over are provided to the tag with the value attribute, each individual subset value separated from each other with the delimiter, defaulting to a comma. The current value that is being iterated over can be returned using the rah_repeat_value tag, wrapped in rah_repeat block. The following would generate a HTML list from comma-separated list of red, blue, green.

<txp:rah_repeat value="red, blue, green" wraptag="ul" break="li">
	<txp:rah_repeat_value />
</txp:rah_repeat>

In addition to iterating over values and creating lists, the tag can also be used to extract values and assign each one to a variable tag. This can be done using the rah_repeat tag’s assign attribute. The attribute takes a comma-separated list of variable names that will be created, each containing one of the values.

<txp:rah_repeat value="red, blue, green" assign="color1, color2, color3" />

The above would extra each of the colors as a variable. These variables would be named as color1, color2 and color3. Using <txp:variable name="color1" /> would return red.

Tags and attributes

The plugin comes with a total of four tags. The main tag rah_repeat, a single tag rah_repeat_value, and two conditionals rah_repeat_if_first and rah_repeat_if_last.

rah_repeat

<txp:rah_repeat value="value1, value2, ...">
	...contained statement...
</txp:rah_repeat>

The <txp:rah_repeat> tag is the plugin’s main tag. It’s a container tag used for iterations. Attributes for it are as follows.

value
Sets the values that are passed to the tag. Multiple values are separated with the delimiter which by default is a comma (,). This attribute or either range is required.
Example: value="dog,cat,human" Default: ""

range
Creates a list of values containing a range of elements. Using range overrides value attribute. It works identically to PHP’s range function and uses same sequence syntax as it. The attribute’s value consists of three parts: minimum, maximum and step, which are separated by a comma. All but step are required.
Example: range="1, 10" Default: undefined

delimiter
Sets the delimiter that is used to split the provided value into a list. Default delimiter is comma (,).
Example: delimiter="|" Default: ","

assign
Assigns values as Textpattern’s variables. Takes a comma-separated list of variable names: variable1, variable2, variable3, ....
Example: assign="label, value" Default: unset

duplicates
Removes duplicate values from the list. If the attribute is set to 1, only first occurrence of the value is used and duplicates are stripped off.
Example: duplicates="1" Default: "0"

exclude
Exclude certain values from the list. The attribute takes a comma (or delimiter, if delimiter is changed) separated list of values.
Example: exclude="foo,bar" Default: undefined

trim
Trims values from extra whitespace. This can be particularly helpful if the provided values are from user-input (e.g. from an article field), or the values just have extra whitespace, and the resulting output has to be clean (i.e. used in XML, JavaScript or to a variable comparison). If you want to keep whitespace intact, you can use this attribute. By default the option is on, and values are trimmed.
Example: trim="0" Default: "1"

sort
Sorts the values. If the attribute is used, all values are rearranged to the specified order. Available options are regular (sorts without checking the type), numeric (sorts in a numeric order), string (sorts as strings) and locale_string (sorts according server’s locale settings). All the values can be followed by the sorting direction, either desc and asc. By default the option isn’t used (unset), and the values are returned in the order they were supplied.
Example: sort="regular asc" Default: ""

offset
The number of items to skip. Default is 0 (none).
Example: offset="5" Default: "0"

limit
The number of items are displayed. By default there is no limit, and all items are returned.
Example: limit="10" Default: undefined

form
Use specified form partial. By default contained statement is used instead of a form.
Example: form="price_column" Default: ""

wraptag
The (X)HTML tag (without brackets) used to wrap the output.
Example: wraptag="div" Default: ""

break
The (X)HTML tag (without brackets) or a string used to separate list items.
Example: "break="br" Default: ""

class
The (X)HTML class applied to the wraptag. Default is unset.
Example: class="plugin" Default: ""

rah_repeat_value

<txp:rah_repeat value="value1, value2, ...">
	<txp:rah_repeat_value />
</txp:rah_repeat>

Rah_repeat_value a single tag, used to display a iterated value. The tag should be used inside a <txp:rah_repeat></txp:rah_repeat> block.

escape
If set to 1, HTML and Textpattern markup are escaped, and special characters are converted to HTML entities. By default this option is off.
Example: escape="1" Default: "0"

index
If set to 1, the tag returns the iterated value’s index number. The index starts from 0.
Example: index="1" Default: "0"

rah_repeat_if_first

<txp:rah_repeat value="value1, value2, ...">
	<txp:rah_repeat_if_first>
		Fist item.
	</txp:rah_repeat_if_first>
</txp:rah_repeat>

The <txp:rah_repeat_if_first> tag is a container, and has no attributes. It’s a conditional tag that checks if the current item is the first one.

rah_repeat_if_last

<txp:rah_repeat value="value1, value2, ...">
	<txp:rah_repeat_if_last>
		Last item.
	</txp:rah_repeat_if_last>
</txp:rah_repeat>

The <txp:rah_repeat_if_last> tag is a container, and has no attributes. It’s a conditional tag that checks if the current item is the last one.

Examples

Simple usage example

This example turns simple comma separated list of dog, cat, butterfly into a HTML list.

<txp:rah_repeat value="dog, cat, butterfly" wraptag="ul" break="li">
	A <txp:rah_repeat_value />.
</txp:rah_repeat>

The above returns:

<ul>
	<li>A dog.</li>
	<li>A cat.</li>
	<li>A butterfly.</li>
</ul>

Using tags as values

As of Textpattern version 4.0.7, you can use tags inside tags.

Let’s say that you have comma separated list of items stored inside article’s custom field. For example, list of “Nameless” video service’s video IDs (ID1, ID2, ID3, ID4), and you want to embed each of those as a playable video.

We pass the custom field hosting the video IDs to rah_repeat tag (with the value attribute), and place the video player code inside the container:

<txp:rah_repeat value='<txp:custom_field name="MyCustomFieldName" />'>
	<object width="600" height="380">
		<param name="movie" value="http://example.com/v/<txp:rah_repeat_value />"></param>
		<embed src="http://example.com/v/<txp:rah_repeat_value />" width="600" height="380"></embed>
	</object>
</txp:rah_repeat>

The above code would output 4 embedded players (one for each clip), displaying the videos specified with the custom field.

Taking advantage of offset and limit attributes

First display two items, then some text between, two more items, some more text and then the rest of the items.

<txp:rah_repeat value='<txp:custom_field name="MyCustomFieldName" />' limit="2">
	<txp:rah_repeat_value />
</txp:rah_repeat>
<p>Some text here.</p>
<txp:rah_repeat value='<txp:custom_field name="MyCustomFieldName" />' offset="2" limit="4">
	<txp:rah_repeat_value />
</txp:rah_repeat>
<p>Some another cool phrase here.</p>
<txp:rah_repeat value='<txp:custom_field name="MyCustomFieldName" />' offset="4">
	<txp:rah_repeat_value />
</txp:rah_repeat>

Repeat inside repeat

<txp:rah_repeat value="group1|item1|item2, group2|item1|item2">
	<ul>
		<txp:rah_repeat value='<txp:rah_repeat_value />' delimiter="|">
			<li><txp:rah_repeat_value /></li>
		</txp:rah_repeat>
	</ul>
</txp:rah_repeat>

Returns two HTML lists:

<ul>
	<li>group1</li>
	<li>item1</li>
	<li>item2</li>
</ul>
<ul>
	<li>group2</li>
	<li>item1</li>
	<li>item2</li>
</ul>

Basic usage of the if_first and the if_last tags

With the conditional tags <txp:rah_repeat_if_first /> and <txp:rah_repeat_if_last> we can test which value is the first and which is the last.

<txp:rah_repeat value="item1, item2, item3, item4, item5" wraptag="ul" break="li">
	<txp:rah_repeat_if_first>First: </txp:rah_repeat_if_first>
	<txp:rah_repeat_if_last>Last: </txp:rah_repeat_if_last>
	<txp:rah_repeat_value />
</txp:rah_repeat>

Returns:

<ul>
	<li>First: item1</li>
	<li>item2</li>
	<li>item3</li>
	<li>item4</li>
	<li>Last: item5</li>
</ul>

Remove duplicate values

<txp:rah_repeat duplicates="1" value="foo, bar, bar, foo, bar, bar, foo, foobar">
	<txp:rah_repeat_value />
</txp:rah_repeat>

Returns: foo, bar, foobar

Arrange the values from lowest to highest

<txp:rah_repeat value="b, a, c" sort="regular asc">
	<txp:rah_repeat_value />
</txp:rah_repeat>

Returns: a, b, c

Excluding values

<txp:rah_repeat value="foo, bar, foobar" exclude="foo, bar">
	<txp:rah_repeat_value />
</txp:rah_repeat>

Returns: foobar

Using range attribute

With the range it’s possible to create a range of elements with out specifying each. For example generating list of alphabet (A-z) can be done with range.

<txp:rah_repeat range="a, z, 1">
	<txp:rah_repeat_value />
</txp:rah_repeat>

Or listing number from 0 to 10.

<txp:rah_repeat range="0, 10, 1">
	<txp:rah_repeat_value />
</txp:rah_repeat>

Or values 0, 2, 4, and 6.

<txp:rah_repeat range="0, 6, 2">
	<txp:rah_repeat_value />
</txp:rah_repeat>

Assign variables with assign attribute

The assign attribute allows exporting split values as variables.

<txp:rah_repeat value="JavaScript, jQuery, 1.8.0" assign="language, framework, version" />

<txp:variable name="language" />
<txp:variable name="framework" />

<txp:if_variable name="version" value="1.8.0">
	Version is 1.8.0.
</txp:if_variable>

Changelog

Version 1.0.1 – 2013/05/07

• Composer package now uses textpattern/lock and textpattern/installer. The package installs to Textpattern without any extra configuration.

Version 1.0.0 – 2013/04/23

• Fixed: Return a empty string instead of NULL byte on halt.
• Added: form attribute.
• Added: index attribute to the rah_repeat_value tag.
• Now requires Textpattern 4.5.0 or newer.

Version 0.8.1 – 2012/08/25

• Fixed: range attribute. It ignored any options and always created an list of 1-10.

Version 0.8 – 2012/08/24

• Fixed: made the sort attribute’s direction optional.
• Added: exclude can now take and exclude empty strings ("") and zeros (0).
• Added: range attribute. Allows generating automated lists (range="min, max, step").
• Added: assign attribute. Allows extracting values as variables.
• Added: escape attribute to <txp:rah_repeat_value />.
• Added: Support for natural ordering (sort="natural").
• Changed: Now trim is enabled by default. Previously values weren’t trimmed from white-space by default.
• Changed: Renamed locale sorting option to LOCALE_STRING.
• Changed: Order can be reversed with out re-sorting by using sort="desc".
• Now requires PHP 5.2 (or newer).

Version 0.7 – 2011/12/02

• Added: trim attribute. When set to 1, provided values are trimmed from surrounding whitespace.
• Fixed: “locale” sorting option. Previously it sorted values as a string, not by locale options.
• Changed: limit’s default to NULL. Leave limit unset if you only want offset without limit, or use a high value.
• Improved: Better offset and limit functionality. Now slices the list of values before staring to build the markup.

Version 0.6 – 2010/05/09

• Added: exclude attribute.
• Fixed: <txp:rah_repeat_if_last> tag. Issue was caused by v0.5 update.

Version 0.5 – 2010/05/08

• Changed offset’s default value from unset to 0.
• Added: sort attribute.
• Added: duplicates attribute.

Version 0.4 – 2009/11/30

• Fixed: now returns old parent global, if two tags are used inside each other, instead of defining it empty.
• Added: <txp:rah_repeat_if_first>.
• Added: <txp:rah_repeat_if_last>.

Version 0.3 – 2009/11/28

• Added: wraptag attribute.
• Added: break attribute.
• Added: class attribute.

Version 0.2 – 2009/11/23

• Added: limit attribute.
• Added: offset attribute.

Version 0.1 – 2009/11/20

• Initial release.