Cosa sono gli shortcode di WordPress
Gli shortcode sono frammenti di codice racchiusi tra parentesi quadre che WordPress interpreta ed esegue per generare contenuti dinamici all’interno di post, pagine e widget. Introdotti in WordPress 2.5, permettono agli utenti di inserire funzionalità complesse senza scrivere codice PHP.
La sintassi base è [nomeshortcode]. Gli shortcode possono accettare attributi ([nomeshortcode attr1="valore1" attr2="valore2"]) e contenuto racchiuso ([nomeshortcode]contenuto[/nomeshortcode]). WordPress li processa durante il rendering della pagina, sostituendoli con l’output generato dal codice PHP associato.
Quando usare gli shortcode
Gli shortcode sono ideali per:
- Inserire elementi dinamici in posizioni specifiche del contenuto (bottoni, griglie, call-to-action)
- Aggiungere funzionalità senza modificare i file del tema
- Creare componenti riutilizzabili in tutto il sito
- Offrire agli utenti un modo semplice per interagire con il plugin
Oggi Gutenberg ha ridotto la necessità di shortcode per molti casi d’uso, ma rimangono preziosi per plugin, funzionalità legacy e integrazioni che devono funzionare anche con l’editor classico. Inoltre, gli shortcode possono essere usati all’interno di blocchi Gutenberg, rendendoli compatibili con entrambi gli editor.
Creare il primo shortcode con add_shortcode()
Per creare uno shortcode, usa la funzione add_shortcode() che accetta due parametri: il nome dello shortcode (tag) e la funzione callback che ne genera l’output. La callback riceve tre parametri: $atts (array degli attributi), $content (contenuto racchiuso, se presente) e $tag (il nome dello shortcode).
Esempio base: uno shortcode che mostra la data corrente. La funzione restituisce la data formattata e WordPress la inserisce nel punto del contenuto in cui è stato posizionato lo shortcode. Ricorda: la callback deve sempre restituire (return) l’output, non stamparlo (echo).
Gestire gli attributi con shortcode_atts()
Gli attributi rendono gli shortcode flessibili e riutilizzabili. Usa shortcode_atts() per definire valori predefiniti e unirli con gli attributi passati dall’utente. Questa funzione garantisce che tutti gli attributi abbiano un valore e protegge da attributi non autorizzati.
Esempio: uno shortcode bottone che accetta attributi come colore, url e testo. shortcode_atts() imposta “blu” come colore predefinito, “#” come url predefinito e “Clicca qui” come testo predefinito. Se l’utente non specifica un attributo, viene usato il valore di default.
Sanitizza sempre gli attributi: usa esc_url() per URL, esc_attr() per valori da inserire in attributi HTML, intval() per numeri. Non fidarti mai dell’input dell’utente, anche se è un amministratore.
Shortcode con contenuto racchiuso
Quando lo shortcode racchiude del contenuto tra tag di apertura e chiusura, la callback riceve il contenuto come secondo parametro ($content). Questo permette di creare wrapper: elementi che avvolgono e trasformano il contenuto esistente.
Esempio: uno shortcode [highlight]testo[/highlight] che avvolge il testo in un elemento con sfondo giallo. La callback restituisce il contenuto originale racchiuso in un tag con classe CSS. Puoi combinare attributi e contenuto racchiuso: [highlight colore=”verde”]testo importante[/highlight].
Usa sempre do_shortcode() sul contenuto racchiuso se vuoi permettere shortcode annidati. Senza do_shortcode(), gli shortcode all’interno del contenuto non vengono processati.
Shortcode complessi: esempi pratici
Tabs
Uno shortcode per tabs permette di creare interfacce a schede nel contenuto. La struttura prevede uno shortcode contenitore [tabs] che racchiude più shortcode [tab titolo=”Scheda 1″]contenuto[/tab]. Il PHP genera HTML con classe JavaScript per l’interattività, includendo gli script necessari solo tramite wp_enqueue_script().
Accordion
Simile ai tabs, l’accordion usa uno shortcode contenitore [accordion] e item [accordion-item titolo=”Domanda”]risposta[/accordion-item]. Ogni item mostra un’intestazione cliccabile che rivela il contenuto. L’implementazione richiede JavaScript minimo, anche con CSS puro usando l’hack del checkbox.
Bottoni
Uno shortcode bottone versatile accetta attributi come url, colore, dimensione, icona e target. Genera un tag con classi CSS predefinite. Esempio: [bottone url=”https://esempio.com” colore=”rosso” dimensione=”grande”]Scarica ora[/bottone].
Colonne
Le colonne permettono layout a griglia nel contenuto. Struttura: [colonne] [colonna larghezza=”1/2″]testo sinistra[/colonna] [colonna larghezza=”1/2″]testo destra[/colonna] [/colonne]. La larghezza può essere espressa in frazioni (1/2, 1/3, 2/3) o percentuali. Il CSS converte le frazioni in percentuali usando calcoli semplici.
Best practice per gli shortcode
Seguire convenzioni solide previene conflitti e problemi di manutenzione:
- Prefisso unico: usa un prefisso per tutti i tuoi shortcode (es. mp_bottone, mp_tabs). Previene conflitti con altri plugin.
- Nomi descrittivi: shortcode come “mp_bottone_download” sono meglio di “mp_btn1”.
- Output pulito: la callback deve restituire HTML valido e ben formattato. Evita tag non chiusi o markup errato.
- No a eval e base64: non usare mai funzioni pericolose negli shortcode. Un attaccante potrebbe sfruttarle se riesce a modificare i post.
- Caricare script solo se necessario: usa wp_enqueue_script() e wp_enqueue_style() condizionalmente, verificando se lo shortcode è presente nel contenuto con has_shortcode().
- Non hard-codare output: usa sempre __() e _e() per stringhe di testo, così il plugin è traducibile.
Evitare l’HTML injection
La sicurezza è fondamentale negli shortcode. Utenti malintenzionati potrebbero passare attributi che iniettano codice JavaScript o HTML. Proteggiti in questi modi:
- Usa wp_kses() per filtrare l’HTML consentito nel contenuto racchiuso
- Usa esc_attr() per attributi HTML (class, style, id)
- Usa esc_url() per URL
- Limita i valori ammessi per attributi enumerativi (colore: solo “rosso”, “blu”, “verde”)
- Non usare attributi che accettano codice arbitrario
Anche se solo gli amministratori e gli editor possono modificare i post, un attacco XSS potrebbe permettere a un utente con ruolo inferiore di iniettare codice attraverso uno shortcode non protetto.
Alternative moderne: Gutenberg blocks
Con Gutenberg, i blocchi sono l’evoluzione naturale degli shortcode. Un blocco Gutenberg offre un’interfaccia visuale per la configurazione, un’anteprima in tempo reale e non richiede all’utente di ricordare sintassi testuali.
Tuttavia, gli shortcode non scompariranno. Sono ancora il modo migliore per:
- Fornire funzionalità a utenti che usano l’editor classico
- Inserire elementi in widget (testo) e campi ACF
- Integrazioni con plugin di terze parti che supportano solo shortcode
- Backward compatibility con siti esistenti che usano massicciamente shortcode
Se sviluppi un plugin nuovo, considera di supportare entrambi: un blocco Gutenberg per l’editor moderno e uno shortcode per compatibilità. Puoi persino registrare il blocco in modo che generi shortcode nel contenuto salvato.
Shortcode nelle aree widget
Di default, WordPress non processa gli shortcode nei widget di testo. Per abilitarli, aggiungi nel functions.php del tema: add_filter('widget_text', 'do_shortcode');. Con i widget blocchi di Gutenberg, gli shortcode funzionano automaticamente inserendoli in un blocco “Shortcode”.
Conclusione
Gli shortcode rimangono uno strumento potente e flessibile nell’arsenale dello sviluppatore WordPress. Nonostante l’avvento di Gutenberg, saper creare shortcode è una competenza fondamentale: permette di sviluppare plugin versatili, mantenere compatibilità con installazioni eterogenee e offrire funzionalità immediate agli utenti. Inizia con shortcode semplici e, man mano che acquisisci confidenza, passa a strutture più complesse come tabs e accordion. Il limite è solo la tua creatività.