Oct 20 2019
Oct 20

There has been amazing progress with Drupal’s API-First Initiative in the past few years. A major milestone was when JSON:API was added to core as a stable module in Drupal 8.7.

An API-first Drupal enables many things, but probably the best known use case of APIs is a decoupled front-end. Numerous blog posts and at least one book have been been written about decoupled Drupal. There have been many conference sessions on the topic, and there is an entire conference focused only on decoupled CMS architectures.

These exciting developments ensure that Drupal stays relevant, and that it is a first-class choice for building ambitious digital experiences in the modern web development landscape, where component-based JavaScript front-end libraries and frameworks like React and Vue are so popular.

A lot of the activity around decoupled Drupal originates from developers and other employees of Drupal agencies working on projects for large enterprises and organizations. These projects might require a content service not just for for app-like websites, but also for other publishing channels like native mobile apps and digital kiosks.

However, from a practical requirements and resources point of view, the vast majority of website owners just need a traditional website. And for someone like me, who often works as the only developer on (non-ambitious?) traditional website projects, JavaScript-based decoupled front-ends are interesting, but not required.

There are other ways

When so much attention is focused on APIs and JavaScript, it is possible to miss or forget the fact that loose coupling and components are general architectural principles that can be implemented in many different ways. A different approach can be used to get many of the benefits of a decoupled, component-based front-end.

Component-based theming is a commonly used name for a specific way to develop and organize Twig templates and related assets in Drupal themes. I am not sure how well known it is that component-based theming is actually a way to decouple most of the front-end from Drupal.

The best known benefit of this decoupling approach is the possibility to develop most of the theme layer independently of Drupal, with the help of a tool like Pattern Lab. But while there are already some very interesting examples out there, I believe that the full potential of decoupled Twig components is yet to be realized. By this I mean Twig component libraries that can be used with minimal integration effort in both Drupal and WordPress, for example. I believe that agencies offering services for both platforms could benefit a lot from this.

For ‘small Drupal’ too

Since it is often associated with style guides and design systems, it is possible to get the impression that component-based theming is only useful for large teams working on projects for large clients. However, I know from my own experience that even single-developer projects can benefit from it.

Component-based theming adds very little overhead to regular Drupal theming. Thinking in components can improve the quality of your work in many ways, and most importantly, building anything from blocks is fun!

There is no requirement to develop a style guide – although you might find that you end up with the beginnings of one as a happy side result.

A decoupled front-end means that work on the theme can be started even before Drupal is installed, and clients can be shown the design in a real browser much sooner.

So unless you are working on a project that requires a JavaScript-based front-end, I can warmly recommend component-based theming to teams and projects of all sizes.

Decoupling the front-end without APIs and JavaScript

https://www.aleksip.net/decoupling-the-front-end-without-apis-and-javasc...

Aug 25 2019
Aug 25

I have previously written about using Drupal’s definition files in component-based theming and how it is possible to have component-specific layout and asset library definition files. Now that Layout Builder is stable it is time to have a look at how it can be used with theme components.

Two schools

There are two main approaches to integrating independent theme components with Drupal. They could be described as the ‘Twig developer’ approach and the ‘site builder’ approach.

In the Twig developer approach integration is done entirely in Twig ‘presenter’ templates. A significant benefit of this straightforward approach is that no contrib modules are required (although Component Libraries is usually used). There is also no need for endless pointing and clicking in the admin UI, and dealing with related configuration. The downside is that in most cases this approach leaves the admin UI disconnected from the components. This means that a site builder not familiar with Twig or with no access to the Twig templates has no way of affecting the appearance of the integrated components.

In the site builder approach integration is done using the admin UI. Until now this has required sophisticated contrib modules like Display Suite and UI Patterns, with their own ecosystems of related modules. These are great modules, but ideally it should be possible to use just Drupal core for the site builder approach. With Layout Builder in core we are a huge leap closer to that goal.

Revisiting an old example

Back in January 2017 I wrote a blog post on how to use UI Patterns to integrate a simple Code component. I will now use the same component in an example of how to use Layout Builder for the same task.

Step 1: Create layout and asset library definitions

Starting from where we ended up in that old blog post, we need to provide information about the component’s variables and assets to Drupal in some other way than a .ui_patterns.yml file. This can now be easily done using Drupal core’s definition files.

Drupal core only supports theme (or module) specific definition files, but the Multiple Definition Files module can be used to add support for component-specific files. The results are identical in both approaches, so using Multiple Definition Files is completely optional.

Multiple Definition Files does add one useful feature though. Drupal places layout regions in content, so for example a code region would be accessed in Twig as content.code. To remove this Drupalism, Multiple Definition Files makes layout regions accessible in the Twig root context, so a code region is accessible in Twig as just code.

The definitions in this example are in component-specific files. If you want to use Multiple Definition Files, be sure to enable the module at this point.

The layout definition, shila-code.layouts.yml:

shila_code:
label: 'Code'
category: 'Shila'
template: source/_patterns/01-molecules/content/shila-code/shila-code
library: shila_theme/shila_code
regions:
language:
label: 'Language'
code:
label: 'Code'

and the library definition, shila-code.libraries.yml:

shila_code:
css:
theme:
source/_patterns/01-molecules/content/shila-code/prism.css: {}
js:
source/_patterns/01-molecules/content/shila-code/prism.js: {}

Note the library reference in shila-code.layouts.yml, linking the two definitions. Be sure to clear caches after adding the new definitions.

(As a side note, the UI Patterns From Layouts module makes it possible to use Drupal’s definition files with UI Patterns as well.)

Step 2: Enable Layout Builder

After enabling the Layout Builder module, Layout Builder has to be enabled for our Code paragraphs type’s display.

If you are moving away from a Display Suite layout, be sure to select - None - for the layout and save the settings before enabling Layout Builder. It seems that if you do not do this, Display Suite is still active and Layout Builder won’t work as expected.

Step 3: Integrate the component using Layout builder

Clicking on the ‘Manage layout’ button takes us to Layout Builder. Display Suite and UI Patterns show a textual representation of a layout, but Layout Builder is different as it displays the layout visually.

First we remove the default section, then we add a new section and choose the ‘Code’ layout for it.

As a reminder, this is what our extremely simple shila-code.html.twig template looks like:

<pre><code{% if language %} class="language-{{ language }}"{% endif %}>{{ code }}</code></pre>

Layout Builder’s visual representation will not be a problem in many cases. However, components often use variables for non-visual purposes or have layouts with overlapping regions. Our Code component is a good example, since language is used as a part of a CSS class name. Layout Builder does not expect layouts to be used in this way, and the result is a completely unusable UI.

Oh no. What we need is a text based way to configure the layout. The good news is that due to accessibility reasons a textual version of the Layout Builder UI is already in the works. So, let’s apply the patch from that issue, clear the caches, and see what happens.

A ‘Layout overview’ link has appeared! Let’s click on it.

This is looking good! We can now add the right paragraph fields to the respective regions in the Code layout and then click on the ‘Save layout’ button. Let’s have a look at a page that contains a Code paragraph.

Something is obviously going wrong here. Let’s have a look at the HTML source.

Since we have placed fields in Layout Builder blocks, there is unwanted HTML from the block and field templates. What we really need is just the contents of the fields, nothing else. This can be an issue with many independent theme components, since they often do not expect extra markup to be provided.

Display Suite has a ‘Full Reset’ field formatter and UI Patterns has an ‘Only content’ option. But what can we do here? Creating specific Twig templates to remove the HTML is an option, but not an ideal one. What we want is an easy UI based way to deal with the problem.

Step 4: Install and enable the Full Reset module (if required)

