Crear bloque de Gutenberg personalizado – Parte 2: bloque de registro
En esta parte escribiremos Javascript para registrar y configurar nuestro bloque personalizado. Al final registraremos el script con PHP y haremos el código PHP necesario para que WordPress lo reconozca como un nuevo bloque.
Primero una nota rápida sobre cómo acceder a las funciones y componentes de WordPress Gutenberg.
wpEl paquete global y la desestructuración
Cuando estamos en un archivo Javascript en cola en el editor Gutenberg, tenemos acceso a un objeto/paquete global: wp. Este es un objeto Javascript muy, muy grande y contiene un montón de componentes y funciones útiles que usaremos para crear bloques. Al escribir Javascript para bloques personalizados, se referirá a wpbastante.
Por lo tanto, es común, tanto en Javascript moderno como en React, desestructurar lo que queremos usar de él. Básicamente, solo significa que definimos variables locales a partir de partes de una estructura más grande. Por ejemplo, la primera función que usaremos es registerBlockType()la que existe dentro de wp.blocks. Podríamos invocar la función así:
wp.blocks.registerBlockType();Pero es más fácil desestructurarlo así:
const { registerBlockType } = wp.blocks;
registerBlockType();Ahora puede hacer referencia a la función directamente sin prefijarla con su estructura. Se vuelve mucho más útil cuando nos referimos a funciones o componentes que repetiremos a menudo.
Haremos reestructuraciones en esta serie y, a medida que avancemos en el tutorial, veremos cuánto más legible y más corto se vuelve nuestro código.
Registro de un nuevo bloque
La función para registrar un nuevo bloque personalizado está registerBlockType()disponible en el wp.blockspaquete. Acepta dos parámetros; primero una cadena con el espacio de nombres y el nombre del bloque, y segundo un objeto con la configuración completa del bloque.
Gutenberg espera que todos los bloques tengan un espacio de nombres y un nombre, definido con una barra inclinada en el medio. El espacio de nombres es para garantizar que el nombre de su bloque no entre en conflicto con ningún otro bloque que pueda usar el mismo nombre. Todos los bloques en WordPress usan el espacio de nombres core. Por ejemplo, el bloque de párrafo estándar en WordPress tiene el nombre core/paragraph. Si elige otro espacio de nombres, también puede crear un bloque llamado párrafo sin causar ningún problema.
Decida un espacio de nombres de versión slug que sea único para usted. Usaré el espacio de nombres awp(versión corta de A White Pixel) en esta serie.
Abra el archivo fuente que creamos en el último paso; src/block-awhitepixel-myfirstblock.js, en un editor. Primero llamaremos registerBlockTypedesde desestructurados wp.blocks, con el nombre awp/firstblock. Ajuste su nombre y espacio de nombres sobre la marcha.
const { registerBlockType } = wp.blocks;
registerBlockType('awp/firstblock', {
// Your block configuration and code here
});En el segundo parámetro, el objeto de configuración del bloque, necesitamos definir algunas propiedades para que se registre correctamente. Recuerde que la configuración del bloque es un objeto, lo que significa que debe escribir todo como pares clave + valor, separados por comas. Hay bastantes propiedades de configuración posibles, así que repasemos estas y veremos el código final al final.
Requerido: título
La primera propiedad requerida es title. Este es el nombre que aparecerá cuando seleccione entre bloques. Establezca esta propiedad como cualquier nombre que desee en una cadena.
Añadiremos lo siguiente como título:
title: 'My first block',PD: Revisaremos cómo escribimos todas las cadenas en nuestro bloque para asegurarnos de que se puedan traducir en la parte 8. Pero por ahora lo mantendremos simple y simplemente escribiremos cadenas.
Requerido: categoría
La propiedad categorydefine en qué categoría de bloque aparecerá su bloque cuando seleccione bloques para insertarlos en el editor. Los valores posibles son common, formatting, layout, widgets, embed.
Pongámoslo en common, la primera categoría de bloque.
category: 'common',Opcional: icono
Si ha usado Gutenberg, probablemente haya notado que todos los bloques tienen íconos. Puede agregar un ícono a su bloque con una cadena que se refiera a cualquiera de los Dashicons de WordPress, o puede proporcionar un svgelemento personalizado.
Elegiré uno de los dashicons de WordPress, el emoticón, pero puedes elegir el que quieras. Tenga en cuenta que omite incluir "dashicons-" en su nombre de clase de icono.
icon: 'smiley',Opcional: descripción
Puede proporcionar una descripción que se mostrará en la barra lateral de Configuración (en el lado derecho) cuando el bloque esté activo.
Solo agregaré un texto rápido como ejemplo:
description: 'Learning in progress',Opcional: palabras clave
Gutenberg admite una función de búsqueda al elegir tipos de bloques. Puede proporcionar una matriz de posibles coincidencias en la propiedad keywords. Sin keywordsusted, solo encontraría su bloque buscando su nombre.
Agregaré exampley testpara que podamos encontrar fácilmente nuestro bloque personalizado cuando comencemos a escribir una de estas palabras clave.
keywords: ['example', 'test'],Opcional: atributos
La propiedad attributeses una propiedad muy importante que revisaremos con bastante frecuencia en esta serie de tutoriales. Aquí es donde almacena sus datos estructurados y la información ingresada por el usuario para su bloque. Puedes imaginarlo como variables. No lo agregaremos por ahora, pero definitivamente volveremos a esto muy pronto.
(Más o menos) obligatorio: editar y opcional: guardar
Dentro editde savelas propiedades es en realidad donde agregará todo su código tanto para la salida del editor como para el procesamiento de la interfaz. Ambas propiedades esperan una función que debería devolver algún resultado.
La propiedad editdescribe la estructura de su bloque dentro del editor. La savepropiedad maneja básicamente dos cosas; la salida de su bloque en la interfaz, pero también la estructura de cómo se guarda su bloque en la base de datos. Trabajará principalmente editporque aquí es donde agrega entradas para ingresar o elegir cosas y actualizar los datos del bloque. La savefunción no debe actualizar ni editar los datos de ninguna manera, solo debe generar una salida.
Gutenberg necesita poder reconstruir su bloque con todas sus configuraciones en el editor a partir de lo que se genera en la savefunción (y atributos). Si Gutenberg alguna vez abre una publicación en la que la salida del bloque guardado previamente difiere (aunque sea un poco) de lo que se definió al guardar, su bloque dejará de ser válido.
Puedo garantizarle que se encontrará con esto muchas veces al desarrollar bloques personalizados. Cuando esto sucede, debe eliminar el bloque (de los puntos en la barra de herramientas) y volver a agregarlo. También recomiendo actualizar el navegador (F5 o CTRL+R).
WordPress tiene una página de documentación dedicada a las funciones de edición y guardado del bloque si desea obtener más información.
En cuanto a nuestro primer bloque, generemos algo básico. Devolveremos lo mismo para ambos edity save; un ":)" envuelto en <div>. Después de todo, el ícono del bloque es un emoticón.
Otras propiedades
Hay propiedades más opcionales para registerBlockType; parent, supports, transforms, exampley styles. Omitiremos estos por ahora, ya que la mayoría son para la construcción de bloques más avanzada o personalizada. Si está interesado en leer más sobre esto, eche un vistazo a la documentación de WordPress.
Código de bloque de registro final
Nuestro código ahora se parece a esto.
Con esto tenemos suficiente para que nuestro bloque sea registrado exitosamente como bloque personalizado. Veámoslo en la práctica dentro del editor Gutenberg.
¿Te acordaste de compilar tu Javascript? En el paso anterior aprendimos que no podemos cargar este archivo Javascript en Gutenberg; necesitamos la versión compilada. Por lo general, se desarrollaría npm run startejecutándose en segundo plano, o simplemente puede ejecutar npm run builduna vez ahora. Eso debería compilar nuestro Javascript fuente y colocarlo donde lo definió para colocarlo y nombrarlo en su archivo webpack.config.js.
La parte PHP de registrar un bloque
Para cada bloque, debe registrar el archivo Javascript y esto es lo mismo que registraría cualquier otro script en WordPress, utilizando [wp_register_script](https://developer.wordpress.org/reference/functions/wp_register_script/)(). Tenga en cuenta que registramos el script, no lo ponemos en cola. Esto se debe a que también necesitamos llamar a una función de PHP para registrar cada bloque personalizado, y esa función es responsable de poner en cola el script cuando sea necesario.
Prefiero mantener el código relacionado con Gutenberg en un archivo separado en mis temas. Pero puede, y lo haremos en este tutorial, simplemente escribir todo el código PHP directamente dentro del tema functions.phppor simplicidad.
Recomiendo usar el initgancho para su función, y no enqueue_block_assets. Podemos juntar tanto el registro del script como el registro del bloque.
La función de PHP que usaremos para registrar un nuevo bloque es [register_block_type](https://developer.wordpress.org/reference/functions/register_block_type/)(). De manera similar a Javascript, registerBlockType()acepta dos parámetros; el espacio de nombres y el nombre del bloque, y una matriz con argumentos. Asegúrese de proporcionar exactamente el mismo espacio de nombres y nombre en PHP que en Javascript.
En el segundo argumento hay algunos argumentos posibles (a algunos de los cuales volveremos más adelante en esta serie). Pero el más importante es editor_scriptdonde proporciona el identificador (primer parámetro de wp_register_script()) del script registrado.
¡Y eso es!
Nuestro bloque en el editor de Gutenberg
Ahora, cuando actualice su editor en alguna publicación, debería encontrar nuestro bloque, ya sea abriendo la categoría Común o buscando cualquiera de las palabras clave o el nombre que proporcionó.
Nuestro bloque representa un simple ":)" tanto en el editor como en la interfaz. A partir de ahora, no puede editar nada en el bloque, ¡pero eso es lo que aprenderemos en los próximos pasos!