Proposal for Block Templates #3588

mtias · 2017-11-21T11:56:17Z

Seems we didn't have an overview issue for block templates even though we have discussed them repeatedly.

Definition: In its most general sense, a block template is a definition that includes a list of block items. Those blocks can have predefined attributes, placeholder content, be static or dynamic.

Uses

Not to mistake with global blocks and nested blocks, even though they can be related — the list of blocks a template provides could potentially include a global block and it can have nested blocks in the specification. The use case of "reusing a group of blocks" is not necessarily a template task, but a global blocks one paired with nesting.

What block templates allow is to specify a default state for an editor session and a mechanism for rendering a page-route's corresponding PHP theme file. This can be done in multiple ways:

Setting a default through code dynamically. (defaultBlock API should support option of supplying a list of blocks, not just a single block.)
Instantiated as a default for a given post type, post format, etc. (When registering a post type you can specify a default block or template to use for any new post of that type.)
Saved and assigned to pages as "page templates". They can be defined in a template.php file or pulled from a custom post type (wp_templates) that is site specific.
As the equivalent of the theme hierarchy.

Example with pseudo code below of a template.php:

<body>

<?php
    do_blocks( array(
        // Theme header: "blocks/header/index.php"
        do_block( 'theme/header' );
        // A core text block
        do_block( 'core/text', array( 'placeholder' => 'Fill some text here...' ) );
        do_block( 'core/post-title', array( 'id' => get_post_id() ) );
        // A post block: renders the_content
        do_block( 'core/post', array( 'id' => get_post_id() ) );
        // Theme footer: "my-theme/blocks/footer/index.php"
        do_block( 'theme/footer' );
    ) );
?>

</body>

Details

Templates can:

Be defined in JS (state tree) or PHP.
Include blocks with children.
Be locked (no movers or ability to delete its components).
Be set as defaults for post types.
Be saved and edited by the user.
Be used as the contents of a page-template.php for initializing an editor provided by a theme.
Include static blocks as de facto placeholders in themselves since they don't have a save callback on the server.
Be inherently portable across themes.

Implementation Steps

(From 3 onwards we are in customization territory.)

Add support for specifying an array of blocks to the editor as initial state.
Add ways of defining array of blocks in both JS and PHP.
Allow rendering a .php file that includes a list of blocks and relevant functions. These are transformed to an editor state tree when loaded in an editing context.
Allow saving templates by the user. These are shown when creating a new page alongside theme provided defaults.
Build theme with nothing but block definitions in the template hierarchy.
Allow editing regular theme hierarchy templates (index.php, archive.php, etc) through the editor, saving changes in a revisioned CPT that can rule over the theme supplied ones as needed.

Tasks

Define array of blocks in the editor as initial state.
Allow custom post types to define a template.
Allow block templates to be locked down.
Allow templates to be saved in a wp_templates hidden post type.

The text was updated successfully, but these errors were encountered:

domtra · 2017-12-14T09:12:54Z

It took me a while to find this issue, but this is exactly what I have been looking for. Great, @mtias, that this already exists and work is actually already being done.

I just want to add a couple of thoughts regarding your proposal:

With a system like this, and nested blocks via BlockList or some other component that should have the same option to add a template like in your proposal, quite a few issues could be solved.
Especially when looking at #3330 and in particular meta boxes support, this could be another way on how to migrate legacy meta boxes to Gutenberg. Having a template that you can hook into and customize from a theme, for example, would also mean that even if the editor (the_content) is not available in a custom post type, you could still use Gutenberg for a better experience by integrating all meta boxes as fixed blocks defined in the template.

At my company we use ACF Pro quite extensively. One of the great features is to be able to define static fields, but also (with the pro version) flexible content and repeater fields. The same thing could be achieved by defining a template that is locked and including a BlockList component to which you can add dynamic blocks. You would need to specify what childblocks are allowed in this BlockList, but I think someone is already on that.

One other thing that comes to my mind is that besides Gutenberg showing a locked template, there should probably also be some server side validation. I do not know if this is a priority atm though.

youknowriad · 2017-12-22T14:08:40Z

I'm going to close this as the initial version of this is shipped. I'll leave #1684 open to track "nested locking"

mtias · 2018-01-03T11:36:10Z

Reopening so we can still access the remaining points about saved templates.

greatislander · 2018-01-03T13:32:48Z

