README

下载 | Packagist | 问题

为 Textpattern CMS 添加迭代器模板标签。该插件将提供的值分割成更小的块并迭代，就像在任何编程语言中的 for each 循环一样。使用该插件，您可以将简单的以逗号分隔的值列表转换为高级 HTML 输出，或提取值的部分作为变量。

安装

使用 Composer

$ composer require rah/rah_repeat

或下载安装包。

基础

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

Rah_repeat 的主要任务是迭代值。其迭代能力可用于创建列表或提取数据的子集。当您有一个包含以逗号分隔的值列表的自定义字段，您想将其作为 HTML 列表呈现或将其提取为单独的值时，该插件非常有用。

要迭代的值通过具有 value 属性的标签提供，每个单独的子集值由 delimiter 分隔，默认为逗号。正在迭代的当前值可以使用 rah::repeat_value 标签返回，并包裹在 rah::repeat 块中。以下示例将生成来自逗号分隔列表 red, blue, green 的 HTML 列表。

<rah::repeat value="red, blue, green" wraptag="ul" break="li">
    <rah::repeat_value />
</rah::repeat>

除了迭代值和创建列表之外，该标签还可以用于提取值并将每个值分配给一个变量标签。这可以通过使用 rah_repeat 标签的 assign 属性来完成。该属性接受一个以逗号分隔的变量名列表，将创建每个包含一个值的变量。

<rah::repeat value="red, blue, green" assign="color1, color2, color3" />

上面的示例将每个颜色作为变量提取。这些变量的名称将分别为 color1、color2 和 color3。使用 <txp:variable name="color1" /> 将返回 red。

标签和属性

该插件包含总共四个标签。主要的 rah::repeat 标签，一个单个的 rah::repeat_value 标签，以及两个条件标签 rah::repeat_if_first 和 rah::repeat_if_last。

rah::repeat

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

<rah::repeat> 标签是插件的主要标签。它是一个容器标签，用于迭代。它的属性如下。

value
设置传递给标签的值。多个值用 delimiter 分隔，默认为逗号（,）。如果 range 设置为 1，则单个值可以声明由破折号分隔的值范围，例如 1-5, 8, 24-81, 9, 15。此属性或 range 是必需的。
示例：value="dog, cat, human" 默认：""

range
创建包含元素范围的值列表，或者如果设置为布尔值1，则在value属性中启用值范围功能。使用range创建值列表会覆盖value属性。它的工作方式与PHP的range函数相同，并使用相同的序列语法。该属性的值由三部分组成：minimum、maximum和step，每个部分之间用逗号分隔。除了step外，其他都是必需的。如果将range设置为1，则会在value属性的单个分隔值中启用类似的功能。
示例：range="1, 10" 默认：未定义

分隔符
设置用于将提供的value分割成列表的分隔符。默认分隔符是逗号（,）。
示例：delimiter="|" 默认：","

分配
将值分配为Textpattern的变量。接受以逗号分隔的变量名列表：variable1, variable2, variable3, ...。
示例：assign="label, value" 默认：unset

重复项
从列表中删除重复值。如果将属性设置为1，则仅使用值的首次出现并删除重复项。
示例：duplicates="1" 默认："0"

排除
从列表中排除某些值。该属性接受以逗号（或delimiter，如果已更改分隔符）分隔的值列表。
示例：exclude="foo,bar" 默认：未定义

修剪
修剪额外的空白。如果提供的值来自用户输入（例如，来自文章字段）或值中包含额外的空白，并且生成的输出必须干净（即在XML、JavaScript或变量比较中使用），这特别有用。如果您想保持空白不变，则可以使用此属性。默认情况下，此选项处于开启状态，并且会修剪值。
示例：trim="0" 默认："1"

排序
对值进行排序。如果使用此属性，则将所有值重新排列到指定的顺序。可用选项包括regular（不检查类型排序）、numeric（按数字顺序排序）、string（按字符串排序）和locale_string（根据服务器的区域设置排序）。所有值后都可以跟排序方向，即desc和asc。默认情况下，此选项未使用（未设置），且值将按提供的顺序返回。
示例：sort="regular asc" 默认：""

偏移量
要跳过的项目数。默认值为0（无）。
示例：offset="5" 默认："0"

限制
显示的项目数。默认情况下，没有限制，并返回所有项目。
示例：limit="10" 默认：未定义

表单
使用指定的表单部分。默认情况下，使用包含的语句而不是表单。
示例：form="price_column" 默认：""

包装标签
用于包装输出的(X)HTML标签（不带括号）。
示例：wraptag="div" 默认：""

换行
用于分隔列表项的(X)HTML标签（不带括号）或字符串。
示例："break="br" 默认：""

类
应用于wraptag的(X)HTML类。默认未设置。
示例：class="plugin" 默认：""

rah::repeat_value

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

rah_repeat_value：单个标签，用于显示迭代的值。该标签应位于 <rah::repeat><rah::repeat> 块内部。

转义
如果设置为 1，则 HTML 和 Textpattern 标记将被转义，特殊字符将被转换为 HTML 实体。默认情况下，此选项关闭。
示例： escape="1" 默认："0"

索引
如果设置为 1，则标签返回迭代值的索引号。索引从 0 开始。
示例： index="1" 默认："0"

