WordPress: aggiungere un pulsante all'editor per richiamare shortcode

WordPress è una piattaforma molto flessibile che permette di creare e utilizzare nuove funzionalità personalizzate. Per rendere queste funzionalità disponibili in modo semplice, senza dover ogni volta riscrivere tutto il codice necessario, è possibile utilizzare gli shortcode.

Cos'è uno shortcode?

Uno shortcode, letteralmente "codice breve", è uno speciale tag che funziona come un richiamo; una sorta di riassunto che, una volta inserito nei nostri contenuti per mezzo dell'editor, richiamerà ed eseguirà tutto il codice ad esso associato. Un esempio di semplice shortcode può essere quello in cui una stringa viene racchiusa fra parentesi quadre, come nell'esempio che segue:

[link]

Ipotizziamo ora di dover inserire spesso un link, magari lungo ed elaborato all'interno delle pagine o dei post, lo shortcode può essere complesso e la stringa che lo rappresenta può includere attributi da passare alla funzione che verrà eseguita:

[link href="http://www.miolink.com/cartella/sottocartella/sottosottocartella/documento.pdf"]link[/link]

Nell'esempio proposto, lo shortcode complesso è costituito da due blocchi racchiusi tra parentesi quadre, un attributo è l'URL del link, l'altro è il testo che lo rappresenta. Sia Il link che il testo sono accessibili e possono essere modificati a piacere.

Come si crea uno shortcode?

Per creare uno shortcode sono necessari due passaggi fondamentali. Il primo consiste nel creare una funzione contenente la porzione di codice che eseguirà una determinata azione; la funzione può essere inserita nel file functions.php o in altri file in esso inclusi. Buona abitudine è quella di attribuire alla funzione un nome che possa essere il più specifico possibile, sia per far capire immediatamente a cosa serve, sia per evitare che il nome possa andare in conflitto con altre funzioni del tema o di eventuali plugin:

<?php
			// funzione shortcode semplice
			function shortcode_mio_link_semplice() {
				echo '<a href="http://www.miolink.com/cartella/sottocartella/sottosottocartella/documento.pdf">mio link</a>';
			}
		?>

Il link, per comodità, potrebbe anche essere racchiuso all'interno del codice della funzione e questa stamperà il link predefinito. La funzione che genera lo shortcode con attributi è invece appena più articolata:

<?php
			// funzione shortcode con attributi
			function shortcode_mio_link_con_attributi($atts, $content = null) {
				extract(shortcode_atts(array(
              	'href' => 'http://www.miolink.com/cartella/sottocartella/sottosottocartella/documento.pdf'
         		), $atts));
        		return '<a href="'.$href.'">'.$content.'</a>';
			}
		?>

Essa richiama gli eventuali attributi passati allo shortcode e imposta il contenuto di default come nullo:

<?php
				shortcode_mio_link_con_attributi ($atts,$content = null);
		?>

Fatto questo estrae gli attributi con extract attraverso l'istruzione shortcode_atts e definisce l’attributo href del link che verrà stampato dallo shortcode:

<?php
			extract(shortcode_atts(array(
              	'href' => 'http://www.miolink.com/cartella/sottocartella/sottosottocartella/documento.pdf'
         		), $atts));
         ?>

Infine, passa a return il link e la marcatura insieme all'attributo definito dall'utente per l'output finale:

<?php
		return '<a href="'.$href.'">'.$content.'</a>';
		?>

Il secondo passaggio per la creazione dello shortcode sarà quello di indicarne la disponibilità a WordPress tramite add_shortcode passando due parametri: il primo è il nome che vogliamo attribuire per richiamarlo (in questo caso miolink), il secondo è il nome della funzione da eseguire:

<?php
			add_shortcode("miolink", "shortcode_mio_link_con_attributi");
		?>

Ora, inserendo lo shortcode nei nostri contenuti, potremo vedere il risultato:

