Latte szűrők

A sablonokban olyan függvényeket használhatunk, amelyek segítenek az adatok módosításában vagy újraformázásában a végső formába. Ezeket szűrőknek nevezzük.

Továbbá léteznek escapelő szűrők HTML-hez (escapeHtml és escapeHtmlComment), XML-hez (escapeXml), JavaScripthez (escapeJs), CSS-hez (escapeCss) és iCalendarhez (escapeICal), amelyeket a Latte maga használ a kontextusérzékeny escapelés révén, és nem kell őket kiírni.

A Latte src és href attribútumokat automatikusan ellenőrzi, így a checkUrl szűrőt szinte soha nem kell használni.

Minden alapértelmezett szűrő UTF‑8 kódolású stringekhez készült.

Használat

A szűrőket függőleges vonal után írjuk (előtte lehet szóköz):

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

A szűrőket (régebbi verziókban helper-eket) láncolni lehet, és balról jobbra kerülnek alkalmazásra:

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

A paramétereket a szűrő neve után adjuk meg, kettősponttal vagy vesszővel elválasztva:

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

A szűrőket kifejezésre is lehet alkalmazni:

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

Egyéni szűrőket így lehet regisztrálni:

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

A sablonban pedig így hívjuk meg:

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

Szűrők

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

Szűrő, amely leegyszerűsíti a lineáris adatok táblázatos formában történő kiírását. Visszaad egy tömbökből álló tömböt a megadott számú elemmel. Ha megadja a második paramétert, azt használja a hiányzó elemek pótlására az utolsó sorban.

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

Kiírja:

<table>
	<tr>
		<td>a</td>
		<td>b</td>
		<td>c</td>
	</tr>
	<tr>
		<td>d</td>
		<td>e</td>
		<td>Nincs elem</td>
	</tr>
</table>

Lásd még group és a iterateWhile taget.

breakLines

Minden új sor karakter elé beszúrja a <br> HTML taget.

{var $s = "Szöveg & \n új sorral"}
{$s|breakLines}    {* kiírja: "Szöveg &amp; <br>\n új sorral" *}

bytes (int $precision=2)

A bájtban megadott méretet ember által olvasható formátumra alakítja. Ha a nemzeti beállítások be vannak állítva, a megfelelő tizedes- és ezreselválasztókat használja.

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

ceil (int $precision=0)

Felfelé kerekíti a számot a megadott pontosságra.

{=3.4|ceil}         {* kiírja: 4      *}
{=135.22|ceil:1}    {* kiírja: 135.3  *}
{=135.22|ceil:3}    {* kiírja: 135.22 *}

Lásd még floor, round.

capitalize

A szavak nagybetűvel kezdődnek, az összes többi karakter kisbetűs lesz. Szükséges a mbstring PHP kiterjesztés.

{='szeretem a LATTÉt'|capitalize}  {* kiírja: 'Szeretem A Lattét' *}

Lásd még firstUpper, lower, upper.

checkUrl

Kikényszeríti az URL cím tisztítását. Ellenőrzi, hogy a változó webes URL-t tartalmaz-e (azaz HTTP/HTTPS protokollt), és megakadályozza az olyan linkek kiírását, amelyek biztonsági kockázatot jelenthetnek.

{var $link = 'javascript:window.close()'}
<a data-href={$link|checkUrl}>ellenőrzött</a>
<a data-href={$link}>nem ellenőrzött</a>

Kiírja:

<a data-href="">ellenőrzött</a>
<a data-href="javascript:window.close()">nem ellenőrzött</a>

Lásd még nocheck.

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

Az értéket a megadott inkluzív min és max tartományba korlátozza.

{$level|clamp: 0, 255}

Létezik függvényként is.

dataStream (string $mimetype=detect)

A tartalmat data URI scheme-re konvertálja. Segítségével képeket lehet beágyazni HTML-be vagy CSS-be külső fájlok linkelése nélkül.

