The Beginner’s Guide to Writing Your Own Custom Shortcode

I codici brevi sono una caratteristica popolare inclusa in molti plugin e temi. Tuttavia, se non avete mai costruito i vostri shortcodes prima, potreste non avere idea di come aggiungerli ai vostri progetti WordPress.

Fortunatamente, la Shortcode API di WordPress rende abbastanza semplice creare i vostri shortcodes. In questo modo gli utenti potranno sfruttare le caratteristiche del vostro plugin o tema da qualsiasi area di testo sul loro sito WordPress. Includere gli shortcodes nei vostri progetti è un modo semplice per costruire sulla funzionalità che avete già creato, in modo da ottenere il massimo per i vostri soldi.

In questo articolo, parleremo un po’ di più su come funzionano gli shortcodes. Poi, ti mostreremo come può essere semplice programmare il tuo in tre passi. Iniziamo!

Un’introduzione agli shortcode e alle Shortcode API

Le Shortcode API di WordPress sono un comodo strumento per gli sviluppatori.

Gli shortcode si presentano come piccoli pezzi di testo tra parentesi quadre, come questo: . Ognuno di essi rappresenta un’unica esecuzione di codice predefinito, che viene attivato su richiesta. Puoi usarli quasi ovunque il testo possa essere aggiunto in WordPress.

Mentre la maggior parte degli shortcodes sono aggiunti da temi e plugin, il core di WordPress ha alcuni shortcodes predefiniti che puoi usare. Alcuni esempi di questi sono audio, galleria e didascalia.

Per esempio, quando si aggiunge un’immagine con una didascalia, WordPress genera un particolare shortcode:

Quando si visualizza questo sul front-end, si vedrà un’immagine con una didascalia:

Fortunatamente, la Shortcode API rende relativamente semplice creare shortcode personalizzati per i vostri progetti WordPress. Questa è spesso un’idea intelligente perché rende la vita dei vostri utenti più facile, consentendo loro di utilizzare funzionalità complesse con pochi tasti.

Come scrivere il proprio shortcode personalizzato (in 3 semplici passi)

Ora che avete capito come funzionano gli shortcode, impariamo ad aggiungerne uno al vostro tema o plugin! Naturalmente, ciò che il tuo shortcode fa dipenderà da te. In questo esempio, useremo una semplice funzione “Hello world!” per iniziare.

Scrivere la funzione shortcode

Prima di tutto, vorrai aprire un nuovo file in un editor di testo. Poi, scrivete una funzione con un nome unico, che eseguirà il codice che vorreste che lo shortcode attivasse:

function torque_hello_world_shortcode() { return 'Hello world!';}

Se dovessimo usare questa funzione normalmente, essa restituirebbe Hello world! come una stringa che potrebbe essere emessa in HTML. Questa funzione può anche accettare parametri personalizzati. Per esempio, se volete che qualcuno sia in grado di fargli dire Hello Bob! invece, potreste aggiungere un parametro name. Questi parametri sono chiamati attributi, e sono tutti gestiti utilizzando un singolo array predefinito come $atts da WordPress.

Ecco un esempio di come utilizzare la funzione $atts dello shortcode per gestire correttamente gli attributi dello shortcode in WordPress. Potete imparare di più su come funziona per le vostre esigenze nel codex di WordPress:

function torque_hello_world_shortcode( $atts ) { $a = shortcode_atts( array( 'name' => 'world' ), $atts ); return 'Hello ' . $a . !';}

Questo attributo di default è world se non è disponibile nessun altro nome. Se viene fornito un nome, la funzione mostrerà invece quello. Ecco un esempio di come questo verrebbe eseguito con uno shortcode:

// Outputs "Hello world!" // Outputs "Hello Bob!"

Una volta che hai finito, questo può essere usato in tutte le aree di testo di un sito WordPress dove è installato il plugin o il tema che contiene questo shortcode.

Salva il file e aggiungilo al tuo progetto

Una volta che il tuo shortcode è pronto, puoi creare un nuovo file nel tuo tema o plugin personalizzato per salvare la funzione. Un nome descrittivo ti aiuterà a trovare questo file in seguito (per esempio: shortcode-function-hello-world.php).

Ora, è il momento di dire al resto del tuo progetto di questo nuovo file. Se stai lavorando con un tema, vorrai includerlo nel file functions.php. Se stai costruendo un plugin, puoi includerlo in qualsiasi file già caricato nel progetto.

Qui c’è un esempio di come potresti caricare il file in un tema usando get_stylesheet_directory(). Assicuratevi di modificare il percorso del file in modo che corrisponda alla struttura delle cartelle all’interno del vostro tema:

include( get_stylesheet_directory() . 'path/to/shortcode-function-hello-world.php' );

D’altra parte, questo è l’aspetto del caricamento del file in un plugin, usando plugin_dir_url(). Ancora una volta, modificate il percorso del vostro file in modo che corrisponda alla struttura della cartella del vostro plugin:

include( plugin_dir_url( __FILE__ ) . 'path/to/shortcode-function-hello-world.php' );

A questo punto, la vostra funzione è ora disponibile per l’uso! Non resta che registrare attivamente lo shortcode all’interno di WordPress.

Registra lo Shortcode

L’ultimo passo è registrare il tuo nuovo shortcode con le Shortcode API. Questo viene fatto con la funzione add_shortcode. Richiede due argomenti:

  1. Il tag shortcode da utilizzare nell’editor di testo
  2. Il nome della funzione che gestisce l’esecuzione dello shortcode

Sotto la vostra funzione shortcode, includete questa linea di codice e aggiornatela per farle corrispondere ai vostri valori:

add_shortcode( 'helloworld', 'torque_hello_world_shortcode' );

Il primo valore andrà tra parentesi quadre nell’editor di testo. Il secondo corrisponderà al nome della funzione che avete scritto nei due passi precedenti. Entrambi dovrebbero essere abbastanza unici da non interferire con altri codici brevi inclusi dal core di WordPress, dai temi o dai plugin.

Una volta che hai finito, tutto ciò che resta è testarlo. Accedi all’amministrazione di WordPress e prova ad aggiungere il tuo shortcode a un post:

È tutto qui! Il tuo shortcode può essere complicato o semplice quanto vuoi – quello che decidi di costruire usando questo potere dipende da te! Per situazioni avanzate in cui vorresti modificare l’output per diverse situazioni, potrebbe valere la pena scrivere una classe PHP unica per gestire il tuo nuovo shortcode.

Conclusione

Aggiungere funzionalità complesse ai post e alle pagine di WordPress è facile con gli shortcode. Sono semplici da programmare e aggiungono valore al vostro progetto esistente rendendo dinamici i contenuti semplici.

In questo articolo, avete imparato che ci vogliono solo tre semplici passi per creare uno shortcode:

  1. Scrivere una funzione regolare che esegua il codice personalizzato desiderato.
  2. Salvare il codice nel vostro plugin o tema WordPress.
  3. Registrare lo shortcode in WordPress.

Lascia un commento