After searching for existing solutions and not coming up with anything, I ended up writing a small module for this particular purpose. Full Reset does two things: it provides a field formatter and adds a reset option to Layout Builder blocks. The name is a hat tip to the trusty Display Suite field formatter I have used so many times.

A good way to support third party settings for Layout Builder blocks is still being worked on, so a core patch must be applied for Full Reset to work.

With the core patch applied and Full Reset installed and enabled, we can select the ‘Full Reset’ field formatter and tick the ‘Full Reset this block’ checkbox.

Now the block and field templates are not used at all, and the component works and looks like expected! It still does not work in Layout Builder’s visual preview though, because Layout Builder expects the content to be a valid DOM node and have a surrounding HTML tag. For this reason Full Reset does not remove block theming in the preview.

Conclusion

Layout Builder can be successfully used in component-based theming today. There might be some problems with specific components like the one in this example, but these problems can be circumvented by applying two patches and using the Full Reset module.

For me this means that I can now stop using Display Suite, a module that I have used in almost all of my Drupal projects since 2011. Personally I find this change to be just as significant as it was when Field API and Views were added to core.

Jul 12 2019
Jul 12

The PHP version of Pattern Lab has been a trusty tool for a long time, especially for many of us working with Twig and component-based theming for Drupal. However, ever since a decision was made to focus development efforts on Pattern Lab Node, it has been clear that it would eventually become necessary to switch from using the PHP version to using the Node version.

Twig developers do not need to worry about compatibility, since thanks to the efforts of Evan Lovely and Salem Ghoweri, Pattern Lab Node now uses a PHP Twig renderer to render Twig templates. This means that templates are rendered using the official PHP implementation of Twig, and it is even possible to add PHP extensions to the Twig environment used by the renderer.

Pattern Lab Node 3.0 is the future of Pattern Lab, with many improvements over the PHP version, especially in the UI. However, it is still in beta and a bit rough around the edges. There have been issues with pseudo-patterns, and more work is needed to support plugins. With well-established development approaches based on the use of data files and plugins in Pattern Lab PHP, how can we make the switch to using the Node version?

A new approach

Limitations can often drive creativity. I do not know if that is the case here, but a great new development approach is being used by folks already using Pattern Lab Node. This approach was described by Evan Lovely in his excellent presentation ‘Pattern Lab: The Definitive How-to’, and is used by Aaron Froehlich and Jeff Amaral in Union, an inspiring project well worth checking out.

The basic idea in this new approach is to use a new type of template in Pattern Lab. These new templates provide demo data for the actual component templates, making traditional Pattern Lab JSON/YAML data files mostly unnecessary.

As an example, if we have a _heading.twig template (note the leading underscore, which hides the pattern in Pattern Lab)

instead of creating a heading.yml data file

we create a heading-demo.twig template

These demo templates are very similar to ‘presenter’ templates used in component-based Drupal theming, as they only process and pass data to the actual component templates, and do not contain any markup.

Pros and possible cons

Even though plugins like Data Transform Plugin can make plain data files more powerful, using Twig to provide demo data opens up a whole new world of possibilities. For example, demo templates can use Twig extensions that might not be acceptable in plain Twig components. I am certain that there will be a lot of innovation within this approach and related best practices in the future.

One possible drawback is that the Pattern Lab UI will display the Twig source of the demo template instead of the source of the actual component. However, it is only a possible drawback, as in many cases it might actually be useful to show how the component should be included from another template. And it is still possible to use a data file if it is important to show the source of the component itself.

A new version of Shila theme

I have been wanting to switch to using Pattern Lab Node for some time now, and this new approach has made it possible. I have refactored Shila theme, which I use as a starting point for all my Drupal theme projects, to use demo templates. This change makes it possible to use Shila theme with both Pattern Lab PHP and Pattern Lab Node. If you are interested in seeing an example of a full implementation of this new approach, be sure to check out the new version of Shila theme.

Nov 21 2018
Nov 21

All the great work already done and to be released by the Layout Initiative has inspired me to think about how core’s definition files can be used in component-based theme development. As a result I am now happy to announce two Drupal modules and a Pattern Lab plugin which enable new ways of using core’s definition files.

Layout definitions have superpowers

Layout definition regions can be used for both blocks and fields, to create both page-level layouts and more intricate layouts for smaller pieces of content and components.

Data mapped to layout regions can also be used in component template files to configure the component in some way, instead of just displaying the data as it is.

The terms ‘layout’ and ‘region’ can be a bit misleading in that last use case. However, I am not aware of any reason why layouts should not be used in this way. Layout definitions have been successfully used as de facto component definitions in component-based theming for quite a while now. There are no ugly hacks involved, and soon Drupal core will even have UI support for it.

Layout definitions can also reference an asset library, which can be used to define all the assets of a component.

Introducing the Multiple Definition Files module

So, what could be done to improve component-based theming with these superpowers we already have in core?

One of the general principles of component-based theming is that all files related to a particular component should be located in a component-specific folder. However, Drupal core currently only supports extension (theme) specific definition files for asset libraries and layouts. Wouldn’t it be nice to have component-specific definition files?

I decided to try an approach that uses existing definition file types, with no specific requirements as to where they should be located. The Multiple Definition Files module recursively scans the default theme’s directories for .libraries.yml and .layouts.yml files and then merges all found definitions to the theme’s main definition files. I haven’t found any problems with this approach so far, and I think it would be great to have this type of functionality in core some day.

Introducing the UI Patterns From Layouts module

What about the great features provided by UI Patterns? To use UI Patterns we still need to create .ui_patterns.yml definitions, or Pattern Lab and Fractal users can install an additional module that exposes their respective component definition files as patterns.

UI Patterns includes the UI Patterns Layouts module that exposes patterns as layouts. But what if it was done the other way round? Could layouts be exposed as patterns?

Thanks to another core layout definition superpower, support for arbitrary properties, we can add the preview values expected by UI Patterns to the layout definition file. And thus was born the UI Patterns From Layouts module!

Introducing the Drupal Definition Files plugin for Pattern Lab

Being a Pattern Lab user and contributor, I naturally turned my attention to Pattern Lab next. If Drupal core definition files could already be used for everything in Drupal, why not add support for them in Pattern Lab, removing the need to create Pattern Lab specific files?

So, I wrote a Pattern Lab plugin that adds support for .layouts.yml files and the arbitrary preview data section. The Drupal Definition Files plugin also supports defining the data for the base pattern and all of its pseudo-patterns in just one file. This is a nice feature for projects that have many pseudo-patterns.

Data Transform Plugin users need not worry, because all of its data transform features can be used in .layouts.yml files too!

Currently the plugin supports just layout definitions, but the plan is to add support for asset library definitions. Pull Requests are welcome!

Pick and mix

The modules and plugin introduced here can be used on their own or in any combination. The Pattern Lab plugin can be useful on its own just for the pseudo-pattern feature, even for non-Drupal projects.

The modules and plugin can probably also be used for other things not described in this blog post. If so, I would be interested to learn about such use cases.

Nov 17 2018
Nov 17

A quick overview of some things happening with Drupal’s Layout Initiative from the perspective of component-based theming, a theme development approach that has been gaining popularity in the past few years.

Layouts in core

The Layout API and the Layout Discovery module were added in Drupal 8.3 as an experimental subsystem, and they were stabilized in Drupal 8.4.

Layouts have been an important tool in component-based theming as they can be used to map data to component templates. Layouts can be used with well-established contrib modules like Display Suite and Panels, and the UI Patterns module can expose its patterns as layouts.

Field Layout

An experimental Field Layout module was also added in Drupal 8.3. Field Layout provides a simple UI for arranging rows of entity fields into regions of a single layout, in a very similar way to Display Suite. Field Layout was planned to be stabilized in Drupal 8.5, but it continues to be an experimental module.

