Crear bloque de Gutenberg personalizado – Parte 9: bloques dinámicos y PHP Render

Hasta ahora hemos renderizado la salida del bloque en Javascript. Sin embargo, con contenido dinámico como publicaciones recientes o mostrar una publicación, debemos representar la salida del bloque en PHP. En este post aprenderemos cómo y por qué.

¿Por qué necesitamos manejar los bloques dinámicos de manera diferente?

Algunos ejemplos son obvios; un bloque que muestra las últimas publicaciones en una categoría es dinámico porque las publicaciones cambiarán con el tiempo. No eliges las publicaciones en el bloque; en su lugar, probablemente tendrá configuraciones para elegir la categoría, qué información mostrar para cada publicación, la cantidad de publicaciones, la cantidad de columnas, etc. Cada vez que WordPress carga una publicación con este bloque, debe consultar a WordPress en ese momento para conocer las publicaciones más recientes. Ver la misma publicación el mes siguiente puede arrojar resultados diferentes aunque la publicación con el bloque en sí no se haya actualizado.

Pero la necesidad de bloques dinámicos a veces no es tan obvia. Puede imaginar un bloque de publicaciones destacadas en el que elige una publicación específica para mostrarla, no es necesariamente dinámico. Pero podría ser, y debería serlo. Recuerde que la publicación seleccionada podría actualizar su título, extracto o imagen destacada en cualquier momento, y eso debería reflejarse en los bloques que presentan esta publicación.

Para crear un bloque no dinámico para mostrar una sola publicación, deberá guardar la ID de la publicación, su URL, la URL de la imagen destacada, la cadena de extracto o lo que necesite para obtener una vista previa de la publicación, en los atributos del bloque. Y aquí radica el problema. Si actualiza la imagen destacada de la publicación seleccionada, la publicación con el bloque de publicación destacada no actualizará automáticamente sus atributos. Permanecerá guardado con la URL de la imagen destacada anterior. Solo cuando edite la publicación con el bloque y se asegure de volver a guardar los atributos con la información actualizada, el bloque mostrará la información actualizada correcta.

Entonces, cada vez que tratamos con contenido dinámico (publicaciones, categorías o cualquier cosa que pueda cambiar con el tiempo), estamos tratando con bloques dinámicos. Y para los bloques dinámicos necesitamos usar PHP (código del lado del servidor) para renderizar nuestro bloque y asegurarnos de que recuperará información actualizada cada vez que se renderice.

La naturaleza modificada de los bloques dinámicos en el editor.

Cuando comience a desarrollar bloques dinámicos, la naturaleza de su bloque dentro del editor cambiará. La función de su bloque a editmenudo también debe ser dinámica. Por ejemplo, para un bloque de publicaciones destacadas, deberá buscar publicaciones para elegir, o para un bloque de últimas noticias, deberá recuperar una lista de categorías para que el usuario elija.

Es completamente posible solicitar información de WordPress desde el editor haciendo solicitudes AJAX, ya sea utilizando paquetes y componentes o realizándolos manualmente con la API REST de WordPress. Independientemente del método que elija, su bloque debe manejar el flujo de entrada asíncrono: el período de tiempo mientras espera una respuesta.

Existen múltiples métodos y patrones para crear un bloque dinámico para Gutenberg. Lo más común es que utilice un patrón React llamado componentes de orden superior en el que WordPress proporciona muchas funciones y componentes.

Veremos cómo obtener publicaciones y cómo recuperar categorías en nuestro bloque en la siguiente parte del tutorial. Por ahora, necesitamos aprender cómo hacer que PHP represente nuestro bloque.

Preparando nuestro bloque para el renderizado de PHP

La parte principal que debemos hacer en Javascript es hacer que la savefunción del bloque regrese null. Puede mantener la salida original, pero una vez que le digamos a WordPress que use PHP para representar el bloque, esto será ignorado. Para que quede claro para nosotros y para los demás que la salida del bloque no se maneja en Javascript, cambiaremos la savefunción.

No olvide que cambiar la función de guardar hará que todos los bloques existentes se rompan. Vuelva a agregar el bloque. El bloque debería funcionar como antes; con la configuración y actualizando los atributos. Ahora simplemente no generará nada en la interfaz. El bloque de comentarios estará allí, almacenando todos los atributos en JSON, pero no se representa ningún HTML visible.

