Gli shortcode di WordPress: come inserire elementi dinamici al tuo progetto

Nel 2008, il team di sviluppo di WordPress ha introdotto i cosiddetti shortcode: una funzione che ti permette di aggiungere facilmente elementi dinamici ai tuoi contenuti. Anche se dalla versione 5.0 il CMS utilizza l’editor a blocchi Gutenberg, che offre molte funzionalità un tempo disponibili solo tramite shortcode, questi ultimi restano comunque una parte fondamentale per molti plugin e temi.

Che cosa sono gli shortcode?

Gli shortcode, che sono stati aggiunti a WordPress a partire dalla versione 2.5, sono dei comandi brevi, che possono essere inseriti nei testi e sono collegati a un codice PHP. Tale codice è integrato nel file functions.php o in un file .php separato a cui si fa riferimento nel file functions.php. Se le pagine vengono aperte con uno shortcode, WordPress è responsabile per l’esecuzione e l’interpretazione del rispettivo script. Il visitatore o la visitatrice cerca così, al posto del codice, il contenuto generato tramite la funzione PHP. Uno shortcode ricopre quindi la funzione di segnaposto, ad esempio per gli elementi semplici, come una parte di un testo, o anche per diversi tipi di contenuti dinamici, come finestre pop-up o una galleria di immagini.

L’implementazione di uno shortcode su WordPress non presenta grosse difficoltà, perché basta inserirlo direttamente nell’editor al punto giusto dell’articolo. Questi codici vengono posti tra parantesi quadre [], per far sì che WordPress li riconosca come tali. Così uno shortcode ha ad esempio la forma [post-recenti]. Collegato con la giusta funzione PHP, con questo codice devono essere indicati alla posizione scelta gli articoli pubblicati recentemente. Inoltre, si possono specificare anche altri parametri aggiuntivi.

Anche se gli shortcode funzionano ancora, WordPress offre oggi con l’editor a blocchi un modo più intuitivo per aggiungere funzioni simili direttamente tramite blocchi. Molti degli shortcode classici sono stati sostituiti dai blocchi di Gutenberg, così puoi inserire contenuti dinamici in modo ancora più semplice, senza dover scrivere codice. Se però non vuoi rinunciare agli shortcode, WordPress mette a tua disposizione il blocco shortcode, che ti permette di inserirli direttamente nell’editor a blocchi.

Perché gli shortcode di WordPress sono così utili?

Con l’introduzione dell’editor a blocchi, il modo in cui si usano gli shortcode è cambiato. Molte funzioni che prima richiedevano uno shortcode sono state sostituite da blocchi, così ora puoi aggiungere contenuti direttamente con la funzione drag and drop, senza dover scrivere un codice. Tuttavia, gli shortcode restano utili, soprattutto per i plugin specializzati o per funzioni personalizzate che non hanno ancora un’alternativa nell’editor a blocchi.

Gli shortcode sono particolarmente pratici nelle installazioni WordPress già esistenti, perché garantiscono la compatibilità con i temi e i plugin più datati, che spesso si basano ancora sugli shortcode e non sono stati completamente adattati ai blocchi. Inoltre, gli shortcode sono adatti ai contenuti dinamici e alle funzioni complesse. Risultano utili anche se vorresti sviluppare delle funzionalità personalizzate: infatti, ti permettono di integrare funzioni specifiche senza dover intervenire direttamente sul codice del tema.

Anche se WordPress punta sempre più sui blocchi, gli shortcode restano una risorsa preziosa, soprattutto per chi ha già una certa esperienza o per casi d’uso particolari.

Come creare shortcode su WordPress

È già chiaro che il fulcro di uno shortcode è lo script PHP, che viene eseguito non appena WordPress si imbatte in uno di questi elementi predefiniti. Tuttavia, in questa sede eviteremo di addentrarci nella programmazione di uno script simile perché si finirebbe per scrivere un corso base di programmazione PHP.

Nei paragrafi successivi imparerai, invece, come integrare e disattivare gli shortcode su WordPress per poter utilizzare il tuo progetto. Inserisci il rispettivo codice PHP nel file functions.php, contenuto nella directory del tema utilizzato, o in un file PHP separato, che integrerai opportunamente nel codice. Per assicurarti che gli shortcode non spariscano con il prossimo aggiornamento del tema, devi creare un tema child. Per riuscirci bastano pochi passaggi, come indicato nelle nostre istruzioni “Come creare un tema child su WordPress”.

