Gutenberg si è evoluto in un editor potente e altamente personalizzabile. Al di là delle sue solide funzionalità, gli sviluppatori di WordPress ora possono sfruttare un ricco set di API per integrare facilmente funzionalità personalizzate nei loro siti web. Questa estensibilità porta con sé notevoli possibilità di sviluppo su misura, permettendo di creare esperienze online altamente personalizzate e ricche di funzionalità.
Questo articolo esplora due funzionalità di WordPress meno note eppure potenti: Varianti di stile (note anche come stili di blocco) e Varianti di blocco.
Anche se all’inizio la loro utilità può sembrare un po’ oscura, la loro utilità è sorprendente e un piccolo investimento di tempo permetterà di integrarli nel workflow senza problemi.
Vedremo da vicino cosa sono e come usarli attraverso un progetto reale. Potremo implementare questo progetto su un sito WordPress semplicemente copiando e incollando il codice di questo tutorial ed eventualmente aggiungendo delle personalizzazioni.
Prima di immergerci nel progetto, esaminiamo rapidamente i prerequisiti:
- Ambiente di sviluppo WordPress locale: anche se va bene qualsiasi ambiente, noi consigliamo vivamente DevKinsta, la suite di sviluppo locale di Kinsta. È intuitiva e offre molte impostazioni e strumenti per lanciare rapidamente e gestire senza fatica un sito WordPress locale.
- Node.js e npm: sono essenziali perché l’editor di blocchi è costruito su React e richiede un processo di build.
- Competenze di base nello sviluppo frontend: sarà utile avere una conoscenza di base di Node.js, JavaScript (con React), PHP e CSS.
Anche se questo progetto non è eccessivamente complesso, bisognerà scrivere un po’ di codice. Il codice completo è disponibile anche su GitHub.
Iniziamo!
Stili di blocco e Varianti di blocco
Gli stili di blocco e le varianti di blocco sono due potenti funzionalità di WordPress per gli sviluppatori. Sebbene i loro nomi suonino piuttosto simili, differiscono per scopo e utilizzo.
Gli stili di blocco, noti anche come varianti di stile, sono set predefiniti di stili CSS che permettono di cambiare l’aspetto di un blocco con un solo clic. Dopo aver registrato uno stile di blocco, nella barra laterale del blocco appare un pulsante che permette all’utente di assegnare un set predefinito di stili al blocco. È possibile attivare e disattivare gli stili e visualizzare l’anteprima del blocco nell’editor in tempo reale.
Le varianti di stile non alterano gli attributi del blocco. Modificano solo l’aspetto di un blocco assegnando una classe CSS all’elemento che lo contiene.
Le varianti di blocco sono uno strumento più potente perché permettono di creare una versione preconfigurata di un blocco con attributi e blocchi interni. Inoltre, vengono visualizzate nel pannello di inserimento dei blocchi dell’editor. In sostanza, una variante di blocco appare all’utente come se fosse un blocco a sé stante, completamente indipendente dal blocco su cui è costruito.
Le varianti di blocco consentono di personalizzare l’aspetto, le impostazioni iniziali e la struttura di un blocco.
Tenendo presente tutto questo, utilizziamo questi strumenti per portare i blocchi di Gutenberg a un livello superiore!
Un effetto Polaroid animato su un blocco Immagine
Ora immergiamoci nel nostro progetto! Estenderemo il blocco core Immagine con un plugin Gutenberg per:
- Implementare una variante di stile Polaroid: gli utenti potranno applicare un gradevole effetto Polaroid alle loro immagini con un solo clic dalla barra laterale delle impostazioni del blocco.
- Aggiungere un’animazione hover: Miglioreremo le immagini in stile Polaroid con una leggera animazione hover.
- Creare una variante del blocco “Animated Polaroid”: ciò consentirà agli utenti di inserire rapidamente immagini Polaroid preconfigurate con un effetto hover direttamente dal pannello di inserimento dei blocchi.
Pronti? Configuriamo il nostro plugin!
Configurazione dell’ambiente
Prima di iniziare, dobbiamo configurare un ambiente di sviluppo WordPress con Node.js. Partiamo dal presupposto di aver già installato l’ambiente di sviluppo WordPress locale e le ultime versioni di Node.js e npm. Se ci fosse bisogno di aiuto, c’è sempre il nostro tutorial su come creare un plugin Gutenberg per aggiungere funzionalità all’editor a blocchi.
Passo 1 – Creare la struttura di base del plugin
Per questo tutorial, chiameremo il nostro plugin Image Hacker.
Spostiamoci nella tua cartella plugins e creiamo una nuova cartella image-hacker. All’interno di questa cartella, creiamo un nuovo file image-hacker.php (il file principale del plugin) e una sottocartella src, dove svilupperemo le funzionalità del plugin.
Ecco la struttura di base del plugin:
/wp-content/plugins/
└── /image-hacker/
├── image-hacker.php
└── /src/Passo 2 – Creare il codice PHP
Di seguito, dobbiamo assicurarci che WordPress riconosca il plugin. Per farlo, aggiungiamo il seguente codice 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:
* Text Domain: image-hacker
*/
if ( ! defined( 'ABSPATH' ) ) {
exit; // Exit if accessed directly.
}Passo 3 – Inizializzare npm e installare le dipendenze
Apriamo lo strumento a riga di comando preferito e spostiamoci nella directory del plugin. Una volta lì, eseguiamo il seguente comando:
npm init -yQuesto comando inizializza un nuovo file package.json, che include le dipendenze e gli script del progetto.
Quindi dovremo installare gli script di WordPress e gli strumenti di compilazione come webpack e Babel:
npm install @wordpress/plugins @wordpress/scripts --save-devQuesto comando crea una cartella node_modules con le dipendenze di Node e un file package-lock.json. L’immagine che segue mostra la struttura attuale del progetto in Visual Studio Code:
Ora apriamo il package.json e aggiorniamo la proprietà scripts come segue:
{
"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"
}
}Si noti che le versioni di devDependencies possono differire da quelle indicate qui sopra e dipendono dalle versioni effettivamente installate nell’ambiente.
Passo 4 – Creare i file sorgente del plugin
Il passo successivo consiste nel creare i file sorgente del plugin. Andiamo nella cartella src e aggiungiamo i seguenti file:
index.jsstyle.scsseditor.scss
La struttura del plugin dovrebbe ora essere questa:
/wp-content/plugins/
└── /image-hacker/
├── /node-modules/
├── image-hacker.php
├── package.json
├── package-lock.json
└── /src/
├── index.js
├── style.scss
└── editor.scssOra apriamo il pannello di amministrazione di WordPress e andiamo alla schermata dei plugin. Cerchiamo il plugin Image Hacker e attiviamolo.
Passo 5 – Includere le risorse nel file del plugin
Ora dobbiamo includere le risorse necessarie nel file principale del plugin. Aggiungiamo quanto segue 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' );Ecco cosa fa questo codice:
- L’hook
enqueue_block_editor_assetsinserisce lo scriptindex.jse il fileeditor.css. - L’hook
enqueue_block_assetsrichiede il filestyle.css.
Si noti che questo codice include le risorse .js e .css che si trovano nella cartella /build/ del plugin. Ciò significa che, per farlo funzionare, è necessario eseguire il comando build nello strumento a riga di comando:
npm run buildInoltre, quando si importa un file chiamato style.scss in index.js, il file CSS compilato non si chiamerà style.css ma style-index.css.
Registrare lo stile del blocco
Abbiamo completato la configurazione dell’ambiente di sviluppo. Ora possiamo passare alla parte più interessante del progetto e registrare una variante di stile del blocco.
Esistono diversi modi per registrare gli stili del blocco e quello che si sceglie dipende dagli obiettivi e dalle preferenze personali. Noi seguiremo l’approccio JS per costruire un plugin Gutenberg. Apriamo il file /src/index.js e incolliamo il seguente codice:
// 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 assicura che la variante di stile venga registrata solo quando il DOM è completamente caricato. Si legga anche la documentazione ufficiale.
Quando viene selezionato lo stile Polaroid, WordPress aggiunge automaticamente la classe .is-style-polaroid al contenitore del blocco.
Il passo successivo consiste nel fornire il codice CSS per la variante di stile. Apriamo il file /src/style.scss e aggiungiamo il seguente codice:
.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;
}
}Salviamo il codice, eseguiamo npm run build e accediamo alla dashboard di WordPress. Creiamo un nuovo post o una nuova pagina e aggiungiamo un’immagine. Con l’immagine selezionata, clicchiamo sull’etichetta Stili nella barra laterale del blocco e selezioniamo Polaroid.
Aggiungiamo una didascalia, salviamo il post e controlliamo il risultato nel frontend. Dovremmo vedere un’immagine in stile Polaroid con una bella didascalia in corsivo.
Creare la logica
Il passo successivo consiste nel creare la logica per animare l’immagine. Creeremo una semplice animazione usando la proprietà CSS transform. Per iniziare, aggiungiamo il seguente blocco al file src/style.scss:
.wp-block-image.is-style-polaroid.has-image-animation:hover {
transform: rotate(0deg) scale(1.05);
}Questo codice assicura che l’effetto hover venga applicato solo se il blocco è un’immagine Polaroid e ha una classe has-image-animation. Questa viene applicata dal toggle della barra degli strumenti.
Ora serve la logica per aggiungere la classe CSS al contenitore dell’immagine, che è un elemento figure. Per farlo, abbiamo bisogno di alcuni filtri e funzioni di callback.
Per prima cosa, aggiungiamo la seguente riga al file src/index.js:
import { addFilter } from '@wordpress/hooks';Passo 1. Aggiungere un nuovo attributo al blocco Immagine
Utilizzeremo addFilter per manipolare il blocco Image. Aggiungiamo un nuovo attributo imageAnimation al blocco Immagine:
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 funzione di callback addImageAnimationAttribute accetta due argomenti:
settings: un array di attributi del blocco correntename: il nome del blocco di cui vogliamo modificare gli attributi.
La funzione restituisce l’array di attributi aggiornato.
Passo 2. Aggiungere un controllo al blocco Image
Ora dobbiamo aggiungere un controllo alla barra degli strumenti del blocco Immagine per attivare l’animazione.
Per prima cosa, aggiungiamo i seguenti import al file 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';Quindi aggiungiamo il seguente codice alla fine del file:
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
);Ecco cosa fa questo codice:
- La funzione
createHigherOrderComponentcrea un componente di ordine superiore (HOC) che racchiudeBlockEdit, che è il componente principale responsabile della visualizzazione dei blocchi nell’editor. - L’HOC intercetta il componente e verifica che si tratti di un blocco Immagine. Questo assicura che tutte le modifiche vengano applicate solo al blocco Immagine.
- L’assegnazione per destrutturazione estrae le proprietà e gli attributi necessari dagli oggetti
propseattributes. BlockControls,ToolbarGroupeToolbarButtonaggiungono un pulsante di attivazione dell’animazione alla barra degli strumenti del blocco.isActiveimposta lo stato predefinito diimageAnimationonClickinverte il valore diimageAnimation.
Ora abbiamo un attributo e un pulsante. Tuttavia, se facciamo clic sul pulsante, non succede nulla.
Passo 3. Aggiungere la classe CSS all’elemento wrapper
Il passo successivo consiste nell’applicare la classe has-image-animation all’elemento figure che racchiude l’immagine. Per farlo, abbiamo bisogno di un filtro che permetta di assegnare la classe CSS all’immagine nel frontend.
Aggiungiamo il seguente codice al file 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
);Questo codice aggiunge dinamicamente la classe CSS has-image-animation all’elemento figure quando l’attributo imageAnimation è impostato su true.
Cerchiamo di capire cosa succede nel dettaglio.
addFiltersi aggancia ai processi dell’editor per modificare dati o comportamenti.blocks.getSaveContent.extraPropsè il gancio specifico a cui ci rivolgiamo.extraPropsè un hook speciale che permette di aggiungere attributi HTML extra all’elemento wrapper.image-hacker/add-animation-classè il nome univoco del filtro.addAnimationFrontendClassè il nome della funzione di callback che viene eseguita ogni volta che viene eseguito l’hookblocks.getSaveContent.extraProps. Questa funzione accetta 3 argomenti:extraProps: un oggetto contenente le proprietà dell’elemento wrapper del blocco, come ad esempioclassName.blockType: un oggetto con i dati del blocco, come ad esempioname(core/image).attributes: un oggetto contenente gli attributi del blocco
- La logica della funzione assicura che il codice venga eseguito solo quando
blockType.name === 'core/image'eattributes.imageAnimationsonotrue. - Se entrambe le condizioni sono vere, la funzione restituisce un nuovo oggetto
propsconhas-image-animationaggiunto alla classe dell’oggetto esistente.
Ora facciamo una prova. Aggiungiamo un’immagine al contenuto, selezioniamo lo stile Polaroid dalla barra laterale dei blocchi e clicchiamo sul pulsante Toggle Animation nella barra degli strumenti del blocco. Salviamo il post e controlliamo il risultato nel frontend. Passando il mouse sopra, l’immagine dovrebbe ruotare.
Registrazione della variante del blocco
Le varianti di blocco sono versioni preconfigurate di un blocco, con una serie di attributi e blocchi annidati. WordPress tratta le varianti di blocco come blocchi indipendenti, rendendole disponibili nel pannello di inserimento dei blocchi e contrassegnandole con un’icona personalizzata.
Ora utilizzeremo una variante di blocco per creare una nuova versione del blocco Immagine con lo stile Polaroid applicato di default.
Il primo passo è importare la funzione registerBlockVariation nel file /src/index.js:
import { registerBlockStyle, registerBlockVariation } from '@wordpress/blocks';Poi aggiungiamo una chiamata alla funzione registerBlockVariation all’interno di domReady(), proprio sotto 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 funzione registerBlockVariation crea una variante per un blocco esistente. Accetta due argomenti: il nome del blocco e un oggetto che definisce la variante (si veda anche l’introduzione alle varianti di blocco e la documentazione della Block Variations API).
Salviamo il file, eseguiamo la build per applicare le modifiche e poi torniamo al pannello di amministrazione di WordPress. Creiamo un nuovo post e cerchiamo il blocco Animated Polaroid nel pannello di inserimento dei blocchi.
Test e debug
Facciamo qualche prova. Aggiungiamo una o più immagini a un nuovo post. Selezioniamo lo stile Polaroid per ogni immagine, attiviamo l’animazione e aggiungiamo i link. Eseguiamo anche dei test con il blocco Galleria.
Tutto sembra funzionare come previsto. Tuttavia, l’aggiunta di un link con effetto lightbox a un’immagine con lo stile Polaroid non produce un risultato gradevole.
Questo strano comportamento sembra essere dovuto a un problema di compatibilità tra il lightbox di WordPress e le transizioni CSS.
Per evitare un lungo e complesso processo di debug, potremmo disabilitare l’opzione Ingrandisci al clic e aggiungere un alert per avvisare gli utenti che il lightbox è disabilitato.
Per prima cosa, dobbiamo importare alcune risorse aggiuntive. Di seguito riportiamo l’elenco completo delle risorse importate dal file /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';Abbiamo aggiunto le seguenti importazioni:
Ora modifichiamo la funzione withPolaroidControls come segue:
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');useEffectè un hook di React che “permette di sincronizzare un componente con un sistema esterno”. Il codice viene eseguito dopo il rendering del componente e ogni volta che un valore dell’array di dipendenze[isPolaroid, lightbox]cambia. Il controllo viene eseguito solo quando l’utente applica o rimuove lo stile Polaroid o attiva o disattiva la lightbox (vedi la documentazione di React).- La condizione
if (isPolaroid() && lightbox.enabled)assicura che il codice venga eseguito solo se l’immagine ha lo stile Polaroid e l’opzione lightbox è attiva. - Se la condizione è
true, il lightbox viene disattivato e viene visualizzato un avviso temporaneo vedi anche la documentazione degli avvisi). - La condizione
isSelected && isPolaroidgenera un nuovo pannello nella barra degli strumenti del blocco immagine per avvisare gli utenti che la lightbox è disabilitata. A differenza della barra degli strumenti, questo pannello visualizza un avviso permanente.
Riepilogo
In questo tutorial abbiamo analizzato alcune delle funzionalità più interessanti e potenti per gli sviluppatori dell’editor di blocchi di WordPress dandoci come obiettivo la realizzazione di un progetto reale: abbiamo esteso il blocco Immagine predefinito con funzionalità non disponibili, con stili personalizzati ed effetti di animazione.
Abbiamo seguito un approccio di miglioramento progressivo, creando una variante di stile per il blocco Immagine. In questo modo gli utenti possono dare alle loro immagini un aspetto classico da Polaroid in modo semplice.
Abbiamo poi aggiunto un pulsante alla barra degli strumenti del blocco Immagine, consentendo agli utenti di creare un accattivante effetto di animazione al passaggio del mouse.
Infine, abbiamo creato una variante del blocco preconfigurata con lo stile Polaroid e le impostazioni di animazione applicate di default.
Ci auguriamo che le conoscenze e le tecniche acquisite in questo tutorial permettano di creare personalizzazioni davvero sorprendenti per i blocchi core di Gutenberg!
Happy coding!
Kinsta
Carlo è cultore appassionato di webdesign e front-end development. Gioca con WordPress da oltre 20 anni, anche in collaborazione con università ed enti educativi italiani ed europei. Su WordPress ha scritto centinaia di articoli e guide, pubblicati sia in siti web italiani e internazionali, che su riviste a stampa. Lo trovate su LinkedIn.
Home Appliance/
Pendidikan
Pendidikan
Download Anime
Berita Teknologi
Seputar Teknologi
