Introduzione

Un tema è una raccolta di files che definiscono il livello presentazione del sito.

I temi devono trovarsi nella cartella themes/contrib/ se sono stati scaricati da Drupal.org o nella cartella themes/custom/ se sono temi personalizzati, non nella cartella core/themes così quando si aggiorna il core non si sovrascrivono i temi.

Struttura di un tema

I files e le cartelle che compongono il tema sono:

  • nome_tema.info.yml che definisce i metadati necessari per il tema
  • nome_tema.theme contiene logica PHP e gestisce la preelaborazione delle variabili prima che vengano visualizzate tramite i files di template
  • templates/*.html.twig che contengono markup e semplice logica di presentazione
  • nome_tema.libraries.yml che definisce CSS e JavaScript da includere nel tema
  • nome_tema.breakpoints.yml che definiscono i breakpoints per il responsive
  • config/install/nome_tema.settings.yml che contiene impostazioni per l'installazione
  • theme-settings.php per avere dei custom theme settings
  • cartelle css/, js/, images/ che contengono i corrispondenti files usati dal tema
  • nome_tema.post_update.php contiene funzioni di post-update da eseguire durante gli aggiornamenti successivi del codice, per esempio tramite update.php o drush updb
  • tests/ che contiene i test automatici

Il file .info.yml

Il file nome_tema.info.yml è l'unico obbligatorio e contiene obbligatoriamente i seguenti dati:

  • name: un nome leggibile per il tema
  • type: deve valere theme dato che si tratta di un tema
  • base theme: il nome macchina del tema che viene esteso dal tema custom. Se non si è sicuri di quale tema di base utilizzare, scegliere Stable9, se non si desidera utilizzare alcun tema di base, mettere false
  • core_version_requirement: indica la versione del core con cui il tema è compatibile

Altri dati sono facoltativi, come ad esempio:

  • description: una descrizione del tema
  • package: se si vogliono raggruppare più temi sotto uno stesso package
  • libraries: i files CSS e JavaScript da aggiungere alle pagine che utilizzano il tema
  • regions: per definire regioni personalizzate

Il file .theme

Il file .theme viene utilizzato quando il tema deve intervenire sulla fase di preparazione dei dati prima che questi vengano stampati nel template Twig. Per esempio nel file .theme si possono definire:

  • funzioni di preprocess, per modificare le variabili passate a template come page.html.twig, node.html.twig, block.html.twig o field.html.twig
  • alter hook, per modificare alcuni array o definizioni prima che vengano usati dal sistema di rendering
  • theme hook custom, quando si vuole associare un nuovo template Twig a un determinato render array o a un form
  • logica per allegare librerie CSS/JS solo in determinate condizioni

Le funzioni definite nel file .theme seguono una convenzione di naming basata sul nome macchina del tema. Per esempio, se il tema si chiama nome_tema, una funzione di preprocess per il template page.html.twig sarà:

<?php

/**
* Implements hook_preprocess_HOOK dove hook è il nome del tema mente HOOK è l'elemento che si vuole modificare
* quindi tutte le funzioni inizieranno per nome_tema_preprocess_ seguito da page, menu, ecc....
*/
function nome_tema_preprocess_page(array &$variables): void {
  // Modifica o aggiunta di variabili per page.html.twig.
}

?>

La cartella templates

Invece che modificare un file di template preesistente è preferibile apportare le modifiche a una copia dell'originale.

Per far ciò bisogna quindi

  1. individuare il template attualmente in uso
  2. copiare il template nel tema
  3. modificare il contenuto del template copiato

Dato che quindi possono esserci più files di template per una stessa parte della pagina Drupal va a cercare nell'ordine:

  1. nei templates del tema in uso
  2. nel tema base (se il tema custom deriva da un altro)
  3. nei files del core

Ad esempio per la stampa di un nodo Drupal cercherà un file denominato node.html.twig, ma possono esserci anche files utilizzati solo per uno specifico content type o uno specifico nodo, quindi cercherà anche altri templates in base a una convenzione di denominazione dei files. Ad esempio nel contesto della visualizzazione della pagina del nodo 123 verranno cercati i template nell'ordine:

  1. node--{NID}.html.twig (quindi node--123.html.twig)
  2. node--{TYPE}.html.twig (quindi node--page.html.twig)
  3. node.html.twig

La ricerca va dal più specifico al meno specifico, con l'opzione Twig debug abilitata nell'HTML verranno stampati dei commenti che mostrano i template disponibili e quello attualmente in uso. IL commento FILE NAME SUGGESTIONS mostra la lista dei possibili template, dal più specifico al meno specifico e mostra quello attualmente in uso, poi i commenti BEGIN OUTPUT e END OUTPUT mostrano cosa viene stampato da quel template.

Il file .libraries.yml

Il file .libraries.yml serve per definire le librerie di asset messe a disposizione dal tema. In Drupal, i file CSS e JavaScript non vengono normalmente caricati singolarmente e direttamente nei template, ma vengono raggruppati in librerie. Una libreria può contenere uno o più file CSS, uno o più file JavaScript e le eventuali dipendenze da altre librerie.

Nel file .libraries.yml si definisce la libreria ma non si indica dove verrà caricata.

Il caricamento della libreria può avvenire in punti diversi:

  • globalmente, dal file nome_tema.info.yml
  • in un template Twig, tramite attach_library()
  • in un render array, tramite #attached
  • nel file .theme, per esempio da una preprocess function o da un alter hook

Se un file JavaScript usa le API JavaScript di Drupal, è necessario indicare la dipendenza da core/drupal, se usa drupalSettings bisogna dichiarare anche la dipendenza corrispondente :

article-card:
  js:
    js/article-card.js: {}
  dependencies:
    - core/drupal
    - core/drupalSettings