Layout Builder

An experimental Layout Builder module was added in Drupal 8.5. Layout Builder provides a UI with a visual preview and it supports using multiple layouts together, placing blocks in layout regions and creating layouts for individual pieces of content. It is powerful and unique and a huge step forward in capabilities offered by core. Layout Builder is currently planned to be stabilized in Drupal 8.7.

Field Layout might be removed from core

Layout Builder has essentially deprecated much of what Field Layout provides, and uses a completely different technical approach. Layout Builder does not currently support form displays, however. As Field Layout is still experimental, it has been proposed that Field Layout should be removed from core after moving its form display capabilities to core’s Field UI.

An alternative non-visual UI has been proposed for Layout Builder

Drupal’s values and principles include building software that everyone can use. Core changes must pass through a series of ‘gates’ to ensure their quality is up to standards, and one of them is accessibility.

Modern UIs can be challenging to build in an accessible way, as the WordPress community has sadly discovered recently. Layout Builder is no exception, and it might prove difficult to pass Drupal’s accessibility gate in time to stabilize Layout Builder in Drupal 8.7. Because of this it has been proposed that Layout Builder provide an alternative accessible UI without a visual preview, not unlike Field Layout or the block admin UI.

Component-based theming use cases

Both aforementioned types of UIs are useful from a component-based theming perspective. However, a simple non-visual UI can be a better option in many cases. Layout definitions for components might include regions for adding things that are not displayed, for example.

Such a case can be found in my old blog post about using UI Patterns. The Code component described in that blog post defines a layout region for adding the code language. Instead of displaying the value, the component uses it as a part of a CSS class name.

Another example might be a component that defines a layout region for an image and a region for text, which the component then displays over the image. Such visually overlapping regions would be unnecessarily hard to implement perfectly in a UI with a visual preview, when a simple non-visual UI could just as well be used.

Now is a good time to get involved in the discussion

Personally I think it would be really great to have an alternative simple UI without a visual preview for layouts in core. If you would like to express your opinion on this, or can think of further use cases for such a UI, now is a good time to get involved in the related issues on Drupal.org:

On experimental modules

This case is a good reminder that experimental core modules should only be used for experimentation, not in production. An experimental module might be removed instead of being stabilized.

Thank you

Finally, I want to thank everyone involved in the Layout and Media Initiatives! Your work is very impressive and keeps making Drupal core better and more capable for component-based theming.

Apr 24 2018
Apr 24

Decoupled Drupal has been an increasingly visible topic at Drupal events and on the web for several years now. But what is the percentage of decoupled Drupal sites out of all Drupal sites?

Unfortunately there is no way to get hard numbers at the moment. It also looks as if there have been no user surveys about decoupled Drupal usage so far.

One way to estimate the number of decoupled sites is to look at the usage statistics of modules commonly used on decoupled sites. So I thought I would do that.

(All figures are from 15 April 2018.)

Number of Drupal sites:

  • Drupal 8: 226,908 sites
  • Drupal 7: 895,343 sites
  • Drupal 8 and 7 total: 1,122,251 sites.

To get a better overall picture let’s first look at the the most popular modules:

The difference between the most popular module on Drupal 8 and Drupal 7 is huge! This is probably because Drupal 8 core provides much more functionality out of the box.

Now let’s look at the modules used for decoupled Drupal. For Drupal 8 I have selected the REST UI module and for Drupal 7 the Services module:

  • Drupal 8: REST UI, installed on 8,404 sites (3.7 % of all Drupal 8 sites)
  • Drupal 7: Services, installed on 43,081 sites (4.8 % of all Drupal 7 sites)
  • Drupal 8 and 7: REST UI + Services, installed on 51,485 sites (4.6 % of all Drupal 8 and 7 sites).

Finally let’s look at graphs of usage over time, starting with Services:

We can see that usage grew steadily until early 2016, when it stabilised at the current level. Probably something to do with Drupal 8 being released at that time.

And then the graph for REST UI:

We can see a steady and steep rise in usage right from the time Drupal 8 was released.

These figures and graphs seem to confirm that decoupled Drupal is rapidly gaining popularity, although Drupal 8 usage still has not reached Drupal 7 level (see update below). It will be interesting to see for how long this rate of increase in usage will continue.

Update 26 April 2018: It has been suggested that the JSON API module should be included in the figures for Drupal 8, and this is indeed a good suggestion. JSON API is used in decoupled Drupal distributions like Contenta and Reservoir, and there should be very little overlap in REST UI and JSON API usage.

  • Drupal 8: JSON API, installed on 6,341 sites (2.8 % of all Drupal 8 sites)
  • Drupal 8: REST UI + JSON API, installed on 14,745 sites (6.5 % of all Drupal 8 sites)
  • Drupal 8 and 7: REST UI + JSON API + Services, installed on 57,826 sites (5.2 % of all Drupal 8 and 7 sites).

Usage graph for JSON API:

This looks very similar to REST UI, with a steady and steep rise in usage.

Feb 25 2018
Feb 25

Twice a year the new Drupal upgrade model makes me both excited about new features and worried about the possibility that the sites I maintain will break. I think there are some ways how the upgrade experience could be made better.

Things that could be improved

I have already written a couple of blog posts (1, 2) about the new upgrade model, detailing things that have caused and could continue to cause problems.

The main points made in those posts are:

  • Security support is only provided for the latest minor version, and there are two minor version releases each year.
  • It is a big challenge for contrib to keep up with changes, new features and new experimental modules in core.

As a consequence:

  • A minor version upgrade can cause sites using contrib projects to break.
  • Drupal 8 sites need more resources to maintain than previous major versions of Drupal.
  • It is not clear if it is always possible to maintain a working site that is covered by security support.
  • These issues make Drupal 8 less attractive for smaller site owners currently on a previous major version of Drupal.

Improvement idea 1: Extend security support to cover the previous minor version

Extending security support to cover the previous minor version would give contrib more time to fix possible issues. It would also make maintaining sites less resource intensive, increasing interest in adopting Drupal 8.

This would of course mean more work for core committers and the security team, so I don’t know whether the idea is realistic or not. But Dries ‘liked’ the idea when I mentioned it on Twitter, so that makes me hopeful!

I have opened an issue suggesting this on Drupal.org and would love to see discussion there.

Improvement idea 2: Provide a new way to find out how contrib projects are affected by a new core version

Currently there are two ways to find out if a new core version breaks your site. The best and only completely sure way is to test the new core version on the site. Another way is to browse through the issue queues of all contrib projects used on the site, looking for issues related to the new core version.

It would be nice to be able to get a list of all contrib projects that have been found to either work or break on a new core version. I believe this functionality could also be useful in the Automatic Updates initiative, to determine whether an update can be made or not.

A lightweight implementation of this feature would be to tag issues in a commonly agreed way. If for example a contrib module was found to be broken by changes made in Drupal 8.6.0, an issue could be opened and tagged ‘Breaks in 8.6.0’. That way all projects broken by changes in 8.6.0 could be easily found using the ‘Search issues for all projects’ page.

Being able to easily find out which contrib projects have been reported to break in the next minor release would possibly help getting issues fixed quicker. This data could also be used to gain insight on the ways contrib uses core that result in breakage. It would also provide interesting statistics on how common breakages are.

Feb 05 2018
Feb 05

After working almost exclusively with the latest and greatest version of Drupal since 2015, I am now facing some Drupal 7 projects. I did not want to give up using atomic design and Pattern Lab, so I decided to create a PHPTemplate (.tpl.php) PatternEngine for Pattern Lab.

Creating a PatternEngine

The Pattern Lab ecosystem can be a bit daunting. Although the actual technical implementation of a PHPTemplate PatternEngine was not that difficult, I had to create four different projects to accomplish a fully working Pattern Lab: a PatternEngine, a StyleguideKit, a StarterKit and an Edition that bundles everything together.

