Филтри за Latte

Филтрите са функции, които променят или форматират данните в желаната от нас форма. Това е кратко описание на наличните вградени филтри.

Съществуват и филтри за ескапиране за HTML (escapeHtml и escapeHtmlComment), XML (escapeXml), JavaScript (escapeJs), CSS (escapeCss) и iCalendar (escapeICal), които Latte използва сам благодарение на контекстно-осъзнатото ескапиране и не е необходимо да ги пишете.

Latte проверява атрибутите src и href автоматично, така че почти не е необходимо да използвате филтъра checkUrl.

Всички вградени филтри работят с низове, кодирани в UTF-8.

Употреба

Latte позволява извикване на филтри чрез използване на знака за тръба (позволен е предхождащ интервал):

<h1>{$heading|upper}</h1>

Филтрите могат да бъдат верижно свързани, като в този случай се прилагат в ред от ляво на дясно:

<h1>{$heading|lower|capitalize}</h1>

Параметрите се поставят след името на филтъра, разделени с двоеточие или запетая:

<h1>{$heading|truncate:20,''}</h1>

Филтрите могат да се прилагат върху изрази:

{var $name = ($title|upper) . ($subtitle|lower)}</h1>

Потребителски филтри могат да бъдат регистрирани по този начин:

$latte = new Latte\Engine;
$latte->addFilter('shortify', fn(string $s, int $len = 10) => mb_substr($s, 0, $len));

Използваме го в шаблон по следния начин:

<p>{$text|shortify}</p>
<p>{$text|shortify:100}</p>

Филтри

batch (int length, mixed item): array

Филтър, който опростява изписването на линейни данни под формата на таблица. Връща масив от масиви със зададения брой елементи. Ако предоставите втори параметър, той се използва за попълване на липсващите елементи на последния ред.

{var $items = ['a', 'b', 'c', 'd', 'e']}
<table>
{foreach ($items|batch: 3, 'No item') as $row}
	<tr>
		{foreach $row as $column}
			<td>{$column}</td>
		{/foreach}
	</tr>
{/foreach}
</table>

Отпечатва:

<table>
	<tr>
		<td>a</td>
		<td>b</td>
		<td>c</td>
	</tr>
	<tr>
		<td>d</td>
		<td>e</td>
		<td>No item</td>
	</tr>
</table>

breakLines

Вмъква прекъсванията на HTML редове преди всички нови редове.

{var $s = "Text & with \n newline"}
{$s|breakLines}    {* списъци "Text & with <br>\n newline" *}

bytes (int precision = 2)

Форматира размера в байтове в удобна за четене от човека форма.

{$size|bytes}     0 B, 1.25 GB, …
{$size|bytes:0}   10 B, 1 GB, …

ceil (int precision = 0)

Закръгляне на число до зададена точност.

{=3.4|ceil}         {* изходи 4 *}
{=135.22|ceil:1}    {* изходи 135.3 *}
{=135.22|ceil:3}    {* изходи 135.22 *}

Вижте също floor, round.

capitalize

Връща версия на стойността, изписана със заглавие. Думите започват с главни букви, а всички останали символи са малки. Изисква PHP разширение mbstring.

{='i like LATTE'|capitalize} {* списъци 'I Like Latte' *}

Вижте също firstUpper, lower, upper.

checkUrl

Принуждава URL адреса да се почиства. Той проверява дали променливата съдържа уеб URL адрес (т.е. протокол HTTP/HTTPS) и предотвратява записването на връзки, които могат да представляват риск за сигурността.

{var $link = 'javascript:window.close()'}
<a data-href="{$link|checkUrl}">checked</a>
<a data-href="{$link}">unchecked</a>

Отпечатва:

<a data-href="">checked</a>
<a data-href="javascript:window.close()">unchecked</a>

Вижте също nocheck.

clamp (int|float min, int|float max)

Връща стойността, която е вкарана в обхват от min и max.

{$level|clamp: 0, 255}

Съществува и като clamp.

dataStream (string mimetype = detect)

Конвертира съдържанието в схема URI за данни. Може да се използва за вмъкване на изображения в HTML или CSS, без да е необходимо да се свързват външни файлове.

Нека имаме изображение в променлива $img = Image::fromFile('obrazek.gif'), тогава

<img src="{$img|dataStream}">

Отпечатва например:

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA
AAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO
9TXL0Y4OHwAAAABJRU5ErkJggg==">

Изисква PHP разширение fileinfo.

date (string format)

Връща дата в зададен формат, като използва опциите на функциите strftime или date на PHP. Филтърът получава датата като времеви печат на UNIX, низ или обект от тип DateTime.

{$today|date:'%d.%m.%Y'}
{$today|date:'j. n. Y'}

escapeUrl

Избягва променлива, която да се използва като параметър в URL.

<a href="http://example.com/{$name|escapeUrl}">{$name}</a>

Вижте също query.

explode (string separator = '')

Разделя низ по зададения разделител и връща масив от низове. Псевдоним за split.

{='one,two,three'|explode:','}    {* returns ['one', 'two', 'three'] *}

Ако разделителят е празен низ (стойност по подразбиране), входът ще бъде разделен на отделни символи:

{='123'|explode}                  {* returns ['1', '2', '3'] *}

Можете да използвате и псевдонима split:

{='1,2,3'|split:','}              {* returns ['1', '2', '3'] *}

Вижте също implode.

first

Връща първия елемент от масив или символ от низ:

{=[1, 2, 3, 4]|first}    {* outputs 1 *}
{='abcd'|first}          {* outputs 'a' *}

Вижте също last, random.

floor (int precision = 0)

Закръгляне на число до зададена точност.

{=3.5|floor}        {* outputs 3      *}
{=135.79|floor:1}   {* outputs 135.7  *}
{=135.79|floor:3}   {* outputs 135.79 *}

Вижте също ceil, round.

firstUpper

Преобразува първата буква на стойността в главна буква. Изисква PHP разширение mbstring.

{='the latte'|firstUpper}  {* outputs 'The latte' *}

Вижте също capitalize, lower, upper.

implode (string glue = '')

Връща низ, който е конкатенация на низовете в масива. Псевдоним за join.

{=[1, 2, 3]|implode}      {* outputs '123' *}
{=[1, 2, 3]|implode:'|'}  {* outputs '1|2|3' *}

Можете също така да използвате псевдонима join:

{=[1, 2, 3]|join}         {* outputs '123' *}

indent (int level = 1, string char = "\t")

Отстъпва текста отляво с даден брой табулации или други символи, които посочваме във втория незадължителен аргумент. Празните редове не се отдръпват.

<div>
{block |indent}
<p>Hello</p>
{/block}
</div>

Отпечатва:

<div>
	<p>Hello</p>
</div>

last

Връща последния елемент от масив или символ от низ:

{=[1, 2, 3, 4]|last}    {* outputs 4 *}
{='abcd'|last}          {* outputs 'd' *}

Вижте също first, random.

length

Връща дължината на низ или масив.

• За низове връща дължина в UTF-8 символи.
• за масиви ще върне броя на елементите.
• за обекти, които имплементират интерфейса Countable, ще се използва върнатата стойност на функцията count()
• за обекти, които реализират интерфейса IteratorAggregate, ще се използва върнатата стойност на iterator_count()

{if ($users|length) > 10}
	...
{/if}

lower

Преобразува стойността в малки букви. Изисква PHP разширение mbstring.

{='LATTE'|lower}   {* outputs 'latte' *}

Вижте също capitalize, firstUpper, upper.

nocheck

Предотвратява автоматичното почистване на URL адреси. Latte автоматично проверява дали променливата съдържа уеб URL адрес (т.е. протокол HTTP/HTTPS) и предотвратява записването на връзки, които могат да представляват риск за сигурността.

Ако връзката използва друга схема, например javascript: или data:, и сте сигурни в нейното съдържание, можете да деактивирате проверката чрез |nocheck.

{var $link = 'javascript:window.close()'}

<a href="{$link}">checked</a>
<a href="{$link|nocheck}">unchecked</a>

Отпечатъци:

<a href="">checked</a>
<a href="javascript:window.close()">unchecked</a>

Вижте също checkUrl.

noescape

Деактивира автоматичното ескапиране.

{var $trustedHtmlString = '<b>hello</b>'}
Escaped: {$trustedHtmlString}
Unescaped: {$trustedHtmlString|noescape}

Отпечатва:

Escaped: <b>hello</b>
Unescaped: <b>hello</b>

Злоупотребата с филтъра noescape може да доведе до уязвимост XSS! Никога не го използвайте, освен ако не сте напълно сигурни какво правите и че низът, който отпечатвате, идва от надежден източник.

number (int decimals = 0, string decPoint = '.', string thousandsSep = ',')

Форматира число до зададен брой знаци след десетичната запетая. Можете също така да зададете символ на десетичната запетая и разделителя за хиляди.

{1234.20 |number}              1,234
{1234.20 |number:1}            1,234.2
{1234.20 |number:2}            1,234.20
{1234.20 |number:2, ',', ' '}  1 234,20

padLeft (int length, string pad = ' ')

Попълва низ с определена дължина с друг низ отляво.

{='hello'|padLeft: 10, '123'}  {* outputs '12312hello' *}

padRight (int length, string pad = ' ')

Подвежда низ до определена дължина с друг низ отдясно.

{='hello'|padRight: 10, '123'}  {* outputs 'hello12312' *}

query

Динамично генерира низ за заявка в URL адреса:

<a href="http://example.com/?{[name: 'John Doe', age: 43]|query}">click</a>
<a href="http://example.com/?search={$search|query}">search</a>

Отпечатва:

<a href="http://example.com/?name=John+Doe&amp;age=43">click</a>
<a href="http://example.com/?search=Foo+Bar">search</a>

Ключовете със стойност null се изпускат.

Вижте също escapeUrl.

random

Връща произволен елемент от масив или символ от низ:

{=[1, 2, 3, 4]|random}    {* example output: 3 *}
{='abcd'|random}          {* example output: 'b' *}

Вижте също first, last.

repeat (int count)

Повтаря символния низ х пъти.

{='hello'|repeat: 3}  {* outputs 'hellohellohello' *}

