Anleitungen zur Umstellung von Drupal Twig (tpl.php auf html.twig)

Dieses Dokument wurde während des größten Teils des Twig-Umstellungsprozesses für Drupal 8 verwendet und kann auch für Sie nützlich sein, um Ihre eigenen Themes und Module für die Verwendung der Twig-Template-Engine in Drupal 8 zu aktualisieren.

Hinweis: Alle Arbeiten mit Twig werden nun im Drupal Core Issue Queue durchgeführt. Verwenden Sie nur die Twig-Umstellungs-Sandbox, um bereits umgestellte Templates und Funktionen zu finden.

Schritte für die Hauptbeteiligten:

• Finden Sie die Hauptprobleme, um Korrekturen zu posten und zu prüfen.
• Keine Patches an die Sandbox anwenden.
• Keine Patches für die Sandbox erstellen.
• Sandbox nur zum Testen und/oder zum Finden von bereits umgestelltem Code verwenden.
• Sehen Sie sich dieses YouTube-Video für eine Übersicht über diesen Prozess an.

Einrichtung

Drupal 8.0.x klonen:

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

Die aktuelle Arbeitsversion von Drupal wird im Ordner „d8“ installiert (benennen Sie ihn nach Belieben).

1. Installieren Sie Drupal wie gewohnt (unter Verwendung des Standard-Installationsprofils).
2. Setzen Sie alle 3 Twig-Einstellungen (debugging, cache, auto_reload) in services.yml auf True.

Umstellung

Themenfunktionen

Wandeln Sie eine Theme-Funktion in eine Template-Datei und eine Preprocess-Funktion um:

1. Bestimmen Sie die Datei, aus der Ihre Theme-Funktion stammt (theme.inc? Core/modules/color/?)
2. Erstellen Sie eine Template-Datei X.html.twig für Ihre Theme-Funktion:
                     - Benennen Sie Ihre neue Datei entsprechend
                     - Entfernen Sie „theme_“ vom Anfang Ihrer Funktion und beenden Sie den Dateinamen mit .html.twig
                     - Wandeln Sie Unterstriche („_“) in Bindestriche („-“) um.
                     - Beispiele:
                                * theme_link() wird zu link.html.twig
                                * theme_user_signature() wird zu user-signature.html.twig

3. Legen Sie Ihr neues Twig-Template im Template-Ordner des vollständigen Themes (im Sandbox) ab:
                     - für Funktionen, die aus einem bestimmten Modul stammen, z.B. stark/templates/comment usw.
                     - für Funktionen aus theme.inc, z.B. stark/templates/theme.inc
                     - für Funktionen aus form.inc, z.B. stark/templates/form.inc
4. Gehen Sie zur Dokumentation auf Drupal 8 API und suchen Sie Ihre Funktion.
                     - (Es gibt Links zu allen Funktionen in der Tabellendatei)
