Search and replace in content

By the end of this page you know how an agent finds text or a CSS class in saved content, how it replaces it in two steps, and how to undo a replacement.

These tools are in the Search and replace in content group. It starts off, and it needs the edit_others_posts and edit_theme_options capabilities. Every post is also checked on its own: a post the account cannot edit is skipped.

What is searched

By default: posts, pages and every other public post type, plus the three types the Site Editor saves: templates, template parts and patterns. Published, scheduled, draft, pending and private content is included. Content in the trash is never touched.

Only content saved in the database can be reached. A template that still comes straight from a theme file has no saved copy. Search those with btm.theme-search instead. See Edit theme files.

A post larger than 1 MB is skipped and counted.

Two modes

• text matches the text anywhere in the saved markup. That includes block settings and URLs. Use it for a phrase, a URL or a piece of markup.
• class matches a whole CSS class name, in HTML class attributes and in a block’s className. Use it to rename or remove a class.

Text mode can match more than you mean. A search for hero also finds it inside a sentence or an image address. Class mode matches hero only where it is a complete class name, never hero-title and never the word in a paragraph. It also changes the HTML and the block’s own setting together, so the block stays valid in the editor.

Class mode is case-sensitive. A class name has no spaces and none of ", ', <, > and &.

Search

btm.content-search returns the posts that match, each with a count and a short excerpt around the first match. Results come in pages. The agent passes nextCursor back as cursor until it comes back as null.

{
  "pattern": "hero-title",
  "mode": "class"
}

Replace is always two steps

1. Dry run

btm.content-replace runs as a dry run unless told otherwise. A dry run writes nothing.

{
  "replacements": [
    { "from": "hero-title", "to": "page-title" }
  ],
  "mode": "class"
}

The result lists each post that would change, with up to three before and after previews, and a token. A post that would be skipped is listed with the reason:

• locked: someone else is editing it.
• no-revisions: its post type keeps no revisions, or fewer than two. It is never written, because there would be no way back.
• too-large: over the size limit.

2. Real run

The agent calls the tool again with dryRun set to false, the token, and the same mode and replacements:

{
  "replacements": [
    { "from": "hero-title", "to": "page-title" }
  ],
  "mode": "class",
  "dryRun": false,
  "token": "<token from the dry run>"
}

The real run writes exactly the posts the dry run listed, and no others. The token works once, for 15 minutes, and only for the account that ran the dry run. With anything else the call is refused:

This token is unknown, expired, already used, belongs to another user, or was issued for a different mode or replacements. Run a new dry run with exactly the mode and replacements you want, then pass its token.

Each post gets an outcome:

• changed: saved exactly as previewed.
• filtered: saved, but WordPress or another plugin altered the content on save. Read the post to check it.
• conflict: the post was edited after the dry run. It was not written. Run a new dry run.
• locked, forbidden, no-revisions: not written, for the reason named.
• failed: not written. The row carries the error.

Undo

Before a post is written, a revision of its current content is saved. The result gives its id as revisionBefore.

• For a post or page: open it in wp-admin and restore that revision under Revisions.
• For a template or template part: use btm.template-restore-revision, or the Site Editor’s revisions.

Good to know

• A real run writes posts one at a time. If it stops part-way, the posts already written stay written, and the token is spent. Run a new dry run for the rest.
• Up to 20 replacements can go in one call. They are applied in order, each on the result of the one before.
• Some plugins store structured data as a post’s content. Text mode can damage it when a replacement changes the length. Leave such post types out, or use class mode.

For a full example that covers theme files and content together, see Rename a CSS class across the theme and saved content.