Skip to content

UI Patterns ​

What it does ​

UI Patterns 2 draws the same Single Directory Components outside the builder: as a block, as the layout of a content type or paragraph type, as a field formatter, as the style or the row of a view. Frame does not build a field mapping of its own: a component is mapped once, with UI Patterns, and the editor draws it from the same *.component.yml.

UI Patterns is optional. Everything here works when it is installed and is skipped when it is not. The recipe frame_editor_ui_patterns installs it with its submodules ui_patterns_blocks, ui_patterns_layouts, ui_patterns_field_formatters and ui_patterns_views (and Field Layout of core); frame_editor_full includes it.

bash
composer require 'drupal/ui_patterns:^2'
drush recipe themes/contrib/frame/recipes/frame_editor_ui_patterns

Lists of objects and text between components ​

UI Patterns types a prop by its schema, and any list of objects looks like a list of links to it. Its Twig extension then rewrites the items before the template gets them: text becomes title, href becomes url, and an item with no title gets its position as one. That would turn the keys of a component's own list into something else.

  • Frame stops it for the components of the theme. A list of objects in a component of the theme or its base themes is typed frame_list instead of links (Frame does it in hook_component_info_alter()), and gets to the template as it is, on the page, in the editor and in a UI Patterns block. A list is still a list of links, and is normalised by UI Patterns, when its prop says so ($ref: 'ui-patterns://links') or its items have both title and url. A frame_list prop has no source in a UI Patterns block, as an unknown one has none.
  • Text that is Twig\Markup needs a patch of UI Patterns. A string prop that gets markup from another component (a block of Twig captured with {% set %}, which is a Twig\Markup, not Drupal's Markup) is escaped by UI Patterns 2.0, because it only trusts Drupal's MarkupInterface. Frame's composer.json declares a patch for it (patches/ui_patterns-string-twig-markup.patch, in extra.patches), which cweagans/composer-patches 2 applies when the site requires it. With version 1 of the plugin, set "enable-patching": true in the extra of the site's composer.json. A plain string is still escaped, and a text/plain prop still loses its tags. Without the patch, pass the text as a slot or build it with Markup::create() in PHP.

Limitations ​

  • A local $ref in a schema. UI Patterns 2.0 cannot resolve $ref: '#/$defs/name' (a reference inside the component's own schema), and then reads none of the components of the theme. SDC and the editor accept it. Inline the schema, or use a reference to a file. The status report says when it happens.
  • Module order. Field Layout must run before UI Patterns Layouts so that the entity is known to the mapping; the names do that on a normal site (field_layout sorts first).
  • Blocks in the editor. UI Patterns offers every component as a Drupal block (ui_patterns:<theme>:<name>). The Blocks panel does not list them: the components of the theme are in the panel already, in their own groups, and a second entry for each would only be a copy. Place the component, or the block in a region of the theme.
  • UI Patterns adds data-component-id to the root element of every component it draws, also those of the editor.

One component, two ways to work ​

  • Classic: design, then fields and a paragraph type, then a Twig template, then the component.
  • Simple: design, then the component with its props in the schema; Frame makes the editor form from the schema.

Both end at the same component. With the classic way, a UI Patterns layout on the display of the paragraph type takes the fields to the props and the slots of the component, so the paragraph is drawn by the component and not by a template of its own. With the simple way an editor places the component in the editor. A component can be used both ways at once: the markup is the same.

WhereHowWhat draws it
the editorthe component is a block of the Blocks panelFrame, from the schema
a paragraph block of the editorthe layout of the paragraph's displayUI Patterns, through the display
a content type or any entitythe layout of its display (Manage display)UI Patterns
a block of a regionthe block ComponentUI Patterns
a fieldthe formatter Component or Component per itemUI Patterns
a viewthe style or the row ComponentUI Patterns

Paragraphs drawn by a component ​

A Paragraph block of the editor is drawn by the view display of its paragraph type (default). Put a UI Patterns layout on that display and the component draws the block:

  1. Structure → Paragraph types → your type → Manage display, Layout = the component (for example Promo).
  2. Map the fields: a prop gets Field property, a text or a fixed value; a slot gets the fields put in its region.
  3. Hide the fields that became props, so they are not printed twice.

What changes: the fields of the paragraph are drawn by the component. What stays: the wrapper of the paragraph template (paragraph.html.twig, the div with the classes paragraph paragraph--type--…), as for any entity with a layout. The block names a revision of the paragraph, and the component shows that revision. The unsaved values of the editor show in the same way, in the editor and its preview.

A paragraph type from a component ​

Configuration → Content authoring → Frame components has a link Create paragraph type at each component, for those who may administer paragraph types. It asks for a name and a machine name, lists what will be made and makes:

  • a paragraph type with a field for each prop that has a matching field type: text (string), formatted text (long text), yes or no, number (integer or decimal), choice (list of text, with the labels of meta:enum), link (link field, no title), email, date and date and time, image (media field of the image media types, else an image field). The fields are required where the prop is, take the title and description of the prop, and the default of the schema where it is a plain value. A field of the same name and type that exists is reused;
  • the form display and the view display with a widget and a formatter for each field;
  • with Field Layout and UI Patterns Layouts, the layout of the component on the view display, each field mapped to its prop (Field property) and removed from the display. The image stays a field of the display, as no prop takes the id of a media item yet;
  • for each slot, a field of nested paragraphs (Entity reference revisions, any paragraph type, widget Paragraphs, as many as wanted). On the view display the field stays a field, with the formatter Rendered entity, in the region that has the name of the slot, so the nested paragraphs are drawn inside the slot. Structure shows them under the block with the name of the slot. A field of the same name and type that exists is reused; its name is field_ and the name of the slot.

Skipped, and listed in the form with the reason: props with no field type (spacing lengths, hidden or fixed props, lists and groups of values, a time without a date, a field of the same name and another type). A slot whose field name is taken by a field of another type is listed as not mapped.

Without Field Layout and UI Patterns Layouts the fields, those of the slots too, are made and shown as a list of fields.

Sources of Frame ​

UI Patterns offers a source for each prop, by the type of the prop. The module adds four. They are values of a prop in the form of UI Patterns, with the tokens of the active theme.

SourceFor props of the typeGives
Frame styles (frame_features)attributesthe features of the editor as the attributes of the root element: margin, padding, maximum width, alignment, background colour, border, rounded corners, and classes
Frame image (media library) (frame_image)text, URLthe URL of an image of the media library, in an image style of the theme (the value of a prop with contentMediaType: image/*)
Frame entity (content, term or user) (frame_entity)an object that lists the properties of the entity objectthe object of the entity widget (x-builder-widget: entity): type, bundle, id, uuid, label, url, picked with an entity autocomplete
Frame length (spacing scale) (frame_length)texta step of the spacing scale, or a checked custom length such as 12px (the value of a prop with x-builder-widget: length)
  • Frame styles gives a component placed by UI Patterns the same spacing and background the editor gives its items: style="margin: 1rem; padding: 2rem" from the tokens, never a free value. Only the features the theme switches on are printed, and there is no value per breakpoint: that is for the editor.
  • The image and the length are what the editor stores ({"media": 12, "style": "style:medium"}, {"size": "l"}), so the same markup comes out. The image is picked with an autocomplete of the media library.
  • Frame entity limits the autocomplete to the x-builder-target and x-builder-bundles of the prop. A prop that does not name them gets a choice of the kind in the settings. The entity is not shown to a user who may not view it. UI Patterns has no prop type for an object, so it offers no source for type: object. The module adds the prop type frame_entity: a prop of the type object whose properties are only some of type, bundle, id, uuid, label and url has it, and so has the source. List the properties the template uses.
  • UI Patterns reads only type, format and enum of a prop. It drops contentMediaType and the x-builder-* keys, so it cannot tell an image or a length from any other text, and the two sources are offered for every text prop. Put them where they fit.
  • The sources give only the prop. The x-builder-picture, -srcset, -sizes and -alt helpers of the editor are not filled: with UI Patterns, map those props yourself.

Views ​

A view with a display of the type Component keeps working when it uses the UI Patterns style or row. Choose Component (UI Patterns) as the Format → Show (a style that wraps all rows in a component, rows in a slot with the source View rows) or as the row (each result is a component, its fields mapped to props). Placed in the editor, the display is drawn by Views, which runs the style and the row as everywhere. See Views in the editor.

Status report ​

Reports → Status report has the entry Frame and UI Patterns. For every display whose layout is a UI Patterns component it names:

  • a required prop with no source, or a fixed value left empty;
  • a source that gives another type than the prop takes (a number for a text);
  • a source that is gone (a field that was deleted), or a layout of a component that is gone.

It warns, and says which display. A component UI Patterns cannot read at all is reported too (see below). The entry is not there when no display maps a component.

When the component changes ​

The settings of UI Patterns store no version, so a renamed prop would leave them with a prop that is gone. The update of the content (drush updb, see Versions and migrations) also moves them: blocks, the layout of a display, the settings of a field formatter and the style and row of a view get the same declared steps as the pages (rename, remove, values of fixed props). The same post update function brings all of them up to date.

Tests ​

UiPatternsRenderTest draws one fixture component, promo of the theme frame_editor_test_ui_theme, as an item of the editor, as a block and as the style and row of a view, and compares the markup. It also runs the post update that version 2 of promo (a renamed prop) needs, and checks that every one of these ways, and the layout of a display, is brought up to date by it. UiPatternsParagraphsTest does it for the layout of a paragraph display, UiPatternsFieldTest for the field formatters, UiPatternsSourcesTest for the sources of Frame and UiPatternsRequirementsTest for the status report. They are skipped without UI Patterns.