Plantillas y atajos

Una plantilla recibe una página y escribe su HTML. Esta es una plantilla completa, plantillas/articulo.twig:

{% extends 'plantillas/base.twig' %}

{% block cuerpo %}
  <article>
    <h1>{{ pagina.titulo }}</h1>
    {{ pagina.contenido }}
  </article>
{% endblock %}

Una página la usa nombrándola en su front matter, sin carpeta ni extensión:

---
titulo: Mi primera entrada
plantilla: articulo
---
Hoy empiezo un blog.

Si una página no dice nada, usa plantillas/pagina.twig. Con plantilla: false sale tal cual, sin layout, que es lo que necesita un robots.txt. Y si nombras una plantilla que no existe, la compilación se detiene: es mejor no publicar que publicar una página sin su marco.

Tres variables¶

En cualquier plantilla tienes:

• sitio: lo que escribiste en sitio.yml (sitio.nombre, sitio.url).
• datos: los ficheros de datos/. El de datos/menus.yml es datos.menus.
• pagina: la página que se está construyendo. Trae los campos de su front matter (pagina.titulo, pagina.fecha…), y además pagina.url, pagina.contenido (el cuerpo ya convertido a HTML) y pagina.idioma.

Un campo que no existe sale vacío, así que {% if pagina.imagen %} funciona sin comprobar antes que exista.

Campos propios y los «sí» y «no»¶

En el front matter puedes escribir los campos que quieras, y la plantilla los recibe como los lee YAML. Cuidado con una cosa: sí y no solo significan verdadero y falso en los campos que Ehundu reserva, como borrador o listada. En un campo tuyo son el texto «sí» y el texto «no»:

destacado: sí

Para quedarte con las páginas que lo llevan, compara con el texto:

{% for p in coleccion('proyectos')|donde('destacado', 'sí') %}

Y no escribas {% if pagina.destacado %} pensando en un no: el texto «no» no está vacío, así que una plantilla lo toma por verdadero. Si de verdad quieres un verdadero o un falso, escribe true o false, sin comillas, que YAML sí los lee como tales: destacado: true se filtra con donde('destacado', true).

Layouts y parciales¶

Un layout se hereda con {% extends %} y se rellena por bloques; un trozo que se repite se trae con {% include %}. Las dos cosas se nombran con la ruta desde la raíz del proyecto:

{% extends 'plantillas/base.twig' %}
{% include 'parciales/cabecera.twig' %}

Una idea que ordena mucho: en base.twig está lo que todas las páginas comparten (la cabecera, el pie, las hojas de estilo) y un bloque vacío; cada layout concreto solo rellena el bloque.

Twig escapa lo que escribe¶

Todo lo que una plantilla escribe sale con el HTML escapado, así que un título con < o & no rompe nada. Hay una excepción pensada: lo que ya es HTML hecho por el motor, como pagina.contenido, sale tal cual. Si en una plantilla escribes un campo tuyo que lleva HTML a propósito, hay que pedirlo con |raw:

{{ pagina.aviso|raw }}

Úsalo solo con texto tuyo, nunca con lo que venga de fuera.

Atajos para el Markdown¶

El Markdown no pasa por Twig: dentro de un texto no hay variables ni condiciones. Lo que sí hay es un vocabulario pequeño y cerrado de atajos, que escribes entre corchetes con atributos con nombre:

[imagen fichero="img/escaparate.jpg" alt="Escaparate de la librería" pie="La tienda en otoño"]

Ehundu trae cuatro:

Crea el tuyo¶

Un atajo es una plantilla en parciales/atajos/, con su nombre. Para un aviso, parciales/atajos/aviso.twig:

<div class="aviso aviso--{{ tipo|default('nota') }}">
  {{ contenido }}
</div>

Los atributos llegan como variables (tipo), y contenido es lo que el atajo envuelve, ya convertido a HTML. Lo usas así, con la apertura y el cierre cada uno en su línea:

[aviso tipo="importante"]
Las plazas son **limitadas**.
[/aviso]

Y sale:

<div class="aviso aviso--importante">
  <p>Las plazas son <strong>limitadas</strong>.</p>
</div>

Si un atajo produce un bloque (un div, una figura), ponlo en su propio párrafo. Y si necesitas escribir uno como texto, y no como atajo, ponle delante una barra: \[aviso].

Para cambiar cómo sale uno de los que trae el motor, escribe una plantilla con su mismo nombre en parciales/atajos/: la tuya gana.

El detalle está en las plantillas y en los atajos.