Desarrollo WordPress personalizado en Barcelona

Bloques de Gutenberg propios para que un equipo editorial publique sin romper el diseño: block.json, patrones, plantillas bloqueadas, Block Bindings y deprecaciones, según el manual oficial del editor de bloques.

Desarrollo WordPress personalizado

Mi lugar en la comunidad WordPress

  • Tengo cuenta en wordpress.org desde 2006.
  • He contribuido al núcleo de WordPress en las versiones 7.0 y 7.1.
  • Mantengo 30 plugins en wordpress.org.
  • Organizo WordCamps y hablo en ellos como ponente.
  • He asistido a todas las WordCamp Europe de 2017 a 2026.
  • Meetup local de WordPress: WordPress Barcelona

Mi perfil en WordPress.org

Una redacción no necesita un constructor de páginas con cien opciones. Necesita poder publicar el artículo de hoy sin que la cabecera, la cita o la ficha de autor salgan distintas cada vez. En WordPress eso se resuelve con el editor de bloques: unos pocos bloques propios, patrones y plantillas que fijan lo que se puede cambiar y lo que no. Soy Mariusz Szatkowski, trabajo con WordPress desde 2006 y construyo estos conjuntos de bloques a distancia y por escrito para equipos de Barcelona. Esta página explica cómo se montan y qué decisiones conviene tomar antes de programar nada. Todo lo técnico procede del manual del editor de bloques de WordPress.

Bóveda del puente del carrer del Bisbe, Barcelona

Foto: Jordiferrer, CC BY-SA 4.0, Wikimedia Commons.

#Bloque, patrón o plantilla: tres herramientas distintas

Antes de escribir una línea de código conviene repartir cada pieza editorial entre tres herramientas que se confunden a menudo.

  • Patrón: una combinación de bloques del núcleo, con contenido de ejemplo, que el equipo inserta desde la pestaña de patrones. No lleva lógica propia.
  • Plantilla de tipo de contenido: los bloques con los que arranca cada entrada nueva de ese tipo, con la opción de bloquearlos.
  • Bloque propio: una pieza con atributos estructurados, con su propio panel de ajustes o con datos que salen del servidor.

La regla práctica: si una pieza se puede montar con bloques del núcleo, es un patrón. Un bloque propio solo compensa si hay algo que el núcleo no sabe hacer. Cada bloque propio es código que alguien mantiene durante años, así que prefiero entregarte menos bloques y más patrones.

#Registrar el bloque con block.json

Desde WordPress 5.8 el manual recomienda block.json como forma canónica de registrar un tipo de bloque, tanto en PHP como en JavaScript. Ese archivo declara el nombre, el título, la categoría, los atributos, las opciones de supports y los recursos del bloque. Tiene tres ventajas prácticas para una redacción.

  • Carga selectiva: si el tema admite la carga diferida de recursos, los estilos y scripts de style y viewScript solo se cargan en las páginas donde el bloque aparece.
  • Esquema: con la línea $schema los editores de código ofrecen autocompletado y validación del archivo.
  • Directorio de plugins: el directorio de WordPress.org detecta los bloques que declaran block.json.

Los recursos del editor (editorScript, editorStyle) y los de la web pública (viewScript, viewStyle) se declaran por separado. El manual distingue además viewScript de viewScriptModule, disponible desde WordPress 6.5: los scripts de WordPress y los módulos no son compatibles entre sí, y los módulos son los que usa la API de Interactividad. Para un bloque editorial sin comportamiento en el navegador, nada de esto hace falta.

#El nombre del bloque no se puede cambiar gratis

El manual de registro lo advierte expresamente: el nombre se guarda en el contenido de cada entrada que usa el bloque, como en el comentario <!-- wp:mi-plugin/ficha -->. Cambiarlo después obliga a editar todas esas entradas o a ejecutar scripts sobre la base de datos. El mismo manual recomienda un espacio de nombres que lleve el nombre real del plugin y desaconseja los genéricos como editorial/ o create-block/. Para un archivo con años de artículos, este es el primer detalle que fijo por escrito.

#Estático o dinámico: dónde se genera el HTML

Un bloque estático guarda su HTML en la base de datos. Un bloque dinámico guarda solo sus atributos y genera el HTML en PHP cada vez que se pide la página. Con block.json basta la propiedad render, disponible desde WordPress 6.1, que apunta a un archivo PHP. Ese archivo recibe $attributes, $content y $block. El manual da este ejemplo mínimo, que escapa la salida:

<div <?php echo get_block_wrapper_attributes(); ?>>
    <?php echo esc_html( $attributes['label'] ); ?>
</div>

Para una redacción esa elección importa por el archivo. Si el marcado de un bloque estático cambia, los artículos antiguos hay que migrarlos (siguiente apartado). Un bloque dinámico puede cambiar de aspecto sin tocar el contenido guardado, porque la base de datos solo guarda los atributos. El archivo render.php se carga una vez por cada instancia del bloque en la página, así que el manual recomienda no declarar funciones o clases dentro de él y sacar la lógica compartida a otro archivo.

#Dónde puede ir cada bloque

Block.json permite limitar dónde se inserta un bloque, y eso evita montajes que nadie quería:

  • parent: el bloque solo se ofrece dentro de los bloques indicados, como hijo directo.
  • ancestor: igual, pero en cualquier nivel del subárbol (desde WordPress 6.0).
  • allowedBlocks: qué bloques pueden ser hijos directos de este (desde WordPress 6.5).

Con eso una ficha de autor puede existir solo dentro del bloque de artículo, y un bloque de cita solo admite los hijos que tú decidas. Los bloques styles ofrecen variantes visuales como clases CSS del contenedor, y variations permite insertar el mismo bloque con atributos iniciales distintos. En un equipo que publica sin diseñador, dos o tres variantes cerradas valen más que un selector de colores libre.

#Plantillas bloqueadas para cada tipo de contenido

Un tipo de contenido (entrada, reportaje, ficha) puede registrar una plantilla con los bloques con los que arranca cada documento nuevo, con atributos y textos de ayuda. La propiedad template_lock fija hasta dónde puede tocar el equipo:

ValorEfecto según el manual
contentOnlyImpide todas las operaciones; solo se edita el contenido de los bloques.
allNo se puede insertar, mover ni borrar bloques.
insertNo se puede insertar ni quitar bloques, pero sí moverlos.

El bloqueo también se hereda en los bloques anidados y existe a nivel de un solo bloque con el atributo lock (move, remove). Un truco que el propio manual muestra es bloquear toda la plantilla y dejar libre un solo párrafo para el cuerpo del texto. Con eso la entradilla, la cita y la caja de datos quedan donde deben, y la redacción escribe en el hueco que le corresponde.

#Patrones registrados desde el plugin

Un patrón se registra con register_block_pattern() desde un gancho init. El manual lista las propiedades que más me sirven en una redacción:

  • blockTypes: asocia el patrón a un bloque, de modo que aparece como transformación posible.
  • postTypes: restringe el patrón a ciertos tipos de contenido, y fuera de ellos no se ofrece.
  • categories: agrupa los patrones en el insertador, con categorías registradas aparte.
  • inserter: con false el patrón no se muestra y solo se usa por código.

Así el equipo de un tipo de contenido ve solo los patrones de su sección, con nombres que reconocen, y no una lista mezclada de todo lo que existe en el sitio.

#Datos de la ficha: Block Bindings

Muchos artículos repiten datos que no son texto libre: la fuente, la fecha de un evento, el nombre de un ponente. Lo más limpio es guardarlos como campos personalizados y mostrarlos con Block Bindings, una API disponible desde WordPress 6.5 que enlaza un atributo del bloque con una fuente de datos. La fuente core/post-meta exige que el campo se registre con show_in_rest y que su clave no empiece por guion bajo. Funciona con atributos concretos de bloques del núcleo: por ejemplo el contenido de un párrafo o de un encabezado, o la URL y el texto de un botón. Si el dato cambia en el campo, cambia en todos los lugares donde se muestra.

Otra fuente que trae el núcleo, core/pattern-overrides, permite que un patrón sincronizado deje editables solo ciertos bloques en cada instancia. Sirve para una ficha común con un único campo que varía.

#Cambiar un bloque sin romper el archivo

Cuando cambia el HTML que guarda un bloque estático, cada artículo publicado con la versión anterior deja de coincidir con lo que el bloque espera, y el editor lo marca como no válido. El manual de deprecación ofrece dos salidas: crear un bloque nuevo con otro nombre o añadir una entrada a la propiedad deprecated del bloque.

Los detalles que más importan:

  • Cada entrada de deprecated lleva sus propios attributes, supports y save: no heredan de la versión actual.
  • La función migrate recibe los atributos antiguos y devuelve los nuevos.
  • No funciona como una cadena de migraciones de base de datos: se usa la primera versión cuyo save produce un bloque válido.
  • Las versiones se ordenan de la más reciente a la más antigua.
  • Si el save de una versión importa funciones de otros archivos, un cambio posterior en esos archivos puede romper la deprecación; el manual aconseja guardar una copia de esas funciones.
  • El manual recomienda conservar un contenido de prueba por cada versión antigua del bloque.

