Overriding Automatic Pattern Discovery

While the UI Patterns Pattern Lab module is intended to discover patterns in a Pattern Lab instance with little to no configuration, there may be cases where overriding the default behavior may be useful. To allow for this, during discovery the module will check for the existence of the  ui_pattern_definition key in your pattern definition file. This key primarily exists to allow the pattern to be overridden using the pattern definition options supported by the UI Patterns module.

UI Patterns Pattern Definition Options

UI Patterns Pattern Lab will currently recognize a label for the pattern, description for the pattern, and individual field definitions, and a use value to explicitly define the twig template to be used for the pattern. A yaml example of all four would be as follows:

ui_pattern_definition:
  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
  use: "my-blockquote.twig"

For any options not provided via ui_pattern_definition values, UI Patterns Pattern Lab will fall back to its default automatic discovery behavior. For example it would be possible to provide label and description values, but use default field discovery.

It is possible to mix 'traditional' fields in your pattern definition file alongside ui_pattern_definition values.  The following would be acceptable for example:

image: https://placeimg.com/640/480/arch
caption: Caption for my image (this will be discovered automatically)
ui_pattern_definition:
  label: My Label
  description: This description will override automatic discovery.

The goal is to support all UI Patterns pattern definition options at some point in the future including libraries.

About 'Use' Values

UI Patterns Pattern Lab will only look inside a single directory for files and assets related to your pattern. It will not traverse subdirectories. As a result, any path included in a 'use' value will be ignored and the module will look for the specified file in the same directory as the pattern definition file containing the use statement.

For the sake of compatibility with existing UI Patterns definition files, namespaces and paths can be included in a use value, but they will be ignored.

Consider the file blockquote.yml. The following use values:

ui_pattern_definition:
  use: "@molecules/media/my-blockquote.twig"

and

ui_pattern_definition:
  use: "my-blockquote.twig"

Would both result in the module attempting to use a the twig file my-blockquote.twig in the same location as blockquote.yml when defining the related UI Pattern.

Additional Pattern Definition Options

It is also possible to use ui_pattern_definition to tell UI Patterns Pattern Lab to ignore a pattern in your Pattern Library. This can be useful if your pattern library contains example patterns for illustration or prototyping purposes that you do not want exposed in Drupal as UI Patterns.  The following is an example of a pattern definition would result in the pattern being ignored by UI Patterns Pattern Lab during pattern discovery:

image: https://placeimg.com/640/480/arch
caption: Caption for my image (this will be discovered automatically)
ui_pattern_definition:
  ignore: true