I'm wondering if the code that has been merged for Block Template support exposes any API that would allow the template to be switched based on taxonomy selection? Say, for example, you have a category that you use for all image posts. Upon selecting that category, could you switch to a Block Template with an image block and nothing else?

I guess this also leads to a broader question. If a post is begun without an assigned Block Template and a change is made (e.g. selecting a specific post format) that assigns a Block Template, what happens to the content? The block paradigm changes the current behaviour, where switching post formats has no impact on the editor.

westonruter · 2018-01-16T04:03:24Z

Example with pseudo code below of a template.php:

I think that such a blockified PHP template should really be returning the data structure. For example:

<?php
return do_blocks( array(
    // Theme header: "blocks/header/index.php"
    do_block( 'theme/header' );
    // A core text block
    do_block( 'core/text', array( 'placeholder' => 'Fill some text here...' ) );
    do_block( 'core/post-title', array( 'id' => get_post_id() ) );
    // A post block: renders the_content
    do_block( 'core/post', array( 'id' => get_post_id() ) );
    // Theme footer: "my-theme/blocks/footer/index.php"
    do_block( 'theme/footer' );
) );

This would then allow for the template's block configuration to be read out as data and it wouldn't have to be executed. This would make it easier for a PHP-coded template to be copied into the database for modification, and it would also allow a theme to introspect its templates to find where a given block is used. This would solve the problem currently faced in core with regard to widget sidebars, where we don't know in the theme where a given sidebar is used. If all of the templates were data, then it would be possible to parse them to find out which blocks are used in which templates, and then be able to come up with a URL for a request that would result in a template being chosen that would contain the desired block to view.

ZebulanStanphill · 2018-03-14T18:47:32Z

Forgive me if this has already been asked/answered, and I'm not even sure this is the right place to ask it, but I haven't been able to find any specific info relating to how the following situation would be handled:

I create a template that I use on every instance of a certain kind of post, whether it be a custom post type or a post about a certain thing or whatever - it doesn't matter what post it is, just that it is using the template.

One day, I decide to change the layout of the blocks for those kinds of posts. I change the template... and what happens to the existing posts? Do they automatically change to match the new template? If I have a website with, for example, hundreds of products, and I decide one day that I want to move the gallery block from the left side to the right side of the page, do I have to go in and change every single product?

I guess what I'm asking for is global layouts, without making the specific content (product title, description, the image used, etc.) global. This is kind of similar to the "Selective Sync" feature that Divi Builder modules have, which allows you to set which settings of a module are global and which are specific to each individual instance of the module.

https://www.elegantthemes.com/documentation/divi/divi-library/
https://www.elegantthemes.com/documentation/divi/global-modules/

In the context of Gutenberg, where blocks are basically the equivalent of modules, the closest existing equivalent to the "Selective Sync" feature is making a plugin with a custom block made from one of the existing ones, but with certain settings turned into some kind of global field could work, but that's rather cumbersome and far from user-friendly.

But in this case, what I'm asking for isn't limited to the scope of a single block, but rather the entire post... or if you want to allow for even more freedom (like a section that only exists on a single product), just a section of the post.

If a "Selective Sync" kind of feature was added to global blocks, then the making-changes-to-templates issue could be resolved by having every block of a post nested in one parent block that uses global sync for the order of its children blocks, but not the content of the blocks themselves. But I'm not really sure as to whether or not this is the right way to handle this.

What do you think... is this something that should be implemented in templates? Global blocks? Or something else entirely?

Pre-Gutenberg, you would separate the content/data from the layout by using custom fields to store stuff like the price/description/title/whatever and page template .php files to store the layout of the page and how the content is presented. of course you could still do this in Gutenberg by using blocks that are basically just custom field holders that don't actually render on the page, like what GCF does:
https://wordpress.org/plugins/gutenberg-custom-fields/

However, since Gutenberg is intended to make editing posts more visual, it would be really unfortunate if people using custom post types with a need for standardized layouts (WooCommerce products, for example) to settle for just throwing custom-field-input blocks onto the Gutenberg editor with no relation to the actual visual layout... or else make the editing experience visual but have layouts be stuck to individual posts with no easy way to apply changes to all of them at once.

jasonbahl · 2018-04-09T17:31:26Z

Is it possible to have block templates for Page Templates?

I have some pages that have the need to have "fixed" sections of content, and some flexible "freeform" sections of content.

