Starter Page Templates

[koke]

We are building a template selector for new pages created on the mobile apps. We have already started working on our first version, but I think this could be an interesting feature not just for mobile, but for core as well.

Earlier this year, WordPress.com developed and launched a similar feature, via the full-site-editing plugin (There’s a good walkthrough of the broader project and lessons learned in this comment).

I believe this feature makes sense in Gutenberg/core, and would allow third parties to then offer more templates as an added value.

What we are building on mobile

We are trying to start simple to see if the feature is useful to our users and continue from there.

User flows

Designs by @iamthomasbishop:

Phase 1 MVP (milestone)

When a new page is created:

• Initially we’ll start with two templates available: About and Contact. These will be simplified versions of the existing ones in WordPress.com, with only blocks that are currently supported in the apps. We need to find a way to localize these templates.
• We will be developing new blocks in parallel, so depending on the available blocks we’ll likely ship more and better templates on this stage.
• We expect to have Media & Text (shipping on 13.5), Gallery, Spacer, Group (in progress), Columns, and Button (not started). This would enable all of the templates existing in WordPress.com today except:
  • Contact wouldn’t have a contact form
  • Portfolio would use an image or video block instead of a Youtube embed
  • Blog won’t be available
• The editor will show a list of available templates with a series of buttons.
• These buttons will be visible while the post content is empty. If the user starts creating content, they will disappear.
• When the user taps on one of the templates, we will show a non-editable native preview of the template. The user can dismiss or create a page with this template.
• If the user chooses to create a page with this template, the post content will be replaced with the template and the preview dismissed.

Phase 2

In this stage, we expect to have enough supported blocks to have a better offering of available templates.

• The button list will be scrollable, and have a “••• More” button at the end.
• That button will open a full screen selector with all the available templates.
• The user will be able to switch to a different template from the preview screen.

Phase 3

In this stage, we complete the set of existing templates in WordPress.com and set up the necessary systems to keep them in sync.

• When a new page is created on a WordPress.com site, we offer an API-based set of templates, depending on what’s available for that site.
• We will come up with a process to ensure that the apps continue getting updated templates, while ensuring that we only offer templates with supported features.
• A card will be shown in the page management screen announcing the new feature to users. We will consider adding more hints in the onboarding process or Quick Start.

What this could be in core

I think the main idea of the feature would remain the same. Larger screens would benefit from a different UX, since there is enough room to show a preview alongside the templates list.

But more important than UX, I think the bulk of the extra work for core is making this extensible. We would need new API endpoints to expose these templates. We would need hooks for themes and plugins to define their own templates.

We also need to see how this feature fits in all the existing “template” features:

• The current discussion around block templates in Introduce concept of block templates for full site editing #17512 (which are more like template files).
• The existing API to define templates for Custom Post Types or blocks.

In our MVP I started with About and Contact because they feel the most universal of all templates, but this requires more thought and discussion, as I'm not sure what's the right balance for a set of templates bundled by core.

[retrofox]

It's a very nice feature and it worths the try 👍.
What point that I'd like to suggest is to analyze the previewing performance. Right now the <BlockPreview /> previews just a couple of blocks as maximum. (block styles, live preview in the main inserter).
But for templates, maybe the amount of blocks to preview gets concerning, to the point to make the feature unfeasible.
Take it as simple advice. I don't want to be a killjoy :-D

[koke]

@retrofox thanks for the tip. We don’t plan to use live previews for now, just a modal when the user picks a template. Did you identify what made the previews slow?

[retrofox]

@retrofox thanks for the tip. We don’t plan to use live previews for now, just a modal when the user picks a template. Did you identify what made the previews slow?

Not completely sure why it happens and but it takes the same time to render the blocks into the Editor if I'm not wrong. We're talking about ~2 or ~3 seconds per template depending on how many blocks it has. The problem gets evidence when you have fifteen templates, and twenty-five blocks per each one for instance. Preview all of them increase the time which the process takes.
If I should start to work in the performance, one of a task to I could start to research is a preview mode for each block, getting rid off those elements which are not necessary for the preview (inserter, drop zone, etc) and their functionality.

[kjellr]

Just wanted to note that as @jffng and I have been experimenting with the block-based theme spec over in the theme-experiments repository, we're frequently noticing that we have ideas that will benefit from this concept. Here's a simplified example:

I recently rebuilt the Gutenberg Starter theme to use the new block-templates structure. I'd like to bundle an example layout with it.

My first thought was to bundle this as starter content. This works, but starter content code is a little unwieldy, since it's full of post-content HTML inside of php. Twenty Twenty's Starter content is a good example of this.

To get around that, I thought I'd just have the starter content reference the demo layout as a block template part. This works, but it has two downsides: First, when a user goes to edit the page, the content isn't really there. It's just pulled in from a the file (and currently only displayed with a placeholder, though I know that will change). What I really want is for the content to be imported into the post. The second (and more major) downside is just an inherent problem with starter content: it can really only be pulled in once, when the site is fresh.

This would be much better suited to a "page Template", as described in this ticket. I've been digging around for documentation on adding new templates, but I haven't found anything yet... is it possible for themes to include these at this point? I can see these being really helpful in cases where a theme wants to include some pre-built page layouts to the user.

[jffng]

I also wonder if this could be conceived of as a part of the template creation flow being discussed in #19254

[MichaelArestad]

CC @dwolfe since this relates to the mosaic view.

[mapk]

It appears the UI for displaying the theme templates and generic layout templates is being explored here: #19254 especially with this comment.

Should this issue also remain open?

[MichaelArestad]

@mapk I think so because I'll be exploring the templates themselves here in detail. It'll help focus conversations.

[noahtallen]

I want to mention that semantics around "template" can be weird.

We are building a template selector for new pages created on the mobile apps.

I believe that the "template selector" outlined in the post refers to different options for default page content. E.g. you have several different options to select from for "about pages" or "contact pages". Selecting an option just changes the post_content of that individual page. The feature shipped to WordPress.com contains what we have now started calling "page patterns" to differentiate from FSE template. (FSE templates define the structure of site pages, rather than content).

I like mentioning these semantics when I see conversations about "templates", because it's very easy to mean different things when we say "template" :)

[carolinan]

Is this view with selectable core templates (as compared to files in themes) being considered for the 5.8 MVP?

[chipsnyder]

I'd like to provide an update on how the Starter template flow currently works from the original post. The update UI now follows this flow and sits outside of the Gutenberg Codebase on Mobile and each of the provided templates now includes a live demo URL providing previews of the pages.

The templates are currently pulled from a WordPress.com API however we do have them segmented to provide an endpoint that would be WordPress.org specific.

---

I'll do a brief backscroll and trying to answer some of the more recent questions to the best of my understanding.

@carolinan

Is this view with selectable core templates (as compared to files in themes) being considered for the 5.8 MVP?

The updated UI has been released and the "Starter Page Template" buttons were released briefly but then updated and removed from the mobile UI around Oct/Nov of 2020.

We don't currently have a mechanism for theme developers to add to the starter content but I do like that concept and would be in favor of exploring how we could make that happen if that's of interest.

@noahtallen

I believe that the "template selector" outlined in the post refers to different options for default page content

That is correct the feature in Mobile is about prepopulating the content of the page. Thanks for adding that clarity 👍

[noahtallen]

I've also heard ideas about calling this feature "page patterns," similar to block patterns but for a whole page. I personally think it's a nice distinction from templates.

[anarieldesign]

@koke I think this would be soo useful to have in the core. I created 2 FSE themes so far and also our latest premium theme is made with block patterns and this is exactly what I thought and talked with few people about. It would be great when a user opens a new page, to chose design/page patterns however we called it and it starts editing it right away. Most of the users just want to add a page, choose a layout and start adding their content.

[chipsnyder]

@anarieldesign Thanks for following up with that suggestion ❤️ FYI @koke is currently working on other projects but I'm leading a team that is focused on these Page Patterns/Layouts and will take this request to be reviewed.

[anarieldesign]

@anarieldesign Thanks for following up with that suggestion ❤️ FYI @koke is currently working on other projects but I'm leading a team that is focused on these Page Patterns/Layouts and will take this request to be reviewed.

@chipsnyder that would be great :). Thank you. I'm sure this would be very useful to other theme authors and especially to the users, which's most important. I wanted to open a ticket and suggest if we could make something similar that WordPress.com did but @annezazu shared this ticket with me and so happy you already thought about it. From the user perspective, I think this would be a huge help. Just by opening a new page, having a modal window to choose a design and start to edit it right away is a big step 👍

