By the end of this page you know how an agent finds and reads the patterns available on your site, and how it creates and changes your own patterns with a way back from every change.
These tools are in the Patterns group. It starts off, and it needs the edit_theme_options capability and an active block theme.
Two kinds of pattern
- Registered patterns come from the theme, from plugins and from WordPress itself. A theme keeps its own as PHP files in its
patterns/folder. - Your own patterns are the ones you create in the editor. WordPress stores each one in the database. A synced pattern stays the same everywhere it is used. A pattern that is not synced is copied into the page when you insert it.
An agent can read both kinds. It can create and change only your own patterns. The theme’s pattern files are PHP, and these tools do not write PHP into a theme.
Find and read
btm.pattern-list lists every pattern with its source, its categories and whether it is synced. The agent can filter by source (user, theme, plugin or core) or by a word in the title. The list is paged, 50 patterns to a page unless the agent asks for another size.
btm.pattern-read returns one pattern’s block markup. A registered pattern is read by its name, one of your own by its id. For your own patterns the result includes a hash, which a later change needs.
Reading first matters. An agent that builds a page from the patterns your theme already has keeps the page consistent with the rest of the site.
Create and change
btm.pattern-create adds a new pattern of your own: a title, the block markup, whether it is synced, and its categories. A new pattern is synced unless the agent says otherwise, and a category that does not exist yet is created.
btm.pattern-update changes one of your own patterns: its title, content, sync setting or categories. The agent sends the hash it read as expectedHash. If the pattern changed in between, the call is refused and the agent reads again. A revision is saved before the change, even when the only change since the last revision is in the spacing.
The hash covers the title, the block markup, the sync setting and the categories. If someone changes any one of them while the agent works, even just the title or a category, the agent’s update, restore or delete is refused, and the agent reads the pattern again.
Changing a synced pattern changes every page that uses it, the same as editing it in the editor.
Go back
btm.pattern-revisionslists a pattern’s saved revisions. Each one has a hash of its block markup, which tells the revisions apart. It is not the hash a change needs.btm.pattern-restore-revisionputs one back. It brings back the revision’s title and content; the sync setting and categories stay as they are. It needsexpectedHash, and the version it replaces is saved as a revision first.btm.pattern-deletemoves one of your own patterns to the trash. It needsexpectedHashtoo. You can restore the pattern from the trash in wp-admin. It never deletes for good: on a site with the trash switched off, the call is refused.
Who may change which pattern
The group’s requirement is checked first. On top of it, every one of your own patterns is checked on its own: the account the agent acts as must be allowed to edit that pattern, and to delete it for btm.pattern-delete. A pattern the account cannot edit is left out of the list, and only counted.
Confirmation
btm.pattern-create, btm.pattern-update, btm.pattern-restore-revision and btm.pattern-delete are marked destructive. A browser agent asks you before running them while Confirm destructive tools is on. A remote client asks in the client. The other three tools are read-only.
Related
- A class name used inside your saved patterns can be renamed across all of them with Search and replace in content.
- Templates that use patterns are covered in Site Editor templates.