Filtros Latte
Nos templates, podemos usar funções que ajudam a modificar ou reformatar dados para a forma final. Chamamos eles de filtros.
capitalize |
minúsculas, primeira letra das palavras maiúscula |
firstUpper |
converte a primeira letra para maiúscula |
lower |
converte para minúsculas |
upper |
converte para maiúsculas |
ceil |
arredonda um número para cima para a precisão dada |
floor |
arredonda um número para baixo para a precisão dada |
round |
arredonda um número para a precisão dada |
escapeUrl |
escapa um parâmetro em uma URL |
noescape |
imprime uma variável sem escapar |
query |
gera uma query string em uma URL |
Além disso, existem filtros de escaping para HTML (escapeHtml
e escapeHtmlComment
), XML
(escapeXml
), JavaScript (escapeJs
), CSS (escapeCss
) e iCalendar (escapeICal
),
que o Latte usa por si só graças ao escaping sensível ao contexto e você
não precisa escrevê-los.
checkUrl |
trata um endereço URL contra entradas perigosas |
nocheck |
evita o tratamento automático do endereço URL |
Os atributos Latte src
e href
verificam automaticamente, então você quase nunca precisa
usar o filtro checkUrl
.
Todos os filtros padrão são destinados a strings na codificação UTF-8.
Uso
Os filtros são escritos após uma barra vertical (pode haver um espaço antes dela):
<h1>{$heading|upper}</h1>
Os filtros (em versões mais antigas, helpers) podem ser encadeados e são aplicados na ordem da esquerda para a direita:
<h1>{$heading|lower|capitalize}</h1>
Os parâmetros são inseridos após o nome do filtro, separados por dois pontos ou vírgulas:
<h1>{$heading|truncate:20,''}</h1>
Os filtros também podem ser aplicados a uma expressão:
{var $name = ($title|upper) . ($subtitle|lower)}</h1>
Filtros personalizados podem ser registrados desta forma:
$latte = new Latte\Engine;
$latte->addFilter('shortify', fn(string $s, int $len = 10) => mb_substr($s, 0, $len));
No template, ele é chamado assim:
<p>{$text|shortify}</p>
<p>{$text|shortify:100}</p>
Filtros
batch (int $length, mixed $item): array
Filtro que simplifica a exibição de dados lineares na forma de uma tabela. Retorna um array de arrays com o número especificado de itens. Se você fornecer um segundo parâmetro, ele será usado para preencher os itens ausentes na última linha.
{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>
Exibe:
<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>
Veja também group e a tag iterateWhile.
breakLines
Adiciona a tag HTML <br>
antes de cada caractere de nova linha.
{var $s = "Text & with \n newline"}
{$s|breakLines} {* exibe "Text & with <br>\n newline" *}
bytes (int $precision=2)
Formata o tamanho em bytes de forma legível por humanos. Se a localidade estiver definida, os separadores decimais e de milhares correspondentes serão usados.
{$size|bytes} 0 B, 1.25 GB, …
{$size|bytes:0} 10 B, 1 GB, …
ceil (int $precision=0)
Arredonda um número para cima para a precisão dada.
{=3.4|ceil} {* exibe 4 *}
{=135.22|ceil:1} {* exibe 135.3 *}
{=135.22|ceil:3} {* exibe 135.22 *}
capitalize
As palavras começarão com letras maiúsculas, todos os caracteres restantes serão minúsculos. Requer a extensão PHP
mbstring
.
{='i like LATTE'|capitalize} {* exibe 'I Like Latte' *}
Veja também firstUpper, lower, upper.
checkUrl
Força o tratamento do endereço URL. Verifica se a variável contém uma URL da web (ou seja, protocolo HTTP/HTTPS) e evita a exibição de links que podem representar um risco de segurança.
{var $link = 'javascript:window.close()'}
<a data-href={$link|checkUrl}>verificado</a>
<a data-href={$link}>não verificado</a>
Exibe:
<a data-href="">verificado</a>
<a data-href="javascript:window.close()">não verificado</a>
Veja também nocheck.
clamp (int|float $min, int|float $max)
Limita o valor ao intervalo inclusivo especificado de min e max.
{$level|clamp: 0, 255}
Existe também como função.
dataStream (string $mimetype=detect)
Converte o conteúdo para o esquema data URI. Com ele, é possível incorporar imagens em HTML ou CSS sem a necessidade de vincular arquivos externos.
Tenhamos na variável a imagem $img = Image::fromFile('imagem.gif')
, então
<img src={$img|dataStream}>
Exibe, por exemplo:
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA
AAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO
9TXL0Y4OHwAAAABJRU5ErkJggg==">
Requer a extensão PHP fileinfo
.
date (string $format)
Formata data e hora de acordo com a máscara usada pela função PHP date. O filtro aceita
a data no formato timestamp UNIX, como string ou objeto do tipo DateTimeInterface
.
{$today|date:'j. n. Y'}
Veja também localDate.
escapeUrl
Escapa uma variável para uso como parâmetro em uma URL.
<a href="http://example.com/{$name|escapeUrl}">{$name}</a>
Veja também query.
explode (string
$separator=''
)
Divide uma string em um array por um separador. Alias para split
.
{='one,two,three'|explode:','} {* retorna ['one', 'two', 'three'] *}
Se o separador for uma string vazia (valor padrão), a entrada será dividida em caracteres individuais:
{='123'|explode} {* retorna ['1', '2', '3'] *}
Você também pode usar o alias split
:
{='1,2,3'|split:','} {* retorna ['1', '2', '3'] *}
Veja também implode.
first
Retorna o primeiro elemento de um array ou caractere de uma string:
{=[1, 2, 3, 4]|first} {* exibe 1 *}
{='abcd'|first} {* exibe 'a' *}
floor (int $precision=0)
Arredonda um número para baixo para a precisão dada.
{=3.5|floor} {* exibe 3 *}
{=135.79|floor:1} {* exibe 135.7 *}
{=135.79|floor:3} {* exibe 135.79 *}
firstUpper
Converte a primeira letra para maiúscula. Requer a extensão PHP mbstring
.
{='the latte'|firstUpper} {* exibe 'The latte' *}
Veja também capitalize, lower, upper.
group (string|int|\Closure $by): array
O filtro agrupa dados por vários critérios.
Neste exemplo, as linhas da tabela são agrupadas pela coluna categoryId
. A saída é um array de arrays, onde a
chave é o valor na coluna categoryId
. Leia o tutorial
detalhado.
{foreach ($items|group: categoryId) as $categoryId => $categoryItems}
<ul>
{foreach $categoryItems as $item}
<li>{$item->name}</li>
{/foreach}
</ul>
{/foreach}
Veja também batch, a função group e a tag iterateWhile.
implode (string $glue=''
)
Retorna uma string que é a concatenação dos itens da sequência. Alias para join
.
{=[1, 2, 3]|implode} {* exibe '123' *}
{=[1, 2, 3]|implode:'|'} {* exibe '1|2|3' *}
Você também pode usar o alias join
:
{=[1, 2, 3]|join} {* exibe '123' *}
indent (int $level=1, string
$char="\t"
)
Indenta o texto da esquerda por um número especificado de tabulações ou outros caracteres, que podem ser especificados no segundo argumento. Linhas vazias não são indentadas.
<div>
{block |indent}
<p>Hello</p>
{/block}
</div>
Exibe:
<div>
<p>Hello</p>
</div>
last
Retorna o último elemento de um array ou caractere de uma string:
{=[1, 2, 3, 4]|last} {* exibe 4 *}
{='abcd'|last} {* exibe 'd' *}
length
Retorna o comprimento de uma string ou array.
- para strings, retorna o comprimento em caracteres UTF-8
- para arrays, retorna o número de itens
- para objetos que implementam a interface Countable, usa o valor de retorno do método count()
- para objetos que implementam a interface IteratorAggregate, usa o valor de retorno da função iterator_count()
{if ($users|length) > 10}
...
{/if}
localDate (?string $format=null, ?string $date=null, ?string $time=null)
Formata data e hora de acordo com a localidade, o que garante uma
exibição consistente e localizada de informações de tempo em diferentes idiomas e regiões. O filtro aceita a data como
timestamp UNIX, string ou objeto do tipo DateTimeInterface
.
{$date|localDate} {* 15 de abril de 2024 *}
{$date|format: yM} {* 4/2024 *}
{$date|localDate: date: medium} {* 15/04/2024 *}
Se você usar o filtro sem parâmetros, a data será exibida no nível long
, veja abaixo.
a) uso do formato
O parâmetro format
descreve quais componentes de tempo devem ser exibidos. Ele usa códigos de letras para eles,
cujo número de repetições afeta a largura da saída:
ano | y / yy / yyyy |
2024 / 24 / 2024 |
mês | M / MM / MMM / MMMM |
8 / 08 / ago / agosto |
dia | d / dd / E / EEEE |
1 / 01 / dom / domingo |
hora | j / H / h |
preferido / 24 horas / 12 horas |
minuto | m / mm |
5 / 05 (2 dígitos em combinação com segundos) |
segundo | s / ss |
8 / 08 (2 dígitos em combinação com minutos) |
A ordem dos códigos no formato não importa, pois a ordem dos componentes será exibida de acordo com os costumes da
localidade. O formato é, portanto, independente dela. Por exemplo, o formato yyyyMMMMd
no ambiente
en_US
exibe April 15, 2024
, enquanto no ambiente cs_CZ
exibe
15. dubna 2024
:
locale: | cs_CZ | en_US |
---|---|---|
format: 'dMy' |
10. 8. 2024 | 8/10/2024 |
format: 'yM' |
8/2024 | 8/2024 |
format: 'yyyyMMMM' |
srpen 2024 | August 2024 |
format: 'MMMM' |
srpen | August |
format: 'jm' |
17:22 | 5:22 PM |
format: 'Hm' |
17:22 | 17:22 |
format: 'hm' |
5:22 odp. | 5:22 PM |
b) uso de estilos predefinidos
Os parâmetros date
e time
determinam com que detalhe a data e a hora devem ser exibidas. Você pode
escolher entre vários níveis: full
, long
, medium
, short
. É possível exibir
apenas a data, apenas a hora ou ambos:
locale: | cs_CZ | en_US |
---|---|---|
date: short |
23.01.78 | 1/23/78 |
date: medium |
23. 1. 1978 | Jan 23, 1978 |
date: long |
23. ledna 1978 | January 23, 1978 |
date: full |
pondělí 23. ledna 1978 | Monday, January 23, 1978 |
time: short |
8:30 | 8:30 AM |
time: medium |
8:30:59 | 8:30:59 AM |
time: long |
8:30:59 SEČ | 8:30:59 AM GMT+1 |
date: short, time: short |
23.01.78 8:30 | 1/23/78, 8:30 AM |
date: medium, time: short |
23. 1. 1978 8:30 | Jan 23, 1978, 8:30 AM |
date: long, time: short |
23. ledna 1978 v 8:30 | January 23, 1978 at 8:30 AM |
Para a data, também pode ser usado o prefixo relative-
(por exemplo, relative-short
), que para
datas próximas ao presente exibirá ontem
, hoje
ou amanhã
, caso contrário, será exibido
da maneira padrão.
{$date|localDate: date: relative-short} {* ontem *}
Veja também date.
lower
Converte uma string para minúsculas. Requer a extensão PHP mbstring
.
{='LATTE'|lower} {* exibe 'latte' *}
Veja também capitalize, firstUpper, upper.
nocheck
Evita o tratamento automático do endereço URL. O Latte verifica automaticamente se a variável contém uma URL da web (ou seja, protocolo HTTP/HTTPS) e evita a exibição de links que podem representar um risco de segurança.
Se o link usar outro esquema, como javascript:
ou data:
, e você tiver certeza do seu conteúdo,
pode desativar a verificação usando |nocheck
.
{var $link = 'javascript:window.close()'}
<a href={$link}>verificado</a>
<a href={$link|nocheck}>não verificado</a>
Exibe:
<a href="">verificado</a>
<a href="javascript:window.close()">não verificado</a>
Veja também checkUrl.
noescape
Desativa o escaping automático.
{var $trustedHtmlString = '<b>hello</b>'}
Escapado: {$trustedHtmlString}
Não escapado: {$trustedHtmlString|noescape}
Exibe:
Escapado: <b>hello</b>
Não escapado: <b>hello</b>
O uso incorreto do filtro noescape
pode levar à vulnerabilidade XSS! Nunca o use a menos que
tenha certeza absoluta do que está fazendo e que a string exibida vem de uma fonte confiável.
number (int $decimals=0, string
$decPoint='.'
, string $thousandsSep=','
)
Formata um número para um certo número de casas decimais. Se a localidade estiver definida, os separadores decimais e de milhares correspondentes serão usados.
{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)
O parâmetro format
permite definir a aparência dos números exatamente de acordo com suas necessidades. Para
isso, é necessário ter a localidade configurada. O formato consiste
em vários caracteres especiais, cuja descrição completa pode ser encontrada na documentação DecimalFormat:
0
dígito obrigatório, sempre será exibido, mesmo que seja zero#
dígito opcional, será exibido apenas se o número realmente existir neste local@
dígito significativo, ajuda a exibir o número com um certo número de dígitos válidos.
indica onde deve estar a vírgula decimal (ou ponto, dependendo do país),
serve para separar grupos de dígitos, mais comumente milhares%
multiplica o número por 100× e adiciona o sinal de porcentagem
Vamos dar uma olhada nos exemplos. No primeiro exemplo, duas casas decimais são obrigatórias, no segundo, opcionais. O terceiro exemplo mostra o preenchimento com zeros à esquerda e à direita, o quarto exibe apenas os dígitos existentes:
{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 *}
Os dígitos significativos determinam quantos dígitos, independentemente da vírgula decimal, devem ser exibidos, com arredondamento:
{1234|number: '@@'} {* 1200 *}
{1234|number: '@@@'} {* 1230 *}
{1234|number: '@@@#'} {* 1234 *}
{1.2345|number: '@@@'} {* 1.23 *}
{0.00123|number: '@@'} {* 0.0012 *}
Uma maneira fácil de exibir um número como porcentagem. O número é multiplicado por 100× e o sinal %
é
adicionado:
{0.1234|number: '#.##%'} {* 12.34% *}
Podemos definir um formato diferente para números positivos e negativos, separados pelo caractere ;
. Desta forma,
por exemplo, pode-se definir que números positivos devem ser exibidos com o sinal +
:
{42|number: '#.##;(#.##)'} {* 42 *}
{-42|number: '#.##;(#.##)'} {* (42) *}
{42|number: '+#.##;-#.##'} {* +42 *}
{-42|number: '+#.##;-#.##'} {* -42 *}
Lembre-se de que a aparência real dos números pode variar dependendo das configurações do país. Por exemplo, em alguns países, usa-se vírgula em vez de ponto como separador decimal. Este filtro leva isso em consideração automaticamente e você não precisa se preocupar com nada.
padLeft (int $length, string
$pad=' '
)
Preenche uma string até um certo comprimento com outra string pela esquerda.
{='hello'|padLeft: 10, '123'} {* exibe '12312hello' *}
padRight (int $length, string
$pad=' '
)
Preenche uma string até um certo comprimento com outra string pela direita.
{='hello'|padRight: 10, '123'} {* exibe 'hello12312' *}
query
Gera dinamicamente uma query string em uma URL:
<a href="http://example.com/?{[name: 'John Doe', age: 43]|query}">clique</a>
<a href="http://example.com/?search={$search|query}">pesquisar</a>
Exibe:
<a href="http://example.com/?name=John+Doe&age=43">clique</a>
<a href="http://example.com/?search=Foo+Bar">pesquisar</a>
Chaves com valor null
são omitidas.
Veja também escapeUrl.
random
Retorna um elemento aleatório de um array ou caractere de uma string:
{=[1, 2, 3, 4]|random} {* exibe por ex.: 3 *}
{='abcd'|random} {* exibe por ex.: 'b' *}
repeat (int $count)
Repete uma string x vezes.
{='hello'|repeat: 3} {* exibe 'hellohellohello' *}
replace (string|array $search, string
$replace=''
)
Substitui todas as ocorrências da string de pesquisa pela string de substituição.
{='hello world'|replace: 'world', 'friend'} {* exibe 'hello friend' *}
É possível realizar várias substituições de uma vez:
{='hello world'|replace: [h => l, l => h]} {* exibe 'lehho worhd' *}
replaceRE (string $pattern, string
$replace=''
)
Realiza uma pesquisa de expressão regular com substituição.
{='hello world'|replaceRE: '/l.*/', 'l'} {* exibe 'hel' *}
reverse
Inverte a string ou array fornecido.
{var $s = 'Nette'}
{$s|reverse} {* exibe 'etteN' *}
{var $a = ['N', 'e', 't', 't', 'e']}
{$a|reverse} {* retorna ['e', 't', 't', 'e', 'N'] *}
round (int $precision=0)
Arredonda um número para a precisão dada.
{=3.4|round} {* exibe 3 *}
{=3.5|round} {* exibe 4 *}
{=135.79|round:1} {* exibe 135.8 *}
{=135.79|round:3} {* exibe 135.79 *}
slice (int $start, ?int $length=null, bool $preserveKeys=false)
Extrai uma parte de um array ou string.
{='hello'|slice: 1, 2} {* exibe 'el' *}
{=['a', 'b', 'c']|slice: 1, 2} {* exibe ['b', 'c'] *}
O filtro funciona como a função PHP array_slice
para arrays ou mb_substr
para strings com fallback
para a função iconv_substr
no modo UTF-8.
Se start for positivo, a sequência começará deslocada por este número a partir do início do array/string. Se for negativo, a sequência começará deslocada por tanto a partir do fim.
Se o parâmetro length for especificado e for positivo, a sequência conterá tantos elementos. Se um parâmetro length negativo for passado para esta função, a sequência conterá todos os elementos do array original, começando na posição start e terminando na posição menor em length elementos a partir do fim do array. Se este parâmetro não for especificado, a sequência conterá todos os elementos do array original, começando na posição start.
Por padrão, o filtro reordena e redefine as chaves inteiras do array. Este comportamento pode ser alterado definindo preserveKeys como true. As chaves de string são sempre preservadas, independentemente deste parâmetro.
sort (?Closure $comparison, string|int|\Closure|null $by=null, string|int|\Closure|bool $byKey=false)
O filtro ordena os elementos de um array ou iterador e preserva suas chaves associativas. Quando a localidade está definida, a ordenação segue suas regras, a menos que uma função de comparação personalizada seja especificada.
{foreach ($names|sort) as $name}
...
{/foreach}
Array ordenado em ordem inversa:
{foreach ($names|sort|reverse) as $name}
...
{/foreach}
Você pode especificar uma função de comparação personalizada para ordenação (o exemplo mostra como inverter a ordenação do maior para o menor):
{var $reverted = ($names|sort: fn($a, $b) => $b <=> $a)}
O filtro |sort
também permite ordenar elementos por chaves:
{foreach ($names|sort: byKey: true) as $name}
...
{/foreach}
Se você precisar ordenar uma tabela por uma coluna específica, pode usar o parâmetro by
. O valor
'name'
no exemplo especifica que a ordenação será por $item->name
ou $item['name']
,
dependendo se $item
é um array ou objeto:
{foreach ($items|sort: by: 'name') as $item}
{$item->name}
{/foreach}
Você também pode definir uma função de callback que determinará o valor pelo qual ordenar:
{foreach ($items|sort: by: fn($items) => $items->category->name) as $item}
{$item->name}
{/foreach}
O parâmetro byKey
pode ser usado da mesma maneira.
spaceless
Remove espaços em branco desnecessários da saída. Você também pode usar o alias strip
.
{block |spaceless}
<ul>
<li>Hello</li>
</ul>
{/block}
Exibe:
<ul> <li>Hello</li> </ul>
stripHtml
Converte HTML para texto puro. Ou seja, remove as tags HTML e converte as entidades HTML em texto.
{='<p>one < two</p>'|stripHtml} {* exibe 'one < two' *}
O texto puro resultante pode naturalmente conter caracteres que representam tags HTML, por exemplo,
'<p>'|stripHtml
é convertido para <p>
. Em nenhuma circunstância exiba o texto
resultante com |noescape
, pois isso pode levar a uma falha de segurança.
substr (int $offset, ?int $length=null)
Extrai uma parte de uma string. Este filtro foi substituído pelo filtro slice.
{$string|substr: 1, 2}
translate (…$args)
Traduz expressões para outros idiomas. Para que o filtro esteja disponível, é necessário configurar o tradutor. Você também pode usar tags para tradução.
<a href="basket">{='Carrinho'|translate}</a>
<span>{$item|translate}</span>
trim (string
$charlist=" \t\n\r\0\x0B\u{A0}"
)
Remove espaços em branco (ou outros caracteres) do início e do fim de uma string.
{=' I like Latte. '|trim} {* exibe 'I like Latte.' *}
{=' I like Latte.'|trim: '.'} {* exibe ' I like Latte' *}
truncate (int $length, string
$append='…'
)
Corta uma string para o comprimento máximo especificado, tentando preservar palavras inteiras. Se a string for encurtada, adiciona reticências no final (pode ser alterado com o segundo parâmetro).
{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 uma string para maiúsculas. Requer a extensão PHP mbstring
.
{='latte'|upper} {* exibe 'LATTE' *}
Veja também capitalize, firstUpper, lower.
webalize
Modifica uma string UTF-8 para a forma usada em URLs.
Converte para ASCII. Converte espaços em hífens. Remove caracteres que não são alfanuméricos, sublinhados ou hífens. Converte para minúsculas. Também remove espaços iniciais e finais.
{var $s = 'Nosso 10º produto'}
{$s|webalize} {* exibe 'nosso-10-produto' *}
Requer a biblioteca nette/utils.