Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. WordPress Gutenberg
Code

Bloque de WordPress Gutenberg API: Creación de Bloques Personalizados

by
Difficulty:IntermediateLength:LongLanguages:
This post is part of a series called WordPress Gutenberg Block API.
WordPress Gutenberg Block API: Block Look and Feel
WordPress Gutenberg Block API: Extending Blocks

Spanish (Español) translation by James (you can also view the original English article)

El nuevo editor de WordPress (codenamed Gutenberg) está previsto que salga en versión 5.0. Ahora es el momento perfecto para conseguir a los apretones con él antes de aterriza en el núcleo de WordPress. En esta serie, te muestro cómo trabajar con la API de bloque y crear sus propios bloques de contenido que se pueden utilizar para construir sus mensajes y las páginas.

En el post anterior vimos cómo utilizar el kit de herramientas de create-guten-block para crear un plugin que contiene un bloque de muestras listo para trabajar con. Fácilmente podemos extender esto como sea necesario, pero es una buena idea para saber cómo crear un bloque desde el principio para entender todos los aspectos de desarrollo del bloque de Gutenberg.

En este post vamos a crear un segundo bloque en nuestro plugin my-custom-block para mostrar una imagen aleatoria desde el servicio web de PlaceIMG. Usted también podrá personalizar el bloque seleccionando la categoría de la imagen de un control de selección desplegable.

Pero en primer lugar aprenderemos cómo bloquear secuencias de comandos y estilos son cola antes de pasar a la función registerBlockType() muy importante, que es fundamental para crear bloques en Gutenberg.

Enqueueing Secuencias de Comandos y Estilos de Bloque

Para agregar el JavaScript y CSS requeridos por nuestros bloques, podemos utilizar dos ganchos de WordPress nuevo proporcionados por Gutenberg:

  • enqueue_block_editor_assets
  • enqueue_block_assets

Sólo están disponibles si está activo el plugin de Gutenberg, y funcionan de manera similar a ganchos estándar de WordPress para secuencias de comandos de enqueueing. Sin embargo, se destinan específicamente para trabajar con bloques de Gutenberg.

El gancho de enqueue_block_editor_assets agrega scripts y estilos al editor admin solamente. Esto es ideal para enqueueing JavaScript para registrar bloques y CSS a elementos de interfaz de usuario estilo para configuración de bloque.

Para la salida del bloque, sin embargo, usted querrá sus bloques para hacer lo mismo en el editor como lo hacen en la parte delantera la mayor parte del tiempo. Uso enqueue_block_assets hace fácil como estilos se añaden automáticamente al final del editor y la frente. También puede utilizar este gancho para cargar JavaScript si es necesario.

Pero tal vez se pregunte cómo poner scripts y estilos solo en la parte delantera. No hay un gancho de WordPress para que pueda hacer esto directamente, pero usted puede conseguir alrededor de esto agregando una instrucción condicional dentro de la función de devolución de llamada de gancho enqueue_block_assets.

Realmente poner scripts y estilos utilizando estos dos ganchos nuevos, puede utilizar las funciones estándar de wp_enqueue_style() y wp_enqueue_scripts() como lo haría normalmente.

Sin embargo, necesita asegurarse de que está utilizando las dependencias de la escritura correcta. Enqueueing secuencias de comandos en el editor, puede utilizar las siguientes dependencias:

  • scripts: array( 'wp-blocks', 'wp-i18n', 'wp-element', 'wp-components' )
  • estilos: array ('wp-editar-blocks')

Y cuando enqueueing estilos para el editor y el front-end, se puede utilizar esta dependencia:

  • array ('wp-blocks')

Una cosa vale la pena mencionar aquí es que la cola de archivos de nuestro plugin de my-custom-block son las versiones compiladas de JavaScript y CSS y no los archivos que contienen el código fuente JSX y Sass.

Esto es algo a tener en cuenta cuando manualmente archivos de enqueueing. Si se intenta poner crudo código que incluye reaccionar, ES6 +, o Sass y luego te vas a encontrar numerosos errores.

Esto es por qué es útil utilizar un conjunto de herramientas tales como create-guten-block procesos y secuencias de comandos de cola para usted automáticamente!

Registro de Bloques de Gutenberg

