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

Nel 2008, il team di sviluppo di WordPress ha in­tro­dot­to i co­sid­det­ti shortcode: una funzione che ti permette di ag­giun­ge­re fa­cil­men­te elementi dinamici ai tuoi contenuti. Anche se dalla versione 5.0 il CMS utilizza l’editor a blocchi Gutenberg, che offre molte fun­zio­na­li­tà un tempo di­spo­ni­bi­li solo tramite shortcode, questi ultimi restano comunque una parte fon­da­men­ta­le 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 ri­fe­ri­men­to nel file functions.php. Se le pagine vengono aperte con uno shortcode, WordPress è re­spon­sa­bi­le per l’ese­cu­zio­ne e l’in­ter­pre­ta­zio­ne del ri­spet­ti­vo script. Il vi­si­ta­to­re o la vi­si­ta­tri­ce cerca così, al posto del codice, il contenuto generato tramite la funzione PHP. Uno shortcode ricopre quindi la funzione di se­gna­po­sto, 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’im­ple­men­ta­zio­ne di uno shortcode su WordPress non presenta grosse dif­fi­col­tà, perché basta inserirlo di­ret­ta­men­te 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 pub­bli­ca­ti re­cen­te­men­te. Inoltre, si possono spe­ci­fi­ca­re anche altri parametri ag­giun­ti­vi.

Anche se gli shortcode fun­zio­na­no ancora, WordPress offre oggi con l’editor a blocchi un modo più intuitivo per ag­giun­ge­re funzioni simili di­ret­ta­men­te tramite blocchi. Molti degli shortcode classici sono stati so­sti­tui­ti dai blocchi di Gutenberg, così puoi inserire contenuti dinamici in modo ancora più semplice, senza dover scrivere codice. Se però non vuoi ri­nun­cia­re agli shortcode, WordPress mette a tua di­spo­si­zio­ne il blocco shortcode, che ti permette di inserirli di­ret­ta­men­te nell’editor a blocchi.

Perché gli shortcode di WordPress sono così utili?

Con l’in­tro­du­zio­ne dell’editor a blocchi, il modo in cui si usano gli shortcode è cambiato. Molte funzioni che prima ri­chie­de­va­no uno shortcode sono state so­sti­tui­te da blocchi, così ora puoi ag­giun­ge­re contenuti di­ret­ta­men­te con la funzione drag and drop, senza dover scrivere un codice. Tuttavia, gli shortcode restano utili, so­prat­tut­to per i plugin spe­cia­liz­za­ti o per funzioni per­so­na­liz­za­te che non hanno ancora un’al­ter­na­ti­va nell’editor a blocchi.

Gli shortcode sono par­ti­co­lar­men­te pratici nelle in­stal­la­zio­ni WordPress già esistenti, perché ga­ran­ti­sco­no la com­pa­ti­bi­li­tà con i temi e i plugin più datati, che spesso si basano ancora sugli shortcode e non sono stati com­ple­ta­men­te adattati ai blocchi. Inoltre, gli shortcode sono adatti ai contenuti dinamici e alle funzioni complesse. Risultano utili anche se vorresti svi­lup­pa­re delle fun­zio­na­li­tà per­so­na­liz­za­te: infatti, ti per­met­to­no di integrare funzioni spe­ci­fi­che senza dover in­ter­ve­ni­re di­ret­ta­men­te sul codice del tema.

Anche se WordPress punta sempre più sui blocchi, gli shortcode restano una risorsa preziosa, so­prat­tut­to per chi ha già una certa espe­rien­za o per casi d’uso par­ti­co­la­ri.

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 pre­de­fi­ni­ti. Tuttavia, in questa sede eviteremo di ad­den­trar­ci nella pro­gram­ma­zio­ne di uno script simile perché si finirebbe per scrivere un corso base di pro­gram­ma­zio­ne PHP.

