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
ortheme: 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.