5. Fügen Sie am Anfang der Datei einen PHP-Dokblock ein und umschließen Sie ihn mit Twig-Kommentaren {# #}
                     - Fügen Sie ganz oben die Zeile @file hinzu.
                     - Kopieren Sie die Funktionsdefinition direkt unter die @file-Zeile. Ändern Sie „Returns HTML ...“ zu „Default theme implementation ...“. Schreiben Sie es so um, dass es in eine Zeile passt.
                     - Fügen Sie die Zeile „Verfügbare Variablen:“ hinzu (ersetzen Sie die Variablen in @param)
                     - Kopieren Sie die Variablen aus dem Abschnitt „Parameters“ in der api.drupal.org Dokumentation
                     - Entfernen Sie die Zeile @see template_preprocess(), falls vorhanden.
                     - Fügen Sie die Zeile @see template_preprocess_THEME_HOOK() hinzu.
                     - Fügen Sie die Theme-Zeile @ingroup hinzu (siehe Beispiel-Dokblock unten).

6. Kopieren Sie den Quellcode Ihrer Funktion unter den Dokblock (siehe Beispiel unten)
7. Ändern Sie den PHP-Code hauptsächlich zu HTML und Print-Operatoren
                   - Entfernen Sie PHP-Code aus HTML, Beispiele:
                               * function whatever() {
                               * // …
                               * return $output; }
                   - Entfernen Sie PHP-Print-Anweisungen und ersetzen Sie sie durch {{}}
                               * Wandeln Sie $variables in einfache Namen um: $variable['title'] wird zu {{title}}
                               * Ersetzen Sie Array-Syntax durch Punkt-Syntax: $variable['page']['tabs'] wird zu {{page.tabs}}
                   - Entfernen Sie PHP-Logik und ersetzen Sie sie durch Branch-Syntax {%%}.
                               * <?php foreach $items as $item?> wird zu {% for item in items %}
                   - Ersetzen Sie PHP-Kommentare durch Twig-Kommentare: {# #}
                   - Ersetzen Sie Funktionen t() um Literale durch den Filter t: {{ 'Text in Anführungszeichen'|t }}
                   - Verlegen Sie alle PHP-Logik für Variablen in eine Preprocess-Funktion. (Anweisungen zur Preprocess-Funktion siehe unten.)
8. Wenn Sie dabei Dinge entdecken, die verbessert werden könnten, z.B. das Zusammenführen scheinbar überflüssiger Templates zu einem oder die Verbesserung von Markup oder Variablennamen, vermerken Sie dies in dieser Tabelle oder erstellen Sie ein Issue in unserer Sandbox. Zum Beispiel: http://drupal.org/node/180591

Umwandlung oder Zusammenführung in Preprocess-Funktionen

HINWEIS:

• Preprocess-Funktionen ersetzen alle Theme-Funktionen.
• Wenn Ihr Template PHP-Logik enthält, die die ausgegebenen Variablen beeinflusst, muss dieser Code in eine Preprocess-Funktion verschoben werden.
• Wenn Ihr Template als Theme-Funktion begann, muss diese Theme-Funktion in eine Preprocess-Funktion umgewandelt werden.
• Falls einige Theme-Funktionen bereits assoziierte Preprocess-Funktionen haben, muss die Variablenverarbeitung aus diesen Theme-Funktionen in die Preprocess-Funktion verschoben werden.
• Fügen Sie keine Zeile in Ihre hook_theme-Implementierung ein, die Drupal anweist, eine Template-Datei statt einer Theme-Funktion zu verwenden.

ANWEISUNGEN:

• Benenne theme_YOURFUNCTION in template_preprocess_YOURFUNCTION um.
• Übergebe $variables als Referenz mit einem &-Zeichen, z.B. wird theme_select($variable) zu template_preprocess_select(&$variable).
• Bearbeite die Funktion so, dass nur die Logik zur Variablenverarbeitung enthalten ist; entferne jegliches Markup (also $output).

Wenn in Ihren Twig-Templates Filter oder Funktionen fehlen ...

Falls Sie Zugriff auf einen Filter oder eine Funktion im Twig-Template benötigen, der/die noch nicht funktioniert, fügen Sie ihn/sie in diese offene Aufgabe ein. Beachten Sie, dass die meisten PHP- oder Drupal-Funktionen in Preprocess-Funktionen verlagert werden sollten. Nur wenn Sie glauben, dass Theme-Entwickler direkten Zugriff auf diese Funktion brauchen, sollte sie im Template verbleiben.

EINFACHES BEISPIEL FÜR DIE UMSTELLUNG (theme_link)

PHP-Code

function theme_link($variables) { return '<a href="' . ($variables['options']['html'] ? $variables['text'] : check_plain($variables['text'])) . '">' . ($variables['options']['html'] ? $variables['text'] : check_plain($variables['text'])) . '</a>'; } 

Twig-Template (Dateiname: link.html.twig)

{# /**
 * @file
 * Default theme implementation to display a link.
 *
 * Available variables:
 * - text: The link text for the anchor tag.
 * - url: The complete URL being linked to, such as
 *   "/node/34" or "http://example.com/foo".
 * - attributes: Remaining HTML attributes for the containing element.
 *
 * @see template_preprocess_link()
 *
 * @ingroup themeable
 */ #}
<a href="{{ url }}" class="{{ attributes.class }}"{{ attributes }}>{{ text }}</a>

Änderungen in system.module (Preprocess-Funktion)

/**
 * Bereitet Variablen für Link-Templates vor.
 *
 * Standardtemplate: link.html.twig.
 *
 * @param array $variables
 *   Ein assoziatives Array mit:
 *   - text: Der übersetzte Linktext für das Ankerglied.
 *   - path: Der interne Pfad oder externe URL, auf die verlinkt wird.
 *   - options: Ein assoziatives Array mit zusätzlichen Optionen.
 */
function template_preprocess_link(&$variables) {
  $variables['url'] = url($variables['path'], $variables['options']);
}

Kommentare:

Andrey Podanenko: http://drupal.org/node/1783130 Wie Variablen umbenannt werden
jen: Fügen Sie Ihre eigenen Twig-Kommentaröffnungs- und -schlussmarker {# und #} hinzu.
jen: Folgen Sie Twig-Kommentar-Markern mit Standard-PHP-Doxygen-Markern für Doxygen.
jen: Kopieren Sie diese Definition aus api.drupal.org
James Wilson: Wenn Sie Definitionen von *Funktionen* kopieren, schreiben Sie „Returns HTML ...“ als „Default theme implementation“ um.
jen: Kopieren Sie „Parameters“ aus api.drupal.org
James Wilson: Entfernen Sie Dollarzeichen aus Variablennamen, falls Sie im Docblock auf andere Variablen verweisen, verwenden Sie einfache Anführungszeichen. [Siehe Richtliniendiskussion hier http://drupal.org/node/1804710]
jen: Sie „drucken“ Variablen im Template mit der Syntax {{}}
jen: Attribute sind „durchbohrt“, sodass Sie z.B. Klassen referenzieren können
jen: Die meisten Funktionen wie url() sollten aus der Template-Datei entfernt und stattdessen in die Preprocess-Funktion aufgenommen werden.