Tutorial: crear un control deslizante como un bloque dinámico de Gutenberg

Este tutorial explicará cómo crear un bloque dinámico de WordPress Gutenberg. El resultado final es un control deslizante que muestra la imagen destacada de las publicaciones de categorías seleccionadas. El código incluye el uso de un componente de orden superior (withSelect) para obtener todas las categorías dentro del editor de bloques.

que haremos

El bloque representará un control deslizante simple utilizando el script jQuery Cycle2. Pero puede usar cualquier otro script de control deslizante. El bloque dentro del editor mostrará una lista de todas las categorías, lo que permitirá al usuario seleccionar una categoría. Al mostrar el bloque en la interfaz, obtendrá de forma dinámica las publicaciones de la categoría elegida y mostrará sus imágenes destacadas como diapositivas. Este tutorial lo mantendrá bastante simple, permitiéndole expandir y ajustar su control deslizante como lo desee.

He optado por no mostrar la presentación de diapositivas dentro del editor. Por lo general, se aseguraría de que el renderizado en el editor y la interfaz sean iguales. Pero en el caso de un control deslizante, me gusta mantenerlo simple para no molestar al usuario con animaciones constantes dentro del editor.

El bloque tendrá solo dos configuraciones; la elección de la categoría y el número de diapositivas (mensajes). Recomiendo agregar más configuraciones, como velocidad de deslizamiento, configuraciones para mostrar píldoras, flechas, texto y otras configuraciones típicas del control deslizante. Debería ser bastante simple agregar estas configuraciones usted mismo.

Todo el código está escrito en Javascript ES6 / ES2015+. Tenga en cuenta que este código necesita que Babel transforme y cree los archivos Javascript finales. Consulte la guía a continuación si no sabe cómo hacerlo.

configurar los archivos

En este ejemplo estamos creando el bloque dentro de un tema. En la carpeta del tema tengo una subcarpeta ‘ gutenberg/‘ donde he colocado mi package.jsony webpack-config.js. Dentro de la subcarpeta ‘ src/‘ en esta carpeta es donde coloco todos mis archivos de compilación. La configuración de mi paquete web está configurada para colocar los archivos de compilación en la subcarpeta de mi tema ‘ assets/js/‘.

Cree un nuevo archivo fuente vacío theme-folder/gutenberg/src/block-slider.jsy configure Webpack para crear el archivo de compilación en theme-folder/assets/js/block-slider.js. Puede cambiar las ubicaciones y/o los nombres de archivo como desee, solo recuerde ajustar el código a continuación.

También necesitamos descargar el script deslizante necesario. Puede descargar Cycle2 en este enlace, o puede usar cualquier otra secuencia de comandos de diapositivas y ajustar el código a continuación. Estoy colocando el jquery.cycle2.min.jsarchivo en mi carpeta de /assets/js/carpetas de temas.

También prepararé un pequeño archivo CSS que se cargará solo en el editor. Solo hacemos una pequeña pieza de estilo para que la selección de categoría sea óptima. Creo un archivo vacío editor-block-slider.cssy lo coloco en theme-folder/assets/css/.

Finalmente vamos a un archivo PHP que está cargado en el tema. En aras de la simplicidad, estoy haciendo la parte de PHP en el archivo functions.php.

Registrar el bloque de Gutenberg en PHP

