Filtre Latte

În șabloane, putem folosi funcții care ajută la modificarea sau reformatarea datelor în forma finală. Le numim filtre.

Mai există filtre de escapare pentru HTML (escapeHtml și escapeHtmlComment), XML (escapeXml), JavaScript (escapeJs), CSS (escapeCss) și iCalendar (escapeICal), pe care Latte le folosește singur datorită escapării contextuale sensibile și nu trebuie să le scrieți.

Atributele Latte src și href verifică automat, deci filtrul checkUrl aproape că nu trebuie folosit.

Toate filtrele implicite sunt destinate șirurilor în codificarea UTF-8.

Utilizare

Filtrele se scriu după bara verticală (poate fi precedată de un spațiu):

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

Filtrele (în versiunile mai vechi, ajutoarele) pot fi înlănțuite și apoi se aplică în ordine de la stânga la dreapta:

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

Parametrii se specifică după numele filtrului, separați prin două puncte sau virgule:

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

Filtrele pot fi aplicate și pe o expresie:

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

Filtrele personalizate pot fi înregistrate în acest mod:

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

În șablon, se apelează apoi astfel:

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

Filtre

batch (int $length, mixed $item): array

Filtrul care simplifică afișarea datelor liniare sub formă de tabel. Returnează un array de array-uri cu numărul specificat de elemente. Dacă specificați al doilea parametru, acesta va fi folosit pentru a completa elementele lipsă de pe ultimul rând.

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

Afișează:

<table>
	<tr>
		<td>a</td>
		<td>b</td>
		<td>c</td>
	</tr>
	<tr>
		<td>d</td>
		<td>e</td>
		<td>Niciun element</td>
	</tr>
</table>

Vezi și group și tag-ul iterateWhile.

breakLines

Adaugă tag-ul HTML <br> înaintea fiecărui caracter de linie nouă.

{var $s = "Text & with \n newline"}
{$s|breakLines}    {* afișează "Text &amp; with <br>\n newline" *}

bytes (int $precision=2)

Formatează dimensiunea în bytes într-o formă lizibilă pentru om. Dacă sunt setate setările regionale, se vor folosi separatoarele corespunzătoare pentru zecimale și mii.

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

ceil (int $precision=0)

Rotunjește numărul în sus la precizia dată.

{=3.4|ceil}         {* afișează 4      *}
{=135.22|ceil:1}    {* afișează 135.3  *}
{=135.22|ceil:3}    {* afișează 135.22 *}

Vezi și floor, round.

capitalize

Cuvintele vor începe cu majuscule, toate celelalte caractere vor fi minuscule. Necesită extensia PHP mbstring.

{='i like LATTE'|capitalize}  {* afișează 'I Like Latte' *}

Vezi și firstUpper, lower, upper.

checkUrl

Forțează curățarea adresei URL. Verifică dacă variabila conține o adresă URL web (adică protocol HTTP/HTTPS) și previne afișarea linkurilor care pot reprezenta un risc de securitate.

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

Afișează:

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

Vezi și nocheck.

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

Limitează valoarea la intervalul inclusiv dat min și max.

{$level|clamp: 0, 255}

Există și ca funcție.

dataStream (string $mimetype=detect)

Convertește conținutul în schema data URI. Cu ajutorul acesteia, se pot încorpora imagini în HTML sau CSS fără a fi nevoie de linkuri către fișiere externe.

Să avem într-o variabilă imaginea $img = Image::fromFile('imagine.gif'), apoi

<img src={$img|dataStream}>

Afișează, de exemplu:

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

Necesită extensia PHP fileinfo.

date (string $format)

Formatează data și ora conform măștii utilizate de funcția PHP date. Filtrul acceptă data în format UNIX timestamp, ca șir sau obiect de tip DateTimeInterface.

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

Vezi și localDate.

escapeUrl

Escapează variabila pentru utilizare ca parametru în URL.

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

Vezi și query.

explode (string $separator='')

Împarte șirul într-un array după delimitator. Alias pentru split.

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

Dacă delimitatorul este un șir gol (valoarea implicită), intrarea va fi împărțită în caractere individuale:

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

Puteți folosi și aliasul split:

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

Vezi și implode.

first

Returnează primul element al array-ului sau caracterul șirului:

{=[1, 2, 3, 4]|first}    {* afișează 1 *}
{='abcd'|first}          {* afișează 'a' *}

Vezi și last, random.

