Cómo crear tu primer bloque para Gutenberg

Publicada en WordPress.

Ni el constante crecimiento en el número de webs que eligen WordPress como gestor de contenidos ni su posición dominante en el mercado han hecho que la comunidad de desarrolladores se relaje. WordPress va a cambiar mucho en muy poco tiempo. Y el mayor cambio en WordPress se llama Gutenberg.

En este artículo te voy a hablar de Gutenberg y te voy a mostrar cómo introducirte en su desarrollo creando tu primer bloque, un concepto que sin duda vas a tener que dominar si piensas seguir ganándote la vida con WordPress los próximos años. ¡Empezamos!

¿Qué es Gutenberg?

Gutenberg es el nuevo editor de contenidos de WordPress. Pero es mucho más que eso. Gutenberg va a cambiar la manera en la que tanto los usuarios como los desarrolladores trabajamos con WordPress.

Hasta ahora estarás acostumbrado a utilizar el editor de WordPress como si de un documento de Microsoft Word se tratase. Pues esto cambia y aparece en escena el concepto de bloque. Ahora tus contenidos en WordPress estarán compuestos por bloques. Tendrás bloques para párrafos, para imágenes, para encabezados, para citas, y mucho más. Además, la comunidad de desarrolladores se va a volver loca creando plugins que añadan bloques nuevos.

Si quieres una primera impresión de la pinta que tiene Gutenberg, no te pierdas el siguiente vídeo donde Matías Ventura, el lead developer de WordPress, te hace una demo de las funcionalidades principales durante la WordCamp US de 2017:

Además, ten en cuenta que Gutenberg no se queda solo en el editor de contenidos de WordPress. La evolución va más allá. En próximas iteraciones del desarrollo, el concepto de bloque va a sustituir otros conceptos ya conocidos en WordPress como son los widgets y los menús. En WordPress pronto todo van a ser bloques. De ahí mi interés en enseñarte a crear uno básico.

Instalar y activar Gutenberg

Se dice, se comenta, que Gutenberg estará listo para ser incluido en la versión 5.0 de WordPress, para Abril de 2018. Pero creo que vamos a tener que esperar un poco más hasta que Gutenberg acabe dentro de WordPress (¿apostamos?).

Ahora mismo si quieres probar Gutenberg tendrás que instalar un plugin. Pero ojo, no te recomiendo que lo hagas en tu instalación de WordPress de producción, ya que todavía está en pleno desarrollo y se te pueden romper cosas. Pruébalo en una instalación de test que tengas disponible.

Pantalla de edición de una entrada con el nuevo editor Gutenberg para WordPress.
Pantalla de edición de una entrada con el nuevo editor Gutenberg para WordPress.

Sólo has de instalar el plugin de Gutenberg, activarlo e ir a editar una entrada o página. Por cierto, me encantará que me dejes en los comentarios tu opinión después de probarlo, ya que ha habido mucha controversia con todo esto.

Vamos a crear un nuevo bloque para Gutenberg

Ahora que ya sabes lo que es Gutenberg, adentrémonos en el maravilloso mundo del código. Para ello, vamos a plantearnos crear un bloque nuevo para Gutenberg que nos permita añadir un testimonio de un cliente en nuestra web.

El testimonio contará con una foto de la persona que da el testimonio, su nombre y cargo, además del propio texto del testimonio. El resultado final que queremos será parecido al siguiente:

Mockup del nuevo bloque de testimonio que vamos a añadir a WordPress.
Mockup del nuevo bloque de testimonio que vamos a añadir a WordPress.

¡Vamos a por faena!

Crear el plugin y la estructura de archivos

Primero de todo vamos a crear un plugin para WordPress que incluya los archivos necesarios para tener un nuevo bloque en Gutenberg. Para ello crea una estructura de archivos y directorios como la siguiente:

Estructura de archivos para el plugin que añade el bloque de testimonio en Gutenberg.
Estructura de archivos para el plugin que añade el bloque de testimonio en Gutenberg.

Permíteme que haga un repaso a los archivos más relevantes y para qué sirven:

  • block/testomonial/index.php: se encarga de encolar los archivos que definen el block y lo muestran tanto en el backend como en el frontend de WordPress.
  • block/testimonial/block.js: definición del bloque de testimonio y su comportamiento al editar y guardar. Es el archivo más importante en cuanto al bloque se refiere.
  • block/testimonial/editor.css: estilos CSS para el bloque de testimonio que aplican al editar el bloque desde Gutenberg.
  • block/testimonial/style.css: estilos CSS para el bloque de testimonio que aplican al frontend, cuando visualizamos el resultado final del bloque en nuestro contenido.
  • nelio-testimonial-block.php: es el archivo principal del plugin, donde se definen las cabeceras necesarias para describir el plugin e incluir el archivo index.php. Puedes verlo aquí.

Tienes todo el código del plugin subido en GitHub.

Encolando los archivos necesarios

