Comprensione degli shortcode di WordPress

Se usi WordPress da un po' di tempo, probabilmente hai già utilizzato alcuni shortcode.

Gli shortcode sono piccoli frammenti utili che ti consentono di inserire una sorta di funzionalità speciale nei tuoi contenuti che altrimenti non sarebbe possibile. Ad esempio: molte gallerie di immagini e plug-in di scorrimento ti forniscono uno shortcode che puoi semplicemente inserire nei tuoi contenuti ovunque tu voglia per far apparire lì le immagini appropriate. Gli shortcode di solito assomigliano a questo:

[example shortcode]

In altre parole: gli shortcode fanno accadere qualcosa di speciale ovunque siano inseriti nel testo.
Ma non sei limitato a codici brevi predefiniti; puoi definire codici brevi personalizzati per fare quello che vuoi! Possono essere semplici, complessi o qualsiasi altra via di mezzo.

In questa serie, inizieremo con un semplice shortcode e ci faremo strada fino ad alcuni esempi più intricati (e ancora più utili!).

Nota: qui lavoreremo principalmente con PHP, in particolare nel file functions.php del tuo tema. Se non stai utilizzando un tema figlio (o un tema personalizzato/di base che può essere modificato senza timore che gli aggiornamenti sovrascrivano le tue modifiche), ti consigliamo di creare un tema figlio prima di iniziare.

Nota anche: non hai bisogno di alcuna conoscenza di PHP per leggere questo post, ma conoscere almeno le basi ti aiuterà. Il codice coinvolto qui è abbastanza semplice e abbiamo cercato di renderlo il più semplice possibile da copiare e personalizzare. Spiegheremo ogni parte del codice man mano che procediamo, ma se sei completamente nuovo al tema PHP di WordPress, tieni presente che un po' di codice errato nel tuo file functions.php può danneggiare il sito.

Un utile esempio di shortcode semplice

Diciamo che vogliamo uno shortcode che inserisca una speciale sezione di informazioni sull'autore in un post, come questo:

Invece di creare e modellare la scatola, l'immagine e il testo nell'editor visivo di WordPress, creeremo semplicemente uno shortcode per produrre l'intera cosa con un semplice frammento!

(Nota a margine: WordPress ha modi migliori di lavorare con i profili degli autori, ma ci atteniamo a questo esempio perché dimostra bene quanto sia facile utilizzare gli shortcode per inserire blocchi specifici di contenuto in una pagina.)

Passaggio 1: aggiungi lo shortcode nel file functions.php del tuo tema

Utilizzerai la funzione add_shortcode per dare un nome al tuo shortcode e dirai a WordPress cosa dovrebbe fare ogni volta che viene utilizzato lo shortcode. Aggiungi questa riga al file functions.php del tuo tema:

 [php]add_shortcode( 'author_bio', 'create_author_bio' );[/php]

Non importa dove si trovi all'interno functions.php , ma per evitare conflitti, consigliamo di inserirlo alla fine. (Se il file termina con un tag di chiusura ?>, però, dovrebbe andare subito prima, non dopo.)

Prima di andare oltre, rompiamo un po' quella riga, in modo da capire cosa sta realmente accadendo qui. I due frammenti di testo, o "argomenti", all'interno delle parentesi non sono speciali, in realtà; sono solo nomi. Esaminiamo cosa significa ciascuno:

1. Il primo argomento: in questo caso, author_bio – dice a WordPress il vero nome del tuo shortcode. Questo sarà il testo che gli utenti potranno digitare, tra parentesi, per utilizzare lo shortcode. Quindi, con questo codice come scritto, [author_bio] sarà il nostro shortcode per attivare la nostra biografia dell'autore.
   Questo testo potrebbe essere qualsiasi cosa, ma è sempre meglio cercare di essere unici. In questo modo, non correrai il rischio che il tuo nome shortcode sia in conflitto con quello di qualcun altro da un altro plugin o tema installato.
2. Il secondo argomento: in questo caso, create_author_bio – indirizza WordPress verso l'effettiva funzione PHP che dovrebbe eseguire ogni volta che viene utilizzato questo shortcode. Creeremo quella funzione nel passaggio successivo; per ora, stiamo solo facendo sapere a WordPress quale sarà il suo nome. (Anche questo nome dovrebbe essere univoco, per evitare conflitti.)

Quindi, se aiuta, potresti pensare al codice in questo modo:

 [php]add_shortcode( 'when_you_see_THIS_shortcode', 'do_THIS' );[/php]

Se sei interessato a dettagli più nitidi, dai un'occhiata alla voce del codice add_shortcode .

Passaggio 2: creare la funzione per gestire lo shortcode

Ora dobbiamo effettivamente creare la funzione che abbiamo appena nominato!

Dato che abbiamo appena detto a WordPress nell'ultimo passaggio che il nome della nostra funzione è create_author_bio, il nostro codice ora dovrebbe assomigliare a questo, una volta aggiunta la nuova funzione:

 [php]add_shortcode( 'author_bio', 'create_author_bio' ); function create_author_bio(){ //Code goes here! }[/php]

Potresti notare che questa funzione in realtà non fa ancora nulla; tutto quello che c'è dentro è un commento. Ci occuperemo di questo nel passaggio successivo. Per ora, vogliamo solo sottolineare che in realtà ci sono solo due pezzi qui: la registrazione dello shortcode e la funzione che si verifica ogni volta che viene utilizzato. WordPress PHP può sembrare intimidatorio, ma è davvero così semplice!

Nota a margine: non importa se la funzione create_author_bio viene dopo la funzione add_shortcode o prima di essa. L'ordine non è importante in questo caso.

Passaggio 3: fai in modo che la funzione faccia qualcosa

Ora non resta che fare in modo che la nostra funzione faccia quello che vogliamo!

Una funzione come questa potrebbe fare qualsiasi cosa, ma non importa cosa, alla fine dovrebbe restituire un singolo valore (come una stringa di testo o un numero). Quel valore potrebbe essere di qualsiasi lunghezza o complessità, ma qualunque cosa restituisca la funzione è ciò che apparirà ovunque venga utilizzato il nostro shortcode.

Per i nostri scopi, questo sarà solo un semplice codice HTML. Ecco il markup per aggiungere l'immagine e la biografia dell'autore all'interno di un elemento <aside> con una classe personalizzata (ma non metterlo ancora da nessuna parte; lo stiamo solo guardando come anteprima per il momento):

 [html]<aside class="author-bio-box"></span> <img src="https://upload.wikimedia.org/wikipedia/en/1/1f/Bilbo_Baggins_Tolkien_illustration.jpg"> <p>Bilbo Baggins is the author of <cite>The Hobbit</cite>, translator of various works from the elvish, and author of a number of poems and songs.</p> <p>He is the oldest Hobbit ever in Middle Earth, and spends his days in his Tol Eressea home across the sea.</p> </aside>[/html]

Alla fine, useremo quella classe author-bio-box sulla prima riga per modellare la biografia con i CSS. (Useremo una classe invece di un ID, nel caso in cui desideri aggiungere più di uno shortcode dell'autore per contenuti scritti da più autori.) Ma ricorda, questo potrebbe essere qualsiasi cosa vogliamo inserire nella pagina!

Ora, tutto ciò che dobbiamo fare è fare in modo che la funzione del nostro shortcode restituisca l'HTML sopra!

Dal momento che il file functions.php dovrebbe contenere solo... beh, funzioni PHP (e anche per ordine), abbiamo rimosso le interruzioni di riga e gli spazi tra quegli elementi HTML che abbiamo appena visto e li abbiamo inseriti in una stringa (all'interno di virgolette singole) . Ma funzionalmente, è sempre lo stesso frammento HTML che abbiamo appena visto sopra, ed ecco come dovrebbe apparire il nostro codice PHP finale:

 [html]add_shortcode( 'author_bio', 'create_author_bio' ); function create_author_bio(){ return '<aside class="author-bio-box"><img src="https://upload.wikimedia.org/wikipedia/en/1/1f/Bilbo_Baggins_Tolkien_illustration.jpg"><p>Bilbo Baggins is the author of <cite>The Hobbit</cite>, translator of various works from the elvish, and author of a number of poems and songs.</p><p>He is the oldest Hobbit ever in Middle Earth, and spends his days in his Tol Eressea home across the sea.</p></aside>'; }[/html]

Abbiamo finito con PHP! Una volta che abbiamo salvato il nostro file functions.php con il codice finale di cui sopra, qualsiasi autore può semplicemente inserire [author_bio] in qualsiasi pagina o post, e l'HTML sopra apparirà al posto dello shortcode!

Inoltre, la cosa davvero interessante è che se mai avessimo bisogno di aggiornare la nostra biografia, non avremo bisogno di modificare ogni singolo posto in cui appare! Invece, tutto ciò che dobbiamo fare è modificare il codice nel nostro file functions.php e verrà aggiornato ovunque contemporaneamente. Pulito, eh?

Tuttavia, per ottenere il massimo da questo, probabilmente vorremo aggiungere uno stile speciale alla scatola bio.

Passaggio 4: aggiungi alcuni CSS

Lo shortcode non è eccezionale senza uno stile, quindi aggiungiamolo! Potrebbe essere necessario regolare un po' alcuni dei valori, a seconda dei caratteri del proprio sito (quello nell'immagine sopra è Fanwood Text) e delle regole CSS già presenti. Oppure potresti semplicemente provare qualcosa di diverso!

Questo CSS può essere copiato nel file style.css del tuo tema (figlio) o, se stai utilizzando WordPress 4.7 o versioni successive (cosa che dovresti fare!), puoi semplicemente incollare questo CSS nella casella "CSS aggiuntivo" in Personalizza schermo:

 [css].author-bio-box { background: #d4ead9; padding: 2em; overflow: auto; font-family: Fanwood Text; font-size: 1.2em; line-height: 1.4em; } .author-bio-box img { float: left; max-width: 128px; height: auto; margin: 0 1em 0 0; } .author-bio-box > p:first-of-type:first-letter { font-size: 3.1em; line-height: 1; float: left; margin-bottom: -.2em; } .author-bio-box > p:last-of-type { margin: 0; }[/css]

Ora le cose dovrebbero andare molto meglio. Ma sentiti libero di giocare con il CSS per personalizzare la casella dell'autore e farlo sentire a casa sul tuo sito!

Consigliato: rendere la funzione "collegabile"

Questo non è specifico per gli shortcode e non è strettamente necessario affinché il codice funzioni, ma è una buona pratica e questo è un buon momento per menzionarlo.

Innanzitutto, un piccolo background su come funziona PHP :

Ricordi come abbiamo chiamato noi stessi la nostra funzione create_author_bio ? Bene, non c'è niente di speciale nel nome create_author_bio; avremmo potuto facilmente nominare la nostra funzione come volevamo (anche se è meglio se il nome della funzione ti dà almeno un piccolo suggerimento su cosa fa, motivo per cui abbiamo scelto create_author_bio ).

Ma ecco il punto: se due funzioni PHP hanno lo stesso nome, il risultato sarà un errore fatale che impedirà il caricamento del sito, poiché PHP non avrà idea di quale funzione sia quella giusta. PHP non indovina, quindi si ferma.

E non è solo del nostro codice di cui dobbiamo preoccuparci; un sito WordPress potrebbe utilizzare il codice di dozzine o forse anche centinaia di sviluppatori diversi, a seconda dei plugin e dei temi installati. Se lo stesso nome di funzione viene utilizzato due volte, tutto si guasta!

È un male e, ovviamente, vogliamo assicurarci che non accada mai.

Possiamo farlo rendendo la nostra funzione "pluggable"; in altre parole, dicendo a WordPress di non creare la nostra funzione se ne esiste già un'altra con lo stesso nome. È elegantemente semplice; racchiudiamo semplicemente il nostro codice esistente all'interno di questa semplice istruzione condizionale:

 [php]if( !function_exists( 'create_author_bio' ) ){ //Our existing PHP goes here! }[/php]

Quel condizionale se l'espressione controlla solo per essere sicuri che una funzione chiamata create_author_bio non esista già. Tutto il nostro codice PHP che abbiamo utilizzato finora può essere semplicemente spostato all'interno di tale istruzione, tra le parentesi graffe { } .

Tuttavia, è comunque meglio nominare le funzioni nel modo più univoco possibile! Rendere la nostra funzione collegabile evita solo un errore fatale. Quindi, se ci fosse un conflitto di denominazione, il nostro shortcode non funzionerebbe ancora, ma almeno il sito sarebbe ancora attivo e nient'altro verrebbe danneggiato.

Conclusione

Questo è tutto! Spero ti sia piaciuto creare uno shortcode bio dell'autore personalizzato! Se hai seguito, tutto ciò che devi fare è digitare [author_bio] ovunque in una pagina o in un post e il tuo codice apparirà!

Questo shortcode può essere facilmente adattato per inviare qualsiasi cosa a una pagina. Una gif, un blocco personalizzato di HTML e/o JavaScript, un'immagine o un video... tutto quello che vuoi!

Tuttavia, sebbene questo esempio sia utile se hai solo bisogno di generare un singolo valore statico sulla pagina da qualche parte, non è molto flessibile. Restituirà sempre esattamente la stessa cosa ogni volta e spesso abbiamo bisogno di shortcode per essere più adattabili di così.

Buone notizie: abbiamo coperto solo le basi degli shortcode e sono capaci di molto, molto di più!