Por eso cada cambio de marcado en un proyecto mío acaba con una deprecación y un artículo de prueba de la versión anterior. La deprecación se hace cuando se cambia el bloque, no cuando alguien descubre meses después que el archivo se ve roto.

#Cómo es un encargo de bloques conmigo

  1. Brief por escrito. Me envías la dirección de tu web, ejemplos de artículos y las piezas que tu equipo repite. Te contesto por escrito con preguntas concretas.
  2. Inventario y decisión. Reparto cada pieza entre patrón, plantilla y bloque, y lo documento antes de programar.
  3. Plugin propio. Los bloques viven en un plugin, no en el tema, con block.json y un espacio de nombres único.
  4. Entorno de pruebas. Pruebo con artículos reales de tu archivo. Tu equipo trabaja en ese entorno antes de la publicación.
  5. Entrega con documentación. Dejo una guía breve para editores y otra para desarrolladores. Si más adelante quieres mantenimiento, es un acuerdo aparte.

Para empezar el manual de WordPress describe el entorno habitual de desarrollo de bloques con wp-env, create-block y wp-scripts; son las herramientas que uso y no tienen nada de exótico, de modo que cualquier desarrollador WordPress podrá seguir con el código.

#Qué preparas tú, aunque no trabajes conmigo

  • Lista de las piezas que tu equipo repite en cada artículo, con un ejemplo publicado de cada una.
  • Decisión sobre qué puede cambiar la redacción y qué no.
  • El diseño de cada pieza. No hago diseño gráfico, maquetas ni wireframes: los aporta el cliente, normalmente con la hoja de maquetación que te envío, y yo los implemento.
  • Acceso de administrador al sitio y a un entorno de pruebas.
  • Una muestra de contenido antiguo con el que probar.

#Preguntas frecuentes

#¿Cuándo compensa un bloque propio y cuándo basta un patrón?

Un patrón es una combinación de bloques del núcleo con contenido de ejemplo. Basta cuando la pieza no necesita lógica ni campos estructurados. Un bloque propio compensa cuando hay atributos con significado (autor, fecha, fuente), datos que vienen del servidor o reglas que el equipo no debe poder saltarse.

#¿Los bloques viven en el tema o en un plugin?

En un plugin. Si los bloques están en el tema, un cambio de tema deja el contenido publicado con bloques que ya no existen. El tema decide el aspecto, el plugin decide qué piezas existen.

#¿Qué pasa con los artículos antiguos si cambio un bloque?

Si cambia el marcado que guarda un bloque estático, los artículos antiguos aparecen como bloque no válido salvo que el bloque tenga una entrada en deprecated con su función migrate. Los bloques dinámicos renderizados en PHP evitan gran parte del problema.

#¿Puedo impedir que la redacción desmonte la maquetación?

Sí. Una plantilla con template_lock fija los bloques de partida. Con contentOnly solo se edita el contenido; con all no se puede insertar, mover ni borrar. Un bloque concreto también admite bloqueo de movimiento y de borrado.

#¿Dónde se guardan los datos de la ficha de cada artículo?

En campos personalizados registrados con show_in_rest, enlazados a los bloques con Block Bindings (WordPress 6.5 o superior). Así el dato vive en un solo sitio y el bloque solo lo muestra.

#¿Qué necesito aportar para empezar?

La dirección de tu web, ejemplos de artículos publicados, la lista de piezas que tu equipo repite y el diseño de cada una. El diseño gráfico y la maqueta los aportas tú; yo los implemento.

#Escríbeme con tus piezas editoriales

Si tu equipo pierde tiempo rehaciendo la misma cabecera o la misma ficha en cada artículo, cuéntame tu caso desde la página de contacto. Me sirve la dirección de tu web, tres o cuatro artículos que representen lo que publicáis, la lista de piezas repetidas, los plugins instalados y la fecha a la que quieres llegar. Con esos datos te envío una primera estimación por escrito, gratuita, y te hago por correo las preguntas que falten.

¿Buscas el servicio: Desarrollo WordPress personalizado en Barcelona?

Describe tu proyecto por e-mail. Respondo en 48 horas.

Describe tu proyecto

Explora otros servicios WordPress y base de conocimiento