Crear bloque personalizado de Gutenberg – Parte 4: Atributos

En esta parte, veremos cómo definir atributos, obtener sus valores y actualizarlos. Con los atributos podemos aceptar la entrada del editor, guardarla y generarla como elijamos. En el paso anterior vimos los componentes de WordPress, dónde encontrarlos y cómo implementarlos. En esta publicación, agregaremos accesorios para hacer la conexión con los atributos: los datos guardados.

Definición de atributos

Los atributos se agregan como objetos en una matriz a la attributespropiedad en registerBlockType(). La clave de cada atributo es el nombre del atributo, y debe tener la propiedad typecomo mínimo.

La typepropiedad puede ser cualquiera de las siguientes; null, boolean, object, array, number, string, o integer.

Opcionalmente, puede proporcionar la propiedad defaultpara definir el valor inicial de su atributo. Si no proporciona un valor predeterminado, el atributo será null.

Otra propiedad de atributo es sourceque funciona junto con la selectorpropiedad, pero estas son cosas delicadas que veremos en detalle más adelante.

Por ejemplo, definir dos atributos; exampleTextcomo cadena y postIdscomo matriz, se vería así:

Cualquier cosa que necesite guardar para su bloque (entrada del usuario/editor) requiere un atributo. Depende de usted cómo estructura sus datos, definiendo atributos separados para cada uno o agrupándolos todos en un objeto. Solo será una diferencia en cómo obtienes sus datos y cómo los actualizas.

Obtener valores de atributo

Los atributos están disponibles como accesorios para sus bloques edity savefunciones. Si ha seguido esta serie del paso anterior, recuerde que actualizamos las funciones para pasar props como parámetro.

Es común desestructurar los atributos de los accesorios, ya que normalmente se refiere a ellos con frecuencia. Por ejemplo, la salida de un atributo llamado exampleTextse vería así:

Actualizar valores de atributos

Para actualizar atributos tenemos un método disponible en props, llamado setAttributes(). Esta función acepta un objeto donde puede agregar cualquier atributo que desee actualizar. Puede actualizar solo un atributo, más o todos a la vez. Si tiene varios atributos definidos y llama setAttributes()para actualizar solo uno de ellos, los otros no se tocan.

Si tiene experiencia con React, probablemente reconocerá inmediatamente las similitudes entre setAttributes()y setState(). Funcionan exactamente igual, pero la diferencia es que el estado en React es simplemente algo almacenado localmente en ese componente, y los atributos en realidad se guardan como datos fuera del componente.

Para actualizar un atributo, generalmente destruiría la función de accesorios y la llamaría así: A continuación, actualizamos exampleTextel atributo para que sea "Hola".

const { setAttributes } = props;
setAttributes({ exampleText: 'Hi' });

Naturalmente, ejecutaría setAttributes()desde dentro alguna acción. Un ejemplo común está dentro de la onChangepropiedad en algún tipo de campo de entrada que se usa para almacenar el valor del exampleTextatributo.

Asegúrese de guardar los atributos en el tipo que ha definido en el atributo. No tendrá suerte tratando de guardar objetos en un atributo de cadena, por ejemplo.

¡Probémoslo en la práctica! Inicie npm run startsi aún no lo ha hecho.

Mostrar un atributo en una entrada de texto personalizada y actualizar el valor del atributo

En el paso anterior, agregamos algunos componentes edit, por ejemplo, una entrada de texto, pero no se almacenó nada. Agreguemos un atributo y una entrada de texto en nuestro bloque. Ambos nos aseguraremos de que la entrada de texto muestre el valor actual, y cada vez que se cambie la entrada, actualizaremos el atributo.

Agregar la entrada de texto y su onChangeaccesorio

Desestructuramos attributesy setAttributesde propscomo usaremos ambos. Luego usamos un componente del paquete TextControlde WordPress. wp.componentsLe pasamos dos puntales; valueestablecerá el valor de la entrada (tanto inicialmente como mientras escribimos) y una acción en el evento de la entrada onChange.

En valuelo fijamos al valor de nuestro atributo; attributes.exampleText. En el onChangecaso de que ejecutemos una función, pasando el valor escrito de nuestra entrada como parámetro newtext(el valor de entrada es un accesorio que se devuelve desde el componente). En esa función llamamos setAttributes()y actualizamos el atributo exampleTexta lo que se escribió en la entrada.

Esto es React básico, aparte del hecho de que trabajamos con atributos y no con estados. Si lo anterior te confundió, te recomiendo que consultes un tutorial rápido en React, ¡ya que probablemente te lo explicarán mejor que yo!

¡Actualiza tu editor y mira cómo funciona el bloque! Debería obtener una entrada de texto estándar para escribir cosas, y se guardará cada vez que presione Guardar/Actualizar en la edición posterior.

El resultado en frontend y en la base de datos.

Si ve su publicación en la interfaz, aún debería hacer eco de un div con ":)" porque eso es lo que todavía tenemos en nuestra savefunción. ¡Pero algo ha sucedido detrás de escena! El bloque de comentarios de nuestro bloque ahora contiene el valor de nuestro atributo en JSON.

No puede ver los bloques de comentarios en una plantilla que realiza una the_content()llamada normal. Para ver los bloques de comentarios tienes dos opciones. O mire en la post_contenttabla de la base de datos de publicaciones. O agregue echo get_the_content()la plantilla y mírela en la herramienta Inspeccionar/depurar.

Obviamente, también tenemos acceso a los atributos save, desde props.

