Crear un layout custom con Layout API

Thursday, May 31, 2018

Podemos usar Layout API de Drupal 8 para evitar usar módulos cómo Field Group para definir contenedores, ya que podemos definir plantillas reutilizables para varios contenidos.

A partir de la salida de la versión 8 de Drupal, el módulo Layout Plugin ha servido para definir estructuras de plantillas que posteriormente se usaban junto con otros módulos cómo Panels, Display Suite, Radix Layouts o Bootstrap Layouts.

Además este módulo te permitía registrar nuevas plantillas de una manera simple.

Afortunadamente a partir de la versión 8.3.x se ha hecho una transición del módulo Layout Plugin a Layout Discovery ahora situado en el core.

Junto a Layout Discovery y de manera experimental tenemos Field Layout, permitiendo elegir los layouts disponibles desde la pestaña de manage display del contenido.

Una novedad en la versión 8.5.x es el de Layout Builder, ofreciendo un live preview para poder aplicar los layouts registrados y mediante un interfaz drag&drop construir la estructura del contenido.

A continuación vamos a explicar cómo crear un layout y aplicarlo a un tipo de contenido básico.

Se recomienda tener nociones de Drupal, PHP y Twig.

Cómo crear mi primer layout sin morir en el intento

Introducción

Lo primero a tener en cuenta es elegir cómo queremos añadir los layouts custom.

Layout Discovery te permite registrarlos a partir de un módulo o un template.

En nuestro ejemplo vamos a guiarnos por el más simple, el del módulo.

Generar módulo

Vamos a crear nuestro módulo custom, podemos hacerlo con Drupal Console si lo tienes instalado.

drupal generate:module

Vamos a crear el siguiente yaml con el nombre mi_modulo.layouts.yml en la raíz de nuestro módulo, esto servirá para definir las plantillas que tenemos.

Aquí tienes un ejemplo de lo que va a contener.

my_custom_layout:
  label: 'Mi plantilla custom'
  category: 'Mis plantillas'
  template: templates/my-layout
  default_region: main
  regions:
    main:
      label: 'Contenido Principal'
    sidebar:
      label: Sidebar

my_custom_layout": Va a ser el nombre del nuevo layout.
Label: Etiqueta para diferenciar el layout.
Category: Se pueden agrupar los layouts por categoría.
Template: Será el fichero twig (la plantilla) sin la extensión.
default_region: Será la región donde se pondrá los elementos por defecto.
regions: Todas las regiones, posteriormente se usarán en el twig.

Crear el template

Debemos situar el fichero twig en nuestra carpeta templates; si el directorio no está creado lo creamos.

El nombre del fichero en este caso será my-layout.html.twig ya que así lo hemos escrito en el fichero mi_modulo.layouts.yml.

El contenido del fichero twig será básico.

<div class="two-column">
  <div class="main-region">
    {{ content.main }}
  </div>
  <div class="sidebar-region">
    {{ content.sidebar }}
  </div>
</div>

Cómo vemos las dos regiones que teníamos definidas en el fichero yaml las estamos usando aquí.

Usar estilos en la plantilla

Un layout no sirve de mucho sin tematizado por lo que también vamos a registrar una librería CSS en el módulo.

En la raíz del módulo vamos a crear el fichero mi_modulo.libraries.yml que es donde se deberá registrar todas las librerías disponibles.

Aquí os dejo un ejemplo de cómo registrar una librería propia del módulo:

my-custom-library:
  version: 1.x
  css:
    theme:
      css/styles-library.css: {}

Una vez que ya existe la librería debemos indicar en el yml del layout, *.layouts.yml, que queremos usarla.

my_custom_layout:
  label: 'Mi plantilla custom'
  category: 'Mis plantillas'
  template: templates/my-layout
  default_region: main
  library: mi_modulo/my-custom-library
  regions:
    main:
      label: 'Main Content'
    sidebar:
      label: Sidebar

Cómo se puede ver en el ejemplo anterior hemos añadido la línea "library" con el nombre de nuestro módulo y la librería que hemos registrado en el fichero *.libraries.yml

Ya podemos tematizar nuestra plantilla en el fichero css/styles-library.css.

Pasos finales

Quedaría activar nuestro módulo y activar el módulo Layout Discovery si no está activo para que encuentre la plantilla. Después activar un módulo que gestione esas plantillas, cómo Display Suite o Panels. En este caso vamos a activar Field Layout que aunque es experimental lo tenemos en el core y no necesitamos instalar nada más .

Si vamos a un display de un tipo de contenido en "Structure/Content types/contenido/Manage display" en la parte inferior tendremos disponible los layouts. Entre ellos tendremos el nuestro.

Al seleccionarlo vemos que nos aparecen las regiones definidas, y vemos los campos que están activos en la región por defecto, ahora sólo queda distribuir cada campo en la región que nos convenga.

Manage display

Guardamos el display y ya podemos ver el resultado en un contenido creado.

Más información

Layout API

Eduardo Morales

Senior Drupal developer