Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/gocom/rah_repeat

Iterator tags for Textpattern CMS templates
https://github.com/gocom/rah_repeat

php textpattern textpattern-plugin

Last synced: 10 months ago
JSON representation

Iterator tags for Textpattern CMS templates

Awesome Lists containing this project

README 

          
h1. rah_repeat



"Download":https://github.com/gocom/rah_repeat/releases | "Packagist":https://packagist.org/packages/rah/rah_repeat | "Issues":https://github.com/gocom/rah_repeat/issues



Adds iterator template tags to "Textpattern CMS":https://textpattern.com. 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":https://docs.textpattern.com/tags/variable.



h2. Install



Using "Composer":https://getcomposer.org:



bc. $ composer require rah/rah_repeat



Or "download":https://github.com/gocom/rah_repeat/releases an installer package.



h2. Basics



bc. 

    ...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":https://docs.textpattern.com/tags/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@.



bc. 

    



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":https://docs.textpattern.com/tags/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.



bc. 



The above would extra each of the colors as a variable. These variables would be named as @color1@, @color2@ and @color3@. Using @@ would return @red@.



h2. 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@.



h3. rah::repeat



bc. 

    ...contained statement...



The @@ 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":https://secure.php.net/manual/en/function.range.php 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":https://docs.textpattern.com/tags/variable. 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":https://docs.textpattern.com/tags/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: @""@



h3. rah::repeat_value



bc. 

    



Rah_repeat_value a single tag, used to display a iterated value. The tag should be used inside a @@ 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"@



h3. rah::repeat_count



bc. 



Returns the number of items in the last @rah::repeat@ loop. This tag works similarly to the "search_result_count":https://docs.textpattern.com/tags/search_result_count.



h3. rah::repeat_if_first



bc. 

    

        Fist item.

    



The @@ tag is a container, and has no attributes. It's a conditional tag that checks if the current item is the first one.



h3. rah::repeat_if_last



bc. 

    

        Last item.

    



The @@ tag is a container, and has no attributes. It's a conditional tag that checks if the current item is the last one.



h2. Examples



h3. Simple usage example



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



bc. 

    A .



The above returns:



bc. 
    

        
  • A dog.
    • 

        
  • A cat.
    • 

        
  • A butterfly.
    • 




h3. Using tags as values



Let's say that you have comma separated list of items stored inside article's "custom field":https://docs.textpattern.com/tags/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:



bc. 

    



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



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



bc. 

    



Some text here.



    



Some another cool phrase here.



    



h3. Repeat inside repeat



bc. 

    

        

    



Returns two HTML lists:



bc. 
    

        
  • group1
    • 

        
  • item1
    • 

        
  • item2
    • 



    

        
  • group2
    • 

        
  • item1
    • 

        
  • item2
    • 




h3. Basic usage of the if_first and the if_last tags



With the conditional tags @@ and @@ we can test which value is the first and which is the last.



bc. 

    First: 

    Last: 

    



Returns:



bc. 
    

        
  • First: item1
    • 

        
  • item2
    • 

        
  • item3
    • 

        
  • item4
    • 

        
  • Last: item5
    • 




h3. Remove duplicate values



bc. 

    



Returns: @foo, bar, foobar@



h3. Arrange the values from lowest to highest



bc. 

    



Returns: @a, b, c@



h3. Excluding values



bc. 

    



Returns: @foobar@



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



bc. 

    



Or listing number from 0 to 10.



bc. 

    



Or values @0@, @2@, @4@, and @6@.



bc. 

    



h3. Assign variables with assign attribute



The @assign@ attribute allows exporting split values as "variables":https://docs.textpattern.com/tags/variable.



bc.. 



    Version is 1.8.0.



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



bc. 

    



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



h3. Returns number of items



bc. 



h2. Changelog



h3. Version 3.0.1 - 2023/05/21



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



h3. Version 3.0.0 - 2022/04/22



* Fixed PHP >= 8.1 compatibility.

* Now requires PHP >= 8.1.



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



h3. Version 1.1.0 - 2014/03/19



* Added: value ranges support; @@.

* Added: @@.



h3. Version 1.0.1 - 2013/05/07



* Composer package now uses "textpattern/lock":https://packagist.org/packages/textpattern/lock and "textpattern/installer":https://packagist.org/packages/textpattern/installer. The package installs to Textpattern without any extra configuration.



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



h3. Version 0.8.1 - 2012/08/25



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



h3. 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 @@.

* 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).



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



h3. Version 0.6 - 2010/05/09



* Added: @exclude@ attribute.

* Fixed: @@ tag. Issue was caused by v0.5 update.



h3. Version 0.5 - 2010/05/08



* Changed offset's default value from @unset@ to @0@.

* Added: @sort@ attribute.

* Added: @duplicates@ attribute.



h3. 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: @@.

* Added: @@.



h3. Version 0.3 - 2009/11/28



* Added: @wraptag@ attribute.

* Added: @break@ attribute.

* Added: @class@ attribute.



h3. Version 0.2 - 2009/11/23



* Added: @limit@ attribute.

* Added: @offset@ attribute.



h3. Version 0.1 - 2009/11/20



* Initial release.