Change a heading or button on a WPBakery page

ContentIntermediate~10 min

Before you start

Plugin version 1.12.0 or newer with WPBakery Page Builder active. The WPBakery tools are off until you switch them on; turn on the page read, Update a WPBakery element, and Replace text in a WPBakery page if body copy changes too, plus List revisions and Restore revision for the way back. The agent needs edit access to the page. Design Options and settings that can carry script or raw HTML need a user who may post unfiltered HTML. A site that keeps only one revision per post loses the restore point during the save; an element update then returns reversible_reason, and a text replace gives no sign.

WPBakery splits a page’s words across two places. Running text in a Text Block is the element’s inner content. A Custom Heading’s text, a button’s label and its link are settings stored inside the shortcode’s opening tag. That split is why a generic search and replace either misses a button label or mangles the shortcode around it.

This prompt has the agent check where the words live before it picks the tool.

The prompt
On our [About] page (id [18]) I want the heading [Our story] to read
[How we work], and the button at the bottom to say [See our services]
and link to [/services/].
Read the page with wpbakery-get-page-content and include_structure, and
find both elements. For each, tell me its index, tag and where its words are
stored. Look each tag up with wpbakery-list-elements, and tell me the setting
name that holds the heading text, the button label and the button link, and
whether wpbakery-update-element can write it.
Show me every old value beside the new one and wait for my go. Then change the
settings with wpbakery-update-element, using the index and the tag and
fingerprint from the outline, one element per call, reading the outline again
between calls. If any change is plain body text in a text block instead, use
wpbakery-replace-text for it. Give me the restore_revision_id from each
wpbakery-update-element write. wpbakery-replace-text returns none, so before
it runs, list the page's revisions with list-revisions and note the newest
one, then tell me which revision to restore if I want that change undone.
Read the page back at the end to confirm.

Why this is safe to run

The outline and the settings lookup are reads. The agent finds out which setting holds the words, and whether the tool may write it, before it proposes a change. A link goes in as url, title, target and rel, the form WPBakery’s own link field uses, rather than as a raw encoded string.

Update a WPBakery element is a single-element write. It refuses a stale index or fingerprint, a setting the element does not have or that cannot be written, an already encoded value, and anything that would add or remove an element. Square brackets, percent-encoded brackets and data-* attributes in body text need a user who may post unfiltered HTML, and even then text that would add an element is refused. WPBakery’s own save filter still runs.

When revisions are on, an element update returns restore_revision_id (a text replace does not, so its restore point comes from List revisions) for Restore revision, which now works on WPBakery pages while WPBakery is active. Every tool here starts off, runs as the user you bound the agent to, and is recorded in the Activity Log.

Already connected? Ask your agent for the “change a heading or button on a WPBakery page” recipe, or tell it which words to change, and it runs the same flow on your own site.

How it works

  1. Read the page with its element outline and find the heading, button or text block.
  2. Look up that element's settings to see where WPBakery keeps the words.
  3. Show the old and new value and wait for your approval.
  4. Change a setting with Update a WPBakery element, or body copy with Replace text.
  5. Read the page back and keep the restore_revision_id from each element update. For a Replace text change, find the revision with List revisions.

Questions

Why can't a find-and-replace change my button label?
WPBakery keeps a heading's text or a button's label in the element's settings, inside the shortcode, rather than as body text. Replace text in a WPBakery page refuses a change there because it would alter the element. Update a WPBakery element writes that setting by its name, which is the route this recipe takes.
Does it touch the rest of the page?
No. Only the element's opening tag changes, and for text its inner content. Every other byte of the page stays as it was, and a save that would change other content for this user is refused with nothing saved.
How do I undo it?
When the site keeps revisions, Update a WPBakery element returns restore_revision_id, and Restore revision puts the page back. Replace text in a WPBakery page returns no restore point: find the revision saved just before it with List revisions and restore that one. WPBakery edits are not in the Changes tab.