Gutenberg se ha convertido en un editor potente y altamente personalizable. Más allá de sus sólidas funcionalidades listas para usar, los desarrolladores de WordPress ahora pueden aprovechar un amplio conjunto de APIs para integrar fácilmente funcionales personalizadas en sus sitios web. Esta extensibilidad permite un notable grado de desarrollo a medida, lo que permite a los desarrolladores crear experiencias online altamente personalizadas y ricas en funcionalidades.
Este artículo explora dos funcionalidades menos conocidas pero muy potentes del desarrollo de WordPress: Variaciones de Estilo (también conocidas como estilos de bloque) y Variaciones de Bloque.
Aunque su utilidad pueda parecer poco clara al principio, te sorprenderá lo útiles que son y cómo una pequeña inversión de tiempo te permitirá integrarlos perfectamente en tu flujo de trabajo.
Obtendrás una comprensión práctica de lo que son y cómo utilizarlos a través de un proyecto real. Puedes implementar este proyecto en tu sitio de WordPress simplemente copiando y pegando el código de este tutorial y, finalmente, añadiendo personalizaciones.
Antes de sumergirnos en el proyecto, revisemos rápidamente los requisitos previos:
- Entorno local de desarrollo de WordPress: Aunque cualquiera es válido, recomendamos encarecidamente DevKinsta, la suite de desarrollo local de Kinsta. Es fácil de usar y ofrece muchos ajustes y herramientas para lanzar y gestionar rápidamente un sitio local de WordPress.
- Node.js y npm: Son esenciales, ya que el editor de bloques está basado en React y requiere un proceso de
- construcción
- Conocimientos básicos de desarrollo frontend: Será beneficioso tener conocimientos básicos de Node.js, JavaScript (con React), PHP y CSS.
Aunque este proyecto no es demasiado complejo, prepárate para escribir algo de código. El código completo también está disponible en GitHub.
¡Empecemos!
Estilos de bloque Vs. Variaciones de bloque
Los Estilos de bloque y las Variaciones de bloque son dos potentes funcionalidades de WordPress para desarrolladores. Aunque sus nombres suenan bastante parecidos, difieren en su finalidad y uso.
Los Estilos de bloque, también conocidos como variaciones de estilo, son conjuntos preconfigurados de estilos CSS que te permiten cambiar el aspecto de un bloque con un solo clic. Tras registrar un estilo de bloque, aparece un botón en la barra lateral del bloque para asignar un conjunto de estilos preconstruidos al bloque. Puedes activar y desactivar los estilos y previsualizar el bloque en el editor en tiempo real.
Las variaciones de estilo no alteran los atributos del bloque. Sólo modifican la apariencia de un bloque asignando una clase CSS al elemento envolvente del bloque.
Las variaciones de bloque son una herramienta más potente porque te permiten crear una versión preconfigurada de un bloque con atributos y bloques interiores. También aparecen en el insertador de bloques del editor. Esencialmente, una variación de bloque aparece ante el usuario como si fuera un bloque independiente, completamente independiente del bloque sobre el que se construye.
Las variaciones de bloque permiten personalizar el aspecto, la configuración inicial y la estructura de un bloque.
Con todo esto en mente, ¡utilicemos estas herramientas para llevar los bloques Gutenberg al siguiente nivel!
Un efecto Polaroid animado en un bloque principal de Imagen
Ahora, ¡vamos a sumergirnos en nuestro proyecto! Vamos a ampliar el bloque principal Imagen con un plugin de Gutenberg para:
- Implementar una Variación del Estilo Polaroid: Los usuarios pueden aplicar un bonito efecto Polaroid a sus imágenes con un solo clic desde la barra lateral de configuración del bloque.
- Añadir una Animación Hover: Mejoraremos las imágenes de estilo Polaroid con una sutil animación hover.
- Crea una Variación del Bloque «Polaroid Animada»: Esto permitirá a los usuarios insertar rápidamente imágenes Polaroid preconfiguradas con un efecto hover directamente desde el insertador de bloques.
¿Estás preparado? ¡Vamos a configurar nuestro plugin!
Configuración del entorno
Antes de empezar, necesitamos configurar un entorno de desarrollo de WordPress con Node.js. Suponemos que ya has instalado tu entorno de desarrollo local de WordPress y las últimas versiones de Node.js y npm. Si necesitas ayuda, consulta nuestro tutorial sobre cómo crear un plugin Gutenberg para añadir funcionalidad al editor de bloques.
Paso 1 – Crear la estructura básica del plugin
Para este tutorial, llamaremos a nuestro plugin Image Hacker.
Navega a tu directorio plugins y crea una nueva carpeta image-hacker. Dentro de esta carpeta, crea un nuevo archivo image-hacker.php (el archivo principal de tu plugin) y una subcarpeta src, donde crearás las funcionalidades del plugin.
Esta es la estructura básica de tu plugin:
/wp-content/plugins/
└── /image-hacker/
├── image-hacker.php
└── /src/Paso 2 – Crear el código PHP
A continuación, debes asegurarte de que WordPress reconoce tu plugin. Para ello, añade el siguiente código a image-hacker.php:
<?php
/**
* Plugin Name: Image Hacker
* Description: Adds new features to the core Image block
* Version: 1.0.0
* Author: Your Name
* License: GPL-2.0-or-later
* License URI: https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain: image-hacker
*/
if ( ! defined( 'ABSPATH' ) ) {
exit; // Exit if accessed directly.
}Paso 3 – Inicializar npm e instalar dependencias
Abre tu herramienta de línea de comandos favorita y navega hasta el directorio de tu plugin. Una vez allí, ejecuta el siguiente comando:
npm init -yEste comando inicializa un nuevo archivo package.json, que incluye las dependencias y scripts de tu proyecto.
A continuación, tienes que instalar los scripts de WordPress y herramientas de construcción como webpack y Babel:
npm install @wordpress/plugins @wordpress/scripts --save-devEste comando añade una carpeta node_modules con dependencias de nodos y un archivo package-lock.json. La siguiente imagen muestra la estructura actual de tu proyecto en Visual Studio Code:
A continuación, abre tu package.json y actualiza la propiedad scripts como se indica a continuación:
{
"name": "image-hacker",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"build": "wp-scripts build",
"start": "wp-scripts start"
},
"keywords": [],
"author": "",
"license": "ISC",
"description": "",
"devDependencies": {
"@wordpress/plugins": "^7.25.0",
"@wordpress/scripts": "^30.18.0"
}
}Ten en cuenta que las versiones de devDependencies pueden diferir de las anteriores y dependen de las versiones reales instaladas en tu entorno.
Paso 4 – Crea los archivos fuente de tu plugin
El siguiente paso es crear los archivos fuente del plugin. Navega hasta la carpeta src y añade los siguientes archivos:
index.jsstyle.scsseditor.scss
La estructura del plugin debería tener ahora este aspecto:
/wp-content/plugins/
└── /image-hacker/
├── /node-modules/
├── image-hacker.php
├── package.json
├── package-lock.json
└── /src/
├── index.js
├── style.scss
└── editor.scssAhora abre tu panel de administración de WordPress y navega hasta la pantalla de Plugins. Busca el plugin Image Hacker y actívalo.
Paso 5 – Incluir activos en el archivo de tu plugin
A continuación, tienes que incluir los activos del plugin en el archivo principal del plugin. Añade lo siguiente a image-hacker.php:
/**
* Enqueue block editor assets.
*/
function image_hacker_enqueue_editor_assets() {
$asset_file = include( plugin_dir_path( __FILE__ ) . 'build/index.asset.php');
// Enqueue the script with our modifications
wp_enqueue_script(
'image-hacker-script',
plugins_url( 'build/index.js', __FILE__ ),
array( 'wp-plugins', 'wp-edit-post' ),
filemtime( plugin_dir_path( __FILE__ ) . 'build/index.js' )
);
// Enqueue the editor-only styles
wp_enqueue_style(
'image-hacker-editor-style',
plugins_url( 'build/editor.css', __FILE__ ),
[],
filemtime( plugin_dir_path( __FILE__ ) . 'build/editor.css' )
);
}
add_action( 'enqueue_block_editor_assets', 'image_hacker_enqueue_editor_assets' );
/**
* Enqueue frontend and editor assets.
*/
function image_hacker_enqueue_assets() {
$asset_file = include( plugin_dir_path( __FILE__ ) . 'build/index.asset.php');
// Enqueue styles for both frontend and editor
wp_enqueue_style(
'image-hacker-style',
plugins_url( 'build/style-index.css', __FILE__ ),
[],
filemtime( plugin_dir_path( __FILE__ ) . 'build/style-index.css' )
);
}
add_action( 'enqueue_block_assets', 'image_hacker_enqueue_assets' );Esto es lo que hace este código
- El hook de acción
enqueue_block_editor_assetssolicita el scriptindex.jsy el archivoeditor.css. - El hook de acción
enqueue_block_assetssolicita el archivostyle.css.
Ten en cuenta que este código incluye los activos .js y .css ubicados en la carpeta /build/ de tu plugin. Esto significa que, para que funcione, necesitas ejecutar el comando build en tu herramienta de línea de comandos:
npm run buildTen en cuenta también que cuando importes un archivo llamado style.scss en index.js, el archivo CSS compilado no se llamará style.css sino style-index.css.
Registrar el estilo de bloque
Has completado la configuración de tu entorno de desarrollo. Ahora, puedes pasar a la parte emocionante del proyecto y registrar tu variación de estilo de bloque.
Hay varias formas de registrar estilos de bloque, y la que elijas dependerá de tus objetivos y preferencias personales. Nosotros seguiremos el enfoque JS para construir un plugin de Gutenberg. Abre tu archivo /src/index.js y pega el siguiente código:
// Import the function to register block styles.
import { registerBlockStyle } from '@wordpress/blocks';
// Import the function to run code only when the DOM is ready.
import domReady from '@wordpress/dom-ready';
// This line tells the build process to include and compile our SCSS file.
import './style.scss';
/**
* Use domReady to run code only when the DOM is ready.
*/
domReady(() => {
// Register our new style variation for the core image block.
registerBlockStyle('core/image', {
name: 'polaroid',
label: 'Polaroid',
});
});registerBlockStyle con domReady garantiza que la variación de estilo sólo se registre cuando el DOM esté completamente cargado. Consulta también la documentación oficial.
Cuando se selecciona el estilo Polaroid, WordPress añade automáticamente la clase .is-style-polaroid a la envoltura del bloque.
El siguiente paso es proporcionar el CSS para tu variación de estilo. Abre tu /src/style.scss y añade el siguiente código:
.wp-block-image.is-style-polaroid {
padding: 15px 15px 70px 15px;
background-color: white;
box-shadow: 0 4px 10px rgba(0, 0, 0, 0.2);
max-width: 360px;
transform: rotate(-3deg);
transition: transform 0.3s ease-in-out;
figure {
margin: 0 !important;
}
img {
display: block;
width: 100%;
height: auto;
}
figcaption {
position: absolute;
bottom: 15px;
left: 0;
right: 0;
text-align: center;
font-family: 'Permanent Marker', cursive;
color: #333;
font-size: 18px;
}
}Guarda tu código, ejecuta npm run build, y salta a tu panel de control de WordPress. Crea una nueva entrada o página y añade una imagen. Con la imagen seleccionada, haz clic en la etiqueta Estilos de la barra lateral del bloque y selecciona Polaroid.
Añade un pie de foto, guarda la entrada y comprueba el resultado en el frontend. Deberías ver una imagen estilo Polaroid con un bonito pie de foto en cursiva.
Construye la lógica
El siguiente paso es construir la lógica para animar la imagen. Crearemos una animación sencilla utilizando la propiedad CSS transform. Para empezar, añade el siguiente bloque a tu archivo src/style.scss:
.wp-block-image.is-style-polaroid.has-image-animation:hover {
transform: rotate(0deg) scale(1.05);
}Este código garantiza que el efecto hover sólo se aplique si el bloque es una imagen Polaroid y tiene una clase has-image-animation aplicada desde el conmutador de la barra de herramientas.
Ahora, necesitas la lógica para añadir la clase CSS al contenedor de la imagen, que es un elemento figure. Para ello, necesitas algunos filtros y funciones callback.
En primer lugar, añade la siguiente línea a tu archivo src/index.js:
import { addFilter } from '@wordpress/hooks';Paso 1. Añade un nuevo atributo al bloque Imagen
Utilizarás addFilter para manipular el bloque principal Imagen. Primero, añade un nuevo atributo imageAnimation al bloque Imagen:
function addImageAnimationAttribute( settings, name ) {
if ( name !== 'core/image' ) {
return settings;
}
settings.attributes = {
...settings.attributes,
imageAnimation: {
type: 'boolean',
default: false,
},
};
return settings;
}
addFilter(
'blocks.registerBlockType',
'image-hacker/add-image-animation-attribute',
addImageAnimationAttribute
);La función callback addImageAnimationAttribute recibe dos argumentos:
settings– Un array de atributos del bloque actualname– Especifica el nombre del bloque cuyos atributos quieres modificar.
La función devuelve el array de atributos actualizado.
Paso 2. Añadir un control de conmutador al bloque Imagen
A continuación, tendrás que añadir un control a la barra de herramientas del bloque Imagen para activar la animación.
En primer lugar, añade los siguientes imports al archivo index.js:
import { createHigherOrderComponent } from '@wordpress/compose';
import { Fragment } from '@wordpress/element';
import { BlockControls } from '@wordpress/block-editor';
import { ToolbarGroup, ToolbarButton } from '@wordpress/components';
import { __ } from '@wordpress/i18n';A continuación, añade el siguiente código al final del archivo:
const withPolaroidControls = createHigherOrderComponent((BlockEdit) => {
return (props) => {
if (props.name !== 'core/image') {
return <BlockEdit {...props} />;
}
const { attributes, setAttributes, isSelected } = props;
const { imageAnimation, className, lightbox } = attributes;
return (
<Fragment>
<BlockEdit {...props} />
<BlockControls>
<ToolbarGroup>
<ToolbarButton
icon="format-image"
label={__('Toggle Animation', 'image-hacker')}
isActive={imageAnimation}
onClick={() =>
setAttributes({ imageAnimation: !imageAnimation })
}
/>
</ToolbarGroup>
</BlockControls>
</Fragment>
);
};
}, 'withPolaroidControls');
addFilter(
'editor.BlockEdit',
'image-hacker/with-polaroid-controls',
withPolaroidControls
);Esto es lo que hace este código
- La función
createHigherOrderComponentcrea un componente de orden superior (HOC) que envuelve aBlockEdit, que es el componente principal responsable de mostrar los bloques en el editor. - El HOC intercepta el componente y comprueba si se trata de un bloque Imagen. Esto garantiza que todas tus ediciones sólo se apliquen al bloque Imagen.
- Utilizamos la asignación de desestructuración para extraer las propiedades y atributos necesarios de los objetos
propsyattributes. - Utilizamos
BlockControls,ToolbarGroupyToolbarButtonpara añadir un botón Activar Animación a la barra de herramientas del bloque. isActiveestablece el estado por defecto deimageAnimationonClickalterna el valor deimageAnimation.
Ahora tienes un atributo y un botón. Sin embargo, si haces clic en el botón, no ocurre nada.
Paso 3. Añade la clase CSS al elemento envoltorio
El siguiente paso es aplicar la clase has-image-animation al elemento figure que envuelve la imagen. Para ello, necesitas un filtro que te permita asignar la clase CSS a la imagen en el frontend.
Añade el siguiente código al archivo index.js:
function addAnimationFrontendClass(extraProps, blockType, attributes) {
if (blockType.name === 'core/image' && attributes.imageAnimation) {
extraProps.className = `${extraProps.className || ''} has-image-animation`;
}
return extraProps;
}
addFilter(
'blocks.getSaveContent.extraProps',
'image-hacker/add-animation-frontend-class',
addAnimationFrontendClass
);Este código añade dinámicamente la clase CSS has-image-animation al elemento figure cuando el atributo imageAnimation se establece en true.
Intentemos comprender lo que ocurre en detalle.
addFilterhace hook en los procesos del editor para modificar datos o comportamientos.blocks.getSaveContent.extraPropses el hook específico al que nos dirigimos.extraPropses un hook especial que te permite añadir atributos HTML adicionales al elemento envoltorio.image-hacker/add-animation-classes el nombre único de tu filtro.addAnimationFrontendClasses el nombre de la función de devolución de llamada que se ejecuta cada vez que se ejecuta el hookblocks.getSaveContent.extraProps. Esta función toma 3 argumentos:extraProps: Un objeto que contiene las propiedades del elemento envoltorio del bloque, comoclassName.blockType: Un objeto con detalles del bloque, como suname(core/image).attributes: Un objeto de atributos del bloque
- La lógica de la función garantiza que el código sólo se ejecuta cuando
blockType.name === 'core/image'yattributes.imageAnimationsontrue. - Si ambas condiciones son verdaderas, la función devuelve un nuevo objeto
propsconhas-image-animationañadido al objeto de clase existente.
Ahora, puedes probarlo tú mismo. Añade una imagen a tu contenido, selecciona el estilo Polaroid en la barra lateral del bloque y haz clic en el botón Activar Animación de la barra de herramientas del bloque. Guarda tu entrada y comprueba el resultado en el frontend. Tu imagen debería girar cuando pases el ratón sobre ella.
Registrar variación de bloque
Las variaciones de bloque son versiones preconfiguradas de un bloque, con un conjunto de atributos y bloques anidados. WordPress trata las variaciones de bloque como bloques independientes, haciéndolas disponibles en el insertador de bloques y marcándolas con un icono personalizado.
Puedes utilizar una variación de bloque para crear una nueva versión del bloque Imagen con el estilo Polaroid aplicado por defecto.
El primer paso es importar la función registerBlockVariation a tu archivo /src/index.js:
import { registerBlockStyle, registerBlockVariation } from '@wordpress/blocks';Luego añades una llamada a la función registerBlockVariation dentro de domReady(), justo debajo de registerBlockStyle:
domReady(() => {
// Register a style variation for the image block.
registerBlockStyle('core/image', {
name: 'polaroid',
label: 'Polaroid',
});
// Register a block variation of the image block
registerBlockVariation('core/image', {
name: 'animated-polaroid',
title: 'Animated Polaroid',
icon: 'image-filter',
attributes: {
className: 'is-style-polaroid',
imageAnimation: true,
},
scope: ['inserter'],
});
});La función registerBlockVariation crea una variación para un bloque existente. Acepta dos argumentos: el nombre del bloque y un objeto que define la variación. (Consulta también la introducción a las variaciones de bloque y la documentación de la API Variaciones de bloque).
Guarda tu archivo, ejecuta la construcción para aplicar los cambios y, a continuación, vuelve al administrador de WordPress. Crea una nueva entrada y busca el bloque Polaroid Animada en el insertador de bloques.
Pruebas y depuración
Hagamos algunas pruebas. Añade una o varias imágenes a una nueva entrada. Selecciona el estilo Polaroid para cada imagen, activa la animación y añade enlaces. Además, haz pruebas con el bloque Galería.
Todo parece funcionar como se espera. Sin embargo, añadir un enlace con efecto lightbox a una imagen con el estilo Polaroid no produce un resultado agradable.
Este extraño comportamiento parece deberse a un problema de compatibilidad entre la caja de luz de WordPress y las transiciones CSS.
Para evitar un proceso de depuración largo y complejo, puedes desactivar la opción Ampliar al hacer clic y añadir una advertencia para notificar a los usuarios que la caja de luz está desactivada.
Primero necesitas importar algunos recursos adicionales. A continuación encontrarás la lista completa de recursos importados desde el archivo /src/index.js:
import { registerBlockStyle, registerBlockVariation } from '@wordpress/blocks';
import domReady from '@wordpress/dom-ready';
import { addFilter } from '@wordpress/hooks';
import { createHigherOrderComponent } from '@wordpress/compose';
import { Fragment, useEffect } from '@wordpress/element';
import { InspectorControls, BlockControls } from '@wordpress/block-editor';
import { PanelBody, Notice, ToolbarGroup, ToolbarButton } from '@wordpress/components';
import { __ } from '@wordpress/i18n';
import { useDispatch } from '@wordpress/data';
import './style.scss';Hemos añadido las siguientes importaciones:
useEffectde@wordpress/element. (Ver documentación)InspectorControlsde@wordpress/block-editor(Ver documentación).PanelBodyyNoticede@wordpress/components(Ver documentación).useDispatchdesde@wordpress/data. (Ver blog del desarrollador de WordPress)
Ahora cambia la función withPolaroidControls de la siguiente manera:
const withPolaroidControls = createHigherOrderComponent((BlockEdit) => {
return (props) => {
if (props.name !== 'core/image') {
return <BlockEdit {...props} />;
}
const { attributes, setAttributes, isSelected } = props;
const { imageAnimation, className, lightbox } = attributes;
const isPolaroid = className?.includes('is-style-polaroid');
const { createNotice } = useDispatch('core/notices');
useEffect(() => {
if (isPolaroid && lightbox?.enabled) {
// Disable the lightbox to prevent the conflict.
setAttributes({ lightbox: { ...lightbox, enabled: false } });
// Show the user a temporary 'snackbar' notice.
createNotice(
'warning', // The type of notice (info, success, warning, error)
__('Lightbox disabled for Polaroid style.', 'image-hacker'),
{
type: 'snackbar',
isDismissible: true,
}
);
}
}, [isPolaroid, lightbox]);
return (
<Fragment>
<BlockEdit {...props} />
<BlockControls>
<ToolbarGroup>
<ToolbarButton
icon="format-image"
label={__('Toggle Animation', 'image-hacker')}
isActive={imageAnimation}
onClick={() =>
setAttributes({ imageAnimation: !imageAnimation })
}
/>
</ToolbarGroup>
</BlockControls>
{isSelected && isPolaroid && (
<InspectorControls>
<PanelBody title={__('Polaroid Style', 'image-hacker')}>
<Notice status="info" isDismissible={false}>
{__(
'The "Expand on click" (lightbox) feature is disabled for this style to prevent visual conflicts.',
'image-hacker'
)}
</Notice>
</PanelBody>
</InspectorControls>
)}
</Fragment>
);
};
}, 'withPolaroidControls');useEffectes un Hook React que «te permite sincronizar un componente con un sistema externo». El código se ejecuta después de que el componente se haya renderizado y cada vez que cambie un valor del array de dependencias[isPolaroid, lightbox]. La comprobación sólo se ejecuta cuando el usuario aplica o elimina el estilo Polaroid o activa o desactiva la caja de luz (consulta la documentación de React).- La condición
if (isPolaroid() && lightbox.enabled)garantiza que el código sólo se ejecute si la imagen tiene el estilo Polaroid y la opción lightbox está activada. - Si la condición es
true, la caja de luz se desactiva y aparece un aviso temporal. (Ver también la referencia de datos Avisos). - La condición
isSelected && isPolaroidgenera un nuevo panel en la barra de herramientas del bloque de imagen para notificar a los usuarios que la caja de luz está desactivada. A diferencia de la barra de herramientas, este panel muestra un aviso permanente.
Resumen
En este tutorial, hemos profundizado en algunas de las funcionalidades más interesantes y potentes para desarrolladores del editor de bloques de WordPress a través de un proyecto real: hemos ampliado el bloque Imagen básico con funcionalidades que no están disponibles de serie, con estilos personalizados y efectos de animación.
Hemos seguido un enfoque de mejora progresiva, creando una variación de estilo de bloque para el bloque Imagen. Esto permite a los usuarios dar fácilmente a sus imágenes un aspecto clásico de Polaroid.
A continuación, hemos añadido un botón específico a la barra de herramientas del bloque Imagen, que permite a los usuarios crear un atractivo efecto de animación al pasar el cursor por encima.
Por último, lo hemos completado creando una variación del bloque preconfigurada con el estilo Polaroid y los ajustes de animación aplicados por defecto.
Esperamos que las ideas y técnicas que has adquirido en este tutorial te permitan crear algunas personalizaciones realmente sorprendentes para los bloques principales de Gutenberg.
¡Feliz programación!
