Filtri Latte

Nei template possiamo utilizzare funzioni che aiutano a modificare o riformattare i dati nella loro forma finale. Li chiamiamo filtri.

Inoltre, esistono filtri di escaping per HTML (escapeHtml e escapeHtmlComment), XML (escapeXml), JavaScript (escapeJs), CSS (escapeCss) e iCalendar (escapeICal), che Latte utilizza autonomamente grazie all'escaping sensibile al contesto e non è necessario scriverli.

Gli attributi Latte src e href vengono controllati automaticamente, quindi non è quasi mai necessario utilizzare il filtro checkUrl.

Tutti i filtri predefiniti sono progettati per stringhe con codifica UTF‑8.

Utilizzo

I filtri vengono scritti dopo una barra verticale (può esserci uno spazio prima):

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

I filtri (nelle versioni precedenti helper) possono essere concatenati e vengono applicati nell'ordine da sinistra a destra:

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

I parametri vengono specificati dopo il nome del filtro, separati da due punti o virgole:

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

I filtri possono essere applicati anche a un'espressione:

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

Filtri personalizzati possono essere registrati in questo modo:

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

Nel template, viene quindi chiamato così:

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

Filtri

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

Filtro che semplifica la visualizzazione di dati lineari sotto forma di tabella. Restituisce un array di array con il numero specificato di elementi. Se si specifica il secondo parametro, verrà utilizzato per completare gli elementi mancanti nell'ultima riga.

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

Stampa:

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

Vedi anche group e il tag iterateWhile.

breakLines

Aggiunge un tag HTML <br> prima di ogni carattere di nuova riga.

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

bytes (int $precision=2)

Formatta la dimensione in byte in un formato leggibile dall'uomo. Se è impostata l'impostazione locale, verranno utilizzati i separatori decimali e delle migliaia corrispondenti.

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

ceil (int $precision=0)

Arrotonda un numero per eccesso alla precisione specificata.

{=3.4|ceil}         {* stampa 4      *}
{=135.22|ceil:1}    {* stampa 135.3  *}
{=135.22|ceil:3}    {* stampa 135.22 *}

Vedi anche floor, round.

capitalize

Le parole inizieranno con lettere maiuscole, tutti i caratteri rimanenti saranno minuscoli. Richiede l'estensione PHP mbstring.

{='i like LATTE'|capitalize}  {* stampa 'I Like Latte' *}

Vedi anche firstUpper, lower, upper.

checkUrl

Forza la pulizia dell'indirizzo URL. Controlla se la variabile contiene un URL web (cioè protocollo HTTP/HTTPS) e impedisce la visualizzazione di link che potrebbero rappresentare un rischio per la sicurezza.

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

Stampa:

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

Vedi anche nocheck.

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

Limita un valore all'interno dell'intervallo inclusivo specificato min e max.

{$level|clamp: 0, 255}

Esiste anche come funzione.

dataStream (string $mimetype=detect)

Converte il contenuto nello schema URI dei dati. Può essere utilizzato per incorporare immagini in HTML o CSS senza la necessità di collegare file esterni.

Supponiamo di avere un'immagine nella variabile $img = Image::fromFile('image.gif'), quindi

<img src={$img|dataStream}>

Stampa ad esempio:

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

Richiede l'estensione PHP fileinfo.

date (string $format)

Formatta data e ora secondo la maschera utilizzata dalla funzione PHP date. Il filtro accetta la data nel formato timestamp UNIX, come stringa o oggetto di tipo DateTimeInterface.

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

Vedi anche localDate.

escapeUrl

Esegue l'escaping di una variabile per l'uso come parametro in un URL.

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

Vedi anche query.

explode (string $separator='')

Divide una stringa in un array in base a un delimitatore. Alias per split.

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

Se il delimitatore è una stringa vuota (valore predefinito), l'input verrà diviso in singoli caratteri:

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

Puoi anche usare l'alias split:

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

Vedi anche implode.

first

Restituisce il primo elemento di un array o carattere di una stringa:

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

Vedi anche last, random.

floor (int $precision=0)

Arrotonda un numero per difetto alla precisione specificata.

