Wp-calypso: Patterns API: create a glossary of definitions [ongoing]

[ramonjd]

To reduce confusion caused by the multitude of terms and discussions across various teams and projects, let's create a glossary to which folks can refer.

A list of definitions will ensure that we are speaking about the same concepts in our communication.

We might use a term such as "Patterns" differently to how Gutenberg ultimately uses it. It doesn't really matter.

We should be able to have productive conversations if we can point folks to a definition of our working terms.

The glossary will be an ongoing task once we agree on usage, but terms we could include are:

• pattern: a collection of one or more blocks ???
• vertical
• pattern API
• starter pages ?
• design sites
• Gutenboarding
• page template/layout
• ????

I just made all these up by the way. None of them needs to be included.

The best place for will initially be a p2 or FG page. But maybe also in the README of any library we eventually create.

[andrewserong]

Just adding a few that have come up while hacking around with design starter sites. When setting a post or page in a source design site, we'll want to define its _type_ (or another term for it) to indicate where it'll be used. E.g.

• type: 'block_pattern' — used in the inserter within the editor
• type: 'page_layout' — used as a page layout when someone goes to create a page
• type: 'homepage_design' — used as a design that someone selects within Gutenboarding

And I guess an individual block pattern could potentially be more than one of these (e.g. maybe a homepage design is _both_ a page layout and a homepage design, whereas an About page page layout would only be shown when creating a page).

So perhaps this isn't so much type but maybe it's a show_in attribute with an array of places where it should be shown? In that case, we could have tags like:

• block_pattern_show_in_block_inserter
• block_pattern_show_in_page_layouts
• block_pattern_show_in_homepage_designs

Naming is hard! 😅

[ramonjd]

maybe a homepage design is both a page layout and a homepage design

Don't want to throw a spanner in the works, but page_layout seems to cover both to me, so long as we distinguish between a "pattern" (a collection/group of blocks intended to be used within a page) and a group of blocks intended to represent an entire page.

We'll also have to have some way to group page layouts under a particular "design", e.g., the Home, About and Contact page layouts for a new Maywood site (?) This is where we might exploit the use of categories/tags on the source sites.

Once we get a consistent set list of categories or tags down we could add them to our glossary too.

Naming is hard! 😅

Yes. 🤣

[andrewserong]

Don't want to throw a spanner in the works, but page_layout seems to cover both to me

It totally does! I think the glossary is going to be quite important for all of this.

[ianstewart]

type: 'homepage_design' — used as a design that someone selects within Gutenboarding

Not to throw another spanner in the works but this one feels tricky for me because of the usage. :) As it works now in Gutenboarding the intent with the starter site designs we've created with individual blogs on wp.com is to have …

• The content from a homepage on a site (that's the "layout" part)
• Plus the blog posts from a site
• Plus the theme active on a site
• Plus the global styles fonts on a site

Like with Bowen here.

• Content on a homepage
• Plus the blog posts on a site
• Plus the Coutoire theme (to get the colours and basic styles)
• Plus the global styles fonts on a site (Playfair Display / Roboto)

That said, I do think we want to take some Layouts and _categorize_ them as home pages like we do in the Layout Selector right now.

So, if we have something like …

• block_pattern_show_in_block_inserter
• block_pattern_show_in_page_layouts

… I'd imagine both would also allow arbitrary categorization. And for page layouts one of our arbitrary categories might be "Home Pages" — at least for the Layout Selector or any future version of it that let you add pages to your site. (How that would work with Starter Designs in Gutenboarding, that part seems tricky.)

[ramonjd]

Not to throw another spanner in the works but this one feels tricky for me because of the usage. :) As it works now in Gutenboarding the intent with the starter site designs we've created with individual blogs on wp.com is to have …

Strictly talking about the categorization of "block collections" - and I'm using that phrase to described any collection of blocks - we could have some hierarchy to describe the "types"

"a word for any collection of blocks"
    |__layout // a collection of blocks that constitutes the entire post_content
        |__page
        |   |____some_page_desc // home, contact, some other descriptor
        |           |____
        |__post
    |__pattern // a collection of blocks with
        |____some_pattern_desc // what the pattern represents

