Filtros Latte

En las plantillas, podemos usar funciones que ayudan a modificar o reformatear los datos a su forma final. Los llamamos filtros.

Además, existen filtros de escape para HTML (escapeHtml y escapeHtmlComment), XML (escapeXml), JavaScript (escapeJs), CSS (escapeCss) e iCalendar (escapeICal), que Latte utiliza por sí mismo gracias al escape sensible al contexto y no necesita escribirlos.

Latte comprueba automáticamente los atributos src y href, por lo que casi nunca necesitará usar el filtro checkUrl.

Todos los filtros predeterminados están diseñados para cadenas en codificación UTF‑8.

Uso

Los filtros se escriben después de una barra vertical (puede haber un espacio antes de ella):

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

Los filtros (en versiones anteriores, helpers) se pueden encadenar y se aplican en orden de izquierda a derecha:

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

Los parámetros se especifican después del nombre del filtro, separados por dos puntos o comas:

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

Los filtros también se pueden aplicar a una expresión:

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

Los Filtros personalizados se pueden registrar de esta manera:

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

Luego se llama en la plantilla así:

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

Filtros

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

Filtro que simplifica la visualización de datos lineales en forma de tabla. Devuelve un array de arrays con el número especificado de elementos. Si especifica el segundo parámetro, se utiliza para rellenar los elementos faltantes en la última fila.

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

Imprime:

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

Vea también group y la etiqueta iterateWhile.

breakLines

Añade la etiqueta HTML <br> antes de cada carácter de nueva línea.

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

bytes (int $precision=2)

Formatea el tamaño en bytes en un formato legible por humanos. Si se establece la configuración regional, se utilizan los separadores decimales y de miles correspondientes.

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

ceil (int $precision=0)

Redondea un número hacia arriba a la precisión dada.

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

Vea también floor, round.

capitalize

Las palabras comenzarán con mayúsculas, todos los caracteres restantes estarán en minúsculas. Requiere la extensión PHP mbstring.

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

Vea también firstUpper, lower, upper.

checkUrl

Fuerza el saneamiento de la dirección URL. Comprueba si la variable contiene una URL web (es decir, protocolo HTTP/HTTPS) y evita la impresión de enlaces que puedan suponer un riesgo de seguridad.

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

Imprime:

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

Vea también nocheck.

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

Limita el valor al rango inclusivo dado de min y max.

{$level|clamp: 0, 255}

También existe como función.

dataStream (string $mimetype=detect)

Convierte el contenido al esquema data URI. Permite insertar imágenes en HTML o CSS sin necesidad de enlazar archivos externos.

Supongamos que tenemos una imagen en la variable $img = Image::fromFile('imagen.gif'), entonces

<img src={$img|dataStream}>

Imprime, por ejemplo:

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

Requiere la extensión PHP fileinfo.

date (string $format)

Formatea la fecha y la hora según la máscara utilizada por la función PHP date. El filtro acepta la fecha en formato de marca de tiempo UNIX, como cadena o como objeto de tipo DateTimeInterface.

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

Vea también localDate.

escapeUrl

Escapa una variable para usarla como parámetro en una URL.

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

Vea también query.

explode (string $separator='')

Divide una cadena en un array por un delimitador. Alias para split.

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

Si el delimitador es una cadena vacía (valor predeterminado), la entrada se dividirá en caracteres individuales:

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

También puede usar el alias split:

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

Vea también implode.

first

Devuelve el primer elemento de un array o carácter de una cadena:

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

Vea también last, random.

floor (int $precision=0)

Redondea un número hacia abajo a la precisión dada.

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

Vea también ceil, round.

firstUpper

Convierte la primera letra a mayúscula. Requiere la extensión PHP mbstring.

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

Vea también capitalize, lower, upper.

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

El filtro agrupa los datos según diferentes criterios.

En este ejemplo, las filas de la tabla se agrupan por la columna categoryId. La salida es un array de arrays donde la clave es el valor de la columna categoryId. Lea el tutorial detallado.

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

Vea también batch, la función group y la etiqueta iterateWhile.

implode (string $glue='')

Devuelve una cadena que es la concatenación de los elementos de una secuencia. Alias para join.

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

También puede usar el alias join:

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

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

Indenta el texto desde la izquierda un número determinado de tabuladores u otros caracteres, que podemos especificar en el segundo argumento. Las líneas vacías no se indentan.

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

Imprime:

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

last

Devuelve el último elemento de un array o carácter de una cadena:

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

Vea también first, random.

length

Devuelve la longitud de una cadena o un array.

