Start an initial documentation about the block based themes

[youknowriad]

This is a very early document explaining the current state of the block-based themes when you enable the "Full Site Editing" experiment.

Note that everything in that document is subject to change including the APIs themselves and the naming of the different concepts.

[joyously]

This whole concept sounds like a regression.
Why would anyone want to switch to static HTML for things that are better generated dynamically? Why would the user be editing these templates, and possibly changing the HTML that the CSS relies upon?

[mtias]

Why would anyone want to switch to static HTML for things that are better generated dynamically?

This is not static HTML since the blocks themselves are dynamic. There's no significant difference to how a php template currently works with function calls intermixed with markup. (A template could also be expressed as a json file.)

Why would the user be editing these templates, and possibly changing the HTML that the CSS relies upon?

People can already edit them in the "theme editor" in wp-admin. The infrastructure needs to support the equivalent. The actual editing interface is a product and design decision in terms of what is editable and in which ways.

[dennisheiden]

This whole concept sounds like a regression.
Why would anyone want to switch to static HTML for things that are better generated dynamically? Why would the user be editing these templates, and possibly changing the HTML that the CSS relies upon?

As far as I understand the concept, you edit these template files in the backend with Gutenberg instead of working directly in PHP files. You can select different templates like before when editing a post. I don't think this will break CSS, you add styles via block settings not CSS files. I think this will be a more stable approach for styling with complex websites. You don't have to hassle with class dependancies, you just edit the look on spot. Themes could provide global settings or template patterns to ensure a unique style.

In the end, this will make editing for non-dev users easier.

[joyously]

you edit these template files in the backend with Gutenberg instead of working directly in PHP files. You can select different templates like before when editing a post. I don't think this will break CSS, you add styles via block settings not CSS files.

You miss the point of styling a front end page. The CSS depends on the hierarchy of the HTML. If you rearrange things (as blocks), the styles probably won't work right.

In the end, this will make editing for non-dev users easier.

No, it makes it more confusing, to have yet one more way to mess up the front end. If you want a different design, choose a different theme. That's easier.

[ZebulanStanphill]

What's the difference between a template part and a reusable block?

[epiqueras]

What's the difference between a template part and a reusable block?

Template parts can be provided by themes in files and will have a different editing/saving flow in the UI.

[dennisheiden]

@joyously thank you for response, don't get me wrong, I like to talk about your feedback. Feel free to give some examples for your code dependencies.

you edit these template files in the backend with Gutenberg instead of working directly in PHP files. You can select different templates like before when editing a post. I don't think this will break CSS, you add styles via block settings not CSS files.

You miss the point of styling a front end page. The CSS depends on the hierarchy of the HTML. If you rearrange things (as blocks), the styles probably won't work right.

We have a misunderstanding here. I think you mean editing the HTML structure and changing dependencies here which would break CSS IF your rules are depending on HTML structure.
I don't think this will be the case with templates. Sure you can change HTML structure, but why would you? Every template contains header, content and footer. So you are able to do CSS like
footer .block-class

instead of

body > footer > .my-class > .block-class

Moving the block wouldn't change its styling.

Sure you could change the block layout if it's placed in a sidebar instead of the footer,
but the dependency would be very simple:

.sidebar .block-class
footer .block-class

Does that make sense?

In the end, this will make editing for non-dev users easier.

No, it makes it more confusing, to have yet one more way to mess up the front end. If you want a different design, choose a different theme. That's easier.

Do you have a use case? I can't think about changing the theme if I just need a different template for a landingpage besides my other sites. It's easier to clone the main template and change its header or footer for the specific page.

If I want to redesign I wouldn't change the theme either. I would just change the blocks within header, content and footer.

[youknowriad]

Thanks all for your feedback, Let's keep the discussion about the docs here and feel free to join our #core-editor and #themereview channels/meetings on WordPress core slack for the discussions about the concepts themselves This PR just describes what's already experimental in the plugin.

[derekherman]

I don't believe static html driven templating is the answer for regular users and definitely is not for Enterprise. I would expect dynamically rendered blocks inside php files. This should be additive to the current templating engine, not reinvent the entire ecosystem for the sake of making it easier for the Gutenberg team to build.

• Was this discussed somewhere else?
• What is the reasoning behind this approach?
• How is this better than dynamic content?
• How is this a good user experience/editorial workflow?
• Have you done any UX research?

I have so many questions and concerns with this approach. Additionally, this PR has been approved without much discussion in less than a day. Please slow down and discuss this before unilaterally deciding the fate of a third of the internet.

Enterprise has not yet fully adopted Gutenberg because of these kind of changes. We're talking about millions and millions of dollars to rebuild platforms to leverage Gutenberg and yet it keeps breaking backwards compatibility, which is a pillar of the WordPress ecosystem. Without truly considering the needs of those who invest truck loads of money into WordPress we are creating a half baked solution that doesn't provide value to at least 80% of the user base.

I don't think I'm alone in these concerns. This is obviously a contentious feature for many reasons, but in reality something this important deserves more than a single day of review/discussion before being approved.

[mtias]

I don't believe static html driven templating is the answer for regular users and definitely is not for Enterprise.

Me neither! Please, review how it works as this is not static HTML. There is markup in themes .php files, but that doesn't make them static.

Was this discussed somewhere else?

Indeed. See https://make.wordpress.org/core/2019/09/05/defining-content-block-areas/ and #17512 which has references to multiple other threads and discussions.