Plus the theme active on a site
Plus the global styles fonts on a site

I think we should capture what we mean by these terms in a glossary

For the patterns API, I'm yet to see where we need to concern ourselves with themes/global styles _right now_ while we're thinking about raw block content.

I suppose we will however when we start using the API to create sites, in which case themes and so on will be variables in another site creation system, the evil twin of headstart (?)

block_pattern_show_in_block_inserter
block_pattern_show_in_page_layouts

I'm probably misunderstanding the intention here. It might be a good idea for consumers of the API to determine which blocks they want in their application rather than categorizing a block itself to appear in a certain place. 🤷

[andrewserong]

For the patterns API, I'm yet to see where we need to concern ourselves with themes/global styles right now while we're thinking about raw block content.

I suppose we will however when we start using the API to create sites, in which case themes and so on will be variables in another site creation system, the evil twin of headstart (?)

Thinking over Ian's comment, I'm imagining we'd need to know default theme / font pairs to be able to replace the hard-coded available-designs.ts list, for the design step, and for the live preview in the style step (which currently renders the blocks in the appropriate theme), before we get to site creation, too. So perhaps this is a chunk of metadata associated with each block pattern? We could infer theme based on the theme set of the design source site, but we might need a label/tag/whatchamacallit for the font pairing... but then again, this'll only be for home page templates, since ordinary block patterns don't care about the theme / fonts? 🤔

I'm probably misunderstanding the intention here. It might be a good idea for consumers of the API to determine which blocks they want in their application rather than categorizing a block itself to appear in a certain place.

That's a good point! I guess all we need is for the tagging to be appropriate and logical enough so that a single API call in the consuming code can grab what it needs. So is_block_pattern or is_page_layout might be enough, without the show_in. And again, these names could be anything else, of course!

[ramonjd]

Thinking over Ian's comment, I'm imagining we'd need to know default theme / font pairs to be able to replace the hard-coded available-designs.ts list, for the design step, and for the live preview in the style step

I forgot about the preview. 👍 Glad someone is thinking. :)

I assume theme/font info would remain config data we'd store independently of our block pattern templates (the files we use to swap content/language in a block).

[ianstewart]

Hopefully non-spanner comment:

https://make.wordpress.org/design/2019/11/14/blocks-patterns-and-layouts/

Some definitions adapted from Mel's work.

• Pattern: Patterns are curated collections of blocks, often organized around a specific section or purpose. They make up common patterns across the web. Users currently interact with them directly with the Gutenberg Insertor.
• Layouts: Layouts are (conceptually) one step up from patterns. They can be groupings of patterns or specific blocks that make up the entire design of your page. Users currently interact with them directly when adding a new page on WP.com in the Layout Selector. And indirectly when selecting a Starter Design in the Gutenboarding flow.
• Starter Designs: The guide for the default content selected by a user in the steps that make up the Gutenboarding flow. Currently consisting of the following elements bundled together: A page layout with text, images, and settings meant to evoke the homepage of a common type of site; matching Posts that may be required by dynamic blocks in the page layout; a WordPress.com Theme and Global Styles Font pairing meant to make that page layout look it's best.

but then again, this'll only be for home page templates, since ordinary block patterns don't care about the theme / fonts?

Correct. Only Starter Designs care about theme / fonts. And that's only because of the nature of Starter Designs that currently bundle the selection of a Layout, Theme, and a default font pairing in one Gutenboarding Step.

I assume theme/font info would remain config data we'd store independently of our block pattern templates

That'd be my assumption too, fwiw.

[ianstewart]

There are some more technical supplementary additions to some of those definitions here:

https://developer.wordpress.org/block-editor/developers/block-api/block-patterns/

[ramonjd]

Now that we've started our MVP I've created a page to capture some important terms

PbxlJb-gy-p2

Feel free to add/edit/delete. The ambition is to promote it to the FG once we have a working application in production.

I'll close this issue to reduce clutter for the board.