El contenido del patrón es HTML con los comentarios que indican bloques: lt!– wp:heading –gt … lt!– /wp:heading –gt. Esto permite que el patrón se inserte como bloques reales.
Usa la función de i18n (wp.i18n.__) para internacionalizar el título y descripción.
Las imágenes o IDs incluidos en el contenido deben existir o se pueden dejar como placeholders es común usar bloques con contenido genérico que el usuario reemplaza.
3. Registrar variaciones de bloques desde JavaScript
Las variaciones permiten ofrecer sabores del mismo bloque con atributos preconfigurados (por ejemplo, un botón de estilo corporativo). Se suelen registrar sobre bloques core (core/button, core/columns, core/quote) u otros bloques registrados por plugins.
Ejemplo: variación para core/button y otra variación para core/columns con innerBlocks definidos.
( function( wp ) {
var registerBlockVariation = wp.blocks.registerBlockVariation
var unregisterBlockVariation = wp.blocks.unregisterBlockVariation
var domReady = wp.domReady
var __ = wp.i18n.__
domReady( function() {
// Variación para core/button: estilo brand
registerBlockVariation( core/button, {
name: brand,
title: __( Botón marca, mi-textdomain ),
attributes: {
className: is-style-brand,
// puedes predefinir other attributes como backgroundColor, textColor, etc.
},
isDefault: false
} )
// Variación para core/columns con 2 columnas preconfiguradas
registerBlockVariation( core/columns, {
name: two-equal,
title: __( Dos columnas iguales, mi-textdomain ),
attributes: {
// no hace falta attributes si se usan innerBlocks
},
innerBlocks: [
[ core/column, { width: 50% } ],
[ core/column, { width: 50% } ]
],
isDefault: false
} )
// Ejemplo: si quieres eliminar una variación registrada por otro plugin o core
// unregisterBlockVariation( core/button, outline )
} )
} )( window.wp )
Notas:
innerBlocks en registerBlockVariation acepta una estructura como la que usan las plantillas: arrays con [blockName, attributes, innerBlocks].
Si necesitas condiciones para mostrar una variación, puedes gestionarlas en tu UI o registrar/desregistrar condicionalmente con lógica JS.
4. Registrar categorías de patrones (si necesitas nuevas)
Las categorías de patrones ayudan a clasificar los patrones en el explorador. Habitualmente se registran en PHP, ya que es un ajuste del servidor y está disponible en todas las cargas. Ejemplo:
lt?php
function mi_plugin_register_pattern_categories() {
if ( function_exists( register_block_pattern_category ) ) {
register_block_pattern_category(
mi-categoria,
array( label => __( Mis patrones, mi-textdomain ) )
)
}
}
add_action( init, mi_plugin_register_pattern_categories )
?gt
Si registras tu patrón JS con categories: [ mi-categoria ], el patrón aparecerá dentro de esa categoría.
5. Buenas prácticas y recomendaciones
Namespacing: Usa prefijos únicos (mi-plugin/, mi_tema/) para evitar colisiones de nombres de patrones y variaciones.
Internacionalización: Usa wp.i18n.__ o wp.i18n._x en los títulos y descripciones JS para que sean traducibles.
Separar contenido y estilos: El patrón debe contener HTML/estructura, pero evita estilos CSS inline excesivos en su lugar, incluye estilos en el tema o en tu plugin para mantener consistencia.
Evitar IDs fijos: No incluyas IDs únicos (por ejemplo, id=123) en content del patrón salvo cuando sea necesario puede provocar duplicados no deseados.
Control de versiones: Si actualizas patrones en producción, ten cuidado: los patrones ya insertados en posts no se actualizan automáticamente.
Compatibilidad: Comprueba las APIs disponibles según la versión mínima de WP en tu plugin maneja feature detection si necesitas ser compatible con versiones muy antiguas.
6. Depuración y pruebas
Habilita la consola del navegador (F12) y revisa errores JS al abrir el editor de bloques.
Utiliza wp.domReady para asegurarte de que las funciones de wp.blocks están disponibles.
Si no ves un patrón, revisa que el script JS realmente se carga (Network tab) y que las dependencias estén satisfechas.
Prueba a llamar unregisterBlockPattern con el identificador para comprobar que puedes eliminarlo también prueba a listar patrones desde la consola con window.wp.blocks ?
Ejemplo completo de flow (PHP JS)
Resumen de pasos para desplegar un patrón/variación desde un plugin:
Registrar categoría de patrones (opcional) en init (PHP).
Encolar script JS en enqueue_block_editor_assets.
En el JS, usar wp.domReady para llamar a registerBlockPattern y registerBlockVariation.
Probar en el editor, hacer ajustes en content, atributos o i18n.
7. Ejemplos avanzados y consideraciones
Patrones dinámicos: si necesitas obtener contenido dinámico (por ejemplo, plantillas con datos de la base de datos), puedes generar el bloque content desde PHP y exponerlo vía REST o localize_script, y luego registrarlo desde JS usando esa cadena HTML. Otra opción es registrar el patrón en PHP directamente con register_block_pattern si el contenido depende del servidor.
Compatibilidad con themes: si tu tema define estilos particulares, documenta las clases que tus patrones usan para que funcionen correctamente en el front-end.
Cómo remover o reemplazar patrones/variaciones de terceros
Para desactivar un patrón ya registrado por otro plugin, usa unregisterBlockPattern con el nombre completo (namespace/slug) en tu JS ejecutado en domReady.
Para desactivar variaciones indeseadas, usa unregisterBlockVariation( blockName, variationName ).
8. Ejemplo final: registrar, desregistrar y versionado
En este ejemplo se registran dos patrones, se desregistra uno existente y se registra una variación además demostramos cómo usar i18n y domReady.
( function( wp ) {
var registerBlockPattern = wp.blocks.registerBlockPattern
var unregisterBlockPattern = wp.blocks.unregisterBlockPattern
var registerBlockVariation = wp.blocks.registerBlockVariation
var unregisterBlockVariation = wp.blocks.unregisterBlockVariation
var domReady = wp.domReady
var __ = wp.i18n.__
domReady( function() {
// Desregistrar un patrón de ejemplo que queremos reemplazar
try {
unregisterBlockPattern( core/old-pattern )
} catch ( e ) {
// ignore si no existe
console.warn( No se pudo desregistrar core/old-pattern:, e )
}
// Registrar patrón nuevo
registerBlockPattern( mi-plugin/hero-oscuro, {
title: __( Hero oscuro, mi-textdomain ),
description: __( Hero con fondo oscuro y botón claro, mi-textdomain ),
categories: [ mi-categoria, featured ],
content:
} )
// Registrar variación de botón
registerBlockVariation( core/button, {
name: ghost,
title: __( Ghost Button, mi-textdomain ),
attributes: { className: is-style-ghost },
isDefault: false
} )
// Ejemplo de cómo desregistrar una variación por nombre
// unregisterBlockVariation( core/button, outline )
} )
} )( window.wp )
Conclusión
Registrar patrones y variaciones desde JavaScript te da flexibilidad para generar, modificar y condicionar el registro en tiempo de ejecución, algo útil cuando tus patrones dependen de parámetros del cliente o de recursos generados por build. Sigue las mejores prácticas de namespacing, i18n y separación de estilos para mantener patrones mantenibles y compatibles. Usa PHP para registrar categorías o generar contenido dinámico del lado del servidor si lo necesitas.
En este tutorial explico, paso a paso y con todo lujo de detalles, cómo registrar patrones (block patterns) y variaciones de bloques (block variations) desde JavaScript en WordPress. Verás ejemplos completos de código para integrarlo en tu plugin o tema, mejores prácticas, cómo organizar categorías y cómo depurarlo en el editor de bloques. Los ejemplos usan la API pública del editor (wp.) para asegurar compatibilidad con instalaciones estándar de Gutenberg/WordPress.
Requisitos
WordPress 5.8 (o una versión que incluya las APIs modernas de bloques).
Acceso para añadir un plugin o modificar el functions.php de un tema hijo.
Familiaridad básica con JavaScript y PHP.
Conocimientos mínimos sobre cómo funcionan los bloques en el editor (markup HTML con comentarios de bloque).
Conceptos clave
Patrón (Block Pattern): fragmentos de contenido compuestos por uno o varios bloques que el usuario puede insertar desde el explorador de patrones.
Variación de bloque (Block Variation): una variante de un bloque existente con atributos, innerBlocks o estilos por defecto.
Categorías de patrones: agrupaciones que ayudan a organizar patrones en el selector del editor.
Nota: Muchos ejemplos en la documentación antigua usan PHP para patrones aquí te muestro cómo hacerlo desde JS para cargar y gestionar patrones dinámicamente o como parte de un build de JS.
Resumen rápido de funciones JS (tabla)
Función
Qué hace
wp.blocks.registerBlockPattern
Registra un patrón nuevo para que aparezca en el explorador de patrones.
wp.blocks.unregisterBlockPattern
Elimina un patrón registrado.
wp.blocks.registerBlockVariation
Registra una variación para un bloque concreto (por ejemplo core/button).
wp.blocks.unregisterBlockVariation
Elimina una variación registrada.
1. Cómo cargar el script JS en el editor
Primero debes encolar tu script para que se ejecute en el editor de bloques. Usa el hook enqueue_block_editor_assets. En el ejemplo asumimos que tu archivo JS se llama editor-patterns.js y está en la carpeta del plugin.
Dependencias: wp-blocks (para registerBlockPattern, registerBlockVariation), wp-dom-ready (asegura que el editor esté listo), wp-i18n (para internacionalización si la usas).
Versionado dinámico con filemtime para evitar caché durante desarrollo.
2. Registrar patrones desde JavaScript
En JS puedes usar wp.domReady para ejecutar el registro una vez que el editor esté listo. El bloque de contenido del patrón suele ser HTML concomentarios de bloque (block comments), exactamente el mismo formato que exporta el editor.
Ejemplo: registro de un patrón simple llamado my-plugin/hero con título, descripción, categorías y contenido HTML.
( function( wp ) {
var registerBlockPattern = wp.blocks.registerBlockPattern
var domReady = wp.domReady
var __ = wp.i18n.__
domReady( function() {
registerBlockPattern( my-plugin/hero, {
title: __( Hero con CTA, mi-textdomain ),
description: __( Sección hero con fondo, título, texto y botón., mi-textdomain ),
categories: [ featured, text ],
keywords: [ hero, llamada a la acción, cta ],
viewportWidth: 1200,
content:
El contenido del patrón es HTML con los comentarios que indican bloques: lt!– wp:heading –gt … lt!– /wp:heading –gt. Esto permite que el patrón se inserte como bloques reales.
Usa la función de i18n (wp.i18n.__) para internacionalizar el título y descripción.
Las imágenes o IDs incluidos en el contenido deben existir o se pueden dejar como placeholders es común usar bloques con contenido genérico que el usuario reemplaza.
3. Registrar variaciones de bloques desde JavaScript
Las variaciones permiten ofrecer sabores del mismo bloque con atributos preconfigurados (por ejemplo, un botón de estilo corporativo). Se suelen registrar sobre bloques core (core/button, core/columns, core/quote) u otros bloques registrados por plugins.
Ejemplo: variación para core/button y otra variación para core/columns con innerBlocks definidos.
( function( wp ) {
var registerBlockVariation = wp.blocks.registerBlockVariation
var unregisterBlockVariation = wp.blocks.unregisterBlockVariation
var domReady = wp.domReady
var __ = wp.i18n.__
domReady( function() {
// Variación para core/button: estilo brand
registerBlockVariation( core/button, {
name: brand,
title: __( Botón marca, mi-textdomain ),
attributes: {
className: is-style-brand,
// puedes predefinir other attributes como backgroundColor, textColor, etc.
},
isDefault: false
} )
// Variación para core/columns con 2 columnas preconfiguradas
registerBlockVariation( core/columns, {
name: two-equal,
title: __( Dos columnas iguales, mi-textdomain ),
attributes: {
// no hace falta attributes si se usan innerBlocks
},
innerBlocks: [
[ core/column, { width: 50% } ],
[ core/column, { width: 50% } ]
],
isDefault: false
} )
// Ejemplo: si quieres eliminar una variación registrada por otro plugin o core
// unregisterBlockVariation( core/button, outline )
} )
} )( window.wp )
Notas:
innerBlocks en registerBlockVariation acepta una estructura como la que usan las plantillas: arrays con [blockName, attributes, innerBlocks].
Si necesitas condiciones para mostrar una variación, puedes gestionarlas en tu UI o registrar/desregistrar condicionalmente con lógica JS.
4. Registrar categorías de patrones (si necesitas nuevas)
Las categorías de patrones ayudan a clasificar los patrones en el explorador. Habitualmente se registran en PHP, ya que es un ajuste del servidor y está disponible en todas las cargas. Ejemplo:
lt?php
function mi_plugin_register_pattern_categories() {
if ( function_exists( register_block_pattern_category ) ) {
register_block_pattern_category(
mi-categoria,
array( label => __( Mis patrones, mi-textdomain ) )
)
}
}
add_action( init, mi_plugin_register_pattern_categories )
?gt
Si registras tu patrón JS con categories: [ mi-categoria ], el patrón aparecerá dentro de esa categoría.
5. Buenas prácticas y recomendaciones
Namespacing: Usa prefijos únicos (mi-plugin/, mi_tema/) para evitar colisiones de nombres de patrones y variaciones.
Internacionalización: Usa wp.i18n.__ o wp.i18n._x en los títulos y descripciones JS para que sean traducibles.
Separar contenido y estilos: El patrón debe contener HTML/estructura, pero evita estilos CSS inline excesivos en su lugar, incluye estilos en el tema o en tu plugin para mantener consistencia.
Evitar IDs fijos: No incluyas IDs únicos (por ejemplo, id=123) en content del patrón salvo cuando sea necesario puede provocar duplicados no deseados.
Control de versiones: Si actualizas patrones en producción, ten cuidado: los patrones ya insertados en posts no se actualizan automáticamente.
Compatibilidad: Comprueba las APIs disponibles según la versión mínima de WP en tu plugin maneja feature detection si necesitas ser compatible con versiones muy antiguas.
6. Depuración y pruebas
Habilita la consola del navegador (F12) y revisa errores JS al abrir el editor de bloques.
Utiliza wp.domReady para asegurarte de que las funciones de wp.blocks están disponibles.
Si no ves un patrón, revisa que el script JS realmente se carga (Network tab) y que las dependencias estén satisfechas.
Prueba a llamar unregisterBlockPattern con el identificador para comprobar que puedes eliminarlo también prueba a listar patrones desde la consola con window.wp.blocks ?
Ejemplo completo de flow (PHP JS)
Resumen de pasos para desplegar un patrón/variación desde un plugin:
Registrar categoría de patrones (opcional) en init (PHP).
Encolar script JS en enqueue_block_editor_assets.
En el JS, usar wp.domReady para llamar a registerBlockPattern y registerBlockVariation.
Probar en el editor, hacer ajustes en content, atributos o i18n.
7. Ejemplos avanzados y consideraciones
Patrones dinámicos: si necesitas obtener contenido dinámico (por ejemplo, plantillas con datos de la base de datos), puedes generar el bloque content desde PHP y exponerlo vía REST o localize_script, y luego registrarlo desde JS usando esa cadena HTML. Otra opción es registrar el patrón en PHP directamente con register_block_pattern si el contenido depende del servidor.
Compatibilidad con themes: si tu tema define estilos particulares, documenta las clases que tus patrones usan para que funcionen correctamente en el front-end.
Cómo remover o reemplazar patrones/variaciones de terceros
Para desactivar un patrón ya registrado por otro plugin, usa unregisterBlockPattern con el nombre completo (namespace/slug) en tu JS ejecutado en domReady.
Para desactivar variaciones indeseadas, usa unregisterBlockVariation( blockName, variationName ).
8. Ejemplo final: registrar, desregistrar y versionado
En este ejemplo se registran dos patrones, se desregistra uno existente y se registra una variación además demostramos cómo usar i18n y domReady.
( function( wp ) {
var registerBlockPattern = wp.blocks.registerBlockPattern
var unregisterBlockPattern = wp.blocks.unregisterBlockPattern
var registerBlockVariation = wp.blocks.registerBlockVariation
var unregisterBlockVariation = wp.blocks.unregisterBlockVariation
var domReady = wp.domReady
var __ = wp.i18n.__
domReady( function() {
// Desregistrar un patrón de ejemplo que queremos reemplazar
try {
unregisterBlockPattern( core/old-pattern )
} catch ( e ) {
// ignore si no existe
console.warn( No se pudo desregistrar core/old-pattern:, e )
}
// Registrar patrón nuevo
registerBlockPattern( mi-plugin/hero-oscuro, {
title: __( Hero oscuro, mi-textdomain ),
description: __( Hero con fondo oscuro y botón claro, mi-textdomain ),
categories: [ mi-categoria, featured ],
content:
} )
// Registrar variación de botón
registerBlockVariation( core/button, {
name: ghost,
title: __( Ghost Button, mi-textdomain ),
attributes: { className: is-style-ghost },
isDefault: false
} )
// Ejemplo de cómo desregistrar una variación por nombre
// unregisterBlockVariation( core/button, outline )
} )
} )( window.wp )
Conclusión
Registrar patrones y variaciones desde JavaScript te da flexibilidad para generar, modificar y condicionar el registro en tiempo de ejecución, algo útil cuando tus patrones dependen de parámetros del cliente o de recursos generados por build. Sigue las mejores prácticas de namespacing, i18n y separación de estilos para mantener patrones mantenibles y compatibles. Usa PHP para registrar categorías o generar contenido dinámico del lado del servidor si lo necesitas.
