Etiquetas Latte

Resumen y descripción de todas las etiquetas del sistema de plantillas Latte que están disponibles de forma estándar.

Impresión

{$var} {...} {=...}

En Latte se utiliza la etiqueta {=...} para imprimir cualquier expresión en la salida. Latte se preocupa por su comodidad, por lo que si la expresión comienza con una variable o una llamada de función, no es necesario escribir el signo igual. Lo que en la práctica significa que casi nunca es necesario escribirlo:

Nombre: {$name} {$surname}<br>
Edad: {date('Y') - $birth}<br>

Como expresión puede escribir cualquier cosa que conozca de PHP. Simplemente no tiene que aprender un nuevo lenguaje. Por ejemplo:

{='0' . ($num ?? $num * 3) . ', ' . PHP_VERSION}

Por favor, no busque ningún sentido en el ejemplo anterior, pero si encuentra alguno, escríbanos :-)

Escapado de la salida

¿Cuál es la tarea más importante de un sistema de plantillas? Prevenir agujeros de seguridad. Y eso es exactamente lo que hace Latte siempre que imprime algo. Lo escapa automáticamente:

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

Para ser precisos, Latte utiliza el escapado sensible al contexto, que es algo tan importante y único que le hemos dedicado un capítulo aparte.

¿Y qué pasa si imprime contenido codificado en HTML de una fuente confiable? Entonces se puede desactivar fácilmente el escapado:

{$trustedHtmlString|noescape}

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

Impresión en JavaScript

Gracias al escapado sensible al contexto, es maravillosamente fácil imprimir variables dentro de JavaScript y Latte se encarga del escapado correcto.

La variable no tiene por qué ser solo una cadena, se admite cualquier tipo de dato, que luego se codifica como JSON:

{var $foo = ['hello', true, 1]}
<script>
	alert({$foo});
</script>

Genera:

<script>
	alert(["hello", true, 1]);
</script>

Esa es también la razón por la que no se escriben comillas alrededor de la variable: Latte las añade por sí mismo para las cadenas. Y si quisiera insertar una variable de cadena en otra cadena, simplemente concaténelas:

<script>
	alert('Hello ' + {$name} + '!');  // OK

	alert({="Hello $name!"});         // OK

	alert('Hello {$name} !');         // ¡ERROR!
</script>

Filtros

La expresión impresa puede ser modificada por un filtro. Así, por ejemplo, convertimos una cadena a mayúsculas y la acortamos a un máximo de 30 caracteres:

{$string|upper|truncate:30}

También puede usar filtros en partes parciales de la expresión de esta manera:

{$left . ($middle|upper) . $right}

Condiciones

{if} {elseif} {else}

Las condiciones se comportan igual que sus contrapartes en PHP. Puede usar en ellas las mismas expresiones que conoce de PHP, no tiene que aprender un nuevo lenguaje.

{if $product->inStock > Stock::Minimum}
	En stock
{elseif $product->isOnWay()}
	En camino
{else}
	No disponible
{/if}

Como cualquier etiqueta par, el par {if} ... {/if} también se puede escribir en forma de n:atributo, por ejemplo:

<p n:if="$count > 0">En stock {$count} unidades</p>

¿Sabía que a los n:atributos puede adjuntar el prefijo tag-? Entonces la condición se referirá solo a la impresión de las etiquetas HTML y el contenido entre ellas se imprimirá siempre:

<a href="..." n:tag-if="$clickable">Hola</a>

{* imprime 'Hola' cuando $clickable es false *}
{* imprime '<a href="...">Hola</a>' cuando $clickable es true *}

Genial.

n:else

Si escribe la condición {if} ... {/if} en forma de n:atributo, tiene la opción de indicar también una rama alternativa usando n:else:

<strong n:if="$count > 0">En stock {$count} unidades</strong>

<em n:else>no disponible</em>

