Share
El nuevo editor de WordPress (con nombre en código Gutenberg) se lanzará en la versión 5.0. Ahora es el momento perfecto para enfrentarlo antes de que llegue al núcleo de WordPress. En esta serie, te muestro cómo trabajar con la API de bloque y crear tus propios bloques de contenido que puedes usar para construir tus publicaciones y páginas..
En el post anterior, vimos cómo usar el crear-guten-block kit de herramientas para crear un complemento que contenga un bloque de muestra listo para que podamos trabajar. Podemos extenderlo fácilmente según sea necesario, pero es una buena idea saber cómo crear un bloque desde cero para comprender completamente todos los aspectos del desarrollo del bloque Gutenberg..
En este post vamos a crear un segundo bloque en nuestro. mi-bloque personalizado complemento para mostrar una imagen aleatoria del servicio web PlaceIMG. También podrá personalizar el bloque seleccionando la categoría de imagen de un control de selección desplegable.
Pero primero aprenderemos cómo se encolan los scripts de bloque y los estilos antes de pasar a lo más importante registerBlockType () Función fundamental para crear bloques en Gutenberg..
Para agregar el JavaScript y CSS requeridos por nuestros bloques, podemos usar dos nuevos ganchos de WordPress proporcionados por Gutenberg:
Accentsconagua
enqueue_block_editor_assetsenqueue_block_assetsEstos solo están disponibles si el complemento Gutenberg está activo y funcionan de manera similar a los enganches estándar de WordPress para poner en cola los scripts. Sin embargo, están destinados específicamente para trabajar con bloques de Gutenberg..
los enqueue_block_editor_assets Hook agrega scripts y estilos solo al editor de administración. Esto lo hace ideal para encolar JavaScript para registrar bloques y CSS para diseñar elementos de la interfaz de usuario para la configuración de bloques.
Sin embargo, para la salida de bloques, querrá que los bloques se muestren igual en el editor que en la parte frontal la mayor parte del tiempo. Utilizando enqueue_block_assets facilita esta tarea, ya que los estilos se agregan automáticamente tanto al editor como a la interfaz. También puede usar este gancho para cargar JavaScript si es necesario.
Pero es posible que se esté preguntando cómo poner en cola scripts y estilos. solamente en la parte delantera No hay un gancho de WordPress que le permita hacer esto directamente, pero puede solucionar esto agregando una declaración condicional dentro de enqueue_block_assets función de devolución de llamada de gancho.
add_action ('enqueue_block_assets', 'load_front_end scripts'); función load_front_end scripts () if (! is_admin () // poner en cola los scripts y estilos del front end solo aquíPara poner en cola realmente los scripts y los estilos utilizando estos dos nuevos ganchos, puede usar el estándar wp_enqueue_style () y wp_enqueue_scripts () funciona como lo haría normalmente.
Sin embargo, debe asegurarse de que está utilizando las dependencias de script correctas. Para poner en cola los scripts en el editor, puede usar las siguientes dependencias:
array ('wp-blocks', 'wp-i18n', 'wp-element', 'wp-components') array ('wp-edit-blocks') Y al poner en cola los estilos tanto para el editor como para el front-end, puede usar esta dependencia:
array ('wp-blocks')Una cosa que vale la pena mencionar aquí es que los archivos reales puestos en cola por nuestros mi-bloque personalizado plugin son los compilado versiones de JavaScript y CSS y no los archivos que contienen el código fuente de JSX y Sass.
Esto es algo que se debe tener en cuenta al poner en cola manualmente los archivos. Si intenta poner en cola el código fuente sin procesar que incluye React, ES6 + o Sass, encontrará numerosos errores..
Por eso es útil usar un kit de herramientas como crear-guten-block A medida que procesa y encola los scripts de forma automática.!
Para crear un nuevo bloque, necesitamos registrarlo con Gutenberg llamando registerBlockType () y pasando el nombre del bloque más un objeto de configuración. Este objeto tiene bastantes propiedades que requieren una explicación adecuada..
En primer lugar, sin embargo, echemos un vistazo al nombre del bloque. Este es el primer parámetro y es una cadena compuesta por dos partes, un espacio de nombres y el nombre del bloque, separados por un carácter de barra diagonal..
Por ejemplo:
registerBlockType ('block-namespace / block-name', // objeto de configuración);Si está registrando varios bloques en un complemento, puede usar el mismo espacio de nombres para organizar todos sus bloques. Sin embargo, el espacio de nombres debe ser exclusivo de su complemento, lo que ayuda a evitar conflictos de nombres. Esto puede suceder si un bloque con el mismo nombre ya se ha registrado a través de otro complemento.
El segundo registerBlockType () parámetro es un objeto de configuración y requiere que se especifique una serie de propiedades:
título (cadena): se muestra en el editor como la etiqueta de bloque de búsquedadescripción (cadena opcional): describe el propósito de un bloqueicono (Elemento de Dashicon o JSX opcional): icono asociado con un bloquecategoría (cadena): donde aparece el bloque en el Agregar bloques diálogopalabras clave (matriz opcional): hasta tres palabras clave utilizadas en búsquedas de bloqueatributos (objeto opcional): maneja los datos del bloque dinámicoeditar (función): una función que devuelve el marcado que se representará en el editorsalvar (función): una función que devuelve el marcado que se va a representar en el extremo delanterouso una vez (booleano opcional): restringe que el bloque se agregue más de una vezapoya (objeto opcional): define características soportadas por bloquesSuponiendo que estamos usando JSX para el desarrollo de bloques, he aquí un ejemplo. registerBlockType () La llamada podría parecerse a un bloque muy simple:
registerBlockType ('my-unique-namespace / ultimate-block', title: __ ('The Best Block Ever', 'dominio'), icono: 'wordpress', categoría: 'common', palabras clave: [__ ('sample ',' dominio '), __ (' Gutenberg ',' dominio '), __ (' bloque ',' dominio ')], editar: () => Bienvenido al Editor de Gutenberg!
, guardar: () => ¿Cómo estoy mirando en la parte delantera?
);Observe cómo no incluimos una entrada para el descripción, atributos, uso una vez, y apoya propiedades? Cualquier campo que sea opcional (y no relevante para su bloque) puede omitirse de manera segura. Por ejemplo, como este bloque no involucró ningún dato dinámico, no debemos preocuparnos por especificar ningún atributo.
Ahora vamos a cubrir el registerBlockType () propiedades del objeto de configuración con más detalle uno por uno.
Al insertar o buscar un bloque en el editor, el título se mostrará en la lista de bloques disponibles.
También se muestra en la ventana del inspector de bloques, junto con la descripción del bloque, si está definida. Si el inspector de bloques no está visible actualmente, puede usar el ícono de engranaje en la esquina superior derecha del editor de Gutenberg para alternar la visibilidad.
Lo ideal sería que los campos de título y descripción estuvieran envueltos en funciones i18n para permitir la traducción a otros idiomas..
Actualmente hay cinco categorías de bloques disponibles:
comúnformateodiseñowidgetsempotrarEstos determinan la sección de categoría donde se incluye su bloque dentro de la Agregar bloque ventana.
los Bloques la pestaña contiene Bloques comunes, Formateo, Elementos de diseño, y Widgets categorías, mientras que Inserta categoría tiene su propia pestaña.
Las categorías actualmente están arregladas en Gutenberg, pero esto podría estar sujeto a cambios en el futuro. Esto sería útil, por ejemplo, si estuviera desarrollando múltiples bloques en un solo complemento y quisiera que todos estuvieran incluidos en una categoría común para que los usuarios pudieran localizarlos más fácilmente..
Por defecto, a su bloque se le asigna el escudo Dashicon, pero puede anularlo especificando un Dashicon personalizado en el icono campo.
Cada Dashicon tiene el prefijo dashicons- seguido de una cadena única. Por ejemplo, el icono de engranaje tiene el nombre dashicons-admin-generic. Para usar esto como un ícono de bloque, simplemente quite la dashicons- prefijo para que sea reconocido, por ejemplo. icono: 'admin-generic'.
Sin embargo, no está limitado a usar Dashicons como propiedad de icono. La función también acepta un elemento JSX, lo que significa que puede usar cualquier imagen o elemento SVG como su icono de bloque.
Solo asegúrese de mantener el tamaño del ícono consistente con otros íconos de bloque, que es 20 x 20 píxeles por defecto.
Elija hasta tres palabras clave traducibles para que su bloque se destaque cuando los usuarios busquen un bloque. Es mejor elegir palabras clave que se relacionen estrechamente con la funcionalidad de su bloque para obtener mejores resultados.
palabras clave: [__ ('búsqueda', 'dominio'), __ ('para', 'dominio'), __ ('yo', 'dominio'),]Incluso puede declarar el nombre de su compañía y / o complemento como palabras clave, de modo que si tiene varios bloques, los usuarios pueden comenzar a escribir el nombre de su compañía y todos sus bloques aparecerán en los resultados de búsqueda..
Aunque agregar palabras clave es totalmente opcional, es una excelente manera de facilitar a los usuarios la búsqueda de sus bloques..
Los atributos ayudan a gestionar datos dinámicos en un bloque. Esta propiedad es opcional, ya que no la necesita para bloques muy simples que generan contenido estático.
Sin embargo, si su bloque trata con datos que podrían cambiar (como el contenido de un área de texto editable) o si necesita almacenar configuraciones de bloque, entonces la forma de hacerlo es usar atributos..
Los atributos funcionan almacenando datos de bloques dinámicos en el contenido de la publicación guardado en la base de datos o en el metadatos de la publicación. En este tutorial solo usaremos atributos que almacenan datos junto con el contenido de la publicación.
Para recuperar los datos de atributos almacenados en el contenido de la publicación, debemos especificar dónde se encuentran en el marcado. Podemos hacer esto especificando un selector de CSS que apunta a los datos del atributo.
Por ejemplo, si nuestro bloque contenía una etiqueta de anclaje, podemos usar su título campo como nuestro atributo de la siguiente manera:
atributos: linktitle: source: 'attribute', selector: 'a', attribute: 'title'
Aquí, el nombre del atributo es linktitle, que es una cadena arbitraria y puede ser lo que quieras.
Por ejemplo, podríamos usar este atributo para almacenar el título del enlace. que se ha introducido a través de un cuadro de texto en la configuración de bloque. Hacerlo de repente hace que el campo de título sea dinámico y le permite cambiar su valor en el editor.
Cuando se guarda la publicación, el valor del atributo se inserta en los enlaces título campo. Del mismo modo, cuando se carga el editor, el valor del título etiqueta se recupera del contenido y se inserta en el linktitle atributo.
Hay más formas de usar fuente para determinar cómo se almacena o recupera el contenido del bloque a través de los atributos. Por ejemplo, puede utilizar el 'texto' Fuente para extraer el texto interno de un elemento de párrafo..
atributos: párrafo: fuente: 'texto', selector: 'p'
También puedes usar el niños fuente para extraer todos los nodos secundarios de un elemento en una matriz y almacenarlo en un atributo.
atributos: editablecontent: source: 'children', selector: '.parent'
Esto selecciona el elemento con clase. .padre y almacena todos los nodos hijos en el contenido editablec atributo.
Si no especifica una fuente, el valor del atributo se guarda en comentarios HTML como parte del marcado de publicación cuando se guarda en la base de datos. Estos comentarios se eliminan antes de que se publique la publicación en la parte delantera.
Veremos un ejemplo específico de este tipo de atributo cuando implementemos nuestro bloque de imágenes al azar más adelante en este tutorial..
Los atributos pueden tardar un poco en acostumbrarse, así que no te preocupes si no los entiendes por primera vez. Recomiendo echar un vistazo a la sección de atributos del manual de Gutenberg para obtener más detalles y ejemplos..
los editar La función controla cómo aparece tu bloque dentro de la interfaz del editor. Los datos dinámicos se pasan a cada bloque como accesorios, Incluyendo cualquier atributo personalizado que haya sido definido..
Es una práctica común agregar className = props.className al elemento de bloque principal para generar una clase CSS específica para su bloque. WordPress no agrega esto para usted dentro del editor, por lo que debe agregarse manualmente para cada bloque si desea incluirlo.
Utilizando props.className es una práctica estándar y se recomienda ya que proporciona una manera de adaptar los estilos CSS para cada bloque individual. El formato de la clase CSS generada es .wp-block- espacio de nombres - nombre. Como puede ver, esto se basa en el espacio de nombres de bloque / nombre y lo hace ideal para ser utilizado como un identificador de bloque único.
La función de edición requiere que devuelva un marcado válido a través de hacer() Método, que luego se utiliza para representar su bloque dentro del editor.
Similar a editar función, salvar muestra una representación visual de su bloque pero en el extremo delantero. También recibe datos de bloques dinámicos (si están definidos) a través de accesorios.
Una diferencia principal es que props.className no está disponible dentro salvar, pero esto no es un problema porque se inserta automáticamente por Gutenberg.
los apoya la propiedad acepta un objeto de valores booleanos para determinar si su bloque admite ciertas funciones básicas.
Las propiedades de objeto disponibles que puede establecer son las siguientes.
ancla (falso por defecto): le permite enlazar directamente a un bloque específicocustomClassName (verdadero): agrega un campo en el inspector de bloques para definir una costumbre nombre de la clase por el bloque nombre de la clase (verdadero): agrega un nombre de la clase al elemento raíz del bloque basado en el nombre del bloquehtml (verdadero): permite editar el marcado de bloque directamenteuso una vez PropiedadEsta es una propiedad útil que le permite restringir un bloque para que no se agregue más de una vez a una página. Un ejemplo de esto es el núcleo. Más bloque, que no se puede agregar a una página si ya está presente.
Como se puede ver, una vez que el Más se ha agregado el bloque, el icono del bloque aparece en gris y no se puede seleccionar. los uso una vez la propiedad se establece en falso por defecto.
Ahora es el momento de utilizar el conocimiento que hemos adquirido hasta ahora para implementar un ejemplo sólido de trabajo de un bloque que hace algo más interesante que simplemente generar contenido estático..
Construiremos un bloque para generar una imagen aleatoria obtenida a través de una solicitud externa al sitio web de PlaceIMG, que devuelve una imagen aleatoria. Además, podrá seleccionar la categoría de imagen devuelta a través de un control desplegable de selección.
Para mayor comodidad, agregaremos nuestro nuevo bloque al mismo. mi-bloque personalizado plugin, en lugar de crear un plugin nuevo. El código para el bloque predeterminado se encuentra dentro de / src / block carpeta, así que agregue otra carpeta dentro / src llamado Imagen aleatoria y agregar tres nuevos archivos:
Alternativamente, usted podría copiar el / src / block Carpeta y renómbrela si no desea escribir todo a mano. Asegúrate, sin embargo, de cambiar el nombre block.js a index.js dentro de la nueva carpeta de bloques.
Estamos usando index.js para el nombre de archivo del bloque principal, ya que esto nos permite simplificar la declaración de importación en el interior blocks.js. En lugar de tener que incluir la ruta y el nombre completo del bloque, podemos especificar la ruta a la carpeta del bloque, y importar buscará automáticamente un index.js expediente.
Abrir /src/blocks.js y agregue una referencia a nuestro nuevo bloque en la parte superior del archivo, directamente debajo de la declaración de importación existente.
importar './random-image';
Dentro /src/random-image/index.js, Agregue el siguiente código para poner en marcha nuestro nuevo bloque..
// Importar CSS. importar './style.scss'; importar './editor.scss'; const __ = wp.i18n; const registerBlockType, consulta = wp.blocks; registerBlockType ('cgb / block-random-image', title: __ ('Random Image'), icono: 'format-image', categoría: 'common', palabras clave: [__ ('random'), __ (' imagen ')], edit: function (props) return ( Bloque de imagen aleatoria (editor)
); , save: function (props) return ( Bloque de imagen aleatoria (frontal)
); );Esto configura el marco de nuestro bloque y es bastante similar al código de bloque repetitivo generado por el crear-guten-block caja de herramientas.
Comenzamos importando el editor y las hojas de estilo front-end, y luego extraeremos algunas funciones de uso común de wp.i18n y wp.blocks en variables locales.
Dentro registerBlockType (), Se han introducido valores para el título, icono, categoría, y palabras clave propiedades, mientras que el editar y salvar Las funciones actualmente solo emiten contenido estático.
Agregue el bloque de imagen al azar a una nueva página para ver el resultado generado hasta ahora.
Asegúrese de seguir viendo los archivos en busca de cambios para que cualquier código fuente de bloque (JSX, ES6 +, Sass, etc.) sea transpilado a JavaScript y CSS válidos. Si actualmente no está viendo los archivos en busca de cambios, abra una ventana de línea de comandos dentro de mi-bloque personalizado carpeta raíz del plugin y entrar npm start.
Quizás se esté preguntando por qué no tuvimos que agregar ningún código PHP para poner en cola secuencias de comandos de bloque adicionales. Los guiones de bloque para el mi-bloque personalizado bloque encolado a través de init.php, pero no necesitamos poner en cola los scripts específicamente para nuestro nuevo bloque, ya que esto se encarga de nosotros. crear-guten-block.
Mientras importemos nuestro archivo de bloque principal en src / blocks.js (como hicimos anteriormente) entonces no necesitamos hacer ningún trabajo adicional. Todo el código JSX, ES6 + y Sass se compilará automáticamente en los siguientes archivos:
Estos archivos contienen JavaScript y CSS para todos los bloques, por lo que solo es necesario poner en cola un conjunto de archivos, independientemente del número de bloques creados.!
Ahora estamos listos para agregar un poco de interactividad a nuestro bloque, y podemos hacerlo agregando primero un atributo para almacenar la categoría de imagen.
atributos: categoría: tipo: 'cadena', por defecto: 'naturaleza'
Esto crea un atributo llamado categoría, que almacena una cadena con un valor predeterminado de 'naturaleza'. No especificamos una ubicación en el marcado para almacenar y recuperar el valor del atributo, por lo que se usarán comentarios HTML especiales en su lugar. Este es el comportamiento predeterminado si omite una fuente de atributo.
Necesitamos alguna forma de cambiar la categoría de imagen, lo que podemos hacer a través de un control desplegable de selección. Actualizar el editar función a lo siguiente:
edit: function (props) const atributos: category, setAttributes = props; función setCategory (event) const selected = event.target.querySelector ('option: checked'); setAttributes (category: selected.value); event.preventDefault (); regreso ( La categoría actual es: categoría ); Esto es lo que se verá:
Esto es bastante diferente de la estática anterior. editar función, así que vamos a correr a través de los cambios.
Primero, hemos agregado un control desplegable de selección con varias opciones que coinciden con las categorías de imágenes disponibles en el sitio de PlaceIMG.
Cuando el valor del menú desplegable cambia, setCategory se llama a la función, que encuentra la categoría seleccionada actualmente y luego a su vez llama a la setAttributes función. Esta es una función central de Gutenberg y actualiza un valor de atributo correctamente. Se recomienda que solo actualices un atributo usando esta función.
Ahora, cada vez que se selecciona una nueva categoría, el valor del atributo se actualiza y se pasa nuevamente a la editar Función, que actualiza el mensaje de salida..
Tenemos que completar un último paso para obtener la imagen al azar para mostrar. Necesitamos crear un componente simple que tome en la categoría actual y produzca un
La solicitud que debemos hacer a PlaceIMG es de la siguiente forma: https://placeimg.com/[width◆/[height◆/[category]
Mantendremos el ancho y la altura fijos por ahora, por lo que solo tenemos que agregar la categoría actual al final de la URL de solicitud. Por ejemplo, si la categoría era 'naturaleza' entonces la URL de solicitud completa sería: https://placeimg.com/320/220/nature.
Agrega un Imagen aleatoria componente arriba registerBlockType ():
function RandomImage (category) const src = 'https://placeimg.com/320/220/' + category; regreso;
Para usarlo, simplemente agréguelo dentro de la función de edición y elimine el mensaje de salida estática. Mientras estamos en eso, haz lo mismo con la función de guardar.
El lleno index.js El archivo ahora debería verse así:
// Importar CSS. importar './style.scss'; importar './editor.scss'; const __ = wp.i18n; const registerBlockType, consulta = wp.blocks; function RandomImage (category) const src = 'https://placeimg.com/320/220/' + category; regreso); , save: function (props) const attributes: category = props; regreso (
Finalmente (por ahora), agregue los siguientes estilos a editor.scss Para agregar un borde de color alrededor de la imagen..
.wp-block-cgb-block-random-image select padding: 2px; margen: 7px 0 5px 2px; radio del borde: 3px;
También necesitarás algunos estilos en style.css.
.wp-block-cgb-block-random-image fondo: # f3e88e; color: #fff; borde: 2px sólido # ead9a6; radio del borde: 10px; relleno: 5px; ancho: -webkit-fit-content; ancho: -moz-fit-content; ancho: ajuste de contenido; img radio-borde: heredar; borde: 1px punteado # caac69; pantalla: rejilla;
Cada vez que se actualice la página en el editor o en el extremo frontal, se mostrará una nueva imagen aleatoria.
Si está viendo la misma imagen una y otra vez, puede hacer una actualización para evitar que la imagen se muestre desde el caché de su navegador..
En este tutorial hemos cubierto bastante terreno. Si lo has hecho bien, entonces date una merecida palmadita en la espalda. El desarrollo del bloque Gutenberg puede ser muy divertido, pero definitivamente es un desafío comprender todos los conceptos en la primera exposición.
A lo largo del camino, hemos aprendido a poner en cola los scripts y estilos de bloque y hemos cubierto la registerBlockType () función en profundidad.
Seguimos esto poniendo en práctica la teoría y creando un bloque personalizado desde cero para mostrar una imagen aleatoria de una categoría específica utilizando el servicio web PlaceIMG.
En la siguiente y última parte de esta serie de tutoriales, agregaremos más funciones a nuestro bloque de imágenes al azar a través del panel de configuración en el inspector de bloques.
Si has estado siguiendo este tutorial y solo quieres experimentar con el código sin escribir todo, podrás descargar la versión final. mi-bloque personalizado plugin en el siguiente tutorial.
