Making Pattern Lab work with Drupal 8 Twig theme templates

In the solutions described in this post I have tried to use the existing extension mechanisms built into Pattern Lab as much as possible, and not to introduce any dependencies to Drupal core. The end result is that Pattern Lab can be used on its own with just the Twig templates, CSS and other assets from a Drupal theme.

Drupal Twig StarterKit

Drupal templates use custom Twig filters, functions and tags. Support for these Twig extensions can be added to Twig PatternEngine via a custom StarterKit. Drupal's extensions can be replaced with simple alternative versions that have no Drupal dependencies.

Data Transform Plugin

The Attribute object is used extensively in Drupal theme templates. Drupal templates also use variables that contain HTML rendered from other templates. However, currently Pattern Lab only supports plain string data from JSON files.

Pattern Lab plugins can listen to events and hook into the build process. A plugin can be used to process the JSON string data before patterns are rendered.

Data Transform Plugin is a plugin that can transform data into something expected by Drupal theme templates. Drupal Attribute objects and rendered templates can be added using special syntax in Pattern Lab's JSON data files.

Data Transform Plugin also has a function to join strings, which can be very useful. The plugin is PatternEngine agnostic and can be used with Mustache templates as well.

Patches to Pattern Lab Core

Change link to patternLink

link is a custom function used in some Drupal theme templates. Unfortunately it is also a reserved key in Pattern Lab, used for the pattern linking feature. It seems to be used only internally though, so a small patch that changes link to patternLink will hopefully not cause any problems. The patch does not change the syntax used in patterns.

Patches to Twig PatternEngine

Extend templates from the _patterns directory

The current version of Twig PatternEngine's template loader does not support extending templates from the _patterns directory. All that is required to support this feature used by some Drupal theme templates is to add a few lines of code. This solution admittedly does seem to go against Twig PatternEngine's design, but it does do what we want...

Add auto-escape support

The contents of Twig variables are HTML auto-escaped by default, so we need to add support for disabling autoescaping to Twig PatternEngine.

Pass pattern specific data to included patterns

An issue with the current version of Twig PatternEngine is that pattern specific data is not passed to included patterns. Included patterns do get the data from the parent pattern, but not the pattern specific data which needs to be used with Drupal theme templates.

One solution inspired by a great blog post by Matthias Noback is to use a Node Visitor and a wrapper class to add the data in the template compilation phase. This solution seems to do what we want with string data, but will convert Attribute objects to strings.

Special handling for Attribute objects could be added to the PatternDataIncludeNode class, but this would introduce Drupal specific code to Twig PatternEngine. For now the Twig include tag cannot be used with this solution if an Attribute object is manipulated in the included template. A workaround is to add the template as a variable using the include feature of Data Transform Plugin.

That's all, Folks!

That was all that was required to create Shila theme, which was introduced in my previous post.