Filtros de Latte

Os filtros são funções que mudam ou formatam os dados para um formulário que desejamos. Este é um resumo dos filtros incorporados que estão disponíveis.

Há também filtros de fuga para HTML (escapeHtml e escapeHtmlComment), XML (escapeXml), JavaScript (escapeJs), CSS (escapeCss) e iCalendar (escapeICal), que Latte se utiliza graças à fuga consciente do contexto e você não precisa escrevê-los.

Latte os atributos src e href verificam automaticamente, de modo que quase não é necessário usar o filtro checkUrl.

Todos os filtros integrados trabalham com cordas codificadas UTF-8.

Utilização

O Latte permite a chamada de filtros utilizando a notação do sinal de canalização (o espaço precedente é permitido):

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

Os filtros podem ser acorrentados, nesse caso, eles se aplicam por ordem da esquerda para a direita:

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

Os parâmetros são colocados após o nome do filtro separado por dois pontos ou vírgula:

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

Os filtros podem ser aplicados por expressão:

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

Os 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));

Usamo-lo em um modelo como este:

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

Filtros

batch (int length, mixed item): array

Filtro que simplifica a listagem de dados lineares na forma de uma tabela. Ele retorna uma matriz com o determinado número de itens. Se você fornecer um segundo parâmetro, este é usado para preencher os itens em falta 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>

Impressões:

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

Consulte também a tag group e iterateWhile.

breakLines

Insere quebras de linha HTML antes de todas as novas linhas.

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

bytes (int precision = 2)

Formata o tamanho em bytes em um formato legível por humanos. Se a localidade estiver definida, serão usados os separadores decimais e de milhar correspondentes.

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

ceil (int precision = 0)

Arredonda um número até uma determinada precisão.

{=3.4|ceil}         {* saídas 4 *}
{=135.22|ceil:1}    {* saídas 135,3 *}
{=135.22|ceil:3}    {* saídas 135,22 *}

Veja também piso, redondo.

capitalize

Devolve uma versão do valor com base no título. As palavras começarão com letras maiúsculas, todos os caracteres restantes são minúsculos. Requer extensão PHP mbstring.

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

Ver também firstUpper, lower, upper.

checkUrl

Impõe a higienização do URL. Verifica se a variável contém uma URL da web (ou seja, protocolo HTTP/HTTPS) e impede a escrita de links que possam representar um risco de segurança.

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

Impressões:

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

Veja também nocheck.

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

Retorna o valor fixado para a faixa inclusiva de min e max.

{$level|clamp: 0, 255}

Também existe como função.

dataStream (string mimetype = detect)

Converte o conteúdo para o esquema URI de dados. Pode ser usado para inserir imagens em HTML ou CSS sem a necessidade de vincular arquivos externos.

Vamos ter uma imagem em uma variável $img = Image::fromFile('obrazek.gif'), então

<img src={$img|dataStream}>

Impressões, por exemplo:

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

Requer extensão PHP fileinfo.

date (string format)

Formata a data e a hora de acordo com a máscara usada pela função PHP date. O filtro aceita a data no formato de carimbo de data/hora do UNIX, como uma cadeia de caracteres ou como um objeto DateTimeInterface.

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

Consulte também localDate.

escapeUrl

Escapa a uma variável para ser usada como parâmetro na URL.

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

Veja também consulta.

explode (string separator = '')

Divide um fio pelo delimitador dado e retorna um conjunto de fios. Alias para split.

{='um,dois,três'|explodir:','}    {* retorna ['um', 'dois', 'três'] *}

Se o delimitador for uma cadeia vazia (valor padrão), a entrada será dividida em caracteres individuais:

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

Você também pode usar o pseudônimo split:

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

Veja também implodir.

first

Devolve o primeiro elemento de matriz ou caráter de corda:

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

Ver também último, aleatório.

floor (int precision = 0)

Arredonda um número para uma determinada precisão.

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

Veja também Cessar, redondo.

firstUpper

Converte uma primeira letra de valor em maiúsculas. Requer extensão PHP mbstring.

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

Veja também capitalizar, inferior, superior.

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

O filtro agrupa os dados de acordo com diferentes critérios.

Neste exemplo, as linhas da tabela são agrupadas pela coluna categoryId. O resultado é uma matriz de matrizes em que a chave é o valor da coluna categoryId. Leia as instruções detalhadas.

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

Consulte também batch, a função group e a tag iterateWhile.

implode (string glue = '')

Retorna um fio que é a concatenação das cordas na matriz. Alias para join.

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