Legyen egy kép a $img = Image::fromFile('kep.gif') változóban, ekkor

<img src={$img|dataStream}>

Kiírja például:

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

Szükséges a fileinfo PHP kiterjesztés.

date (string $format)

Dátumot és időt formáz a PHP date függvény által használt maszk szerint. A szűrő elfogadja a dátumot UNIX timestamp formátumban, stringként vagy DateTimeInterface típusú objektumként.

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

Lásd még localDate.

escapeUrl

Escapeli a változót URL paraméterként való használatra.

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

Lásd még query.

explode (string $separator='')

Stringet tömbre bont elválasztó szerint. Alias a split-re.

{='egy,kettő,három'|explode:','}    {* visszaadja: ['egy', 'kettő', 'három'] *}

Ha az elválasztó üres string (alapértelmezett érték), a bemenet egyes karakterekre lesz bontva:

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

Használhatja a split aliast is:

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

Lásd még implode.

first

Visszaadja a tömb első elemét vagy a string első karakterét:

{=[1, 2, 3, 4]|first}    {* kiírja: 1 *}
{='abcd'|first}          {* kiírja: 'a' *}

Lásd még last, random.

floor (int $precision=0)

Lefelé kerekíti a számot a megadott pontosságra.

{=3.5|floor}        {* kiírja: 3      *}
{=135.79|floor:1}   {* kiírja: 135.7  *}
{=135.79|floor:3}   {* kiírja: 135.79 *}

Lásd még ceil, round.

firstUpper

Az első betűt naggyá alakítja. Szükséges a mbstring PHP kiterjesztés.

{='a latte'|firstUpper}  {* kiírja: 'A latte' *}

Lásd még capitalize, lower, upper.

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

A szűrő csoportosítja az adatokat különböző kritériumok szerint.

Ebben a példában a táblázat sorai a categoryId oszlop szerint vannak csoportosítva. A kimenet egy tömbökből álló tömb, ahol a kulcs a categoryId oszlop értéke. Olvassa el a részletes útmutatót.

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

Lásd még batch, a group függvény és a iterateWhile tag.

implode (string $glue='')

Visszaad egy stringet, amely a szekvencia elemeinek összefűzése. Alias a join-ra.

{=[1, 2, 3]|implode}      {* kiírja: '123' *}
{=[1, 2, 3]|implode:'|'}  {* kiírja: '1|2|3' *}

Használhatja a join aliast is:

{=[1, 2, 3]|join}         {* kiírja: '123' *}

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

A szöveget balról behúzza a megadott számú tabulátorral vagy más karakterrel, amelyet a második argumentumban adhatunk meg. Az üres sorok nincsenek behúzva.

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

Kiírja:

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

last

Visszaadja a tömb utolsó elemét vagy a string utolsó karakterét:

{=[1, 2, 3, 4]|last}    {* kiírja: 4 *}
{='abcd'|last}          {* kiírja: 'd' *}

Lásd még first, random.

length

Visszaadja a string vagy a tömb hosszát.

• stringek esetén visszaadja a hosszt UTF‑8 karakterekben
• tömbök esetén visszaadja az elemek számát
• a Countable interfészt implementáló objektumok esetén a count() metódus visszatérési értékét használja
• az IteratorAggregate interfészt implementáló objektumok esetén az iterator_count() függvény visszatérési értékét használja

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

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

Dátumot és időt formáz a nemzeti beállítások szerint, ami biztosítja az időadatok következetes és lokalizált megjelenítését a különböző nyelveken és régiókban. A szűrő elfogadja a dátumot UNIX timestampként, stringként vagy DateTimeInterface típusú objektumként.

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

Ha a szűrőt paraméterek nélkül használja, a dátum a long szinten kerül kiírásra, lásd alább.

a) formátum használata

A format paraméter leírja, hogy mely időösszetevőket kell megjeleníteni. Ehhez betűkódokat használ, amelyek ismétlődésének száma befolyásolja a kimenet szélességét:

A kódok sorrendje a formátumban nem számít, mert az összetevők sorrendje a nemzeti beállítások szokásai szerint kerül kiírásra. A formátum tehát független tőle. Például a yyyyMMMMd formátum en_US környezetben April 15, 2024-et ír ki, míg hu_HU környezetben 2024. április 15.-öt:

b) előre beállított stílusok használata

A date és time paraméterek határozzák meg, hogy milyen részletességgel kell a dátumot és az időt kiírni. Több szint közül választhat: full, long, medium, short. Kiíratható csak a dátum, csak az idő, vagy mindkettő:

A dátumnál ezenkívül használható a relative- előtag (pl. relative-short), amely a jelenhez közeli dátumok esetén tegnap, ma vagy holnap szöveget jelenít meg, egyébként a standard módon írja ki.

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

Lásd még date.

lower

A stringet kisbetűssé alakítja. Szükséges a mbstring PHP kiterjesztés.

{='LATTE'|lower}   {* kiírja: 'latte' *}

Lásd még capitalize, firstUpper, upper.

nocheck

Megakadályozza az URL cím automatikus tisztítását. A Latte automatikusan ellenőrzi, hogy a változó webes URL-t tartalmaz-e (azaz HTTP/HTTPS protokollt), és megakadályozza az olyan linkek kiírását, amelyek biztonsági kockázatot jelenthetnek.

Ha a link más sémát használ, pl. javascript: vagy data:, és biztos a tartalmában, a |nocheck segítségével kikapcsolhatja az ellenőrzést.

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

<a href={$link}>ellenőrzött</a>
<a href={$link|nocheck}>nem ellenőrzött</a>

Kiírja:

<a href="">ellenőrzött</a>
<a href="javascript:window.close()">nem ellenőrzött</a>

Lásd még checkUrl.

noescape

Letiltja az automatikus escapelést.

{var $trustedHtmlString = '<b>helló</b>'}
Escapelt: {$trustedHtmlString}
Nem escapelt: {$trustedHtmlString|noescape}

Kiírja:

Escapelt: <b>helló</b>
Nem escapelt: <b>helló</b>

A noescape szűrő helytelen használata XSS sebezhetőséghez vezethet! Soha ne használja, ha nem teljesen biztos abban, amit csinál, és hogy a kiírt string megbízható forrásból származik.

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

Számot formáz adott számú tizedesjegyre. Ha a nemzeti beállítások be vannak állítva, a megfelelő tizedes- és ezreselválasztókat használja.

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

A format paraméter lehetővé teszi a számok megjelenésének pontos meghatározását az Ön igényei szerint. Ehhez be kell állítani a nemzeti beállításokat. A formátum több speciális karakterből áll, amelyek teljes leírását a DecimalFormat dokumentációban találja:

• 0 kötelező számjegy, mindig megjelenik, még akkor is, ha nulla
• # opcionális számjegy, csak akkor jelenik meg, ha ezen a helyen valóban van számjegy
• @ jelentős számjegy, segít a szám megjelenítésében adott számú érvényes számjeggyel
• . jelzi, hol legyen a tizedesvessző (vagy pont, országtól függően)
• , a számjegycsoportok, leggyakrabban ezresek elválasztására szolgál
• % a számot 100-zal szorozza és hozzáadja a százalékjelet

Nézzünk néhány példát. Az első példában két tizedesjegy kötelező, a másodikban opcionális. A harmadik példa a nullákkal való kiegészítést mutatja balról és jobbról, a negyedik csak a létező számjegyeket jeleníti meg:

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

A jelentős számjegyek határozzák meg, hogy hány számjegy jelenjen meg a tizedesvesszőtől függetlenül, kerekítéssel:

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

Egyszerű módja a szám százalékként való megjelenítésének. A számot 100-zal szorozza és hozzáadja a % jelet:

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