Para crear un nuevo bloque, tenemos que registrar con Gutenberg llamando registerBlockType() y pasando el nombre de bloque más un objeto de configuración. Este objeto tiene bastantes propiedades que requieren de explicación adecuada.

Sin embargo, en primer lugar, echemos un vistazo en nombre del bloque. Este es el primer parámetro y es una cadena compuesta de dos partes, un espacio de nombres y el nombre de bloque, separada por un carácter de barra diagonal.

Por ejemplo:

Si está registrando unas manzanas en un plugin puede utilizar el mismo espacio de nombres para organizar todos sus bloques. El espacio de nombres debe ser único para tu plugin, sin embargo, que ayuda a evitar conflictos de nombres. Esto puede ocurrir si un bloque con el mismo nombre ya ha sido registrado mediante otro plugin.

El segundo parámetro de registerBlockType() es un objeto de ajustes y requiere una serie de propiedades que se especificará:

  • title (string): aparece en el editor de la etiqueta del bloque de búsqueda
  • description (cadena opcional): describe el propósito de un bloque
  • icon (elemento opcional Dashicon o JSX): icono asociado con un bloque
  • Category (string): donde el bloque aparece en el cuadro de diálogo de Agregar bloques
  • keywords (array opcional): hasta tres palabras clave utilizadas en las búsquedas de bloque
  • attributes (objeto opcional): maneja los datos de bloque dinámico
  • edit (función): una función que devuelve el marcado que procesa en el editor de
  • save (función): una función que devuelve el marcado que procesa en la parte delantera
  • useOnce (boolean opcional): restringir el bloque se añaden más de una vez
  • supports (objeto opcional): define características respaldados por el bloque

Suponiendo que estamos utilizando JSX para desarrollo de bloque, aquí lo que una llamada de registerBlockType() de ejemplo podría parecer un bloque muy sencillo:

¿Observa cómo no incluimos una entrada para la propiedades descriptionattributesuseOnce, y supports? Los campos que son opcionales (y no relevante para su bloque) pueden omitirse con seguridad. Por ejemplo, como este bloque no implica cualquier datos dinámicos, no necesita preocuparse de especificar todos los atributos.

Vamos a ahora cubre las propiedades del objeto de configuración de registerBlockType() más detalladamente uno por uno.

Título y Descripción

Cuando se inserta o buscando un bloque en el editor, el título se mostrará en la lista de bloques disponibles.

También se muestra en la ventana de inspector de bloque, junto con la descripción del bloque si. Si el inspector del bloque no es actualmente visible puede utilizar el icono de engranaje en la esquina superior derecha del editor de Gutenberg para alternar visibilidad.

Block title and description

El título y la descripción de campos idealmente deben estar envueltos en funciones de i18n para permitir la traducción a otros idiomas.

Categoría

Hay cinco categorías de bloque disponibles actualmente:

  • común
  • formato
  • diseño
  • widgets
  • Insertar

Determinan la sección de la categoría que su bloque se cotiza dentro de la ventana de Añadir bloque.

Block categories

La ficha de Bloques contiene categorías de Bloques Comunes, Formato, Widgets y Elementos de Diseño, mientras que la categoría de Embeds tiene su propia pestaña.

Categorías se fijan actualmente en Gutenberg, pero esto puede variar en el futuro. Esto sería útil, por ejemplo, si estaban desarrollando varios bloques en un solo plugin y quisiste a todos a figurar bajo una categoría común, por lo que los usuarios podrían localizarlos más fácilmente.

Icono

Por defecto, el bloque se asigna el escudo Dashicon, pero esto puede anular especificando un Dashicon personalizado en el campo de icono.

Dashicons

Cada Dashicon es el prefijo dashicons- seguido por una cadena única. Por ejemplo, el icono de engranaje tiene el nombre dashicons-admin-genérico. Para utilizar esto como un icono de bloque, basta con retirar el prefijo dashicons- para que sea reconocido, por ejemplo, icon: 'admin-generic'.

Sin embargo, no está sólo limitada al uso de Dashicons como la propiedad de icono. La función acepta un elemento JSX, que significa que puede usar cualquier imagen o elemento SVG como su icono de bloque.

Sólo asegúrese de mantener el tamaño de icono consistente con otros iconos de bloque, que es de 20 x 20 píxeles por defecto.