Todos los bloques de Gutenberg deben estar registrados con [register_block_type](https://developer.wordpress.org/reference/functions/register_block_type/)(). Prefiero llamarlo dentro de una función enganchada a init. El primer parámetro es el nombre de su bloque, incluido el espacio de nombres. He decidido llamar a mi secuencia de comandos deslizante awp/slider(ajustar como quieras). El segundo argumento es una matriz de argumentos.

Dentro de la misma función, registraré el script de compilación [wp_register_script](https://developer.wordpress.org/reference/functions/wp_register_script/)()y registraré mi archivo CSS del editor con [wp_register_style](https://developer.wordpress.org/reference/functions/wp_register_style/)(). Ambos identificadores se agregarán como argumentos a ‘ editor_script‘ y ‘ editor_style‘, respectivamente. En cuanto a las dependencias, agregué algunos de los paquetes más básicos para el script para garantizar que nuestro script de bloque se cargue en el orden correcto. En cuanto al estilo del editor, usar ‘ wp-edit-blocks‘ es una buena dependencia para evitar que se anulen sus estilos.

Y finalmente, debido a que este es un bloque dinámico, también debemos agregar el render_callbackargumento ‘ ‘, que apunta a una función que es responsable de representar el bloque en la interfaz.

Finalmente definimos la función render. Obtenemos dos parámetros para la devolución de llamada de la función; una matriz de atributos del bloque y el contenido interno (no utilizado en este bloque). Simplemente devolveré una cadena ficticia. Volveremos y desarrollaremos la función de renderizado más tarde. Recuerde devolver una cadena, no un eco.

function awp_gutenberg_slider_render($attributes, $content) {
    return 'Slider render comes here.';
}

Volveremos a la función de representación de PHP al final de este tutorial. ¡Ahora es el momento de pasar a Javascript!

Registre un bloque de Gutenberg personalizado en Javascript

Abramos nuestro block-slider.jsarchivo fuente. En este punto, iniciaré el script (npm run start) para transformar todo lo que hacemos en este archivo en el archivo de compilación a medida que avanzamos. Necesitamos registrar el bloque usando [registerBlockType](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/)(). Echa un vistazo al enlace para ver todos los argumentos posibles.

Como decidimos register_block_type()en PHP, nuestro bloque se llama awp/slider. También queremos agregar dos atributos al bloque, como se mencionó anteriormente: uno para el ID del término seleccionado y otro para el número de diapositivas.

También me gusta agregar la funcionalidad de alineación de bloques. Se agregará automáticamente agregando ‘ align‘ al supportsobjeto. Si desea todas las alineaciones de bloques, simplemente puede configurarlas aligncomo verdaderas. Sin embargo, un control deslizante alineado a la izquierda o a la derecha no tiene mucho sentido, por lo que definiré los tipos específicos de alineación de bloques que admite este bloque: "Alinear al centro" (‘ center‘), "Ancho ancho" (‘ wide‘) y " Ancho completo" (‘ full‘). Además, para definir una alineación predeterminada y hacerla accesible desde PHP, agrego ‘ align‘ como atributo a nuestro bloque.

Establecí el argumento del bloque editen un componente separado que crearemos a continuación. Y finalmente la savefunción simplemente devuelve null, porque este es un bloque dinámico.

Necesitamos definir el componente para la editpropiedad. Antes del código de registro, defino un componente de función BlockEditque simplemente representa un divy un Placeholdertexto ficticio.

[Placeholder](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/placeholder)es un buen componente para renderizar un área para la configuración, y no necesariamente para el renderizado real de un bloque. Dentro del Placeholdercomponente es donde representamos una lista de términos para elegir.

¡En este punto, nuestro bloque debería estar disponible en WordPress Gutenberg! Creemos una nueva publicación, agreguemos un nuevo bloque y busquemos nuestro bloque dentro de la categoría Común. Así es como se ve nuestro bloque actualmente:

Adición de la configuración del Inspector

Agreguemos algunas configuraciones al Inspector (barra lateral derecha del editor). Como se mencionó, nuestro bloque solo tiene una configuración; número de diapositivas. Aquí es donde te recomiendo que agregues más configuraciones para tu bloque deslizante. Recuerde registrar atributos para cada configuración que agregue.

Para agregar algo al Inspector usamos el componente [InspectorControls](https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/src/components/inspector-controls)( ). wp.blockEditorDentro representamos un [PanelBody](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/panel#panelbody)( wp.components) para agregar una nueva sección contraíble. Luego, simplemente renderizamos un [RangeControl](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/range-control)( wp.components) para crear una configuración de entrada para elegir el número de diapositivas. Establecemos el mínimo en 1 y el máximo en 10. Conectamos el evento valuey onChangeal atributo numSlides.

Con el código anterior, ahora deberíamos obtener una buena sección con un control deslizante de rango para configurar el número de diapositivas.

Nuevamente, le recomiendo que juegue agregando más configuraciones a su control deslizante. El siguiente paso es crear el elemento para representar una lista de categorías para elegir.

Creación de un componente de selección de categoría

Para mantener nuestro código ordenado y reutilizable, creemos el componente selector de categoría en un archivo separado. Dentro de la carpeta de compilación, creo un nuevo archivo awp-category-picker.js.

Dentro de este archivo, definimos un componente que recorrerá todas las categorías actualmente en WordPress y las representará de alguna manera. Para obtener categorías, debemos envolverlo dentro de un llamado componente de orden superior, que proporcionará a nuestro componente lo que necesitamos a través de accesorios. Para ello utilizaremos [withSelect](https://developer.wordpress.org/block-editor/packages/packages-data/#withSelect). Dentro withSelectpodemos hacer una solicitud para buscar todas las categorías en WordPress usando el selector de tienda [select](https://developer.wordpress.org/block-editor/packages/packages-data/#select)(). Nosotros podemos usar:

para obtener todos los términos dentro del slug de taxonomía proporcionado. Si no está familiarizado con los componentes y selectores de orden superior en WordPress Gutenberg, tengo una publicación que explica este concepto con más detalle: Crear un bloque de Gutenberg personalizado – Parte 10: Obtención de publicaciones y componentes de orden superior.

Debido a que necesitamos exportar un componente de este archivo, colocamos la combinación de withSelecty nuestro componente definido en la export defaultinstrucción. Nuestro CategorySelectcomponente simplemente devuelve un div con un texto ficticio para que podamos ver que funciona. El withSelectdebe proporcionar el apoyo ‘ terms‘ a CategorySelect. He agregado una console.log()en este accesorio para que podamos ver que funciona.

Lo último que tenemos que hacer es importar y usar este componente selector de categoría en nuestro bloque personalizado.

De vuelta block-slider.js, primero debemos importar el componente en la parte superior del archivo. Y dentro de nuestro Placeholdercomponente simplemente renderizamos el componente.

Con el código anterior, su bloque ahora debería representar el div del CategorySelectcomponente. Si abre la consola en su navegador, también debería ver algunos registros. Recuerde que withSelectes una consulta asíncrona, lo que significa que podría procesarse varias veces. La(s) primera(s) vez(es) que los términos prop son null. Pero los últimos registros deberían terminar con una serie de términos de categoría.

¡Excelente! ¡Sigamos trabajando con nuestro CategorySelectcomponente y hagamos que realmente represente la lista de términos que le permite al usuario seleccionar uno!

Representación de una lista de términos para elegir

Hay muchas formas de representar una lista de opciones donde el usuario puede seleccionar un elemento. Si desea algo realmente simple, puede representar un menú desplegable de selección estándar ([SelectControl](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/select-control)). Depende completamente de ti. He optado por un enfoque más limpio y agradable usando [MenuGroup](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/menu-group)( wp.components) y [MenuItem](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/menu-item)( wp.components).

Dentro de un MenuGroupcomponente, debemos recorrer la props.termsmatriz y, para cada elemento, queremos mostrar un MenuItemcomponente que represente el nombre del término. Y, por supuesto, solo queremos renderizar esto si props.termsrealmente contiene algo (solicitud asíncrona, ¿recuerdas?).

Le he dado al MenuGroupcomponente una clase personalizada, ya que necesitaremos apuntar a esto con CSS. Y configuré el accesorio roleen MenuItem‘ menuitemradio‘ para asegurarme de que solo se pueda elegir uno a la vez. Por defecto, funcionan como casillas de verificación, lo que permite elegir varios elementos.

Con el código anterior, nuestro bloque debería ahora (después de un pequeño segundo) mostrar una buena lista de todas las categorías en su instancia de WordPress.

Puede notar que nuestro bloque se expandirá para contener todas las categorías. Si estamos en una instancia de WordPress con muchas categorías, esto rápidamente se convierte en un problema. Queremos asegurarnos de que el selector sea un contenedor de altura máxima que obtenga una barra de desplazamiento vertical si hay muchas categorías. Aquí es donde entra nuestro archivo CSS.

En nuestro editor-block-slider.cssarchivo agregar:

.awp-categoryselect div {
    max-height: 200px;
    overflow: hidden scroll;
    border: 1px solid #b3bcc0;
}

Este CSS apunta al interior de divnuestro interior MenuGroupy se asegura de que nunca supere los 200 px. Si el contenido de la MenuGroupse hace más grande (más categorías) se mostrará una barra de desplazamiento vertical. Este es el mínimo de CSS para nuestro bloque, pero, por supuesto, puede agregar más CSS si lo desea.

Lo último que debemos corregir en nuestro selector de categorías es la funcionalidad para mostrar el elemento seleccionado actualmente y permitir que el usuario seleccione un término de la lista. Para ello necesitamos pasar algunos accesorios a este componente desde nuestro bloque.

Necesitamos block-slider.jspasar el término seleccionado actual (valor del atributo termId) y una función para actualizar el término seleccionado (setAttributes) como apoyos a nuestro componente selector de categoría.

En el código anterior en la línea #6, definimos una función que simplemente actualiza el atributo termId. Pasamos este nombre de función como prop a CategorySelectat line #17. Y en la línea #16pasamos el valor actual de termId. Con podemos actualizar nuestro CategorySelectcomponente para reflejar el elemento elegido y permitir que el usuario elija un término.

De vuelta awp-category-picker.js, agregamos algunos accesorios nuevos en MenuItem. Devolvemos trueo falsepara la propiedad isSelectedsi el ID del término actual es o no el mismo que el seleccionado actualmente. Iniciamos la selectTermfunción en el onClickevento, pasando el término ID. Y para que el elemento seleccionado sea visual, agregamos condicionalmente un ícono antes de cada elemento.

Con esto, nuestro selector de categoría debería verse así:

La lista debe marcar claramente el término seleccionado con un ícono de verificación, y puede hacer clic en cualquier término para seleccionar ese término en su lugar.

¡Eso fue todo para el editor y la parte de Javascript! Lo que queda ahora es el renderizado frontend, que haremos en PHP.

Renderizar el bloque dinámico en PHP

Antes de sumergirnos en la función de renderizado, primero ocupémonos de algunas cosas.

Primero, debemos poner en cola el script de ciclo2 en la interfaz para que nuestro código del control deslizante se convierta en un control deslizante. Hacemos esto con una función simple conectada a wp_enqueue_scripts. Ajuste lo siguiente si optó por otra secuencia de comandos deslizante.

add_action('wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'cycle2-slider-js', 
        get_template_directory_uri(). '/assets/js/jquery.cycle2.min.js', 
        ['jquery'], 
        '', 
        true
    );
});

En segundo lugar, queremos volver a la register_block_type()llamada a la función. Cuando manejamos bloques dinámicos definitivamente deberíamos agregar un nuevo argumento; attributes. En este argumento, definimos todos los atributos que hemos definido registerBlockTypeen Javascript, incluidos sus valores predeterminados. Si no lo hacemos, no todos los atributos estarán disponibles en nuestra devolución de llamada de renderizado. Si un atributo se dejó sin cambios en el editor de bloques, el atributo y su valor no estarán disponibles en la matriz de atributos en PHP. Por lo tanto, le recomiendo que siempre tenga cuidado de agregar la attributesmatriz a la register_block_type()función de PHP cuando trabaje con bloques dinámicos. Para nuestro bloque se vería así:

Ahora volvemos a nuestra función de renderizado de devolución de llamada awp_gutenberg_slider_render(). La salida depende completamente de usted, especialmente si ha elegido usar otro script de control deslizante. El siguiente es un ejemplo simple.

La idea principal es que comprobemos si se eligió o no un término ($attributes['termId']). Si se completa, creamos un [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/)()con argumentos para el número de publicaciones ($attributes['numSlides']) y la ID de categoría seleccionada. Luego, se trata de generar el HTML adecuado para que Cycle2 funcione, recorrer las publicaciones y mostrar sus imágenes destacadas como diapositivas.

Tenga en cuenta cómo agrego la clase de alineación de bloque adecuada en línea #12. El resultado debería ser un control deslizante de las imágenes destacadas. Tenga en cuenta que este es un ejemplo básico que tiene algunos defectos. Por ejemplo, buscamos las últimas tres publicaciones de la categoría seleccionada. Pero suponiendo que uno de ellos no tenga una imagen destacada, el control deslizante solo mostrará dos publicaciones.

Lo importante a recordar es devolver una cadena y no repetirla. También recomiendo usar algún tipo de funcionalidad de plantillas en su tema para renderizados de bloques dinámicos como estos. Rápidamente puede volverse complicado arreglar y construir HTML como una cadena.

Ultimas palabras

Este tutorial le ha mostrado cómo crear un bloque dinámico personalizado de Gutenberg de WordPress donde renderiza su contenido de interfaz en PHP. Y ha visto cómo usar el componente de orden superior withSelectpara consultar todos los términos de categoría y un método para mostrar una lista seleccionable.

Todo el código anterior está escrito de la manera más simple posible. Solo he agregado el mínimo absoluto de configuraciones. El control deslizante funciona, pero generalmente desea más, por ejemplo, hacer enlaces de diapositivas, mostrar títulos de las publicaciones, flechas del control deslizante o la opción de personalizar la velocidad u otras configuraciones del control deslizante. La idea es mostrarle los conceptos básicos y facilitarle la ampliación, la ampliación y los cambios para adaptarse a las necesidades de su proyecto.