Іstruzioni per la conversione di Drupal Twig (da tpl.php a html.twig)

Questo documento è stato utilizzato per gran parte del processo di conversione Twig per Drupal 8 e può esserti utile anche per aggiornare i tuoi temi e moduli personalizzati per usare il motore di template Twig in Drupal 8.

Nota: tutto il lavoro con Twig ora viene svolto nella coda dei problemi del core Drupal. Usa solo la sandbox di conversione Twig per trovare template e funzioni già convertite.

Passaggi per i collaboratori principali:

• Trova i problemi principali per pubblicare e revisionare le patch.
• Non applicare patch alla sandbox.
• Non creare patch per la sandbox.
• Usa la sandbox solo per testare e/o ottenere codice già convertito.
• Guarda questo video su YouTube per una panoramica di questo processo.

Configurazione

Clonare Drupal 8.0.x:

git clone -b 8.0.x http://git.drupal.org/project/drupal.git d8

La versione di lavoro corrente di Drupal sarà installata nella cartella “d8” (puoi rinominarla come preferisci).

1. Installa Drupal normalmente (utilizzando il profilo di installazione Standard).
2. Imposta tutti e 3 i parametri di Twig (debugging, cache, auto_reload) su True in services.yml.

Conversione

Funzioni di tema

Converti una funzione di tema in un file di template e una funzione di preprocess:

1. Identifica il file da cui proviene la tua funzione di tema (theme.inc? Core/modules/color/?)
2. Crea un file di template X.html.twig per la tua funzione di tema:
        - Nomina il nuovo file in modo appropriato
        - Rimuovi theme_ dall’inizio della funzione e termina il nome con .html.twig
        - Converti gli underscore (“_”) in trattini (“-”)
        - Esempi:
            * theme_link() diventa link.html.twig
            * theme_user_signature() diventa user-signature.html.twig

3. Inserisci il nuovo template Twig nella cartella templates nel tema completo (in sandbox):
        - per funzioni provenienti da moduli specifici, stark/templates/comment ecc.
        - per funzioni provenienti da theme.inc, stark/templates/theme.inc
        - per funzioni provenienti da form.inc, stark/templates/form.inc
4. Vai alla documentazione API di Drupal 8 e trova la tua funzione.
        - (ci sono link a tutte le funzioni in questo foglio di calcolo)