El atributo n:else también se puede usar en pareja con n:ifset, n:foreach, n:try, n:ifcontent y n:ifchanged.

{/if $cond}

Quizás le sorprenda que la expresión en la condición {if} también se pueda indicar en la etiqueta de cierre. Esto es útil en situaciones en las que al abrir la condición aún no conocemos su valor. Llamémoslo decisión diferida.

Por ejemplo, comenzamos a imprimir una tabla con registros de una base de datos y solo después de finalizar la impresión nos damos cuenta de que no había ningún registro en la base de datos. Entonces ponemos una condición en la etiqueta final {/if} y si no hay ningún registro, no se imprimirá nada de eso:

{if}
	<h1>Listado de filas de la base de datos</h1>

	<table>
	{foreach $resultSet as $row}
		...
	{/foreach}
	</table>
{/if isset($row)}

Ingenioso, ¿verdad?

En la condición diferida también se puede usar {else}, pero no {elseif}.

{ifset} {elseifset}

Vea también {ifset block}

Usando la condición {ifset $var} averiguamos si una variable (o varias variables) existe y tiene un valor no null. En realidad, es lo mismo que if (isset($var)) en PHP. Como cualquier etiqueta par, también se puede escribir en forma de n:atributo, así que mostrémoslo como ejemplo:

<meta name="robots" content={$robots} n:ifset="$robots">

{ifchanged}

{ifchanged} comprueba si el valor de una variable ha cambiado desde la última iteración en el bucle (foreach, for o while).

Si indicamos una o más variables en la etiqueta, comprobará si alguna de ellas ha cambiado y, en consecuencia, imprimirá el contenido. Por ejemplo, el siguiente ejemplo imprime la primera letra del nombre como título cada vez que cambia al imprimir los nombres:

{foreach ($names|sort) as $name}
	{ifchanged $name[0]} <h2>{$name[0]}</h2> {/ifchanged}

	<p>{$name}</p>
{/foreach}

Sin embargo, si no indicamos ningún argumento, se comprobará el contenido renderizado en comparación con su estado anterior. Esto significa que en el ejemplo anterior podemos omitir tranquilamente el argumento en la etiqueta. Y, por supuesto, también podemos usar un n:atributo:

{foreach ($names|sort) as $name}
	<h2 n:ifchanged>{$name[0]}</h2>

	<p>{$name}</p>
{/foreach}

Dentro de {ifchanged} también se puede indicar la cláusula {else}.

{switch} {case} {default}

Compara un valor con múltiples opciones. Es análogo a la sentencia condicional switch que conoce de PHP. Sin embargo, Latte lo mejora:

• utiliza comparación estricta (===)
• no necesita break

Es, por tanto, el equivalente exacto de la estructura match que introduce PHP 8.0.

{switch $transport}
	{case train}
		En tren
	{case plane}
		En avión
	{default}
		De otra manera
{/switch}

La cláusula {case} puede contener múltiples valores separados por comas:

{switch $status}
{case $status::New}<b>nuevo elemento</b>
{case $status::Sold, $status::Unknown}<i>no disponible</i>
{/switch}

Bucles

En Latte encontrará todos los bucles que conoce de PHP: foreach, for y while.

{foreach}

Escribimos el bucle exactamente igual que en PHP:

{foreach $langs as $code => $lang}
	<span>{$lang}</span>
{/foreach}

Además, tiene varias características ingeniosas de las que hablaremos ahora.

Latte, por ejemplo, comprueba si las variables creadas sobrescriben accidentalmente variables globales del mismo nombre. Esto salva situaciones en las que cuenta con que $lang contiene el idioma actual de la página y no se da cuenta de que foreach $langs as $lang le ha sobrescrito esa variable.

El bucle foreach también se puede escribir de forma muy elegante y económica mediante un n:atributo:

<ul>
	<li n:foreach="$items as $item">{$item->name}</li>
</ul>

¿Sabía que a los n:atributos puede adjuntar el prefijo inner-? Entonces solo se repetirá el interior del elemento en el bucle:

