Immagina di dover aggiungere una galleria di 20 immagini a un articolo. Senza shortcode, sarebbero decine di righe di HTML con wrapper, classi, attributi data e link alle anteprime. Con uno shortcode, basta una riga: [gallery]. È stato proprio per questo contrasto tra volume di lavoro ripetitivo e risultati che WordPress 2.5 ha introdotto gli shortcode e, a quasi vent'anni di distanza, il meccanismo resta indispensabile.

Il problema è che la maggior parte degli utenti o teme gli shortcode considerandoli «roba da programmatori» oppure li copia alla cieca senza capirne la sintassi. Nel frattempo, un singolo shortcode personalizzato può sostituire un plugin da quaranta megabyte o far risparmiare un'ora di lavoro ripetitivo al mese. Questa analisi, dallo shortcode nativo [gallery] e [audio] fino al tuo shortcode personale in functions.php, ti darà il controllo completo sullo strumento.

💡 Panoramica rapida:

• Cos'è uno shortcode: un tag tra parentesi quadre che WordPress sostituisce con il risultato di una funzione PHP al caricamento della pagina.
• Shortcode nativi: gallery, audio, video, caption, embed e playlist funzionano subito dopo l'installazione di WordPress, senza plugin.
• Parametri degli shortcode: la sintassi key="value" permette di personalizzare l'output senza modificare il codice.
• Creare il proprio shortcode: dalla semplice sostituzione di un URL a uno shortcode per immagini con attributi, con codice PHP pronto per functions.php.
• Shortcode nei widget e nei template: come abilitare il supporto con una riga e dove torna utile.

Cos'è uno shortcode e come funziona

Uno shortcode è un breve tag tra parentesi quadre che WordPress sostituisce con il risultato dell'esecuzione di una funzione PHP nel momento in cui la pagina viene generata. Scrivi [gallery] nell'editor, i visitatori vedono una griglia ordinata di immagini. Nessuna magia: dietro ogni shortcode c'è una funzione registrata tramite add_shortcode() nel core, nel tema o in un plugin.

La differenza fondamentale rispetto agli inserimenti HTML statici: uno shortcode viene eseguito lato server. Gli passi dei parametri e il risultato viene generato dinamicamente. Il contenuto cambia, l'output cambia, senza dover modificare manualmente decine di pagine.

Dal punto di vista dell'editor, c'è una sfumatura da considerare. L'editor visuale (Gutenberg o il classico TinyMCE) mostra subito lo shortcode come anteprima, quindi per lavorare con parametri e tag annidati bisogna passare alla modalità testo. Solo lì puoi vedere la struttura reale: tag di apertura, attributi, contenuto, tag di chiusura.

Shortcode nativi di WordPress: cosa hai a disposizione senza plugin

WordPress viene distribuito con sei shortcode registrati. Non devi attivarli né configurarli, ti basta inserirli in un articolo e ottenere il risultato.

Il più flessibile tra questi è [gallery]. L'attributo ids permette di specificare immagini precise tramite ID, anche quelle non collegate all'articolo corrente. L'attributo size imposta la dimensione delle anteprime (thumbnail, medium, large o full). La combinazione di questi due parametri copre la maggior parte degli scenari per cui un tempo si installava un plugin galleria dedicato.

[audio] e [video] supportano sorgenti multiple, il browser sceglierà il formato compatibile. Le playlist tramite [playlist] vengono create a partire dagli ID degli allegati in modo simile a una galleria, ma restituiscono un player con cambio traccia.

Parametri degli shortcode: come controllare l'output

La maggior parte degli shortcode accetta attributi nel formato key="value". Sostituire i valori cambia la logica della funzione senza intervenire sul codice.

Prendi [gallery]. Senza parametri, mostra tutte le immagini dell'articolo nella dimensione standard. Aggiungi delle specifiche:

1
[gallery ids="12,34,56" size="large" columns="3"]

Ora l'output è limitato a tre immagini specifiche, la dimensione è aumentata a large e la griglia è organizzata in tre colonne. I parametri possono essere combinati liberamente, quelli non specificati ricevono i valori predefiniti.

Alcuni shortcode usano tag di apertura e chiusura quando è necessario passare del contenuto tra di essi. Ad esempio, un plugin per Google Maps potrebbe aspettarsi una costruzione del tipo:

1
[maps]New York, USA[/maps]

Il tag di chiusura inizia sempre con una barra /. WordPress usa questa notazione per distinguere il contenuto tra i tag dagli attributi all'interno del tag di apertura.

Come creare il tuo shortcode personale

Quando hai inserito lo stesso URL, blocco HTML o call-to-action negli articoli per la decima volta in una settimana, è il momento di scrivere uno shortcode. Non serve essere uno sviluppatore PHP: la struttura di base sta in tre righe.