Nei paragrafi suc­ces­si­vi imparerai, invece, come integrare e di­sat­ti­va­re gli shortcode su WordPress per poter uti­liz­za­re il tuo progetto. Inserisci il ri­spet­ti­vo codice PHP nel file functions.php, contenuto nella directory del tema uti­liz­za­to, o in un file PHP separato, che in­te­gre­rai op­por­tu­na­men­te nel codice. Per as­si­cu­rar­ti che gli shortcode non spa­ri­sca­no con il prossimo ag­gior­na­men­to del tema, devi creare un tema child. Per riuscirci bastano pochi passaggi, come indicato nelle nostre istru­zio­ni “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 ri­chia­ma­ta in par­ti­co­la­ri con­di­zio­ni con parametri definiti. La seguente funzione di esempio ricerca nel database e genera per lo shortcode [post-recenti] un link all’ultimo post pub­bli­ca­to:

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 so­sti­tui­re lo shortcode, si trova nella variabile $return_string (in PHP tutte le variabili sono con­tras­se­gna­te con $). La funzione PHP (post_recenti_function) risponde a questa variabile con l’istru­zio­ne return. Se, invece, utilizzi er­ro­nea­men­te il comando echo, l’elemento im­ple­men­ta­to tramite shortcode finisce im­prov­vi­sa­men­te prima del contenuto vero e proprio.

Rilevare gli shortcode su WordPress

È in­di­spen­sa­bi­le far capire a WordPress che la funzione creata cor­ri­spon­de a uno shortcode, che deve essere eseguito au­to­ma­ti­ca­men­te, se la pagina ri­chia­ma­ta 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, è im­por­tan­te che scegli un nome univoco che compaia una sola volta.

Definire con i parametri gli shortcode per una maggiore fun­zio­na­li­tà

Per conferire una fles­si­bi­li­tà ag­giun­ti­va al tuo shortcode di WordPress, hai la pos­si­bi­li­tà di ag­giun­ge­re parametri opzionali. Nell’esempio uti­liz­za­to finora si presenta la pos­si­bi­li­tà di segnalare nello shortcode esat­ta­men­te 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 au­to­ma­ti­ca­men­te 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 spe­ci­fi­chi lo shortcode nel testo, per esempio in questo modo [post-recenti post="5"], non compare solo l’ultimo articolo pub­bli­ca­to, ma una lista dei cinque articoli più recenti.

Uti­liz­za­re contenuti precisi come parametri degli shortcode

Puoi mo­di­fi­ca­re ancora l’esempio pre­sen­ta­to e ag­giun­ge­re 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 de­si­de­ra­to 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]

Uti­liz­za­re uno shortcode di WordPress in un widget

In passato, gli shortcode dovevano essere attivati ma­nual­men­te per i widget. Tuttavia, da WordPress 5.8, molti contenuti possono essere aggiunti di­ret­ta­men­te nei widget tramite l’editor a blocchi, riducendo così la necessità di usare gli shortcode in molti casi, come già men­zio­na­to. Se desideri con­ti­nua­re a usare uno shortcode, puoi sem­pli­ce­men­te inserirlo in un blocco “Shortcode” all’interno di un widget.

Di­sat­ti­va­re gli shortcode non più necessari

Se un preciso shortcode non ti serve più, hai due pos­si­bi­li­tà per di­sat­ti­var­lo: 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 ri­co­no­sce­reb­be lo shortcode come tale e lo farebbe vi­sua­liz­za­re come testo in chiaro nel bel mezzo dell’articolo. Visto che questo metodo comporta spesso un grande impegno, se uno shortcode viene uti­liz­za­to spesso, si può ricorrere per casi di questo tipo a una seconda pos­si­bi­li­tà: al posto di eliminare il codice e la funzione PHP, si amplia la funzione di callback tramite un’istru­zio­ne 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 mol­te­pli­ci pos­si­bi­li­tà offerte da questa tecnica.

Inserire il pulsante per i link

Per ag­giun­ge­re un pulsante per i link al tuo progetto con una scritta per­so­na­liz­za­ta, 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 de­si­de­ra­ta del pulsante sem­pli­ce­men­te 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 vi­sua­liz­za­re 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 uti­liz­za­re questo shortcode, inserisci sem­pli­ce­men­te come parametro il nome del menu cor­ri­spon­den­te, 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 ap­pro­pria­to 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 prin­ci­pa­li, 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é im­ple­men­ta­re ma­nual­men­te modelli già pronti nel file functions.php e nel cor­ri­spet­ti­vo file PHP, c’è ancora un’altra pos­si­bi­li­tà per attivare i comandi utili per il proprio progetto web: sul sito ufficiale di WordPress trovi un’ampia scelta di plugin che ag­giun­go­no alla tua in­stal­la­zio­ne di WordPress sia shortcode singoli che altri diversi. Alcuni esempi che vale la pena di citare sono:

• Short­co­der: in un editor visuale generi il tuo shortcode e lo inserisci fa­cil­men­te negli snippet HTML e Ja­va­Script.
• Short­co­des Ultimate: questo plugin include oltre 50 shortcode pre­de­fi­ni­ti utili e supporta l’editor a blocchi.