rah_repeat

Download | Packagist | Issues

Adds iterator template tags to Textpattern CMS. The plugin splits provided values to smaller chunks and iterates overs, just like you would expect from a for each loop in any programming language. With the plugin you can turn a simple comma-separated list of values into advanced HTML output, or extract parts of a value as variables.

Install

Using Composer:

$ composer require rah/rah_repeat

Or download an installer package.

Basics

<rah::repeat range="min, max, step" value="value1, value2, ..." assign="variable1, variable2, ...">
    ...contained statement...
</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.

<rah::repeat value="red, blue, green" wraptag="ul" break="li">
    <rah::repeat_value />
</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.

<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

<rah::repeat value="value1, value2, ...">
    ...contained statement...
</rah::repeat>

The <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 (,). If range is set to 1, individual values can declare dash-separated value ranges, e.g. 1-5, 8, 24-81, 9, 15. Either this attribute or range is required.
Example: value="dog, cat, human" Default: ""

range
Creates a list of values containing a range of elements, or if set to boolean 1, enables the value ranges feature in the value attribute. Using range to create a list of values 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, each separated by a comma. All but step are required. If the range is set to 1, it enables similar feature in the value attribute’s individual delimiter-separated values.
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

<rah::repeat value="value1, value2, ...">
    <rah::repeat_value />
</rah::rah_repeat>

Rah_repeat_value a single tag, used to display a iterated value. The tag should be used inside a <rah::repeat><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_count

<rah::repeat_count />

Returns the number of items in the last rah::repeat loop. This tag works similarly to the search_result_count.

rah::repeat_if_first

<rah::repeat value="value1, value2, ...">
    <rah::repeat_if_first>
        Fist item.
    </rah::repeat_if_first>
</rah::repeat>

The <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

<rah::repeat value="value1, value2, ...">
    <rah::repeat_if_last>
        Last item.
    </rah::repeat_if_last>
</rah::repeat>

The <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.

<rah::repeat value="dog, cat, butterfly" wraptag="ul" break="li">
    A <rah::repeat_value />.
</rah::repeat>

The above returns:

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

Using tags as values

Let’s say that you have comma separated list of items stored inside article’s custom field. For example, list of YouTube’s video IDs (BUY6HGqYweQ, Vui-qGCfXuA, kF8I_r9XT7A, Z_2gbGXzFbs) you wish to embed to your article.

We wrap the embed code in a rah_repeat tag pair and pass the custom field hosting the video IDs to the value attribute:

<rah::repeat value='<txp:custom_field name="youtube" />'>
    <iframe width="560" height="315" src="//www.youtube.com/embed/<rah::repeat_value />" frameborder="0" allowfullscreen></iframe>
</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.

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

Repeat inside repeat

<rah::repeat value="group1|item1|item2, group2|item1|item2" break="ul">
    <rah::repeat value='<rah::repeat_value />' delimiter="|" break="li">
        <rah::repeat_value />
    </rah::repeat>
</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 <rah::repeat_if_first /> and <rah::repeat_if_last> we can test which value is the first and which is the last.

<rah::repeat value="item1, item2, item3, item4, item5" wraptag="ul" break="li">
    <rah::repeat_if_first>First: </rah::repeat_if_first>
    <rah::repeat_if_last>Last: </rah::repeat_if_last>
    <rah::repeat_value />
</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

<rah::repeat duplicates value="foo, bar, bar, foo, bar, bar, foo, foobar" break=",">
    <rah::repeat_value />
</rah::repeat>

Returns: foo, bar, foobar

Arrange the values from lowest to highest

<rah::repeat value="b, a, c" sort="regular asc" break=",">
    <rah::repeat_value />
</rah::repeat>

Returns: a, b, c

Excluding values

<rah::repeat value="foo, bar, foobar" exclude="foo, bar" break=",">
    <rah::repeat_value />
</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.

<rah::repeat range="a, z, 1">
    <rah::repeat_value />
</rah::repeat>

Or listing number from 0 to 10.

<rah::repeat range="0, 10, 1">
    <rah::repeat_value />
</rah::repeat>

Or values 0, 2, 4, and 6.

<rah::repeat range="0, 6, 2">
    <rah::repeat_value />
</rah::repeat>

Assign variables with assign attribute

The assign attribute allows exporting split values as variables.

<rah::repeat value="JavaScript, jQuery, 1.8.0" assign="language, framework, version" />

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

<if::variable name="version" value="1.8.0">
    Version is 1.8.0.
</if::variable>

Using value ranges

Value ranges can be enabled by setting range attribute to 1 instead of providing it a range. When enabled, you can use value ranges in the value attribute.

<rah::repeat value="1, 3-6, 9, 13-17" range="1" break=",">
    <rah::repeat_value />
</rah::repeat>

Returns: 1, 3, 4, 5, 6, 13, 14, 15, 16, 17.

Returns number of items

<rah::repeat value="1, 2, 67, 17" />
<rah::repeat_count />

Changelog

Version 3.0.1 – 2023/05/21

• Fixed PHP >= 8.2 compatibility. PHP 8.2 displayed deprecation errors.

Version 3.0.0 – 2022/04/22

• Fixed PHP >= 8.1 compatibility.
• Now requires PHP >= 8.1.

Version 2.0.0 – 2019/04/06

• Fixed rah::repeat_count tag.
• Registered the template tags, and offers rah::for as an alias.
• Now requires Textpattern 4.7.0 or newer.
• Now requires PHP 5.6.0 or newer.

Version 1.1.0 – 2014/03/19

• Added: value ranges support; <rah::repeat value="1, 3-6, 13-17" range="1" />.
• Added: <rah::repeat_count />.

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 <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: <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: <rah::repeat_if_first>.
• Added: <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.