Work with builder data safely
POM's builder stores editable page content through the bundled builder and WordPress. Integrations should extend its public shortcode and mapping interfaces, not parse or rewrite builder content as an undocumented data format.
Register a code-owned component
Register the shortcode callback with WordPress. Add its builder mapping during the builder's normal registration phase when the mapping API is available.
Keep the shortcode name and parameter names stable after publication. Existing pages retain those names in their content even if the visible builder label changes.
Read and write pages
Use WordPress post APIs for page ownership, permissions, status, revisions, and content updates. Do not update a post solely to replace raw shortcode text unless the integration owns the complete document and has validated the transformation.
For editor-managed pages, prefer a migration command that:
- selects an explicit site and narrow set of posts;
- creates or preserves revisions;
- parses only the owned shortcode;
- leaves unknown attributes and nested content intact;
- supports a dry run;
- reports changed post IDs without exposing private content.
Mapping rules
A mapping describes the editor interface; it is not server-side validation. The shortcode callback must still normalize attributes, validate identifiers, enforce access rules, and escape its output.
Do not accept arbitrary PHP callbacks, file paths, script handles, or recipient addresses through builder parameters.
Declare translatable content
Use the pom_shortcode_translation_schema filter from your plugin or theme bootstrap. It must be registered even when the builder interface is absent. POM Theme declares its own modules through this filter; POM Translate and POM AI read the same declarations.
add_filter('pom_shortcode_translation_schema', static function (array $schema): array {
$schema['acme_cards'] = [
'attributes' => ['heading', 'button_label'],
'content' => true,
'groups' => ['items' => ['title', 'description']],
];
return $schema;
});Use lowercase shortcode and parameter names. attributes lists textual attributes. content permits enclosed prose or nested shortcodes; set it to false for technical bodies. groups maps a parameter-group attribute to its textual child fields. Groups must contain a URL-encoded JSON array of objects. Space encoding may use %20 or +, matching WPBakery group values. Only declared string members are translated; configuration members retain their values, and malformed groups are preserved.
Omitted keys default to an empty attribute list, content: true, and an empty group map. Return the incoming registry with your entry added. An empty list explicitly declares that an element has no translatable attributes. Register dynamic parameter names after their associated content types are available.
Declare only human-readable text, including accessible labels. Keep URLs, IDs, CSS, query settings, enum values, and numbers outside the text lists. For POM modules, the builder's translatable flags are derived from these declarations, including individual group fields. Do not maintain a second list in vc_map. Third-party elements without a shared declaration retain their existing flags.
POM's declarations cover its titles, buttons, form and finder messages, listing labels, accessible controls, and Timeline fields. Related-listing headings are resolved for registered public post types. Code and script bodies remain technical content. Translations cover values saved in the page; default interface labels continue to use normal WordPress localization.
After adding a declaration, rescan existing pages in POM Translate or translate them again with POM AI. Verify that intended text is available, configuration stays intact, and the translated page renders correctly. Include nested components, rich-text attributes with both quote styles, multiline text, and group values in that check. In POM Translate, use Generate pending translations → Process all to discover fields on existing pages; Translate pending only does not discover new fields.
Verify compatibility
Create, edit, duplicate, save, and render the component in backend and frontend editors. Test old content without newly introduced attributes, nested placement, translated pages, revisions, and the absence of the optional dependency.