Iterations plugin for Textpattern

Installs: 26

Dependents: 0

Stars: 3

Watchers: 1

Type: textpattern-plugin

1.1.0 2014-03-19 10:39 UTC


Download | Packagist | Twitter | GitHub | Support forum | Donate

Rah_repeat is a Textpattern CMS plugin used for iterations. The plugin splits a provided value 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.


Using Composer:

$ composer require rah/rah_repeat:*

Or download a plugin package.


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

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

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.


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

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.

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: ""

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

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

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

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

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"

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: ""

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

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

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

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

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

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


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

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.

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"

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


<txp:rah_repeat_count />

Returns the number of items in the last rah_repeat loop. This tag works similarly to the search_result_count.


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

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.


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

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.


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

The above returns:

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

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:

<txp:rah_repeat value='<txp:custom_field name="youtube" />'>
    <iframe width="560" height="315" src="//www.youtube.com/embed/<txp:rah_repeat_value />" frameborder="0" allowfullscreen></iframe>

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

Repeat inside repeat

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

Returns two HTML lists:


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


    <li>First: item1</li>
    <li>Last: item5</li>

Remove duplicate values

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

Returns: foo, bar, foobar

Arrange the values from lowest to highest

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

Returns: a, b, c

Excluding values

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

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

Or listing number from 0 to 10.

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

Or values 0, 2, 4, and 6.

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

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.

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.

<txp:rah_repeat value="1, 3-6, 9, 13-17" range="1" break=",">
    <txp:rah_repeat_value />

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

Returns number of items

<txp:rah_repeat value="1, 2, 67, 17" />
<txp:rah_repeat_count />


Version 1.1.0 – 2014/03/19

  • Added: value ranges support; <txp:rah_repeat value="1, 3-6, 13-17" range="1" />.
  • Added: <txp:rah_repeat_count />.

Version 1.0.1 – 2013/05/07

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.