A chiunque abbia gestito un sito basato su WordPress, sarà capitato di inserire in un post una galleria di immagini. Ogni volta che si esegue questa operazione WordPress inserisce nel contenuto testuale del post/pagina un tag, shortcode, costituito da un nome e da uno o più attributi.
In sintesi, gli shortcode non sono altro che blocchi di codice inseriti all'interno dei contenuti per generare dinamicamente markup. Nel caso delle immagini e dei file media, WordPress permette di inserire gli shortcode grazie all'interfaccia dell'uploader e non sarà necessario inserire manualmente i tag.
Gli shortcode possono disporre di attributi che ne specifichino il comportamento. Gli attributi dello shortcode [gallery], ad esempio, permettono di impostare le immagini da inserire (o meno) nella galleria (attributo id, include ed exclude), l'ordine di visualizzazione (order e orderby) o il tipo di collegamento ipertestuale associato ad ogni immagine (link).
WordPress ammette due tipi di shortcode. Il primo viene individuato da semplici parentesi quadre, come nel caso delle gallerie di immagini:
[gallery ids="44,34"]Il secondo tipo prevede un tag di apertura ed uno di chiusura:
[myshortcode]Content[/myshortcode]Ma WordPress offre la possibilità agli sviluppatori di andare oltre gli shortcode predefiniti, grazie alla Shortcode API, che offre un set di funzioni che permettono di aggiungere shortcode personalizzati ai propri temi e plugin.
Vediamo come aggiungere i due diversi tipi di shortcode all'interno del file functions.php del tema.
Aggiungere shortcode ad un tema
Per aggiungere valore ad un tema, quindi, lo si può arricchire con funzioni specifiche, che eseguono determinate operazioni, e restituiscono markup e informazioni testuali che possono essere inserite all'interno dei contenuti del sito. Per entrambi i tipi di shortocode descritti l'attivazione avviene tramite la funzione add_shortcode:
<?php add_shortcode( $tag , $func ); ?>Questa funzione aggancia un nuovo shortcode ad una funzione che viene eseguita nel momento in cui WordPress carica lo shortcode. La funzione accetta due argomenti:
| Argomento | Tipo | Descrizione |
|---|---|---|
$tag |
string | il nome dell'etichetta (o tag) dello shortcode |
$func |
callable | il nome della funzione da eseguire |
La funzione di callback genera il markup da inserire all'interno dei contenuti del sito, e accetta uno o due argomenti, a seconda del tipo di shortocode che si sta progettando. Quello che segue è un esempio relativo al primo tipo di shortcode.
[myshortcode foo="val1" bar="val2"]Questo viene definito come segue:
add_shortcode( 'myshortcode', 'my_shortcode_callback' );
function my_shortcode_callback( $atts ){
$atts = shortcode_atts( array(
// list of all available attributes and their defaults
'foo' => 'value',
'bar' => 'value'
), $atts, 'myshortcode' );
// your code here
return $output;
}add_shortcode aggancia lo shortcode alla funzione di callback, la quale accetta come argomento un array di attributi resi disponibili dalla funzione shortcode_atts. Quest'ultima accetta tre argomenti: il primo è un array i cui elementi sono costituiti da tutti gli attributi disponibili e dai loro valori predefiniti; il secondo argomento è costituito dall'array degli attributi impostati dall'utente con lo shortcode; l'ultimo argomento è l'etichetta dello shortcode, che può essere utilizzata dal filtro shortcode_atts_{$myshortcode}.
Ci può essere un solo hook per ogni shortcode: ciò significa che non è possibile duplicare i nomi degli shortcode all'interno della stessa istallazione.
Il secondo tipo di shortcode prevede l'utilizzo di un tag di apertura e uno di chiusura:
[myshortcode foo="val1" bar="val2"]Content here[/myshortcode]In questo secondo caso la funzione di callback accetterà un argomento in più:
add_shortcode( 'myshortcode', 'my_shortcode_callback' );
function my_shortcode_callback( $atts, $content = '' ){
// your code here
return $content;
}Si tenga presente che la funzione di callback dovrà sempre restituire il codice HTML che andrà a sostituire lo shortcode dove questo è stato inserito.
Uno shortcode per inserire i dati dell'utente
Si proporrà uno shortcode che permetterà di inserire all'interno di una pagina o di un post dati specifici relativi all'account dell'utente collegato, come l'email o il nome scelto per la visualizzazione nel front-end. Per prima cosa, invochiamo la funzione add_shortcode agganciandola all'hook init:
function custom_init() {
add_shortcode( 'seventyone_user_info', 'seventyone_user_info' );
}
add_action('init', 'custom_init');Quella che segue è la funzione di callback che produce il markup:
function seventyone_user_info( $atts ){
$atts = shortcode_atts( array(
// list of all available attributes and their defaults
'attribute' => 'display_name'
), $atts, 'seventyone_user_info' );
if ( is_user_logged_in() ) {
// get the current user
$cu = wp_get_current_user();
$attribute = sanitize_html_class( $atts['attribute'] );
return $cu->$attribute;
}else{
return '';
}
}La funzione verifica che l'utente abbia effettuato il login. In caso positivo, wp_get_current_user() rende disponibile l'oggetto WP_User, le cui proprietà danno accesso a tutti i dati relativi all'utente registrato. Ora per visualizzare l'email dell'utente corrente basterà inserire all'interno di un post o di una pagina il seguente shortcode:
[seventyone_login_form attribute="user_email"]Il valore dell'attributo dovrà essere una delle proprietà dell'oggetto WP_User. Come ultimo esempio, si inserisca il seguente markup nell'editor di testo:
<ul>
<li>Default: [seventyone_user_info]</li>
<li>Login: [seventyone_login_form attribute="user_login"]</li>
<li>Email: [seventyone_login_form attribute="user_email"]</li>
<li>First name: [seventyone_login_form attribute="user_firstname"]</li>
<li>Last name: [seventyone_login_form attribute="user_lastname"]</li>
<li>Display name: [seventyone_login_form attribute="display_name"]</li>
<li>User ID: [seventyone_login_form attribute="ID"]</li>
</ul>Il risultato sarà una lista con tutti i dati dell'utente.