• para cadenas, devuelve la longitud en caracteres UTF‑8
• para arrays, devuelve el número de elementos
• para objetos que implementan la interfaz Countable, utiliza el valor de retorno del método count()
• para objetos que implementan la interfaz IteratorAggregate, utiliza el valor de retorno de la función iterator_count()

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

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

Formatea la fecha y la hora según la configuración regional, lo que garantiza una visualización consistente y localizada de los datos de tiempo en diferentes idiomas y regiones. El filtro acepta la fecha como marca de tiempo UNIX, cadena u objeto de tipo DateTimeInterface.

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

Si utiliza el filtro sin parámetros, la fecha se mostrará en el nivel long, vea más abajo.

a) Uso del formato

El parámetro format describe qué componentes de tiempo se deben mostrar. Utiliza códigos de letras para ellos, cuyo número de repeticiones afecta el ancho de la salida:

El orden de los códigos en el formato no importa, ya que el orden de los componentes se mostrará según las convenciones de la configuración regional. Por lo tanto, el formato es independiente de ella. Por ejemplo, el formato yyyyMMMMd en el entorno en_US mostrará April 15, 2024, mientras que en el entorno es_ES mostrará 15 de abril de 2024:

b) Uso de estilos preestablecidos

Los parámetros date y time determinan con qué detalle se deben mostrar la fecha y la hora. Puede elegir entre varios niveles: full, long, medium, short. Puede mostrar solo la fecha, solo la hora o ambas:

Para la fecha, también puede usar el prefijo relative- (por ejemplo, relative-short), que para fechas cercanas a la actual mostrará ayer, hoy o mañana, de lo contrario se mostrará de la manera estándar.

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

Vea también date.

lower

Convierte una cadena a minúsculas. Requiere la extensión PHP mbstring.

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

Vea también capitalize, firstUpper, upper.

nocheck

Evita el saneamiento automático de la dirección URL. Latte comprueba automáticamente si la variable contiene una URL web (es decir, protocolo HTTP/HTTPS) y evita la impresión de enlaces que puedan suponer un riesgo de seguridad.

Si el enlace utiliza otro esquema, como javascript: o data:, y está seguro de su contenido, puede desactivar la comprobación con |nocheck.

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

<a href={$link}>comprobado</a>
<a href={$link|nocheck}>no comprobado</a>

Imprime:

<a href="">comprobado</a>
<a href="javascript:window.close()">no comprobado</a>

Vea también checkUrl.

noescape

Deshabilita el escape automático.

{var $trustedHtmlString = '<b>hello</b>'}
Escapado: {$trustedHtmlString}
No escapado: {$trustedHtmlString|noescape}

Imprime:

Escapado: <b>hello</b>
No escapado: <b>hello</b>

¡El uso incorrecto del filtro noescape puede llevar a una vulnerabilidad XSS! Nunca lo use si no está completamente seguro de lo que está haciendo y de que la cadena que se imprime proviene de una fuente confiable.

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

Formatea un número a un número específico de lugares decimales. Si se establece la configuración regional, se utilizan los separadores decimales y de miles correspondientes.

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

El parámetro format permite definir la apariencia de los números exactamente según sus necesidades. Para ello, es necesario tener establecida la configuración regional. El formato consta de varios caracteres especiales, cuya descripción completa encontrará en la documentación de DecimalFormat:

• 0 dígito obligatorio, siempre se muestra, aunque sea cero
• # dígito opcional, se muestra solo si realmente hay un número en esa posición
• @ dígito significativo, ayuda a mostrar el número con un cierto número de dígitos significativos
• . indica dónde debe estar la coma decimal (o el punto, según el país)
• , sirve para separar grupos de dígitos, generalmente miles
• % multiplica el número por 100 y añade el signo de porcentaje

Veamos algunos ejemplos. En el primer ejemplo, se requieren dos lugares decimales, en el segundo son opcionales. El tercer ejemplo muestra el relleno con ceros a la izquierda y a la derecha, el cuarto muestra solo los 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 *}

Los dígitos significativos determinan cuántos dígitos se deben mostrar independientemente de la coma decimal, redondeando:

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

Una forma fácil de mostrar un número como porcentaje. El número se multiplica por 100 y se añade el signo %:

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

Podemos definir un formato diferente para números positivos y negativos, separados por el carácter ;. De esta manera, por ejemplo, se puede configurar que los números positivos se muestren con el signo +:

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

Recuerde que la apariencia real de los números puede variar según la configuración del país. Por ejemplo, en algunos países se utiliza una coma en lugar de un punto como separador decimal. Este filtro lo tiene en cuenta automáticamente y no tiene que preocuparse por nada.

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