{=3.5|floor}        {* stampa 3      *}
{=135.79|floor:1}   {* stampa 135.7  *}
{=135.79|floor:3}   {* stampa 135.79 *}

Vedi anche ceil, round.

firstUpper

Converte la prima lettera in maiuscolo. Richiede l'estensione PHP mbstring.

{='the latte'|firstUpper}  {* stampa 'The latte' *}

Vedi anche capitalize, lower, upper.

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

Il filtro raggruppa i dati secondo vari criteri.

In questo esempio, le righe della tabella vengono raggruppate per la colonna categoryId. L'output è un array di array, dove la chiave è il valore nella colonna categoryId. Leggi il tutorial dettagliato.

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

Vedi anche batch, la funzione group e il tag iterateWhile.

implode (string $glue='')

Restituisce una stringa che è la concatenazione degli elementi della sequenza. Alias per join.

{=[1, 2, 3]|implode}      {* stampa '123' *}
{=[1, 2, 3]|implode:'|'}  {* stampa '1|2|3' *}

Puoi anche usare l'alias join:

{=[1, 2, 3]|join}         {* stampa '123' *}

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

Indenta il testo da sinistra di un dato numero di tabulazioni o altri caratteri, che possiamo specificare nel secondo argomento. Le righe vuote non vengono indentate.

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

Stampa:

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

last

Restituisce l'ultimo elemento di un array o carattere di una stringa:

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

Vedi anche first, random.

length

Restituisce la lunghezza di una stringa o di un array.

• per le stringhe, restituisce la lunghezza in caratteri UTF‑8
• per gli array, restituisce il numero di elementi
• per gli oggetti che implementano l'interfaccia Countable, utilizza il valore restituito dal metodo count()
• per gli oggetti che implementano l'interfaccia IteratorAggregate, utilizza il valore restituito dalla funzione iterator_count()

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

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

Formatta data e ora secondo le impostazioni locali, garantendo una visualizzazione coerente e localizzata dei dati temporali tra diverse lingue e regioni. Il filtro accetta la data come timestamp UNIX, stringa o oggetto di tipo DateTimeInterface.

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

Se si utilizza il filtro senza parametri, la data verrà visualizzata al livello long, vedi oltre.

a) utilizzo del formato

Il parametro format descrive quali componenti temporali devono essere visualizzati. Utilizza codici letterali per questo, il cui numero di ripetizioni influenza la larghezza dell'output:

L'ordine dei codici nel formato non ha importanza, poiché l'ordine dei componenti viene visualizzato secondo le convenzioni delle impostazioni locali. Il formato è quindi indipendente da esse. Ad esempio, il formato yyyyMMMMd nell'ambiente en_US stampa April 15, 2024, mentre nell'ambiente it_IT stampa 15 aprile 2024:

b) utilizzo di stili preimpostati

I parametri date e time specificano quanto dettagliatamente devono essere visualizzati data e ora. È possibile scegliere tra diversi livelli: full, long, medium, short. È possibile visualizzare solo la data, solo l'ora o entrambi:

Per la data, è possibile utilizzare anche il prefisso relative- (es. relative-short), che per le date vicine a quella attuale visualizzerà ieri, oggi o domani, altrimenti verrà visualizzato nel modo standard.

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

Vedi anche date.

lower

Converte una stringa in minuscolo. Richiede l'estensione PHP mbstring.

{='LATTE'|lower}   {* stampa 'latte' *}

Vedi anche capitalize, firstUpper, upper.

nocheck

Impedisce la pulizia automatica dell'indirizzo URL. Latte controlla automaticamente se la variabile contiene un URL web (cioè protocollo HTTP/HTTPS) e impedisce la visualizzazione di link che potrebbero rappresentare un rischio per la sicurezza.

Se il link utilizza un altro schema, ad esempio javascript: o data:, e sei sicuro del suo contenuto, puoi disabilitare il controllo usando |nocheck.

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

<a href={$link}>controllato</a>
<a href={$link|nocheck}>non controllato</a>

Stampa:

<a href="">controllato</a>
<a href="javascript:window.close()">non controllato</a>

Vedi anche checkUrl.

noescape

Disabilita l'escaping automatico.

