Crear bloque de Gutenberg personalizado – Parte 3: accesorios y componentes de WordPress
El paso anterior de esta serie de tutoriales fue cómo registrar un bloque personalizado, tanto en Javascript como en PHP. En este paso, aprenderemos cómo usar los componentes de WordPress para agregar diferentes tipos de campos y configuraciones.
Para utilizar los componentes de WordPress en nuestro bloque, primero debemos conocer los accesorios.
Accesorios
Props es una característica importante en React y es básicamente una forma de pasar variables o funciones a otros componentes. Si no está familiarizado con los accesorios de React, puede leer el tutorial oficial de React sobre esto.
WordPress proporciona algunos apoyos para las funciones edit
y en. Dentro de estos accesorios tenemos acceso a cosas críticas, como atributos y un método para actualizar nuestros atributos. ¡Repasaremos los atributos en detalle en el siguiente paso! save``registerBlockType()
Hasta ahora en nuestro bloque escribimos la función for edit
y save
así:
Debería acostumbrarse a agregar el parámetro props
a ambos edit
y save
, así:
Ahora tiene acceso completo a la variable props
y todo lo que contiene desde dentro edit
y save
. Si tiene curiosidad, puede agregar un console.log(props);
en la edit
función antes de la return
declaración. Debería ver qué accesorios están disponibles en el depurador de la consola.
Usando los componentes de WordPress
Como se mencionó antes, tenemos acceso a una enorme biblioteca de componentes y funciones útiles dentro del paquete global wp
. Encontrará componentes listos para usar para cualquier tipo de componente relacionado con la entrada que se le ocurra. Los ejemplos incluyen entradas de texto, entradas de texto enriquecido, menús desplegables, alternar, casillas de verificación, botones en diferentes estilos, cargador de medios y selectores de color. También hay funciones y componentes para una funcionalidad más avanzada. Como consultar el contenido de WordPress (publicaciones, categorías, etc.) con funciones integradas o buscar con la API REST.
Es más fácil y recomendable usar los componentes de la interfaz de usuario de WordPress. Esto es para asegurarse de que el diseño y la funcionalidad sean lo más eficientes posible para no confundir ni molestar a los usuarios.
Pero desafortunadamente al momento de escribir esto la documentación de Gutenberg es muy escasa. Encontré que la mejor manera de aprender sobre lo que existe dentro del wp
paquete y cómo funcionan los componentes es mirar en su repositorio oficial de Gutenberg Github. Algunos de los paquetes (carpetas) tienen un texto Léame que ofrece un poco de documentación. Eche un vistazo al archivo Léame de un botón o la palanca, por ejemplo.
El repositorio de Github debe corresponder a lo que hay dentro del wp
paquete (según la versión que tenga y la rama que esté viendo en Github). Esto significa que cada carpeta que ve en el packages
directorio raíz de Github reside en el wp
paquete global. Como ejemplo, recuerde que la función que usamos en el paso anterior registerBlockType()
, estaba dentro wp.blocks
de, lo que significa que encontrará el código fuente de esta función exportado dentro de packages/blocks/
.
A medida que desarrollé varios bloques de Gutenberg personalizados y busqué un poco en el repositorio de Github, descubrí que hay algunos paquetes que contienen la funcionalidad más común utilizada para crear bloques personalizados. Los incluiré a continuación.
Para obtener una descripción más completa de los componentes disponibles, recomiendo descargar mi libro electrónico gratuito que cubre los componentes disponibles en Gutenberg. Contiene los componentes más comunes y útiles con documentación sobre accesorios y ejemplos de código:
Una descripción general rápida de los paquetes más comunes que usará para los bloques
Obviamente hay muchos más disponibles, pero lo siguiente es lo más común para el desarrollo de bloques. Usaremos la mayoría, si no todos, de estos en esta serie de tutoriales. Siempre que desee utilizar un componente, debe saber en qué paquete se encuentra.
wp.components
Encontrará la mayoría de los componentes de entrada de la interfaz de usuario dentro de wp.components
. Los ejemplos son diferentes entradas de texto, selección, casillas de verificación, botones de radio, componentes que se pueden arrastrar, botones, selector de color, selector de fecha, etc. También encontrará componentes de la interfaz de usuario que puede usar para la barra de herramientas de bloque y el contenido de la barra lateral de configuración (llamada InspectorControls) en el editor.
Echa un vistazo a las carpetas en el repositorio de Github.
wp.blockEditor y wp.editor
En estos dos paquetes, encontrará componentes útiles para texto enriquecido, manejo de imágenes/cargador de medios y componentes para agregar barras de herramientas o paneles de Inspector (barra lateral) personalizados.
Al final de esta serie, veremos la creación de bloques dinámicos en los que usaremos PHP para representar la salida del bloque, y para eso usaremos un componente de wp.editor
.
Según tengo entendido, la mayoría de los componentes comenzaron en wp.editor
los primeros días de Gutenberg, pero especialmente después de WordPress 5.3, muchos de ellos se trasladaron a wp.blockEditor
. Si usa un componente en wp.editor
el que WordPress planea mudarse a wp.blockEditor
él, no fallará a partir de ahora, pero en el depurador de la consola recibirá advertencias de que ha quedado obsoleto y que debe cambiarlo wp.blockEditor
cuando pueda. Y de manera reversible, si está siguiendo esta serie con una versión anterior de WordPress por alguna razón, es posible que encuentre errores al llamar a componentes que aún no se wp.blockEditor
han movido.
elemento wp
Dentro wp.element
encontrarás componentes que corresponden a los componentes de React. Por ejemplo Component
(que corresponde a React.Component
) y Fragment
( React.Fragment
). Los usaremos cuando comencemos a dividir nuestro código en componentes separados.
wp.i18n
Como su nombre lo indica, el wp.i18n
paquete contiene funciones para manejar la traducción. Contiene las mismas funciones de traducción que conocemos en PHP; por ejemplo __()
y _e()
. Veremos esto en detalle en <<<>>>> cuando aprendamos a traducir nuestro bloque.
wp.datos
El wp.data
paquete es para consultar WordPress por datos fuera del editor. Hay componentes para enviar mensajes, withSelect
y select
que usaremos más adelante en esta serie para consultar publicaciones dentro de nuestro bloque.
wp.componer
El paquete anterior y wp.compose
son para la construcción de bloques más avanzada. Dentro de este paquete encontraremos componentes y funciones para crear los llamados componentes de orden superior. Los componentes de orden superior son una técnica de patrón en React para reutilizar componentes y lógica, y usaremos esto en combinación con wp.data
para consultar publicaciones.
Basta de hablar: ¿cómo se utilizan algunos de estos componentes en la práctica?
Como se mencionó anteriormente; para poder usar los componentes de WordPress necesitas saber dónde están. Con suerte, mi descripción general anterior combinada con el repositorio de Github le dará una idea de dónde obtenerlos.
No olvide que siempre puede agregar cualquier etiqueta HTML normal, como div, span, encabezados, etc. Solo recuerda seguir las pautas de React en atributos. Por ejemplo class
, es una palabra clave reservada en React (para crear componentes basados en clases), por lo que si desea agregar una clase a un elemento HTML, debe usar className
.
Nota: Mientras desarrolla, no olvide iniciar npm run start
para compilar su código.
Como un ejemplo simple, probemos algunos componentes para ver cómo se ven. Los desestructuramos de sus paquetes correspondientes y los usamos en nuestra edit
función.
Esto, por ejemplo, hará que nuestro bloque se vea así en el editor.
Notarás que recibirás mensajes de error en la Consola cuando los escribas, y que no guardará lo que escribas al actualizar la publicación (y refrescar). Esto se debe a que nos faltan accesorios en los componentes, que es la conexión a los atributos, donde se almacenan todos nuestros datos de bloque. Los props se encargan de pasar los valores guardados y las funciones se encargan de actualizar nuestros atributos cuando algo cambia en nuestras entradas. Esto es lo que haremos en el próximo paso, donde finalmente comenzaremos a escribir código de verdad.