Drupal’s Twig extensions for JavaScript

It’s common for Drupal developers to use a style guide tool to document/display a project’s frontend components. Most of these style guide tools are written in JavaScript and don’t easily integrate with the PHP code in Twig. Fortunately, there are two different ports of Twig into JavaScript, Twig.js and Twing.

This project is the JavaScript port of Drupal 9’s Twig extensions for use with either Twig.js or Twing.

Installation

In order for this project to work, you must install either Twig.js or Twing.

To install Twig.js: npm install --save-dev twig

To install Twing: npm install --save-dev twing

Then install this project with:
npm install --save-dev drupal-twig-extensions

Usage

In your Twig templates, just follow the integration code below and you'll be able to use Drupal extensions like this:

{{ 'Hello World!'|drupal_escape }}

Twig.js 1.15.0 or later

If you use Twig.js, use the following JavaScript to integrate with Twig:

import Twig from 'twig';
import { addDrupalExtensions } from 'drupal-twig-extensions/twig';

// Add the extensions for Drupal.
addDrupalExtensions(Twig, {
  // Optionally, set options to configure how the Drupal
  // extensions should behave. See below for details.
});

Twing 5.0.2 or later

If you use Twing, use the following JavaScript to integrate with Twing:

import { TwingEnvironment, TwingLoaderRelativeFilesystem } from 'twing';
import { addDrupalExtensions } from 'drupal-twig-extensions/twing';

// Create an instance of the Twing Environment.
const twingEnvironment = new TwingEnvironment(
  new TwingLoaderRelativeFilesystem(),
);

// Add the extensions for Drupal.
addDrupalExtensions(twingEnvironment, {
  // Optionally, set options to configure how the Drupal
  // extensions should behave. See below for details.
});

// If you use twing-loader, it will need access to the same twing environment.
export default twingEnvironment;

Options for addDrupalExtensions()

Normally, these extensions would get their configuration from Drupal itself. Since this is a JavaScript environment, you'll need to provide some of that configuration yourself; just add the specified properties to the second argument of addDrupalExtensions.

addDrupalExtensions(twigOrTwing, {
  // Set the active theme's machine name; defaults to 'stark'.
  active_theme: 'zen',
  // Set the active theme's path. Uses the active_theme name to
  // determine the default value. Core themes default to
  // 'core/themes/[active_theme]'. Other themes default to
  // 'themes/custom/[active_theme]'.
  active_theme_path: 'themes/contrib/zen',

  // Override any of Drupal's default date_format patterns.
  // Or add your own custom formats.
  date_format: {
    long: 'Y-m-d H:i:s',
  },
});

If you don't want to specify any configuration options, you can skip the second argument. Like so:

addDrupalExtensions(twigOrTwing);

Implementation details

Filters

The official list of filters is in Drupal 9’s code and are described in Drupal’s Twig filters documentation.

• clean_class
• clean_id
• drupal_escape
• format_date
• placeholder
• render¹
• safe_join
• t²
• trans²
• without

¹ This filter does not work the same as it does in Drupal; it just returns the input cast to a string using its toString method. It is implemented to keep Twig compilation from breaking when this Drupal-specific filter is used in Twig templates.

² These filters do not work the same as they do in Drupal; they just return their input without modification. They are implemented to keep Twig compilation from breaking when these Drupal-specific filters are used in Twig templates.

Functions

The official list of functions is in Drupal 9’s code and are described in Drupal’s Twig functions documentation.

• active_theme
• active_theme_path
• attach_library³
• create_attribute
• file_url²
• link
• path²
• render_var¹
• url²

¹ This function does not work the same as it does in Drupal; it just returns the input cast to a string using its toString method. It is implemented to keep Twig compilation from breaking when this Drupal-specific function is used in Twig templates.

² These functions do not work the same as they do in Drupal; they just return their input without modification. They are implemented to keep Twig compilation from breaking when these Drupal-specific functions are used in Twig templates.

³ These functions do not work the same as they do in Drupal; they just return an empty string. They are implemented to keep Twig compilation from breaking when these Drupal-specific functions are used in Twig templates.

Tags

NOTE: Tags have not yet been implemented in this project.

The official list of tags is in Drupal 9’s code.

• trans, plural, and endtrans: These tags are described in Drupal’s “Translation in Twig templates” documentation.

Tests and operators

Drupal 9 does not currently implement any custom Twig tests or Twig operators.