Você também pode usar um pseudônimo join:

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

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

Indica um texto da esquerda por um determinado número de abas ou outros caracteres que especificamos no segundo argumento opcional. As linhas em branco não são indentadas.

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

Impressões:

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

last

Retorna o último elemento de matriz ou caráter de corda:

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

Veja também primeiro, aleatório.

length

Retorna o comprimento de um fio ou matriz.

• para cordas, ele retornará o comprimento em caracteres UTF-8
• para arrays, ele retornará a contagem dos itens
• para objetos que implementam a interface Countable, ele usará o valor de retorno da contagem()
• para objetos que implementam a interface IteratorAggregate, ele usará o valor de retorno do iterator_count()

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

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

Formata a data e a hora de acordo com a localidade, garantindo a exibição consistente e localizada dos dados de hora em diferentes idiomas e regiões. O filtro aceita a data como um carimbo de data/hora UNIX, uma cadeia de caracteres ou um objeto DateTimeInterface.

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

Se você usar o filtro sem nenhum parâmetro, ele emitirá a data no nível de formato longo, conforme explicado mais adiante.

a) Usando o formato

O parâmetro format descreve quais componentes de tempo devem ser exibidos. Ele usa códigos de letras, em que o número de repetições afeta a largura da saída:

A ordem dos códigos no formato não importa, pois a ordem dos componentes será exibida de acordo com as convenções da localidade. Portanto, o formato é independente da localidade. Por exemplo, o formato yyyyMMMMd na localidade en_US gera April 15, 2024, enquanto na localidade cs_CZ gera 15. dubna 2024:

b) Uso de estilos predefinidos

Os parâmetros date e time determinam o nível de detalhe da exibição de data e hora. Você pode escolher entre vários níveis: full, long, medium, short. Você pode exibir apenas a data, apenas a hora ou ambas:

Para a data, você também pode usar o prefixo relative- (por exemplo, relative-short), que para datas próximas ao presente exibirá yesterday, today, ou tomorrow; caso contrário, será exibido da maneira padrão.

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

Consulte também date.

lower

Converte um valor para minúsculas. Requer extensão PHP mbstring.

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

Ver também capitalize, firstUpper, upper.

nocheck

Impede a higienização automática da URL. Latte verifica automaticamente se a variável contém uma URL da web (ou seja, protocolo HTTP/HTTPS) e impede a escrita de links que possam representar um risco de segurança.

Se o link usa um esquema diferente, como javascript: ou data:, e você tem certeza de seu conteúdo, você pode desativar a verificação via |nocheck.

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

<a href={$link}>checked</a>
<a href={$link|nocheck}>unchecked</a>

Impressões:

<a href="">checked</a>
<a href="javascript:window.close()">unchecked</a>

Veja também checkUrl.

noescape

Desativa a fuga automática.

{var $trustedHtmlString = '<b>hello</b>'}
Escaped: {$trustedHtmlString}
Unescaped: {$trustedHtmlString|noescape}

Impressões:

Escaped: <b>hello</b>
Unescaped: <b>hello</b>

O mau uso do filtro noescape pode levar a uma vulnerabilidade XSS! Nunca o use a menos que você esteja absolutamente seguro do que está fazendo e que o fio que você está imprimindo vem de uma fonte confiável.

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

Formata um número com um número especificado de casas decimais. Se a localidade estiver definida, serão usados os separadores decimais e de milhar correspondentes.

