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.