Pro module33 abilities
Breakdance ability reference
Reference for the GoBuildWP Pro 1.12.4 source. Installed schemas and policy remain authoritative.
This Breakdance ability reference covers how an agent reads and rebuilds Breakdance pages, templates, headers, footers, popups and global blocks, and edits the site's design tokens and form submissions. The notes below concentrate on how standalone Breakdance persists that data, because the encoding is unusual and a hand-written postmeta value is enough to make the editor show an empty canvas.
Read-only, write and destructive groups describe the source annotations. They do not establish a minimum safety profile, human approval or undo support. Those controls are separate: check the installed ability, the connected user and the active site policy before calling it. A read can still return sensitive data. These pages are not evidence that every operation passed an end-to-end runtime test.
What Breakdance needs before these load
Breakdance 2.7.0 or newer must be active. The gate reads the __BREAKDANCE_VERSION constant and checks that Breakdance\Data\get_global_option exists, and it steps aside when BREAKDANCE_MODE is set to oxygen, so an Oxygen 6 install gets the Oxygen tools instead. Below the floor, or on an Oxygen site, none of these abilities register. Every call runs GoBuildWP's permission check, which means manage_options (super admin on multisite).
- Minimum (base)
- 2.7.0
WPPILOT_PRO_BREAKDANCE_MIN_VERSION - Breakdance editions
- free, pro
- Agent skills shipped
breakdance-build-page
Two layers of JSON inside _breakdance_data
A page's element tree lives in the _breakdance_data post meta as an envelope, {tree_json_string: "..."}, whose value is itself a JSON string of the tree. Template settings in _breakdance_template_settings are encoded twice as well. The helpers decode both layers on read and write the same double-encoded shape back, because a single-encoded value reads as null in Breakdance and breaks its templates admin. When the meta is missing or fails to decode, the read falls back to a fresh root node with _nextNodeId set to 100.
Before saving, a tree is checked to decode back after encoding: near PHP's JSON depth limit an encode can succeed while the next read fails, which would let a later add wipe the canvas. That case returns bd_invalid_input. After the write, the post cache is cleaned and Breakdance's own generateCacheForPost runs. If that CSS regeneration throws, the save is kept and the call returns a warning that says whether an element failed to render (for example an unconfigured Form Builder) or the cache files could not be written.
Five template post types and name-keyed classes
Templates span breakdance_template, breakdance_header, breakdance_footer, breakdance_popup and breakdance_block (shown as Global Block). Deleting one trashes it by default and does not clean up parentId pointers, ruleGroups values or embedded global blocks that still point at it.
Global classes sit in the breakdance_classes_json_string option and are identified by name, with a type of class or custom for a raw selector; there is no separate id. Variables use variables_json_string and global settings use global_settings_json_string, each written under its own lock so edits to one store do not block the others.
Code Blocks, licence mode and submissions
EssentialElements\CodeBlock is the one element type behind the allow_code_elements flag. Without it, a write that adds or edits one fails with breakdance_code_element_needs_confirmation (HTTP 422, listing up to ten node ids); a set-content tree made of nothing but Code Blocks is refused even with the flag. Check-setup reports licence mode as free or pro together with a detection_source of canonical or fallback, and a fallback free result should be confirmed with the user. Other codes you will see are bd_not_found, bd_write_not_applied and bd_unavailable.
Example Breakdance input: wppilot/breakdance-get-element-tree
This one operation declares the 3 top-level input parameters below in wppilot-pro/includes/wppilot-abilities/wppilot-breakdance/wppilot-get-element-tree.php; post_id is required. Other calls in this module take different arguments. Nested schemas and constraints are not expanded here; the complete live schema a connected client discovers is authoritative.
| Parameter | Type and meaning |
|---|---|
post_idrequired | integer. Id of any post that has a Breakdance canvas. |
depth | integer. How many levels below the root to include. 1 = root + direct children (default). 2 = + grandchildren. -1 = entire tree. 0 = only the root summary. |
max_nodes | integer. Safety cap on the total number of summary rows returned. When the tree has more nodes than `max_nodes`, the response is truncated to the root summary only and `truncated: true` is set so the caller can re-issue with a tighter `depth`. Default 500. |
Representative call sequence
This sequence describes the documented calls and checks to perform. It is not a recorded result from an installed WordPress site. Inspect returned errors and partial results, then verify the saved values and affected output before proceeding.
Add a site-wide announcement header on a Breakdance site.
- 01
wppilot/breakdance-check-setupConfirms the plugin is active above the floor and reports the licence mode and where that answer came from. - 02
wppilot/breakdance-create-templateCreates a breakdance_header post; with no settings passed it has no conditions yet. - 03
wppilot/breakdance-set-contentWrites the header's element tree into _breakdance_data and returns any CSS regeneration warning. - 04
wppilot/breakdance-set-template-conditionsReplaces the header's ruleGroups in _breakdance_template_settings so it applies across the site.
Questions about Breakdance
Can I get a Breakdance form submission back after deleting it?
Usually not. The breakdance_form_res post type does not declare trash support, so the row is removed even when force is false, and the response mode says what happened. Uploaded files are left in the media library.
How many submissions does one list call return?
100 by default, and the limit is clamped to 500. Rows are matched on the _breakdance_form_id meta, and the status filter uses unread, read or any rather than publish or draft.
Breakdance reads
| Ability | What it does |
|---|---|
wppilot/breakdance-check-setupCheck Breakdance Setup | Returns the Breakdance runtime state in one call: plugin availability/version, license mode with its detection source, and separate AI capability/runtime signals. ai.ai_supported reports the Breakdance capability constant; ai.native_ai_surface_loaded reports whether the native MCP/AI ability surface is actually loaded. Use this BEFORE any other Breakdance ability. Every other call is gated on plugin.active && plugin.min_satisfied. license.mode is informative, not a hard gate. A canonical free result comes from Breakdance's initialized runtime. When the fallback reports free, verify the license with the user before avoiding Pro-only elements and features. |
wppilot/breakdance-get-dynamic-data-fieldGet Breakdance Dynamic Data Field | Returns the full configuration of a single dynamic-data field by slug: label, category, subcategory, returnTypes, defaultAttributes, the full controls tree (form-control schema agents need when binding a control to dynamic data), and proOnly. Repeater/group fields with separately registered children also include subfields entries with each child's slug, label, and provider type. Use list-dynamic-data-fields first to discover the slug. |
wppilot/breakdance-get-elementGet Breakdance Element | Returns the full payload of a single Breakdance element by id: type, the full properties blob (every builder control value), parent_id (null for root), child summaries, and child_count. Call get-element-tree first to find the id you want to read, then pass the returned properties (or a subset of its top-level keys) back to edit-element to patch the node. |
wppilot/breakdance-get-element-schemaGet Breakdance Element Schema | Progressive-disclosure schema for a Breakdance element's controls - the content.*, design.* and settings.* property PATHS, each control's TYPE, and (for enum controls) the allowed values - so you can style an element without guessing. Pass type (e.g. EssentialElements\Heading). With no other argument you get a compact GROUP MAP: per tab, each top-level control group with its path prefix and leaf-control count - cheap, never the whole tree. Drill into a group with group (a group slug or dotted path, e.g. spacing or design.typography) or find controls with search to get the leaf rows: path (exactly what add-element/edit-element expect under properties), label, type (unit, color, typography, dropdown, …), value (a shape hint - e.g. a unit is {"number":24,"unit":"px"}), and options (enum values for dropdown/button_bar). The settings tab includes the builder-level per-element settings shared by every element type: CSS classes (settings.advanced.classes), display conditions (settings.conditions.*), and the draft flag (settings.advanced.draft). The exact serialized value of compound controls (typography, …) is best confirmed by setting it once and reading it back with get-element. |
wppilot/breakdance-get-element-treeGet Breakdance Element Tree | Returns the Breakdance element tree (the builder canvas) of any post the builder edits, including templates AND regular pages/posts that have been opened in Breakdance. The response is a nested summary of {id, type, child_count, children} rows. Use depth to control how deep the walk goes: 1 (default) returns the root and its direct children, 2 includes grandchildren, -1 walks the entire tree. Pair with get-element to fetch the full properties blob of a specific node. |
wppilot/breakdance-get-form-submissionGet Breakdance Form Submission | Returns the full payload of a Breakdance form submission by id: id, form_id, the host post_id, submission date, status, fields (the actual submitted values), ip, referer, user_agent, user_id, form_actions (the actions Breakdance ran on submit, with their statuses), and uploads (attachment ids if the form accepted files). |
wppilot/breakdance-get-global-classGet Breakdance Global Class | Returns the full record of a single Breakdance global class identified by name: name, type (class for regular CSS classes or custom for raw selectors), and the entire properties blob (the CSS rules attached to the class). Call list-global-classes first to discover the available name values, and pair with edit-global-class to patch the properties shape returned here. |
wppilot/breakdance-get-global-settingsGet Breakdance Global Settings | Returns the Breakdance Global Styles categories stored inside the native settings envelope. Returned keys are categories like typography, colors, buttons, containers, forms, woocommerce, etc., each one a nested object with the CSS controls the builder UI shows. Pair with edit-global-settings to patch. |
wppilot/breakdance-get-templateGet Breakdance Template | Returns the full Breakdance template payload for a single id: title, post_type, status, modified date, and the entire decoded _breakdance_template_settings JSON (parentId, type slug, ruleGroups, triggers, priority, fallback). Use this when you need the conditions / triggers in full. list-templates only carries summary counts. |
wppilot/breakdance-list-dynamic-data-fieldsList Breakdance Dynamic Data Fields | Lists every dynamic-data source Breakdance can resolve at render time: post fields, site info, ACF/Metabox/JetEngine integration fields, Featured Image, Author, Current User, URL & Query, and so on. Each row is a compact summary: slug (the id used when binding a control to dynamic data), label, category, subcategory, returnTypes (e.g. string, image_url, url), and pro_only. pro_only comes straight from Breakdance's catalogue, whose base field class defaults to true - most integration fields (Meta Box, ACF, …) carry it even when core-adjacent. It gates the builder-UI picker only, NOT front-end rendering; on free-license sites still prefer non-pro fields so the user could recreate the binding in the builder UI. The full controls tree per field is heavy. Use get-dynamic-data-field for that. |
wppilot/breakdance-list-element-typesList Breakdance Element Types | Lists the element types registered in THIS Breakdance install - core EssentialElements, Breakdance Pro, and any third-party add-on - so you can pick a valid type for add-element. Each row is compact: slug (the exact, case-sensitive string add-element expects, e.g. EssentialElements\Heading), label (the editor name, e.g. "Image" for EssentialElements\Image2), and category. The editor resolves elements by exact slug, so casing matters - this is the source of truth for it. Filter with category, namespace, or search to narrow; total is the filtered count, catalogue_total the count in scope before category/namespace/search narrowing (it grows when include_hidden is set). Always-hidden internals (the deprecated "Image V1", the MissingElement placeholder, preset/internal nodes) are omitted by default - pass include_hidden=true to include them. The heavy per-element control/property schema is NOT returned here: add the element once and read it back with get-element to inspect its property shape. |
wppilot/breakdance-list-form-submissionsList Breakdance Form Submissions | Lists Breakdance-owned rows from the form-submissions CPT (breakdance_form_res). Oxygen and standalone Breakdance are mutually exclusive at runtime; the _breakdance_form_id marker only prevents residual or imported foreign rows from being exposed. Each row carries id, the source form_id, the host post_id (page that hosted the form), submission date, status, IP, referer, and the count of fields. Filter by form_id to scope to a single form. Use get-form-submission to read the full field values. |
wppilot/breakdance-list-global-classesList Breakdance Global Classes | Lists every Breakdance global class (reusable CSS class) defined for the project. Each row is a compact summary: name (used as the id), type (class for normal CSS classes, custom for custom selectors), and property_count. To inspect the full properties blob of a specific class call get-global-class. |
wppilot/breakdance-list-template-conditionsList Breakdance Template Conditions | Returns the catalogue of conditions a Breakdance template (or header/footer/popup) can use to scope visibility. The catalogue is CPT-specific: breakdance_template exposes the single, archive, 404, search shape while breakdance_header / _footer / _popup additionally surface the "Everywhere" pseudo-rule. Each row is a {slug, label, values, ...} record sourced live from Breakdance\Themeless\getConditionsWithValuesForPostType, the same source the admin SPA uses. Use the slug field as the ruleCategorySlug / ruleSlug value when composing a payload for set-template-conditions. The response also includes template_types: the registered values valid for a template's type field (set via create-template / edit-template). Each is {slug, label, category}; for a single template targeting a custom post type the slug IS that post type's slug (e.g. location), alongside generic types like all-singles, archive types, 404, search, front_page. |
wppilot/breakdance-list-templatesList Breakdance Templates | Lists Breakdance "template-like" posts across the five CPTs the builder ships (breakdance_template, breakdance_header, breakdance_footer, breakdance_popup, breakdance_block). Each row is a compact summary: id, title, post_type + friendly label, status, modified date, the template settings type slug (e.g. single, archive), the priority value, and the number of rule groups currently attached. Use post_type to scope (e.g. only headers) and limit to keep the response small. |
wppilot/breakdance-list-variablesList Breakdance Variables | Lists every Breakdance design variable (custom property the builder generates into CSS vars). Each variable returns the full shape: id, cssVariableName, label, type, collection, value and dynamicData. The response also includes collections, the user-defined groupings variables belong to (e.g. "colors", "spacing"). Variables are stored as a single JSON blob option, so this call decodes the whole table on every read; it remains cheap because the option is small. |
Destructive Breakdance calls
| Ability | What it does |
|---|---|
wppilot/breakdance-add-elementAdd Breakdance Element | Inserts a new element into the Breakdance element tree of a post. The raw EssentialElements\CodeBlock element is gated and rejected unless the user explicitly confirms it and the re-call sets allow_code_elements:true; prefer native Breakdance elements. parent_id is the id of the element that will contain the new node (use 1 for the root). type is the Breakdance element type slug, e.g. EssentialElements\Section, EssentialElements\Heading, EssentialElements\Text, EssentialElements\Image2 (the modern image - the bare Image is the deprecated "Image V1"). Slugs are case-sensitive PascalCase: type is resolved against Breakdance's live element registry, so a wrong-cased slug is normalised to the registered one and a genuinely unknown type is rejected with the nearest match (call wppilot/breakdance-list-element-types to discover valid slugs). Optional properties is the element-type-specific blob (same shape as get-element returns). position is the zero-based index inside the parent's children array (omit to append at the end). The new id is allocated from the tree's monotonic _nextNodeId counter, matching Breakdance's own builder. |
wppilot/breakdance-create-global-classCreate Breakdance Global Class | Creates a new Breakdance global class. name is required and acts as the unique id; pick something CSS-safe (lowercase, dashes). type defaults to class; use custom for custom selectors. properties is the CSS rule tree the class applies (same shape as element properties); omit to start with an empty class you fill later via edit-global-class. |
wppilot/breakdance-create-templateCreate Breakdance Template | Creates a new Breakdance template post under one of the five CPTs. post_type is required and must be one of breakdance_template, breakdance_header, breakdance_footer, breakdance_popup, breakdance_block. title is required. Optional settings is the _breakdance_template_settings JSON object (leave it out and the post is created without conditions, use set-template-conditions later). Element-tree content (the builder canvas) is NOT created here. Pair this with the element-tree abilities (breakdance-add-element, breakdance-get-element-tree) or open the template in the Breakdance editor. |
wppilot/breakdance-create-variableCreate Breakdance Variable | Creates a new Breakdance design variable. Required: label (human-readable name, e.g. "Brand Primary"), value (the literal value, color hex, length, etc.), type (Breakdance variable kind, e.g. "color", "size", "typography"). Optional: id (defaults to a slug derived from label), cssVariableName (defaults to a slug too), collection (group the variable belongs to). The variable is appended to the global variables JSON blob and the response returns the full new variable. |
wppilot/breakdance-delete-elementDelete Breakdance Element | Removes an element from the Breakdance element tree, along with its entire subtree (every descendant). Deletion is immediate and there is no trash for canvas nodes; the change ledger records the post first, so wppilot/rollback-change can put the whole post back. The root (id 1) cannot be deleted; to clear a whole canvas use breakdance-set-content with elements: [], which keeps the storage format intact. |
wppilot/breakdance-delete-form-submissionDelete Breakdance Form Submission | Deletes a Breakdance form submission. The breakdance_form_res CPT does not declare WordPress trash support, so even with force=false the submission is permanently removed at the WordPress layer. The response mode reflects what actually happened: trashed when WordPress kept the trash row, force_deleted when the row is gone. Uploads attached to the submission are NOT cleaned up; Breakdance treats those as separate media items. |
wppilot/breakdance-delete-global-classDelete Breakdance Global Class | Removes a Breakdance global class by name. Deletion is immediate. A retained ledger before-image can restore the captured class store, including later edits to it. Elements that referenced the class continue to carry its name in their properties; they simply lose the styles the class provided. |
wppilot/breakdance-delete-templateDelete Breakdance Template | Removes a Breakdance template. Default behaviour: trash (recoverable from the WP admin trash bin for each of the five template CPTs). Pass force=true to hard-delete (irrecoverable). Use trash whenever possible, a trashed template can also be restored through restore-post where its generic post-type and permission gates allow, or through a supported retained ledger before-image. Deletion does NOT cascade-clean references to this template id from OTHER templates: parentId pointers in child templates, ruleGroups rules whose value matches this id, and _breakdance_data element trees that embed a now-deleted global block all stay as dangling pointers (silently broken). Inspect dependents with list-templates and get-template before force-deleting. |
wppilot/breakdance-delete-variableDelete Breakdance Variable | Removes a Breakdance design variable by id. Deletion is immediate. A retained ledger before-image can restore the captured variable stores, including later edits to those stores. Any element using the variable continues to reference its CSS variable name. Breakdance falls back to the literal value at render time, but new edits will see the variable as missing. |
wppilot/breakdance-edit-elementEdit Breakdance Element | Patches the properties or registered type of an existing Breakdance element. Editing an existing raw EssentialElements\CodeBlock, or changing another element into one, is gated and rejected unless the user explicitly confirms it and the re-call sets allow_code_elements:true. Merge semantics apply on the top level of properties: keys you pass replace the corresponding key on the stored element, keys you omit are kept as-is. To wipe a key, pass null. |
wppilot/breakdance-edit-global-classEdit Breakdance Global Class | Patches an existing Breakdance global class. Identified by name; the name itself is immutable here (delete + create to rename). properties is shallow-merged on top of the stored properties: keys you pass replace the corresponding key, keys you omit are preserved, pass null to wipe a key. type can be changed if needed. |
wppilot/breakdance-edit-global-settingsEdit Breakdance Global Settings | Patches categories inside Breakdance's native settings envelope with shallow merge semantics. Category keys you pass replace the stored value for that section; keys you omit are preserved; pass null to wipe a section. The replacement is *not* deep: if you patch typography, the entire typography sub-tree is overwritten with what you pass, not deep-merged. To partially patch a section, call get-global-settings with section, modify the returned object, then pass the whole sub-object back here. |
wppilot/breakdance-edit-templateEdit Breakdance Template | Patches an existing Breakdance template. Merge semantics on settings: only the top-level keys you pass are updated, omitted keys keep their current value (so you can patch priority without touching ruleGroups). title and status are routed through wp_update_post. To replace the conditions wholesale use set-template-conditions instead. This ability is for everything that is NOT conditions. |
wppilot/breakdance-edit-variableEdit Breakdance Variable | Updates an existing Breakdance design variable identified by id. Use list-variables first to discover the id. Only the fields you pass are touched, omitted fields are kept as-is. id itself is immutable; to rename a variable, delete-variable then create-variable. label, type and cssVariableName cannot be set to empty strings, and cssVariableName must remain unique across the project (collisions are rejected). |
wppilot/breakdance-move-elementMove Breakdance Element | Relocates an element (and its entire subtree) inside the Breakdance canvas. new_parent_id may be the same as the current parent; in that case only position (the zero-based index inside the new parent's children array) is updated. Omitting position appends to the end. Moving an element under one of its own descendants is rejected. |
wppilot/breakdance-set-contentSet Breakdance Content | Replaces the entire Breakdance element tree of a post in one atomic write. A tree containing raw EssentialElements\CodeBlock elements is gated and rejected unless the user explicitly confirms it and the re-call sets allow_code_elements:true; a tree whose content consists only of Code Blocks is always rejected even with that flag. elements is a NESTED list of the page's top-level elements (the children of the root); each node is {type, properties?, children?}. Node ids are allocated automatically from the tree's monotonic counter - do not supply them. Every type is resolved against Breakdance's live element registry: a wrong-cased slug is normalised to the canonical registered slug and reported in warnings, while a genuinely unknown type aborts the whole write with a suggestion. Storage is handled correctly, so prefer this over hand-writing postmeta. Use this to lay down or fully replace a page; use add-element / edit-element / move-element / delete-element for small incremental edits. Passing elements: [] clears the canvas. |
wppilot/breakdance-set-template-conditionsSet Breakdance Template Conditions | Writes the ruleGroups field onto an existing Breakdance template's _breakdance_template_settings. ruleGroups is a list of OR-groups: each top-level entry is itself a list of AND-rules. A rule is {operand: "is"|"is_not", ruleCategorySlug?: string, ruleSlug?: string, ruleDynamic?: string, value?: string|string[]}. The whole bucket is replaced wholesale: pass the COMPLETE list, or [] to clear it. Always validate rule slugs against list-template-conditions BEFORE calling this; unknown rules are stored verbatim and silently never match. Other settings (type, priority, triggers, fallback) are untouched; use edit-template for those. |
For the task-level view of Breakdance, with worked requests and what to check afterwards, see Breakdance integration page.