Making Pattern Lab work with Drupal 8 Twig theme templates

Update: Please note that this is an old post and that the official version of Pattern Lab now works with Drupal 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.

Comments

Hi Colin, I do not know of a solution where the same template files can be shared between Pattern Lab and Drupal 7. The problem is that Pattern Lab uses Mustache or Twig templates and Drupal 7 uses PHPTemplate.

You can still integrate Pattern Lab and a Drupal 7 theme using a similar approach, the only difference being that a separate set of Mustache or Twig templates has to be created and kept in sync with Drupal 7 templates.

Hi there, there is this Pattern Lab for Gesso Drupal theme a link. I don't know if this is a good deal, but now I'm trying to use it and integrate Pattern Lab in my Drupal 7 project. I will write a feedback about it asap.

Submitted by Ensk on 29 March 2016

Permalink

hi aleskip and thanks for your solution, i would like to know how to add a partial twice. for example we have block--system-menu-block.html.twig with a json file with the same name and a menu.html.twig and his json file.

then if I want to show two menus I have to replicate all these files and so on for every menu ?? what is the way to acomplish this?

thank for help

Hi Ensk

If you want to include a pattern twice with different data you can use Twig variables. I have added an example to the organisms-list pattern and its JSON data.

In very simple cases it is also possible to use an include statement with the with keyword in the Twig template to pass the different data. However, at the moment this will not work if an Attribute object is manipulated in the included pattern template.

Hi aleskip thanks for the response but i can't understand how to take your example and use it with system--block-menu-block to display various menu in patternlab

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.