Palabras Clave

Elige hasta tres palabras traducibles para ayudar a que su bloque se destacan cuando los usuarios buscan un bloque. Es mejor elegir las palabras claves que estrechamente se relacionan con la funcionalidad de su bloque para obtener mejores resultados.

Incluso podría declarar su nombre de compañía o plugin como palabras clave para que si tienes varios bloques, usuarios pueden empezar a escribir su nombre de la empresa y todos sus bloques aparecerán en los resultados.

Aunque añadir palabras clave es totalmente opcional, es una gran manera de hacerlo más fácil para los usuarios encontrar sus bloques.

Atributos

Atributos de ayudan con el manejo de datos dinámicos en un bloque. Esta propiedad es opcional mientras que usted no necesita para bloques muy sencillos que había salida de contenido estático.

Sin embargo, si trata de su bloque de datos que podrían cambiar (por ejemplo, el contenido de un área de texto editable) o necesita almacenar la configuración del bloque, luego utilizando atributos es el camino a seguir.

Atributos de trabajo almacenamiento de datos de bloque dinámico en el contenido del post guardado a la base de datos o en post meta. En este tutorial solo utilizaremos atributos que almacenan datos junto con el contenido del post.

Para recuperar datos de los atributos almacenados en el contenido del post, necesitamos especificar donde se encuentra en el marcado. Podemos hacerlo especificando un selector CSS que apunta a los datos de atributo.

Por ejemplo, si nuestro bloque contiene una etiqueta de ancla, podemos usar su campo de title como nuestro atributo como sigue:

Aquí, el nombre del atributo es linktitle, que es una cadena arbitraria y puede ser cualquier cosa que te gusta.

Por ejemplo, podríamos utilizar este atributo para almacenar el título del enlace <a title="some title"> que se han introducido a través de un cuadro de texto de configuración del bloque. Haciendo así, de repente hace dinámico el campo título y le permite cambiar su valor en el editor de.</a>

Cuando se guarda el mensaje, el valor del atributo se inserta en el campo de title de enlaces. Del mismo modo, cuando el editor se carga, el valor de la etiqueta title es obtenido del contenido e insertado en el atributo linktitle.

Hay más maneras de utilizar source para determinar cómo bloque contenido es almacenado u obtenido por medio de atributos. Por ejemplo, puede utilizar la fuente de 'texto' para extraer el texto interno de un elemento de párrafo.

También puede utilizar la fuente de los hijos para extraer todos los nodos secundarios de un elemento en un array y guarde en un atributo.

Esto selecciona el elemento con clase .parent y almacena todos los nodos secundarios en el atributo editablecontent.

Si no se especifica una fuente el valor del atributo se guarda en los comentarios HTML como parte de la anotación de correos cuando guarda la base de datos. Estos comentarios se pelan hacia fuera antes de que el mensaje se procesa en la parte delantera.

Nos veremos un ejemplo concreto de este tipo de atributo cuando nos metemos en la implementación de nuestro bloque de imagen aleatoria más adelante en este tutorial.

Atributos puede tomar un poco acostumbrarse, así que no se preocupe si no entiende completamente los primera vez. Recomiendo echar un vistazo a la sección de atributos del manual de Gutenberg para más detalles y ejemplos.

Editar

La función edit controla cómo aparece su bloque dentro de la interfaz del editor. Dinámico de datos se pasa a cada bloque como props, incluyendo los atributos personalizados que se hayan definido.

Es una práctica común añadir className = {props.className} para el elemento del bloque principal para una clase CSS específica para su bloque de salida. WordPress no añade esto para usted en el editor, por lo que debe agregarse manualmente para cada bloque si desea incluirlo.

Utilizando props.className es una práctica estándar y es recomendable ya que proporciona una manera de adaptar estilos CSS para cada bloque individual. El formato de la clase CSS generado es .wp-block-{namespace}-{name}. Como se puede ver, esto se basa en el nombre del espacio de nombres del bloque y lo hace ideal para ser utilizado como un identificador de bloque único.

La función de edición requiere retorno marcado válido mediante el método render(), que entonces se utiliza para representar el bloque en el editor.

Guardar