Rellena una cadena hasta una longitud determinada con otra cadena desde la izquierda.

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

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

Rellena una cadena hasta una longitud determinada con otra cadena desde la derecha.

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

query

Genera dinámicamente una cadena de consulta en una URL:

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

Imprime:

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

Las claves con valor null se omiten.

Vea también escapeUrl.

random

Devuelve un elemento aleatorio de un array o carácter de una cadena:

{=[1, 2, 3, 4]|random}    {* imprime por ejemplo: 3 *}
{='abcd'|random}          {* imprime por ejemplo: 'b' *}

Vea también first, last.

repeat (int $count)

Repite una cadena x veces.

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

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

Reemplaza todas las ocurrencias de la cadena de búsqueda con la cadena de reemplazo.

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

También se pueden realizar múltiples reemplazos a la vez:

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

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

Realiza una búsqueda de expresiones regulares con reemplazo.

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

reverse

Invierte la cadena o el array dado.

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

round (int $precision=0)

Redondea un número a la precisión dada.

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

Vea también ceil, floor.

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

Extrae una parte de un array o cadena.

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

El filtro funciona como la función PHP array_slice para arrays o mb_substr para cadenas con fallback a la función iconv_substr en modo UTF‑8.

Si start es positivo, la secuencia comenzará desplazada este número desde el inicio del array/cadena. Si es negativo, la secuencia comenzará desplazada tanto desde el final.

Si se especifica el parámetro length y es positivo, la secuencia contendrá tantos elementos. Si se pasa un parámetro length negativo a esta función, la secuencia contendrá todos los elementos del array original, comenzando en la posición start y terminando en la posición menor a length elementos desde el final del array. Si no especifica este parámetro, la secuencia contendrá todos los elementos del array original, comenzando en la posición start.

Por defecto, el filtro cambia el orden y restablece las claves enteras del array. Este comportamiento se puede cambiar estableciendo preserveKeys a true. Las claves de cadena siempre se conservan, independientemente de este parámetro.

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

El filtro ordena los elementos de un array o iterador y conserva sus claves asociativas. Si se establece la configuración regional, la ordenación se rige por sus reglas, a menos que se especifique una función de comparación personalizada.

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

Array ordenado en orden inverso:

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

Puede especificar una función de comparación personalizada para la ordenación (el ejemplo muestra cómo invertir la ordenación de mayor a menor):

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

El filtro |sort también permite ordenar elementos por claves:

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

Si necesita ordenar una tabla por una columna específica, puede usar el parámetro by. El valor 'name' en el ejemplo indica que se ordenará por $item->name o $item['name'], dependiendo de si $item es un array o un objeto:

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

También puede definir una función de callback que determine el valor por el cual ordenar:

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

De la misma manera, también se puede utilizar el parámetro byKey.

spaceless

Elimina los espacios en blanco innecesarios de la salida. También puede usar el alias strip.

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

Imprime:

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

stripHtml

Convierte HTML a texto plano. Es decir, elimina las etiquetas HTML y convierte las entidades HTML en texto.

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

El texto plano resultante puede contener naturalmente caracteres que representan etiquetas HTML, por ejemplo, '<p>'|stripHtml se convierte en <p>. En ningún caso imprima el texto resultante con |noescape, ya que esto puede llevar a un agujero de seguridad.

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

Extrae una parte de una cadena. Este filtro ha sido reemplazado por el filtro slice.

{$string|substr: 1, 2}

translate (…$args)

Traduce expresiones a otros idiomas. Para que el filtro esté disponible, es necesario configurar el traductor. También puede usar etiquetas para traducción.

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

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

Elimina los caracteres en blanco (u otros caracteres) del principio y el final de una cadena.

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

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

Recorta una cadena a la longitud máxima especificada, intentando conservar palabras completas. Si la cadena se acorta, añade puntos suspensivos al final (se puede cambiar con el 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

Convierte una cadena a mayúsculas. Requiere la extensión PHP mbstring.

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

Vea también capitalize, firstUpper, lower.

webalize

Modifica una cadena UTF‑8 a la forma utilizada en las URL.

Se convierte a ASCII. Convierte los espacios en guiones. Elimina los caracteres que no son alfanuméricos, guiones bajos o guiones. Convierte a minúsculas. También elimina los espacios iniciales y finales.

{var $s = 'Nuestro 10º producto'}
{$s|webalize}   {* imprime 'nuestro-10-producto' *}

Requiere la librería nette/utils.