README

一组 Twig 函数。此插件是 craft 3 插件，此插件是 craft 2 模块的更新https://github.com/carlcs/craft-helpers

安装

该插件在 Packagist 上可用，可以使用 Composer 进行安装。您也可以下载最新版本并将文件复制到 craft/plugins/helpers/。

$ composer require berraisabdelaziz/craft-helpers

文件助手

该插件提供了读取和转换 JSON、YAML、CSV 和 PHP 文件内容的功能。使用 readText 或 inline 函数，您可以将整个文件读取到字符串中。

所有函数都接受一个 path 参数，这可以是相对路径或绝对路径，也可以是文件的完整 URL。默认情况下，相对路径被视为相对于网站根目录，但可以通过 basePath 配置设置来更改。

以下是一些关于读取文件的思路

读取 SVG 文件或“可视区域” CSS 文件并将其内联到模板中
读取 Git 版本控制的 markdown 文档
从 JSON 或 YAML 文件中读取模拟数据以进行原型设计
不使用 Ajax 请求读取 Element API 端点
读取各种映射表（关键词到元素 ID，关键词到原子 CSS 类的常用集合等）

readJson( path )

读取 JSON 文件，解析并转换其内容。

path (必需) – 要读取的文件的路径。

{% for article in readJson('https://example.com/api/news') %}
    {{ article.body }}
{% endfor %}

readYaml( path )

读取 YAML 文件，解析并转换其内容。

path (必需) – 要读取的文件的路径。

{% set c = readYaml('tachyons/base.yaml') %}
<img class="{{ c.img.avatar }}" src="http://tachyons.io/img/logo.jpg" alt="avatar">