Default template rendering works in the same way in both Drupal 7 and 8: a child template is rendered first, and the result is passed as a variable to the parent template. The Data Transform Plugin, which is included in the new PHPTemplate Edition, was written to support this type of rendering in Pattern Lab.

Getting started with the PHPTemplate Edition

If you are still working with Drupal 7 and want to use atomic design and Pattern Lab, setting up a compatible Pattern Lab is as easy as typing:

composer create-project -s beta aleksip/edition-php-tpl

The PHPTemplate Edition is currently a beta release but I am already using it successfully in a Drupal 7 project.

Setting up a Pattern Lab project

Another new project of mine is a Pattern Lab starter project that can be used as a starting point for both Drupal 7 and Drupal 8 themes or modules with templates. I hope to document it better and maybe also write a blog post about it soon.

Update: What about using Twig in Drupal 7?

Since publishing this blog post I have received feedback regarding the possibility of using Twig for Drupal (TFD7) module and the Twig Edition of Pattern Lab with Drupal 7. I have not tried TFD7 myself, but apparently it works very well and can be used together with Pattern Lab.

I think that the TFD7 approach could be a very good or possibly better alternative when creating an entirely new theme. This is especially true if you also want to use or create a general-purpose Twig component library.

However, if you need to work with an existing PHPTemplate theme, or just want to avoid using a non-standard theme engine, using the PHPTemplate Edition of Pattern Lab should be a good option.

Jan 25 2018
Jan 25

When Pattern Lab renders a pattern, it does not by default include the data for any included patterns. There are plugins that can be used to include this data, but the many different ways to include patterns within another and to implement data inheritance can cause confusion.

The many faces of Pattern Lab

Before getting to the main topic, it should be noted that there are two versions of Pattern Lab (PHP and Node) and several editions of both versions. While trying to keep generic where possible, this article is mainly focused on the PHP version and Twig PatternEngine, which are bundled together in the Twig Edition of Pattern Lab PHP.

Including patterns in one another

In Pattern Lab a pattern can be included within another by using Pattern Lab’s shorthand include syntax or the templating language’s own include syntax. The shorthand include syntax is nice, but will not work outside Pattern Lab. This is why it is best to use the templating language’s own syntax if you want to keep Pattern Lab in sync with a production environment.

Twig’s include syntax supports namespaced paths. Namespaces are a great way to avoid both absolute and relative file system paths in native Twig includes. Pattern Lab automatically registers Twig namespaces for the top-level pattern folders, and the Twig Namespaces Plugin can be used to add more. The Component Libraries module can be used to add Twig namespace support and use the same namespaces in Drupal 8 themes.

Twig namespace support was added to Twig PatternEngine in May 2016. However, proper lineage support for namespaced includes was only added to the official versions of Pattern Lab PHP Core and Twig PatternEngine in October 2017. This made Data Inheritance Plugin work with Twig namespaces as well. Data Transform Plugin currently has support for namespaced includes in its development branch.

Types of data and default data inheritance

Pattern Lab supports global data files and pattern specific data files. Pseudo-pattern data files are a third type of data file, but in most situations they can be considered to be pattern specific data.

By default Pattern Lab merges pattern specific data with global data, with pattern specific data taking precedence.

How plugins currently implement additional data inheritance

Data Inheritance Plugin merges pattern specific data from included patterns (lineage data) with the current pattern’s pattern specific data. The current pattern's data takes precedence. This happens before the default merge with global data. The merged data is passed to the template engine when the current pattern is rendered.

Data Transform Plugin hooks into the Twig template engine. When the template engine performs an include operation, Data Transform Plugin fetches data for the included pattern from Pattern Lab’s data store. It merges pattern specific data with global data, with pattern specific data taking precedence.

In other words:

Data Inheritance Plugin

  • merges pattern specific data of all included patterns with the pattern specific data of the parent pattern
  • merges global data only once, with the previously merged pattern specific data
  • passes data to the parent pattern only

Data Transform Plugin

  • merges global data with pattern specific data individually for every pattern
  • passes data individually for every pattern

Practical implications of the different approaches

In many cases there might be no differences in the results, especially if the parent pattern’s data also contains data for all the included patterns or if the variable names used in the patterns are all different.

But there are some cases where the end results will differ depending on which plugin is used. These cases often involve missing pattern specific data for variable names used in more than one pattern.

Examples

I will use the following data files to demonstrate these differences:

Global data file (data.json):

parent pattern data file (parent.json):

child pattern data file (child.json):

The parent and child patterns both have variables called title and content. The parent pattern includes the child pattern.

Merged data can flow up from included patterns

Using Data Inheritance Plugin, the title for the parent pattern will be ‘Child title’ and using Data Transform Plugin it will be ‘Global title’.

Global data merged with pattern specific data of included pattern takes precedence over parent pattern’s data

Using Data Inheritance Plugin the content for the child pattern will be ‘Parent content’. Using Data Transform Plugin it will be ‘Global content’

Is one approach better than the other?

The different approaches can be used to fulfil different kinds of requirements, and the choice might depend on how the patterns have been implemented.

Data Transform Plugin, including its data inheritance functionality, was written specifically with Drupal theme development in mind, and is compatible with the default Drupal template rendering style of not actually using Twig includes.

I would be very interested in learning about cases where one approach is definitely better than the other.

Oct 09 2017
Oct 09

The recent announcement that Drupal is looking to adopt React has inspired me to live up to my Twitter bio, and be an active advocate for open standards-based technologies. While my knee-jerk reaction to the announcement was to focus on React, this blog post addresses the topic of adopting technologies in a more general manner, still aiming to contribute to the current front-end framework discussion.

Company-led open source projects rarely prioritise standards

I’ve always thought that it is important for the core technologies of the web to be standards-based and to have good open source implementations that are accepted by everyone. A problem with standards is that it can take a long time for them to be completed and widely adopted. This is especially true when it comes to front-end web technologies, which have evolved so rapidly that standards have been struggling to keep up.

With most companies now embracing open source, company-led open source projects have become increasingly common. However, companies don’t usually prioritise standards over their own business interests, which is perfectly understandable of course. Many company-led projects are developed primarily for the companies’ own needs, and they want to steer these projects in the direction that best benefits them.

Companies may cease to exist or change their interests

If a company maintaining a project ceases to exist, or suddenly decides that its interests lie elsewhere, the project might be abandoned altogether. This is especially likely if the project hasn’t been a part of the company’s core business model. In a situation like this an open source project can of course usually be picked up or forked by someone else, but finding new people to maintain it can be very difficult.

Software patents and open source projects

It is common for large companies to acquire software patents, to be used in legal battles with competitors. Technologies invented in open source projects led by large companies have a higher probability of being patented. If the license doesn’t have an explicit patent grant, possible patents are a risk for all users of the project.

Large companies usually acquire patents for defensive patent portfolios, and this is why they aren’t considered by many to be a serious risk. But open source software and patents do not go well together. Neither do standards and patents. For a project to become a true part of web infrastructure, it needs to be accepted by all, including strict FLOSS projects and competitors of the company maintaining the project.

Drupal as infrastructure

I like to think of Drupal being a part of the infrastructure of the web, acceptable to all. This is possible because Drupal is open source, standards-based, community-led and it depends on other projects that adhere to these values. I believe these characteristics have had an important role in Drupal becoming so popular, in addition to Drupal being great technology, of course.

Whenever Drupal needs to choose a new technology to be included in its core, great importance should be placed on the acceptability of Drupal to everyone. By choosing a technology based on other merits alone, we could lose this general acceptability.

Staying relevant in the long run