Definiálhatunk eltérő formátumot a pozitív és negatív számokra, ezeket a ; jel választja el. Ezzel a módszerrel például beállítható, hogy a pozitív számok + jellel jelenjenek meg:

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

Ne feledje, hogy a számok tényleges megjelenése eltérhet az ország beállításaitól függően. Például néhány országban vesszőt használnak pont helyett tizedesjelként. Ez a szűrő ezt automatikusan figyelembe veszi, és nem kell semmiről gondoskodnia.

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

A stringet balról kiegészíti egy másik stringgel a megadott hosszúságra.

{='helló'|padLeft: 10, '123'}  {* kiírja: '12312helló' *}

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

A stringet jobbról kiegészíti egy másik stringgel a megadott hosszúságra.

{='helló'|padRight: 10, '123'}  {* kiírja: 'helló12312' *}

query

Dinamikusan generál query stringet az URL-ben:

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

Kiírja:

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

A null értékű kulcsok kimaradnak.

Lásd még escapeUrl.

random

Visszaadja a tömb véletlen elemét vagy a string véletlen karakterét:

{=[1, 2, 3, 4]|random}    {* kiírja pl.: 3 *}
{='abcd'|random}          {* kiírja pl.: 'b' *}

Lásd még first, last.

repeat (int $count)

A stringet x-szer ismétli.

{='helló'|repeat: 3}  {* kiírja: 'hellóhellóhelló' *}

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

A keresett string összes előfordulását lecseréli a helyettesítő stringre.

{='helló világ'|replace: 'világ', 'barát'}  {* kiírja: 'helló barát' *}

Több cserét is végre lehet hajtani egyszerre:

{='helló világ'|replace: [h => l, l => h]}  {* kiírja: 'lehho vihág' *}

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

Reguláris kifejezés keresést végez cserével.

{='helló világ'|replaceRE: '/l.*/', 'l'}  {* kiírja: 'hel' *}

reverse

Megfordítja a megadott stringet vagy tömböt.

{var $s = 'Nette'}
{$s|reverse}    {* kiírja: 'etteN' *}
{var $a = ['N', 'e', 't', 't', 'e']}
{$a|reverse}    {* visszaadja: ['e', 't', 't', 'e', 'N'] *}

round (int $precision=0)

A számot a megadott pontosságra kerekíti.

{=3.4|round}        {* kiírja: 3      *}
{=3.5|round}        {* kiírja: 4      *}
{=135.79|round:1}   {* kiírja: 135.8  *}
{=135.79|round:3}   {* kiírja: 135.79 *}

Lásd még ceil, floor.

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

Kivon egy részt a tömbből vagy stringből.

{='helló'|slice: 1, 2}           {* kiírja: 'el' *}
{=['a', 'b', 'c']|slice: 1, 2}   {* kiírja: ['b', 'c'] *}

A szűrő úgy működik, mint a PHP array_slice függvénye tömbökre vagy az mb_substr stringekre, fallbackként az iconv_substr függvénnyel UTF‑8 módban.

Ha a start pozitív, a szekvencia ennyivel eltolva kezdődik a tömb/string elejétől. Ha negatív, a szekvencia ennyivel eltolva kezdődik a végétől.

Ha a length paraméter meg van adva és pozitív, a szekvencia ennyi elemet fog tartalmazni. Ha negatív length paramétert adunk át ennek a függvénynek, a szekvencia az eredeti tömb összes elemét tartalmazza, a start pozíciótól kezdve és a tömb végétől számított length elemmel korábban végződve. Ha ezt a paramétert nem adja meg, a szekvencia az eredeti tömb összes elemét tartalmazza, a start pozíciótól kezdve.

Alapértelmezés szerint a szűrő megváltoztatja a sorrendet és visszaállítja a tömb egész számú kulcsait. Ez a viselkedés megváltoztatható a preserveKeys true-ra állításával. A string kulcsok mindig megmaradnak, ettől a paramétertől függetlenül.

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

