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 and import statements (i.e. ES Module syntax) in your JavaScript, 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 "Options" below for
  // details.
});

If you use Twig.js and require statements (i.e. CommonJS syntax) in your JavaScript, use the following JavaScript to integrate with Twig:

const Twig = require('twig');
const { addDrupalExtensions } = require('drupal-twig-extensions/twig');

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

Twing 5.1.0 or later

If you use Twing and import statements (i.e. ES Module syntax) in your JavaScript, 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 "Options" below for
  // details.
});

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

If you use Twing and require statements (i.e. CommonJS syntax) in your JavaScript, use the following JavaScript to integrate with Twing:

const { TwingEnvironment, TwingLoaderRelativeFilesystem } = require('twing');
const { addDrupalExtensions } = require('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 "Options" below for
  // details.
});

// If you use twing-loader, it will need access to the same
// twing environment.
module.exports = 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',

  // Set the base_url of the Drupal install; defaults to '/'.
  base_url: '/',

  // Override any of Drupal's default stream wrappers.
  // Or add your own stream wrappers; new stream wrappers will
  // be merged with the default ones.
  streamWrapper: {
    'public://': 'sites/default/files',
    'private://': 'sites/default/private',
    'temporary://': 'sites/default/tmp',
  },

  // Override any of Drupal's default date_format patterns.
  // Or add your own custom formats; new formats will be
  // merged with the default ones.
  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
• render1
• safe_join
• t2
• trans2
• without

1 The render 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.

2 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_library3
• create_attribute
• file_url
• link
• path2
• render_var1
• url2

1 See the note above about the render filter.

2 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.

3 This function does not work the same as it does in Drupal; it just returns an empty string. It is implemented to keep Twig compilation from breaking when this Drupal-specific function is 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.