Una vez tienes los archivos creados y la estructura del plugin funcionando, lo importante es poder encolar tanto los archivos CSS como el archivo JavaScript como Gutenberg necesita. Esto lo hacemos en el archivo block/testomonial/index.php y tiene la siguiente pinta (ver código en GitHub):

Fíjate que básicamente encolamos en dos hooks: enqueue_block_editor_assets y enqueue_block_assets. El primer hook es para incluir los archivos que utilizamos dentro del editor de Gutenberg. Aquí metemos block.js y editor.css. Y en el segundo hook metemos los estilos del frontend (archivo style.css).

A destacar aquí que en el archivo JavaScript block.js, que es el que define el bloque, añadimos como dependencias wp-blocks, wp-i18n y wp-element, que son necesarios para trabajar con bloques, elementos e internacionalización.

Registrando el nuevo bloque

Pasamos ahora al archivo block.js (link al archivo en GitHub) donde vamos a registrar el nuevo bloque de testimonio. Para ello, utilizamos la llamada registerBlockType de Gutenberg, que sirve exactamente para eso, registrar un nuevo bloque en el editor:

No te asustes, vamos a ir pasito a pasito. Primero ponemos un nombre interno al bloque, en nuestro caso, 'nelio/testimonial-block'. Y luego le pasamos un objeto con todas las propiedades del bloque. A destacar el título (línea 10), icono (línea 13), categoría del bloque (línea 16) y atributos (líneas 19 a 47).

Los atributos son las características que contendrá el bloque. En nuestro caso, el bloque de testimonial tendrá lo siguiente:

  • name: nombre de la persona que hace el testimonio.
  • position: cargo de la persona que hace el testimonio.
  • testimonial: el texto del testimonio.
  • mediaID: ID de la imagen en la biblioteca de medios de WordPress.
  • mediaURL: URL de la imagen de la persona del testimonio.
  • alignment: alineación del texto del bloque.

Aquí es importante darse cuenta que para los atributos que se asocian con un elemento HTML del bloque de testimonio hemos de poner un selector. Y este ha de ser único. Si por ejemplo tenemos varios atributos que se asocian con etiquetas <p> dentro del bloque, cada uno ha de tener un selector diferente (lo puedes hacer con nombres de clases CSS diferentes) o sino Gutenberg te dará un error al abrir el contenido.

Y por último tenemos las funciones de edición y guardado del bloque. Pero esto lo vamos a explicar en más detalle a continuación.

El método edit

Aquí es donde empieza lo bueno. El método edit permite montar el bloque para su edición dentro de Gutenberg. Básicamente, este método devuelve un componente React formado por todos los componentes que queremos que aparezcan en el editor. Tiene esta pinta:

Si vas poco a poco, verás que tampoco es tan complicado. Vas anidando elementos con la función el() y de esta forma defines el HTML que forma el bloque. Por ejemplo, si miras las líneas 79 a 91, veras que definimos la etiqueta <p> que contiene el cargo (position, en inglés) de la persona que hace el testimonio. Se define la clase del elemento (nelio-testimonial-position), un placeholder para mostrar (Position, que es internacionalizable), el valor del elemento (que lo coges de los atributos del bloque definidos previamente) y las funciones onChange y onFocus para actualizar el valor del atributo y controlar su foco.

A parte de esto, hay alguna peculiaridad adicional, como el hecho de tener un botón para abrir el selector de imágenes de la biblioteca de medios. Esto lo puedes ver en las líneas 37 a 47, donde hacemos uso de blocks.MediaUpload, que ya es un componente reutilizable del propio Gutenberg. Y las líneas de la 22 a la 30 añaden otro componente también reutilizable: la barra donde poder cambiar la alineación del texto.

El método save

El método save se encarga de coger la información y prepararla para guardarla en el contenido dentro de la base de datos. Es bastante más sencillo que edit y tiene la siguiente pinta:

Fíjate que construimos un elemento div que contiene dos divs más dentro. El primero tiene la imagen del testimonio y el segundo los tres párrafos con el texto del testimonio, el nombre del que dice el testimonio y el cargo.

Añadiendo estilo al bloque

Si no hacemos nada más, el resultado en el editor es tal que así:

Bloque para testimonio sin estilos CSS para el editor (editor.css está vacío).
Bloque para testimonio sin estilos CSS para el editor (editor.css está vacío).

Si añadimos valores al texto y seleccionamos una imagen, el resultado que vemos dentro del editor es este:

Si añadimos valores al bloque, vemos que la imagen hace que todo se desborde. No hay estilos CSS definidos.
Si añadimos valores al bloque, vemos que la imagen hace que todo se desborde. No hay estilos CSS definidos.

Y si publicamos la entrada y la vamos a ver, esto es lo que verán nuestros visitantes:

Lo que ven nuestros usuarios no es lo que queríamos en nuestro mockup inicial. Debemos usar CSS ya que style.css está vacío.
Lo que ven nuestros usuarios no es lo que queríamos en nuestro mockup inicial. Debemos usar CSS ya que style.css está vacío.

