Support for "block" based patterns

[ringods]

I am using Pattern Lab Node v3.0.4 on Mac, with Node v10.16.3, using a Custom Edition.

Actual Behavior

Patterns can only be included using a single tag include:

{{> molecules-some-pattern }}

They can be parameterized using e.g. pattern parameters and pattern data. If the pattern you create is a customization of a general HTML div tag, this limits ones options very much. For instance, I created an atom for a general section on a web page:

https://gitlab.com/ringods/starterkit-zoho-sites/blob/03bbe04aba199266d9c28b4cb1b3479ea6df36c3/dist/_patterns/00-atoms/05-sections/00-section.hbs

This mimics the generated HTML for a section div in Zoho Sites. Since this is a generic container, you can add any type and any amount of content. I made this pattern data driven via Handlebars dynamic partials to detect the content which needs to be put between the opening and closing div section tag.

Suppose I want to have an organism pattern representing a section with a title and a two column layout as can be seen in the following example image:

To implement this complex nesting, you end up writing HTML in JSON:

https://gitlab.com/ringods/starterkit-zoho-sites/blob/03bbe04aba199266d9c28b4cb1b3479ea6df36c3/dist/_patterns/02-organisms/00-heading/00-section-114.hbs
https://gitlab.com/ringods/starterkit-zoho-sites/blob/03bbe04aba199266d9c28b4cb1b3479ea6df36c3/dist/_patterns/02-organisms/00-heading/00-section-114.json

I clearly went too far on the data-driven and dynamic partial approach here. Re-using the pattern in a template or page would mean I need to copy and embed a full JSON structure in the data file for the tempate or page.

This got me thinking on what I was missing in PL.

Expected Behavior

If a pattern could be written as a block, meaning an open and close tag, a molecule or organism could be much easier written by including lower level patterns. E.g. my section organism representing the image could be written as:

{{! 02-organisms/00-heading/00-section-114.hbs }}
{{> atoms-section }}