Impostare una funzione di callback

La funzione PHP che viene eseguita non appena WordPress rileva uno shortcode è la funzione di callback, in italiano: funzione di richiamo. Viene passata come parametro di un’altra funzione e richiamata in particolari condizioni con parametri definiti. La seguente funzione di esempio ricerca nel database e genera per lo shortcode [post-recenti] un link all’ultimo post pubblicato:

function post_recenti_function() {
query_posts(array('orderby' => 'date', 'order' => 'DESC' , 'showposts' => 1));
if (have_posts()) :
while (have_posts()) : the_post();
$return_string = '<a href="'.get_permalink().'">'.get_the_title().'</a>';
endwhile;
endif;
wp_reset_query();
return $return_string;
}

Il testo che deve sostituire lo shortcode, si trova nella variabile $return_string (in PHP tutte le variabili sono contrassegnate con $). La funzione PHP (post_recenti_function) risponde a questa variabile con l’istruzione return. Se, invece, utilizzi erroneamente il comando echo, l’elemento implementato tramite shortcode finisce improvvisamente prima del contenuto vero e proprio.

Rilevare gli shortcode su WordPress

È indispensabile far capire a WordPress che la funzione creata corrisponde a uno shortcode, che deve essere eseguito automaticamente, se la pagina richiamata presenta il comando [post-recenti]. Per fare ciò, devi ampliare il file PHP con il seguente codice:

add_shortcode(post-recenti, post_recenti_function');

Così hai definito da una parte il nome dello shortcode [post-recenti], che utilizzi dopo anche nell’editor, e dall’altra la funzione da applicare, cioè post_recenti_function(). Per evitare che sorgano conflitti tra i diversi shortcode di WordPress, è importante che scegli un nome univoco che compaia una sola volta.

Definire con i parametri gli shortcode per una maggiore funzionalità

Per conferire una flessibilità aggiuntiva al tuo shortcode di WordPress, hai la possibilità di aggiungere parametri opzionali. Nell’esempio utilizzato finora si presenta la possibilità di segnalare nello shortcode esattamente quanti post debbano essere mostrati. A questo scopo hai bisogno di altre due funzioni: la funzione shortcode_atts(), che combina l’attributo shortcode generato dagli utenti con attributi nativi e inserisce automaticamente i valori standard necessari, e la funzione PHP extract() per estrarre gli attributi degli shortcode. Nel caso in cui il campo dell’argomento rimanga vuoto, inserisci anche il valore standard 1 ('posts' => 1):

function post_recenti_function($atts){
extract(shortcode_atts(array(
'posts' => 1,
), $atts));
$return_string = '<ul>';
query_posts(array('orderby' => 'date', 'order' => 'DESC' , 'showposts' => $posts));
if (have_posts()) :
while (have_posts()) : the_post();
$return_string .='<li><ahref="'.get_permalink().'">'.get_the_title().'</a></li>';
endwhile;
endif;
$return_string .= '</ul>';
wp_reset_query();
return $return_string;
}

Se ora specifichi lo shortcode nel testo, per esempio in questo modo [post-recenti post="5"], non compare solo l’ultimo articolo pubblicato, ma una lista dei cinque articoli più recenti.

Utilizzare contenuti precisi come parametri degli shortcode

Puoi modificare ancora l’esempio presentato e aggiungere un elemento preciso del contenuto come paragrafo. Nel nostro esempio il parametro del contenuto deve definire il titolo di un <h3>. Così ampli lo script di callback con la variabile $content e inserisci prima dell’elenco <ul> il titolo HTML <h3>:

function post_recenti_function($atts, $content = null) {
extract(shortcode_atts(array(
'posts' => 1,
), $atts));
$return_string = '<h3>'.$content.'</h3>';
$return_string .= '<ul>';
query_posts(array('orderby' => 'date', 'order' => 'DESC' , 'showposts' => $posts));
if (have_posts()) :
while (have_posts()) : the_post();
$return_string .= '<li><a href="'.get_permalink().'">'.get_the_title().'</a></li>';
endwhile;
endif;
$return_string .= '</ul>';
wp_reset_query();
return $return_string;
}

In modo analogo come con un tag HTML, incornici ora il titolo desiderato nel tuo testo con uno shortcode di apertura e uno di chiusura:

[post-recenti post ="5"]Titolo dell’elenco degli articoli più recenti[/post-recenti]

Utilizzare uno shortcode di WordPress in un widget

In passato, gli shortcode dovevano essere attivati manualmente per i widget. Tuttavia, da WordPress 5.8, molti contenuti possono essere aggiunti direttamente nei widget tramite l’editor a blocchi, riducendo così la necessità di usare gli shortcode in molti casi, come già menzionato. Se desideri continuare a usare uno shortcode, puoi semplicemente inserirlo in un blocco “Shortcode” all’interno di un widget.

Disattivare gli shortcode non più necessari

Se un preciso shortcode non ti serve più, hai due possibilità per disattivarlo: la soluzione ottimale sarebbe quella di eliminare la funzione di callback dal file PHP e tutte le voci del codice dai tuoi articoli. Se invece volessi rimuovere solo la funzione di callback, WordPress non riconoscerebbe lo shortcode come tale e lo farebbe visualizzare come testo in chiaro nel bel mezzo dell’articolo. Visto che questo metodo comporta spesso un grande impegno, se uno shortcode viene utilizzato spesso, si può ricorrere per casi di questo tipo a una seconda possibilità: al posto di eliminare il codice e la funzione PHP, si amplia la funzione di callback tramite un’istruzione return e in questo modo viene come bloccata:

add_shortcode('post-recenti', '__return_false');

Shortcode pratici per il tuo blog

Dopo che hai avuto un piccolo accenno sulla struttura degli shortcode e sai come fare in modo che vengano rilevati e integrati su WordPress, passiamo agli esempi seguenti, dove facciamo luce sulle molteplici possibilità offerte da questa tecnica.

Inserire il pulsante per i link

Per aggiungere un pulsante per i link al tuo progetto con una scritta personalizzata, basta uno shortcode con la seguente funzione di callback:

function link_button_function( $atts, $content = null ) {
return '<button type="button">'.do_shortcode($content).'</button>';
}
add_shortcode('link-button', 'link_button_function');

Ora inserisci la scritta desiderata del pulsante semplicemente tra lo shortcode di apertura e quello di chiusura:

[link-button]Clicca qui![/link-button]

Mostrare il menu di WordPress

Con il seguente codice puoi visualizzare il menu scelto del tuo progetto con WordPress in un testo:

function menu_function($atts, $content = null) {
extract(
shortcode_atts(
array( 'name' => null, ),
$atts
)
);
return wp_nav_menu(
array(
'menu' => $name,
'echo' => false
)
);
}
add_shortcode('menu', 'menu_function');

Se desideri utilizzare questo shortcode, inserisci semplicemente come parametro il nome del menu corrispondente, come nell’esempio:

[menu name="Menu principale"]

Integrare Google Maps

Con la tecnica dello shortcode si possono integrare nel tuo progetto anche le mappe di Google Maps in modo facile e veloce, senza dover adattare il codice sorgente. Il codice appropriato per il tuo file PHP sarà il seguente:

function googlemap_function($atts, $content = null) {
extract(shortcode_atts(array(
"width" => '640',
"height" => '480',
"src" => ''
), $atts));
return '<iframe width="'.$width.'" height="'.$height.'" src="'.$src.'&key=LA_TUA_CHIAVE_API"></iframe>';
}
add_shortcode("googlemap", "googlemap_function");

Questo classico shortcode è collegato ai tre parametri principali, ovvero all’altezza (height), alla lunghezza (width) e alla fonte di Google Maps (src). Perciò il codice dovrebbe apparire nel tuo editor così:

[googlemap width="640" height="480" src= https://www.google.com/maps/place/Brandenburger+Tor/@52.5158015,13.3776636,233m?hl=it]

I plugin per inserire gli shortcode di WordPress: la via più facile

Per tutti quelli che non vogliono né creare un proprio shortcode, né implementare manualmente modelli già pronti nel file functions.php e nel corrispettivo file PHP, c’è ancora un’altra possibilità per attivare i comandi utili per il proprio progetto web: sul sito ufficiale di WordPress trovi un’ampia scelta di plugin che aggiungono alla tua installazione di WordPress sia shortcode singoli che altri diversi. Alcuni esempi che vale la pena di citare sono:

• Shortcoder: in un editor visuale generi il tuo shortcode e lo inserisci facilmente negli snippet HTML e JavaScript.
• Shortcodes Ultimate: questo plugin include oltre 50 shortcode predefiniti utili e supporta l’editor a blocchi.