Etiquetas de Latte

Resumen y descripción de todas las etiquetas disponibles de serie en el sistema de plantillas Latte.

Impresión

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

En Latte, la etiqueta {=...} sirve para imprimir cualquier expresión en la salida. Latte se preocupa por su comodidad, así que si la expresión empieza por una variable o por una llamada a una función, no hace falta escribir el signo igual. Lo que en la práctica significa que casi nunca hay que escribirlo:

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

Como expresión puede escribir todo lo que conoce de PHP. Sencillamente, no tiene que aprender un lenguaje nuevo. Por ejemplo:

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

No busque ningún sentido al ejemplo anterior, pero si se lo encuentra, avísenos :-)

Escapado de la salida

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

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

Para ser precisos, Latte usa escapado sensible al contexto, una función tan importante y singular que le hemos dedicado un capítulo aparte.

¿Y si imprime contenido HTML procedente de una fuente confiable? Entonces puede desactivar el escapado sin problema:

{$trustedHtmlString|noescape}

¡Un uso indebido del filtro noescape puede provocar una vulnerabilidad XSS! No lo use nunca salvo que esté absolutamente seguro de lo que hace y de que la cadena que imprime procede de una fuente confiable.

Impresión en JavaScript

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

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

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

Genera:

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

Por eso también no debe escribir comillas alrededor de la variable: Latte las añade automáticamente en las cadenas. Y si quiere insertar una variable de cadena dentro de otra cadena, simplemente concaténelas:

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

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

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

Filtros

La expresión impresa se puede modificar con filtros. Por ejemplo, esto convierte la cadena a mayúsculas y la acorta a un máximo de 30 caracteres:

{$string|upper|truncate:30}

También puede aplicar filtros a partes de una expresión, así:

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

Condiciones

{if} {elseif} {else}

Las condiciones se comportan igual que sus equivalentes de PHP. Puede usar las mismas expresiones que conoce de PHP; no tiene que aprender un lenguaje nuevo.

{if $product->inStock > Stock::Minimum}
	In stock
{elseif $product->isOnWay()}
	On the way
{else}
	Not available
{/if}

Como toda etiqueta par, la pareja {if} ... {/if} también se puede escribir con un n:atributo, por ejemplo:

<p n:if="$count > 0">In stock {$count} items</p>

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

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

{* muestra 'Hello' cuando $clickable es falsy *}
{* muestra '<a href="...">Hello</a>' cuando $clickable es truthy *}

Genial.

n:else n:elseif

Si escribe la condición {if} ... {/if} en forma de n:atributo, tiene la posibilidad de indicar ramas alternativas con n:else (desde 3.0.12) y n:elseif (desde 3.1):

<strong n:if="$count > 0">In stock {$count} items</strong>

<em n:elseif="$count < 0">Invalid count</em>

<em n:else>not available</em>

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

{/if $cond}

Quizá le sorprenda que la expresión de la condición {if} se pueda indicar también en la etiqueta de cierre. Resulta útil cuando al abrir la condición aún no conocemos su valor. Llamémoslo decisión aplazada.

Por ejemplo, empezamos a listar una tabla con registros de la base de datos y solo al terminar la salida nos damos cuenta de que en la base no había ningún registro. Ponemos entonces la condición en la etiqueta de cierre {/if} y, si no hay registros, no se imprimirá nada de todo aquello:

{if}
	<h1>List of rows from the database</h1>

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

Práctico, ¿verdad?

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

{ifset} {elseifset}

Vea también {ifset block}

Use la condición {ifset $var} para determinar si una variable (o varias) existe y tiene un valor distinto de null. Es en realidad lo mismo que if (isset($var)) en PHP. Como toda etiqueta par, también se puede escribir con un n:atributo, así que veamos un 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 de un bucle (foreach, for o while).

Si indicamos una o varias variables en la etiqueta, comprueba si alguna de ellas ha cambiado e imprime el contenido en consecuencia. Por ejemplo, el siguiente ejemplo imprime la primera letra de un nombre como encabezado cada vez que cambia durante el listado de nombres:

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

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

Ahora bien, si no se indica ningún argumento, se comprobará el propio contenido renderizado frente a su estado anterior. Esto significa que, en el ejemplo anterior, podemos omitir tranquilamente el argumento de 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 usar una cláusula {else}.

{switch} {case} {default}

Compara un valor con varias opciones. Es parecido a la sentencia switch que se conoce de PHP. Latte, sin embargo, la mejora:

• usa comparación estricta (===)
• no requiere break

Así se acerca mucho a la estructura match introducida en PHP 8.0.

{switch $transport}
	{case train}
		By train
	{case plane}
		By plane
	{default}
		Otherwise
{/switch}

La cláusula {case} puede contener varios valores separados por comas:

