Mejores prácticas de Twig: funciones y plantillas de preprocesamiento

19/06/2025, by Ivan

Para hacer que el theming en Drupal 8 sea lo más eficiente posible y proporcionar más opciones de personalización en las plantillas Twig, siga estas recomendaciones:

Esta guía está escrita para ayudar a desarrolladores de Drupal que puedan tener experiencia con Drupal 7 y están tratando de eliminar funciones como theme() o drupal_render(), que ya no deben usarse en Drupal 8+. Los ejemplos "antes" generalmente están escritos en estilo de código Drupal 7.

Devolver arrays de renderizado desde funciones de preprocesamiento

Siempre devuelva arrays de renderizado en lugar de llamar a theme() o drupal_render() dentro de funciones de preprocesamiento.

Twig renderiza todo automáticamente, por lo que no es necesario llamar a drupal_render() o theme() dentro de una función de preprocesamiento. En su lugar, los arrays de renderizado deben pasarse a la plantilla, ya que esto permite mucha más personalización que una cadena HTML ya renderizada.

Eliminar theme() de la función de preprocesamiento:

// Antes - pasando una cadena HTML renderizada a la plantilla.
$variables['table'] = theme('table', ['header' => $header, 'rows' => $rows]);

// Después - pasando un array de renderizado a la plantilla.
$variables['table'] = [
  '#theme' => 'table',
  '#header' => $header,
  '#rows' => $rows,
];

Eliminar drupal_render() de la función de preprocesamiento es solo cuestión de eliminar la llamada:

// Antes, llamada innecesaria a drupal_render().
$variables['teaser'] = drupal_render($node_teaser);

// Después, sin drupal_render().
$variables['teaser'] = $node_teaser;

Un caso común es que drupal_render() se usaba al agregar datos a una tabla.

// Antes, llamada innecesaria a drupal_render().
$row[] = drupal_render($display['title']);

// Después, sin drupal_render().
$row[]['data'] = $display['title'];

Filtros de llamada y funciones utilitarias en plantillas

Aunque los arrays de renderizado proporcionan una estructura direccionable y modificable para los datos a lo largo del camino hasta la plantilla, no todas las variables requieren arrays de renderizado. Para entregar datos sin procesar a las plantillas durante más tiempo, los desarrolladores de temas deben llamar a filtros, como t, y funciones utilitarias, como url(), desde las plantillas Twig. Llamar a estas funciones directamente en la plantilla Twig, en lugar de en la función de preprocesamiento, puede reducir las llamadas a funciones, dado que las variables pasadas a la plantilla pueden no imprimirse en absoluto.

Antes:

En la función de preprocesamiento:

$variables['no_content_text'] = t('You have not created any content types yet. Go to the <a href="@create-content">content type creation page</a> to add a new content type.', array('@create-content' => url('admin/structure/types/add')));

En la plantilla:

<p>{{ no_content_text }}</p>

Después:

En la plantilla:

<p>{{ 'You have not created any content types yet. Go to the <a href="@create-content">content type creation page</a> to add a new content type.'|t({'@create-content': url('admin/structure/types/add')}) }}</p>

Mostrar / ocultar y eliminar drupal_render_children y element_children

Si hide() fue llamado en la plantilla original y se usó drupal_render_children para renderizar el "resto" de los datos, debemos dividir todo esto en variables separadas durante el preprocesamiento.

Antes (archivo PHPTemplate):

<?php
hide($form['advanced']);
hide($form['actions']);
?>
<div class="layout-node-form clearfix">
<div class="layout-region layout-region-node-main">
<?php print drupal_render_children($form); ?>
</div>
<div class="layout-region layout-region-node-secondary">
<?php print render($form['advanced']); ?>
</div>
<div class="layout-region layout-region-node-footer">
<?php print render($form['actions']); ?>
</div>
</div>

Use el filtro Twig llamado without para ocultar elementos específicos. Puede usarlos normalmente donde sea necesario.

Después: (plantilla Twig)

<div class="layout-node-form clearfix">
  <div class="layout-region layout-region-node-main">
    {{ form|without('advanced', 'actions') }}
  </div>
  <div class="layout-region layout-region-node-secondary">
    {{ form.advanced }}
  </div>
  <div class="layout-region layout-region-node-footer">
    {{ form.actions }}
  </div>
</div>

Método alternativo (ya no recomendado):

Preprocese todo en variables separadas y páselas a la plantilla. Puede que necesite volcar elementos que quiera renderizar en variables desde el elemento completo (en este caso, el formulario) antes de renderizar el resto. Imprima el contenido exactamente como lo especifica la plantilla.

Antes: (preprocesamiento)

function template_preprocess_node_edit_form(&$variables) {
  $form = $variables['form'];
  
  // @todo Actualizar esto una vez que se resuelva drupal.org/node/1920886.
  $variables['advanced'] = $form['advanced'];
  $variables['actions'] = $form['actions'];
  unset($form['advanced'], $form['actions']);
  $variables['form'] = drupal_render_children($form);
}