Dev Notes for WordPress 5.8

[youknowriad]

https://github.com/WordPress/gutenberg/pulls?q=is%3Apr+is%3Amerged+label%3A%22Needs+Dev+Note%22

Here are all the PRs that need a Dev Note to be written. I tried organizing the PRs in different sections and each section represents a single make/core post.

Please share the dev notes here as comments here or links to shared documents. Please let me know if you're unable to write a note for your PR. The notes should be posted before WP 5.8 RC (June 29), but the sooner, the better.

Global Styles and Global Settings (theme.json)

• A post to introduce the theme.json file and its capabilities is needed. Maybe my own blog post could serve as a base for this post. The labeled PRs related to this are: Rename and stabilize useEditorFeature as useSetting #31587 (we probably miss a number of unlabeled PRs here) Published

Template Mode for classic themes

• Introducing the template mode Allow creating custom block templates in classic themes #30438 cc @youknowriad Published
• iFraming the template mode Iframe the template editor #31375 cc @ellatrix (I wonder if we should have a dedicated dev note for the iframing)

New Block Supports flags and Customizations Options

It seems most PRs introducing these are unlabeled. cc @nosolosw in case you know what new options have been stabilized/introduced during the 5.8 cycle.

• Layout config Add a layout config to the group and theme.json and make alignments declarative #29335 @youknowriad

Widgets Editor

A post about the new widgets editor and how it impacts third-party developers.

Related PRs:

• Add widget id to blocks in the widgets screen #28379 cc @kevin940726 @noisysocks @talldan

Various Block Editor API removals.

• Remove APIs deprecated in WP 5.2 Public API: Remove small APIs deprecated in WordPress 5.2 #30283 @youknowriad
• Remove subheading block Remove the subheading block #29627 @youknowriad

Various new Block Editor APIs

• Abstract block editor configuration @gziolo Published
• Consolidate block registration using registerBlockType Blocks: Deprecate registerBlockTypeFromMetadata in favor of registerBlockType #32030 Blocks: Introduce registerBlockTypeFromMetadata API #30293 @gziolo Published
• Additions to the Block Patterns Registration API Block Patterns: Remove scope from Query patterns and introduce blockTypes #30471 @ntsekouras
• Introduce the "group" prop in BlockControls to normalize block toolbars Cover Block: Normalize the block toolbar #29247 @youknowriad
• resolveSelection function in the data module Data: graduate the __experimentalResolveSelect function to a stable status #28544 @jsnajdr
• Enqueue script and style assets only for blocks present on the page @aristath

Various changes to styling of blocks and editor potentially impacting themes.

I feel there's a number of unlabeled changes here. Let me know what we should include here cc @carolinan @scruffian @aristath @MaggieCabrera @kjellr

• Deprecating the dark theme support flag Dark Theme Support: Allow for theme modifications #28233 @scruffian
• Updated reset Reset all WP Admin styles in the wrapper of the editor styles. #29590

Please update the issue If you think there are other changes that would require a dev note.

Also cc @zzap as documentaion lead.

[MaggieCabrera]

#30804 Comes to mind as a change that can affect block-based themes using the Query block

[youknowriad]

@MaggieCabrera Query block has never been released in Core so maybe we need a post for all new blocks but it's not necessarily something for theme authors I think.

[MaggieCabrera]

@MaggieCabrera Query block has never been released in Core so maybe we need a post for all new blocks but it's not necessarily something for theme authors I think.