Shortcode semplice per un URL

Aggiungi questo codice in fondo al file functions.php del tuo tema (Aspetto → Editor del tema → functions.php):

1
function techblog_short_url() {
2
    return 'https://techblog.sdstudio.top';
3
}
4
add_shortcode( 'techblog', 'techblog_short_url' );

Ora in qualsiasi articolo, [techblog] verrà automaticamente sostituito con l'URL del sito. La funzione restituisce una stringa, WordPress la sostituisce al posto dello shortcode.

Due regole di importanza critica dalla documentazione ufficiale:

• La funzione restituisce un valore tramite return, non produce output con echo. L'output diretto rompe l'ordine di rendering e porta a risultati imprevisti.
• Registra gli shortcode sull'hook init in modo che WordPress abbia il tempo di caricare tutte le dipendenze:

1
add_action( 'init', 'techblog_register_shortcodes' );
2
function techblog_register_shortcodes() {
3
    add_shortcode( 'techblog', 'techblog_short_url' );
4
}

Shortcode per immagine con attributi personalizzabili

Uno scenario leggermente più complesso: vuoi inserire un'immagine, impostando larghezza e altezza direttamente nell'editor. In functions.php:

1
function techblog_img_shortcode( $atts, $content = null ) {
2
    $atts = shortcode_atts(
3
        array(
4
            'width'  => '',
5
            'height' => '',
6
        ),
7
        $atts,
8
        'img'
9
    );
10
    return '<img src="' . esc_url( $content ) . '" width="' . esc_attr( $atts['width'] ) . '" height="' . esc_attr( $atts['height'] ) . '" alt="" />';
11
}
12
add_shortcode( 'img', 'techblog_img_shortcode' );

Utilizzo nell'editor:

1
[img width="800" height="600"]https://example.com/photo.jpg[/img]

La funzione shortcode_atts() unisce gli attributi passati con i valori predefiniti, questo è il modo standard e sicuro per gestire i parametri. Nota esc_url() e esc_attr(): l'escape è obbligatorio quando si produce output di dati inseriti dall'utente nel frontend. Un elenco completo degli attributi disponibili per le immagini si trova nella specifica W3C.

Merita una menzione a parte la validazione degli attributi. Quando accetti valori dall'editor e li inserisci nell'HTML, verifica sempre i tipi di dato. Per attributi numerici come width e height, usa intval(), questo eliminerà eventuali lettere inserite per errore. Per le stringhe, definisci un insieme di valori consentiti tramite in_array(), ad esempio le dimensioni delle miniature (thumbnail, medium, large). In questo modo il layout resta integro e i risultati nel frontend saranno prevedibili, anche se l'autore commette un errore nel valore dell'attributo.

Shortcode nei widget di testo e nei file PHP

Dalla versione di WordPress 4.9 (novembre 2017), gli shortcode funzionano automaticamente nei widget di testo. Ma se stai usando un tema personalizzato senza supporto integrato, puoi abilitarlo con una riga in functions.php:

1
add_filter( 'widget_text', 'do_shortcode' );

Per evitare l'inserimento automatico dei tag <p> e <br> intorno allo shortcode in un widget (WordPress formatta automaticamente le interruzioni di riga), aggiungi anche:

1
add_filter( 'widget_text', 'shortcode_unautop' );

Lo stesso principio vale per i template PHP. Se devi eseguire uno shortcode direttamente in header.php o in un altro file del tema, racchiudilo in do_shortcode():

1
echo do_shortcode( '[techblog]' );

In questo modo la stessa logica è disponibile nell'editor, nel widget e nel template, senza duplicare codice.

Come mostrare il testo di uno shortcode senza eseguirlo

A volte serve non eseguire uno shortcode ma mostrarne la sintassi al lettore, come in questo articolo. Se inserisci semplicemente [gallery] nell’editor, WordPress lo esegue subito o mostra un segnaposto. Ci sono due modi per evitarlo.

Doppie parentesi quadre. Il metodo più semplice: raddoppia le parentesi esterne:

1
[[gallery]]

Per i tag accoppiati, si raddoppiano la prima parentesi di apertura e l’ultima di chiusura:

1
[[maps]New York, USA[/maps]]

Codici carattere HTML. Nell’editor di testo puoi sostituire le parentesi con i rispettivi codici ASCII: [ al posto di [ e ] al posto di ]. La stringa [gallery] verrà visualizzata come testo [gallery], ma non sarà eseguita.

Il primo metodo è più semplice e leggibile nel codice sorgente, il secondo è più affidabile in presenza di formattazione complessa. Scegli le doppie parentesi per modifiche rapide nell’editor di testo e i codici ASCII quando lo shortcode è vicino ad altre parentesi quadre, per esempio dentro blocchi di codice o descrizioni di meta-campi. In entrambi i casi i visitatori del sito vedono esattamente il testo dello shortcode e WordPress non lo esegue.