{switch $status}
{case $status::New}<b>new item</b>
{case $status::Sold, $status::Unknown}<i>not available</i>
{/switch}

Bucles

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

{foreach}

El bucle se escribe exactamente igual que en PHP:

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

Además, tiene algunas funciones prácticas de las que hablaremos ahora.

Por ejemplo, Latte comprueba que las variables creadas no sobrescriban por accidente variables globales del mismo nombre. Esto le libra de situaciones en las que espera que $lang contenga el idioma actual de la página y no se da cuenta de que foreach $langs as $lang ha sobrescrito esa variable.

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

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

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

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

Así imprime algo como:

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

{else}

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

<ul>
	{foreach $people as $person}
		<li>{$person->name}</li>
	{else}
		<li><em>Sorry, there are no users in this list</em></li>
	{/foreach}
</ul>

$iterator

Dentro del bucle foreach, Latte crea la variable $iterator, que nos permite conocer información útil sobre el bucle en curso:

• $iterator->first – ¿es esta la primera iteración?
• $iterator->last – ¿es esta la última iteración?
• $iterator->counter – contador de iteraciones, empezando por uno
• $iterator->counter0 – contador de iteraciones, empezando por cero
• $iterator->odd – ¿es esta una iteración impar?
• $iterator->even – ¿es esta una iteración par?
• $iterator->parent – el iterador que rodea al actual
• $iterator->nextValue – el siguiente elemento del bucle
• $iterator->nextKey – la clave del siguiente elemento del 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 listo, y $iterator->last funciona no solo con arrays, sino también cuando el bucle recorre un iterador general en el que 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 renderiza si es la primera iteración. El contenido de {last} se renderiza… ¿lo adivina? Sí, si es la última iteración. En realidad son atajos de {if $iterator->first} y {if $iterator->last}.

Las etiquetas también se pueden usar con elegancia como n:atributos:

{foreach $rows as $row}
	{first}<h1>List of names</h1>{/first}

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

	<hr n:last>
{/foreach}

El contenido de la etiqueta {sep} se renderiza si la iteración no es la última, lo que la hace adecuada para imprimir separadores, como las comas entre los elementos listados:

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

Es bastante práctico, ¿no?

{iterateWhile}

Simplifica la agrupación de datos lineales durante la iteración de un bucle foreach, ejecutando la iteración en un bucle anidado mientras se cumpla la condición. Lea las instrucciones detalladas.

También puede sustituir con elegancia a {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}

El bucle se escribe exactamente igual que en PHP:

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

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

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

{while}

De nuevo, el bucle se escribe 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 de cierre, que corresponde al bucle do-while de PHP:

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

{continueIf} {skipIf} {breakIf}

Las etiquetas especiales {continueIf ?} y {breakIf ?} se pueden usar para controlar cualquier bucle. Saltan a la siguiente iteración 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} se parece mucho a {continueIf}, pero no incrementa $iterator->counter. Así se evitan huecos en la numeración al imprimir el contador y saltarse algunos elementos. Además, la cláusula {else} se renderizará si se saltan todos los elementos.

<ul>
	{foreach $people as $person}
		{skipIf $person->age < 18}
		<li>{$iterator->counter}. {$person->name}</li>
	{else}
		<li><em>Sorry, there are no adults in this list</em></li>
	{/foreach}
</ul>

{exitIf}

Termina el renderizado de una plantilla o de un bloque cuando se cumple una condición (es decir, “salida anticipada”).

{exitIf !$messages}

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

Inclusión de plantillas

{include 'file.latte'}

Vea también {include block} y {embed}

La etiqueta {include} carga y renderiza la plantilla indicada. En nuestro querido lenguaje PHP sería algo así:

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

Las plantillas incluidas no tienen acceso a las variables del contexto activo, pero sí a las variables globales.

Puede pasar variables a la plantilla incluida de este modo:

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

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

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

Si una plantilla existe se puede comprobar con la función hasTemplate().

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

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

De forma predeterminada, la herencia de plantillas no interviene aquí. Aunque puede usar bloques en las plantillas incluidas, estos no sustituirán a los bloques correspondientes de la plantilla en la que se incluyen. Piense en las plantillas incluidas como partes independientes y aisladas de las páginas o módulos. Este comportamiento se puede cambiar con el modificador with blocks:

{include 'template.latte' with blocks}

La relación entre el nombre de archivo indicado en la etiqueta y el archivo del disco depende del loader.

{sandbox}

Al incluir una plantilla creada por un usuario final debería plantearse ejecutarla en 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 ofrecen la posibilidad de aplicar filtros a una parte de la plantilla. Por ejemplo, puede aplicar el filtro spaceless para eliminar los espacios innecesarios:

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

Tratamiento de excepciones

{try}

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

