Filtri Latte

V predlogah lahko uporabljamo funkcije, ki pomagajo urediti ali preoblikovati podatke v končno obliko. Imenujemo jih filtri.

Poleg tega obstajajo filtri za ubežanje znakov za HTML (escapeHtml in escapeHtmlComment), XML (escapeXml), JavaScript (escapeJs), CSS (escapeCss) in iCalendar (escapeICal), ki jih Latte uporablja samo zaradi kontekstno občutljivega ubežanja in jih ni treba zapisovati.

Latte atributa src in href samodejno preverja, zato filtra checkUrl skoraj ni treba uporabljati.

Vsi privzeti filtri so namenjeni nizom v kodiranju UTF‑8.

Uporaba

Filtri se zapisujejo za navpičnico (pred njo je lahko presledek):

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

Filtre (v starejših različicah helperje) je mogoče verižiti, nato pa se uporabljajo v vrstnem redu od leve proti desni:

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

Parametri se vnašajo za imenom filtra, ločeni z dvopičji ali vejicami:

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

Filtre je mogoče uporabiti tudi na izrazu:

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

Filtri po meri se lahko registrirajo na ta način:

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

V predlogi se nato kliče takole:

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

Filtri

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

Filter, ki poenostavlja izpis linearnih podatkov v obliki tabele. Vrne polje polj z določenim številom elementov. Če podate drugi parameter, se uporabi za dopolnitev manjkajočih elementov v zadnji vrstici.

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

Izpiše:

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

Glejte tudi group in oznako iterateWhile.

breakLines

Doda pred vsak znak nove vrstice oznako HTML <br>.

{var $s = "Text & with \n newline"}
{$s|breakLines}    {* izpiše "Text &amp; with <br>\n newline" *}

bytes (int $precision=2)

Formatira velikost v bajtih v človeku berljivo obliko. Če so nastavljene lokalne nastavitve, se uporabijo ustrezna ločila za decimalna mesta in tisočice.

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

ceil (int $precision=0)

Zaokroži število navzgor na dano natančnost.

{=3.4|ceil}         {* izpiše 4      *}
{=135.22|ceil:1}    {* izpiše 135.3  *}
{=135.22|ceil:3}    {* izpiše 135.22 *}

Glejte tudi floor, round.

capitalize

Besede se bodo začele z velikimi črkami, vsi preostali znaki bodo mali. Zahteva razširitev PHP mbstring.

{='i like LATTE'|capitalize}  {* izpiše 'I Like Latte' *}

Glejte tudi firstUpper, lower, upper.

checkUrl

Vsili obdelavo naslova URL. Preverja, ali spremenljivka vsebuje spletni URL (tj. protokol HTTP/HTTPS) in preprečuje izpis povezav, ki lahko predstavljajo varnostno tveganje.

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

Izpiše:

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

Glejte tudi nocheck.

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

Omeji vrednost na dano vključno območje min in max.

{$level|clamp: 0, 255}

Obstaja tudi kot funkcija.

dataStream (string $mimetype=detect)

Pretvori vsebino v shemo data URI. Z njo je mogoče v HTML ali CSS vstavljati slike brez potrebe po povezovanju zunanjih datotek.

Imejmo sliko v spremenljivki $img = Image::fromFile('slika.gif'), potem

<img src={$img|dataStream}>

Izpiše na primer:

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

Zahteva razširitev PHP fileinfo.

date (string $format)

Formatira datum in čas glede na masko, ki jo uporablja funkcija PHP date. Filter sprejema datum v formatu UNIX timestamp, kot niz ali objekt tipa DateTimeInterface.

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

Glejte tudi localDate.

escapeUrl

Ubeža spremenljivko za uporabo kot parameter v URL.

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

Glejte tudi query.

explode (string $separator='')

Razdeli niz na polje glede na ločilo. Alias za split.

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

Če je ločilo prazen niz (privzeta vrednost), bo vhod razdeljen na posamezne znake:

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

Lahko uporabite tudi alias split:

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

Glejte tudi implode.

first

Vrne prvi element polja ali znak niza:

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

Glejte tudi last, random.

floor (int $precision=0)

