Creazione di template Twig personalizzati per un modulo personalizzato

L’idea generale in Drupal 8 è che si vuole evitare di creare HTML direttamente nel codice PHP del proprio modulo personalizzato. L’HTML deve invece essere spostato nei template Twig. Per creare nuovi template Twig nel tuo modulo, segui questi passaggi.

Passo n. 1: Definire hook_theme nel file .module
Crea il file [module].module, se non esiste già, e aggiungi il codice che definisce ciascuno dei tuoi template Twig. La chiave di ogni elemento nell’array è ciò che dovrai usare per richiamare il template in seguito. Non usare trattini nel nome del file.

function test_twig_theme($existing, $type, $theme, $path) {
  return [
    'my_template' => [
      'variables' => ['test_var' => NULL],
    ],
  ];
}

Consulta la documentazione per hook_theme().

Passo n. 2: Richiamare il template
Nel punto in cui restituisci il tuo render array (da un metodo del controller che viene invocato dal file yml del tuo router, o in qualsiasi altro punto), richiama il template Twig. Ecco un esempio di modulo di test, richiamato da un file di routing yml nel modulo. (serve ulteriore documentazione per questa parte)

/**
 * @file
 * Contiene \Drupal\test_twig\Controller\TestTwigController.
 */
 
namespace Drupal\test_twig\Controller;
 
use Drupal\Core\Controller\ControllerBase;
 
class TestTwigController extends ControllerBase {
  public function content() {
 
    return [
      '#theme' => 'my_template',
      '#test_var' => $this->t('Test Value'),
    ];
 
  }
}

Puoi anche usare il metodo di rendering per costruire l’output se ti serve come parte di un altro flusso di lavoro nel tuo codice:

$renderable = [
  '#theme' => 'my_template',
  '#test_var' => 'test variable',
];
$rendered = \Drupal::service('renderer')->renderPlain($renderable);

Tieni presente che questa è un’implementazione di base che non applica alcun caching. I documenti di Render API Overview contengono ulteriori informazioni su come aggiungere caching. A proposito di caching – i nomi delle variabili vengono memorizzati nella cache, e se li cambi (ad esempio da «test_var» a «my_var»), dovrai ricostruire la cache.

Passo n. 3: Creare il template Twig
Nel tuo modulo, dentro la cartella templates, crea il file del template Twig. Il nome del file deve corrispondere a quello definito in hook_theme() (sostituisci gli underscore con i trattini). In questo caso il nome del file sarà my-template.html.twig.
Ecco un file di esempio usato per il test:

<p>Test twig template!</p>
 
<p>test_var: {{ test_var }}</p>

Il bello è che il file del template definito nel tuo modulo verrà usato se non esiste già nella tua tema. Basta inserire il file nella cartella templates del tuo tema, svuotare la cache (drush cache-rebuild), e Drupal leggerà quel file.

Puoi anche collocare il file in qualsiasi sottocartella del tema del sito, per mantenere tutto organizzato.