Decisions on adopting new technologies should not be based on fear of losing relevance. We should not just choose the most popular technology to quickly capture the interest of lots of developers.

Drupal has been around for 17 years. We should think in the long term, instead of looking only at the current situation. New technologies come and go, especially in the world of front-end JavaScript. There is no way to know what is going to be the most popular technology in a couple of years.

Even though standards are not moving as rapidly as some frameworks, standards are something everyone can depend on. For this reason, supporting and choosing established and emergent standards, in addition to being one of Drupal’s principles, are in my opinion the best way to ensure that Drupal stays relevant in the long run.

Do we really want to be advancing a future where the only options are to choose from non-standard technologies controlled by a handful of big companies like Facebook, Google and Apple?

Following others is not the only option, we can lead too

I also like to think that Drupal is an important project for the web, and that our decisions have an impact even outside the Drupal ecosystem. A technology used in Drupal core will create interest in adopting it on Drupal sites, and will make the technology more interesting for non-Drupal projects as well. As long as Drupal offers excellent support for other similar technologies, they can be used too, so Drupal won’t lose developers skilled in them either.

Oct 04 2017
Oct 04

Drupal needs to adopt a JavaScript framework for its administrative interfaces. The selection of this framework is an important decision, which should not be based on just technical merits or popularity. Drupal has been an open source project and a community for over 17 years, and when we make decisions like this, our values should weigh more than what is the hottest JavaScript framework at the moment.

Dries has written and spoken several times about how we should not let a handful of companies like Facebook, Google and Apple control how we experience the web. One aspect of this control is the technologies and standards these companies support or do not support. These companies also acquire software patents, which they can enforce when it best suits their business interests.

Dries and select core maintainers, JavaScript subsystem maintainers, and framework managers are now advocating Facebook’s React to be the adopted JavaScript framework for Drupal.

React was initially licensed under a permissive and GPL3-compatible Apache 2.0 license, which specifically covers possible patents. However, since then Facebook has relicensed React under two different versions of the infamous BSD + Patents license, and, most recently, the MIT license.

The MIT license is widely used, and is arguably better than the BSD + Patents license. However, the MIT license does not mention patents, and according to the Free Software Foundation “leaves room for patent treachery”. Why did Facebook not return to using the Apache 2.0 license if they really want to “ensure that developers can use [their] projects with confidence”?

Even if we trusted Facebook to not have patents on React technology, or at least to not enforce them against React users, patents are not the only issue to consider. Facebook maintains and controls React, deciding its direction. And currently this direction does not seem to be very standards-based. React is developed by Facebook for Facebook. Many decisions are made behind closed doors, and we don’t know the motives behind all of them.

So should Drupal, an open, community-based, GPL-licensed open source project, trust a company like Facebook? Do we want to use technology possibly patented by Facebook, with uncertain license coverage? Do we want Drupal to become a part of an open source ecosystem steered by Facebook? A decision to adopt Facebook technology will affect every Drupal site owner.

Even though we are currently only talking about administrative interfaces, a framework used in core will no doubt influence framework choices for user-facing front ends. People will choose and learn this framework because Drupal core uses it. We should also remember that the Drupal ecosystem is big and important enough for our choices to make a difference even outside of Drupal.

We should cherish our values of openness and being standards-based, and if we value our community, we should prefer community-led projects over company-led projects. These are the things that I’ve understood to be the true ‘core’ of Drupal, things that come before technological trends and details.

Oct 03 2017
Oct 03

Dries Buytaert, the BDFL of Drupal, has just published a blog post in which he states that “React is the right direction to move for Drupal's administrative interfaces”. A related issue has also been opened on drupal.org.

With all the fuss about patents, why did Facebook choose the MIT license?

React’s previous BSD + Patents license received considerable criticism, including notable rejections by the Apache Software Foundation and WordPress. This criticism eventually forced Facebook to relicense React.

However, Facebook chose to relicense React under the MIT license, which does not mention patents at all. I find this interesting, because Facebook has told us that the additional patent grant in the BSD + Patents license was “designed to ensure that developers can use our projects with confidence”.

React was initially released under the Apache 2.0 license, which explicitly covers patents. So why didn’t Facebook now relicense React under Apache 2.0?

It all boils down to trust

As far as I know, the MIT license has not been tested in court regarding patents, and there are differing legal opinions on whether the license covers patents or not.

The Free Software Foundation states on the MIT license that “for substantial programs it is better to use the Apache 2.0 license since it blocks patent treachery”.

The MIT license is a popular license, also used by projects like Angular 2, Ember and Vue. Avoiding all projects that use the MIT license would be a very limiting decision.

So it all boils down to trust. Should we trust Facebook? I don’t, and I don’t think the Drupal community should either.

Sep 15 2017
Sep 15

As I experienced some issues upgrading to Drupal 8.3, I thought I should be more prepared this time, and tried out the Release Candidate version of Drupal 8.4.

The previous minor version of Drupal is unsupported

The new upgrade model in Drupal 8 includes the policy that the previous minor version is unsupported. So if you want to have security support for your production site running Drupal 8, you must upgrade immediately, or at least be prepared to upgrade immediately if a patch release with a security fix comes out.

We already know that changes between minor versions of Drupal 8 can have major consequences for contrib modules. To be able to upgrade and keep security support, site maintainers need to test Drupal Release Candidates, and all possible issues with contrib modules need to be resolved before the new minor version of Drupal comes out.

Drupal 8.4 may introduce backwards compatibility issues

One of the changes in Drupal 8.4 is the inclusion of the Media module in core. Thankfully it looks like migrating from Media Entity to the core Media module will be a much better experience than it was with Layout Plugin and Layout Discovery. It is great that so much effort is put into this, undoubtedly partly because the Thunder and Lightning distributions depend so heavily on Media Entity. Thank you to everyone involved in bringing Media in core!

Drupal 8.4 also includes major version updates for two dependencies: Symfony 3.2 and jQuery 3. Both of these updates do sound like they could break many contrib modules. In my very limited testing on a couple of sites I maintain I found one module broken by the Symfony update, and one module broken by Drupal 8.4 for some reason. It is possible that both of these contrib modules will have a working release before Drupal 8.4 is released, but it will still be interesting to find out how many contrib modules altogether are affected.

Security support for the previous minor version would help a lot

I’d be surprised if I was the only one who feels a bit uneasy about the official policy of no security support for the previous minor version of Drupal. This policy most likely leads to increased testing of Release Candidates, which is a good thing. But I’m not sure if the time window between the first RC and the release is long enough for every problem to be discovered and fixed. This puts a lot of pressure on contrib.

A commitment to provide security support for the previous minor version of Drupal 8 would give more time to get everything fixed in contrib, and give more peace of mind for people responsible for maintaining secure production sites.

Update: I have now opened a core issue about this.

Apr 25 2017
Apr 25

Drupal 8 has a new upgrade model, and the promise is to make upgrades easy forever. The idea behind the upgrade model is great, and has already been proven in other projects like Symfony. However, there might still be some issues that need to be solved, as demonstrated by the recent 8.3 release and the security release that followed it.

The concept of experimental modules is a key part of the new upgrade model. Experimental modules are provided with Drupal core for testing purposes, but are not yet fully supported. As Dries pointed out in his DrupalCon Baltimore Driesnote, experimental modules should not be used in production.

Drupal security releases are provided only for the latest minor release, and older minor releases are considered end-of-life. This is a really strong incentive to upgrade to the latest minor version as soon as possible, as you really want to have security coverage for your production site.

Drupal 8.3.0 was released on 6 April 2017. Drupal 8.3.1 and 8.2.8, containing a critical security fix, had to be released less than two weeks later, on 19 April 2017. The reason for publishing a security release for an end-of-life minor release was that there is a minimum ”grace period” of 1 month between the release of a new minor version and public disclosure of security issues that affect the old minor version. This grace period allows for contrib modules to be updated for the new minor version in case of possible disruptive changes in internal APIs and experimental modules.