[miolink] //forma semplice
		[miolink]link[/miolink] //versione con attributi

Semplificare l'inserimento di uno shortcode

Ricordare uno shortcode come "[link]" è semplice, ma cosa potrebbe succedere se dovessimo tenere a mente più shortcode, magari complessi? In questo caso la scelta migliore dovrebbe essere quella di affidare l'inserimento a un pulsante dedicato, disponibile direttamente nell'editor TinyMCE (l’editor predefinito utilizzato da WordPress). Poiché la funzione per generare lo shortcode è già stata creata, si può passare ad inizializzare il pulsante, continuando a inserire altre istruzioni nel file functions.php:

<?php add_action('init', 'pulsante_link'); // azione che inizializza il pulsante ?>

Abbiamo aggiunto la funzione pulsante_link che visualizzerà il pulsante, questa verrà richiamata insieme alla pagina del pannello di amministrazione. Definiamo ora la funzione:

<?php
			function pulsante_link() {
				if ( ! current_user_can('edit_posts') && ! current_user_can('edit_pages') ) { // controlla se l'utente ha i permessi per modificare pagine e articoli
		        return;
		        }
		    	if ( get_user_option('rich_editing') == 'true' ) { // controlla se l'utente sta utilizzando l'editor visuale
		        add_filter( 'mce_external_plugins', 'aggiungi_plugin' ); // aggiunge il plugin javascript con la funzione "aggiungi_plugin"
		        add_filter( 'mce_buttons_2', 'registra_pulsante' ); // registra il pulsante nella seconda riga dell'editor "_2" con la funzione "registra_pulsante"
		        }
			}
		?>

Aggiungiamo quindi la funzione che registra il pulsante:

<?php
			function registra_pulsante( $buttons ) { // registrazione del pulsante
				array_push( $buttons, "|", "miolink" ); // indicazione del nome dello shortcode associato al pulsante
				return $buttons;
			}
		?>

Fatto questo, aggiungiamo la funzione che registra il plugin javascript del pulsante in TinyMCE. Nella funzione chiamiamo un file javascript che si trova nella cartella del tema dedicata agli script, normalmente la cartella js. Chiaramente è possibile cambiare il percorso, l'importante è che la funzione trovi il file javascript perché sarà quello che registrerà il pulsante e lo farà apparire nell’editor visuale di WordPress:

<?php
			function aggiungi_plugin( $plugin_array ) {
			    $plugin_array['miolink'] = get_template_directory_uri() . '/js/mio_pulsante.js'; // indicazione del nome dello shortcode associato al pulsante e collegamento al file javascript che farà funzionare il pulsante
			    return $plugin_array;
			}
		?>

Inseriamo nel file mio_pulsante.js il codice javascript necessario:

<script type="text/javascript">
		// Script che aggiunge il bottone all'editor
			(function() {
			    tinymce.create('tinymce.plugins.miolink', {
			        init : function(ed, url) {
			            ed.addButton('miolink', {
			                title : 'Aggiungi miolink', //attributo "Title" del pulsante
			                image : '../wp-includes/images/smilies/icon_eek.gif', // collegamento all'icona del pulsante
			                onclick : function() {
			                     ed.selection.setContent('[miolink]' + ed.selection.getContent() + '[/miolink]');
			                }
			            });
			        },
			        createControl : function(n, cm) {
			            return null;
			        },
			    });
			    tinymce.PluginManager.add('miolink', tinymce.plugins.miolink);
			})();
		</script>

Ora, se carichiamo l'editor, dovremmo vedere apparire il pulsante che abbiamo creato. Premiamo sul pulsante e questo stamperà lo shortcode [miolink][/miolink] nel quale potremo inserire il testo che preferiamo: [miolink]link[/miolink]. Il codice html generato sarà il seguente:

<a href="http://www.miolink.com/cartella/sottocartella/sottosottocartella/documento.pdf">link</a>