floor (int $precision=0)

Rotunjește numărul în jos la precizia dată.

{=3.5|floor}        {* afișează 3      *}
{=135.79|floor:1}   {* afișează 135.7  *}
{=135.79|floor:3}   {* afișează 135.79 *}

Vezi și ceil, round.

firstUpper

Convertește prima literă în majusculă. Necesită extensia PHP mbstring.

{='the latte'|firstUpper}  {* afișează 'The latte' *}

Vezi și capitalize, lower, upper.

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

Filtrul grupează datele după diverse criterii.

În acest exemplu, rândurile din tabel sunt grupate după coloana categoryId. Ieșirea este un array de array-uri, unde cheia este valoarea din coloana categoryId. Citiți un tutorial detaliat.

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

Vezi și batch, funcția group și tag-ul iterateWhile.

implode (string $glue='')

Returnează un șir care este concatenarea elementelor secvenței. Alias pentru join.

{=[1, 2, 3]|implode}      {* afișează '123' *}
{=[1, 2, 3]|implode:'|'}  {* afișează '1|2|3' *}

Puteți folosi și aliasul join:

{=[1, 2, 3]|join}         {* afișează '123' *}

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

Indentează textul de la stânga cu un număr dat de tabulatori sau alte caractere, pe care le putem specifica în al doilea argument. Rândurile goale nu sunt indentate.

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

Afișează:

<div>
	<p>Salut</p>
</div>

last

Returnează ultimul element al array-ului sau caracterul șirului:

{=[1, 2, 3, 4]|last}    {* afișează 4 *}
{='abcd'|last}          {* afișează 'd' *}

Vezi și first, random.

length

Returnează lungimea șirului sau a array-ului.

• pentru șiruri, returnează lungimea în caractere UTF-8
• pentru array-uri, returnează numărul de elemente
• pentru obiecte care implementează interfața Countable, utilizează valoarea returnată de metoda count()
• pentru obiecte care implementează interfața IteratorAggregate, utilizează valoarea returnată de funcția iterator_count()

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

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

Formatează data și ora în funcție de setările regionale, asigurând o afișare consistentă și localizată a datelor temporale în diferite limbi și regiuni. Filtrul acceptă data ca UNIX timestamp, șir sau obiect de tip DateTimeInterface.

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

Dacă utilizați filtrul fără parametri, data va fi afișată la nivelul long, vezi mai jos.

a) utilizarea formatului

Parametrul format descrie ce componente temporale trebuie afișate. Utilizează coduri de litere pentru acestea, a căror număr de repetări influențează lățimea ieșirii:

Ordinea codurilor în format nu contează, deoarece ordinea componentelor va fi afișată conform convențiilor setărilor regionale. Formatul este, așadar, independent de acestea. De exemplu, formatul yyyyMMMMd în mediul en_US va afișa April 15, 2024, în timp ce în mediul ro_RO va afișa 15 august 2024:

b) utilizarea stilurilor predefinite

Parametrii date și time determină cât de detaliat trebuie afișată data și ora. Puteți alege dintre mai multe niveluri: full, long, medium, short. Se poate afișa doar data, doar ora sau ambele:

Pentru dată, se poate utiliza în plus prefixul relative- (de ex. relative-short), care pentru datele apropiate de prezent va afișa ieri, azi sau mâine, altfel se va afișa în mod standard.

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

Vezi și date.

lower

Convertește șirul în litere mici. Necesită extensia PHP mbstring.

{='LATTE'|lower}   {* afișează 'latte' *}

Vezi și capitalize, firstUpper, upper.

nocheck

Previne curățarea automată a adresei URL. Latte verifică automat dacă variabila conține o adresă URL web (adică protocol HTTP/HTTPS) și previne afișarea linkurilor care pot reprezenta un risc de securitate.

Dacă linkul utilizează o altă schemă, de ex. javascript: sau data:, și sunteți sigur de conținutul său, puteți dezactiva verificarea folosind |nocheck.

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

<a href={$link}>verificat</a>
<a href={$link|nocheck}>neverificat</a>

Afișează:

<a href="">verificat</a>
<a href="javascript:window.close()">neverificat</a>

Vezi și checkUrl.

noescape

Dezactivează escaparea automată.

{var $trustedHtmlString = '<b>salut</b>'}
Escapat: {$trustedHtmlString}
Neescapat: {$trustedHtmlString|noescape}

Afișează:

Escapat: <b>salut</b>
Neescapat: <b>salut</b>

Utilizarea incorectă a filtrului noescape poate duce la vulnerabilitatea XSS! Nu-l utilizați niciodată dacă nu sunteți absolut sigur de ceea ce faceți și că șirul afișat provine dintr-o sursă de încredere.

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

Formatează numărul la un anumit număr de zecimale. Dacă sunt setate setările regionale, se vor folosi separatoarele corespunzătoare pentru zecimale și mii.

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

Parametrul format permite definirea aspectului numerelor exact conform nevoilor dvs. Pentru aceasta, este necesar să aveți setate setările regionale. Formatul constă din mai multe caractere speciale, a căror descriere completă o găsiți în documentația DecimalFormat:

• 0 cifră obligatorie, se afișează întotdeauna, chiar dacă este zero
• # cifră opțională, se afișează doar dacă numărul există efectiv în această poziție
• @ cifră semnificativă, ajută la afișarea numărului cu un anumit număr de cifre valide
• . indică unde trebuie să fie virgula zecimală (sau punctul, în funcție de țară)
• , servește la separarea grupurilor de cifre, cel mai adesea miilor
• % numărul se înmulțește cu 100× și se adaugă semnul procentului

Să vedem câteva exemple. În primul exemplu, două zecimale sunt obligatorii, în al doilea sunt opționale. Al treilea exemplu arată completarea cu zerouri la stânga și la dreapta, al patrulea afișează doar cifrele existente:

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

Cifrele semnificative determină câte cifre, indiferent de virgula zecimală, trebuie afișate, rotunjindu-se:

{1234|number: '@@'}             {* 1200 *}
{1234|number: '@@@'}            {* 1230 *}
{1234|number: '@@@#'}           {* 1234 *}
{1.2345|number: '@@@'}          {* 1,23 *}
{0.00123|number: '@@'}          {* 0,0012 *}

O modalitate ușoară de a afișa numărul ca procent. Numărul se înmulțește cu 100× și se adaugă semnul %:

{0.1234|number: '#.##%'}        {* 12,34% *}

Putem defini un format diferit pentru numerele pozitive și negative, separate prin caracterul ;. În acest mod, de exemplu, se poate seta ca numerele pozitive să fie afișate cu semnul +:

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

Rețineți că aspectul real al numerelor poate varia în funcție de setările țării. De exemplu, în unele țări se folosește virgula în loc de punct ca separator zecimal. Acest filtru ia în considerare automat acest lucru și nu trebuie să vă faceți griji.

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

Completează șirul la o anumită lungime cu un alt șir de la stânga.

{='salut'|padLeft: 10, '123'}  {* afișează '12312salut' *}

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

Completează șirul la o anumită lungime cu un alt șir de la dreapta.

{='salut'|padRight: 10, '123'}  {* afișează 'salut12312' *}

query

Generează dinamic query string în URL:

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

Afișează:

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

Cheile cu valoarea null sunt omise.

Vezi și escapeUrl.

random

Returnează un element aleatoriu al array-ului sau caracterul șirului:

{=[1, 2, 3, 4]|random}    {* afișează de ex.: 3 *}
{='abcd'|random}          {* afișează de ex.: 'b' *}

Vezi și first, last.

repeat (int $count)

Repetă șirul de x ori.

{='salut'|repeat: 3}  {* afișează 'salutsalutsalut' *}

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

Înlocuiește toate aparițiile șirului de căutare cu șirul de înlocuire.

{='hello world'|replace: 'world', 'friend'}  {* afișează 'hello friend' *}

Se pot efectua și mai multe înlocuiri simultan:

{='hello world'|replace: [h => l, l => h]}  {* afișează 'lehho worhd' *}

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

Efectuează căutarea expresiilor regulate cu înlocuire.

{='hello world'|replaceRE: '/l.*/', 'l'}  {* afișează 'hel' *}

reverse

Inversează șirul sau array-ul dat.

{var $s = 'Nette'}
{$s|reverse}    {* afișează 'etteN' *}
{var $a = ['N', 'e', 't', 't', 'e']}
{$a|reverse}    {* returnează ['e', 't', 't', 'e', 'N'] *}

round (int $precision=0)

Rotunjește numărul la precizia dată.

{=3.4|round}        {* afișează 3      *}
{=3.5|round}        {* afișează 4      *}
{=135.79|round:1}   {* afișează 135.8  *}
{=135.79|round:3}   {* afișează 135.79 *}