I would like for a user to select a "Page Template" that hydrates the block UI with the appropriate mix of locked and free-form blocks.

From what I can tell, that's not yet possible, but perhaps I'm missing something?

wpscholar · 2018-04-12T00:57:45Z

I agree wholeheartedly with @jasonbahl. This is a must-have in my opinion.

There is a ticket to this effect here: #3835

Initially, I was thinking it would make sense to add a filter to the gutenberg_editor_scripts_and_styles() function for the $editor_settings variable right before it is passed to JS. This would allow for empty pages with a specific page template to have the block template and locking set as desired. However, it doesn't provide a clean experience when switching templates within (and without leaving) the editor. An optimal solution will ensure that all available templates and their associated block templates and locking settings are all registered and available in the Gutenberg editor so changes can take place immediately after the user changes the page template.

Currently, users are able to switch page templates within the Gutenberg editor, which triggers an EDIT_POST action. When that occurs, we would need to check if the page template was changed. Then, we could update the blocks on the page (assuming we have a good way of registering the block templates and making them accessible to JS). This would be perfect if there are no blocks on the page. However, the problem is when there are pre-existing blocks on the page. What happens to the user's content? What happens if they switch back to the previous template?

We could temporarily store a copy of the blocks in local storage for each page template; that way when the user switches the template back and forth without leaving the page it would allow us to change all the content and blocks without losing their data. I think it is safe to assume that after saving the post and leaving the page the old content can be forgotten, right?

I think it makes sense to store the page template with revisions so that restoring a page will not break the block structure. We don't want a restored revision to return content from a previous page template when the current page template doesn't match and doesn't support that block structure.

At the moment, I see a way to subscribe to the core data store via wp.coreData.default.subscribe() but not to the core/editor data store (which I can observe via the Redux DevTools extension). Is that by design, or am I just missing something? For maximum interoperability between Gutenberg (itself) and third-party Gutenberg blocks/extensions, I am thinking I should be able to subscribe to and dispatch actions to any registered data store.

Allowing this type of access to the data stores would make it possible to implement a custom solution like @greatislander mentioned where the block template could be changed based on the taxonomy term selected (granted you still have the issue of deciding what block template to use when a user selects multiple taxonomy terms). Or it could allow you to change the block template based on the post format, etc.

westonruter · 2018-04-12T21:29:50Z

@wpscholar

At the moment, I see a way to subscribe to the core data store via wp.coreData.default.subscribe() but not to the core/editor data store (which I can observe via the Redux DevTools extension). Is that by design, or am I just missing something?

According to the data docs, there is an example with a comment:

const { subscribe } = wp.data;
const unsubscribe = subscribe( () => {
	// You could use this opportunity to test whether the derived result of a
	// selector has subsequently changed as the result of a state update.
} );

I've taken this to mean that you have to subscribe to changes to the entire state tree for everything and then detect if a part of it has changed. That doesn't seem ideal, but it's what I've done in a recent PR to look at changes to a given post field in the core/editor store, specifically via a handleValidationErrorsStateChange function which is used to monitor changes via wp.data.subscribe( module.handleValidationErrorsStateChange ).

wpscholar · 2018-04-12T21:39:29Z

Thanks @westonruter! I'll take a closer look at this.

jasonbahl · 2018-05-04T21:24:36Z

@wpscholar @westonruter I've got template switching for a project I'm working on. I'm using WPGraphQL, so what I have doesn't make sense for a core Gutenberg merge (unless we do a WPGraphQL core merge as well 😜). . .but might be helpful should Gutenberg core want to provide a way to swap templates as well.

The way I have it working:

Subscribe to the template change
On change, ask the server for the corresponding template
- note: I'm using WPGraphQL here to get the template back, but could be REST if there was an endpoint registered that could return the template
When GraphQL returns the template, use it to replaceBlocks

Here's a Gist of the client side code: https://gist.github.com/jasonbahl/2af7959e5d10c7eb6781fb86c097786e