{var $trustedHtmlString = '<b>hello</b>'}
Escapato: {$trustedHtmlString}
Non escapato: {$trustedHtmlString|noescape}

Stampa:

Escapato: <b>hello</b>
Non escapato: <b>hello</b>

L'uso improprio del filtro noescape può portare a una vulnerabilità XSS! Non utilizzarlo mai a meno che tu non sia assolutamente sicuro di quello che stai facendo e che la stringa stampata provenga da una fonte attendibile.

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

Formatta un numero a un certo numero di cifre decimali. Se è impostata l'impostazione locale, verranno utilizzati i separatori decimali e delle migliaia corrispondenti.

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

Il parametro format consente di definire l'aspetto dei numeri esattamente secondo le proprie esigenze. Per questo è necessario aver impostato le impostazioni locali. Il formato è composto da diversi caratteri speciali, la cui descrizione completa si trova nella documentazione DecimalFormat:

• 0 cifra obbligatoria, viene sempre visualizzata, anche se è zero
• # cifra facoltativa, viene visualizzata solo se il numero è effettivamente presente in quella posizione
• @ cifra significativa, aiuta a visualizzare il numero con un certo numero di cifre significative
• . indica dove deve trovarsi la virgola decimale (o il punto, a seconda del paese)
• , serve per separare i gruppi di cifre, più comunemente le migliaia
• % moltiplica il numero per 100× e aggiunge il simbolo di percentuale

Vediamo alcuni esempi. Nel primo esempio, due cifre decimali sono obbligatorie, nel secondo facoltative. Il terzo esempio mostra il riempimento con zeri a sinistra e a destra, il quarto visualizza solo le cifre esistenti:

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

Le cifre significative determinano quante cifre devono essere visualizzate indipendentemente dalla virgola decimale, arrotondando:

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

Un modo semplice per visualizzare un numero come percentuale. Il numero viene moltiplicato per 100× e viene aggiunto il simbolo %:

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

Possiamo definire un formato diverso per i numeri positivi e negativi, separati dal carattere ;. In questo modo, ad esempio, è possibile impostare che i numeri positivi vengano visualizzati con il segno +:

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

Ricorda che l'aspetto effettivo dei numeri può variare a seconda delle impostazioni del paese. Ad esempio, in alcuni paesi si usa la virgola invece del punto come separatore decimale. Questo filtro lo tiene automaticamente in considerazione e non devi preoccuparti di nulla.

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

Riempie una stringa a una certa lunghezza con un'altra stringa da sinistra.

{='hello'|padLeft: 10, '123'}  {* stampa '12312hello' *}

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

Riempie una stringa a una certa lunghezza con un'altra stringa da destra.

{='hello'|padRight: 10, '123'}  {* stampa 'hello12312' *}

query

Genera dinamicamente una query string in un URL:

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

Stampa:

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

Le chiavi con valore null vengono omesse.

Vedi anche escapeUrl.

random

Restituisce un elemento casuale di un array o carattere di una stringa:

{=[1, 2, 3, 4]|random}    {* stampa ad es.: 3 *}
{='abcd'|random}          {* stampa ad es.: 'b' *}

Vedi anche first, last.

repeat (int $count)

Ripete una stringa x volte.

{='hello'|repeat: 3}  {* stampa 'hellohellohello' *}

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

Sostituisce tutte le occorrenze della stringa di ricerca con la stringa di sostituzione.

{='hello world'|replace: 'world', 'friend'}  {* stampa 'hello friend' *}

È possibile eseguire più sostituzioni contemporaneamente:

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

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

Esegue una ricerca tramite espressione regolare con sostituzione.

{='hello world'|replaceRE: '/l.*/', 'l'}  {* stampa 'hel' *}

reverse

Inverte la stringa o l'array specificato.

{var $s = 'Nette'}
{$s|reverse}    {* stampa 'etteN' *}
{var $a = ['N', 'e', 't', 't', 'e']}
{$a|reverse}    {* restituisce ['e', 't', 't', 'e', 'N'] *}

round (int $precision=0)

Arrotonda un numero alla precisione specificata.

