Filtros Latte
*************

.[perex]
Los filtros son funciones que cambian o formatean los datos de la forma que queramos. Este es un resumen de los filtros incorporados que están disponibles.

.[table-latte-filters]
|## Transformación de cadenas / matrices
| `batch` | [Listado de datos lineales en una tabla |#batch]
| `breakLines` | [Inserta saltos de línea HTML antes de todas las nuevas líneas |#breakLines]
| `bytes` | [formatea el tamaño en bytes |#bytes]
| `clamp` | [sujeta el valor al rango|#clamp]
| `dataStream` | [Conversión de protocolo URI de datos|#datastream]
| `date` | [Formatea la fecha |#date]
| `explode` | [divide una cadena por el delimitador dado |#explode]
| `first` | [devuelve el primer elemento de una matriz o carácter de una cadena |#first]
| `implode` | [une una matriz a una cadena |#implode]
| `indent` | [sangrar el texto desde la izquierda con un número de tabulaciones |#indent]
| `join` | [une una matriz con una cadena|#implode]
| `last` | [devuelve el último elemento de la matriz o carácter de la cadena |#last]
| `length` | [devuelve la longitud de una cadena o matriz |#length]
| `number` | [Formatea un número |#number]
| `padLeft` | [completa la cadena a la longitud dada desde la izquierda |#padLeft]
| `padRight` | [completa la cadena a la longitud dada desde la derecha|#padRight]
| `random` | [devuelve un elemento aleatorio de una matriz o un carácter de una cadena |#random]
| `repeat` | [repite la cadena |#repeat]
| `replace` | [reemplaza todas las ocurrencias de la cadena buscada con el reemplazo |#replace]
| `replaceRE` | [reemplaza todas las apariciones según la expresión regular |#replaceRE]
| `reverse` | [invierte una cadena o matriz UTF-8 |#reverse]
| `slice` | [Extrae una porción de una matriz o cadena |#slice]
| `sort` | [ordena una matriz |#sort]
| `spaceless` | [Elimina espacios en blanco |#spaceless], similar a la etiqueta [sin espacios |tags].
| `split` | [divide una cadena por el delimitador dado |#explode]
| `strip` | [elimina los espacios en blanco |#spaceless]
| `stripHtml` | [elimina etiquetas HTML y convierte entidades HTML en texto |#stripHtml]
| `substr` | [devuelve parte de la cadena|#substr]
| `trim` | [elimina los espacios en blanco de la cadena |#trim]
| `translate` | [traducción a otros idiomas|#translate]
| `truncate` | [acorta la longitud conservando palabras enteras |#truncate]
| `webalize` | [ajusta la cadena UTF-8 a la forma utilizada en la URL |#webalize]

.[table-latte-filters]
|## Mayúsculas
| `capitalize` | [minúsculas, la primera letra de cada palabra mayúsculas |#capitalize]
| `firstUpper` | [convierte la primera letra en mayúscula|#firstUpper]
| `lower` | [convierte una cadena en minúscula |#lower]
| `upper` | [convierte una cadena en mayúscula |#upper]

.[table-latte-filters]
|## Redondeo de números
| `ceil` | [redondea un número hacia arriba a una precisión dada|#ceil]
| `floor` | [redondea un número hacia abajo a una precisión dada|#floor]
| `round` | [redondea un número a una precisión dada|#round]

.[table-latte-filters]
|## Escape
| `escapeUrl` | [escapa parámetro en URL |#escapeUrl]
| `noescape` | [imprime una variable sin escapar|#noescape]
| `query` | [genera una cadena de consulta en la URL|#query]

También existen filtros de escapado para HTML (`escapeHtml` y `escapeHtmlComment`), XML (`escapeXml`), JavaScript (`escapeJs`), CSS (`escapeCss`) e iCalendar (`escapeICal`), que Latte utiliza por sí mismo gracias al [escapado consciente del |safety-first#Context-aware escaping] contexto y no es necesario escribirlos.

.[table-latte-filters]
|## Seguridad
| `checkUrl` | [desinfecta la cadena para su uso dentro del atributo href |#checkUrl]
| `nocheck` | [evita la desinfección automática de URLs |#nocheck]

Latte los atributos `src` y `href` [comprueba automáticamente |safety-first#link checking], por lo que casi no es necesario utilizar el filtro `checkUrl`.


.[note]
Todos los filtros incorporados funcionan con cadenas codificadas en UTF-8.


Utilización .[#toc-usage]
=========================

Latte permite llamar a filtros utilizando la notación del signo pipa (se permite el espacio precedente):

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

Los filtros pueden encadenarse, en cuyo caso se aplican en orden de izquierda a derecha:

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

Los parámetros se ponen después del nombre del filtro separados por dos puntos o coma:

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

Los filtros se pueden aplicar sobre la expresión:

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

Los filtros [personalizados |extending-latte#filters] se pueden registrar de esta manera:

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

Lo usamos en una plantilla como esta:

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


Filtros .[#toc-filters]
=======================


batch(int length, mixed item): array .[filter]
----------------------------------------------
Filtro que simplifica el listado de datos lineales en forma de tabla. Devuelve un array de array con el número de elementos dado. Si se proporciona un segundo parámetro, éste se utiliza para rellenar los elementos que faltan en la última fila.

```latte
{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:

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


breakLines .[filter]
--------------------
Inserta saltos de línea HTML antes de todas las nuevas líneas.

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


bytes(int precision = 2) .[filter]
----------------------------------
Formatea un tamaño en bytes a formato legible por humanos.

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


ceil(int precision = 0) .[filter]
---------------------------------
Redondea un número hasta una precisión dada.

```latte
{=3.4|ceil}         {* salidas 4      *}
{=135.22|ceil:1}    {* salidas 135.3  *}
{=135.22|ceil:3}    {* salidas 135.22 *}
```

Ver también [floor |#floor], [round |#round].


capitalize .[filter]
--------------------
Devuelve una versión en mayúsculas del valor. Las palabras comenzarán con mayúsculas, todos los caracteres restantes en minúsculas. Requiere la extensión PHP `mbstring`.

```latte
{='i like LATTE'|capitalize}  {* salidas 'I Like Latte' *}
```

Vea también [firstUpper |#firstUpper], [lower |#lower], [upper |#upper].


checkUrl .[filter]
------------------
Aplica la limpieza de URL. Comprueba si la variable contiene una URL web (es decir, protocolo HTTP/HTTPS) e impide la escritura de enlaces que puedan suponer un riesgo para la seguridad.

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

Imprime:

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

Véase también [nocheck |#nocheck].


clamp(int|float min, int|float max) .[filter]
---------------------------------------------
Devuelve el valor ajustado al rango inclusivo de mín y máx.

```latte
{$level|clamp: 0, 255}
```

También existe como [función |functions#clamp].


dataStream(string mimetype = detect) .[filter]
----------------------------------------------
Convierte el contenido en un esquema URI de datos. Puede utilizarse para insertar imágenes en HTML o CSS sin necesidad de enlazar archivos externos.

Tengamos una imagen en una variable `$img = Image::fromFile('obrazek.gif')`, entonces

```latte
<img src={$img|dataStream}>
```

Imprime por ejemplo

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

.[caution]
Requiere extensión PHP `fileinfo`.


date(string format) .[filter]
-----------------------------
Devuelve una fecha en el formato dado usando las opciones de las funciones PHP [php:strftime] o [php:date]. Filter obtiene una fecha como una marca de tiempo UNIX, una cadena o un objeto de tipo `DateTime`.

```latte
{$today|date:'%d.%m.%Y'}
{$today|date:'j. n. Y'}
```


escapeUrl .[filter]
-------------------
Escapa una variable para ser usada como parámetro en URL.

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

Véase también [query |#query].


explode(string separator = '') .[filter]
----------------------------------------
Divide una cadena por el delimitador dado y devuelve una matriz de cadenas. Alias de `split`.

```latte
{='one,two,three'|explode:','}    {* returns ['one', 'two', 'three'] *}
```

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

```latte
{='123'|explode}                  {* returns ['1', '2', '3'] *}
```

También puede utilizar el alias `split`:

```latte
{='1,2,3'|split:','}              {* returns ['1', '2', '3'] *}
```

Ver también [implode |#implode].


first .[filter]
---------------
Devuelve el primer elemento de un array o carácter de una cadena:

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

Ver también [last |#last], [random |#random].


floor(int precision = 0) .[filter]
----------------------------------
Redondea un número a una precisión dada.

```latte
{=3.5|floor}        {* salidas 3      *}
{=135.79|floor:1}   {* salidas 135.7  *}
{=135.79|floor:3}   {* salidas 135.79 *}
```

Ver también [ceil |#ceil], [round |#round].


firstUpper .[filter]
--------------------
Convierte la primera letra de un valor a mayúsculas. Requiere la extensión PHP `mbstring`.

```latte
{='the latte'|firstUpper}  {* salidas 'The latte' *}
```

Vea también [capitalize |#capitalize], [lower |#lower], [upper |#upper].


implode(string glue = '') .[filter]
-----------------------------------
Devuelve una cadena que es la concatenación de las cadenas de la matriz. Alias de `join`.

```latte
{=[1, 2, 3]|implode}      {* salidas '123' *}
{=[1, 2, 3]|implode:'|'}  {* salidas '1|2|3' *}
```

También puede utilizar un alias `join`:

```latte
{=[1, 2, 3]|join}         {* salidas '123' *}
```


indent(int level = 1, string char = "\t") .[filter]
---------------------------------------------------
Indenta un texto desde la izquierda un número determinado de tabulaciones u otros caracteres que especifiquemos en el segundo argumento opcional. Las líneas en blanco no se sangrarán.

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

Imprime:

```latte
<div>
	<p>Hello</p>
</div>
```


last .[filter]
--------------
Devuelve el último elemento del array o carácter de la cadena:

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

Ver también [first |#first], [random |#random].


length .[filter]
----------------
Devuelve la longitud de una cadena o matriz.

- para cadenas, devolverá la longitud en caracteres UTF-8
- para matrices, devolverá el recuento de elementos
- para objetos que implementen la interfaz Countable, utilizará el valor de retorno de count()
- para objetos que implementen la interfaz IteratorAggregate, utilizará el valor de retorno de iterator_count()


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


lower .[filter]
---------------
Convierte un valor a minúsculas. Requiere la extensión PHP `mbstring`.

```latte
{='LATTE'|lower}   {* salidas 'latte' *}
```

Vea también [capitalize |#capitalize], [firstUpper |#firstUpper], [upper |#upper].


nocheck .[filter]
-----------------
Evita la desinfección automática de URL. Latte [comprueba automáticamente |safety-first#Link checking] si la variable contiene una URL web (es decir, protocolo HTTP/HTTPS) e impide la escritura de enlaces que puedan suponer un riesgo para la seguridad.

Si el enlace utiliza un esquema diferente, como `javascript:` o `data:`, y está seguro de su contenido, puede desactivar la comprobación a través de `|nocheck`.

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

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

Imprime:

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

Véase también [checkUrl |#checkUrl].


noescape .[filter]
------------------
Desactiva el escape automático.

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

Imprime:

```latte
Escaped: &lt;b&gt;hello&lt;/b&gt;
Unescaped: <b>hello</b>
```

.[warning]
¡El mal uso del filtro `noescape` puede llevar a una vulnerabilidad XSS! Nunca lo utilices a menos que estés **absolutamente seguro** de lo que estás haciendo y de que la cadena que estás imprimiendo proviene de una fuente de confianza.


number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter]
------------------------------------------------------------------------------------
Formatea un número con un número dado de decimales. También puede especificar un carácter del punto decimal y del separador de miles.

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


padLeft(int length, string pad = ' ') .[filter]
-----------------------------------------------
Rellena una cadena de una longitud determinada con otra cadena de la izquierda.

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


padRight(int length, string pad = ' ') .[filter]
------------------------------------------------
Rellena una cadena de cierta longitud con otra cadena de la derecha.

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


query  .[filter]
----------------
Genera dinámicamente una cadena de consulta en la URL:

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

Imprime:

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

Las teclas con el valor `null` se omiten.

Véase también [escapeUrl |#escapeUrl].


random .[filter]
----------------
Devuelve un elemento aleatorio de una matriz o un carácter de una cadena:

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

Véase también [first |#first], [last |#last].


repeat(int count) .[filter]
---------------------------
Repite la cadena x veces.

```latte
{='hello'|repeat: 3}  {* salidas 'hellohellohello' *}
```


replace(string|array search, string replace = '') .[filter]
-----------------------------------------------------------
Sustituye todas las apariciones de la cadena de búsqueda por la cadena de sustitución.

```latte
{='hello world'|replace: 'world', 'friend'}  {* salidas 'hello friend' *}
```

Se pueden realizar varias sustituciones a la vez:

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


replaceRE(string pattern, string replace = '') .[filter]
--------------------------------------------------------
Reemplaza todas las ocurrencias según la expresión regular.

```latte
{='hello world'|replaceRE: '/l.*/', 'l'}  {* salidas 'hel' *}
```


reverse .[filter]
-----------------
Invierte la cadena o matriz dada.

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


round(int precision = 0) .[filter]
----------------------------------
Redondea un número a una precisión dada.

```latte
{=3.4|round}        {* salidas 3      *}
{=3.5|round}        {* salidas 4      *}
{=135.79|round:1}   {* salidas 135.8  *}
{=135.79|round:3}   {* salidas 135.79 *}
```

Ver también [ceil |#ceil], [floor |#floor].


slice(int start, int length = null, bool preserveKeys = false) .[filter]
------------------------------------------------------------------------
Extrae una porción de una matriz o una cadena.

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

El filtro de rebanada funciona como la función PHP `array_slice` para matrices y `mb_substr` para cadenas con un fallback a `iconv_substr` en modo UTF-8.

Si start es no negativo, la secuencia comenzará en ese inicio de la variable. Si start es negativo, la secuencia comenzará a esa distancia del final de la variable.

Si la longitud es positiva, la secuencia tendrá hasta ese número de elementos. Si la variable es más corta que la longitud, sólo estarán presentes los elementos disponibles de la variable. Si la longitud es negativa, la secuencia se detendrá a esa cantidad de elementos del final de la variable. Si se omite, entonces la secuencia tendrá todo desde offset hasta el final de la variable.

Filter reordenará y restablecerá las claves de la matriz de enteros por defecto. Este comportamiento puede cambiarse estableciendo preserveKeys a true. Las claves de cadena siempre se conservan, independientemente de este parámetro.


sort  .[filter]
---------------
Filtro que ordena un array y mantiene la asociación de índices.

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

Matriz ordenada en orden inverso.

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

Puede pasar su propia función de comparación como parámetro:

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


spaceless  .[filter]
--------------------
Elimina los espacios en blanco innecesarios de la salida. También puede utilizar el alias `strip`.

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

Imprime:

```latte
<ul> <li>Hello</li> </ul>
```


stripHtml .[filter]
-------------------
Convierte HTML en texto sin formato. Es decir, elimina las etiquetas HTML y convierte las entidades HTML en texto.

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

El texto plano resultante puede contener naturalmente caracteres que representen etiquetas HTML, por ejemplo `'&lt;p&gt;'|stripHtml` se convierte en `<p>`. Nunca envíe el texto resultante con `|noescape`, ya que esto puede dar lugar a una vulnerabilidad de seguridad.


substr(int offset, int length = null) .[filter]
-----------------------------------------------
Extrae una porción de una cadena. Este filtro ha sido sustituido por un filtro de [trozos |#slice].

```latte
{$string|substr: 1, 2}
```


translate(string message, ...args) .[filter]
--------------------------------------------
Traduce expresiones a otros idiomas. Para que el filtro esté disponible, es necesario [configurar el traductor |develop#TranslatorExtension]. También puede utilizar las [etiquetas para la traducción |tags#Translation].

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


trim(string charlist = " \t\n\r\0\x0B\u{A0}") .[filter]
-------------------------------------------------------
Elimina los caracteres iniciales y finales, por defecto los espacios en blanco.

```latte
{='  I like Latte.  '|trim}    {* salidas 'I like Latte.' *}
{='  I like Latte.'|trim: '.'} {* salidas '  I like Latte' *}
```


truncate(int length, string append = '…') .[filter]
---------------------------------------------------
Acorta una cadena a la longitud máxima dada, pero intenta conservar las palabras enteras. Si la cadena está truncada, añade elipsis al final (esto puede cambiarse con el segundo parámetro).

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


upper .[filter]
---------------
Convierte un valor a mayúsculas. Requiere la extensión PHP `mbstring`.

```latte
{='latte'|upper}  {* salidas 'LATTE' *}
```

Vea también [capitalize |#capitalize], [firstUpper |#firstUpper], [lower |#lower].


webalize .[filter]
------------------
Convierte a ASCII.

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

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

.[caution]
Requiere el paquete [nette/utils |utils:].