replace (string|array search, string replace = '')

Заменя всички срещания на търсения низ със заместващия низ.

{='hello world'|replace: 'world', 'friend'}  {* outputs 'hello friend' *}

Могат да бъдат извършени няколко замени едновременно:

{='hello world'|replace: [h => l, l => h]}  {* outputs 'lehho worhd' *}

replaceRE (string pattern, string replace = '')

Заменя всички срещания според регулярен израз.

{='hello world'|replaceRE: '/l.*/', 'l'}  {* outputs 'hel' *}

reverse

Обръща даден низ или масив.

{var $s = 'Nette'}
{$s|reverse}    {* outputs 'etteN' *}
{var $a = ['N', 'e', 't', 't', 'e']}
{$a|reverse}    {* returns ['e', 't', 't', 'e', 'N'] *}

round (int precision = 0)

Закръгляне на число до зададена точност.

{=3.4|round}        {* outputs 3      *}
{=3.5|round}        {* outputs 4      *}
{=135.79|round:1}   {* outputs 135.8  *}
{=135.79|round:3}   {* outputs 135.79 *}

Вижте също таван, етаж.

slice (int start, int length = null, bool preserveKeys = false)

Извлича част от масив или низ.

{='hello'|slice: 1, 2}           {* outputs 'el' *}
{=['a', 'b', 'c']|slice: 1, 2}   {* outputs ['b', 'c'] *}

Филтърът за парчета работи като функцията на PHP array_slice за масиви и mb_substr за низове с отпадане на iconv_substr в режим UTF-8.

Ако началото е неотрицателно, последователността ще започне от това начало в променливата. Ако стартът е отрицателен, последователността ще започне на това разстояние от края на променливата.

Ако е зададена дължина и тя е положителна, последователността ще има до толкова елемента в нея. Ако променливата е по-къса от дължината, тогава ще има само наличните елементи на променливата. Ако е зададена дължина и тя е отрицателна, последователността ще спре на толкова елемента от края на променливата. Ако тя е пропусната, последователността ще съдържа всичко от отместването до края на променливата.

По подразбиране Filter ще пренареди и нулира ключовете на целочислените масиви. Това поведение може да бъде променено чрез задаване на стойност preserveKeys на true. Ключовете на низове винаги се запазват, независимо от този параметър.

sort

Филтър, който сортира масив и поддържа асоциация на индексите.

{foreach ($names|sort) as $name}
	...
{/foreach}

Масивът се подрежда в обратен ред.

{foreach ($names|sort|reverse) as $name}
	...
{/foreach}

Можете да подадете своя собствена функция за сравнение като параметър:

{var $sorted = ($names|sort: fn($a, $b) => $b <=> $a)}

spaceless

Премахва ненужните бели полета от изхода. Можете също така да използвате псевдонима strip.

{block |spaceless}
	<ul>
		<li>Hello</li>
	</ul>
{/block}

Отпечатва:

<ul> <li>Hello</li> </ul>

stripHtml

Конвертира HTML в обикновен текст. Това означава, че премахва HTML таговете и преобразува HTML единиците в текст.

{='<p>one &lt; two</p>'|stripHtml}  {* outputs 'one < two' *}

Полученият обикновен текст естествено може да съдържа символи, които представляват HTML тагове, например '<p>'|stripHtml се преобразува в <p>. Никога не извеждайте получения текст с |noescape, тъй като това може да доведе до уязвимост на сигурността.

substr (int offset, int length = null)

Извлича част от низ. Този филтър е заменен с филтър за парчета.

{$string|substr: 1, 2}

translate (string message, …args)

Той превежда изрази на други езици. За да направите филтъра достъпен, трябва да настроите преводач. Можете също така да използвате таговете за превод.

<a href="basket">{='Baskter'|translate}</a>
<span>{$item|translate}</span>

trim (string charlist = " \t\n\r\0\x0B\u{A0}")

Премахване на водещи и завършващи символи, по подразбиране бяло пространство.

{='  I like Latte.  '|trim}    {* outputs 'I like Latte.' *}
{='  I like Latte.'|trim: '.'} {* outputs '  I like Latte' *}

truncate (int length, string append = '…')

Съкращава даден низ до максимално зададената дължина, но се опитва да запази цели думи. Ако низът е съкратен, той добавя елипса в края (това може да се промени с втория параметър).

{var $title = 'Hello, how are you?'}
{$title|truncate:5}  {* Hell…                *}
{$title|truncate:17} {* Hello, how are…      *}
{$title|truncate:30} {* Hello, how are you?  *}

upper

Преобразува стойността в главни букви. Изисква PHP разширение mbstring.

{='latte'|upper}  {* outputs 'LATTE' *}

Вижте също capitalize, firstUpper, lower.

webalize

Преобразува в ASCII.

Превръща интервалите в тирета. Премахва знаци, които не са буквено-цифрови, подчертаващи или дефисни. Преобразува в малки букви. Също така премахва началните и крайните бели полета.

{var $s = 'Our 10. product'}
{$s|webalize}    {* outputs 'our-10-product' *}

Изисква пакет nette/utils.