Zaokroži število navzdol na dano natančnost.

{=3.5|floor}        {* izpiše 3      *}
{=135.79|floor:1}   {* izpiše 135.7  *}
{=135.79|floor:3}   {* izpiše 135.79 *}

Glejte tudi ceil, round.

firstUpper

Pretvori prvo črko v veliko. Zahteva razširitev PHP mbstring.

{='the latte'|firstUpper}  {* izpiše 'The latte' *}

Glejte tudi capitalize, lower, upper.

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

Filter združi podatke po različnih kriterijih.

V tem primeru se vrstice v tabeli združujejo po stolpcu categoryId. Izpis je polje polj, kjer je ključ vrednost v stolpcu categoryId. Preberite podrobna navodila.

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

Glejte tudi batch, funkcijo group in oznako iterateWhile.

implode (string $glue='')

Vrne niz, ki je združitev elementov zaporedja. Alias za join.

{=[1, 2, 3]|implode}      {* izpiše '123' *}
{=[1, 2, 3]|implode:'|'}  {* izpiše '1|2|3' *}

Lahko uporabite tudi alias join:

{=[1, 2, 3]|join}         {* izpiše '123' *}

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

Zamika besedilo z leve za dano število tabulatorjev ali drugih znakov, ki jih lahko navedemo v drugem argumentu. Prazne vrstice niso zamaknjene.

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

Izpiše:

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

last

Vrne zadnji element polja ali znak niza:

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

Glejte tudi first, random.

length

Vrne dolžino niza ali polja.

• za nize vrne dolžino v znakih UTF‑8
• za polja vrne število elementov
• za objekte, ki implementirajo vmesnik Countable, uporabi vračano vrednost metode count()
• za objekte, ki implementirajo vmesnik IteratorAggregate, uporabi vračano vrednost funkcije iterator_count()

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

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

Formatira datum in čas glede na lokalne nastavitve, kar zagotavlja dosleden in lokaliziran prikaz časovnih podatkov med različnimi jeziki in regijami. Filter sprejema datum kot UNIX timestamp, niz ali objekt tipa DateTimeInterface.

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

Če uporabite filter brez parametrov, se izpiše datum na ravni long, glejte spodaj.

a) uporaba formata

Parameter format opisuje, katere časovne komponente naj se prikažejo. Uporablja črkovne kode, katerih število ponovitev vpliva na širino izpisa:

Vrstni red kod v formatu ni pomemben, saj se vrstni red komponent izpiše glede na navade lokalnih nastavitev. Format je torej od njega neodvisen. Na primer, format yyyyMMMMd v okolju en_US izpiše April 15, 2024, medtem ko v okolju sl_SI izpiše 15. april 2024:

b) uporaba prednastavljenih stilov

Parametra date in time določata, kako podrobno naj se izpišeta datum in čas. Izbirate lahko med več ravnmi: full, long, medium, short. Lahko pustite izpisati samo datum, samo čas ali oboje:

Pri datumu lahko dodatno uporabite predpono relative- (npr. relative-short), ki za datume blizu sedanjosti prikaže včeraj, danes ali jutri, sicer se izpiše na standardni način.

{$date|localDate: date: relative-short}    {* včeraj *}

Glejte tudi date.

lower

Pretvori niz v male črke. Zahteva razširitev PHP mbstring.

{='LATTE'|lower}   {* izpiše 'latte' *}

Glejte tudi capitalize, firstUpper, upper.

nocheck

Prepreči samodejno obdelavo naslova URL. Latte samodejno preverja, ali spremenljivka vsebuje spletni URL (tj. protokol HTTP/HTTPS) in preprečuje izpis povezav, ki lahko predstavljajo varnostno tveganje.

Če povezava uporablja drugo shemo, npr. javascript: ali data:, in ste prepričani o njeni vsebini, lahko preverjanje izklopite s pomočjo |nocheck.

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

<a href={$link}>preverjeno</a>
<a href={$link|nocheck}>nepreverjeno</a>

Izpiše:

<a href="">preverjeno</a>
<a href="javascript:window.close()">nepreverjeno</a>

Glejte tudi checkUrl.

noescape

Onemogoči samodejno ubežanje znakov.

