Филтри за 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>

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

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)

Форматира датата и часа в съответствие с маската, използвана от функцията на 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:','}    {* 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.

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}      {* 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}

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

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

{$date|localDate}                  {* 15. dubna 2024 *}
{$date|format: yM}                 {* 4/2024 *}
{$date|localDate: date: medium}    {* 15. 4. 2024 *}

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

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

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

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

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

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

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

{$date|localDate: date: relative-short}    {* yesterday *}

Вижте също дата.

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

number (string $format)

Параметърът format ви позволява да определите външния вид на числата точно според вашите нужди. Той изисква зададена локализация. Форматът се състои от няколко специални знака, чието пълно описание можете да намерите в документацията на “DecimalFormat”::https://unicode.org/…numbers.html#…

• <c id=6/> задължителна цифра, която винаги се показва, дори ако е нула
• # незадължителна цифра, показва се само ако числото има цифра на това място
• @ значима цифра, помага за показване на числото с определен брой значими цифри
• . маркира мястото, където трябва да се намира десетичният разделител (запетая или точка, в зависимост от локала)
• , се използва за разделяне на групи от цифри, обикновено хиляди
• % умножава числото по 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'}  {* 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 (?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' в примера указва, че сортирането ще се извършва по $row->name или $row['name'], в зависимост от това дали $row е масив или обект:

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

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

{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}  {* 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.