🛠 Come aggiungere il tuo shortcode in WordPress: analisi di add_shortcode() [+2 esempi]

Ho creato uno snippet, l'ho aggiunto a functions.php e WordPress risponde "cheatin' uh?" Ti suona familiare? Gli shortcode, il meccanismo di estensione principale di WordPress, e add_shortcode() lo sbloccano in 15 righe di codice. Ma tra un "Hello World" e uno scenario reale si nascondono alcune insidie: return vs echo, l'ordine dei parametri della callback e i conflitti tra tag.

Gli shortcode sono comparsi in WordPress 2.5 e da allora sono diventati le fondamenta dell'ecosistema: contact form, gallerie, slider, output di campi personalizzati, tutto vive dentro le parentesi quadre. add_shortcode() non cambia da anni e puoi padroneggiarlo in mezz'ora.

Di seguito, un'analisi completa della funzione con due esempi pronti all'uso: da un anno che si aggiorna automaticamente nel footer alla lista degli utenti del sito.

💡 Panoramica rapida:

• Sintassi e parametri di add_shortcode(), tag e callback
• La regola: sempre return, mai echo
• L'hook init, perché il tuo shortcode potrebbe non funzionare senza
• Due modi per passare i dati: contenuto tra i tag e attributi
• Codice pronto all'uso: uno shortcode per l'anno automatico e una lista utenti

Come funziona add_shortcode() in WordPress

La funzione add_shortcode() è il punto di ingresso per registrare qualsiasi shortcode personalizzato. Richiede due parametri obbligatori: un tag univoco e il nome della funzione di callback che restituirà il contenuto.

Secondo la documentazione di WordPress, la callback riceve tre argomenti in un ordine fisso:

• $attributes, un array di attributi passati nello shortcode
• $content, il testo tra il tag di apertura e quello di chiusura
• $tag, il nome del tag con cui lo shortcode è registrato

Un esempio base, uno shortcode che produce "Hello World!":

1
// Shortcode callback function
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello World!';
4
}
5
// Shortcode registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Il codice va nel functions.php del tuo tema child o tramite un plugin come Code Snippets. Dopodiché, [hello-world] nell'editor dei post produrrà "Hello World!".

Perché return e non echo

Nota il return dentro la funzione di callback. Se usi echo, l'output avviene prima che WordPress costruisca il resto della pagina, "Hello World!" finisce in cima e il contenuto circostante viene spostato.

La regola è semplice: **una callback di shortcode restituisce sempre un valore tramite ****return**. Niente echo, print o output HTML diretto al di fuori di un buffer.

L'hook init è obbligatorio

Gli sviluppatori di WordPress.org raccomandano di agganciare la registrazione dello shortcode a init, senza chiamare add_shortcode() direttamente nel corpo di functions.php. Senza init, WordPress potrebbe non aver finito di inizializzare i suoi meccanismi interni e lo shortcode semplicemente non si attiverà.

Sintassi e parametri

Firma della funzione:

1
add_shortcode( string $tag, callable $callback )

$tag, il nome dello shortcode (senza parentesi). Se due plugin registrano uno shortcode con lo stesso tag, l'ultimo sovrascrive il precedente. Per evitare conflitti, aggiungi un prefisso univoco: non [gallery], ma [myplugin_gallery].

$callback, il nome della funzione che restituisce il contenuto. Puoi passare una stringa con il nome della funzione, una funzione anonima o un metodo di classe (passando un array [ $object, 'method_name' ]).

Come usare gli shortcode nell'editor

Nell'editor di WordPress, Gutenberg o Classic, uno shortcode si inserisce tra parentesi quadre. Per il nostro esempio:

[hello-world]

Anche la forma completa con il tag di chiusura funziona:

[hello-world][/hello-world]

La seconda opzione è necessaria quando si passa del contenuto tra i tag (ne parliamo più avanti).

Come chiamare uno shortcode in PHP

Nei template del tema o nei plugin, gli shortcode si eseguono tramite do_shortcode():

1
echo do_shortcode( '[hello-world]' );

La funzione prende una stringa che contiene uno shortcode e restituisce il risultato della sua esecuzione. È utile quando devi incorporare l'output di uno shortcode nella logica PHP, per esempio in header.php o dentro un loop.

Passare dati a uno shortcode: due modi

Metodo 1: contenuto tra i tag

Racchiudi i dati tra il tag di apertura e quello di chiusura:

[hello-world]from John to Mary[/hello-world]

La callback riceve la stringa from John to Mary tramite il secondo parametro $content:

1
// Callback with content substitution between tags
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello ' . $content . ' World!';
4
}
5
// Registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Risultato: "Hello from John to Mary World!".

Metodo 2: attributi

Passa i parametri direttamente nel tag di apertura:

[hello-world from="John" to="Mary"][/hello-world]

Nella funzione di callback, gli attributi sono disponibili tramite il primo parametro $attributes, un array associativo dove le chiavi corrispondono ai nomi degli attributi:

1
// Callback with reading shortcode attributes
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello from ' . $attributes['from'] . ' to ' . $attributes['to'] . '!';
4
}
5
// Registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Output: "Hello from John to Mary!". Gli attributi sono migliori per dati strutturati (prezzo, URL, ID), mentre il contenuto tra i tag è migliore per testo libero.

Nella pratica, dovresti aggiungere subito shortcode_atts() agli attributi, una funzione integrata di WordPress che unisce gli attributi passati con un array di valori predefiniti. Senza, l'accesso a $attributes['from'] genererà un Notice PHP se l'utente non ha specificato l'attributo. Con shortcode_atts(), ottieni sempre un array popolato: chiavi definite con valori di fallback e gli attributi sconosciuti vengono filtrati automaticamente.

Due shortcode pronti all'uso per WordPress

1. Anno corrente automatico

Lo shortcode [current-year] inserisce l'anno corrente da solo, senza bisogno di aggiornare la data nel footer ogni gennaio:

1
// Callback: returns current year via date('Y')
2
function current_year_shortcode_callback( $attributes, $content, $tag ) {
3
    return date( 'Y' );
4
}
5
// Registration of shortcode [current-year]
6
function current_year_shortcode() {
7
    add_shortcode( 'current-year', 'current_year_shortcode_callback' );
8
}
9
add_action( 'init', 'current_year_shortcode' );

Inserisci [current-year] nel footer o nel testo di un post e l'anno si aggiornerà automaticamente.

2. Lista utenti registrati

Lo shortcode [users-list] produce i nomi di tutti gli utenti del sito come elenco puntato. Utile in una pagina "Team" o nei report amministrativi:

1
// Callback: gets all users and generates HTML list
2
function my_custom_users_list() {
3
    $users = get_users();
4
    $list_html = '<ul>';
5
    foreach ( $users as $user ) {
6
        $list_html .= '<li>' . $user->data->display_name . '</li>';
7
    }
8
    $list_html .= '</ul>';
9
    return $list_html;
10
}
11
// Registration of shortcode [users-list]
12
function register_my_users_list_shortcode() {
13
    add_shortcode( 'users-list', 'my_custom_users_list' );
14
}
15
add_action( 'init', 'register_my_users_list_shortcode' );

get_users() senza argomenti restituisce tutti gli utenti. Per limitare la query per ruolo, passa un array: get_users( [ 'role' => 'editor' ] ). Il codice va nel functions.php del tema attivo o in un plugin personalizzato.

Video: creare shortcode in WordPress

Un breve video sull'argomento, registrare uno shortcode da zero, dalla scrittura della funzione al test nell'editor:

⁉️🤔 Domande frequenti

Cosa succede se due plugin registrano uno shortcode con lo stesso tag?

WordPress esegue quello caricato per ultimo. Il primo shortcode viene sovrascritto silenziosamente, senza errori. Ecco perché dovresti sempre usare un prefisso nei tuoi shortcode: [acme_gallery] invece di [gallery]. Questo elimina i conflitti con qualsiasi altro plugin o tema.

Gli shortcode possono essere chiamati dentro altri shortcode?

Sì. Se la callback del primo shortcode restituisce una stringa che contiene il tag del secondo shortcode, WordPress elabora automaticamente lo shortcode annidato. Ma non dimenticare do_shortcode(): se stai costruendo contenuto manualmente e contiene shortcode, passa la stringa attraverso do_shortcode() esplicitamente. Il comportamento standard di the_content lo fa da solo, ma una chiamata diretta alla callback no.

Dove dovrebbe risiedere il codice degli shortcode, nel tema o in un plugin?

Gli shortcode personalizzati portano funzionalità, non aspetto, quindi è meglio estrarli in un plugin separato. Cambiare tema non romperà il sito: gli shortcode continueranno a funzionare. Come minimo, usa un tema child se sei certo di non voler cambiare il tema padre.

Ci sono restrizioni sul nome del tag?

Il nome deve essere composto da lettere latine, cifre e trattini. Spazi, underscore e caratteri speciali non sono ammessi. La lunghezza consigliata è fino a 20 caratteri, in minuscolo. Esempio: [my-plugin-shortcode].

Come si fa il debug di uno shortcode se non produce output?

Primo passo, abilita WP_DEBUG in wp-config.php. Secondo, verifica che la callback restituisca un valore tramite return, non echo. Terzo, assicurati che l'hook init sia presente. Se non ci sono errori ma l'output è vuoto, aggiungi error_log() dentro la callback e controlla i log del server.

Cosa ricordare sugli shortcode di WordPress

Gli shortcode sono un meccanismo maturo e stabile. add_shortcode() non cambia da anni: tag, callback, hook init, return invece di echo. Ricorda queste quattro cose e qualsiasi shortcode personalizzato funzionerà al primo tentativo.

• Se devi mostrare l'anno nel footer, prendi il codice pronto [current-year].
• Se ti serve una lista utenti, [users-list] con un filtro per ruolo.
• Se scrivi il tuo shortcode da zero, usa sempre un prefisso e usa sempre init.

Come passo successivo, valuta di impacchettare uno shortcode come plugin autonomo e inviarlo alla directory di WordPress.org, è il modo migliore per separare la funzionalità dal tema e far crescere il tuo profilo di sviluppatore.