Si durante el renderizado del bloque {try} se produce una excepción, se descarta todo el bloque y el renderizado continúa después de él:

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

El contenido de la cláusula opcional {else} se renderiza solo cuando se produce una excepción:

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
	{else}
	<p>Sorry, the tweets could not be loaded.</p>
{/try}

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

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

También es posible definir un manejador de excepciones propio, por ejemplo para registrar los errores.

{rollback}

El bloque {try} también se puede detener y descartar manualmente con {rollback}. Así no tiene que comprobar de antemano todos los datos de entrada y puede decidir durante el renderizado que el objeto no debe renderizarse 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 variables nuevas 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 forma parecida, pero crea las variables solo si no existen. Si una variable ya existe y contiene el valor null, no se sobrescribirá:

{default $lang = 'en'}

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

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

{parameters}

Igual que una función declara sus parámetros, una plantilla puede declarar sus variables al principio:

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

Las variables $a y $b, sin valor predeterminado indicado, tienen automáticamente el valor predeterminado null. Los tipos declarados son de momento informativos y Latte no los comprueba.

Las variables distintas de las declaradas no se pasan a la plantilla. 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>Captured: {$var}</p>

Como toda etiqueta par, esta 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 como un objeto Latte\Runtime\Html, para evitar un escapado no deseado al imprimirla.

Otras

{contentType}

Use esta etiqueta para indicar el tipo de contenido que representa la plantilla. Las opciones son:

• html (tipo predeterminado)
• xml
• javascript
• css
• calendar (iCal)
• text

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

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

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

{debugbreak}

Indica un punto donde la ejecución del programa se detendrá. Se usa para depurar y permite al programador inspeccionar el entorno de ejecución y comprobar que el código funciona como se espera. Es compatible con Xdebug. También puede añadir una condición que determine cuándo debe detenerse el programa.

{debugbreak}                {* pausa el programa *}

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

{do}

Ejecuta código PHP y no imprime nada. Como en 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 biblioteca Tracy.

{php}

De forma predeterminada, {php} funciona como un alias obsoleto de {do} y evalúa solo una única expresión. Para ejecutar cualquier código PHP hay que activar la etiqueta mediante la extensión RawPhpExtension.

{spaceless}

Elimina los espacios en blanco innecesarios de la salida. Funciona de forma parecida 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 de Latte no tienen por qué ir encerradas solo en llaves simples. Puede elegir otro separador, incluso en tiempo de ejecución. Se hace con {syntax …}, donde el parámetro puede ser:

• double: {{...}}
• off: desactiva por completo el procesamiento de las etiquetas de Latte

Con los n:atributos puede desactivar Latte solo en un bloque de JavaScript, por ejemplo:

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

Latte se puede usar muy cómodamente dentro de JavaScript; basta con evitar construcciones como la de este ejemplo, donde una letra sigue inmediatamente a {, vea Latte dentro de JavaScript o CSS.

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

{trace}

Lanza una excepción Latte\RuntimeException cuya traza de pila sigue el espíritu de las plantillas. Así, en lugar de llamadas a funciones y métodos, contiene llamadas a bloques e inclusiones de plantillas. Si usa una herramienta para mostrar con claridad las excepciones lanzadas, como Tracy, verá con nitidez la pila de llamadas, incluidos todos los argumentos pasados.

Ayudas para el maquetador HTML

n:class

Desde Latte 3.1, el atributo HTML class estándar ha ganado la misma funcionalidad. Así que ya no necesita usar n:class.

Gracias a n:class es muy fácil generar el atributo HTML class exactamente como haga falta.

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 necesito 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 sencillo, ¿verdad?

n:attr

El atributo n:attr puede generar atributos HTML cualesquiera con la misma elegancia que class.

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

Según los valores devueltos, imprime, por ejemplo:

<input type="checkbox">

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

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

Las funciones de los atributos inteligentes de Latte 3.1, como descartar los valores null o pasar arrays a class o style, funcionan también dentro de n:attr:

<div n:attr="class: [a, b], title: $title"></div>

n:tag

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

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

Si $heading === null, la etiqueta <h1> se imprime sin cambios. En caso contrario, el nombre del elemento se cambia por el valor de la variable, de modo que para $heading === 'h3' escribe:

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

Como Latte es un sistema de plantillas seguro, comprueba que el nuevo nombre de etiqueta sea válido y no contenga valores indeseados o maliciosos.

n:ifcontent

Impide que se imprima un elemento HTML vacío, es decir, un elemento que no contiene más que espacios en blanco.

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

Según el valor de la variable $error, imprimirá:

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

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

Traducción

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

{_...}

Traduce valores a otros idiomas.

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

Al traductor también se le pueden pasar otros parámetros:

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

{translate}

Traduce partes de la plantilla:

<h1>{translate}Order{/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>Order</h1>