<div n:inner-foreach="$items as $item">
	<h4>{$item->title}</h4>
	<p>{$item->description}</p>
</div>

Así que se imprimirá algo como:

<div>
	<h4>Foo</h4>
	<p>Lorem ipsum.</p>
	<h4>Bar</h4>
	<p>Sit dolor.</p>
</div>

{else}

Dentro del bucle foreach se puede indicar la cláusula {else}, cuyo contenido se mostrará si el bucle está vacío:

<ul>
	{foreach $people as $person}
		<li>{$person->name}</li>
	{else}
		<li><em>Lo sentimos, no hay usuarios en esta lista</em></li>
	{/foreach}
</ul>

$iterator

Dentro del bucle foreach, Latte crea la variable $iterator, mediante la cual podemos averiguar información útil sobre el bucle en curso:

• $iterator->first – ¿es la primera pasada por el bucle?
• $iterator->last – ¿es la última pasada?
• $iterator->counter – ¿cuántas pasadas van contadas desde uno?
• $iterator->counter0 – ¿cuántas pasadas van contadas desde cero?
• $iterator->odd – ¿es una pasada impar?
• $iterator->even – ¿es una pasada par?
• $iterator->parent – el iterador que envuelve al actual
• $iterator->nextValue – el siguiente elemento en el bucle
• $iterator->nextKey – la clave del siguiente elemento en el bucle

{foreach $rows as $row}
	{if $iterator->first}<table>{/if}

	<tr id="row-{$iterator->counter}">
		<td>{$row->name}</td>
		<td>{$row->email}</td>
	</tr>

	{if $iterator->last}</table>{/if}
{/foreach}

Latte es astuto y $iterator->last funciona no solo con arrays, sino también cuando el bucle se ejecuta sobre un iterador general donde no se conoce de antemano el número de elementos.

{first} {last} {sep}

Estas etiquetas se pueden usar dentro del bucle {foreach}. El contenido de {first} se renderizará si es la primera pasada. El contenido de {last} se renderizará… ¿adivina? Sí, si es la última pasada. En realidad, son atajos para {if $iterator->first} y {if $iterator->last}.

Las etiquetas también se pueden usar elegantemente como n:atributo:

{foreach $rows as $row}
	{first}<h1>Lista de nombres</h1>{/first}

	<p>{$row->name}</p>

	<hr n:last>
{/foreach}

El contenido de la etiqueta {sep} se renderizará si la pasada no es la última, por lo que es útil para renderizar separadores, por ejemplo, comas entre los elementos impresos:

{foreach $items as $item} {$item} {sep}, {/sep} {/foreach}

Es bastante práctico, ¿verdad?

{iterateWhile}

Simplifica la agrupación de datos lineales durante la iteración en un bucle foreach realizando la iteración en un bucle anidado mientras se cumpla la condición. Lea el tutorial detallado.

También puede reemplazar elegantemente {first} y {last} en el ejemplo anterior:

{foreach $rows as $row}
	<table>

	{iterateWhile}
	<tr id="row-{$iterator->counter}">
		<td>{$row->name}</td>
		<td>{$row->email}</td>
	</tr>
	{/iterateWhile true}

	</table>
{/foreach}

Vea también los filtros batch y group.

{for}

Escribimos el bucle exactamente igual que en PHP:

{for $i = 0; $i < 10; $i++}
	<span>Elemento {$i}</span>
{/for}

La etiqueta también se puede usar como n:atributo:

<h1 n:for="$i = 0; $i < 10; $i++">{$i}</h1>

{while}

Nuevamente, escribimos el bucle exactamente igual que en PHP:

{while $row = $result->fetch()}
	<span>{$row->title}</span>
{/while}

O como n:atributo:

<span n:while="$row = $result->fetch()">
	{$row->title}
</span>