rah::repeat_count

<rah::repeat_count />

返回最后一个 rah::repeat 循环中的项目数。此标签与 search_result_count 的工作方式类似。

rah::repeat_if_first

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

<rah::repeat_if_first> 标签是一个容器，没有属性。它是一个条件标签，用于检查当前项是否是第一个。

rah::repeat_if_last

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

<rah::repeat_if_last> 标签是一个容器，没有属性。它是一个条件标签，用于检查当前项是否是最后一个。

示例

简单使用示例

此示例将简单的以逗号分隔的列表 dog, cat, butterfly 转换为 HTML 列表。

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

以上代码返回

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

将标签作为值使用

假设您在文章的自定义字段中存储了以逗号分隔的项目列表。例如，您希望将 YouTube 视频ID列表（BUY6HGqYweQ, Vui-qGCfXuA, kF8I_r9XT7A, Z_2gbGXzFbs）嵌入到您的文章中。

我们将嵌入代码包裹在 rah_repeat 标签对中，并将包含视频ID的自定义字段传递给 value 属性

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

上述代码将输出 4 个嵌入播放器（每个剪辑一个），显示由自定义字段指定的视频。

利用 offset 和 limit 属性

首先显示两个项目，然后显示一些文本，然后是两个更多项目，然后是更多文本，最后显示其余项目。

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

重复中的重复

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

返回两个 HTML 列表

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

if_first 和 if_last 标签的基本用法

使用条件标签 <rah::repeat_if_first /> 和 <rah::repeat_if_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>

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

删除重复值

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

返回：foo, bar, foobar

按最低到最高的顺序排列值

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

返回：a, b, c

排除值

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

返回：foobar

使用 range 属性

使用 range 属性，可以创建一个不指定每个元素的元素范围。例如，可以使用范围生成字母列表（A-z）。

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

或列出从 0 到 10 的数字。

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

或值 0、2、4 和 6。

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

使用 assign 属性分配变量

assign 属性允许将分割的值导出为变量。

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

使用 value 范围

可以通过将 range 属性设置为 1 而不是提供范围来启用值范围。启用后，可以在 value 属性中使用值范围。

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

返回：1, 3, 4, 5, 6, 13, 14, 15, 16, 17。

返回项目数

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

变更日志

版本 3.0.1 – 2023/05/21

修复了 PHP >= 8.2 兼容性。 PHP 8.2 显示了弃用错误。

版本 3.0.0 – 2022/04/22

修复了 PHP >= 8.1 兼容性。
现在需要 PHP >= 8.1。

版本 2.0.0 – 2019/04/06

修复了 rah::repeat_count 标签。
注册了模板标签，并提供 rah::for 作为别名。
现在需要Textpattern 4.7.0或更高版本。
现在需要PHP 5.6.0或更高版本。

版本1.1.0 – 2014/03/19

新增：支持值范围；<rah::repeat value="1, 3-6, 13-17" range="1" />。
新增：<rah::repeat_count />。

版本1.0.1 – 2013/05/07

Composer包现在使用textpattern/lock和textpattern/installer。该包无需额外配置即可安装到Textpattern。

版本1.0.0 – 2013/04/23

修复：在停止时返回空字符串而不是NULL字节。
新增：form属性。
新增：为rah_repeat_value标签添加index属性。
现在需要Textpattern 4.5.0或更高版本。

版本0.8.1 – 2012/08/25

修复：range属性。它忽略任何选项，始终创建一个1-10的列表。

版本0.8 – 2012/08/24

修复：使sort属性的顺序可选。
新增：exclude现在可以排除空字符串("")和零(0)。
新增：range属性。允许生成自动化列表(range="min, max, step")。
新增：assign属性。允许将值作为变量提取。
新增：<rah::repeat_value />的escape属性。
新增：支持自然排序(sort="natural")。
更改：现在默认启用trim。之前默认不修剪空白符。
更改：将locale排序选项重命名为LOCALE_STRING。
更改：可以使用sort="desc"反转顺序，而无需重新排序。
现在需要PHP 5.2（或更高版本）。

版本0.7 – 2011/12/02

新增：trim属性。当设置为1时，提供的值将修剪周围的空白。
修复：“locale”排序选项。之前它按字符串排序，而不是按区域设置选项排序。
更改：将limit的默认值设置为NULL。如果您只想设置偏移量而不设置limit，请将其保留为未设置，或使用高值。
改进：更好的偏移量和limit功能。现在在开始构建标记之前先切片值列表。

版本0.6 – 2010/05/09

新增：exclude属性。
修复：<rah::repeat_if_last>标签。问题是由于v0.5更新引起的。

版本0.5 – 2010/05/08

更改偏移量的默认值从unset到0。
新增：sort属性。
新增：duplicates属性。

版本0.4 – 2009/11/30

修复：现在在两个标签嵌套使用时返回旧父全局变量，而不是将其定义为空。
新增：<rah::repeat_if_first>。
新增：<rah::repeat_if_last>。

版本0.3 – 2009/11/28

新增：wraptag属性。
新增：break属性。
新增：class属性。

版本0.2 – 2009/11/23

新增：limit属性。
新增：offset属性。

版本0.1 – 2009/11/20

初始发布。

rah / rah_repeat

维护者

详细信息