Similar a la función edit, save muestra una representación visual de su bloque pero frente al extremo. También recibe datos de bloque dinámico (si) a través de props.

Una diferencia principal es que props.className no está disponible dentro de save, pero esto no es un problema porque se inserta automáticamente por Gutenberg.

Soportes

La propiedad de supports acepta un objeto de valores booleanos para determinar si su bloque admite ciertas características del núcleo.

Las propiedades del objeto disponibles que se pueden establecer son las siguientes.

  • anchor (false por defecto): permite enlazar directamente a un bloque específico
  • customClassName (true): agrega un campo en el inspector de bloque para definir un className personalizada para el bloque
  • className (true): añade un className al elemento raíz bloque basado en el nombre de bloque
  • html (true): permite el marcado de bloque a ser editado directamente

La Propiedad UseOnce

Esta es una propiedad útil que permite restringir un bloque de más de una vez se agrega a una página. Un ejemplo de esto es la base del bloque Más, que no se puede Agregar a una página si ya presente.

useOnce property

Como puede ver, una vez que se ha añadido el bloque Más, el icono de bloque está atenuado y no se puede seleccionar. La propiedad useOnce se establece en false de forma predeterminada.

¡Sea Creativo!

Es tiempo ahora para utilizar el conocimiento que hemos ganado hasta ahora para implementar un sólido ejemplo de trabajo de un bloque que hace algo más interesante que simplemente salida estáticas.

Vamos a construir un bloque para una imagen al azar obtenida a través de una petición externa a la página web PlaceIMG, que devuelve una imagen aleatoria de la salida. Además, podrás seleccionar la categoría de imagen devuelta por un control de lista desplegable select.

Our random image block

Para mayor comodidad, vamos a añadir nuestro nuevo bloque para el mismo plugin de my-custom-block, en lugar de crear un nuevo plugin. Así el código de bloque por defecto se encuentra dentro de la carpeta /src/block agregar otra carpeta dentro de /src llamado random-image y agregar tres nuevos archivos:

  • index.js: registra nuestro nuevo bloque
  • editor.scss: editor de estilos
  • style.scss: estilos para el editor y frente

Alternativamente, puede copiar la carpeta /src/block y cámbiele el nombre si no desea escribir todo a mano. Asegúrese de que, sin embargo, cambiar el nombre de block.js a index.js dentro de la carpeta nueva del bloque.

Estamos usando index.js para el nombre de archivo de bloque principal, esto nos permite simplificar la declaración de importación dentro de blocks.js. En lugar de tener que incluir la ruta y el nombre completo del bloque, sólo podemos especificar la ruta de la carpeta bloques e import buscará automáticamente un archivo index.js.

Abrir /src/blocks.js y agregue una referencia a nuestro nuevo bloque en la parte superior del archivo, directamente debajo de la actual declaración de importación.

Dentro de /src/random-image/index.js, agregue el código siguiente para iniciar nuestro nuevo bloque.

Esto establece el marco de nuestro bloque y es bastante similar al código de bloque repetitivo generado por las herramientas de create-guten-block.

Empezamos importando el editor y hojas de estilo front-end, y luego lo extraemos algunas funciones de uso común de wp.i18n y wp.blocks en variables locales.

Dentro de registerBlockType(), los valores han sido introducidos para las propiedades titleiconcategory, y keywords, mientras que la edit y save funciones actualmente sólo salida de contenido estático.

Añadir la imagen al azar bloque a una nueva página para ver la salida generada hasta ahora.

Bare bones block output

Asegúrese de que todavía estás viendo archivos de cambios así que cualquier bloque de código (JSX, ES6 +, Sass, etc.) es transpiled en JavaScript válido y CSS. Si actualmente no está viendo archivos de cambios, a continuación, abra una ventana de línea de comandos dentro de la carpeta raíz de plugin my-custom-block y enter npm start.

Quizás se pregunte por qué no tenemos que añadir ningún código PHP a enqueue adicional bloquear secuencias de comandos. Las secuencias de comandos de bloque para el bloque de my-custom-block son cola via init.php, pero no necesitamos poner scripts específicamente para nuestro nuevo bloque como esto está cuidado para nosotros por el create-guten-block.