Vezi și ceil, floor.

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

Extrage o parte a array-ului sau a șirului.

{='salut'|slice: 1, 2}           {* afișează 'al' *}
{=['a', 'b', 'c']|slice: 1, 2}   {* afișează ['b', 'c'] *}

Filtrul funcționează ca funcția PHP array_slice pentru array-uri sau mb_substr pentru șiruri, cu fallback la funcția iconv_substr în modul UTF-8.

Dacă start este pozitiv, secvența va începe deplasată cu acest număr de la începutul array-ului/șirului. Dacă este negativ, secvența va începe deplasată cu atâtea de la sfârșit.

Dacă parametrul length este specificat și este pozitiv, secvența va conține atâtea elemente. Dacă în această funcție este transmis un parametru length negativ, secvența va conține toate elementele array-ului original, începând de la poziția start și terminând la poziția mai mică cu length elemente de la sfârșitul array-ului. Dacă nu specificați acest parametru, secvența va conține toate elementele array-ului original, începând de la poziția start.

În mod implicit, filtrul schimbă ordinea și resetează cheile întregi ale array-ului. Acest comportament poate fi schimbat setând preserveKeys la true. Cheile șir sunt întotdeauna păstrate, indiferent de acest parametru.

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

Filtrul sortează elementele unui array sau iterator și păstrează cheile lor asociative. Când sunt setate setările regionale, sortarea respectă regulile acestora, dacă nu este specificată o funcție de comparare personalizată.

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

Array sortat în ordine inversă:

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

Puteți specifica o funcție de comparare personalizată pentru sortare (exemplul arată cum să inversați sortarea de la cel mai mare la cel mai mic):

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

Filtrul |sort permite, de asemenea, sortarea elementelor după chei:

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

Dacă trebuie să sortați un tabel după o anumită coloană, puteți utiliza parametrul by. Valoarea 'name' din exemplu specifică faptul că se va sorta după $item->name sau $item['name'], în funcție de dacă $item este un array sau un obiect:

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

Puteți defini, de asemenea, o funcție callback care determină valoarea după care se va sorta:

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

În același mod se poate utiliza și parametrul byKey.

spaceless

Elimină spațiul alb (spațiile) inutil din ieșire. Puteți folosi și aliasul strip.

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

Afișează:

<ul> <li>Salut</li> </ul>

stripHtml

Convertește HTML în text simplu. Adică elimină tag-urile HTML și convertește entitățile HTML în text.

{='<p>one &lt; two</p>'|stripHtml}  {* afișează 'one < two' *}

Textul simplu rezultat poate conține în mod natural caractere care reprezintă tag-uri HTML, de exemplu '<p>'|stripHtml se convertește în <p>. În niciun caz nu afișați textul astfel obținut cu |noescape, deoarece acest lucru poate duce la o vulnerabilitate de securitate.

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

Extrage o parte a șirului. Acest filtru a fost înlocuit de filtrul slice.

{$string|substr: 1, 2}

translate (…$args)

Traduce expresiile în alte limbi. Pentru ca filtrul să fie disponibil, trebuie setat traducătorul. Puteți utiliza și tag-urile pentru traducere.

<a href="cos">{='Coș'|translate}</a>
<span>{$item|translate}</span>

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

Elimină spațiile albe (sau alte caractere) de la începutul și sfârșitul șirului.

{='  I like Latte.  '|trim}    {* afișează 'I like Latte.' *}
{='  I like Latte.'|trim: '.'} {* afișează '  I like Latte' *}

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

Taie șirul la lungimea maximă specificată, încercând să păstreze cuvintele întregi. Dacă șirul este scurtat, adaugă la sfârșit trei puncte (se poate schimba cu al doilea parametru).

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

upper

Convertește șirul în litere mari. Necesită extensia PHP mbstring.

{='latte'|upper}  {* afișează 'LATTE' *}

Vezi și capitalize, firstUpper, lower.

webalize

Modifică șirul UTF-8 în forma utilizată în URL.

Se convertește în ASCII. Convertește spațiile în cratime. Elimină caracterele care nu sunt alfanumerice, underscore sau cratime. Convertește în litere mici. Elimină, de asemenea, spațiile de la început și sfârșit.

{var $s = 'Produsul nostru 10'}
{$s|webalize}   {* afișează 'produsul-nostru-10' *}

Necesită biblioteca nette/utils.