A szűrő rendezi a tömb vagy iterátor elemeit, és megőrzi azok asszociatív kulcsait. Ha a nemzeti beállítások be vannak állítva, a rendezés annak szabályai szerint történik, hacsak nincs megadva saját összehasonlító függvény.

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

Rendezett tömb fordított sorrendben:

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

Megadhat saját összehasonlító függvényt a rendezéshez (a példa megmutatja, hogyan lehet fordítani a rendezést a legnagyobbtól a legkisebbig):

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

A |sort szűrő lehetővé teszi az elemek kulcsok szerinti rendezését is:

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

Ha egy táblázatot egy adott oszlop szerint kell rendeznie, használhatja a by paramétert. A 'name' érték a példában azt jelzi, hogy a rendezés $item->name vagy $item['name'] szerint történik, attól függően, hogy $item tömb vagy objektum:

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

Definiálhat egy callback függvényt is, amely meghatározza az értéket, amely szerint rendezni kell:

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

Ugyanígy használható a byKey paraméter is.

spaceless

Eltávolítja a felesleges szóközöket a kimenetből. Használhatja a strip aliast is.

{block |spaceless}
	<ul>
		<li>Helló</li>
	</ul>
{/block}

Kiírja:

<ul> <li>Helló</li> </ul>

stripHtml

A HTML-t tiszta szöveggé alakítja. Tehát eltávolítja belőle a HTML tageket és a HTML entitásokat szöveggé alakítja.

{='<p>egy &lt; kettő</p>'|stripHtml}  {* kiírja: 'egy < kettő' *}

Az eredményül kapott tiszta szöveg természetesen tartalmazhat olyan karaktereket, amelyek HTML tageket képviselnek, például a '&lt;p&gt;'|stripHtml <p>-vé alakul. Semmi esetre se írja ki az így keletkezett szöveget |noescape-pel, mert ez biztonsági rés kialakulásához vezethet.

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

Kivon egy részt a stringből. Ezt a szűrőt felváltotta a slice szűrő.

{$string|substr: 1, 2}

translate (…$args)

Kifejezéseket fordít más nyelvekre. Ahhoz, hogy a szűrő elérhető legyen, be kell állítani a fordítót. Használhatja a fordítási tageket is.

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

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

Eltávolítja a szóközöket (vagy más karaktereket) a string elejéről és végéről.

{='  Szeretem a Latte-t.  '|trim}    {* kiírja: 'Szeretem a Latte-t.' *}
{='  Szeretem a Latte-t.'|trim: '.'} {* kiírja: '  Szeretem a Latte-t' *}

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

Levágja a stringet a megadott maximális hosszúságra, miközben megpróbálja megőrizni az egész szavakat. Ha a string rövidül, a végére három pontot tesz (ez a második paraméterrel megváltoztatható).

{var $title = 'Helló, hogy vagy?'}
{$title|truncate:5}  {* Hell…                *}
{$title|truncate:17} {* Helló, hogy va…      *}
{$title|truncate:30} {* Helló, hogy vagy?  *}

upper

A stringet nagybetűssé alakítja. Szükséges a mbstring PHP kiterjesztés.

{='latte'|upper}  {* kiírja: 'LATTE' *}

Lásd még capitalize, firstUpper, lower.

webalize

Az UTF‑8 stringet URL-ben használt formára alakítja.

ASCII-ra konvertálja. A szóközöket kötőjelekre cseréli. Eltávolítja azokat a karaktereket, amelyek nem alfanumerikusak, aláhúzások vagy kötőjelek. Kisbetűssé alakítja. Eltávolítja az elülső és hátsó szóközöket is.

{var $s = 'A mi 10. termékünk'}
{$s|webalize}   {* kiírja: 'a-mi-10-termekunk' *}

Szükséges a nette/utils könyvtár.