Drupal 8.3 added Layout Discovery, a new experimental module that is intended to replace Layout Plugin (9th most popular Drupal 8 contrib module), which is required by Display Suite (22nd) and Panels (31st).

The Display Suite, Panels, Page Manager and Panelizer projects all released new branches compatible with Drupal 8.3 and the experimental Layout Discovery module. The old branches of these modules and the Layout Plugin module itself are NOT compatible with Drupal 8.3. The issue queues of these modules are now full of issues describing upgrade problems resulting in completely broken sites.

So one lesson learned here is that minor upgrades are not always painless to do, at least immediately after a new minor version has been released. In this example case production sites can stick to 8.2.8 and hope all the problems with Layout Discovery and the contrib modules that require it are sorted out soon enough. But 8.2 is officially end-of-life: what happens if a new critical bug is discovered in the meantime?

Even when all the issues related to upgrading to 8.3 and using Layout Discovery are resolved, Layout Discovery is still an experimental module, not recommended for production use. (Admittedly Layout Plugin too is an alpha release, so it or modules requiring it should not be used on a production site. But this is just an example case.)

What should one do to have both a stable and a secure site?

One solution is for contrib modules to offer two versions: one that has experimental modules as dependencies and another that does not. But that is a lot to ask, as even the main branches of so many Drupal 8 modules are still in alpha or beta. Also, in this example case Page Manager depends on Panels which in turn depends on Layout Discovery. With many layers of dependencies even with just one main branch in each module it can sometimes take a lot of time and work just to find out where the root cause of a problem is.

I don’t have a better solution in mind, as I’m not even sure if what I have described here really is a serious problem. If it indeed is a genuine problem I hope it will be resolved sooner rather than later.

Jan 29 2017
Jan 29

A great new Drupal 8 module, UI Patterns by Nuvole, has just been released. UI Patterns can expose stand-alone theme components (patterns) to Drupal and enables them to be used with the core Views module and well-known contrib modules like Field Group, Display Suite and Panels.

Background: the problem with presenter templates

Currently a popular solution for integrating stand-alone components with Drupal is to use ‘presenter’ templates. While being a great solution, presenter templates do have some drawbacks.

One of the key strengths of Drupal is that it is possible to affect the appearance of the site from the administration UI without the need for any coding or theming skills. However, stand-alone components aren’t tied to Drupal’s data model. Presenter templates transform Drupal’s data for the stand-alone components’ templates, and this only happens in one direction. Drupal has no knowledge of stand-alone components’ data models or direct control over the data sent to them. This often results in the administration UI having little or no control at all over the site’s appearance.

Another issue is having to create the intermediary presenter templates in the first place. In addition to the effort required in creating and maintaining these templates, processing Drupal data structures in Twig can become quite tricky, even if using some of the many Drupal specific Twig helper extensions now available.

UI Patterns to the rescue

UI Patterns can be used to remove the need for presenter templates in many cases. By exposing stand-alone components and their data model to Drupal, the administration UI can be used to directly control the data provided to the components’ templates. Since UI Patterns adheres to standard Drupal concepts, it plays really well together with not only core Drupal itself but also with many popular contrib modules used for administration UI based site building.

UI Patterns is not a silver bullet that can remove the need for presenter templates in every possible use case. Presenter templates (or preprocess functions) are still required for conditional logic and advanced data processing. But even with this caveat UI Patterns is a really useful module.

Example: creating a simple UI Patterns enabled Code component

As an example of how to use UI Patterns I’ll describe how to create a simple component that displays syntax highlighted code using the Prism JavaScript library. It is the same component that is used to display code in this blog post.

The Drupal modules used in this example are Component Libraries, Display Suite, Paragraphs, UI Patterns and UI Patterns Layouts (which comes with the main UI Patterns module).

Step 1: Create the component

We’ll start by downloading Prism .js and .css files and defining an asset library in the theme’s .libraries.yml file:

shila-code:
version: 1.x
css:
theme:
dist/_patterns/01-molecules/text/shila-code/prism.css: {}
js:
dist/_patterns/01-molecules/text/shila-code/prism.js: {}

Next we’ll create the simple Twig template, shila-code.html.twig:

<pre><code{% if language %} class="language-{{ language }}"{% endif %}>{{ content }}</code></pre>

A .ui_patterns.yml file is used to define the components provided by a theme or a module and expose them to Drupal. UI Patterns will use all .ui_patterns.yml files it finds in a theme’s or module’s directory structure, so it is possible to create component-specific files! We will now create one for our code component:

shila_code:
label: Code
description: A block of code with syntax highlighting using Prism.
fields:
language:
type: string
label: Language
description: The code language as supported by Prism.
preview: php
content:
type: string
label: Content
description: Content of the code block.
preview: 'print phpinfo();'
libraries:
- shila_theme/shila-code
use: '@molecules/text/shila-code/shila-code.html.twig'

In the fields section we define language and content fields for the two variables in our Twig template.

In the libraries section we let UI Patterns know about our asset library, so that the library will be attached whenever our Code component is displayed. At the moment all asset libraries have to be defined in the theme’s or module’s .libraries.yml file, but a future version of UI Patterns should support defining asset libraries directly in .ui_patterns.yml!

The use template property instructs UI Patterns to use our template file. The property supports Twig namespaces defined using the Component Libraries module, and we are using this great feature here.

Now our component folder looks like this:

The two extra files in the picture are not needed for our example. _shila-code.scss contains some additional styling and shila-code.html.json is a data file for Pattern Lab.

At this point we should clear Drupal’s caches to make sure our new files are discovered. We can then visit the pattern library page created by UI Patterns at /patterns to see a preview version our component.

Step 2: Create a Paragraphs type to match the component

Now we can move over to Drupal’s administration UI and create a Paragraphs type to match our component. We add two text fields to match the fields defined in .ui_patterns.yml:

Next, from the ‘Select layout’ drop-down menu on the ‘Manage display’ page we select our ‘Code’ layout created by the UI Patterns Layouts module:

After clicking on ‘Save’ to apply the new layout, we can select the ‘Only content’ option from ‘Pattern settings’:

The useful ‘Only content’ option currently affects all fields, but it will be a field specific option in a future version of UI Patterns.

Next we drag the fields to their matching layout regions:

An important thing to note here is that even though the page is called ‘Manage display’ we are just mapping the Paragraph type’s fields to the fields of the component. What is actually displayed is entirely up to the component. In this case our example Code component uses the value of the ‘Code language’ field as a part of a CSS class name.

However, this is different from using presenter templates in many ways. The actual fields defined by the stand-alone component itself are presented in the admin UI. The data provided here goes directly to the component template. The component can provide information on how to use these fields, easily accessible to the site builder on the pattern library page. And the fact that an intermediary template is not needed at all is not insignificant either!

Step 3: Use the new Code Paragraphs type in your content

The Code Paragraphs type can now be used in our site’s content, in the same way it is used in this blog post. You can view the live pattern preview page here.

The role of UI Patterns

This blog post has only scratched the surface of all that is possible using UI Patterns. It is an incredibly powerful and versatile module that I am definitely going to use in all my current and future projects. Although UI Patterns is not even at version 1.0 yet, the module and the concepts behind it seem solid and fully baked. The adherence to standard Drupal concepts, seamless integration with core Drupal and existing contrib modules, the extremely professional development process and good documentation have more than convinced me.

My recommendation to all Drupal site builders and themers is to check this module out. For more information be sure to read the introductory blog post.