How is this better than dynamic content?

This is dynamic content. And it's still most definitely served by PHP.

I have so many questions and concerns with this approach.

Please, do raise them. That's what all of this is for.

Additionally, this PR has been approved without much discussion in less than a day. Please slow down and discuss this before unilaterally deciding the fate of a third of the internet.

This seems unnecessarily incendiary; nothing has been unilaterally decided. The discussions about all these topics have been ongoing for quite some time. This document — prefaced with the words “Experimental” means this is just an early implementation that is subject to potential drastic and breaking changes in iterations based on feedback from users, contributors and theme authors — only aims to bring the conversation to more people by synthetizing the important parts.

The final shape of how themes are to declare templates is not finalized. The one shown in the draft can also easily be expressed as:

$single = array(
	array( 'core/site-title', array() ),
	array( 'core/image', array(
		'sizeSlug' => 'large',
	) ),
	array( 'core/group', array(), array(
		array( 'core/post-title', array() ),
		array( 'core/post-content', array() ),
	) ),
	array( 'core/heading', array(
		'content' => 'Footer',
	) ),
);

Which is a shape that has been in the handbook for a really long time.

[youknowriad]

@jffng Good suggestions, I added them.

I don't have much to say about the discussion about the concepts themselves, these are still an ongoing experiment, again make sure to join the weekly meetings and follow the "Full Site Editing" label on Github for the day to day work and discussions.

[derekherman]

I'm not being incendiary, just candid and direct. Comments like the one Nick Halsey made in your make post are never responded to, and the fact that the work has already started before the documentation is exactly what I mean by my comment. You have to research what the users want, not what the team wants to build. Where is your research?

[felixarntz]

FWIW, these are experimental changes and nothing is set in stone here. As @youknowriad said, the documentation in this PR merely documents what the current state of the experiment is.

Regarding the templates being plain HTML files, this is not final either. I'd like to emphasize though that even if this was to be the final approach, it wouldn't mean there would not be place for dynamic functionality. I'd argue that traditional WordPress themes have been mixing logic and templating for way too long. A theming approach like this one would improve this and by that greatly lower the barrier of entry for creating themes. Dynamic functionality would be part of individual blocks which would be available via plugins (block libraries) or the block directory.

[spacedmonkey]

What research was done to reach this approach? Were theme creators, publishers and developers interviewed / polled? If so, can these results be published, as I would love to see the findings.

I feel like the customization is a great for users, but adds a lot of overhead on QA / testing. Being able to put whatever block whereever, means it a block needs to be extremely responsive. If blocks are everywhere, this would need to be controlled and limited, to stop breakable. So limited in fact, that in some cases, would not be better than what we currently have with widgets.

I am also interested in backwards compatiblity here. Will this feature be opt in? How will this be achieved? Is there a migration path for existing themes? How will the current widgets, headers and navigation ( menus ) fit into these new layouts?

[adriacobo]

From my point of view I always thought this integration on the full site editing will be a mix between Gutenberg Blocks and current theme hierarchy. I love the hierarchy and put PHP on my themes then I think the blocks areas on first moment must be implemented like the menus areas or the old widgets area.
A new component on the backEnd will be like "Blocks Areas" and then create all the areas the user need like header, sidebar, footer and assigns then to a place on the theme.

Then on my functions.php I will have something like:

function wp_custom_blockarea() {
  register_block_area('header-area',__( 'Header Area' ));
  register_block_area('footer-area',__( 'Footer Area' ));
  register_block_area('sidebar-area',__( 'Sidebar Area' ));
}
add_action( 'init', 'wpb_custom_new_menu' );

On my header.php, footer.php or sidebar.php I will have something like:
<?php wp_block_area('header-area'); ?>

On this way, to theme developers is fine integate the new areas and users can create block area with the Gutenberg potential.

[dashkevych]

If we'll use html for creating templates, what would be a proper way to use logic (based on the settings from Customizer) in these files? Can we use PHP if/else statements in them?

[earnjam]

I'm a bit late to this, as I've been busy on some other work, but have a couple of comments.

Was this discussed somewhere else?

Indeed. See https://make.wordpress.org/core/2019/09/05/defining-content-block-areas/ and #17512 which has references to multiple other threads and discussions.

I've been looking at a ton of issues and PRs in this repo and searching in Slack all morning and I haven't been able to find anywhere that discusses the decision to use HTML driven templating except here. I'm not necessarily arguing for or against it, but merely supporting the notion @derekherman made that this feels a bit out of the blue. Perhaps I've just not been able to find it though. Can anyone provide any other links to discussions? Seems like it just showed up in #18247

Let's keep the discussion about the docs here and feel free to join our #core-editor and #themereview channels/meetings on WordPress core slack for the discussions about the concepts themselves

Discussions about architectural concepts should be done in a more public place of permanent record that can be easily searched/indexed/referenced. I think an exception to that can be made if they are summarized and cross linked from GitHub, Trac or a Make blog, but Slack is too linear and momentary to be the only source of information. It's hard to find any past discussions there unless you know specifically what you are looking for, and even then it can be difficult. Furthermore, it's unrealistic for people to be expected to keep up with every chat.

That may not be the case here and perhaps all of these discussions are occurring on GitHub Issues/PRs, but I just wanted to reiterate that because it's been a source of consternation in the past with regards to Gutenberg.