También es posible una variante con la condición en la etiqueta final, que corresponde en PHP al bucle do-while:

{while}
	<span>{$item->title}</span>
{/while $item = $item->getNext()}

{continueIf} {skipIf} {breakIf}

Para controlar cualquier bucle se pueden usar las etiquetas {continueIf ?} y {breakIf ?}, que pasan al siguiente elemento o terminan el bucle respectivamente si se cumple la condición:

{foreach $rows as $row}
	{continueIf $row->date < $now}
	{breakIf $row->parent === null}
	...
{/foreach}

La etiqueta {skipIf} es muy similar a {continueIf}, pero no incrementa el contador $iterator->counter, por lo que si lo imprimimos y al mismo tiempo saltamos algunos elementos, no habrá huecos en la numeración. Y también la cláusula {else} se renderizará si saltamos todos los elementos.

<ul>
	{foreach $people as $person}
		{skipIf $person->age < 18}
		<li>{$iterator->counter}. {$person->name}</li>
	{else}
		<li><em>Lo sentimos, no hay adultos en esta lista</em></li>
	{/foreach}
</ul>

{exitIf}

Termina el renderizado de la plantilla o bloque si se cumple la condición (llamado “early exit”).

{exitIf !$messages}

<h1>Mensajes</h1>
<div n:foreach="$messages as $message">
   {$message}
</div>

Inclusión de plantillas

{include 'file.latte'}

Vea también {include block}

La etiqueta {include} carga y renderiza la plantilla especificada. Si habláramos en el lenguaje de nuestro querido lenguaje PHP, sería algo como:

<?php include 'header.phtml'; ?>

Las plantillas incluidas no tienen acceso a las variables del contexto activo, solo tienen acceso a las variables globales.

Puede pasar variables a la plantilla incluida de esta manera:

{include 'template.latte', foo: 'bar', id: 123}

El nombre de la plantilla puede ser cualquier expresión en PHP:

{include $someVar}
{include $ajax ? 'ajax.latte' : 'not-ajax.latte'}

El contenido incluido se puede modificar mediante filtros. El siguiente ejemplo elimina todo el HTML y ajusta las mayúsculas/minúsculas:

<title>{include 'heading.latte' |stripHtml|capitalize}</title>

Por defecto, la herencia de plantillas no figura de ninguna manera en este caso. Aunque podemos usar bloques en la plantilla incluida, no se reemplazarán los bloques correspondientes en la plantilla en la que se incluye. Piense en las plantillas incluidas como partes independientes y aisladas de páginas o módulos. Este comportamiento se puede cambiar usando el modificador with blocks:

{include 'template.latte' with blocks}

La relación entre el nombre de archivo especificado en la etiqueta y el archivo en el disco es asunto del loader.

{sandbox}

Al incluir una plantilla creada por el usuario final, debería considerar el modo sandbox (más información en la documentación del sandbox):

{sandbox 'untrusted.latte', level: 3, data: $menu}

{block}

Vea también {block name}

Los bloques sin nombre sirven como una forma de aplicar filtros a una parte de la plantilla. Por ejemplo, así se puede aplicar el filtro strip, que elimina los espacios innecesarios:

{block|strip}
<ul>
	<li>Hello World</li>
</ul>
{/block}

Manejo de excepciones

{try}

Gracias a esta etiqueta, es extremadamente fácil crear plantillas robustas.

Si ocurre una excepción durante el renderizado del bloque {try}, todo el bloque se descarta y el renderizado continuará después de él:

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
{/try}

El contenido en la cláusula opcional {else} se renderizará solo si ocurre una excepción:

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
	{else}
	<p>Lo sentimos, no se pudieron cargar los tweets.</p>
{/try}

La etiqueta también se puede usar como n:atributo:

<ul n:try>
	...
</ul>

También es posible definir un manejador de excepciones personalizado, por ejemplo, para el registro.

{rollback}

