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
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
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
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
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
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.
- Previous post: Atomic design, Pattern Lab and Drupal 8 theme development
- Next post: Thoughts on how StarterKits can be used