Guida agli shortcode di WordPress

Cosa sono gli shortcode di WordPress

Gli shortcode sono tag speciali racchiusi tra parentesi quadre che il motore di WordPress sostituisce automaticamente con contenuti dinamici. Per esempio [gallery] visualizza una galleria di immagini, [video] incorpora un video e [contact-form] mostra un modulo di contatto. Gli shortcode consentono agli utenti senza conoscenze tecniche di inserire contenuti complessi negli articoli e nelle pagine semplicemente digitando un breve codice.

Gli shortcode integrati di WordPress coprono le esigenze di base, ma la vera potenza deriva dalla possibilità di creare i propri shortcode. Gli sviluppatori di plugin li utilizzano per aggiungere funzionalità come moduli, tabelle dei prezzi, slider e pulsanti, mentre gli sviluppatori di temi usano gli shortcode per gli elementi di design ricorrenti. Comprendere il sistema degli shortcode è una competenza importante per ogni utente e sviluppatore di WordPress.

Shortcode integrati di WordPress

WordPress include diversi shortcode integrati che coprono le esigenze multimediali di base. Questi shortcode funzionano da subito, senza bisogno di plugin aggiuntivi, e supportano vari parametri per personalizzare l'output.

Elenco degli shortcode integrati

• [caption] - aggiunge una didascalia sotto l'immagine con una cornice stilizzata
• [gallery] - visualizza una galleria di immagini dalla libreria multimediale con opzioni per colonne e dimensioni
• [audio] - incorpora un player audio con i controlli di riproduzione
• [video] - incorpora un player video con supporto per i formati MP4, WebM e Ogg
• [playlist] - crea una playlist audio o video da più file
• [embed] - incorpora contenuti da servizi esterni tramite il protocollo oEmbed

Lo shortcode gallery in dettaglio

Lo shortcode gallery è quello integrato più utilizzato perché consente di creare rapidamente gallerie di immagini. Supporta parametri come ids per immagini specifiche, columns per il numero di colonne, size per la dimensione delle immagini, orderby per l'ordinamento e link per stabilire dove conduce il clic sull'immagine. Per esempio, [gallery ids="1,2,3" columns="3" size="medium"] visualizza tre immagini specifiche in tre colonne di dimensione media.

Creazione di shortcode personalizzati

Creare i propri shortcode nell'ambiente di sviluppo di WordPress è sorprendentemente semplice. Si utilizza la funzione add_shortcode(), che accetta due argomenti: il nome dello shortcode e la funzione di callback che restituisce l'HTML da visualizzare. Questa funzione si aggiunge al file functions.php del tema o a un plugin personalizzato.

Struttura di base

