Synced Patterns for Themes

Description

A theme pattern is usually two things at once: a design, and the words that happen
to be sitting in it. Reuse the design and you copy the words with it — so a theme
that wants five hero sections ships five near-identical patterns.

This plugin separates the two. A pattern marks the parts of itself that are meant
to be filled in, and any other pattern — or template, or post — can then use that
design and say what goes in it:

<!-- wp:pattern {"slug":"mytheme/hero","content":{"headline":{"content":"Built for the long haul"}}} /-->

One design pattern. As many uses as you like, each with its own content, all
expressed in theme files.

The content attribute here is not new: it is the same attribute WordPress
already puts on a synced pattern when you edit one of its fields. All this plugin
does is let a theme pattern accept it too.

Marking the parts to fill in

In the design pattern, give each block you want filled a name and mark it as a
slot. This is core’s Pattern Overrides syntax, unchanged:

<!-- wp:heading {"metadata":{"name":"headline","bindings":{"__default":{"source":"core/pattern-overrides"}}}} -->
<h2 class="wp-block-heading">Headline goes here</h2>
<!-- /wp:heading -->


metadata.name names the slot. `__default` opens up every attribute the block

supports, and is the form to reach for: it is the only one WordPress will let
someone type into inside a synced pattern.

Naming attributes one by one instead — {"content":{"source":"core/pattern-overrides"}} —
also works when the content comes from markup, and is worth using when you want
to fill exactly one attribute and leave the rest alone.

Filling them in

Anywhere a pattern can be used, content supplies the values — keyed by slot
name, then by attribute name:

<!-- wp:pattern {"slug":"mytheme/hero","content":{
    "headline": { "content": "Built for the long haul" },
    "photo":    { "url": "…/roof.jpg", "alt": "A tin roof" }
}} /-->

Any slot you leave out keeps the design pattern’s own content, so a pattern’s
defaults double as its documentation.

Keeping a pattern linked

By default a pattern is a starting point: insert it and you get ordinary blocks
you are free to change. Add Synced: yes to a pattern’s header and it behaves
like a synced pattern instead:

<?php
/**
 * Title: Notice
 * Slug: mytheme/notice
 * Synced: yes
 */
?>

Inserting it stores a reference rather than a copy. The design is rendered from
the theme file and cannot be edited on the page — only the content slots can.
Edit the file and every notice on the site changes with it, keeping whatever
content each one was given.

The block toolbar offers Reset, which puts the pattern’s own content back,
and Detach, which breaks the link and leaves ordinary editable blocks with
the instance’s content baked in.

Unlike version 1, nothing is copied into the database to make this work: the
theme file stays the only source of truth.

Slots in a synced pattern have to bind with __default. WordPress renders any
other binding read-only inside an instance — that is its rule, not this
plugin’s.

Where it works

Patterns, templates, template parts, post content, and patterns inside other
patterns, to any depth.

Inserting an ordinary pattern that fills another gives you plain editable blocks
with the right content already in them. Inserting one marked Synced: yes gives
you a live instance instead, still linked to its file.

What can be filled

The blocks and attributes WordPress supports for Pattern Overrides:

• Paragraph and Heading — content
• Image — url, alt, title, id
• Button — text, url, linkTarget, rel
• List Item — content (WordPress 7.1 and later)

The list is core’s, not this plugin’s, so it grows as core’s does.