If it's helpful at all, here's the Logic used to hook into the WPGraphQL Schema to provide the necessary field/args for GraphQL to respond with the template(https://gist.github.com/jasonbahl/d2df4874a9e3c19fd05767c21fa800a1). . .I'll likely make some adjustments here.

Also, one thing I want to add is having the current state of the template saved to post_meta before making the switch. You can see the GraphQL resolver is already setup to return the persisted template, if one exists. Not sure if meta is ideal for this, but will work for my immediate needs.

jasonbahl · 2018-05-07T16:54:00Z

^ Follow up to my last post. The replaceBlocks method doesn't appear to set attributes. So, if you pass:

<!-- wp:oshpd/my-block {"someAttribute":"someValue"} /-->

What you end up with after using that in replaceBlocks is 

Not quite sure what I'm missing and how to replace blocks with attributes set. 🤔

LABCAT · 2018-06-23T02:51:01Z

Is there anyway we could make a user select the page template when a page is first created?

0aveRyan · 2018-09-04T17:16:24Z

While this isn't in scope for the Block Templates API, the final solution should be considerate to potential 3rd party (or Core) UIs for a captive template picker flow akin to Google Docs.

mtias · 2018-10-07T15:58:42Z

Closing this as the extent in which support mattered for phase 1 is in place. Phase 2 will work further on the saving mechanism and the UI for selecting templates.

Levdbas · 2019-01-08T13:46:48Z

Any word if this is going to be addressed in Phase 2? I think a lot of developers of custom websites would really appreciate the blocks template feature. This way pages with a (semi)static layout could be built on top of gutenberg as well, instead of relying on plugins that use meta fields. In my opinion an ideal implementation you should be able to:

predefined blocks for a page template
setup placeholder content in these blocks
make these blocks within this template fixed, movable or a block you can do anything with.
predefined areas in the block template where new blocks could be added as well.

This way we can create complex template structures (with placeholder data) with fixed headers, footers, call-to-action areas, or any other block that is required on a page by design, while we can still add extra blocks to expand these pages.

wpscholar · 2019-01-08T17:36:10Z

I think it would make sense to have both page templates and block templates as dropdowns in the editor. This way page templates can be created by the theme and may control sidebar layouts, etc. while the block templates can be registered by plugins and utilized within any given page template/layout. This would allow us more flexibility with block templates until Gutenberg takes over theming completely.

ataylorme · 2019-01-08T18:08:42Z

@jeremyfelt has a proof of concept plugin for block templates: https://github.com/happyprime/select-editor-template

Levdbas · 2019-01-09T10:33:45Z

I think it would make sense to have both page templates and block templates as dropdowns in the editor. This way page templates can be created by the theme and may control sidebar layouts, etc. while the block templates can be registered by plugins and utilized within any given page template/layout. This would allow us more flexibility with block templates until Gutenberg takes over theming completely.

And in the case you would like to lock block templates to a page template? I know this is somewhat outside the normal way Gutenberg should be utilized i.e. with blocks as plugins, but I do find myself in quite some situations (read: custom themes for clients) where a page template needs to dictate the blocks being placed.

wpscholar · 2019-01-17T14:41:46Z

@Levdbas I think we should have a way to register block templates to different contexts. For example, a theme or plugin could register a block template to be used in a post type, page template, etc. However, if a page template explicitly names a registered block template in the page template's file header, then that would essentially disable the block template selector as the template has basically defined a specific block template as the only one that should be used. Likewise, if a post type explicitly defines a block template in the post type arguments, then that is the only block template that is allowed. However, if a template or post type doesn't explicitly name one, any of the block templates registered would be made available in the appropriate contexts.

I'm thinking we'd have a generic function like register_block_template() that would allow for registration of a block template to specific contexts.

mcsf · 2019-01-23T13:39:16Z

Any word if this is going to be addressed in Phase 2?

@Levdbas: Yes. The extent of the work is yet to be determined, but templates are a focus for this phase. There's a Phase 2 GH project that can be handy to track, as well as the weekly editor chat.

This was referenced Nov 27, 2017

Framework: Bootstrap Block Templates #3668

Merged

Framework: Adding the possibility to lock the editor #3686

Merged

mtias mentioned this issue Nov 29, 2017

Block Setting Templates - Reusable block configurations #2783

Closed

jaswrks mentioned this issue Dec 7, 2017

Suggestion: Block templates in page template header #3835

Closed

3 tasks

benhuson mentioned this issue Dec 19, 2017

Present Blocks outside of post_content #1684

Closed

youknowriad closed this as completed Dec 22, 2017

mtias reopened this Jan 3, 2018

Soean added the [Feature] Templates API Related to API powering block template functionality in the Site Editor label Jan 15, 2018

aduth mentioned this issue Jan 24, 2018

Framework: Add support for dynamic templates #4659

Closed

3 tasks

mtias added this to the Feature Complete milestone Jan 26, 2018

nerrad mentioned this issue Feb 23, 2018

Additional lock options for template_lock option with block templates #5208

Closed

4 tasks

karmatosed mentioned this issue Apr 19, 2018

Consider real-world usage of WordPress to quantify assumptions made across the Gutenberg project #6228

Closed

ZebulanStanphill mentioned this issue Apr 19, 2018

Consider template blocks or semi-global shared blocks #6297

Closed

mboynes mentioned this issue Jul 23, 2018

Free-form regions in block templates #8139

Closed

youknowriad mentioned this issue Aug 6, 2018

Editor Suggestions #8585

Closed

westonruter mentioned this issue Aug 6, 2018

Expose rendered blocks in REST API endpoint for Reusable Blocks #8625

Closed

mtias removed this from the Feature Complete milestone Aug 31, 2018

Levdbas mentioned this issue Sep 1, 2018

Is there a way to predefine a block arrangement? #9529

Closed

mtias mentioned this issue Sep 1, 2018

🖍 A Block Style System #9534

Closed

mtias closed this as completed Oct 7, 2018

mtias mentioned this issue Oct 23, 2018

Request: Select a Custom Template / Post Format with Pre-Determined Blocks in "Posts" #10926

Closed

felixarntz mentioned this issue Sep 22, 2019

Introduce concept of block templates for full site editing #17512

Closed

BE-Webdesign mentioned this issue Jan 26, 2020

Block Template Validation Improvements #19882

Closed

14 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Proposal for Block Templates #3588

Proposal for Block Templates #3588

mtias commented Nov 21, 2017 •

edited

Loading

domtra commented Dec 14, 2017

youknowriad commented Dec 22, 2017

mtias commented Jan 3, 2018

greatislander commented Jan 3, 2018

westonruter commented Jan 16, 2018 •

edited

Loading

ZebulanStanphill commented Mar 14, 2018 •

edited

Loading

jasonbahl commented Apr 9, 2018

wpscholar commented Apr 12, 2018 •

edited

Loading

westonruter commented Apr 12, 2018

wpscholar commented Apr 12, 2018

jasonbahl commented May 4, 2018 •

edited

Loading

jasonbahl commented May 7, 2018

LABCAT commented Jun 23, 2018

0aveRyan commented Sep 4, 2018

mtias commented Oct 7, 2018

Levdbas commented Jan 8, 2019 •

edited

Loading

wpscholar commented Jan 8, 2019

ataylorme commented Jan 8, 2019

Levdbas commented Jan 9, 2019

wpscholar commented Jan 17, 2019 •

edited

Loading

mcsf commented Jan 23, 2019

Proposal for Block Templates #3588

Proposal for Block Templates #3588

Comments

mtias commented Nov 21, 2017 • edited Loading

Uses

Details

Implementation Steps

Tasks

domtra commented Dec 14, 2017

youknowriad commented Dec 22, 2017

mtias commented Jan 3, 2018

greatislander commented Jan 3, 2018

westonruter commented Jan 16, 2018 • edited Loading

ZebulanStanphill commented Mar 14, 2018 • edited Loading

jasonbahl commented Apr 9, 2018

wpscholar commented Apr 12, 2018 • edited Loading

westonruter commented Apr 12, 2018

wpscholar commented Apr 12, 2018

jasonbahl commented May 4, 2018 • edited Loading

jasonbahl commented May 7, 2018

LABCAT commented Jun 23, 2018

0aveRyan commented Sep 4, 2018

mtias commented Oct 7, 2018

Levdbas commented Jan 8, 2019 • edited Loading

wpscholar commented Jan 8, 2019

ataylorme commented Jan 8, 2019

Levdbas commented Jan 9, 2019

wpscholar commented Jan 17, 2019 • edited Loading

mcsf commented Jan 23, 2019

mtias commented Nov 21, 2017 •

edited

Loading

westonruter commented Jan 16, 2018 •

edited

Loading

ZebulanStanphill commented Mar 14, 2018 •

edited

Loading

wpscholar commented Apr 12, 2018 •

edited

Loading

jasonbahl commented May 4, 2018 •

edited

Loading

Levdbas commented Jan 8, 2019 •

edited

Loading

wpscholar commented Jan 17, 2019 •

edited

Loading