Update: Please note that the example in this blog post is of a very simple use case, and of only one way to use UI Patterns. Be sure to check out the UI Patterns documentation for a more full picture of everything that can be done. You can also have a look at Shila theme for more UI Patterns component examples.

Jan 24 2017
Jan 24

Shila theme has been developed for over a year now. I have learned many lessons from it being used on several production websites, and the theme has changed a lot. Here is a recap of the most important changes and the reasons behind them.

Background

Shila theme has always been meant to be used as a starting point for creating a new theme. It is not meant to be used as it is, although this site does use it with only minimal changes.

Pattern Lab integration has been a feature from the beginning, even before the official Pattern Lab project supported Drupal. Originally the integration started as a proof of concept, using unmodified Drupal Stable theme templates.

How to provide a StarterKit

At first Shila theme could be used to create a separate Pattern Lab StarterKit, which would then be used in Pattern Lab. All development was done in the theme project, and the theme’s Gulp script automatically copied relevant files over to the StarterKit project.

It soon became apparent that the parts that were copied over really made up the bulk of the theme, and that it would be great to be able to develop the theme using Pattern Lab alone, no Drupal required.

So the development setup was moved to the StarterKit, and the automated copying was then done the other way round. This copying was done to keep both projects independently usable ‘out of the box’, although development could now only be done in the StarterKit project. This meant that the development of the theme became dependent on the StarterKit.

It took few more months to realize the obvious: a separate StarterKit project (and copying of files) wasn’t really needed, as the theme project itself could also be used as a StarterKit. The only current requirement set by Pattern Lab is that all StarterKit files must be in a folder called dist. Thankfully this is not a problem for Drupal.

So everything was once again moved back to the theme project and the StarterKit project was abandoned. Some things just have to be learned the hard way, I guess.

Because of the way Pattern Lab currently works, the standard StarterKit installation method can’t really be used to install a development setup that would be independent of Pattern Lab itself. I’d really love to see this being possible some day, but meanwhile the approach used with Shila theme and other themes is to have Pattern Lab inside the theme project.

Hello components

By the time of DrupalCon New Orleans 2016 it seemed that practically everyone in the Drupal front end community was excited about component based theming. John Albin released the Component Libraries module, and the ‘presenter’ pattern became the de facto solution for gluing Drupal themes and stand-alone components together. Component based theming just seemed to make sense, and the time was right to try it out.

A major refactoring was done to make Shila theme component based. Basically all templates were split into two, still trying to keep very close to Drupal’s Stable/Classy theme templates. Variable manipulation was left in presenter templates picked up by Drupal, and the markup itself was moved into component templates.

Goodbye _twig-components

The component templates in Shila theme do not use any Drupal-specific Twig extensions. Drupal-specific Twig is still used in presenter templates, but these are not needed in Pattern Lab. This means that the _twig-components folder providing Drupal compatibility for Pattern Lab is no longer needed. Which is nice!

The Attribute object

One of the most useful and perhaps the most widely used of all Drupal-specific Twig features is the Attribute object. This great utility object contains no Drupal dependencies and could thus be made into a stand-alone Drupal Component.

A stand-alone Attribute component could be used by any Twig project and in stand-alone Twig component libraries. Personally I think that Attribute is so useful that it could even be made a part of Twig itself.

It would be a shame not to be able to take advantage of Attribute in stand-alone components. Fortunately Attribute variables are printed out just like strings, which provides a handy loophole: Attributes can be used as full object variables in presenter templates and as plain string variables in component templates. Admittedly this kind of use of string variables would be quite odd if not for the Attribute object connection, but it is better than nothing.

(Almost) no more PHP

I have started to subscribe to the school of thought that a themer should not have to write any PHP. Having to make significant changes to the standard Drupal templates was a good opportunity to (almost) get rid of Shila theme’s .theme file, which used to contain PHP preprocess functions that added CSS classes to different elements. Almost all of that is now done in Twig in the theme’s presenter templates. However, Twig is a templating language, not a programming language, so some things just can’t be done in Twig (at least with my Twig skills).

shila-css

With so many significant changes to Shila theme, keeping up with them in derivative themes has been quite painful, to say the least. I know, since I have been eating my own dog food!

As Shila theme is only meant to be a starting point, keeping up with changes is of course not necessary at all. But it is nice to have the option. Heavily inspired by inuitcss, the core Sass files from Shila theme were moved to a npm package unsuprisingly called shila-css. The main idea behind this is that derivative themes should not modify the core Sass files, but only configure them using Sass variables and/or extend them using new Sass partials. This should make keeping up with upstream changes much easier.

Namespaced components

The latest major change to Shila theme is the renaming of all component files and folders, adding a shila- namespace prefix to them. As theme components become more common, this allows mixing components from different projects with fewer potential naming conflicts. It also helps to avoid naming conflicts with Drupal’s own template files. A third benefit is that this should also make keeping up with upstream changes easier, as derivative themes should add their own namespace to modified or new components.

The future

There is nothing permanent except change. An exciting new development is the release of the UI Patterns module. But this blog post is already long as it is, and UI Patterns really deserves a blog post of its own.

May 13 2016
May 13

Starting right from the Driesnote, it seemed like the topic of theme components was coming up everywhere at DrupalCon New Orleans 2016. Out of all the activity in this area I have been especially interested in two things: presenters and component folders. I think that they are two key pieces required for the next step, which is component projects.

Presenters

For theme components to be truly stand-alone, they should be independent of Drupal. This means that they should not use Drupal's Twig extensions. It means that the components are not restricted by Drupal's data model. The components should even be independent of the theme they are used in.

So how can components like this be used in a Drupal theme? Several people have come up with practically identical solutions. These were identified by Micah Goldbolt in his DrupalCon session as being presenters from the decades old Model-View-Presenter pattern.

In a nutshell, presenters are standard Drupal theme templates that 1) transform data received from Drupal and 2) use Twig include and embed tags to include one or more components and pass the transformed data. Presenters should be totally free of markup, and this can be achieved by using the Twig extends tag.

Component folders

When implementing theme components, placing all resources related to a particular component in the same component-specific folder seems like a natural thing to do. This is being proposed and done by several well-known members of the Drupal community.

These resources usually include at least the markup (Twig templates) and CSS, but also things like Sass files, images, JavaScript, metadata and documentation.

Getting off the island

So now we have a way to organize stand-alone components and a way for Drupal themes to use them. However, if we have stand-alone components we really should not be thinking about Drupal themes only.

Assuming that they contain Twig templates, components can be used by basically anything that supports Twig. This includes Pattern Lab, Symfony applications and client-side rendering using Twig.js, to mention only a few.

So let's get off Drupal island. From now on, I will use 'host project' instead of 'Drupal theme' whenever applicable. You can always still read 'host project' as 'Drupal theme' if you wish. But you can read it as 'Pattern Lab instance' too, for example.

Component projects

As stand-alone components can be used by different host projects, it should be possible to develop and package components as separate, fully independent projects of their own.

I think that it is a given that component projects should be standardized in such a way that they can be used 'as is' in different types of host projects.

Some other possible requirements for component projects:

  • a component project can contain any number of components

  • a host project can use several component projects

  • a host project can use component projects that are located either inside or outside of the host project

  • component projects can contain their VCS repository metadata while they are used in a host project (to allow for parallel development)

  • component projects can provide machine readable information about dependencies.

Requirements for a standard

Looking at the list above, most of the requirements are really requirements for the host projects. Only the first and last items are direct requirements for component projects.

So what would the requirements for a component project standard be? I suggest the following:

Using an existing and proven standard would of course be the best course of action. Maybe I just suck at googling, but I haven't been able to find such a standard. I will probably find one or someone will let me know about one right after this post is published...

Moving forward

