Agregue una barra lateral de inspector personalizado en WordPress Gutenberg con Post Meta

En este tutorial, veremos cómo agregar una barra lateral personalizada al Inspector (barra lateral derecha) en WordPress Gutenberg. En el interior, implementaremos un campo conectado a una publicación meta. Todo está implementado con Javascript, dentro del editor de Gutenberg, y es una alternativa a agregar metaboxes de la manera tradicional.

¡Aviso!

Este es un tutorial para crear su propia barra lateral personalizada. Pero si está interesado en simplemente agregar meta/configuraciones a la barra lateral estándar del Inspector (pestaña "Documento"), tengo un tutorial para exactamente eso:

lo que vamos a crear

WordPress Gutenberg permite a los desarrolladores crear barras laterales personalizadas mediante la creación de un llamado complemento de Javascript. (No debe confundirse con los complementos tradicionales de WordPress). Al usar un complemento de Javascript, podemos crear una nueva barra lateral y también conectarnos al menú "Herramientas y opciones".

Agregaremos un nuevo elemento de menú en "Herramientas" que abrirá nuestra barra lateral personalizada. El contenido de la barra lateral depende completamente de usted, pero revisaré algunos ejemplos, incluido cómo conectar un metacampo de publicación dentro de él.

Configurando tu Javascript

Para este tutorial, escribiré ES6/ESNext Javascript con JSX, lo que significa que debemos configurar un compilador. Si desea seguir adelante y no escribir Javascript ES5, deberá configurar un entorno de desarrollo que compile su Javascript sobre la marcha. Si no está familiarizado con esto, siga mi publicación que explica cómo configurarlo y luego regrese aquí.

Configuré mi webpack.config.jspara compilar mi archivo Javascript de origen en el archivo /assets/js/sidebar-plugin.js. Este archivo compilado es lo que necesitamos para ponerlo en cola en el editor de Gutenberg. Mientras escribo este código, comencé el compilador en tiempo de ejecución que vuelve a compilar el Javascript cada vez que guardo los cambios en el código fuente (npm run start). Todo esto está explicado en profundidad en el tutorial mencionado anteriormente.

Estoy escribiendo esto en un tema, pero funciona igual en un complemento. Solo recuerde ajustar las rutas al agregar el script al editor.

Agregar el script al editor

Para agregar nuestro script al editor de Gutenberg, necesitamos escribir algo de PHP. Si está en un tema, functions.phpes un buen lugar para comenzar, o en algún lugar de sus archivos de complemento. Tenga en cuenta que debemos agregar el script compilado final, no el código fuente. En mi ejemplo, el Javascript compilado se encuentra en el archivo /assets/js/sidebar-plugin.js.

Creamos una función enganchada a enqueue_block_editor_assets. Dentro hacemos lo de siempre [wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)(). Como dependencias al script agregamos dos; wp-plugins, y wp-edit-post. Estos dos paquetes deben cargarse antes de nuestro script ya que usamos funciones de ellos.

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script('awp-sidebar-plugin', get_stylesheet_directory_uri(). '/assets/js/sidebar-plugin.js', ['wp-plugins', 'wp-edit-post']);
});

Debido a que ponemos en cola el script en el gancho enqueue_block_editor_assets, nuestro script solo se cargará cuando el editor de Gutenberg esté activo. ¡Excelente! Ahora todo está listo para escribir nuestro complemento de Javascript.

Registrar un complemento de Javascript

