Instructies voor het omzetten van Drupal Twig (tpl.php naar html.twig)

Dit document werd gebruikt tijdens het grootste deel van het Twig-conversieproces voor Drupal 8 en kan ook nuttig voor je zijn om je eigen thema’s en modules bij te werken voor gebruik van de Twig template-engine in Drupal 8.

Opmerking: al het werk met Twig gebeurt nu in de issue queue van de Drupal core. Gebruik alleen de Twig-conversie sandbox om eerder geconverteerde templates en functies terug te vinden.

Stappen voor kernbijdragers:

• Vind de belangrijkste issues om patches te publiceren en te beoordelen.
• Pas geen patches toe op de sandbox
• Maak geen patches aan voor de sandbox.
• Gebruik de sandbox alleen voor testen en/of het verkrijgen van eerder geconverteerde code.
• Bekijk deze YouTube-video voor een overzicht van dit proces.

Instellen

Clone Drupal 8.0.x:

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

De huidige werkversie van Drupal wordt geïnstalleerd in de map “d8” (noem deze zoals je wilt)

1. Installeer Drupal zoals gewoonlijk (gebruikend het Standaard install Profiel).
2. Zet alle 3 Twig-instellingen (debugging, cache, auto_reload) op True in services.yml.

Conversie

Themafuncties

Converteer een themafunctie naar een templatebestand en een preprocess-functie:

1. Bepaal het bestand waar je themabron vandaan komt (theme.inc? Core/modules/color/?)
2. Maak een X.html.twig templatebestand voor je themafunctie:
               - Geef je nieuwe bestand een passende naam
               - Verwijder theme_ aan het begin van je functie en eindig de bestandsnaam met .html.twig
               - Zet underscores (“_”) om in koppeltekens (“-”).
               - Voorbeelden:
                 * theme_link() wordt link.html.twig
                 * theme_user_signature() wordt user-signature.html.twig

3. Zet je nieuwe Twig-template in de templates-map van het volledige thema (in sandbox):
               - voor functies afkomstig uit een bepaalde module, stark/templates/comment enz.
               - voor functies afkomstig uit theme.inc, stark/templates/theme.inc
               - voor functies afkomstig uit form.inc, stark/templates/form.inc
4. Ga naar de Drupal 8 API documentatie en zoek je functie op.
               - (er zijn links naar alle functies in de spreadsheet)
5. Voeg een PHP-stijl docblock toe bovenaan het bestand en omring het met Twig-commentaar {# #}
               - Voeg de @file regel helemaal bovenaan toe.
               - Kopieer de functiedefinitie direct onder de @file regel. Herschrijf “Return HTML ...” als “Default theme implementation ...”. Zorg dat het op één regel past.
               - Voeg een regel “Available variables:” toe (vervang de @param variabelen)
               - Kopieer de variabelen uit de “Parameters” sectie van de documentatie op api.drupal.org
               - Verwijder de regel @see template_preprocess(), indien aanwezig.
               - Voeg een regel @see template_preprocess_THEME_HOOK() toe.
               - Voeg een thematische @ingroup regel toe (zie voorbeeld docblock hieronder).

6. Kopieer de broncode van je functie onder het docblock (zie voorbeeld hieronder)
7. Verander PHP-code grotendeels naar HTML en printstatements
               - Verwijder PHP-code uit HTML, voorbeelden:
                  * function whatever() {
                  * // …
                  * return $output; }
               - Vervang PHP print-statements door {{}}
                  * Zet $variables om naar eenvoudige namen: $variable['title'] wordt {{title}}
                  * Vervang array-syntax door dot-syntax: $variable['page']['tabs'] wordt {{page.tabs}}
               - Verwijder PHP-logica en vervang door Twig control flow {%%}.
                  * <?php foreach $items as $item?> wordt {% for item in items %}
               - Vervang PHP-commentaar door Twig-commentaar {# #}
               - Vervang t() functies rond teksten door t-filter: {{ 'text in quotes'|t }}
               - Verplaats alle PHP-logica voor variabelen naar de preprocess-functie (zie preprocess-instructies hieronder.)
8. Als je verbeteringen ziet, zoals het samenvoegen van ogenschijnlijk dubbele templates of het verbeteren van markup of variabelenamen, noteer dat in de spreadsheet of maak een issue aan in de sandbox. Bijvoorbeeld: http://drupal.org/node/180591

Conversie of verplaatsing naar preprocess-functies

OPMERKING:

• Preprocess-functies vervangen alle themafuncties.
• Als er PHP-logica in je template staat die invloed heeft op variabelen die geprint worden, moet die code verplaatst worden naar de preprocess-functie.
• Als je template begon als een themafunctie, moet die themafunctie worden geconverteerd naar een preprocess-functie.
• Als sommige themafuncties al preprocess-functies hebben, moet de variabelenverwerking uit die themafuncties naar preprocess worden verplaatst.
• Voeg geen regel toe in je hook_theme implementatie die Drupal zegt een templatebestand te gebruiken in plaats van een themafunctie.

INSTRUCTIES:

• Hernoem theme_JOUWFUNCTIE naar template_preprocess_JOUWFUNCTIE.
• Geef $variables door als reference door een ampersand toe te voegen. Dus theme_select($variable) wordt template_preprocess_select(&$variable).
• Bewerk de functie om enkel variabelenlogica te verwerken; verwijder alle markup (bijv. $Output).

Als functies ontbreken in je Twig-templates ...

Als je een filter of functie nodig hebt in een Twig-template die nog niet werkt, voeg die toe in dit open issue. Houd er rekening mee dat de meeste PHP- of Drupal-functies naar preprocess moeten worden verplaatst. Alleen als een themadeveloper toegang tot die functie nodig heeft, moet ze in de template blijven.

EENVOUDIG CONVERSIEVOORBEELD (theme_link)

PHP-code

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

Twig-template (bestandsnaam: 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> 

Wijzigingen in system.module (preprocess-functie)

/** * Prepares variables for link templates. * * Default template: link.html.twig. * * @param array $variables * An associative array containing: * - text: The translated link text for the anchor tag. * - path: The internal path or external URL being linked to. * - options: An associative array of additional options. */ function template_preprocess_link(&$variables) { $variables['url'] = url($variables['path'], $variables['options']); } 

Opmerkingen:

Andrey Podanenko: http://drupal.org/node/1783130 Hoe variabelen te hernoemen
jen: Voeg je eigen Twig-commentaar open- en sluitmarkers toe {# en #}.
jen: gebruik Twig-commentaar samen met standaard PHP doxygen markers voor doxygen.
jen: kopieer en plak deze definitie uit api.drupal.org
James Wilson: Als je een definitie kopieert van een *functie*, herschrijf dan “Return HTML ...” naar “Default theme implementation ...”
jen: kopieer en plak “Parameters” uit api.drupal.org
James Wilson: Verwijder het dollarteken uit variabelennamen, en als je in een docblock naar een andere variabele moet verwijzen, gebruik dan enkele aanhalingstekens rond de variabele. [Zie beleidsdiscussie hier http://drupal.org/node/1804710]
jen: je “print” variabelen in Twig met {{}} syntax
jen: attributen zijn “doorgeboord”, zodat je naar bijvoorbeeld classes kunt verwijzen
jen: De meeste functies zoals url() moeten verwijderd worden uit de template en toegevoegd worden in preprocess.