Construir un bloque personalizado en WordPress requiere conectar varias piezas: un proyecto NPM correctamente inicializado, una compilación que garantice compatibilidad con todos los navegadores y el registro tanto en PHP como en JavaScript. Aquí se recorre cada paso, desde la terminal hasta ver el resultado funcionando en el editor y en el front-end.
¿Cómo se inicializa el proyecto con NPM?
El punto de partida es abrir la consola y ejecutar npm init -y para aceptar la configuración por defecto [0:08]. Esto genera un archivo package.json que centraliza toda la configuración del proyecto. Desde la página de NPM se copian los scripts disponibles de la librería para tener todas las funciones listas.
La librería trabaja con dos directorios predeterminados:
- src: contiene el código fuente que escribimos.
- build: almacena el archivo compilado, compatible con todos los navegadores.
Dentro de src se crea un archivo index.js, que es el punto de entrada por defecto [1:00]. Una prueba rápida con console.log("hola") y el comando npm run build en la consola confirma que la compilación funciona correctamente [1:14].
Al revisar la carpeta build aparecen dos archivos: el JavaScript compilado y un archivo PHP llamado index.asset.php [1:30]. Este último contiene las dependencias que el script necesita y la versión de la compilación, datos fundamentales para el registro del bloque.
¿Cómo se registra el bloque en PHP?
En el archivo functions.php se define una función sin parámetros, en este caso llamada pg_register_blocks [1:52]. Dentro de ella se realiza un include_once del archivo index.asset.php usando get_template_directory() para obtener el path del directorio del tema y completar la ruta hacia blocks/build/index.asset.php [2:10].
Después se utiliza wp_register_script para registrar el archivo JavaScript compilado [2:38]. Esta función recibe:
- Un handler identificador, por ejemplo
pg-block.
- La URL del archivo, que se obtiene con
get_template_directory_uri() en lugar de get_template_directory() (este detalle es crucial, porque se necesita una URL, no un path) [6:20].
- Las dependencies extraídas del archivo
.asset.php.
- La versión del asset.
A continuación se invoca register_block_type con dos parámetros: el slug del bloque (pg/basic) y un array de argumentos donde se especifica editor_script con el handler definido antes (pg-block) [3:30]. Esto asocia el bloque al script para que se cargue en el editor.
Finalmente, todo se conecta mediante un hook con add_action('init', 'pg_register_blocks') [4:08], asegurando que el registro ocurra al inicio de la carga del sitio.
¿Cómo se construye el bloque en JavaScript?
En el archivo src/index.js se importa la función registerBlockType desde la librería @wordpress/blocks [4:40]. Esta función recibe el mismo nombre que se usó en PHP (pg/basic) y un objeto de configuración con las siguientes propiedades [5:00]:
- title: el nombre visible del bloque, por ejemplo
Basic Block.
- description: una descripción breve como "este es nuestro primer bloque".
- icon: se selecciona de la librería Dashicons; en este ejemplo se usa
smiley.
- category: define dónde aparecerá en el editor; se utiliza
layout (que en español corresponde a "elementos de diseño").
¿Cuál es la diferencia entre edit y save?
El objeto de configuración incluye dos funciones esenciales [5:40]:
- edit: determina cómo se visualiza el bloque dentro del editor de WordPress. En este caso, una arrow function que retorna un
<h2>Hello World</h2>.
- save: define lo que se renderiza en el front-end del sitio. Aquí se repite la misma estructura del
h2.
La diferencia es clara: edit controla la experiencia de edición y save controla la presentación pública.
¿Cómo se verifica que el bloque funciona?
Tras corregir errores de tipeo y cambiar get_template_directory() por get_template_directory_uri() para pasar una URL válida [6:20], el bloque aparece en el editor dentro de la categoría layout. Al agregarlo se muestra el h2 con "Hello World" tal como se definió [7:02]. Al guardar como borrador y abrir la vista previa, el mismo elemento se reproduce en el front-end como un <h2> [7:18].
Este bloque todavía es estático: reproduce una interfaz fija definida en el código. El siguiente paso será convertirlo en un bloque editable, donde el contenido pueda modificarse directamente desde el administrador. ¿Qué tipo de bloque personalizado te gustaría construir?