El primer paso es registrar un complemento. Hacemos esto con la [registerPlugin](https://github.com/WordPress/gutenberg/tree/master/packages/plugins#registerPlugin)función en wp.plugins desde dentro del wp.pluginspaquete.

Como parámetro para registerPlugin, proporcionamos un nombre (asegúrese de que sea único) y un objeto con configuraciones. Como mínimo, debe proporcionar un componente para la propiedad de representación. También puede agregar opcionalmente un ícono de los dashicons de WordPress. Tenga en cuenta que si no especifica un ícono, volverá al ícono del complemento. Para fines de demostración, estoy usando el 'carrot'icono.

En cuanto al componente, comenzamos definiendo un componente básico que devuelve un div simple con algún texto aleatorio. Y antes de todo el código desestructuramos las funciones de los paquetes que queremos usar.

Si no sucede nada (ni siquiera errores) al actualizar Gutenberg, estamos listos para comenzar. No vemos nuestro componente porque no le hemos dicho a WordPress dónde renderizarlo. El siguiente paso es conectar el menú de la barra lateral personalizada y los componentes del menú de herramientas para representar nuestro material.

Registrar una barra lateral personalizada

Pero primero una explicación de cómo Gutenberg maneja las barras laterales personalizadas y por qué necesitamos hacer lo que haremos. Cuando registramos con éxito una barra lateral personalizada, una cosa sucederá automáticamente inicialmente. Gutenberg agregará un acceso directo a nuestra barra lateral en la barra de herramientas superior, junto al menú Herramientas. Esto sucede porque nuestra barra lateral se "fija" automáticamente.

El problema de simplemente agregar una barra lateral personalizada es que cualquier usuario puede "desanclar" este acceso directo. Cuando hacen eso, ¡no hay ningún punto de acceso para abrir la barra lateral nuevamente! Es por eso que también necesitamos agregar un elemento de menú al menú Herramientas.

El registro de una barra lateral personalizada se realiza con el componente PluginSidebardel wp.editPostpaquete. La adición de un elemento de menú al menú Herramientas se realiza con el componente con el nombre apropiado PluginSidebarMoreMenuItem(también en el wp.editPostpaquete).

Para el PluginSidebarcomponente necesitamos proporcionar algunos accesorios. Debe proporcionar como mínimo namey title. El accesorio titlese explica por sí mismo, este es el nombre que aparecerá en la parte superior de la barra lateral. En el accesorio, nameproporcione una babosa única. Cuando agrega el elemento del menú, debe consultar este slug.

Agregar un PluginSidebarMoreMenuItemcomponente (menú de herramientas) requiere como mínimo un accesorio; target. Aquí proporciona el mismo nombre que dio en la propiedad de la barra lateral name. Como contenido del componente, escribe el texto que se mostrará como elemento de menú. Por lo general, esto sería lo mismo que el de la barra lateral title.

Debido a que React requiere un solo nodo envolvente alrededor del retorno del componente, envolvemos todo dentro de un Fragmentcomponente (del wp.elementpaquete). También estoy envolviendo mis cadenas __()del wp.i18npaquete para permitir la traducción.

Con el código anterior, obtendremos las siguientes dos (probablemente tres) cosas que suceden. Obtendrá un acceso directo con el ícono de zanahoria en la barra de herramientas (si aún no lo ha desanclado). Al hacer clic en esto, se abrirá la barra lateral. También tendrá un nuevo elemento de menú en la barra lateral del menú Herramientas, bajo el título "Complementos".

Agregar contenido a la barra lateral

El contenido real de la barra lateral depende totalmente de usted. Solo necesita agregar HTML o componentes dentro del PluginSidebarcomponente con lo que desee (en lugar del texto "Hola").

Puede notar que falta relleno en el contenido de la barra lateral. Esto es intencional porque la idea es que creará paneles dentro de esta barra lateral. Los paneles son las secciones plegables en la barra lateral normal de Gutenberg. Esos son componentes que puede agregar muy fácilmente dentro de su barra lateral personalizada. Puede agregar tantos paneles como desee y son excelentes para agrupar diferentes cosas.

Agregar paneles en nuestra barra lateral

Veamos rápidamente cómo podemos agregar paneles a nuestra barra lateral. Si ha creado sus propios tipos de bloques personalizados, es posible que esté familiarizado con estos componentes. Usamos PanelBodyy opcionalmente PanelRowdel wp.componentspaquete.

Para un PanelBodycomponente, proporciona como mínimo el accesorio title. Opcionalmente, puede proporcionar verdadero o falso a la initialOpenpropiedad para decidir si el panel debe expandirse de forma predeterminada o no. Como contenido dentro del componente está todo dentro del panel.

Dentro de un PanelBodypuede utilizar opcionalmente PanelRowcomponentes. No son realmente necesarios, pero pueden ayudarlo a obtener un buen estilo para el contenido de su panel.

Por ejemplo, agreguemos dos paneles a nuestra barra lateral personalizada.

¡Con este código, nuestra barra lateral personalizada comienza a parecerse realmente a Gutenberg!

Agregar metacampos de publicación a la barra lateral personalizada

Ahora realmente estamos entrando en el meollo de las cosas útiles para una barra lateral personalizada; agregar configuraciones y almacenar sus valores. Pero primero tenemos que entender cómo.

Es realmente fácil agregar campos de configuración (entradas, casillas de verificación, campos de alternancia, etc.) en la barra lateral usando los componentes listos para usar en los paquetes de WordPress. Sin embargo, debemos considerar cómo almacenar los valores. La opción obvia es almacenarlos como post meta. Pero conectar una configuración a un metacampo de publicación requiere un código adicional. Más específicamente, necesitamos usar los llamados componentes de orden superior para obtener y actualizar el metadato de publicación dentro de Javascript. También necesitamos registrar cada publicación meta usando PHP y ponerlas a disposición de la API REST.

Para cerrar este tutorial, demostraré cómo agregar una meta de publicación con una clave awp_my_custom_metaque debe almacenarse como verdadera o falsa. En la barra lateral se mostrará como un campo de alternancia (un componente verdadero/falso).

Registrar post meta para REST API

El primer paso para agregar publicaciones meta en nuestro archivo Javascript es registrarlas y definirlas como accesibles en la API REST. Para ello volvemos a PHP de nuevo.

Dentro de una función enganchada a la initacción usamos la [register_meta](https://developer.wordpress.org/reference/functions/register_meta/)()función. Como parámetros, necesitamos definir el tipo de objeto como " post" porque lo estamos usando como meta de publicación (no excluye, por ejemplo, el tipo de publicación de página). Proporcionamos la clave meta y luego una serie de argumentos. Lo más importante que se debe agregar en la matriz de argumentos es establecer ‘ show_in_rest‘ en true. Post meta se usa comúnmente como ‘ single‘ (piensa cómo lo usas get_post_meta()). También definimos el type. En cuanto a nuestro caso, lo configuramos en ‘ boolean‘.

Con este código, awp_my_custom_metase puede acceder al metacampo de publicación ‘ ‘ desde Gutenberg. Debe repetir el register_meta()meta para cada publicación que desee agregar en su barra lateral.

Ahora volvamos a nuestro Javascript.

Agregar una configuración a nuestra barra lateral

Comencemos con la parte fácil: agregar la entrada a nuestra barra lateral. Más adelante agregaremos más código para conectar realmente el campo de configuración para publicar meta. Debido a la forma en que necesitamos hacer esto, definimos un nuevo componente separado para nuestra configuración. Entonces, dentro del panel en el que desea agregar su configuración, simplemente llame a este nuevo componente.

Llamemos al componente CustomSidebarMetaComponent(podría llamarlo algo relevante para su proyecto). Dentro de este componente queremos representar un campo de alternancia. Para hacer esto usamos el ToggleControlcomponente del wp.componentspaquete. Como accesorios para ToggleControl, proporcionamos una etiqueta adecuada en el titleaccesorio. Un ToggleControl también necesita accesorios onChangepara actualizar el valor y checkedpara el valor actual. Omitiremos estos dos por ahora hasta el próximo paso.

Con el código anterior, debería obtener un campo de alternancia en la barra lateral. No está marcado y no pasa nada cuando haces clic en él. Ese es el siguiente paso: conectarlo a nuestra publicación meta.

Acceder a la publicación meta con withSelect y withDispatch

Para acceder y actualizar un valor meta de publicación, necesitamos usar componentes de orden superior (HOC) para acceder a la versión de tiendas de WordPress (similar a Redux). WordPress nos proporciona algunos HOC útiles con funciones que podemos usar en el wp.datapaquete.

El componente de orden superior [withSelect](https://developer.wordpress.org/block-editor/packages/packages-data/#withSelect)proporciona a nuestro componente accesorios que, en nuestro caso, se obtienen de la publicación meta. Usamos esto para obtener el valor de nuestra publicación meta. Dentro withSelectpodemos usar select('core/editor').getEditedPostAttribute('meta')para obtener el meta de la publicación actual.

Por otro lado, [withDispatch](https://developer.wordpress.org/block-editor/packages/packages-data/#withDispatch)es un componente de orden superior que puede realizar acciones. En nuestro caso, queremos actualizar la publicación meta cuando se cambia la configuración del campo correspondiente en nuestra barra lateral. Dentro de este componente, usamos dispatch('core/editor').editPost()para informar a WordPress para que envíe una acción. Dentro del objeto que proporcionamos le decimos a WordPress que es meta que queremos actualizar.

Finalmente, necesitamos combinar withSelecty withDispatchcon nuestro componente que maneja el metacampo de publicación (CustomSidebarMetaComponent). Para hacer esto usamos WordPress’ composedel wp.composepaquete. La idea es esa withSelecty proporciona accesorios a withDispatchnuestro componente. proporciona el valor de la publicación meta como accesorio y proporciona una función a la que podemos llamar para actualizar el valor como accesorio. Configuramos estos accesorios en nuestro ToggleField y, correspondientemente.CustomSidebarMetaComponent``withSelect``withDispatch``checked``onChange

Eso es mucho de explicar. Veamos el código real:

Empecemos desde el principio. Que está en la parte inferior. En la línea #36, cambiamos el componente que representamos en nuestra barra lateral al componente que creamos con compose(en la línea #15). El CustomSidebarMetacomponente combinará los componentes withSelecty withDispatchy devolverá el CustomSidebarMetaComponent.

El CustomSidebarMetaComponenttendrá acceso a la customPostMetaValueutilería del withSelect, y la setCustomPostMetautilería de withDispatchEstos dos que usamos para la checkedy onChangeutilería en el ToggleField.

Tenga en cuenta que en línea #5agregamos propscomo parámetros a los componentes para que los accesorios sean accesibles en el componente.

Conclusión y palabras finales

Espero que este tutorial te haya servido de algo. Esto es lo que logré comprender sobre el tema durante muchas pruebas y errores. Apenas hay documentación sobre este tema por ahí todavía. Todavía estoy luchando con esto, especialmente cuando se trata de manejar de manera eficiente el meta de múltiples publicaciones. ¡Si logro aprender algunos buenos trucos, actualizaré este tutorial seguro!

Con suerte, al seguir este tutorial, debería tener un código que agregue con éxito una nueva barra lateral personalizada al editor de WordPress Gutenberg y, con suerte, con contenido y configuraciones significativos. Aquí está el código final para la barra lateral personalizada con el metacampo de publicación.