La funzione di callback riceve fino a tre parametri: $atts (array di attributi che l'utente passa), $content (contenuto compreso tra il tag di apertura e quello di chiusura) e $tag (nome dello shortcode stesso). La funzione deve restituire una stringa con l'HTML e non deve mai usare echo, perché ciò comprometterebbe l'ordine di visualizzazione sulla pagina. Si tratta di un errore comune tra i principianti che porta il contenuto dello shortcode a comparire in cima alla pagina anziché nel punto in cui lo shortcode è stato inserito.

Esempio di shortcode semplice

Immagina di volere uno shortcode che visualizzi una citazione in evidenza con il nome dell'autore. Nel file functions.php definiresti una funzione che accetta gli attributi (autore, colore) e il contenuto (testo della citazione) e restituisce un blocco HTML stilizzato. L'utente scriverebbe nell'editor [quote author="Dante Alighieri"]Nel mezzo del cammin di nostra vita...[/quote] e WordPress lo sostituirebbe con una citazione formattata con il nome dell'autore sotto il testo.

Parametri degli shortcode

I parametri (attributi) rendono gli shortcode flessibili perché consentono agli utenti di personalizzare l'output senza modificare il codice. Utilizza la funzione shortcode_atts() per definire i valori predefiniti e fonderli con i valori passati dall'utente. In questo modo lo shortcode funziona anche quando l'utente non specifica tutti i parametri.

Tipi di parametri

• Testo - titolo, colore, classe, ID (es. title="Titolo")
• Numerico - numero di colonne, limite dei risultati, larghezza (es. columns="3")
• Booleano - opzioni sì/no (es. show_date="true")
• Elenco - ID separati da virgola (es. ids="1,5,12,7")
• Enum - opzioni predefinite (es. size="small|medium|large")

Convalida e sanitizza sempre i parametri passati dall'utente, perché gli shortcode possono diventare un vettore per attacchi XSS se l'input dell'utente viene incorporato direttamente nell'HTML. Utilizza le funzioni esc_attr(), esc_html() e wp_kses() per la pulizia dell'output. Converti i parametri numerici in int con intval() e confronta i parametri booleani con la stringa true o false.

Shortcode annidati

WordPress supporta l'annidamento degli shortcode, il che significa che puoi inserire uno shortcode all'interno di un altro. Questo è utile per creare layout complessi in cui, per esempio, hai uno shortcode per una riga e al suo interno uno shortcode per le colonne. Il contenuto annidato viene elaborato richiamando la funzione do_shortcode() sul parametro $content all'interno della tua funzione di callback.

Una limitazione importante è che non puoi annidare lo stesso shortcode dentro se stesso, perché il parser di WordPress non riesce a distinguere correttamente i tag di apertura e di chiusura. Se ti serve una funzionalità del genere, crea varianti dello shortcode con nomi diversi, come [row] per la riga e [column] per la colonna all'interno della riga. Questa limitazione è voluta per progettazione ed è improbabile che cambi nelle versioni future.

Esempio di annidamento

Un esempio classico è uno shortcode di layout in cui [row] crea un contenitore flex o grid e [col width="6"] crea una colonna di larghezza specifica. L'utente può scrivere [row][col width="4"]Colonna sinistra[/col][col width="8"]Colonna destra[/col][/row] e ottenere un layout a due colonne. Lo shortcode row deve richiamare do_shortcode($content) affinché WordPress elabori gli shortcode col annidati prima di restituire l'HTML finale.

Shortcode nell'editor a blocchi di WordPress

Con l'introduzione dell'editor a blocchi Gutenberg, gli shortcode hanno ottenuto un blocco dedicato chiamato Shortcode che accetta qualsiasi shortcode. Tuttavia, la tendenza nello sviluppo moderno di WordPress si sta orientando verso la sostituzione degli shortcode con blocchi personalizzati che offrono un'anteprima visiva nell'editor anziché testo grezzo tra parentesi quadre. Per i nuovi progetti, valuta la creazione di blocchi anziché di shortcode, ma per i siti esistenti gli shortcode restano completamente supportati e funzionali.

Quando usare gli shortcode e quando i blocchi

• Gli shortcode sono migliori per inserimenti semplici (citazione, pulsante, icona)
• I blocchi sono migliori per elementi di layout complessi con visualizzazione visiva
• Gli shortcode funzionano nell'editor classico e in quello a blocchi
• I blocchi funzionano solo nell'editor a blocchi (Gutenberg)
• Gli shortcode sono più rapidi da sviluppare, i blocchi richiedono la conoscenza di JavaScript
• Per la compatibilità con i plugin, gli shortcode sono più universali

Consigli pratici e best practice

Assegna agli shortcode il prefisso del tuo tema o plugin per evitare conflitti con altri plugin. Per esempio, invece di [button] usa [beo_button], perché è meno probabile che un altro plugin utilizzi lo stesso nome. Aggiungi la documentazione per ogni shortcode che crei, inclusi l'elenco dei parametri, i valori predefiniti e gli esempi d'uso, perché senza documentazione non ricorderai tutte le opzioni nemmeno tu stesso dopo qualche mese.

Per gli shortcode più complessi che generano una quantità significativa di HTML, utilizza l'output buffering o file di template anziché la concatenazione di stringhe. In questo modo il codice diventa più leggibile e più facile da mantenere. Memorizza nella cache i risultati degli shortcode che richiedono query al database. Usa lo strumento di verifica della velocità con la Transients API, perché gli shortcode vengono eseguiti a ogni caricamento di pagina e quelli lenti possono rallentare notevolmente il sito. Testa sempre gli shortcode in contesti diversi, inclusi widget, riassunti e feed RSS, perché il comportamento può variare.