{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 que você defina a aparência dos números exatamente de acordo com suas necessidades. Ele requer uma localidade definida. O formato consiste em vários caracteres especiais, cuja descrição completa pode ser encontrada na documentação DecimalFormat:

• <c id=6/> dígito obrigatório, sempre exibido, mesmo que seja zero
• # dígito opcional, exibido somente se o número tiver um dígito naquele local
• @ dígito significativo, ajuda a exibir o número com um determinado número de dígitos significativos
• . marca onde o separador decimal deve estar (vírgula ou ponto, dependendo da localidade)
• , usado para separar grupos de dígitos, geralmente milhares
• % multiplica o número por 100 e adiciona o sinal de porcentagem

Vamos dar uma olhada em alguns exemplos. No primeiro exemplo, duas casas decimais são obrigatórias; no segundo, são opcionais. O terceiro exemplo mostra o preenchimento com zeros em ambos os lados, e 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 do ponto decimal, devem ser exibidos, arredondando o número, se necessário:

{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 por um caractere ;. Dessa forma, por exemplo, os números positivos podem ser exibidos com um 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 de acordo com as configurações de localidade. Por exemplo, em alguns países, uma vírgula é usada em vez de um ponto como separador decimal. Esse filtro considera isso automaticamente, portanto, você não precisa se preocupar com isso.

padLeft (int length, string pad = ' ')

Coloca um cordel a um certo comprimento com outro cordel da esquerda.

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

padRight (int length, string pad = ' ')

Coloca um cordel a um certo comprimento com outro cordel da direita.

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

query

Dinamicamente, gera uma cadeia de consulta na URL:

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

Impressões:

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

As chaves com um valor de null são omitidas.

Veja também escapeUrl.

random

Devolve elemento aleatório de matriz ou caráter de corda:

{=[1, 2, 3, 4]|random}    {* example output: 3 *}
{='abcd'|random}          {* example output: 'b' *}

Ver também primeiro, último.

repeat (int count)

Repete a seqüência x-vezes.

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

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

Substitui todas as ocorrências da cadeia de busca pela cadeia de substituição.

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

Substituições múltiplas podem ser feitas de uma só vez:

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

replaceRE (string pattern, string replace = '')

Substitui todas as ocorrências de acordo com a expressão regular.

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

reverse

Inverte seqüência ou matriz dada.

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

round (int precision = 0)

Arredonda um número para uma dada precisão.

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

Veja também ceil, chão.

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

Extrai uma fatia de uma matriz ou um fio.

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

O filtro de fatias funciona como a função PHP array_slice para arrays e mb_substr para strings com um fallback para iconv_substr no modo UTF-8.

Se o início for não negativo, a seqüência começará nesse início na variável. Se o início for negativo, a seqüência começará tão longe do final da variável.

Se o comprimento for dado e for positivo, então a seqüência terá até muitos elementos nele. Se a variável for menor do que o comprimento, então somente os elementos variáveis disponíveis estarão presentes. Se o comprimento for dado e for negativo, então a seqüência interromperá que muitos elementos do final da variável. Se for omitido, então a seqüência terá tudo desde o offset até o final da variável.

O filtro reordenará e redefinirá as chaves da matriz inteira por padrão. Este comportamento pode ser alterado ajustando preserveKeys para 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 classifica os elementos de uma matriz ou iterador, preservando suas chaves associativas. Quando uma localidade é definida, a classificação segue suas regras, a menos que uma função de comparação personalizada seja especificada.

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

Array ordenados em ordem inversa.

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

Você pode especificar uma função de comparação personalizada para a classificação (o exemplo mostra como inverter a classificação do maior para o menor):

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

O filtro |sort também permite que você classifique os elementos por chave:

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

Se você precisar classificar uma tabela por uma coluna específica, poderá usar o parâmetro by. O valor 'name' no exemplo especifica que a classificação será feita por $row->name ou $row['name']dependendo do fato de $row ser uma matriz ou um objeto:

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

Você também pode definir uma função de retorno de chamada que determina o valor a ser classificado:

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

O parâmetro byKey pode ser usado da mesma forma.

spaceless

Remove espaços em branco desnecessários da produção. Você também pode usar o pseudônimo strip.

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

Impressões:

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

stripHtml

Converte HTML em texto simples. Ou seja, remove as tags HTML e converte entidades HTML em texto.

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

O texto simples resultante pode naturalmente conter caracteres que representam tags HTML, por exemplo '<p>'|stripHtml é convertido para <p>. Nunca envie o texto resultante com |noescape, pois isso pode levar a uma vulnerabilidade de segurança.

substr (int offset, int length = null)

Extrai uma fatia de um fio. Este filtro foi substituído por uma fatia de filtro.

{$string|substr: 1, 2}

translate (string message, …args)

Ela traduz expressões para outros idiomas. Para tornar o filtro disponível, é necessário instalar um tradutor. Você também pode usar as tags para a tradução.

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

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

Tire os personagens que lideram e seguem, por padrão, o espaço em branco.

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

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

Encurta um fio até o comprimento máximo dado, mas tenta preservar palavras inteiras. Se a cadeia for truncada, acrescenta elipses no final (isto pode ser alterado pelo 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 um valor em maiúsculas. Requer extensão PHP mbstring.

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

Veja também capitalizar, primeiroCima, mais baixo.

webalize

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 abre e desvia espaços em branco.

{var $s = 'Our 10. product'}
{$s|webalize}    {* outputs 'our-10-product' *}

Requer pacote nette/utils.