W4DEV

Site Editor templates

By the end of this page you know how an agent reads and changes templates and template parts the way the Site Editor stores them, how to go back to an earlier version, and how to write a customised template back into the theme’s files.

These tools are in the Site Editor templates group. It starts off, and it needs the edit_theme_options capability and an active block theme.

Two places a template can live

A block theme ships templates as files, such as templates/single.html. When you change one in the Site Editor and save, WordPress stores your version in the database and uses it instead of the file. The file stays as it was.

The tools in this group work on the database copy, exactly like pressing Save in the Site Editor. The tools in the Theme files group work on the files.

btm.template-list shows both at once. For each template and template part it reports:

  • id, in the form theme//slug, for example twentytwentyfive//header
  • source: theme, plugin or custom
  • hasThemeFile: whether a file exists for it
  • customized: whether a saved database copy currently overrides the file

Read and change

btm.template-read returns the block markup the site uses now, and a hash. Pass version: "theme_file" to read the original file instead, for example to compare the two.

btm.template-update replaces the content. The agent sends the complete new markup and the hash it read as expectedHash. If the template changed in between, the call is refused with a 409:

The template has changed since it was read: expectedHash does not match. Read it again and retry with the new hash.

For a template that so far exists only as a file, the first update creates the customisation that overrides the file. The file itself is not touched.

btm.template-create adds a new template or template part, saved in the database. It fails if the slug already exists.

Create and update also return warnings about the markup: content outside blocks, a template part that does not exist, a pattern that is not registered, or a part that includes itself. Warnings do not block the save.

Content is filtered the way WordPress filters a Site Editor save. For an account without the unfiltered_html capability, markup that is not allowed is removed.

Go back to an earlier version

Every save after the first keeps a revision, the same revisions the Site Editor shows.

  • btm.template-revisions lists them, newest first.
  • btm.template-restore-revision puts one back. The restore is saved as a new revision, so it can be undone as well.

Reset or delete

  • btm.template-reset discards a saved customisation, so the theme’s file is used again. It is the Site Editor’s Reset.
  • btm.template-delete removes a template that exists only in the database. A template that comes from a theme or plugin file cannot be deleted, only reset.

Both move the database copy to the trash. They do not erase it. The result reports recoverable. On a site with the trash switched off (EMPTY_TRASH_DAYS set to 0), WordPress deletes the copy for good, and recoverable is false.

Save a template back into the theme

A site built in the Site Editor has its templates in the database. A theme you ship needs them in its files. btm.template-save-to-theme moves one across:

  1. It writes the saved content into the theme’s templates/ or parts/ folder. With a child theme active, the file goes into the child theme.
  2. It updates theme.json when that is needed to keep the title of a custom template or the area of a template part.
  3. It moves the database copy to the trash, so the file is what the site uses.

This tool writes files, so it needs the Theme files group switched on as well. Without it the call is refused with “Saving to the theme needs the Theme files group switched on in Settings → Block Theme MCP.”

The file writes are recorded as one change set, and any file that is replaced is backed up first. btm.theme-revert-change-set undoes the file changes. It does not bring back the trashed database copy: restore that from the trash.

Good to know

  • Only templates of the active theme can be reached.
  • Template edits made here survive a theme update, because they are stored in the database. Files in a theme you do not maintain are replaced by its updates.
  • A class name inside a saved template is content in the database. To rename it everywhere, use Search and replace in content.

For the file side of the same work, see Edit theme files: change sets, backups and undo.