{var $trustedHtmlString = '<b>hello</b>'}
Ubežano: {$trustedHtmlString}
Neubežano: {$trustedHtmlString|noescape}

Izpiše:

Ubežano: <b>hello</b>
Neubežano: <b>hello</b>

Napačna uporaba filtra noescape lahko vodi do nastanka ranljivosti XSS! Nikoli ga ne uporabljajte, če niste popolnoma prepričani, kaj počnete, in da izpisani niz prihaja iz zaupanja vrednega vira.

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

Formatira število na določeno število decimalnih mest. Če so nastavljene lokalne nastavitve, se uporabijo ustrezna ločila za decimalna mesta in tisočice.

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

Parameter format omogoča definiranje videza števil natančno po vaših potrebah. Za to je treba imeti nastavljene lokalne nastavitve. Format je sestavljen iz več posebnih znakov, katerih celoten opis najdete v dokumentaciji DecimalFormat:

• 0 obvezna števka, vedno se prikaže, tudi če je ničla
• # neobvezna števka, prikaže se samo, če na tem mestu število dejansko obstaja
• @ pomembna števka, pomaga prikazati število z določenim številom veljavnih števk
• . označuje, kje naj bo decimalna vejica (ali pika, odvisno od države)
• , služi za ločevanje skupin števk, najpogosteje tisočic
• % število pomnoži s 100× in doda znak za odstotek

Poglejmo si primere. V prvem primeru sta dve decimalni mesti obvezni, v drugem neobvezni. Tretji primer prikazuje dopolnjevanje z ničlami z leve in desne, četrti prikazuje samo obstoječe števke:

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

Pomembne števke določajo, koliko števk, ne glede na decimalno vejico, naj bo prikazanih, pri čemer se zaokrožuje:

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

Enostaven način za prikaz števila kot odstotka. Število se pomnoži s 100× in doda se znak %:

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

Lahko definiramo različen format za pozitivna in negativna števila, loči jih znak ;. Na ta način lahko na primer nastavimo, da se pozitivna števila prikazujejo z znakom +:

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

Ne pozabite, da se dejanski videz števil lahko razlikuje glede na nastavitve države. Na primer, v nekaterih državah se uporablja vejica namesto pike kot ločilo decimalnih mest. Ta filter to samodejno upošteva in vam ni treba skrbeti za nič.

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

Dopolni niz do določene dolžine z drugim nizom z leve.

{='hello'|padLeft: 10, '123'}  {* izpiše '12312hello' *}

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

Dopolni niz do določene dolžine z drugim nizom z desne.

{='hello'|padRight: 10, '123'}  {* izpiše 'hello12312' *}

query

Dinamično generira poizvedbeni niz v URL:

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

Izpiše:

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

Ključi z vrednostjo null se izpustijo.

Glejte tudi escapeUrl.

random

Vrne naključni element polja ali znak niza:

{=[1, 2, 3, 4]|random}    {* izpiše npr.: 3 *}
{='abcd'|random}          {* izpiše npr.: 'b' *}

Glejte tudi first, last.

repeat (int $count)

Ponavlja niz x-krat.

{='hello'|repeat: 3}  {* izpiše 'hellohellohello' *}

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

Nadomesti vse pojavitve iskalnega niza z nadomestnim nizom.

{='hello world'|replace: 'world', 'friend'}  {* izpiše 'hello friend' *}

Lahko izvedemo tudi več zamenjav hkrati:

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

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

Izvede iskanje regularnih izrazov z zamenjavo.

{='hello world'|replaceRE: '/l.*/', 'l'}  {* izpiše 'hel' *}

reverse

Obrne dani niz ali polje.

{var $s = 'Nette'}
{$s|reverse}    {* izpiše 'etteN' *}
{var $a = ['N', 'e', 't', 't', 'e']}
{$a|reverse}    {* vrne ['e', 't', 't', 'e', 'N'] *}

round (int $precision=0)

Zaokroži število na dano natančnost.

{=3.4|round}        {* izpiše 3      *}
{=3.5|round}        {* izpiše 4      *}
{=135.79|round:1}   {* izpiše 135.8  *}
{=135.79|round:3}   {* izpiše 135.79 *}