Mostrar el valor de la entrada ensave

Mostremos el valor del atributo dentro de un div en nuestra savefunción:

Nota: Después de hacer este cambio, obtendrá un bloque roto en la publicación a la que ya ha agregado este bloque. Esto sucede porque el editor encuentra una salida diferente a la saveque hemos definido ahora. Retire el bloque y vuelva a agregarlo. Ingrese algo en su entrada de texto, actualice la publicación y visualícela en la interfaz.

Y esta es la esencia de esto en realidad. Tú decides qué atributos necesitas para guardar lo que quieras en tu bloque. En editél, presentará formas para que el usuario ingrese, teniendo cuidado de que se muestren los valores actuales y actualícelos cada vez que cambien. Y saveextrae los atributos guardados y renderiza la salida como quieras.

Abordaremos muchos más componentes y atributos diferentes a medida que avanzamos en esta serie de tutoriales. Pero veamos otro componente en esta publicación para ver de qué sourcese trata la propiedad de atributo.

RichText y la propiedad de atributosource

El componente de WordPress RichTextle brinda un área de texto "sin bordes" con soporte para formato de texto. Es posible que prefiera usar esto en lugar de una entrada de texto estándar o un área de texto (¿feo?). Pero tenga en cuenta que RichTextdebe manejarse de manera un poco diferente, ya que hay varios accesorios que debe tener en cuenta, y hay una diferencia en la forma en que obtenemos el valor en nuestra savefunción.

Agregar un RichTextcomponente

La forma más simple de RichTextimplementarlo es como lo harías con una entrada de texto:

Desestructuramos el RichTextcomponente del wp.blockEditorpaquete, pero por lo demás, lo anterior es idéntico a lo que hicimos con la entrada de texto estándar.

Manejo saveconRichText

Sin embargo, en la savefunción, debe usar el RichTextcomponente nuevamente para obtener el valor del atributo. Llamamos RichText.Contenty configuramos el accesorio valuea nuestro atributo:

Esto generará lo que se haya escrito en el RichTexteditor directamente sin ningún código HTML.

Cuando trabaja con RichTextusted, lo más probable es que desee controlar el contenedor HTML alrededor del texto, por ejemplo, a <p>o a <h2>, tanto en la interfaz como en el editor. Para eso podemos usar un accesorio llamado tagName.

El componente RichTexttambién permite varios otros accesorios. Puede definir un texto de marcador de posición que se muestra (desvanecido) cuando está vacío con la placeholderpropiedad. El componente también le permite controlar qué opciones de formato permite el campo (qué botones muestra en la barra de herramientas).

RichTextcontagName

Con el accesorio tagName, puede predefinir en qué etiqueta HTML se envuelve su salida. Cuando lo use tagName, debe usar el mismo tagNameaccesorio y valor en ambos edity save.

Digamos que desea poner el valor de su atributo en a <h2>, lo que en el editor forzará que cualquier entrada sea h2. En editpuedes hacer:

Y en save:

Lo anterior ahora generará lo que se haya escrito en el RichTextárea dentro de una <h2>etiqueta.

Usandosource

Obviamente, puede combinar varios textos enriquecidos para un bloque, por ejemplo, uno para encabezado y otro para párrafo. Solo recuerda que cada uno necesitará su propio atributo. Por ejemplo:

Sin embargo, ahora comenzará a encontrar algunos problemas. Aunque puede formatear texto en el editor, no se guardará nada (o parte) de su formato. Cuando vea la publicación en la interfaz, simplemente aparecerá como h2y un p, sin ningún formato que haya hecho (cursiva, negrita, enlace). Ni siquiera el bloque de comentarios de su bloque contiene el formato. Esto es lo complicado con RichText. Para solucionar esto necesitamos trabajar con el atributo property source.

La sourcepropiedad que permite a WordPress extraer e interpretar el contenido directamente del contenido de la publicación. Si un atributo no está sourceconfigurado, se guardará y se extraerá del bloque de comentarios HTML.

Cuando trabajamos con RichText, generalmente establecemos, sourceque htmlusa la biblioteca de WordPress para analizar el marcado HTML. La propiedad sourcefunciona junto con otra propiedad de atributo; selectorque define de qué etiqueta HTML se debe extraer.

Como ejemplo, establecemos sourcecomo htmlen nuestro párrafo RichTexty establecemos selectorcomo p(de lo contrario, el valor predeterminado es root o block the block).

attributes: {
    ...
    myRichText: {
        type: 'string',
        source: 'html',
        selector: 'p'
    }
},

Ahora nuestro segundo RichTextdebería guardar con éxito todo su formato de texto. También notará que el bloque de comentarios ahora solo muestra el myRichHeadingatributo en JSON. El atributo myRichTextha desaparecido por completo del bloque de comentarios. Esto se debe a que sourceWordPress ahora analiza el contenido de la publicación en lugar del bloque de comentarios para el valor del atributo.

Para ser completamente honesto, no he trabajado tanto con el sourceatributo y recomendaría evitarlo si puede. La documentación de WordPress explica algo más sobre la fuente y los atributos que desea comprobar por sí mismo.

En esta publicación, hemos aprendido los conceptos básicos sobre los atributos; cómo definirlos, actualizarlos y generar sus valores. En los próximos pasos, veremos más componentes diferentes y cómo agregar configuraciones fuera del contenido del bloque en sí; en la barra de herramientas y la barra lateral del editor (llamada Inspector).