Skip to content

Introduce overrides in synced patterns iteration for WP 6.6 #59819

@talldan

Description

@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

Block issues

Image Block

Supported attributes: url, id, title, alt

Button Block

Supported attributes: text, url, rel, linkTarget

Heading block

Supported attributes: content
No known issues

Paragraph block

Supported attributes: content
No known issues

Ongoing

Longer term / Stretch Goals

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

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    [Feature] PatternsA collection of blocks that can be synced (previously reusable blocks) or unsynced[Type] IterationScoped iteration of an effort from a tracking issue or overview issue ideally for a major release.

    Type

    No type

    Projects

    Status

    Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions