Questo tutorial spiega in maniera semplice come creare e gestire un proprio Shortcode in Wordpress.

Siccome ho notato che c’e’ molta confusione sulla gestione e la creazione di Shortcode in Stackoverflow e in generale su internet ho deciso di fare questa guida per spiegare in modo semplice come creare e gestiore un Shortcode in Wordpree e a che cosa serve. Prima di tutto …

Cos’e’ uno Shortcode in WordPress e a cosa serve?

Gli Shortcode in WordPress (come dice la parola stessa) sono delle scorciatoie che ci aiutano ad aggiungere contenuto dinamico nei post, nelle pagine e nei widget della barra laterale di WordPress. Sono visualizzati all’interno di parentesi quadre in questo modo:

[ilmioshortcode]

Per comprendere meglio gli shortcode, diamo uno sguardo al motivo per cui sono stati aggiunti in primo luogo. Di regola, WordPress filtra tutto il contenuto per assicurarsi che nessuno utilizzi i post e il contenuto della pagina per inserire codice dannoso nel database. Ciò significa che puoi scrivere HTML di base nei tuoi post, ma non puoi scrivere codice PHP nei post stessi. I post e le pagine di WordPress sono sostanzialmente delle contenuti statici che non vengono compilati dal server.

Fondamentalmente uno Shortcode, consente agli sviluppatori di aggiungere il loro codice PHP all’interno di una funzione e quindi registrare quella funzione con WordPress come shortcode, in modo che gli utenti possano usarlo facilmente all’interno di un post o una pagina senza avere alcuna conoscenza di programmazione. Quindi per la natura dello stesso, lo Shortcode DEVE SEMPRE restituire una stringa che contiene codice HTML. Tieni questo in mente quando la funzione che gestisce il tuo Shortcode generera’ un Fatal Error in PHP.

Quando WordPress trova lo shortcode, eseguirà automaticamente il codice ad esso associato.

Come create uno Shortcode in PHP per WordPress.

Creare un nuovo Shortcode in WordPress e’ molto facile, tutto quello che dobbiamo fare e’ creare una funzione PHP che restituisca codice HTML. Per provarlo vi consiglio di aprire il file functions.php del vostro tema WordPress e aggiungere il codice PHP sottostante alla fine del file.

Questa semplice restituisce al chiamante la nota frase ‘Hello World!‘ avvolta dai tags HTML <h1>.

Quello che dobbiamo fare ora e’ connettere la nostra funzione ad uno Shortcode, per fare questo usiamo la funzione add_shortcode() del framework di WordPress, il primo parametro della funzione e’ il nome dello Shortcode e il secondo parametro e la funzione ad esso associata. Bisogna stare attenti per garantire che il shortcode aggiunto sia unico e non sia in conflitto con altri tag shortcode già aggiunti. In caso di Shortcode duplicato, avrà la precedenza lo Shortcode caricato per ultimo.
La sintassi della funzione e’ add_shortcode( string $tag, callable $callback ) e per maggiori informazioni vi invito a leggere la documentazione ufficiale nel sito di WordPress in questo link. Ecco come usare la funzione add_shortcode() nel nostro esempio:

Aggiungi il codice sopra alla fine del vostro file functions.php.

Se invece state creando un plugin, vi consiglio di inizializzare lo Shortcode solo dopo che WordPress si è caricato completamente. Potete assicurarvi di questo avvolgendo la funzione add_shortcode() all’interno di un’altra funzione come il codice qua sotto. La funzione add_action() aggancia la funzione shortcodes_init per eseguirsi solo dopo che WordPress ha terminato il caricamento Questa si chiama funzione wrapper:

Come passare parametri all’interno del nostro Shortcode.

In WordPress e’ possibile usare varibili e passare parametri all’interno del nostro Shortcode, per fare cio’ dobbiamo modificare la funzione il_mio_shortcode e aggiungere la possibilita di passare parametri attraverso un array $atts che conterra’ tutti i parametri che abbiamo bisogno di passare, il codice della funzione dovra’ selezionare gli elementi del array $atts  che sono necessari per il nostro Shortcode. Ecco un esempio qua sotto:

Questo Shortcode come definito sopra visualizzara’ a schermo la stringa ‘Hello WebMarcello!‘ avvolta dai tags HTML <h1> quando passiamo come parametro il nome ‘WebMarcello’, ma questo e’ ovviamente a vostra discrezione. Vedremo nel paragrafo successivo come usare gli Shortcode e come passare parametri.

Come usare uno Shortcode in post, pagine e all’interno di codice PHP in WordPress.

Nel primo esempio citato sopra, quello senza parametri, per usare lo Shortcode dichiarato come ‘salutidobbiamo solo scrivere il nome dello Shortcode tra parentesi quadre all’interno del nostro post:
[saluti]
.
Questo stampera’ a schermo la stringa HTML <h1>Hello world!</h1> cosi’ come l’abbiamo dichiarata.
WordPress da la possibilita’ di usare Shortcode all’interno di post, pagine, widget e anche all’interno di codice PHP usando la funzione do_shortcode() la cui sintassi e’ do_shortcode( string $content, bool $ignore_html = false ), ecco come usarlo in caso di Shortcode senza parametri:

Nel secondo caso sopra, nella funzione con paramentri, dobbiamo definire tra le parentesi quadre il nome della variabile che stiamo passando alla funzione il_mio_shortcode e il suo valore. Se fate attenzione al corpo della funzione noterete che la stessa si aspetta che voi passate una variabile chiamata ‘nome‘.
Ecco come usarlo: [saluti nome=WebMarcello] .
In questo caso lo Shortcode stampera’ a schermo <h1>Hello WebMarcello!</h1>, nel caso di [saluti nome=Mario] stampera’ <h1>Hello Mario!</h1> ecc..

In caso dobbibamo usare uno Shortcode con parametri all’interno del codice PHP: