Latte филтри

В шаблоните можем да използваме функции, които помагат за модифициране или преформатиране на данните в окончателния им вид. Наричаме ги филтри.

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

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

Всички филтри по подразбиране са предназначени за низове в кодировка UTF‑8.

Използване

Филтрите се записват след вертикална черта (може да има интервал преди нея):

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

Вижте също group и тага iterateWhile.

breakLines

Добавя HTML таг <br> преди всеки знак за нов ред.

{var $s = "Text & with \n newline"}
{$s|breakLines}    {* извежда "Text &amp; 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}>контролирано</a>
<a data-href={$link}>неконтролирано</a>

Извежда:

<a data-href="">контролирано</a>
<a data-href="javascript:window.close()">неконтролирано</a>

Вижте също nocheck.

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

Ограничава стойността в дадения инклузивен диапазон min и max.

{$level|clamp: 0, 255}

Съществува и като функция.

dataStream (string $mimetype=detect)

Конвертира съдържанието в data URI scheme. С негова помощ могат да се вмъкват изображения в 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)

Форматира дата и час според маската, използвана от PHP функцията date. Филтърът приема дата във формат UNIX timestamp, като низ или обект от тип DateTimeInterface.

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

Вижте също localDate.

escapeUrl

Екранира променлива за използване като параметър в URL.

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

Вижте също query.

explode (string $separator='')

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

{='one,two,three'|explode:','}    {* връща ['one', 'two', 'three'] *}

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

{='123'|explode}                  {* връща ['1', '2', '3'] *}

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

{='1,2,3'|split:','}              {* връща ['1', '2', '3'] *}

Вижте също implode.

first

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

{=[1, 2, 3, 4]|first}    {* извежда 1 *}
{='abcd'|first}          {* извежда 'a' *}

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

floor (int $precision=0)

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

{=3.5|floor}        {* извежда 3      *}
{=135.79|floor:1}   {* извежда 135.7  *}
{=135.79|floor:3}   {* извежда 135.79 *}

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

firstUpper

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

{='the latte'|firstUpper}  {* извежда 'The latte' *}

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

group (string|int|\Closure $by): array

Филтърът групира данни по различни критерии.

В този пример редовете в таблицата се групират по колона categoryId. Изходът е масив от масиви, където ключът е стойността в колоната categoryId. Прочетете подробно ръководство.

{foreach ($items|group: categoryId) as $categoryId => $categoryItems}
    <ul>
        {foreach $categoryItems as $item}
            <li>{$item->name}</li>
        {/foreach}
    </ul>
{/foreach}

Вижте също batch, функцията group и тага iterateWhile.

implode (string $glue='')

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

{=[1, 2, 3]|implode}      {* извежда '123' *}
{=[1, 2, 3]|implode:'|'}  {* извежда '1|2|3' *}

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

{=[1, 2, 3]|join}         {* извежда '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}    {* извежда 4 *}
{='abcd'|last}          {* извежда 'd' *}

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

length

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

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

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

localDate (?string $format=null, ?string $date=null, ?string $time=null)

Форматира дата и час според локализация, което осигурява последователно и локализирано показване на времеви данни в различни езици и региони. Филтърът приема дата като UNIX timestamp, низ или обект от тип DateTimeInterface.

{$date|localDate}                  {* 15 април 2024 *}
{$date|format: yM}                 {* 4/2024 *}
{$date|localDate: date: medium}    {* 15.4.2024 *}

Ако използвате филтъра без параметри, датата ще се изведе на ниво long, вижте по-нататък.

а) използване на формат

Параметърът format описва кои времеви компоненти да се покажат. За тях се използват буквени кодове, чийто брой повторения влияе на ширината на изхода:

Редът на кодовете във формата няма значение, тъй като редът на компонентите се извежда според обичаите на локализацията. Следователно форматът е независим от нея. Например форматът yyyyMMMMd в среда en_US ще изведе April 15, 2024, докато в среда bg_BG ще изведе 15 април 2024:

б) използване на предварително зададени стилове

Параметрите date и time определят колко подробно да се изведат датата и часът. Можете да избирате от няколко нива: full, long, medium, short. Може да се изведе само датата, само часът или и двете:

При датата може допълнително да се използва префикс relative- (напр. relative-short), който за дати, близки до настоящия момент, ще покаже вчера, днес или утре, иначе ще се изведе по стандартния начин.

{$date|localDate: date: relative-short}    {* вчера *}

Вижте също date.

lower

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

{='LATTE'|lower}   {* извежда 'latte' *}

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

nocheck

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

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

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

<a href={$link}>контролирано</a>
<a href={$link|nocheck}>неконтролирано</a>

Извежда:

<a href="">контролирано</a>
<a href="javascript:window.close()">неконтролирано</a>

Вижте също checkUrl.

noescape

Забранява автоматичното екраниране.

{var $trustedHtmlString = '<b>hello</b>'}
Екранирано: {$trustedHtmlString}
Неекранирано: {$trustedHtmlString|noescape}

Извежда:

Екранирано: <b>hello</b>
Неекранирано: <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 *}

number (string $format)

Параметърът format позволява да дефинирате вида на числата точно според вашите нужди. За това е необходимо да имате настроена локализация. Форматът се състои от няколко специални знака, чието пълно описание ще намерите в документацията DecimalFormat:

• 0 задължителна цифра, винаги се показва, дори ако е нула
• # незадължителна цифра, показва се само ако на това място числото действително съществува
• @ значеща цифра, помага да се покаже число с определен брой значещи цифри
• . показва къде трябва да бъде десетичната запетая (или точка, според държавата)
• , служи за разделяне на групи цифри, най-често хиляди
• % числото се умножава по 100× и се добавя знак за процент

