rah / rah_repeat
Iterator tags for Textpattern CMS templates
Fund package maintenance!
www.paypal.me/jukkasvahn
Installs: 31
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 3
Forks: 0
Open Issues: 0
Type:textpattern-plugin
Requires
- php: >=8.1.0
- textpattern/installer: *
- textpattern/lock: >=4.7.0
Requires (Dev)
- rah/mtxpc: ^0.9.0
- squizlabs/php_codesniffer: 3.*
README
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 therah_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 toLOCALE_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 to1
, 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
to0
. - 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.