Define your patterns¶

Patterns can be exposed by both modules and themes: all defined patterns are collected and managed by a centralized plugin manager, this means that pattern IDs must be unique in order to avoid conflicts.

Pattern plugins are described using the YAML discovery method. To define your patterns simply create a YAML file named MY_MODULE.ui_patterns.yml or MY_THEME.ui_patterns.yml and list them using the following format:

blockquote:
  label: Blockquote
  description: Display a quote with attribution information.
  fields:
    quote:
      type: text
      label: Quote
      description: Quote text.
      preview: Life is like riding a bicycle. To keep your balance, you must keep moving.
    attribution:
      type: text
      label: Attribution
      description: Quote attribution.
      preview: Albert Einstein
  libraries:
    - MY_MODULE/library-1
    - MY_MODULE/library-2

Let’s break this down:

id

The root of a new pattern definition (blockquote in the example above). It must contain only lowercase characters, numbers and underscores (i.e. it should validate against [^a-z0-9_]+).

label

Pattern label, used on pattern library page.

description

Pattern description, used on pattern library page.

fields

Hash defining the pattern fields. Each field must have the following properties defined below.

type: Field type, can be text, numeric, etc. at the moment only used for documentation purposes.
label: Field label, used on pattern library page.
description: Field description, used on pattern library page.
preview: Preview content, used on pattern library page. It can be either a string or a Drupal render array, in which case we can use keys like type: processed_text or theme: image.

libraries

List of libraries to be loaded when rendering the pattern. UI patterns are supposed to be self-contained so they should define along all needed libraries.

Once the pattern is defined the module will expose them as standard Drupal theme definitions.

For example, given the my_pattern pattern ID then a theme function pattern_my_pattern is created and, consequently, the module will look for a template file called pattern-my-pattern.html.twig.

Once the pattern is defined it’s time to provide its Twig template. In order to do so we create a Twig file called pattern-blockquote.html.twig and we place it either under MY_MODULE/templates, if the pattern is exposed by a module, or under MY_THEME/templates, if it is exposed by a theme. Obviously themes can always override templates exposed by modules.

For example, a blockquote Twig template file pattern-blockquote.html.twig could look like the following:

<blockquote>
  <p>{{ quote }}</p>
  <footer>{{ attribution }}</footer>
</blockquote>

The blockquote pattern defined above will be rendered in the pattern library as shown below (styled using the Bootstrap theme):

Remember: we can always visit the /pattern page in order to have access to a full preview of all our patterns.

Organize your patterns in sub-folders¶

Patterns can be defined using a single NAME.ui_patterns.yml file. However, in case of sites with a large number of patterns, this might quickly becomes difficult to manage.

Luckily pattern definitions can be organised in sub-folders too, as shown below:

.
├── templates
│   └── patterns
│       ├── button
│       │   ├── button.ui_patterns.yml
│       │   └── pattern-button.html.twig
│       ├── media
│       │   ├── media.ui_patterns.yml
│       │   └── pattern-media.html.twig
...
│       └── pattern-jumbotron.html.twig
├── ui_patterns_test_theme.info.yml
└── ui_patterns_test_theme.ui_patterns.yml

Note: the example above is taken by the actual test target site that is used to test the module itself: have a look at ./tests/README.md and at ./tests/target/custom for working examples on how to use the UI Patterns module.

Override patterns behavior¶

The default behavior can be changed by using the following properties in you pattern definitions:

theme hook: If specified it overrides the default pattern_[id] theme hook with the provided value; the template file will change accordingly.
template: If specified it overrides only the template file keeping the default pattern_[id] theme hook.
use: If specified it will use a stand-alone Twig file as template. The value supports Twig namespaces, so the following notations are valid examples:

use: "@my_module/templates/my-template.html.twig"

use: "@molecules/media/media-block.html.twig"

The possibility of using stand-alone Twig templates allows for a swift integration with tools like PatternLab or modules like Component Libraries.

Attention: always remember to double-quote use: values or some YAML parsers (including PatternLab’s) will complain.