Introduce overrides in synced patterns iteration for WP 6.6

[talldan]

Succeeds the tracking issue for 6.4/6.5 - #53705
Related discussions: #50456, #57937

---

Top priority

What's needed to ship pattern overrides in WordPress 6.6

General

• Pattern Overrides: Improve the UI clarity for using named overrides
  PR: Refine rename flow for blocks with overrides #60234
  • Follow up: Further simplify overrides flow (PR: Adjust allow pattern overrides UX flow #60769)
  • Follow up: Come up with a way to extract pattern-overrides from the block-editor package (PR: Extract pattern-overrides code from the block-editor package #60887)
• Pattern Overrides: Refactor pattern (wp:block) block to use the block binding editing API
  PR: Pattern overrides: use block binding editing API
• Pattern Overrides: No opt-out mechanism exists for named overrides
  PR: Allow opt-out of pattern overrides #60066, the feature is now opt-in by default.
• Pattern Overrides: individual binding attributes are saved in the pattern markup and don't auto-update
  PR: Use metadata.name only as the hint for pattern overrides #59956, Add __default binding for pattern overrides #60694
• Pattern Overrides: Explore surfacing the pattern 'schema'
  PR: Add content schema to pattern editing view #59977
• Find a way to remove the lock icons that display in List View for a pattern's inner blocks
  Related: Editing post with template preview on, locally overriding pattern content: Align list view UX
  PR: Remove the lock icon in list views for content only blocks #61012, Add content only descriptions in dropdown menus for patterns and templates #61127
• Improve content-only UI in the block toolbar and the list view
  • Add content only descriptions in dropdown menus for patterns and templates #61127
  • Adjust the icons and text of the binding connected blocks #61560
  • Proposal: Add snackbar notification when unlocking content only blocks #61554
• Overrides shouldn't be applicable to unsynced patterns
  PR: Fix blocks in unsynced patterns can enable overrides #61639
• Remove IS_GUTENBERG_PLUGIN code that prevents shipping pattern overrides in core

Block issues

Image Block

Supported attributes: url, id, title, alt

• Adding an image that has a caption set in the media library displays the caption, even when the original pattern has been designed to hide captions. (it disappears after a refresh though)

Button Block

Supported attributes: text, url, rel, linkTarget

• Pattern Overrides: Button block left empty in original pattern and used as an override throws an error in pattern instances

Heading block

Supported attributes: content
No known issues

Paragraph block

Supported attributes: content
No known issues

Ongoing

• Overrides in Sync Patterns: expand block support

Longer term / Stretch Goals

Tasks that may take a little longer, but we can consider starting once 'Top priorities' are finished

• Advancing contentOnly editing
  PR: WIP: Try surfacing content inspector controls for contentOnly inner blocks #60412
• Features like pattern overrides and block bindings have limited control over block UI
• Add support for synced theme patterns (with overrides)
• Come up with a way to extract pattern-override code from the block-editor package #60619

Past discussions and FAQ

All the discussions could be overwhelming and hard to find. This section attempts to list the latest design decisions and frequently asked questions for those interested. This list will be kept up-to-date as we iterate and merge more PRs. Feel free to suggest questions you think are worth documenting!

Quick video walkthrough of the basic functionalities

Kapture.2024-05-13.at.09.50.50.mp4

What is Pattern Overrides?

Pattern Overrides (previously referred to as "Partially Synced Patterns") is a feature that enables individual pattern instances to be overridden. Users can reuse the same pattern in multiple places with different contents. Due to the similarity, this feature is also related to the Block Bindings API. Pattern Overrides is also often seen as a feature to enable Pattern Shuffling.

How does it work, and what it looks like?

Currently, Pattern Overrides relies on Block Renaming API and Block Bindings API under the hood. A block inside a pattern has to opt-in to enable overrides. Once the block is enabled, the markup of the block will contain the metadata.name and metadata.bindings attributes:

<!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"core/pattern-overrides"}},"name":"My Description"}} -->
<p>Editable description</p>
<!-- /wp:paragraph -->

A pattern instance with overridden contents will have the content attribute with the key-value pairs of the block's name and connected attributes.

<!-- wp:block {"ref":126,"content":{"My Description":{"content":"Edited description"}}} /-->

Which blocks and attributes are supported?

We currently maintain a hard-coded list of supported blocks and attributes:

1. core/paragraph: content
2. core/heading: content
3. core/block: text, url, linkTarget, rel
4. core/image: id, url, title, alt
   We plan to support more core blocks and eventually allow the registration of third-party blocks and attributes. We decided to make this list hard-coded for now so that we can iterate more easily with minimum back-compact concerns as we figure out the UX.