Sin embargo; si alguno de sus atributos está usando la sourcepropiedad, debe cambiar esto. Esto no es compatible con los bloques que se procesan con PHP porque se analizan directamente desde la salida del guardado, que ahora volvemos null. Usamos la fuente en el segundo RichTextde nuestro bloque, para el párrafo. En este punto, el editor no guardará lo que hayas puesto en esto RichText.

Entonces, si todavía está usando sourceel myRichTextatributo, debemos eliminar las propiedades sourcey selectorpara asegurarnos de que los atributos se almacenen y no se analicen desde la savefunción:

attributes: {
    ...
    myRichText: {
        type: 'string',
    },
    ...

Después de esto, nuestro bloque está listo para renderizarse en PHP. Podemos dejar los archivos Javascript (no olvides construirlo) y el resto se hace en PHP.

Representación de bloques en PHP

Para decirle a WordPress que renderice la salida del bloque en PHP, agregamos un nuevo argumento a la función register_block_type(). Necesitamos agregar la clave render_callbacka la matriz con un valor de la función que debe ejecutar.

La función de renderizado de PHP

Definamos la función awp_myfirstblock_rendermás abajo functions.php(o donde hayas puesto tu código PHP). Nuestra función obtendrá dos parámetros; los llamaremos $attry $content.

function awp_myfirstblock_render($attr, $content) {
    // return the block's output here
}

El parámetro $attrserá una matriz asociativa con todos los atributos guardados. El segundo parámetro, $content, es para bloques dentro de nuestro bloque. Esto solo es relevante para los bloques que admiten bloques anidados, como, por ejemplo, Columnas o Cubierta.

La función nunca debe echosalir nada. Toda la salida debe devolverse, por lo que debe crear una cadena y devolverla al final.

Algo importante para recordar acerca de los atributos es que solo los atributos guardados aparecerán en el primer parámetro de la función. Si un atributo nunca se cambió ni se guardó, es decir, si solo se basó en su default, el atributo no se incluirá en absoluto para nuestra función PHP.

Debe manejar este problema verificando siempre if (isset($attr['...']))o de la manera preferible: definiendo los atributos en nuestra register_block_type()llamada. Podemos proporcionar otra clave, attributesy establecer su valor en una matriz con todos los atributos que deseamos extraer de nuestro bloque. La estructura debe ser idéntica a la que definió en Javascript, pero en lugar de un objeto Javascript, lo necesita en una matriz de PHP. Esto puede ser un poco engorroso para redefinir los mismos atributos, pero con un editor de código inteligente debería ser bastante rápido copiar y pegar y editarlo en varias líneas en PHP.

Agregar los atributos para nuestra función de renderizado

Agreguemos el nuevo attributeselemento register_block_type()y peguemos exactamente los mismos atributos que definimos en nuestro archivo Javascript:

Tenga en cuenta que si define un defaultpara todos los atributos, el $attrparámetro de su función siempre debe contener todos los atributos. Por ejemplo, el atributo textAlignmentanterior solo existirá $attrsi se modificó, y deberá verificarlo isset($attr['textAlignment']).

Desafortunadamente, en este momento, hay dos cosas que no obtendrá con PHP Block Render. Uno es el classNameaccesorio, por lo que debe crear la clase de envoltura (si la desea) usted mismo. La otra es la supportpropiedad para la alineación de bloques. Por el momento, WordPress no admite esta propiedad en bloques dinámicos. No obtendremos el valor de la alineación del bloque elegido a menos que lo cambiemos a un atributo y lo manejemos manualmente en Javascript.

En cuanto a la salida HTML de la función, ¡esto depende totalmente de usted!

Solicitud de procesamiento de PHP desde el editor interno

Es posible solicitar el render PHP de nuestro bloque dentro del editor. Esto es útil si desea poder obtener una vista previa de la salida del bloque en el editor. Podemos hacer esto con un componente llamado ServerSideRenderdesde el wp.editorpaquete.

Como accesorios ServerSideRender, debe definir todos los atributos que desea transmitir. Como mínimo, debe proporcionar el nombre del bloque a la propiedad block, para que WordPress sepa qué método de renderizado buscar. Esto está disponible para usted en props.namela editfunción. También debe proporcionar los atributos que necesita en el prop attributes. Si lo desea, también puede agregar variables personalizadas fuera de los atributos aquí. Solo tenga en cuenta que esto solo funcionará para el editor interno y no para la interfaz.

No se puede utilizar ServerSideRenderen la función del bloque save. Su savefunción aún debe regresar null.

Implementemos ServerSideRenderen nuestro bloque para verlo en la práctica.

Uso de ServerSideRender para el modo de vista previa/edición de bloques

Si siguió el paso anterior en el que creamos un conmutador de modo de vista previa/edición para nuestro bloque, ahora podemos usarlo ServerSideRenderpara renderizar la vista previa del bloque desde PHP cuando cambiamos al modo de vista previa.

Primero debemos recordar desestructurar ServerSideRenderen la parte superior:

const { ServerSideRender } = wp.editor;

Si recuerda del paso anterior, usamos los componentes Disabledy/o Placeholderpara mantener la vista previa. El problema con el uso Placeholderes que obtenemos un estilo no deseado aplicado a nuestra salida. Reemplacemos Placeholdercon ServerSideRender. Puede optar por mantener el Disabledcomponente, para asegurarse de que no se pueda hacer clic ni arrastrar ninguno de sus contenidos.

En el código para renderizar el bloque cuando el atributo editModees falso, hacemos:

Ahora nuestro botón personalizado en la barra de herramientas mostrará la salida de PHP cuando cambiemos al modo de vista previa. El resultado debe ser idéntico al ver la publicación en la interfaz. Este es un buen hábito para garantizar que la salida sea idéntica tanto en el editor como en la interfaz.

Ejemplo: bloque dinámico que muestra una publicación seleccionada

La salida en su función de procesamiento de PHP puede ser cualquier cosa y tiene acceso completo a todas las funciones de WordPress. Suponga un bloque donde se guardará una ID de publicación en un atributo. En la render_callbackfunción PHP, puede consultar la publicación desde el ID y generar su información. Debería ser bastante autoexplicativo cómo hacer esto, pero aquí hay un ejemplo rápido.

NB: en este ejemplo, simplemente agregaremos una entrada de texto al editor para ingresar manualmente una ID de publicación. Esta no es una solución muy intuitiva y fácil de usar para seleccionar una publicación, pero esto es lo que aprenderemos en el siguiente paso. El enfoque aquí está en la parte PHP de renderizar la publicación seleccionada.

Agreguemos un atributo selectedPostIdde tipo número:

attributes: {
    selectedPostId: {
        type: 'number'
    }
}

Y en algún lugar dentro de la función de nuestro bloque, editagregamos un TextControlcomponente. Puede estar donde quieras: dentro del bloque o en el Inspector.

Tenga en cuenta que tengo mucho cuidado para asegurarme de que la entrada guarde el atributo correctamente como un número al convertirlo en un número entero con parseInt(). Aunque configuramos el tipo prop typepara numberrepresentar una entrada de número, el valor modificado todavía se interpreta como una cadena. WordPress no guardará su atributo si está en el formato incorrecto.

No olvide agregar el nuevo atributo a su ServerSideRendercomponente si tiene uno:

La parte PHP

Eso debería haberse ocupado de la parte de Javascript. Pasemos a PHP. Primero necesitamos agregar el nuevo atributo selectedPostIda la attributesmatriz en register_block_type():

En la render_callbackfunción, ahora podemos acceder al ID de la publicación con $attr['selectedPostId']. Con eso podemos realizar un simple get_post()y generar los datos de la publicación; su enlace y titulo:

Este es un ejemplo muy básico pensado como un trampolín para que escriba código más avanzado y personalizado.

Ahora que sabemos cómo manejar la representación de bloques dinámicos, el siguiente paso es aprender a hacer que la parte del editor también sea más intuitiva. En el siguiente paso, nos centraremos en cómo consultar publicaciones desde el editor de bloques y en brindarle al usuario una mejor manera de seleccionar una publicación.