Instructions for converting Drupal Twig (tpl.php to html.twig)

This document was used throughout most of the Twig conversion process for Drupal 8 and may also be useful to you when updating your own themes and modules to use the Twig template engine in Drupal 8.

Note: all Twig-related work is now done in the Drupal core issue queue. Use the Twig conversion sandbox only to find previously converted templates and functions.

Steps for core contributors:

• Find core issues to post and review patches.
• Do not apply patches to the sandbox.
• Do not create patches for the sandbox.
• Use the sandbox only for testing and/or retrieving previously converted code.
• Watch this YouTube video for an overview of the process.

Setup

Clone Drupal 8.0.x:

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

The current working version of Drupal will be installed in the "d8" folder (rename as desired).

1. Install Drupal as usual (using the Standard install profile).
2. Set all 3 Twig settings (debugging, cache, auto_reload) to True in services.yml.

Conversion

Theme functions

Convert theme function into a template file and preprocess function:

1. Identify the file from which your theme function came (theme.inc? Core/modules/color/?)
2. Create a X.html.twig template file for your theme function:
    - Name the new file accordingly
    - Remove theme_ from the beginning and end the name with .html.twig
    - Convert underscores ("_") to dashes ("-").
    - Examples:
      * theme_link() becomes link.html.twig
      * theme_user_signature() becomes user-signature.html.twig

3. Place your new Twig template in the template folder of the full theme (in sandbox):
    - for functions from a specific module: stark/templates/comment etc.
    - for functions from theme.inc: stark/templates/theme.inc
    - for functions from form.inc: stark/templates/form.inc
4. Refer to the Drupal 8 API documentation and locate your function.
    - (Links to all functions are available in the spreadsheet)
5. Add a PHP-style docblock at the top of the file and wrap it in Twig comments {# #}
    - Add an @file line at the very top.
    - Copy the function definition below the @file line. Rewrite "Returns HTML ..." as "Default theme implementation ...". Reword it to fit on one line.
    - Add a "Available variables:" line (replace @param variables)
    - Copy variable descriptions from the "Parameters" section on api.drupal.org
    - Remove @see template_preprocess() if present.
    - Add @see template_preprocess_THEME_HOOK().
    - Add @ingroup themeable.

6. Copy the source code of your function under the docblock (see example below).
7. Replace PHP code mostly with HTML and print statements:
    - Remove PHP tags and logic
      * function whatever() {
      * return $output; }
    - Replace print statements with {{}}
      * $variables['title'] becomes {{ title }}
      * $variables['page']['tabs'] becomes {{ page.tabs }}
    - Replace PHP logic with Twig control syntax {%%}
      * foreach becomes {% for item in items %}
    - Replace PHP comments with Twig comments: {# #}
    - Replace t() with the t filter: {{ 'text in quotes'|t }}
    - Move all variable logic into a preprocess function (see below)

8. If you find improvements while doing this, such as consolidating redundant templates or renaming variables, note them in the spreadsheet or sandbox issue. Example: http://drupal.org/node/180591

Converting or Merging into Preprocess Functions

NOTE:

• Preprocess functions will replace all theme functions.
• If your Twig template contains PHP logic affecting variables, move it to preprocess.
• Theme functions need to be turned into preprocess functions.
• If a theme function already has a related preprocess, merge logic there.
• Do not add a theme hook suggestion to use template instead of theme function.

INSTRUCTIONS:

• Rename theme_YOURFUNCTION to template_preprocess_YOURFUNCTION.
• Pass $variables by reference using &.
• Edit function to process variables only; remove markup (i.e., $output).

If your Twig template lacks functions...

If you need access to a filter or function not yet available in Twig templates, request it in the open issue. Most PHP or Drupal functions should go into preprocess. Only leave it in the template if theme developers need it there.

SIMPLE CONVERSION EXAMPLE (theme_link)

PHP Code

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

Twig Template (file name: 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
 */
#}
{{ text }}

Changes in system.module (preprocess function)

/**
 * 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']);
}

Comments:

Andrey Podanenko: http://drupal.org/node/1783130 How to rename variables
jen: Add your own Twig comment tags {# and #}
jen: follow Twig comment tags with standard PHP doxygen markers
jen: copy and paste function definition from api.drupal.org
James Wilson: Rephrase "Returns HTML ..." as "Default theme implementation"
jen: copy "Parameters" section from api.drupal.org
James Wilson: Remove $ from variable names in docs. Wrap variable names in single quotes. See discussion here
jen: print variables using {{ }}
jen: attributes are "drillable", so you can reference e.g., class attributes
jen: Most functions like url() should be removed from templates and added in preprocess.