Glejte tudi ceil, floor.

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

Izvleče del polja ali niza.

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

Filter deluje kot funkcija PHP array_slice za polja ali mb_substr za nize z rezervno funkcijo iconv_substr v načinu UTF‑8.

Če je start pozitiven, se bo zaporedje začelo zamaknjeno za to število od začetka polja/niza. Če je negativen, se bo zaporedje začelo zamaknjeno za toliko od konca.

Če je podan parameter length in je pozitiven, bo zaporedje vsebovalo toliko elementov. Če je tej funkciji posredovan negativen parameter length, bo zaporedje vsebovalo vse elemente prvotnega polja, začenši na poziciji start in končavši na poziciji, manjši za length elementov od konca polja. Če tega parametra ne podate, bo zaporedje vsebovalo vse elemente prvotnega polja, začenši na poziciji start.

Privzeto filter spremeni vrstni red in ponastavi celoštevilske ključe polja. To vedenje lahko spremenite z nastavitvijo preserveKeys na true. Nizovni ključi se vedno ohranijo, ne glede na ta parameter.

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

Filter razvrsti elemente polja ali iteratorja in ohrani njihove asociativne ključe. Pri nastavljenih lokalnih nastavitvah se razvrščanje ravna po njegovih pravilih, če ni specificirana lastna primerjalna funkcija.

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

Razvrščeno polje v obratnem vrstnem redu:

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

Lahko specificirate lastno primerjalno funkcijo za razvrščanje (primer prikazuje, kako obrniti razvrščanje od največjega do najmanjšega):

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

Filter |sort omogoča tudi razvrščanje elementov po ključih:

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

Če morate razvrstiti tabelo po določenem stolpcu, lahko uporabite parameter by. Vrednost 'name' v primeru določa, da se bo razvrščalo po $item->name ali $item['name'], odvisno od tega, ali je $item polje ali objekt:

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

Lahko tudi definirate povratno funkcijo, ki določi vrednost, po kateri naj se razvršča:

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

Na enak način lahko uporabite tudi parameter byKey.

spaceless

Odstrani nepotrebne presledke iz izpisa. Lahko uporabite tudi alias strip.

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

Izpiše:

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

stripHtml

Pretvori HTML v čisto besedilo. Torej odstrani iz njega oznake HTML in entitete HTML pretvori v besedilo.

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

Rezultatno čisto besedilo lahko naravno vsebuje znake, ki predstavljajo oznake HTML, na primer '<p>'|stripHtml se pretvori v <p>. V nobenem primeru ne izpisujte tako nastalega besedila z |noescape, ker lahko to vodi do nastanka varnostne luknje.

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

Izvleče del niza. Ta filter je bil nadomeščen s filtrom slice.

{$string|substr: 1, 2}

translate (…$args)

Prevaja izraze v druge jezike. Da bi bil filter na voljo, je treba nastaviti prevajalnik. Lahko uporabite tudi oznake za prevajanje.

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

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

Odstrani prazne znake (ali druge znake) z začetka in konca niza.

{='  I like Latte.  '|trim}    {* izpiše 'I like Latte.' *}
{='  I like Latte.'|trim: '.'} {* izpiše '  I like Latte' *}

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

Obreže niz na navedeno največjo dolžino, pri čemer poskuša ohraniti cele besede. Če pride do skrajšanja niza, na koncu doda tri pike (lahko spremenite z drugim parametrom).

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

upper

Pretvori niz v velike črke. Zahteva razširitev PHP mbstring.

{='latte'|upper}  {* izpiše 'LATTE' *}

Glejte tudi capitalize, firstUpper, lower.

webalize

Prilagodi niz UTF‑8 v obliko, ki se uporablja v URL-jih.

Pretvarja se v ASCII. Pretvori presledke v pomišljaje. Odstrani znake, ki niso alfanumerični, podčrtaji ali pomišljaji. Pretvori v male črke. Prav tako odstrani začetne in končne presledke.

{var $s = 'Naš 10. produkt'}
{$s|webalize}   {* izpiše 'nas-10-produkt' *}

Zahteva knjižnico nette/utils.