Next steps before stable releases: Variants, Subfields, Multiple fields, Tags and Hidden patterns

[ademarco]

The following is a list of improvements we wish to include in the first stable release. We would like to hear your thoughts about it.

• Variants: possibility for a pattern to expose variants, so that the preview page will automatically display all possible pattern variations. Variants can be mapped to fields or other properties when using patterns to render views, field templates, layouts, etc.
• Subfields: patterns are often composed by subfields, for example in the case of carousel you want a carousel title and each carousel slide, should have an image, a title and a link. This can be achieved by using the type: property. Subfields can be patterns themselves so that mappers will be also enabled to map views or entity fields when suing patterns with views, layouts, etc.
• Multiple fields: we should define which field can accept multiple values so that, for ex., a carousel can render a multiple image field seamlessly, this is a tricky one.
• Tags: each pattern should be tagged so that not all patterns will be exposed all the time in all contexts, i.e. it does not make sense to have a button being exposed as a layout, and vice-versa.
• Hidden patterns: possibilities to declare a pattern as hidden so that it can be considered as a "service pattern" and it will be not rendered in preview pages or exposed to mappers.

All issues above can be summarized in the following example of a carousel definition, we can use this to drive our discussion:

carousel:
  label: carousel
  variants:
    large:
      label: Large
      description: This is a large carousel.
    small:
      label: Small
      description: This is a small carousel.
  tags:
    - partial
  fields:
    title:
      type: string
      label: Title
    slides:
      type: pattern:slide
      multiple: true