If they are using the Query block in their templates they need to change the markup (we've had to do it for some of our themes), but I agree it's not relevant in this case since the block is not in Core yet so forget I mentioned it :D

[oandregal]

― A post to introduce the theme.json file

Probably worth pointing to the existing docs as well, which contains the rationale, examples, and the whole specification. This note can also be useful in explaining how the theme.json values relate to the existing add_theme_support values.

The docs also need to be adapted to highlight which parts are stable and landed in 5.8 and which parts are plugin-only.

― New Block Supports flags and Customizations Options

The new additions also need to be documented in the block supports doc. I compared current 5.8 with what was in the 5.7 line and this is what I see:

• color
  • duotone vs __experimentalDuotone: according to the docs is not clear whether it should be color.duotone or color.__experimentalDuotone. cc @ajlende
  • link: by landing theme.json this has been made stable as now theme authors have a way to target it without the plugin. Can be documented and added in the dev note. The block supports name hasn't changed since we added it but it's only since we ported the elements supports that this works, Update: Use elements mechanism for link color instead of a CSS variable #31524 @jorgefilipecosta
• fontSize, was __experimentalFontSize in 5.7. Changed in Editor: Update WordPress packages to use with WordPress 5.8 wordpress-develop#1176 @gziolo @youknowriad
• lineHeight, was __experimentalLineHeight in 5.7. Changed in Editor: Update WordPress packages to use with WordPress 5.8 wordpress-develop#1176 @gziolo @youknowriad
• spacing
  • margin @stacimc as per Spacing support: Add server-side support for margins #31808
  • padding @youknowriad as per Global Styles: Add padding server-side block support #30332
• __experimentalLayout. Do we need to rename this to layout?

― Should we remove these block supports from core?

I've noticed a few block supports have been ported to core in WordPress/wordpress-develop#1176, such as: __experimentalBorder, __experimentalFontFamily, __experimentalFontStyle, __experimentalFontWeight, __experimentalTextDecoration, __experimentalTextTransform. The corresponding theme.json settings (as well as styles) have not been included. Because not allowed settings are removed and we check for them to decide whether to show the UI for these, these won't work in the editor anyway without the plugin.

However, I wonder if we should remove this code from core?

A plugin could enable them by hooking into the block editor settings filter. The UI for these is not clear yet. And for some, such as border, @aaronrobertshaw had queued up some breaking changes.

[youknowriad]

However, I wonder if we should remove this code from core?

Some core blocks do use these block supports even if they are experimental (not allowed for third-party blocks yet)

[aaronrobertshaw]

The UI for these is not clear yet. And for some, such as border, @aaronrobertshaw had queued up some breaking changes.

There are two PRs specifically relating to the border block support. One to allow non-pixel units and another to allow individual border radius values per corner. These are needed to refine the border support UI before the support gets wider use (#31585).

The PRs updating the border support both currently contain code to handle backwards compatibility so if those approaches are accepted those PRs wouldn't be breaking changes. Still, minimising their exposure before those changes land makes sense to me.

[oandregal]

Some core blocks do use these block supports even if they are experimental (not allowed for third-party blocks yet)

What's the expectation of those block supports I shared? Is it that they work with WordPress 5.8 without the plugin? If so, we need to port more things to theme.json and probably the PRs Aaron shared as well. My understanding was that they didn't.

[youknowriad]

What's the expectation of those block supports I shared? Is it that they work with WordPress 5.8 without the plugin?

I think for me, there are two different things:

• Do we want to allow core blocks to use these feature ? if it's the case, we need to backport the theme.json support for this (to enable/disable).
• Do we want to allow third party core blocks to use these features? If it's the case, we need to backport the theme.json support and stabilize the flag.
• If we still consider breaking changes for any of these, keep them unstable, and don't backport into Core.

[ntsekouras]

Dev note for Additions to the Block Patterns Registration API #30471

Contextual patterns for easier creation and block transformations

We’ve all been there. Staring at a blank page sometimes with an idea of what you want to create and sometimes with a mind as blank as the page. To make the creation process easier there is now a way to suggest patterns based on the block one is working with. This is now implemented for Query block and there are some core patterns to start with.

In addition there is way to suggest pattern transformations that are contextual to the currently selected blocks. So how this is different to the patterns current behaviour? Patterns have some demo content and you have to update that content after insertion. With this feature it's possible to use some patterns and retain some of attributes/content you already have.

So it's for existing blocks!

An important thing to note here is that a pattern transform can result to adding more blocks than the ones currently selected.
You can see this with an example like the below where we have a Quote block but the pattern consist of more blocks:

Quote.mp4

This is the first iteration of the feature that covers most simple blocks (without innerBlocks). A new experimental API has been created where we can mark what block attributes count as content attributes. You can see more details in the PR.

In the long run as this work continues and spreads to more blocks, it will be easier to create content and get inspired without leaving the editor.

Pattern Registration API

if you’re creating your own custom block patterns, there’s a new blockTypes property that will allow your patterns to show up in other contexts like the transform menu. blockTypes property is an array containing the block names.

example

register_block_pattern(
	'heading-example',
	array(
		'title'         => __( 'Black heading' ),
		'categories'    => array( 'text' ),
		'blockTypes'    => array( 'core/heading' ),
		'viewportWidth' => 500,
		'content'       => '<!-- wp:heading {"level":3,"backgroundColor":"black","textColor":"white"} -->
							<h3 class="has-white-color has-black-background-color has-text-color has-background">Demo heading</h3>
							<!-- /wp:heading -->',
	)
);

--props to @annezazu for some of the above content 💯

[dashkevych]

Since 5.8 includes support for Template Mode, would it be possible to include information in notes on how to detect a custom template using PHP?

For example, currently we can use the following conditional tag to detect a template provided by the theme:

is_page_template( 'templates/front-page.php' );

Is it possible to detect a custom template built by the user using Template Mode?

[oandregal]

re: Should we remove these block supports from core?

I took a deeper look at this and discussed with some folks (Riad, Jorge, Miguel, Aaron): these aren't expected to work without the plugin.

As per the code in core: it's fine that it stays there. When the plugin registers the supports it overwrites the core's, so two different implementations can't run at the same time. There's still the possibility that any other plugin activates them. We deem this as no problematic as they're experimental and judge the cost of removing them/syncing with core higher.

From the block supports side, we only need clarification/dev notes for the the ones at "New Block Supports flags and Customizations Options" here.

[zzap]

Hello friends, I come bearing gifts and praises ❤️ Not sure if you hear this often enough but you're all heroes and, personally, I admire your work, dedication and, especially, patience with us who wants more docs.

Now business. We have 3 Trac tickets for Editor component marked for dev note. Reviewing everything in this thread, I believe they're not mentioned (correct me if I'm wrong) but think we could use some info about them in dev notes. These are:

• #50328 - Enqueue script and style assets only for blocks present on the page
• #52920 - Editor: Abstract block editor configuration
• #53233 - Editor: Extend register_block_type to accept the path file or folder with block.json

I have two questions at this point:

1. Will these 3 be covered in already listed dev notes?
2. If answer to the first question is no, is anyone volunteering to write them? (P.S. I have a reputation of bribing docs contributors with cookies, just saying 🤷‍♀️)

Thanks ❤️

[youknowriad]

hi @zzap thanks for highlighting these.

#50328 - Enqueue script and style assets only for blocks present on the page

@aristath would know more, I believe we did a post about it (maybe a dev note in the previous release or something but I'm uncertain). If there are changes in the behavior, a dev note would be needed yes.

#52920 - Editor: Abstract block editor configuration

Good one yes, I'll add to the list cc @gziolo

#53233 Editor: Extend register_block_type to accept the path file or folder with block.json

This one is already covered by: "Consolidate block registration using registerBlockType #32030 #30293"

[gziolo]

I'm planning to provide this week both dev notes @zzap and @youknowriad discussed above 👍🏻

[scruffian]

Dev note for Deprecating the dark theme support flag #28233

Dark theme support is now automatically detected
It is no longer necessary to opt in to dark mode support in the editor if your theme has a dark background. Now Gutenberg will automatically detect whether your site is dark and load the editor in dark mode if necessary. The dark-editor-style theme support can be removed from all themes.

[gziolo]

#53233 - Editor: Extend register_block_type to accept the path file or folder withblock.json

I started a gist with the dev note for changes in Block API since it might get lengthy:

https://gist.github.com/gziolo/cbea77500316a243e445d509ced3c231

[gziolo]

#52920 - Editor: Abstract block editor configuration

I have another gist opened with the dev note for changes related to the block editor configuration and filters used there:

https://gist.github.com/gziolo/a947dc52eb2604c77a0a5b0797b2e781

[mkaz]

Published Template Editor Dev Note. I marked off the item above and linked to the dev note also.

[mkaz]

Published @gziolo new Block Editor APIs for Multiple Admin Screens. I marked off the item above and linked to the dev note.

[mkaz]

Published @gziolo Block API Enhancements and marked the item above with link to the dev note.

[DaisyOlsen]

Published Block supports API updates for WordPress 5.8 - I don't see a corresponding item in the list above to mark complete.

[mkaz]

@nosolosw published Introducing theme.json dev note 👍 marked complete above

[youknowriad]

Block Editor API deprecation and removals

Remove APIs

Keeping deprecated JavaScript APIs around has a cost on performance and bundle size, this means at some point we need to consider removing some of the very old deprecated APIs, especially the ones with low usage. WordPress 5.8 does remove two APIs that were deprecated on WordPress 5.2.

• EditorGlobalKeyboardShortcuts component, this was a component used to define some keyboard shortcuts of the block editor, it was not really meant to be used by third-party developers. We verified that it's not used by any plugin in the repository but if you rely on this component, it should be safe to just replace with VisualEditorGlobalKeyboardShortcuts.
• The hasUploadPermissions selector from the core store. We contacted all the three plugins in the repository that were using this API. If you're still relying on this selector, it can be safely replaced with select( 'core' ).canUser( 'create', 'media' )

Removed blocks

Before WordPress 5.0 and in the very early days of the Gutenberg plugin, we used to have a block called Subheading, this block has never been included in WordPress Core and it was hidden/deprecated very early. We expected its usage to be very small. WordPress 5.8 removes the code of this block meaning that if you open content relying on that block in the editor, it will ask you to fallback to the HTML block instead. We don't expect this to have a noticeable impact on the frontend of your site.

[ellatrix]

This is the proposed dev note for the iframe in the template editor: https://make.wordpress.org/core/?p=89760&preview=1&_ppp=b976a86b78

[mkaz]

@ellatrix That looks good, I do a couple of minor edits and added the proper tags. Feel free to review and publish when ready 👍

@youknowriad The Block Editor API deprecations looks good.

[youknowriad]

@mkaz I also have this dev note that is almost ready https://make.wordpress.org/core/?p=89618&preview=1&_ppp=1f2254d383 it's just missing a potential Gif for the layout options in the sidebar.

I'm AFK the next couple days, so feel free to ship it once you think it's ready.

[mkaz]

I added a GIF and published layout dev note at: https://make.wordpress.org/core/2021/06/29/on-layout-and-content-width-in-wordpress-5-8/

I also published the iframed editor here: https://make.wordpress.org/core/2021/06/29/blocks-in-an-iframed-template-editor/

Both marked complete above 👍

[aristath]

Enqueue script and style assets only for blocks present on the page @aristath

https://make.wordpress.org/core/2021/07/01/block-styles-loading-enhancements-in-wordpress-5-8/

[youknowriad]

The field guide is now published and it seems the latest items here are not that important to require their own dev note, so I'm going to close this temptatively. Thanks all for your work on these dev notes.

[ntsekouras]

Just noting that I don't believe the patterns one has been published: #32365 (comment).

It's perfectly fine if we don't want to, but noting in case it has slipped through the cracks 😄

[youknowriad]

@ntsekouras missed this one, maybe we can do a "Miscellaneous block editor API changes" and include it with some other remaining small ones. WDYT @mkaz

[niklasp]

@youknowriad Please write a dev note for #31375. I am totally lost with styling and hooking into the correct functions now.

[youknowriad]

@niklasp Hi there! I believe the dev note for that PR is this one https://make.wordpress.org/core/2021/06/29/blocks-in-an-iframed-template-editor/