El bloque {try} también se puede detener y saltar manualmente usando {rollback}. Gracias a esto, no necesita verificar todos los datos de entrada de antemano y puede decidir durante el renderizado que no quiere renderizar el objeto en absoluto:

{try}
<ul>
	{foreach $people as $person}
 		{skipIf $person->age < 18}
 		<li>{$person->name}</li>
	{else}
		{rollback}
	{/foreach}
</ul>
{/try}

Variables

{var} {default}

Creamos nuevas variables en la plantilla con la etiqueta {var}:

{var $name = 'John Smith'}
{var $age = 27}

{* Declaración múltiple *}
{var $name = 'John Smith', $age = 27}

La etiqueta {default} funciona de manera similar, pero crea variables solo si no existen. Si la variable ya existe y contiene el valor null, no será sobrescrita:

{default $lang = 'es'}

También puede indicar tipos de variables. Por ahora son informativos y Latte no los comprueba.

{var string $name = $article->getTitle()}
{default int $id = 0}

{parameters}

Así como una función declara sus parámetros, una plantilla también puede declarar sus variables al principio:

{parameters
	$a,
	?int $b,
	int|string $c = 10
}

Las variables $a y $b sin un valor por defecto especificado tienen automáticamente el valor por defecto null. Los tipos declarados son por ahora informativos y Latte no los comprueba.

No se transfieren a la plantilla otras variables que no sean las declaradas. En esto se diferencia de la etiqueta {default}.

{capture}

Captura la salida en una variable:

{capture $var}
<ul>
	<li>Hello World</li>
</ul>
{/capture}

<p>Capturado: {$var}</p>

La etiqueta, como cualquier etiqueta par, también se puede escribir como n:atributo:

<ul n:capture="$var">
	<li>Hello World</li>
</ul>

La salida HTML se guarda en la variable $var en forma de objeto Latte\Runtime\Html, para que no se produzca un escapado no deseado al imprimirla.

Otros

{contentType}

Con esta etiqueta especifica qué tipo de contenido representa la plantilla. Las opciones son:

• html (tipo por defecto)
• xml
• javascript
• css
• calendar (iCal)
• text

Su uso es importante porque establece el escapado sensible al contexto y solo así puede escapar correctamente. Por ejemplo, {contentType xml} cambia al modo XML, {contentType text} desactiva completamente el escapado.

Si el parámetro es un tipo MIME completo, como por ejemplo application/xml, también envía la cabecera HTTP Content-Type al navegador:

{contentType application/xml}
<?xml version="1.0"?>
<rss version="2.0">
	<channel>
		<title>RSS feed</title>
		<item>
			...
		</item>
	</channel>
</rss>

{debugbreak}

Marca el lugar donde se suspenderá la ejecución del programa y se iniciará el depurador, para que el programador pueda inspeccionar el entorno de ejecución y averiguar si el programa funciona como se esperaba. Admite Xdebug. Se puede añadir una condición que determine cuándo debe suspenderse el programa.

{debugbreak}                {* suspende el programa *}

{debugbreak $counter == 1}  {* suspende el programa si se cumple la condición *}

{do}

Ejecuta código PHP y no imprime nada. Al igual que con todas las demás etiquetas, por código PHP se entiende una única expresión, vea limitaciones de PHP.

{do $num++}

{dump}

Vuelca una variable o el contexto actual.

{dump $name} {* Vuelca la variable $name *}

{dump}       {* Vuelca todas las variables definidas actualmente *}

Requiere la librería Tracy.

{php}

Permite ejecutar cualquier código PHP. La etiqueta debe activarse mediante la extensión RawPhpExtension.

{spaceless}

Elimina los espacios en blanco innecesarios de la salida. Funciona de manera similar al filtro spaceless.

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

Genera

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

La etiqueta también se puede escribir como n:atributo.

{syntax}

Las etiquetas Latte no tienen por qué estar delimitadas solo por llaves simples. Podemos elegir otro delimitador e incluso en tiempo de ejecución. Para esto sirve {syntax …}, donde como parámetro se puede indicar:

• double: {{...}}
• off: desactiva completamente el procesamiento de etiquetas Latte

Con el uso de n:atributos se puede desactivar Latte, por ejemplo, solo para un bloque de JavaScript:

<script n:syntax="off">
	var obj = {var: 123}; // esto ya no es una etiqueta
</script>

Latte se puede usar muy cómodamente también dentro de JavaScript, solo hay que evitar construcciones como en este ejemplo, donde una letra sigue inmediatamente después de {, vea Latte dentro de JavaScript o CSS.

Si desactiva Latte usando {syntax off} (es decir, con la etiqueta, no con el n:atributo), ignorará consistentemente todas las etiquetas hasta {/syntax}

{trace}

Lanza una excepción Latte\RuntimeException, cuyo stack trace sigue el espíritu de las plantillas. Es decir, en lugar de llamadas a funciones y métodos, contiene llamadas a bloques e inclusiones de plantillas. Si utiliza una herramienta para la visualización clara de las excepciones lanzadas, como por ejemplo Tracy, se le mostrará claramente el call stack incluyendo todos los argumentos pasados.

Ayudantes del codificador HTML

n:class

Gracias a n:class es muy fácil generar el atributo HTML class exactamente según sus ideas.

Ejemplo: necesito que el elemento activo tenga la clase active:

{foreach $items as $item}
	<a n:class="$item->isActive() ? active">...</a>
{/foreach}

Y además, que el primer elemento tenga las clases first y main:

{foreach $items as $item}
	<a n:class="$item->isActive() ? active, $iterator->first ? 'first main'">...</a>
{/foreach}

Y que todos los elementos tengan la clase list-item:

{foreach $items as $item}
	<a n:class="$item->isActive() ? active, $iterator->first ? 'first main', list-item">...</a>
{/foreach}

Asombrosamente simple, ¿verdad?

n:attr

El atributo n:attr puede generar cualquier atributo HTML con la misma elegancia que tiene n:class.

{foreach $data as $item}
	<input type="checkbox" n:attr="value: $item->getValue(), checked: $item->isActive()">
{/foreach}

Dependiendo de los valores devueltos, imprime por ejemplo:

<input type="checkbox">

<input type="checkbox" value="Hello">

<input type="checkbox" value="Hello" checked>

n:tag

El atributo n:tag puede cambiar dinámicamente el nombre del elemento HTML.

<h1 n:tag="$heading" class="main">{$title}</h1>

Si $heading === null, se imprimirá la etiqueta <h1> sin cambios. De lo contrario, el nombre del elemento cambiará al valor de la variable, por lo que para $heading === 'h3' se imprimirá:

<h3 class="main">...</h3>

Dado que Latte es un sistema de plantillas seguro, comprueba que el nuevo nombre de etiqueta sea válido y no contenga ningún valor no deseado o malicioso.

n:ifcontent

Evita que se imprima un elemento HTML vacío, es decir, un elemento que no contiene nada más que espacios.

<div>
	<div class="error" n:ifcontent>{$error}</div>
</div>

Imprime dependiendo del valor de la variable $error:

{* $error = '' *}
<div>
</div>

{* $error = 'Required' *}
<div>
	<div class="error">Required</div>
</div>

Traducciones

Para que las etiquetas de traducción funcionen, es necesario activar el traductor. Para la traducción también puede usar el filtro translate.

{_...}

Traduce valores a otros idiomas.

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

También se pueden pasar otros parámetros al traductor:

<a href="basket">{_'Cesta', domain: order}</a>

{translate}

Traduce partes de la plantilla:

<h1>{translate}Pedido{/translate}</h1>

{translate domain: order}Lorem ipsum ...{/translate}

La etiqueta también se puede escribir como n:atributo, para traducir el interior del elemento:

<h1 n:translate>Pedido</h1>