Mientras importar nuestro archivo de bloque principal en src/blocks.js (como lo hicimos anteriormente) entonces no necesitamos hacer ningún trabajo adicional. Todos JSX, ES6 + y Sass código serán compilados automáticamente en los siguientes archivos:

  • dist/blocks.style.build.css: estilos para editor y frente
  • dist/blocks.build.js: JavaScript editor sólo
  • dist/blocks.editor.build.css: estilos para el editor sólo

Estos archivos contienen el JavaScript y CSS para todos los bloques, así que solamente un sistema de archivos debe ser cola, independientemente del número de bloques creados!

Ahora estamos listos para añadir un poco de interactividad a nuestro bloque, y esto lo podemos hacer agregando primero un atributo para almacenar la categoría imagen.

Esto crea un atributo llamado category, que almacena un string con un valor predeterminado de 'nature'. No especifique una ubicación en el marcado para almacenar y recuperar el valor del atributo, así que comentarios HTML especiales se utilizarán en su lugar. Este es el comportamiento predeterminado si omites una fuente de atributo.

Necesitamos alguna manera de cambiar la categoría de la imagen, que podemos hacer a través de un control de lista desplegable select. Actualización de la función de edit lo siguiente:

Aquí está lo que se verá como:

Adding a block select drop down control

Esto es muy diferente de la función estática de la edición anterior, así que vamos a ejecutar a través de los cambios.

En primer lugar hemos añadido un control de lista desplegable select con varias opciones que las categorías de imagen disponibles en el sitio PlaceIMG.

PlaceIMG image categories

Cuando cambia el valor de la lista desplegable, se llama la función setCategory, que encuentra la categoría seleccionada y luego a su vez llama a la función de setAttributes. Esto es una función de Gutenberg y actualiza un valor de atributo correctamente. Se recomienda que sólo actualizar un atributo utilizando esta función.

Ahora, cada vez que se selecciona una nueva categoría, el valor del atributo se actualiza y pasa a la función de edit, que actualiza el mensaje de salida.

Image category updated

Tenemos que completar un último paso para obtener la imagen al azar para mostrar. Debemos crear un componente sencillo que tendrá en la categoría actual y la salida un etiqueta <img> con una imagen al azar obtenida desde el sitio PlaceIMG.

La petición que tenemos que hacer para PlaceIMG es de la forma: https://placeimg.com/[anchura]/[altura]/[categoría]

Mantendremos el ancho y alto fijada por ahora, sólo tenemos que añadir la categoría actual en el extremo de la URL de solicitud. Por ejemplo, si fue de la categoría 'nature' entonces la URL de solicitud completa sería: https://placeimg.com/320/220/nature.

Añadir un componente de RandomImage sobre registerBlockType():

Para usarlo, sólo añadir dentro de la función de editar y eliminar el mensaje de salida estática. Mientras estamos en él, lo mismo para guardar la función.

El archivo completo index.js debe ahora este aspecto:

Finalmente (por ahora), agregar los siguientes estilos a editor.scss para agregar un borde de color alrededor de la imagen.

También necesitarás algunos estilos en style.css.

Cada vez que se actualiza la página en el editor o en la parte delantera, se mostrará una nueva imagen al azar.

Finished editor view
Final front end view

Si estás viendo la misma imagen aparece una y otra vez, puede hacer una actualización de disco duro para evitar que la imagen se sirve desde la caché del navegador.

Conclusión

En este tutorial hemos cubierto mucho terreno. Si usted ha hecho hasta entonces darle usted mismo una merecido palmadita en la espalda! Gutenberg bloque desarrollo puede ser muy divertido, pero definitivamente es un reto para comprender cada concepto en primera exposición.

En el camino, hemos aprendido cómo enqueue bloque de scripts y estilos y cubre la función de registerBlockType() en profundidad.

Seguimos esto de poner teoría en práctica y crear un bloque personalizado desde cero para mostrar una imagen aleatoria de una categoría específica mediante el servicio web de PlaceIMG.

En la siguiente y última parte de esta serie de tutoriales, vamos a añadir más funciones a nuestro bloque de imagen al azar mediante el panel de ajustes en el inspector de bloque.

Si has estado siguiendo junto con este tutorial y solo quiero experimentar con el código sin tener que escribir todo en, usted será capaz de descargar el plugin de final my-custom-blocken el siguiente tutorial.

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.