Best practice Twig - funzioni e template di preprocessing

02/10/2025, by Ivan

Per rendere il theming in Drupal 8 il più efficiente possibile e fornire maggiori possibilità di personalizzazione nei template Twig, segui queste linee guida:

Questa guida è stata scritta per aiutare gli sviluppatori Drupal che hanno esperienza con Drupal 7 e stanno cercando di eliminare funzioni come theme() o drupal_render(), che non devono più essere usate in Drupal 8+. Gli esempi “prima” qui sono generalmente in stile Drupal 7.

Restituire array di render dalle funzioni di preprocessing

Restituisci sempre array di render invece di chiamare theme() o drupal_render() nelle funzioni di preprocessing.

Twig renderizza tutto automaticamente, quindi non è necessario chiamare drupal_render() o theme() all’interno di una funzione di preprocessing. Invece, gli array di render devono essere passati al template, poiché questo consente molta più personalizzazione rispetto a una stringa HTML già renderizzata.

Rimozione di theme() da una funzione di preprocessing:

// Prima - passaggio di una stringa di HTML renderizzato al template.
$variables['table'] = theme('table', ['header' => $header, 'rows' => $rows]);

// Dopo - passaggio di un render array al template.
$variables['table'] = [
  '#theme' => 'table',
  '#header' => $header,
  '#rows' => $rows,
];

Rimozione di drupal_render() da una funzione di preprocessing: basta eliminare la chiamata.

// Prima, chiamata inutile a drupal_render().
$variables['teaser'] = drupal_render($node_teaser);

// Dopo, senza drupal_render().
$variables['teaser'] = $node_teaser;

Un caso comune era l’uso di drupal_render() quando si aggiungevano dati a una tabella:

// Prima, chiamata inutile a drupal_render().
$row[] = drupal_render($display['title']);

// Dopo, senza drupal_render().
$row[]['data'] = $display['title'];

Filtri e funzioni di utilità nei template

Sebbene i render array forniscano una struttura indirizzabile e modificabile per i dati fino al template, non tutte le variabili richiedono render array. Per mantenere i dati grezzi disponibili ai template il più a lungo possibile, gli sviluppatori di temi dovrebbero invocare filtri come t e funzioni di utilità come url() direttamente nei template Twig. Farlo nel template Twig, piuttosto che nella funzione di preprocessing, può ridurre il numero di chiamate a funzioni, poiché alcune variabili potrebbero non essere stampate affatto.

Prima:

Nella funzione di preprocessing:

$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')));

Nel template:

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

Dopo:

Nel template:

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

Mostrare/nascondere e rimuovere drupal_render_children e element_children

Se hide() veniva chiamato nel template originale e drupal_render_children veniva usato per renderizzare il resto dei dati, dobbiamo dividere tutto in variabili separate durante il preprocessing.

Prima (file 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>

Usa il filtro Twig chiamato without per nascondere determinati elementi. Puoi quindi stamparli dove necessario.

Dopo (template 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>

Metodo alternativo (non più richiesto):

Preprocessa tutto in variabili separate e passale al template. Potresti dover spostare in variabili specifiche gli elementi che vuoi stampare, prima di renderizzare il resto. Stampa poi i contenuti esattamente come previsto dal template.

Prima (preprocess):

function template_preprocess_node_edit_form(&$variables) {
  $form = $variables['form'];
  
  // @todo Aggiornare questo una volta risolta la issue drupal.org/node/1920886.
  $variables['advanced'] = $form['advanced'];
  $variables['actions'] = $form['actions'];
  unset($form['advanced'], $form['actions']);
  $variables['form'] = drupal_render_children($form);
}