Expose atomic UI patterns as plugins and use them as drop-in templates in your Drupal 8 projects

Establishing an atomic design system in your project is one of the most effective way to build a consistent and maintainable user interface.

Over the past years projects like PatternLab or the Component Libraries module aimed at lowering the cost of maintaining (PatternLab) and re-using (Component Libraries) UI patterns in your projects, be it a generic PHP application or a brand new Drupal 8 site.

But, as we all know, when it comes to presenting content the Drupal 8 landscape is quite diverse: you can layout your pages using Panels or Views, style your entities using Display Suite view modes, group your fields with Field group, etc.

Such a diversification can surely present some challenges when it comes at reusing a well-designed and consistent UI library. In other words: how can I transparently use the same UI pattern in my views, layouts, field formatters, etc.?

Enter the UI Patterns module

The UI Patterns module allows you to define and expose self-contained UI patterns as Drupal 8 plugins and use them seamlessly as drop-in templates for panels, field groups, views, Display Suite view modes and field templates.

The module also generates a pattern library page that can be used as documentation for content editors or as a showcase for business and clients (the following example is styled using the Bootstrap theme):

The UI Patterns module also easily integrates with with tools like PatternLab or modules like Component Libraries.

Define your patterns

Patterns can be defined using YAML in files named MY_MODULE.ui_patterns.yml or MY_THEME.ui_patterns.yml using the following format:

blockquote:<br>&nbsp; label: Blockquote<br>&nbsp; description: Display a quote with attribution information.<br>&nbsp; fields:<br>&nbsp;&nbsp;&nbsp; quote:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; type: text<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; label: Quote<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; description: Quote text.<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; preview: Life is like riding a bicycle. To keep your balance, you must keep moving.<br>&nbsp;&nbsp;&nbsp; attribution:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; type: text<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; label: Attribution<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; description: Quote attribution.<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; preview: Albert Einstein

After defining the pattern you have to provide a Twig template to render it which, in our case, could look like that:

&lt;blockquote&gt;<br>&nbsp; &lt;p&gt;{{ quote }}&lt;/p&gt;<br>&nbsp; &lt;footer&gt;{{ attribution }}&lt;/footer&gt;<br>&lt;/blockquote&gt;

Once you are done you can visit the pattern library page and check your new Blockquote pattern in action:

We have much more options available to make sure pattern definition can fit your use case (i.e. template overrides, etc.), make sure you check the documentation for the full list.

Use your patterns everywhere

After exposing your patterns you are ready to use them anywhere thanks to the sub-modules bundled within UI Patterns, namely:

• UI Patterns Field Group: allows to use patterns to format field groups provided by the Field group module. Read the documentation.
• UI Patterns Layouts: allows to use patterns as layouts provided by the Layout plugin module. This allows patterns to be used on Display Suite view modes or on panels out of the box. Read the documentation.
• UI Patterns Display Suite: allows to use patterns to format Display Suite field templates. Read the documentation.
• UI Patterns Views: allows to use patterns as Views row templates. Read the documentation.

Example: style links as call-to-action buttons

One of the most ordinary situation is styling a group of links as call-to-action buttons. This can be easily achieved using UI Patters.

Say we have defined the following Button pattern:

button:<br> label: Button<br> description: A simple button.<br> fields:<br>&nbsp;&nbsp; title:<br>&nbsp;&nbsp;&nbsp;&nbsp; type: text<br>&nbsp;&nbsp;&nbsp;&nbsp; label: Label<br>&nbsp;&nbsp;&nbsp;&nbsp; description: The button label<br>&nbsp;&nbsp;&nbsp;&nbsp; preview: Submit<br>&nbsp;&nbsp; url:<br>&nbsp;&nbsp;&nbsp;&nbsp; type: text<br>&nbsp;&nbsp;&nbsp;&nbsp; label: URL<br>&nbsp;&nbsp;&nbsp;&nbsp; description: The button URL<br>&nbsp;&nbsp;&nbsp;&nbsp; preview: http://example.com

On the entity display setting page we access the link field setting by clicking on the gear icon:

Then, after selecting the Pattern field template and the Button pattern, we map the link field columns to the pattern's fields defined above:

Each value of our multi-valued link field will be then formatted using the Button pattern,
as shown below:

Conclusions

The UI Patterns module aims at integrating your pattern library with the most used Drupal 8 rendering systems. It also makes easy to use third-party tools such as PatternLab.

The project is currently under active maintenance, please file issues and/or support requests using this GitHub repository.

P.S. Special thanks to aleksip for getting the integration with PatternLab and the Component Libraries to work!

Tags: Drupal PlanetDrupal 8