{=3.4|round}        {* stampa 3      *}
{=3.5|round}        {* stampa 4      *}
{=135.79|round:1}   {* stampa 135.8  *}
{=135.79|round:3}   {* stampa 135.79 *}

Vedi anche ceil, floor.

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

Estrae una parte di un array o di una stringa.

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

Il filtro funziona come la funzione PHP array_slice per gli array o mb_substr per le stringhe con fallback alla funzione iconv_substr in modalità UTF‑8.

Se start è positivo, la sequenza inizierà spostata di questo numero dall'inizio dell'array/stringa. Se è negativo, la sequenza inizierà spostata di tanto dalla fine.

Se il parametro length è specificato ed è positivo, la sequenza conterrà tanti elementi. Se a questa funzione viene passato un parametro length negativo, la sequenza conterrà tutti gli elementi dell'array originale, iniziando dalla posizione start e terminando alla posizione minore di length elementi dalla fine dell'array. Se questo parametro non viene specificato, la sequenza conterrà tutti gli elementi dell'array originale, iniziando dalla posizione start.

Per impostazione predefinita, il filtro riordina e reimposta le chiavi intere dell'array. Questo comportamento può essere modificato impostando preserveKeys su true. Le chiavi stringa vengono sempre conservate, indipendentemente da questo parametro.

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

Il filtro ordina gli elementi di un array o di un iteratore e conserva le loro chiavi associative. Se sono impostate le impostazioni locali, l'ordinamento segue le sue regole, a meno che non sia specificata una funzione di confronto personalizzata.

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

Array ordinato in ordine inverso:

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

È possibile specificare una funzione di confronto personalizzata per l'ordinamento (l'esempio mostra come invertire l'ordinamento dal più grande al più piccolo):

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

Il filtro |sort consente anche di ordinare gli elementi per chiave:

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

Se è necessario ordinare una tabella per una colonna specifica, è possibile utilizzare il parametro by. Il valore 'name' nell'esempio specifica che l'ordinamento avverrà per $item->name o $item['name'], a seconda che $item sia un array o un oggetto:

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

È anche possibile definire una funzione di callback che determini il valore in base al quale ordinare:

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

Allo stesso modo si può utilizzare anche il parametro byKey.

spaceless

Rimuove gli spazi bianchi non necessari dall'output. Puoi anche usare l'alias strip.

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

Stampa:

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

stripHtml

Converte HTML in testo puro. Cioè, rimuove i tag HTML e converte le entità HTML in testo.

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

Il testo puro risultante può naturalmente contenere caratteri che rappresentano tag HTML, ad esempio '<p>'|stripHtml viene convertito in <p>. In nessun caso stampare il testo così generato con |noescape, poiché ciò può portare a una falla di sicurezza.

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

Estrae una parte di una stringa. Questo filtro è stato sostituito dal filtro slice.

{$string|substr: 1, 2}

translate (…$args)

Traduce le espressioni in altre lingue. Affinché il filtro sia disponibile, è necessario impostare il traduttore. È inoltre possibile utilizzare i tag per la traduzione.

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

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

Rimuove gli spazi bianchi (o altri caratteri) dall'inizio e dalla fine di una stringa.

{='  I like Latte.  '|trim}    {* stampa 'I like Latte.' *}
{='  I like Latte.'|trim: '.'} {* stampa '  I like Latte' *}

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

Tronca una stringa alla lunghezza massima specificata, cercando di preservare le parole intere. Se la stringa viene accorciata, aggiunge alla fine tre punti (modificabili con il secondo parametro).

{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 una stringa in maiuscolo. Richiede l'estensione PHP mbstring.

{='latte'|upper}  {* stampa 'LATTE' *}

Vedi anche capitalize, firstUpper, lower.

webalize

Modifica una stringa UTF‑8 nella forma utilizzata negli URL.

Converte in ASCII. Converte gli spazi in trattini. Rimuove i caratteri che non sono alfanumerici, trattini bassi o trattini. Converte in minuscolo. Rimuove anche gli spazi iniziali e finali.

{var $s = 'Náš 10. produkt'}
{$s|webalize}   {* stampa 'nas-10-produkt' *}

Richiede la libreria nette/utils.