{# pattern-carousel.html.twig #}
<div class="carousel">
  <h3 class="title">{{ title }}</h3>
  <div class="slides">
    {% for slide in slides %}
      {{ pattern('slide', slide) }}
    {% endfor %}
  </div>
</div>

slide:
  label: Slide
  hidden: true
  fields:
    image:
      type: pattern:image
    title:
      type: string
      label: Subtitle
      preview: Slide title.
    sudtitle:
      type: string
      label: Subtitle
      preview: Slide subtitle.
    url:
      type: url
      label: URL
      preview: URL the slide links to.

{# pattern-slide.html.twig #}
<a href="{{ url }}" class="slide">
  {{ pattern('image', image) }}
  <h4>{{ title }}</h4>
  <p>{{ subtitle }}</p>
</a>

image:
  label: Image
  hidden: true
  fields:
    url:
      label: URL      
      type: string
    title:
      label: Title       
      type: string

{# pattern-image.html.twig #}
<img src="{{ src }}" title="{{ title }}">

[ademarco]

As first users of the UI Patterns module your input would be of great help! 😄 \cc @drupol @pixelwhip @hctom @aleksip @haringsrob @bircher @kclarkson @capriosa @hctom @tanc

[hctom]

@ademarco This looks absolutely fantastic! ;)

Here are some of my thoughts/questions regarding your topics:

• Variants: How do you want to implement them. Will they be template suggestions like pattern-carousel--large.html.twig or how will those be realized?
• Subfields: This really is a great idea. I think the only "problem" I see with this is the UI for deeply nested components (e.g. a carousel having a slide having a teaser having an image figure etc.). But I guess it is worth giving a try and there will definitely be a solution for possibly components with too many nesting levels
• Multiple fields: What do you think about using a similar syntax like PHPDoc type hinting? So type: pattern:whatever or type: string is single value field and type: pattern:whatever[] or type: string[] is a multivalue field.
• Tags: Sounds really nice, even though a self-contained component normally should work in every context. But you are right, we need something to avoid cluttering the list of components wherever they are selectable.
• Hidden patterns: Definitely something that's needed for small helper patterns ;)

And last but not least, here is a little addon for your list: I would really appreciate something to be able to group components on the preview page. Right now every pattern is just listed and rendered, but with large component libraries this might run into problems really fast (e.g. rendering tons of components on a single page and some of them might even use a lot of JavaScript which might even crash the browser). What do you think about having something that allows setting a "path" of a specific component in a tree structure that is used to render a component menu (e.g. KSS uses something similar with its Styleguide syntax feature)?

... but all in all, this module is really heading the right way! Thanx a lot for that!

[capriosa]

Your ideas sounds really cool. Especially the type:pattern will be very useful. Btw. do you know that UI-Patterns works very well in conjunction with the Stacks module? And with the new features from above this will even get better.

[kclarkson]

+1 for @hctom suggestion for grouping patterns on the overview page. This is desperately needed for organization!

[backlineint]

Also agree that this feature list looks very promising. A few comments:

• Variants - this one came up for me in my use of the module thus far. I'll often include a style modifier variable in my components. Right now I'm passing the appropriate style modifier value when including components from pattern lab, but it sounds like what is planned here could address this nicely.
• Subfields - this is another thing I do frequently in Pattern Lab, so seems important to start thinking about how UI Patterns will handle this as it matures. Also agree that managing the complexity in the UI here is going to be a big part of the trick.
• Multiple fields - this came up a couple of times as a question when I gave a lightning talk on UI Patterns in the Chicago Drupal Meetup recently.

Excited to see where this goes and looking forward to following along.

[ademarco]

Now pattern definitions are actual TypedData objects, this will allow us to introduce things like variants or tags in a much easier and maintainable way. Check PR #79 for more details.

[ademarco]

To all those involved in this discussion you might be interested in this issue: Allow multiple sources to be mapped to the same destination #81

[ademarco]

I'm planning to work on this issue before our talk on UI Patterns on DDD in Seville

As first we could maybe tackle tags and a better overview page, I'm actually thinking to move out the overview page on its own module, say ui_patterns_overview so that we can isolate complex logic there.

It would be also good to have a pattern definition property dedicated to the overview, for example:

button:
  ...
  overview:
    parent: Buttons
    weight: 10

Or maybe we reverse it and we have a YAML file describing the overview page? Such YAML plugin could be exposed by the ui_patterns_overview module, so that we don't clutter the pattern definitions?

@hctom which one would you prefer?

[hctom]

Hm, thats quite tough to decide. On the one hand, a dedicated file is of course good to keep the actual pattern definition short and simple, but on the other hand, the pattern definition itself already contains information that is used in the overview (e.g. label and description).

For now, I think it should all reside in the same file, so you don't have to search different files for metadata information used in the overview or other places that display pattern information (e.g. select lists when assigning patterns).

[tassilogroeper]

At DDD17 we discussed a litte further. This is what we came up with:

• split basic default styleguide off, to a sub module. Make a distinction between the plain ui_patterns and it default Styleguide, that can be used for writing test and demo purpose.
• Discovering a pattern will be done via a "discovery.yml" in every folder (*.ui_pattern.yml) with minimal setup, like
  • machine name ([file_name _base].ui_pattern.yml)
  • label (for the select inside of Drupal, translation via interface translation)
  • tags (eg. hidden, view_row, node, taxonomy) to filter dropdown
  • libraries define related assets as current implementation
  • fields consisting of a list of machine names with label and optionally a type (still unsure about the actual usage)
• For the default style guide add keys to this file, Not part of the Base Pattern definition
  • use, preview, description, variants
• leave out variants from base definition in contrast to drupal view_modes. They are not the same. A "variant" (fractal) or "pseudo-pattern" (patternlab.io) are just a set of special information to the very same fields of one single template. Whereas a drupal view_mode maybe handles different fields.

List of possible styleguides ;-) github.com/davidhund/styleguide-generators

[tassilogroeper]

My proposed structure would be the following:

• Have one [pattern_description].pattern.yml-file (aka pattern description) for every pattern to be discovered.
• Per default a pattern target file ([pattern_description].html.twig) will be automatically discovered in the very same folder as the pattern description file.
• the .html.twig-extension of the target file needs to be a config. for other style guides as patternlab, may use only the .twig-extension. E.g. defined/overwritten in the my_theme.info.yml since the components settings (from the component library module) are situated there as well.

1. One basic assumption to be decided on

1.1. A [pattern_description].pattern.yml-file contains only one describable pattern target. Meaning all assets described in the pattern description belong to the very same library. Thus there can only be one library per pattern (ui_patterns/[pattern_description]). Unique pattern_description-names are implied. 1.2. A [pattern_description].pattern.yml-file may target multiple files and libraries. For this scenario I can not really make up a good usage for naming things. E.g. referencing a library with ui_patterns/[pattern_description]--[custom_name].

Discussion:

I think version 1. is somehow limiting but it can bring the most clarity. So instead of searching in a file for exact patterns and creating somewhat obscure library names, we stick to basic principles:

• one yml file describes a pattern and its dependencies
• there may be more pattern descriptions in one folder without interference
• libraries are easy to name or override
• it feels more like: every component/pattern is a module
• the pattern discovery process only goes for one "extension"

├── components
│   ├── shiny-buttons
│   │   └── buttons.css
│   │   └── button-default.html.twig
│   │   └── button-default.pattern.yml
│   │   └── button-primary.html.twig
│   │   └── button-primary.pattern.yml
│   └── contact
│       ├── contact-base.css  // may also be a compiled file
│       ├── contact-base.scss
│       ├── contact-actions.js
│       ├── contact.config.js // belongs to style guide
│       └── contact.html.twig
│       └── contact.pattern.yml
│   └── contact-preview
│       └── contact-preview.html.twig
│       └── contact-preview.pattern.yml

button-default.pattern.yml

label: Button Default
fields:
  url: Url
  title: Link title
library:
  css:
  # The SMACSS category (base, layout, component, state or theme)
    base:
    # The path relative to the css file.
      buttons.css: {}

contact.pattern.yml

label: Contact information
fields:
  title: Contact title
  emails: Emails
  phones: Telephones
  # ...
library:
  css:
    base:
      '//fonts.googleapis.com/css?family=Lato': { external: true }
    component:
      contact-base.css: {}
  js:
    contact-actions.js: {}
  dependencies:
    - ui_patterns/button-default
    - core/jquery

contact-preview.pattern.yml

label: Contact information preview
fields:
  title: Contact title
  emails: Emails
  phones: Telephones
  # ...
library:
  dependencies:
    - ui_patterns/contact

2. How to load twig files and their assets

How to the style guides will reference their templates is nothing we can influence. E.g. whether ID like include (Fractal: @box for a files situated under components/boxes/box/box.twig) or fully qualified (@components/boxes/box/box.twig). This may not be our problem, because other contrib modules, like components, can take care of that.

Our problem is rather, what if the contact-pattern references the button-pattern with an {% include %} statement? how does the button library get loaded if not directly addressed by our pattern description file? This may be a easy case, but I can think of a article having multiple optional includes...

[ademarco]

Thank you @pheadeaux ! I'll follow up tomorrow, for the moment https://github.com/nuvoleweb/ui_patterns/pull/84 will add support for any sort of file extension in the use: property, so we can just have:

image:
  label: Image
  use: '@molecules/media/image/image.twig'
  fields:
    image: Image
    caption: Caption
    credit: Credit

[kalinchernev]

Hi all, Just passing by this thread, few thoughts:

• "Discovery" feature is a good direction of gluing systems together
• Choosing a specific generator for the pattern library could be a potential scope creep for integration IMHO. For example, Zen with kss-node is good enough for shipping theme with a set of examples, but having fractal for example is a bit different story as it's a whole framework with a build system, although very flexible.
• Instead of going for a specific generator framework of components for the visualization part (pattern library or style guide) the build system would be more independent, but still community-proven: like webpack, rollup, etc. that take a set of files, do something with them and output bundles depending on their purpose. Then these build systems can be integrated into fractal or other frameworks for generating the front-end demo of the patterns, still you keep independence of the framework for the style guide.

[ademarco]

I'm totally for [ID].pattern.yml, although we have been using [ID].ui_patterns.yml for now, but I guess we can support both and slowly fade out [ID].ui_patterns.yml.

Target file can be automatically discovered too, only I'm wondering what would happen with - separators as patterns IDs should not support that, maybe we can convert - into _ or allow it and see how the Drupal theme system reacts to that. For sure we cannot allow double-dash -- as it has a specific meaning for Drupal (i.e. theme suggestion components are separated by a double-dash).

Maybe the best would be to allow a redefinition of pattern ID in the YAML file, for example:

├── components
│   ├── shiny-buttons
│   │   └── buttons.css
│   │   └── button.twig
│   │   └── button.pattern.yml
│   │   └── button-primary.twig
│   │   └── button-primary.pattern.yml

then:

# button-primary.pattern.yml
id: button_primary
use: button-primary.twig
fields:
  label: Label
  url: URL

While for button it could simply be:

# button.pattern.yml
fields:
  label: Label
  url: URL

Pattern names are required to be globally unique too, so I guess allowing developers to re-define IDs is useful or even required.

Libraries already receive the following custom notation:

ui_patterns/[ID].[LOCAL_LIBRARY_NAME]

So if we have (note that the following is the correct way of defining local libraries):

image:
  label: Image
  fields:
    ...
  libraries:
    - library_name:
        css: ...
        js: ...
    - another_library:
        css: ...
        js: ...

Then UI Patterns module will expose its libraries as follow:

- ui_patterns/image.library_name
- ui_patterns/image.another_library

Also with new PR #84 this is now possible already:

  use: '@molecules/media/image/image.twig'

[tassilogroeper]

@ademarco I agree. also the way of referencing the libraries works for me.

About the use-key: please be very cautious about that one, since we might introduce an alias system, that can be hard to grasp:

in Drupal we might use @molecules/media/image/image.html.twig but inside the (whatever) styleguide the include may also go for the .twig version. I mean, we should enforce the parity of the reference methods - otherwise reusing patterns might not work correctly.

[aleksip]

These are all great improvements, but as development has slowed down in the past few months, I'd vote for releasing 1.0 as soon as possible. beta7 is already good enough for a lot of use cases (I've used it on several production websites), and a 1.0 release would be much more attractive for people considering the module.

[sherakama]

Ditto to the 1.0 release.

I am also planning on using this module for a production website and have some development cycles to share. Do you have a development plan outside of this issue or a contributing document?

[sherakama]

A first effort at the variant functionality can be found here: https://github.com/nuvoleweb/ui_patterns/pull/105