Para darle un mejor aspecto y mejorar la usabilidad, añadimos estilos CSS para el editor y para el frontend. Exacto, estamos hablando de los archivos editor.css y style.css. Puedes ver su contenido directamente en GitHub.

Gracias al estilo, el bloque en el editor ahora tiene esta pinta:

Añadiendo CSS al editor.css podemos lograr tener algo mucho más parecido a lo que habíamos esbozado en nuestro mockup.
Añadiendo CSS al editor.css podemos lograr tener algo mucho más parecido a lo que habíamos esbozado en nuestro mockup.

Y nuestros visitantes lo que ven ahora tiene más gracia:

Los visitantes de nuestra web verán el bloque correctamente cuando añadimos los estilos CSS oportunos a style.css.
Los visitantes de nuestra web verán el bloque correctamente cuando añadimos los estilos CSS oportunos a style.css.

Repaso final

Crear un bloque nuevo en Gutenberg puede ser complicado, pero hay que ir paso a paso e ir aumentando la dificultado poco a poco. Recuerda que básicamente entran en juego 3 archivos.

El primero es un archivo JavaScript donde definir el bloque, sus atributos y los métodos save y edit. Esta es la parte más complicada. En nuestro ejemplo hemos usado JavaScript básico, pero es más fácil si utilizamos sintaxis JSX para definir los componentes React. Si os parece interesante, podemos rehacer el bloque de testimonio usando JSX en una entrada futura. ¡Ya me diréis!

Los otros dos archivos importantes son los que definen los estilos tanto del editor como del frontend: editor.css y style.css. Ya habéis visto que un poco de CSS puede dar un cambio radical al resultado final. Os animo a que probéis el código y lo mejoréis.

Recursos

Antes de terminar, permíteme que te deje un listado de recursos de interés por si les quieres echar un ojo y aprender mucho más sobre Gutenberg. Recuerda que pronto lo tendremos en todos los WordPress del mundo mundial, así que más vale que estés preparado para ello.

Me despido por hoy con esta lista. Espero que te sirva:

Imagen destacada de Caleb Woods vía Unsplash.

FlojaNo está malBienMuy bien¡Impecable! (4 votos, promedio: 5,00 de 5)
Cargando…

9 comentarios en «Cómo crear tu primer bloque para Gutenberg»

  1. Buenas Antonio,

    Te lo has currado la verdad y mucho porque ahora mismo hay poco sobre el tema.

    Conclusiones que saco después de leerme tu artículo:

    1) Hay que aprender ReactJS
    2) Veo más complejo definir un bloque que un metabox con sus campos
    3) Entiendo que el rendimiento del bloque es sumamente más rápido que renderizar un metabox y sus variables por ir en ReactJS

    Gracias por acercarnos Guttenberg!
    Saludos!

    1. ¡Gracias Jorge! Pues sí, es bastante trabajo escribir entradas así. Toca aprender un poquito de ReactJS, aunque espero que la documentación de Gutenberg mejore bastante en los próximos meses. Ahora mismo a mi me parecen los metaboxes más sencillos, pero bueno, todo irá evolucionando para que no tengamos que sudar para añadir un bloque. En cuanto a rendimiento, entiendo que sí, será mejor con bloques al ser JavaScript y no PHP, pero lo iremos viendo. La conclusión que has de sacar es que todavía está todo muy verde. Aún le falta un poco de madurez.

  2. Que gran artículo, que nos abre un poco más los ojos para los cambios que se avecinan con el colega Gutenberg.
    Lo que está claro es que hay que aprender ReactJS si o si.
    A ver si podeis realizar esa entrada escribiendo utilizando JSX que nos abra más aún los ojos.

    Gran artículo y gran blog.

    Saludos

    1. Gracias Gabri. Hay que ponerse las pilas, no queda otra. Intentaremos escribir la entrada hablando de JSX lo antes posible 😉

  3. Hola,
    lo primero gracias por la explicación.

    Estoy modificando el ejemplo para hacerme un bloque similar para experiencia laboral y estudios y se me maqueta bien, se guarda, se muestra en el frontal, pero cuando voy a editar la página para añadir un nuevo elemento me dice

    Este bloque se ha modificado externamente.

    Cuando dicho bloque no se ha modificado externamente de ninguna manera.

    Gracias por la ayuda.

    1. Hola GoldraK. Gutenberg sigue en fase de desarrollo y es posible que hayan habido cambios recientes que rompan el código del ejemplo. En el repositorio de Github hice unos cambios recientemente gracias a la sugerencia de otra persona que tuvo problemas.

      1. Gracias por contestar, me esperare a que acaben de jugar antes de volverme loco con ello. 🙂

Deja un comentario

No publicaremos tu correo electrónico. Los campos obligatorios están marcados con: •

He leído y acepto la Política de privacidad de Nelio Software

Al marcar la casilla de aceptación estás dando tu legítimo consentimiento para que tu información personal se almacene en SiteGround y sea usada por Nelio Software con el propósito único de publicar aquí este comentario. Contáctanos para corregir, limitar, eliminar o acceder a tu información.