Is it possible to only override specific attributes?

Not yet, but the eventual plan is to support that. In the future, we might want to add a UI to specify which attributes to connect to the pattern. We think limiting and maintaining the supported attributes in the first release would be easier.

Why use metadata.name instead of IDs?

We've gone through multiple iterations of this, and we're now trying out metadata.name. The first draft used nanoid to generate a unique ID for each block. The idea was that it's easier to retain the connection when moving and renaming. The fact that it generated a random ID is merely an implementation detail and can be swapped to a human-readable ID generator. The decision to switch to using metadata.name started from #59268 and later explained in #53705 (comment). The idea behind this change was to better match the other work in Block Binding API and potential AI integrations. However, the change also has some side-effects, such as the inability to rename blocks.

Why is Pattern Overrides opt-in?

The users have to enable overrides for each block to opt-in to Pattern Overrides. The concerns of the opposite approach have been shared in multiple comments. Since #60234, this feature is opt-in by default.

Why do you need to name a block to enable Pattern Overrides?

This is a valid UX concern shared multiple times, too. The technical reason is that we use the metadata.name attribute to connect the block to its source. There are other reasons, including defining a "semantic schema" for the block, which is still an early vision.

When can't you rename a block if it enables Pattern Overrides?

If a block is connected to a pattern, it's possible it has already been overridden in an instance. Renaming the block could potentially break the connection, so it's not recommended in that case.

[fabiankaegy]

Thanks for creating this! :) Something I would like to clarify is what our end goal for the feature set of the pattern overrides feature looks like.

Will we ever want to open up the API/UI so that an editor can choose which settings of a block should be able to be overwritten in an instance? Or do we only ever want to opt in / out an entire block with all the fields it supports?

My ideal state would be that I as a pattern author could choose that I want the instance of a heading block to overwrite the content and the text color. But not the background color nor any of the typography/dimension controls.

I know we are not there yet because we cannot easily hide/show individual controls of a block today but as far as I'm aware the block bindings API is looking at ways to make this more composable. @gziolo please correct me if I misunderstood you :)

The reason I'm asking this question now is because I think it will have a great impact on the UI / UX for opting in/out of pattern overrides we choose today.

[SaxonF]

Will we ever want to open up the API/UI so that an editor can choose which settings of a block should be able to be overwritten in an instance? Or do we only ever want to opt in / out an entire block with all the fields it supports?

Can we start with one and work towards the other if needed?

[fabiankaegy]

Will we ever want to open up the API/UI so that an editor can choose which settings of a block should be able to be overwritten in an instance? Or do we only ever want to opt in / out an entire block with all the fields it supports?

Can we start with one and work towards the other if needed?

Yes of course. The reason why I ask it though is that I think the designs we come up with for both the API and the UI should ensure that we don't box ourselves into a corner that would not allow us to choose to expand the feature to override individual attributes instead of the whole block.

[gziolo]

I know we are not there yet because we cannot easily hide/show individual controls of a block today but as far as I'm aware the block bindings API is looking at ways to make this more composable. @gziolo please correct me if I misunderstood you :)

Block Bindings API allows granular control over whether the attribute is connected to the data source, and in cases it is, then it allows the specification of the source. So everything is ready on that side, but the missing piece is the proper UI for Pattern Overrides. The prerequisite would be deciding on how much users should be able to control what can be overridden.

[annezazu]

Updating the title of this (feel free to change) to better reflect adding overrides as a feature to patterns rather than a distinct feature. This has caused confusion with folks thinking we're introducing something brand new rather than something added onto patterns today.

[getdave]

Passing on some feedback from a commenter on YouTube (scroll to comments)

I'm wondering if the following functionality is possible. If you set up a pattern with, say, a heading block, paragraph block and a button block (enable overrides on all of them), is it possible to leave one of these blocks empty on an instance of that pattern and have it completely omit that block from rendering?

So removing the text from the heading block in that instance would have it simply not render on the front end. Currently, it looks like it does output the block HTML on the front end, it's just an empty element that takes with it the margin, padding defined in the source pattern.

I think it's a good point regarding the ability to avoid rendering blocks if their content has been removed in the pattern instance. What do you think?

[talldan]

I think it's a good point regarding the ability to avoid rendering blocks if their content has been removed in the pattern instance. What do you think?

I tested and it doesn't seem to be possible right now, the tags are still left in the post. The paragraph and heading blocks collapse to the point where they don't take up any space though.

It seems like there's a bug with the button block—if you leave the block in the original pattern empty, an inserted pattern will throw an error. I'll make an issue for it.

edit: issue here - #61303