Trabaja con los datos del builder de forma segura
El builder de POM almacena el contenido editable de las páginas a través del builder incluido y de WordPress. Las integraciones deben ampliar sus interfaces públicas de shortcode y de mapeo, no analizar ni reescribir el contenido del builder como si fuera un formato de datos no documentado.
Registra un componente cuyo código sea de tu propiedad
Registra la función de devolución de llamada del shortcode en WordPress. Añade su mapeo del builder durante la fase de registro normal del builder, cuando la API de mapeo esté disponible.
Mantén estables el nombre del shortcode y los nombres de los parámetros después de su publicación. Las páginas existentes conservan esos nombres en su contenido aunque cambie la etiqueta visible del builder.
Lee y escribe páginas
Usa las API de entradas de WordPress para la propiedad de las páginas, los permisos, el estado, las revisiones y las actualizaciones de contenido. No actualices una entrada únicamente para reemplazar el texto sin formato de un shortcode, salvo que la integración sea propietaria del documento completo y haya validado la transformación.
Para las páginas gestionadas por editores, prefiere un comando de migración que:
- seleccione un sitio explícito y un conjunto reducido de entradas;
- cree o conserve las revisiones;
- analice únicamente el shortcode del que eres propietario;
- deje intactos los atributos desconocidos y el contenido anidado;
- admita una ejecución de prueba;
- informe de los IDs de las entradas modificadas sin exponer contenido privado.
Reglas de mapeo
Un mapeo describe la interfaz del editor; no es una validación del lado del servidor. La función de devolución de llamada del shortcode debe normalizar igualmente los atributos, validar los identificadores, aplicar las reglas de acceso y escapar su salida.
No aceptes funciones de devolución de llamada de PHP arbitrarias, rutas de archivo, identificadores de scripts ni direcciones de destinatarios a través de los parámetros del builder.
Declara contenido traducible
Usa el filtro pom_shortcode_translation_schema desde el arranque de tu plugin o tema. Debe registrarse incluso cuando la interfaz del builder no esté presente. POM Theme declara sus propios módulos mediante este filtro; POM Translate y POM AI leen las mismas declaraciones.
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;
});Usa nombres de shortcode y de parámetros en minúsculas. attributes enumera los atributos de texto. content permite prosa incluida o shortcodes anidados; establécelo en false para cuerpos técnicos. groups asigna un atributo de grupo de parámetros a sus campos de texto secundarios. Los grupos deben contener una matriz JSON de objetos codificada para URL. La codificación de espacios puede usar %20 o +, coincidiendo con los valores de grupo de WPBakery. Solo se traducen los miembros de cadena declarados; los miembros de configuración conservan sus valores, y los grupos con formato incorrecto se conservan.
Las claves omitidas se establecen por defecto en una lista de atributos vacía, content: true, y en un mapa de grupos vacío. Devuelve el registro entrante con tu entrada añadida. Una lista vacía declara explícitamente que un elemento no tiene atributos traducibles. Registra los nombres de parámetros dinámicos después de que sus tipos de contenido asociados estén disponibles.
Declara únicamente texto legible por humanos, incluidas las etiquetas accesibles. Mantén las URLs, IDs, CSS, ajustes de consulta, valores de enumeración y números fuera de las listas de texto. Para los módulos de POM, las marcas translatable del builder se derivan de estas declaraciones, incluidos los campos de grupo individuales. No mantengas una segunda lista en vc_map. Los elementos de terceros sin una declaración compartida conservan sus marcas existentes.
Las declaraciones de POM cubren sus títulos, botones, mensajes de formularios y del buscador, etiquetas de listados, controles accesibles y campos de Timeline. Los encabezados de listados relacionados se resuelven para los tipos de entradas públicas registrados. Los cuerpos de código y de scripts siguen siendo contenido técnico. Las traducciones cubren los valores guardados en la página; las etiquetas predeterminadas de la interfaz continúan usando la localización normal de WordPress.
Después de añadir una declaración, vuelve a escanear las páginas existentes en POM Translate o tradúcelas de nuevo con POM AI. Comprueba que el texto previsto esté disponible, que la configuración permanezca intacta y que la página traducida se represente correctamente. Incluye en esa comprobación componentes anidados, atributos de texto enriquecido con ambos estilos de comillas, texto multilínea y valores de grupo. En POM Translate, usa Generate pending translations → Process all para descubrir campos en las páginas existentes; Translate pending only no descubre campos nuevos.
Verifica la compatibilidad
Crea, edita, duplica, guarda y renderiza el componente en los editores de backend y de frontend. Prueba contenido antiguo sin atributos recién introducidos, la colocación anidada, las páginas traducidas, las revisiones y la ausencia de la dependencia opcional.