Нека разгледаме примери. В първия пример два десетични знака са задължителни, във втория – незадължителни. Третият пример показва допълване с нули отляво и отдясно, четвъртият показва само съществуващите цифри:

{1234.5|number: '#,##0.00'}     {* 1,234.50 *}
{1234.5|number: '#,##0.##'}     {* 1,234.5 *}
{1.23  |number: '000.000'}      {* 001.230 *}
{1.2   |number: '##.##'}        {* 1.2 *}

Значещите цифри определят колко цифри, независимо от десетичната запетая, трябва да бъдат показани, като се закръгля:

{1234|number: '@@'}             {* 1200 *}
{1234|number: '@@@'}            {* 1230 *}
{1234|number: '@@@#'}           {* 1234 *}
{1.2345|number: '@@@'}          {* 1.23 *}
{0.00123|number: '@@'}          {* 0.0012 *}

Лесен начин да покажете число като процент. Числото се умножава по 100× и се добавя знак %:

{0.1234|number: '#.##%'}        {* 12.34% *}

Можем да дефинираме различен формат за положителни и отрицателни числа, разделени със знака ;. По този начин може например да се настрои положителните числа да се показват със знак +:

{42|number: '#.##;(#.##)'}      {* 42 *}
{-42|number: '#.##;(#.##)'}     {* (42) *}
{42|number: '+#.##;-#.##'}      {* +42 *}
{-42|number: '+#.##;-#.##'}     {* -42 *}

Помнете, че действителният вид на числата може да се различава според настройките на държавата. Например в някои държави се използва запетая вместо точка като разделител на десетичните знаци. Този филтър автоматично взема това предвид и не е нужно да се притеснявате за нищо.

padLeft (int $length, string $pad=' ')

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

{='hello'|padLeft: 10, '123'}  {* извежда '12312hello' *}

padRight (int $length, string $pad=' ')

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

{='hello'|padRight: 10, '123'}  {* извежда 'hello12312' *}

query

Динамично генерира query string в 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}    {* извежда напр.: 3 *}
{='abcd'|random}          {* извежда напр.: 'b' *}

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

repeat (int $count)

Повтаря низ x пъти.

{='hello'|repeat: 3}  {* извежда 'hellohellohello' *}

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

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

{='hello world'|replace: 'world', 'friend'}  {* извежда 'hello friend' *}

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

{='hello world'|replace: [h => l, l => h]}  {* извежда 'lehho worhd' *}

replaceRE (string $pattern, string $replace='')

Извършва търсене с регулярни изрази със замяна.

{='hello world'|replaceRE: '/l.*/', 'l'}  {* извежда 'hel' *}

reverse

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

{var $s = 'Nette'}
{$s|reverse}    {* извежда 'etteN' *}
{var $a = ['N', 'e', 't', 't', 'e']}
{$a|reverse}    {* връща ['e', 't', 't', 'e', 'N'] *}

round (int $precision=0)

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

{=3.4|round}        {* извежда 3      *}
{=3.5|round}        {* извежда 4      *}
{=135.79|round:1}   {* извежда 135.8  *}
{=135.79|round:3}   {* извежда 135.79 *}

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

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

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

{='hello'|slice: 1, 2}           {* извежда 'el' *}
{=['a', 'b', 'c']|slice: 1, 2}   {* извежда ['b', 'c'] *}

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

Ако $start е положителен, последователността ще започне изместена с този брой от началото на масива/низа. Ако е отрицателен, последователността ще започне изместена с толкова от края.

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

По подразбиране филтърът променя реда и нулира целочислените ключове на масива. Това поведение може да се промени, като се зададе $preserveKeys на true. Низовите ключове винаги се запазват, независимо от този параметър.

sort (?Closure $comparison, string|int|\Closure|null $by=null, string|int|\Closure|bool $byKey=false)

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

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

Сортиран масив в обратен ред:

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

Можете да специфицирате собствена функция за сравнение за сортиране (примерът показва как да обърнете сортирането от най-голямо към най-малко):

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

Филтърът |sort също позволява сортиране на елементи по ключове:

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

Ако трябва да сортирате таблица по конкретна колона, можете да използвате параметъра by. Стойността 'name' в примера указва, че ще се сортира по $item->name или $item['name'], в зависимост от това дали $item е масив или обект:

{foreach ($items|sort: by: 'name') as $item}
	{$item->name}
{/foreach}

Можете също да дефинирате callback функция, която да определи стойността, по която да се сортира:

{foreach ($items|sort: by: fn($items) => $items->category->name) as $item}
	{$item->name}
{/foreach}

По същия начин може да се използва и параметърът byKey.

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}  {* извежда 'one < two' *}

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

substr (int $offset, ?int $length=null)

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

{$string|substr: 1, 2}

translate (…$args)

Превежда изрази на други езици. За да бъде филтърът наличен, е необходимо да настроите преводач. Можете също да използвате тагове за превод.

<a href="basket">{='Кошница'|translate}</a>
<span>{$item|translate}</span>

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

Премахва празни знаци (или други знаци) от началото и края на низа.

{='  I like Latte.  '|trim}    {* извежда 'I like Latte.' *}
{='  I like Latte.'|trim: '.'} {* извежда '  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}  {* извежда 'LATTE' *}

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

webalize

Модифицира UTF‑8 низ във форма, използвана в URL.

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

{var $s = 'Нашият 10-ти продукт'}
{$s|webalize}   {* извежда 'nashiyat-10-ti-produkt' *}

Изисква библиотеката nette/utils.