5. Aggiungi un docblock in stile PHP in cima al file e racchiudilo nei commenti Twig {# #}
        - Aggiungi la riga @file all’inizio
        - Copia la definizione della funzione subito sotto la riga @file. Riscrivi “Restituisce HTML ...” come “Implementazione predefinita del tema ...”. Riscrivi su una sola riga.
        - Aggiungi la riga “Variabili disponibili:” (sostituendo le variabili @param)
        - Copia le variabili indicate nella sezione “Parametri” della documentazione api.drupal.org
        - Rimuovi la riga @see template_preprocess(), se esiste.
        - Aggiungi la riga @see template_preprocess_THEME_HOOK().
        - Aggiungi la riga tematica @ingroup (vedi esempio di docblock qui sotto).

6. Copia il codice sorgente della tua funzione sotto il docblock (vedi esempio sotto)
7. Modifica il codice PHP principalmente in HTML e operatori di stampa:
        - Rimuovi il codice PHP dall’HTML, esempi:
          * function whatever() {
          * // …
          * return $output; }
        - Rimuovi gli echo PHP e sostituiscili con {{}}
          * Converti $variables in nomi semplici: $variable['title'] diventa {{title}}
          * Sostituisci la sintassi degli array con quella a punti: $variable['page']['tabs'] diventa {{page.tabs}}
        - Rimuovi la logica PHP e sostituiscila con la sintassi Twig {%%}
          * <?php foreach $items as $item?> diventa {% for item in items %}
        - Sostituisci i commenti PHP con commenti Twig {# #}
        - Sostituisci le funzioni t() intorno ai letterali con il filtro t: {{ 'testo tra virgolette'|t }}
        - Sposta tutta la logica PHP delle variabili nella funzione di preprocess (vedi istruzioni sotto)
8. Se noti cose da migliorare, come unire template ridondanti o migliorare markup o nomi variabili, segnalo in questo foglio di calcolo o apri un issue nella sandbox. Ad esempio: http://drupal.org/node/180591

Conversione o unione nelle funzioni di preprocess

NOTA:

• Le funzioni di preprocess sostituiranno tutte le funzioni di tema.
• Se nel tuo file di template c’è logica PHP che influenza le variabili stampate, quel codice va spostato in una funzione di preprocess.
• Se il tuo template era inizialmente una funzione di tema, deve essere convertito in una funzione di preprocess.
• Se alcune funzioni di tema hanno già funzioni di preprocess associate, il codice di gestione delle variabili va spostato lì.
• Non aggiungere una riga al tuo hook_theme per dire a Drupal di usare un file di template al posto di una funzione di tema.

ISTRUZIONI:

• Rinomina theme_TUA_FUNZIONE in template_preprocess_TUA_FUNZIONE.
• Passa $variables per riferimento aggiungendo la &. Ad esempio: theme_select($variables) diventa template_preprocess_select(&$variables).
• Modifica la funzione per gestire solo la logica di preprocess delle variabili; rimuovi ogni markup (cioè $output).

Se nei tuoi template Twig mancano funzioni...

Se ti serve un filtro o una funzione in Twig non ancora disponibile, aggiungilo a questo issue aperto. Considera che la maggior parte delle funzioni PHP o Drupal va spostata in funzioni di preprocess. Solo se pensi che uno sviluppatore di temi abbia bisogno di accedervi, dovrà restare nel template.

ESEMPIO SEMPLICE DI CONVERSIONE (theme_link)

Codice PHP

function theme_link($variables) { return '' . ($variables['options']['html'] ? $variables['text'] : check_plain($variables['text'])) . ''; } 

Template Twig (nome file: link.html.twig)

{# /** * @file * Implementazione predefinita del tema per mostrare un link. * * Variabili disponibili: * - text: Il testo del link per il tag anchor. * - url: L’URL completo a cui si collega, come * "/node/34" o "http://example.com/foo". * - attributes: Altri attributi HTML per l’elemento contenitore. * * @see template_preprocess_link() * * @ingroup themeable */ #} 
<a href="{{ url }}" class="{{ attributes.class }}"{{ attributes }}>{{ text }}</a> 

Modifiche in system.module (funzione di preprocess)

/** 
 * Prepara le variabili per i template dei link.
 *
 * Template predefinito: link.html.twig.
 *
 * @param array $variables
 *   Un array associativo contenente:
 *   - text: Il testo tradotto del link per il tag anchor.
 *   - path: Il percorso interno o l’URL esterno a cui si collega.
 *   - options: Un array associativo di opzioni aggiuntive.
 */
function template_preprocess_link(&$variables) {
  $variables['url'] = url($variables['path'], $variables['options']);
} 

Commenti:

Andrey Podanenko: http://drupal.org/node/1783130 Come rinominare le variabili
jen: Aggiungi i tuoi marker di commento Twig {# e #}.
jen: segui i marker di commento Twig con i marker PHP standard di doxygen per doxygen.
jen: copia e incolla la definizione da api.drupal.org
James Wilson: quando copi la definizione da una *funzione*, riscrivi “Restituisce HTML ...” come “Implementazione predefinita del tema ...”
jen: copia e incolla la sezione “Parametri” da api.drupal.org
James Wilson: Rimuovi il simbolo $ dai nomi delle variabili; se devi fare riferimento a un’altra variabile nel docblock, usa apici singoli attorno al nome della variabile. [Vedi discussione della policy qui http://drupal.org/node/1804710]
jen: “stampa” le variabili in Twig con la sintassi {{}}
jen: gli attributi si “forano” così puoi riferirti a classi ecc.
jen: La maggior parte delle funzioni, come url(), va rimossa dal file di template e invece aggiunta nel preprocess.