We'd need to define the requirements for component projects and host projects. We'd need to agree on a suitable standard for component projects. If such a standard does not exist we'd have to define one.

I don't think it would need to be a very complicated process. We already have taken many steps in this direction.

I think that, at its core, defining component projects really should be a non-Drupal, non-PHP and non-Twig specific project. And that if one does not already exist, we should create one!

Meanwhile, active discussion related to this topic is already going on in both Drupal and Pattern Lab communities.

May 09 2016
May 09

A lot has happened since my first Pattern Lab post in January. The eve of DrupalCon New Orleans 2016 seemed to me like a good time for a summary.

Drupal Edition of Pattern Lab, Drupal StarterKits

No more dubious forks! Most of my pull requests were merged into the official repository by Dave Olsen, the lead developer of Pattern Lab.

Evan Lovely, Christopher Bloom and Anne Sturdivant from Phase2 got in touch, and Dave gave us the honour of being the first members of a new Pattern Lab Drupal team.

New official Pattern Lab projects were created: the Drupal Edition of Pattern Lab, a Minimal Drupal StarterKit and a Demo Drupal StarterKit.

If you have Composer installed all you need to do to try out the Drupal edition is run

composer create-project pattern-lab/edition-drupal-standard

Pattern Lab chat rooms opened

To help coordinate all this activity, chat rooms were opened on Gitter. There is a general chat room and separate chat rooms for the PHP and Node versions of Pattern Lab. Drupal stuff is mostly discussed in the PHP room. Everyone is welcome to follow and join in the discussion!

Support for Twig namespaces

Twig PatternEngine now supports Twig namespaces for the top-level pattern folders. Includes like @atoms/pattern/path.twig are now possible, and they will work on Drupal too when using the Component Libraries module, for example.

Plugin access to Twig_Environment

This is a big one! Twig PatternEngine now fires events when Twig loaders are initialized and plugins have access to the respective Twig_Environment. This makes it possible for plugins to register Twig extensions.

New version of Data Transform Plugin

As a consequence of Twig_Environment being accessible to plugins, PatternDataVisitor was moved to Data Transform Plugin. Specific handling of Drupal's Attribute class could then be added for a new release of Data Transform Plugin. Workarounds for including templates that manipulate Attribute objects are no longer needed!

The question of Drupal's Twig extensions

It soon came apparent that duplicating the decoupled 'dummy versions' of Drupal's Twig extensions in different StarterKits was not practical or desirable. A Drupal Twig Components Plugin was created to avoid duplication and make updates simpler.

However, the extensions contained in the plugin are still written in the Pattern Lab specific auto-load style. Now that it is possible, creating a standard Twig_ExtensionInterface based extension seems to be the logical next step.

In April a major component-based rendering issue was opened on drupal.org by Wim Leers. Based on the enthusiastic response it is likely that the future of Drupal will include decoupled Twig.js compatible components. A strategy for Drupal's Twig functions, and particularly Attribute, is needed.

To me this looks like an opportunity to create an official stand-alone version of Drupal's Twig extensions. I opened an issue about it and am looking forward to helping make something like that happen.

DrupalCon New Orleans

The buzz around atomic/modular/pattern/component based design seems to keep on growing. The schedule for DrupalCon New Orleans includes at least three sessions and one BoF on Pattern Lab or related topics:

Mar 28 2016
Mar 28

After experimenting with Pattern Lab and Drupal 8 theme development for a while I am starting to see a whole new role for Pattern Lab StarterKits.

StarterKits can contain the source files and master copies of all resources that need to be shared between Pattern Lab and a Drupal theme. With these removed from a Drupal theme all that is left, basically, are the PHP code parts.

StarterKits can be used to separate concerns in a well defined way and to provide a project that can be shared by people and teams with different skill sets and roles.

StarterKits for Drupal themes can be used and developed in Pattern Lab with no Drupal installation required. Even in cases where the same people are responsible for both the PHP and Twig/CSS parts of a Drupal theme, this separation helps to improve the design and implementation of both parts.

Shila theme and Shila theme StarterKit have now been refactored accordingly, which means that the StarterKit is now required for developing Shila theme.

Jan 29 2016
Jan 29

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.

Jan 29 2016
Jan 29

When presented with something that almost instantly seems obvious, you don't need much more convincing. For me atomic design was like that. After making the choice to use atomic design and Pattern Lab in a real world Drupal 8 project and seeing the methodology validated, I have wanted to design and build all websites in this way.

The Holy Grail

Atomic design is both platform and tool agnostic and Pattern Lab is a static site generator. The philosophy of Pattern Lab is to reduce dependencies and keep things simple. So how does Drupal theme development fit in? How can we integrate atomic design and Pattern Lab with Drupal theme development? Can we achieve the Holy Grail of keeping the pattern library in sync with our Drupal theme?

Come together

As a first step we can place Pattern Lab in the Drupal theme folder. This is not necessary but does help in creating a strong mental association between the Drupal theme and Pattern Lab.

An added bonus in having a Pattern Lab instance in the theme folder is that we have a way to access Pattern Lab through the Drupal installation. The URL might not be pretty, but knowing that your theme's pattern library is always there with your theme brings a nice, warm feeling. And it is always possible to have a separate web server configuration for Pattern Lab.

Of course there might be cases where we don't want this, especially on production sites, so having Pattern Lab in the Drupal theme folder should always be optional.

Templates and templates

A Drupal theme has templates. Pattern Lab has templates. CSS is used to style the HTML produced from these templates. CSS is the obvious low hanging fruit that can be fairly easily shared between a Drupal theme and Pattern Lab. We only have to make sure that the naming and structure of the CSS classes (and the structure of the HTML, at least to some extent) stays the same.

It is of course possible to keep a Drupal theme's templates and Pattern Lab's Mustache templates in sync one way or another. But maintaining two sets of templates is not ideal.

Enter Drupal 8 with Twig theme templates and the Twig edition of Pattern Lab. Could there be a way to use the same templates with this combination? Well, unsurprisingly it turns out that there are some issues that need to be solved before Drupal theme templates are usable in Pattern Lab. I have covered these issues, and solutions for them, in a separate post.

But the good news is that after solving the aforementioned issues it is indeed possible to use the exact same templates for both Drupal and Pattern Lab. Then the only thing needed to achieve the Holy Grail is to come up with some conventions and best practices.

It's all about the structure

Drupal allows the organizing of a theme's templates in any kind of folder structure. This means that the templates can be placed in the standard folder structure expected by Pattern Lab. Drupal theme templates that are not used in Pattern Lab can be kept in a separate structure.

Drupal will even find the templates from inside a Pattern Lab folder placed in a Drupal theme folder. However, it is good to keep the theme and Pattern Lab decoupled. Automation and a tool such as Gulp can be used to watch for changes and to keep two sets of templates in sync. This can also be done with CSS files and other assets.

A CSS preprocessor such as Sass allows the compiling of the final theme CSS files from any kind of file and folder structure. Drupal CSS coding standards and atomic design are quite compatible and it is possible to organize CSS partials in a nested structure based on both.

What's in a name

Drupal theme templates not used by Pattern Lab can be kept out of the shared template structure, but Pattern Lab will require some templates not used by Drupal. Having Pattern Lab specific templates in a Drupal theme can be a bit confusing, but a naming convention can help. Such a convention already exists in the form of prefixing Pattern Lab templates with numbers. Number prefixes make it easy to see which templates are for Pattern Lab only.

Introducing Shila theme

This post has only covered the basics of one way to integrate Pattern Lab with Drupal 8 theme development. The best way to present this still experimental approach is to provide a working example.

Shila theme is an atomic design and Pattern Lab friendly starting point for new Drupal 8 themes. A Pattern Lab generated Shila theme style guide is also available on GitHub.

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web