Miglioramento dell’inclusione di Twig per i temi secondari tramite l’estensione personalizzata (Drupal 8)

Cos’è Twig?

Twig è un motore di template utilizzato dai siti web di Drupal 8 che semplifica l’inserimento di contenuti dinamici nelle pagine web. Twig ha alcune utili funzionalità integrate, come una funzione include che consente a file separati di referenziarsi l’un l’altro, consentendo al codice di essere più modulare. In questo post spiegherò come e perché vogliamo migliorare questa funzione di inclusione predefinita tramite un’estensione Twig personalizzata.

Perché scherzare con esso?

Forse ti starai chiedendo “perché qualcuno vorrebbe cambiare la funzione di inclusione di Twig?” Non c’è nulla di rotto con la funzione di inclusione principale, ma potrebbe essere più flessibile, specialmente quando si tratta di temi secondari.

La necessità di una funzione di inclusione più flessibile è nata quando stavo tentando di creare un sottotema di un tema personalizzato preesistente. Un file modello all’interno del tema di base utilizzava la funzione Twig include per fare riferimento a un altro file. La semplice copia del file nel sottotema ha causato un errore perché il percorso definito nell’inclusione sarebbe sempre e solo in un posto. Se il file esistesse solo in uno dei temi e il percorso stesse verificando il tema sbagliato, non sarebbe riuscito a trovare il file, generando un errore fatale.

Ciò di cui avevo bisogno era un’inclusione che controllasse più posizioni per il file. Gli include Twig sono comunemente implementati come percorso hardcoded o coinvolgono una variabile combinata con una stringa per generare dinamicamente il percorso, entrambi i metodi possono causare problemi durante la creazione di un sottotema.

Il percorso hardcoded include il riferimento a una posizione specifica del tema, che quando viene copiata tra i temi, farà sempre riferimento alla posizione esatta del percorso impostato originale. I percorsi variabili consentono un riferimento dinamico al tema corrente, consentendo di copiare il codice tra i temi senza la necessità di aggiornare i percorsi. I percorsi variabili sono un passo nella giusta direzione ma non eseguono il fallback al tema principale se il file non viene trovato.

Vale la pena notare che è possibile passare più percorsi in un Twig include in questo modo:

Il primo percorso per restituire un file sarà quello utilizzato. Questo è il tipo di funzionalità di riserva che desideriamo, ma non è molto scalabile. Ogni volta che un tema viene aggiunto o rimosso, l’array include dovrebbe essere aggiornato manualmente.

In un mondo perfetto

Per illustrare la funzionalità ideale, immagina le seguenti strutture del tema:

– tema-genitore /
– template.html.twig
– component.html.twig
– sub-theme-a /
– template.html.twig
– sub -theme-b /
– component.html.twig

In questo esempio, ogni sottotema ha il tema principale di “tema-genitore” e i file denominati “template.html.twig” includono il file “component.html.twig”. Questi sono i file a cui vogliamo che ogni sottotema faccia riferimento automaticamente senza bisogno di aggiornare il percorso dichiarato in include:

– sub-theme-a:
– sub-theme-a / template.html.twig (sovrascrittura del tema secondario predefinito corrente)
– parent-theme / component.html.twig (personalizzato include fallback )
– sub-theme-b:
– parent-theme / template.html.twig (fallback del sottotema predefinito corrente)
– sub-theme-b / component.html.twig (inclusione personalizzata override)

Per ottenere ciò, la nostra sintassi ideale potrebbe essere simile a questa:

La chiave qui è usare un percorso relativo alla radice del tema quando si definisce il file da includere. In questo modo il percorso non è specifico di un tema, consentendo la risoluzione dello stesso percorso in qualsiasi tema.

Costruirlo da soli

Fortunatamente, Twig consente la creazione di estensioni personalizzate con le quali possiamo aggiungere la nostra funzionalità personalizzata a Twig. Questa estensione Twig avrà la forma di un modulo Drupal 8 in modo che possa essere facilmente abilitata sui progetti Drupal 8.

La struttura del file del modulo è simile a questa:

– twig_extension_theme_include /
– src /
– Theme_Include_Twig_Extension.php
– twig_extension_theme_include.info.yml
– twig_extension_theme_include.services.yml

twig_extension_theme_include.info.yml

Questo è solo un file di informazioni di base sul modulo, niente di straordinario.

twig_extension_theme_include.services.yml

Il file services è una piccola porzione di codice necessaria a Drupal per riconoscere l’estensione personalizzata. All’interno di questo file diciamo a Drupal quale classe dovrebbe usare e che è un’estensione Twig tramite il tag: `twig.extension`. Nei commenti ho suddiviso la sintassi per le poche righe confuse.

Theme_Include_Twig_Extension.php

Il codice è pesantemente commentato per spiegare cosa sta succedendo riga per riga, ma a un livello più alto, la funzione `theme_include ()` inizia dal tema attivo e tenta di trovare il file tramite il percorso passato. Usa la funzione `file_exists_in_theme ()` per determinare se un tema contiene il file o meno. Se un tema non ha il file specificato, la funzione controlla il tema principale e continua con questo modello fino a quando il file non viene trovato o non ci sono più temi principali. Al termine del ciclo, il percorso del file trovato viene inviato alla funzione di inclusione Twig predefinita. Come riserva, se non viene trovato alcun file, il percorso della posizione prevista del file all’interno del tema attivo viene inviato alla funzione di inclusione predefinita. Questo viene fatto sapendo che se “ignora mancante” non è impostato, si verificherà un errore fatale. Il motivo per cui lo facciamo è che vogliamo che la funzionalità, inclusa la gestione degli errori, rimanga il più vicino possibile alla funzione di inclusione originale. Stiamo semplicemente filtrando i dati passati all’inclusione.

È importante notare che questa funzione non duplica la funzionalità dell’inclusione di Twig standard, ma controlla piuttosto l’esistenza di file prima di passare un percorso specifico all’inclusione di Twig. Ciò è vantaggioso per alcuni motivi: ciò consente il riutilizzo del codice preesistente, questa estensione beneficerà automaticamente degli aggiornamenti effettuati all’inclusione predefinita e il comportamento dovrebbe essere già familiare a chiunque abbia familiarità con l’inclusione predefinita. Questo è anche il motivo per cui la funzione accetta gli stessi argomenti dell’inclusione predefinita, poiché tali argomenti vengono passati all’inclusione predefinita. Per farlo correttamente ho fatto riferimento al codice sorgente di Twig include.

Esempio di utilizzo

Con il nostro modulo personalizzato installato, i nostri inclusi normali possono essere convertiti in include a tema.

Ciò consente di copiare i file che utilizzano include tra i sottotemi mantenendo la funzionalità di sovrascrittura dei sottotemi funzionante come previsto. Puoi trovare una copia del prodotto finito e la documentazione di utilizzo qui: https://github.com/alexspirgel/twig_theme_include.

Originariamente pubblicato sul blog della Eastern Standard. Per ulteriori informazioni sullo standard orientale, visita easternstandard.com.