{# outputs "br-100 pa1 ba b--black-10 h3 w3" #}

readCsv( path )

读取 CSV 文件，解析并转换其内容。

path (必需) – 要读取的文件的路径。
associative (默认 true) – 是否应返回关联数组。键由第一行 CSV 提供。

{% for customer in readCsv('data/customers.csv') %}
    {{ customer['First Name'] }}
{% endfor %}

{# outputs "Paul Clara Max Thomas Simone" #}

readPhp( path )

执行 PHP 文件的返回语句并返回其值。

path (必需) – 要读取的文件的路径。

{% for element in readPhp('data/elements.php') %}
    {{ element.getUrl() }}
{% endfor %}

readText( path )

将文件内容读取到字符串中。该插件还提供了一个别名函数 inline( path )。

path (必需) – 要读取的文件的路径。

{{ readText('data/notes.md')|md }}

{{ inline('assets/svg/logo.svg') }}

{% set data = inline(url('api/elements.json')) %}
<vue-component :data="{{ data }}"></vue-component>

字符串助手

truncate( length, suffix, preserve )

截断字符串到指定长度。

length (默认 30) – 文本应截断的字符数。
suffix (默认 '…') – 截断发生时附加的字符串。
preserve (默认 true) – 确保过滤器不会拆分单词。

{{ 'This is some very long text and it is causing a lot of problems.'|truncate(30) }}

{# outputs "This is some very long text…" #}

truncateHtml( length, suffix, preserve )

这是 truncate 过滤器的版本，它可以处理 HTML 输入字符串。truncateHtml 在截断时关闭 HTML 标签。请注意，它的性能比正常 truncate 过滤器差，因此只有在需要时才使用它。

length (默认 30) – 文本应截断的字符数。
suffix (默认 '…') – 截断发生时附加的字符串。
preserve (默认 true) – 确保过滤器不会拆分单词。

{{ 'This is some <strong>very long text and it is causing a lot of problems</strong>.'|truncateHtml(30) }}

{# outputs "This is some <strong>very long text and</strong>…" #}

highlight( terms, format )

在文本中突出显示给定的术语。

terms (必需) – 要搜索的术语或术语数组。
format (默认 '<mark>\1</mark>') – 包含对找到的术语的回溯的替换字符串。默认字符串可以通过 highlightFormat 配置设置进行覆盖。

{% set terms = 'we craf'|split(' ') %}
{{ 'We just installed Craft!'|highlight(terms) }}

{# outputs "<mark>We</mark> just installed <mark>Craf</mark>t!" #}

sentenceList( and, separator )

从字符串数组生成以逗号分隔的列表，其中最后两个字符串用“和”连接。

and（默认 ', and '） – 最后两个字符串之间的分隔符（使用翻译文件进行翻译）。
separator（默认 ', '） – 其他字符串之间的分隔符。

{% set names = ['Patrick', 'Clarisse', 'Caitlin', 'Danny', 'Loretta'] %}
{{ names|sentenceList }}

{# outputs "Patrick, Clarisse, Caitlin, Danny, and Loretta" #}

titleize( ignore )

返回每个单词首字母大写的字符串。

ignore（默认 ['the', 'to', ...]） – 一组不应大写的单词。默认列表可以用titleizeIgnore配置设置覆盖。

{{ 'i like to watch television'|titleize }}

{# outputs "I Like to Watch Television" #}

collapseWhitespace

修剪字符串，并将连续的空白字符替换为单个空格。这包括制表符和换行符，以及多字节空白字符，如细空格和表意空格。

{{ '     where that  extra whitespace  might come from? '|collapseWhitespace }}

{# outputs "where that extra whitespace might come from?" #}

stripWords( wordlist, ignoreCase )

返回从给定单词列表中所有单词中去除的输入字符串。

wordlist（必需） – 应从输入字符串中去除的单词数组。
ignoreCase（默认 true） – 控制是否忽略大小写或尊重大小写。

{% set string = 'In theory it removes both the A and AN, but not the THE.' %}
{{ string|stripWords(['a', 'an']) }}

{# outputs "In theory it removes both the and , but not the THE." #}

stripPunctuation

返回去除所有标点的输入字符串。

{% set string = 'In theory it removes .,:;*# but not ßøü.' %}
{{ string|stripPunctuation }}

{# outputs "In theory it removes but not ßøü" #}

htmlEntityDecode

返回将所有HTML实体转换为相应字符的输入字符串。

{% set string = 'Ein Anf&uuml;hrungszeichen ist &lt;b&gt;fett&lt;/b&gt' %}
{{ string|htmlEntityDecode }}

{# outputs "Ein Anführungszeichen ist <b>fett</b>" #}

数字辅助工具

numbersToWords( locale )

将数字转换为其文字表示。过滤器使用Numbers_Words库生成输出。请查看其文档了解支持的编程语言列表。

locale（默认 en_US） – 设置输出语言的编程语言名称缩写。

{{ 42|numbersToWords('de') }}

{# outputs "zweiundvierzig" #}

currencyToWords( locale, currency, decPoint)

将货币值转换为文字表示。过滤器使用Numbers_Words库生成输出。请查看其文档了解支持的编程语言和货币符号列表。

locale（默认 en_US） – 设置输出语言的编程语言名称缩写。
currency（默认 ''） – 设置输出货币的国际货币符号。
decPoint（默认 null） – 小数点的分隔符。

{{ 1700.99|currencyToWords('en_US', 'EUR') }}

{# outputs "one thousand seven hundred euros ninety-nine euro-cents" #}

numeralSystem( numeralSystem, zero )

将数字（阿拉伯数字系统）转换为另一个数字系统的表示。如果应用于有理数（浮点数），则过滤器首先将其四舍五入到最接近的整数。

numeralSystem（必需） – 数字将被转换到的数字系统。您可以将其转换为罗马数字系统（'roman'、'upperRoman'或'lowerRoman'），或转换为输入数字的字母等效（'alpha'、'upperAlpha'或'lowerAlpha'）。
zero（默认 -1） – 将所有负数和零映射。将此参数设置为-1将为您提供十进制数到字母字符的映射，如下所示：-1 → -B、0 → -A、1 → A。除-1或1之外的任何其他参数值将仅将0映射到该值（即0 → myZero），并保留负数不变。

{{ 42|numeralSystem('roman') }}

{# outputs "XLII" #}

unitPrefix( system, decimals, trailingZeros, decPoint, thousandsSep, unitSep)

使用单位前缀格式化数字。

system（默认 decimal） – 要使用的预定义配置的字符串（例如，“decimal”）或自定义设置数组。
decimals（默认 1） – 小数点后的位数。
trailingZeros（默认 false） – 是否显示尾随零。
decPoint（默认 '.'）– 小数点的分隔符。
thousandsSep（默认 ''）– 千位分隔符。
unitSep（默认 ' '）– 数值与单位之间的分隔符。

{{ 72064|unitPrefix }}

{# outputs "72.1 k" #}

fractionToFloat( precision )

将分数转换为十进制数。

precision（默认 4）– 返回值四舍五入到小数点后的位数。

{{ '2/3'|fractionToFloat }}

{# outputs "0.6667" #}

floatToFraction( tolerance )

将十进制数转换为分数。

tolerance（默认 0.001）– 分数计算的允许误差。例如，0.7143 转换为 5/7 而不是 7138/9993。

{{ 0.7143|floatToFraction }}

{# outputs "5/7" #}

其他辅助工具

randomString( length, extendedChars )

生成指定长度的随机字符串。

length（默认 36）– 生成字符串的长度。
extendedChars（默认 false）– 是否使用扩展字符集。

{{ randomString(6) }}

{# outputs "mRU1wI" #}

md5( string )

生成字符串的md5哈希值。

string（必需）– 生成哈希值的字符串。

{% set string = 'Lorem ipsum dolor sit amet.' %}
{{ string|md5 }}

{# outputs "eb76f38646cca9420296bfc6731f94b5" #}

json_decode( assoc, depth, options )

解析JSON字符串。

assoc（默认 false）– 是否将对象转换为关联数组。
depth（默认 512）– 递归深度。
options（默认 null）– JSON解码选项的位掩码。

{% set json = '{"beers":["Alpirsbacher Klosterbräu","Rothaus Tannenzäpfle","Neumarkter Lammsbräu"],"whiskeys":null}' %}
{% set drinks = json|json_decode() %}

{{ drinks.beers[1] }}

{# outputs "Rothaus Tannenzäpfle" #}

setNotice( message )

将通知存储在用户的闪存数据中。

message（必需）– 信息。

{% do setNotice('My short message.') %}
{{ craft.session.getFlash('notice') }}

{# outputs "My short message." #}

setError( message )

将错误信息存储在用户的闪存数据中。

message（必需）– 信息。

{% do setError('Do panic!') %}
{{ craft.session.getFlash('error') }}

{# outputs "Do panic!" #}

设置

您可以使用在craft/config/目录中创建的helpers.php配置文件来覆盖插件默认设置。

<?php

return [
    'basePath' => getenv('BASE_PATH') ?: $_SERVER['DOCUMENT_ROOT'],
    'highlightFormat' => '<mark>\1</mark>',
    'titleizeIgnore' => ['at', 'by', 'for', 'in', 'of', 'on', 'out', 'to', 'the'],
];

basePath

代码basePath用于inline和文件读取函数。默认设置使用您的环境变量BASE_PATH的值，如果没有设置，则回退到网站根目录。您可以用类似以下方式覆盖它：CRAFT_CONFIG_PATH.'data/'。

highlightFormat

为highlight过滤器设置，用于定义如何替换匹配项。术语本身可以通过\1回引用获取。

titleizeIgnore

不应由titleize过滤器大写的单词列表。

需求

PHP 5.4+

berraisabdelaziz / craft-helpers

维护者

详细信息