{{> atoms-row}}
{{> atoms-column}}
{{#block title }}
{{#with title}}
{{> molecules-heading }}
{{/with}}
{{/block }}
{{/ atoms-column}}
{{/atoms-row}}

{{>atoms-row}}

{{>atoms-column}}
{{#each entries}}
{{! ... more content here to generate each entries' structure }}
{{/each}}
{{/atoms-column}}

{{/atoms-row}}

{{/ atoms-section }}

A corresponding data file for a section like written above could then be limited to the "true" data:

{
    "title": {
        "header": "Menu",
        "align": "center",
        "element": "h2"
    },
    "entries": [
        {
            "food": "Bread with Butter and Jam",
            "description": "Warm oven baked bread with homemade preserves and butter",
            "price": "€5"
        },
        {
            "food": "Cereal",
            "description": "Roasted flakes of grains with honey",
            "price": "€3"
        }
    ]
}

Steps to Reproduce/Emulate

I tried this by using the wax-on set of Handlebars helpers and registerd them like this in PL:

const wax = require('wax-on')

module.exports = function (Handlebars) {
    wax.on(Handlebars);
    wax.setLayoutPath('source/layouts')
};

I created the section as a wax-on layout under source/layouts:

{{! source/layouts/section.hbs }}
<div data-element-type="section"
    class="zpsection zpdefault-section zpdefault-section-bg{{#if image}} zpbackground-size-cover zpbackground-position-center-center zpbackground-repeat-all zpbackground-attachment-scroll{{/if}}{{#if video}} zpvideo-section{{/if}}{{theme-section-classes}}"
    {{#if image}}style="background-image:url({{image}});" {{/if}} {{#if color}}style="background-color:{{color}};"
    {{/if}}>
    <div class="zpcontainer">
        {{#if video}}
        <div class="zpvideo-bg-container">
            <video class="zpsection-video" style="min-width:100%;min-height:100%;" src="{{video}}" muted="" loop=""
                autoplay=""></video>
            <div class="zpvideo-bg-overlay zpvideo-fallback-image" style="background-image:url();"></div>
            <div class="zpvideo-bg-overlay"></div>
        </div>
        {{/if}}
        {{#block content }}
        {{/block}}
    </div>
</div>

The organism using the section then reads this:

{{!organisms-section-114.hbs}}

{{#extends 'section'}}

{{#block content}}
{{#with title}}
{{> molecules-heading}}
{{/with}}
{{/block}}

{{/extends}}

The above snippet only displays the title, but more could be added to add the full menu as in the picture above. However, I don't like this syntax for one main reason: layouts are a wax-on term and are not integrated in Handlebars as patterns. I also can't document it as a pattern.

What do you think of the ability to write patterns as an open/close tag combination to allow for nested content much more easily?

[sghoweri]

Out of curiosity, have you checked out Twig templates?

While I’m not as familiar with what it takes to get this sort nested component composition working in Handlebars / Mustache, I know the ability to nest like this has been supported by Twig (and Nunjucks, which shares a lot of the same syntax) for quite some time!

As far as Handlebars, it sounds like the Handlebars templating engine in PL would need to get some updates in order to support this natively, yes?

[ringods]

@sghoweri with the twig or nunjucks engine, does the extends refer to another pattern, or to a layout/template which is a separate concept too, as in the emulation where I used wax-on in handlebars?

[bmuenzenmeyer]

What do you think of the ability to write patterns as an open/close tag combination to allow for nested content much more easily?

It sounds awesome, and In the past, what we would have tried baking this into core. In fact - that is exactly what we did with mustache - extending mustache's default behavior way past it's core capabilities and tightly-coupling patterns to Pattern Lab. This doesn't help much in the long run, however, when patterns need to exist outside PL in production systems. You need render-parity.

And so (I will fail to find the link now) it was decided to let pattern engines be themselves. We had a motto for a while, "PatternEngines, you be you." It means deprecating things like the shorthand include syntax as Pattern Lab concepts, and instead allow them to exist as PatternEngine concepts. We have work to rid core of the mustache-extended logic littered throughout it - but I am actually really excited with what you shared, because it proves that the Handlebars ecosystem meets your unique use cases and the tooling Pattern Lab provides mostly gets out of the way.

And what @sghoweri said is true too - there may come a time when developers outgrow the capabilities of the PatternEngine they are using. Myself, I have soured on Handlebars of late and am excited about Nunjucks. Nunjucks, Twig, etc have concepts that vastly outclass Handlebars and Mustache. Continuing to use wax-on may be viable, but it also means using that tool in your downstream.

I hope this helps clarify where we want to get Pattern Lab. I think of it today as more like 11ty than anything else, a static site generator that can plugin and harness the capabilities of the chosen templating system.

[ringods]

@bmuenzenmeyer @sghoweri I have been reviewing twig and nunjucks for a bit. Both indeed have extends and block support out of the box but not exactly as I want it. Also wax-on is not how I truly want it. The embed tag from handlebars-layouts comes closest. Based on the documentation, I think it supports:

• embed has an open and close tag
• content tags referring to named blocks of the first outer embed, so they do not conflict with other blocks
• nesting of embed seems to be supported
• the same partial can be used multiple times with different content blocks

On the other hand, if the decision was taken to let engines be themselves, PL should also not limit the extensibility of an engine in any way. Although there is support to register helper functions for Handlebars, helpers coming from a starterkit (e.g. wax-on or handlebars-layouts) can be copied over if I put them in the dist folder but the configuration/registration of it must still be added manually in the PL project using the starterkit. Issue #628, along with PR #632 which did not get merged, was about the fact that a starterkit should be able to influence the configuration of the using project.

Going forward, I would propose to no longer copy over any starterkit content. If a starterkit is published as an NPM package, why not use it as an NPM package:

• read config from ./node_modules/<starterkit_package>/patternlab_config.json
• read assets from ./node_modules/<starterkit_package>/dist/...
  In the config for the starterkit, I could point to where the helpers are located needed for patterns within the starterkit:
• read helpers from ./node_modules/<starterkit_package>/helpers/*.js

The starterkit package itself could have the required package dependencies. In my case that would be wax-on or handlebars-layouts. This would make a starterkit a self-contained unit, as a package ought to be. 😉

If you agree with this latest comment, should I create a new issue for this?

[bmuenzenmeyer]

Issue #628, along with PR #632 which did not get merged, was about the fact that a starterkit should be able to influence the configuration of the using project.

this behavior is supported - i know because i wrestled with it recently

[bmuenzenmeyer]

I would propose to no longer copy over any starterkit content

as far as I am concerned, startertkits are boilerplate meant to be extended from, riffed on, etc- they are not component libraries. in the ecosystem as we currently have it, you are describing a custom Edition that comes pre-built for your purposes.... cli + core + uikit + starterkit + handlebars engine + waxon

[ringods]

Good suggestion, but I do not like this sentence found in the edition-node package README:

Editions like this one are example pairings of Pattern Lab code and do not always have an upgrade path or simple means to run as a dependency within a larger project.

I would prefer packages because these can be easily upgraded. Or am I misinterpreting the sentence above?

[bmuenzenmeyer]

that sentiment is born out of the acknowkedgement that things like edition-node-gulp contained gulp tasks that were essentially boilerplate - with no simple upgrade path if a task changed ... we'd have to ask users to apply the diffs manually. this is the weakness of using any complicated runner in an edition, and why edition-node (pure access to the API)

also, this is before the CLI even existed.

[bmuenzenmeyer]

closing this issue - as i think our discussion led to an outcome besides a code change

[ringods]

For reference of other people bumping into this issue, here is how I reworked my setup with block based patterns. This is to prevent the exaggeration of data driven patterns for generic containers as described above.

https://gitlab.com/ringods/starterkit-zoho-sites/commit/fc78ea267dbee8d02c30d2a572d80827ca5cb767

The implementation is done with handlebars-layouts. Contrary to wax-on, it does not require a separate folder with layouts. Using the embed tag in handlebars-layouts, you can just use any pattern name. Note however that you have to put the pattern name in quotes:

{{#embed "atoms-section"}}
{{#content "section"}}
... nest your content here in derived patterns ...
{{/content}}
{{/embed}}