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.
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.