[digamber89]

Slack brought me here - full page layouts I think is a fantastic idea - that would greatly enhance the usability of blocks.
Theme authors can create great page - designs and instead of creating a block template - would create full page layout patterns - that can be used, there isn't anything blocking block patterns to be used like this now.
But a UI/UX that allowed / distinguished full page patterns sounds better to me.

[mrwweb]

Related: #19907

[youknowriad]

I think we did implement starter templates recently in the site editor. Should we be closing this issue @jorgefilipecosta ?

[youknowriad]

I'm closing this old issue now, let's consider a new issue if there are missing things to the starter templates feature.

[digamber89]

@youknowriad i don't see starter templates anywhere in the 6.3 release can you please let me know where or how starter templates are used

[mrwweb]

@youknowriad I read this issue as being about having starter templates for posts in the block editor (not the site editor). Like @digamber89, I'm not aware of a feature that allows that.

[youknowriad]

In the site editor we have StartTemplateOptions and in the page editor we have StartPageOptions

I'm not entirely sure about the heuristics about how to trigger these modals. I think it's related to the presence of "block patterns" that have some flags in the registration. We may be missing some documentation.

@jorgefilipecosta might know more.

[jorgefilipecosta]

Hi @digamber89 and @mrwweb, as mentioned by @youknowriad, we already have the possibility to have pattterns as a starting point for any post or template.
For a pattern to appear as potential starting content, it must define the blockType property as 'core/post-content' and specify the postTypes where the pattern can initiate content, e.g., postTypes => array('my-custom-post').
If no post type is provided but the pattern indicates it's meant to be post content, the pattern will show up as starting content for pages.

register_block_pattern(
    'my-plugin/about-page',
    array(
        'title'      => __( 'About page', 'my-plugin' ),
        'blockTypes' => array( 'core/post-content' ),
        'content'    => '<!-- wp:paragraph {"backgroundColor":"black","textColor":"white"} -->
        <p class="has-white-color has-black-background-color has-text-color has-background">Write your about page here, feel free to use any block</p>
        <!-- /wp:paragraph -->',
    )
);

Regarding having a starting point for templates, the pattern needs to define the templateTypes where it can be utilized as the starting content:

register_block_pattern(
  'wp-my-theme/404-template-pattern',
  array(
     'title'      => __( '404 Only template pattern', 'wp-my-theme' ),
     'templateTypes' => array( '404' ),
     'content'    => '<!-- wp:paragraph {"align":"center","fontSize":"x-large"} --><p class="has-text-align-center has-x-large-font-size">404 pattern</p><!-- /wp:paragraph -->',
  )
);

This is documented at https://github.com/WordPress/gutenberg/blob/trunk/docs/how-to-guides/curating-the-editor-experience.md#utilizing-patterns.

[digamber89]

Hi @jorgefilipecosta

My thinking wasn't that a pattern would be a starter content. But that users could select predefined pages or pre-build pages. So that they could add the page change the content and continue.

Many plugins and themes do this now but in different guises

Example below:

That way users would be quickly be able to pick and choose different options that a theme developer has envisioned their patterns to be used as.

[mrwweb]

@jorgefilipecosta Wow! This is awesome. Thank you for the clarification. I thought I followed these things, but I had missed this.

I can confirm that either of these will result in a modal pattern selector for a post type.

As a file header in the /patterns/ theme directory:

<?php
/**
 * Title: Pattern Name
 * Slug: prefix/pattern-slug
 * Post Types: post_type_slug
 * Block Types: core/post-content
 * Template Types: single
 */
 ?>

Registering via PHP:

register_block_pattern(
	'prefix/pattern-slug',
	[
		'title' => __( 'Pattern Name', 'textdomain' ),
		'blockTypes' => [ 'core/post-content' ],
		'postTypes' => [ 'post_type_slug' ],
		'templateTypes' => [ 'single' ],
		'content' => '',
	]
);

One potential gotcha: I had previously registered this post type with a template argument to set default blocks on new posts of that post type. With those default blocks set, that seemed to prevent the pattern selector modal from appears (probably because the post didn't appear empty).

Given this, I think closing makes total sense. I appreciate the pointer in the right direction!