Introduce overrides in synced patterns iteration for WP 6.6

[talldan]

For changes to patterns in 6.4/6.5, see #53705
For changes to patterns in 6.7, see #62566
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
• Pattern Overrides: Refactor pattern (wp:block) block to use the block binding editing API
  PR: Pattern overrides: use block binding editing API #60721
• 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
  PR: Add content only descriptions in dropdown menus for patterns and templates #61127
• Improve content-only UI in the block toolbar and the list view
  PR: Add content only descriptions in dropdown menus for patterns and templates #61127
• 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
  PR: Remove IS_GUTENBERG_PLUGIN check to ensure pattern overrides ship in 6.6. #62011
• Pattern Overrides: Initial number of number set (or $ + 2 numbers) disappear from edited Paragraph & Heading Blocks #62347

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)
  • PR: Block Bindings / Pattern Overrides: Prevent normal attribute updates when a __default binding exists #62471
  • PR: Pattern overrides: disallow override for image with caption/href #62747
• Image block: when override added, toolbar shows redundant separator

Button Block

Supported attributes: text, url, rel, linkTarget

• Pattern overrides: Button and Image blocks sharing the same name have incompatible attributes
  • Punted
• Pattern Overrides: Button block left empty in original pattern and used as an override throws an error in pattern instances
  PR: Fix applying bindings or pattern overrides to button blocks with empty text #62220

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

• Improve content-only UI in the block toolbar and the list view
  • Adjust the icons and text of the binding connected blocks #61560
  • Proposal: Add snackbar notification when unlocking content only blocks #61554
• 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/button: 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

[ronalfy]

Just wanted to chime in, but I feel extensibility should be a high concern straight out of the gate.

I’d hate to have to wait until 6.7 to start implementing this on client sites.

[ndiego]

Since Synced Pattern Overrides are intrinsically linked to the Block Bindings API, if new blocks and/or block attributes become supported by the Binding API, will they automatically become available to Synced Pattern Overrides?

[talldan]

Just wanted to chime in, but I feel extensibility should be a high concern straight out of the gate.

@ronalfy It'd be interesting to hear what kind of extensibility you'd like. At the moment the main limitation is that only a subset of block types are supported that can be enabled as overrides.

Since Synced Pattern Overrides are intrinsically linked to the Block Bindings API, if new blocks and/or block attributes become supported by the Binding API, will they automatically become available to Synced Pattern Overrides?

@ndiego Yep, it's not completely automatic, those blocks require some testing, but if they work it's very easy to extend support. In the future though a better opt-in/out system is needed for block bindings.

[colorful-tones]

Can we please attach a Figma file for design considerations around this overall effort? I'm assuming they exist. I'm starting to see quite a bit of new issues tagged Bugs, but it makes one wonder if they're bugs, regressions, or just code discovery?

Here is an example of an Issue labelled as a bug that relates to this feature. If you attempt to follow the breadcrumb trail of pull requests then you’ll yet lost on what is trying to be solved.

Starting here: #62193

As a follow-up to #61560,

and then go to 61560, and see:

Close #61515 and #61547.

And then go to 61515 and 61547, and it keeps going infinitely deeper. 🧶 🫠

Iteration: #59819

and

A follow-up to #61515,

@jasmussen do you know of a particular design artifact that relates to the latest synced pattern overrides user experience? 🤔

[jasmussen]

Where that work was done doesn't come to mind. There isn't always a Figma file attached to some of the work, though I agree it's a best practice, and if you ask for view access to the Figma org, any such work would likely be stored in the "Gutenberg Block Editor" folder.

[talldan]

We're now in the RC phase of 6.6 and everything tracked has been completed or punted, so I'll close this issue. Smaller individual issues are being tracked on the 6.6 project board.

For 6.7, there's a new issue - #62566.