Questo articolo è un'introduzione alle API degli shortcode di WordPress. Gli shortcode sono una delle funzionalità più utilizzate in WordPress.
Uno shortcode in WordPress (nella forma [shortcode]) non è altro che una macro con cui possiamo inserire nei post e nelle pagine dei frammenti di codice HTML.
WordPress individua lo shortcode nel contenuto e lo espande utilizzando la funzione associata al suo nome tramite la funzione core add_shortcode().
Gli shortcode sono in genere creati da temi o plugin. Quando rimuovete un tema o un plugin che ha generato lo shortcode, lo shortcode viene mostrato non espanso nella sua forma letterale, ossia come [shortcode]. Infatti gli shortcode vengono sempre salvati in modo letterale nel database. Solo l'engine di WordPress può espanderli.
Nella sua forma più semplice la registrazione di uno shortcode è come segue:
function my_shortcode() {
$html = '<p>Test.</p>';
return $html;
}
add_shortcode( 'test', 'my_shortcode' );
Inserendo questo codice nel file functions.php o in un plugin creerete lo shortcode [test] che restituirà la stringa HTML specificata.
La cosa fondamentale da capire nel funzionamento degli shortcode è che non dovete mai usare l'operatore echo ma sempre restituire l'output tramite return.
Se volete forzare l'esecuzione di uno shortcode nel vostro tema, ossia al di fuori del contenuto dei post o delle pagine, potete usare la funzione do_shortcode():
do_shortcode( 'test' );
Solitamente gli shortcode non sono abilitati nei widget. Potete comunque abilitarli utilizzando il filtro widget_text:
add_filter( 'widget_text', 'do_shortcode' );
Abbiamo sinora visto gli shortcode nella loro forma essenziale, ma gli shortcode possono accettare attributi e contenuto.
Gli attributi, nella forma [shortcode attributo="valore"], servono ad inserire delle variabili impostate dall'utente per modificare il comportamento dello shortcode.
Vengono definiti in questo modo:
function my_shortcode( $atts ) {
extract( shortcode_atts( array(
'foo' => '',
'bar' => ''
), $atts ) );
$html = '<p class="' . $foo . '" title="' . $bar . '">Test</p>';
return $html;
}
add_shortcode( 'test', 'my_shortcode' );
'foo' e 'bar' sono i nomi dei nostri attributi che vengono estratti come variabili, ossia come $foo e
$bar. Quello che facciamo usando l'array associativo è semplicemente dichiarare dei valori predefiniti nel caso in cui l'utente non ne specifichi nessuno.
Ma gli shortcode possono accettare anche del contenuto, nel qual caso vengono scritti usando una notazione simile ai tag HTML, ossia:
[test]Contenuto[/test]
Data la sintassi peculiare usata da WordPress, che si basa sull'ordine degli argomenti delle funzioni PHP, uno shortcode con contenuto viene definito in questo modo:
function my_shortcode( $atts, $content = null ) {
$html = '<p>' . $content . '</p>';
return $html;
}
add_shortcode( 'test', 'my_shortcode' );
Per una panoramica completa sulle API degli shortcode, consultate la documentazione ufficiale di WordPress.