Video: guida completa agli shortcode di WordPress

Per chi preferisce una spiegazione visiva, ecco un tutorial dettagliato del team Kinsta. L’autore mostra la creazione, il debug ed esempi reali di shortcode in un progetto live, dall’installazione del tema all’output nel frontend.

⁉️🤔 Domande frequenti

Si possono usare gli shortcode in Gutenberg?

Sì, tramite il blocco "Shortcode" nel pannello di inserimento blocchi. Inserisci lo shortcode nel campo del blocco e WordPress lo esegue in fase di rendering. Tuttavia, shortcode complessi con contenuto annidato possono comportarsi in modo imprevedibile; in questi casi è più affidabile passare alla modalità di modifica codice. Gutenberg esegue il rendering degli shortcode via callback lato server, quindi il risultato dipende dal fatto che la funzione restituisca HTML corretto. I temi a blocchi (Full Site Editing) con theme.json possono limitare parzialmente l’output degli shortcode nei template: verifica la compatibilità del tema specifico.

Cosa fare se uno shortcode non funziona?

Verifica tre cause tipiche. Prima: hai inserito lo shortcode nell’editor visuale, che ha convertito le parentesi in entità HTML; passa alla modalità testo e assicurati che le parentesi siano dritte. Seconda: il plugin che registra lo shortcode è disattivato; vai su "Plugin" e controlla lo stato. Terza: la funzione dello shortcode usa echo invece di return; è un errore di sviluppo, l’output compare in un punto sbagliato della pagina. Metodo diagnostico sistematico: apri wp-config.php, attiva WP_DEBUG e WP_DEBUG_LOG. Dopo aver caricato la pagina con lo shortcode, controlla wp-content/debug.log: troverai errori PHP specifici con indicazione di file e riga.

Si può inserire codice PHP direttamente in uno shortcode?

No. Uno shortcode è un trigger, non un contenitore per codice arbitrario. A essere eseguita è la funzione registrata lato server tramite add_shortcode(). Se ti serve una logica personalizzata, scrivila in functions.php (o in un plugin separato) e collegala allo shortcode. Tra le parentesi quadre puoi passare solo contenuti e attributi, non codice eseguibile. Per un’esecuzione sicura di PHP nei contenuti, valuta plugin come "Code Snippets": permettono di gestire snippet dall’interfaccia di amministrazione senza modificare functions.php e con protezione contro gli errori fatali.

Gli shortcode rallentano il sito?

Di per sé, no. add_shortcode() si limita a registrare la corrispondenza tra tag e funzione nell’array globale $shortcode_tags. Il sovraccarico nasce quando la funzione dello shortcode esegue query pesanti sul database o chiamate ad API esterne a ogni caricamento pagina. Il problema non è nel meccanismo degli shortcode, ma nell’implementazione specifica del plugin. Regola pratica: se una pagina contiene più di 20 shortcode, ciascuno dei quali richiama WP_Query o wp_remote_get(), memorizza i risultati nella cache tramite Transients API. Per scenari tipici (uno o due shortcode per pagina), l’impatto sulle prestazioni è trascurabile.

Come rimuovere uno shortcode dall’output senza cancellarlo dall’articolo?

Usa remove_shortcode() in functions.php. Per esempio, per disabilitare la galleria nativa: remove_shortcode( 'gallery' ). Dopo questa modifica, [gallery] nel testo dell’articolo verrà mostrato come normale testo tra parentesi quadre, senza essere eseguito. È utile quando si migra a un’altra soluzione o si fa debug di conflitti. Disabilitazione parziale: puoi sovrascrivere uno shortcode registrando un tuo gestore con lo stesso tag tramite add_shortcode(). L’ultimo gestore registrato ha la priorità.

Vale la pena imparare gli shortcode nel 2026

Gutenberg e l’editor a blocchi hanno coperto molti compiti per cui un tempo si scrivevano shortcode: colonne, pulsanti, inserimento media, wrapper. Ma gli shortcode non sono spariti. I plugin continuano a registrarne a centinaia, dai form di iscrizione al carrello di WooCommerce. E, cosa più importante, uno shortcode personalizzato può sostituire un plugin e fare esattamente ciò che serve al tuo progetto, senza appesantire l’amministrazione con impostazioni altrui.

Se ripeti regolarmente lo stesso blocco HTML, link o template negli articoli, dedica 10 minuti a add_shortcode() in functions.php. Il ritorno sull’investimento: decine di ore all’anno che non spendi in copia e incolla. Gli shortcode sono retrocompatibili: il codice scritto oggi funzionerà nelle future versioni di WordPress, perché l’API degli shortcode non è cambiata dalla sua introduzione e resta uno degli elementi core più stabili.