Come creare un plugin TinyMCE per WordPress

Se sei uno sviluppatore WordPress, a un certo punto potresti trovarti a personalizzare o estendere l'editor visuale di WordPress. Ad esempio, potresti voler aggiungere un pulsante alla barra degli strumenti dell'editor visuale per consentire al tuo cliente di inserire facilmente una casella di testo o un pulsante di invito all'azione senza scrivere alcun codice HTML. In questo articolo, ti mostreremo come creare un plugin TinyMCE in WordPress.

Requisiti

Questo tutorial è destinato agli utenti avanzati. Se sei un utente principiante che desidera solo estendere l'editor visuale, consulta il plugin TinyMCE Advanced o dai un'occhiata a questi suggerimenti sull'utilizzo dell'editor visuale di WordPress.

Per questo tutorial, avrai bisogno di competenze di codifica di base, accesso a un'installazione di WordPress dove puoi testarlo.

È una cattiva pratica sviluppare plugin su un sito web attivo. Un piccolo errore nel codice può rendere il tuo sito inaccessibile. Ma se devi farlo su un sito attivo, allora almeno effettua il backup di WordPress prima.

Creazione del tuo primo plugin TinyMCE

Inizieremo creando un plugin di WordPress per registrare il nostro pulsante personalizzato della barra degli strumenti di TinyMCE. Quando cliccato, questo pulsante consentirà all'utente di aggiungere un link con una classe CSS personalizzata.

Il codice sorgente sarà fornito per intero alla fine di questo articolo, ma fino ad allora, creiamo il plugin passo dopo passo.

Innanzitutto, è necessario creare una directory nella cartella wp-content/plugins della tua installazione di WordPress. Chiama questa cartella tinymce-custom-link-class.

Da qui, inizieremo ad aggiungere il codice del nostro plugin.

L'intestazione del plugin

Crea un nuovo file nella directory del plugin che abbiamo appena creato e chiama questo file tinymce-custom-link-class.php. Aggiungi questo codice al file e salvalo.

/**
 * Plugin Name: TinyMCE Custom Link Class
 * Plugin URI: http://wpbeginner.com
 * Version: 1.0
 * Author: WPBeginner
 * Author URI: https://www.wpbeginner.com
 * Description: A simple TinyMCE Plugin to add a custom link class in the Visual Editor
 * License: GPL2
 */

Questo è solo un commento PHP, che indica a WordPress il nome del plugin, nonché l'autore e una descrizione.

Nell'area di amministrazione di WordPress, attiva il tuo nuovo plugin andando su Plugin > Plugin installati, e quindi cliccando su Attiva accanto al plugin TinyMCE Custom Link Class:

Impostazione della nostra classe plugin

Se due plugin di WordPress hanno funzioni con lo stesso nome, ciò causerebbe un errore. Eviteremo questo problema racchiudendo le nostre funzioni in una classe.

class TinyMCE_Custom_Link_Class {
	
	/**
	* Constructor. Called when the plugin is initialised.
	*/
	function __construct() {
		
	}

}

$tinymce_custom_link_class = new TinyMCE_Custom_Link_Class;

Questo crea la nostra classe PHP, insieme a un costruttore, che viene chiamato quando raggiungiamo la riga $tinymce_custom_link_class = new TinyMCE_Custom_Link_Class;.

Qualsiasi funzione che aggiungiamo all'interno di questa classe non dovrebbe entrare in conflitto con altri plugin di WordPress.

Inizia l'impostazione del nostro plugin TinyMCE

Successivamente, dobbiamo dire a TinyMCE che potremmo voler aggiungere il nostro pulsante personalizzato alla barra degli strumenti dell'Editor Visuale. Per fare ciò, possiamo utilizzare le azioni di WordPress – in particolare, l'azione init.

Aggiungi il seguente codice all'interno della funzione __construct() del tuo plugin:

if ( is_admin() ) {
	add_action( 'init', array(  $this, 'setup_tinymce_plugin' ) );
}

Questo controlla se ci troviamo nell'interfaccia di amministrazione di WordPress. Se ci troviamo, allora chiede a WordPress di eseguire la funzione setup_tinymce_plugin all'interno della nostra classe quando WordPress ha terminato la sua routine di caricamento iniziale.

Successivamente, aggiungi la funzione setup_tinymce_plugin:

/**
* Check if the current user can edit Posts or Pages, and is using the Visual Editor
* If so, add some filters so we can register our plugin
*/
function setup_tinymce_plugin() {

// Check if the logged in WordPress User can edit Posts or Pages
// If not, don't register our TinyMCE plugin
	
if ( ! current_user_can( 'edit_posts' ) && ! current_user_can( 'edit_pages' ) ) {
	        return;
}

// Check if the logged in WordPress User has the Visual Editor enabled
// If not, don't register our TinyMCE plugin
if ( get_user_option( 'rich_editing' ) !== 'true' ) {
return;
}

// Setup some filters
add_filter( 'mce_external_plugins', array( &$this, 'add_tinymce_plugin' ) );
add_filter( 'mce_buttons', array( &$this, 'add_tinymce_toolbar_button' ) );
		
	}

Questo controlla se l'utente WordPress attualmente connesso può modificare Post o Pagine. Se non possono, non ha senso registrare il nostro plugin TinyMCE per quell'utente, poiché non vedranno mai l'Editor Visivo.

Controlliamo quindi se l'utente sta utilizzando l'Editor Visivo, poiché alcuni utenti di WordPress lo disattivano tramite Utenti > Il tuo profilo. Ancora una volta, se l'utente non sta utilizzando l'Editor Visivo, restituiamo (eseguiamo) la funzione, poiché non è necessario fare altro.

Infine, aggiungiamo due filtri di WordPress – mce_external_plugins e mce_buttons, per chiamare le nostre funzioni che caricheranno il file Javascript richiesto per TinyMCE e aggiungeranno un pulsante alla barra degli strumenti di TinyMCE.

Registrazione del file Javascript e del pulsante nell'editor visuale

Procediamo e aggiungiamo la funzione add_tinymce_plugin:

/**
* Adds a TinyMCE plugin compatible JS file to the TinyMCE / Visual Editor instance
*
* @param array $plugin_array Array of registered TinyMCE Plugins
* @return array Modified array of registered TinyMCE Plugins
*/
function add_tinymce_plugin( $plugin_array ) {

$plugin_array['custom_link_class'] = plugin_dir_url( __FILE__ ) . 'tinymce-custom-link-class.js';
return $plugin_array;

}
    

Questa funzione dice a TinyMCE che deve caricare i file Javascript memorizzati nell'array $plugin_array. Questi file Javascript diranno a TinyMCE cosa fare.

Dobbiamo anche aggiungere del codice alla funzione add_tinymce_toolbar_button, per informare TinyMCE del pulsante che vorremmo aggiungere alla barra degli strumenti:

/**
* Adds a button to the TinyMCE / Visual Editor which the user can click
* to insert a link with a custom CSS class.
*
* @param array $buttons Array of registered TinyMCE Buttons
* @return array Modified array of registered TinyMCE Buttons
*/
function add_tinymce_toolbar_button( $buttons ) {

array_push( $buttons, '|', 'custom_link_class' );
return $buttons;
}

Questo aggiunge due elementi all'array dei pulsanti di TinyMCE: un separatore (|) e il nome programmatico del nostro pulsante (custom_link_class).

Salva il tuo plugin, quindi modifica una Pagina o un Articolo per visualizzare l'Editor Visuale. Probabilmente, la barra degli strumenti non viene visualizzata al momento:

Non preoccuparti – se usiamo la console dell'ispettore del nostro browser web, vedremo che un errore 404 e un avviso sono stati generati da TinyMCE, dicendoci che non riesce a trovare il nostro file Javascript.

Questo è positivo – significa che abbiamo registrato con successo il nostro plugin personalizzato di TinyMCE e ora dobbiamo creare il file Javascript per dire a TinyMCE cosa fare.

Creazione del Plugin Javascript

Crea un nuovo file nella tua cartella wp-content/plugins/tinymce-custom-link-class e chiamalo tinymce-custom-link-class.js. Aggiungi questo codice nel tuo file js:

(function() {
	tinymce.PluginManager.add( 'custom_link_class', function( editor, url ) {
		
	});
})();

Questo chiama la classe TinyMCE Plugin Manager, che possiamo usare per eseguire una serie di azioni relative ai plugin di TinyMCE. Nello specifico, stiamo aggiungendo il nostro plugin a TinyMCE usando la funzione add.

Questo accetta due elementi; il nome del plugin (custom_link_class) e una funzione anonima.

Se hai familiarità con il concetto di funzioni nella programmazione, una funzione anonima è semplicemente una funzione senza nome. Ad esempio, function foobar() { ... } è una funzione che potremmo chiamare altrove nel nostro codice usando foobar().

Con una funzione anonima, non possiamo chiamare quella funzione altrove nel nostro codice – viene chiamata solo nel punto in cui viene invocata la funzione add().

Salva il tuo file Javascript, quindi modifica una Pagina o un Post per visualizzare l'Editor Visuale. Se tutto ha funzionato, vedrai la barra degli strumenti:

Al momento, il nostro pulsante non è stato aggiunto a quella barra degli strumenti. Questo perché abbiamo solo detto a TinyMCE che siamo un plugin personalizzato. Ora dobbiamo dire a TinyMCE cosa fare – cioè, aggiungere un pulsante alla barra degli strumenti.

Aggiorna il tuo file Javascript, sostituendo il codice esistente con il seguente:

(function() {
	tinymce.PluginManager.add( 'custom_link_class', function( editor, url ) {
		// Add Button to Visual Editor Toolbar
		editor.addButton('custom_link_class', {
			title: 'Insert Button Link',
			cmd: 'custom_link_class',
		});	
	});
})();

Nota che la nostra funzione anonima ha due argomenti. Il primo è l'istanza editor – questo è l'Editor Visuale di TinyMCE. Nello stesso modo in cui possiamo chiamare varie funzioni su PluginManager, possiamo anche chiamare varie funzioni su editor. In questo caso, stiamo chiamando la funzione addButton, per aggiungere un pulsante alla barra degli strumenti.

Salva il tuo file Javascript e torna al tuo Editor Visuale. A prima vista, nulla sembra essere cambiato. Tuttavia, se passi il cursore del mouse a destra dell'icona più a destra della riga superiore, dovresti vedere apparire un tooltip:

Abbiamo aggiunto con successo un pulsante alla barra degli strumenti, ma necessita di un'immagine. Aggiungi il seguente parametro alla funzione addButton, sotto la riga title::

image: url + '/icon.png',

url is the URL to our plugin. This is handy if we want to reference an image file within our plugin folder, as we can append the image file name to the URL. In this case, we’ll need an image called icon.png in our plugin’s folder. Use the below icon:

Reload our Visual Editor, and you’ll now see your button with the icon:

Definire un Comando da Eseguire

Al momento, se fai clic sul pulsante, non succederà nulla. Aggiungiamo un comando a TinyMCE dicendogli cosa fare quando il nostro pulsante viene cliccato.

Nel nostro file Javascript, aggiungi il seguente codice sotto la fine della sezione editor.addButton:

// Add Command when Button Clicked
editor.addCommand('custom_link_class', function() {
	alert('Button clicked!');
});

Ricarica il nostro Editor Visuale, fai clic sul pulsante e apparirà un alert che conferma che abbiamo appena cliccato il pulsante:

Sostituiamo l'avviso con un prompt, chiedendo all'utente il link che desidera associare al testo selezionato nell'Editor Visuale:

// Add Command when Button Clicked
editor.addCommand('custom_link_class', function() {
	// Check we have selected some text that we want to link
	var text = editor.selection.getContent({
		'format': 'html'
	});
	if ( text.length === 0 ) {
		alert( 'Please select some text to link.' );
		return;
	}

	// Ask the user to enter a URL
	var result = prompt('Enter the link');
	if ( !result ) {
		// User cancelled - exit
		return;
	}
	if (result.length === 0) {
		// User didn't enter a URL - exit
		return;
	}

	// Insert selected text back into editor, wrapping it in an anchor tag
	editor.execCommand('mceReplaceContent', false, '<a class="button" href="' + result + '">' + text + '</a>');
});

Questo blocco di codice esegue alcune azioni.

Innanzitutto, verifichiamo se l'utente ha selezionato del testo da collegare nell'Editor Visuale. In caso contrario, vedrà un avviso che gli dice di selezionare del testo da collegare.

Successivamente, gli chiediamo di inserire un link, verificando nuovamente se lo ha fatto. Se ha annullato o non ha inserito nulla, non facciamo altro.

Infine, eseguiamo la funzione execCommand sull'editor TinyMCE, eseguendo specificamente l'azione mceReplaceContent. Questo sostituisce il testo selezionato con il nostro codice HTML, che comprende un link di ancoraggio con classe=”button”, utilizzando il testo selezionato dall'utente.

Se tutto ha funzionato, vedrai che il testo selezionato è ora collegato nelle viste Editor Visuale e Testo, con la classe impostata su button:

Riepilogo

Abbiamo creato con successo un plugin per WordPress che aggiunge un pulsante all'editor visuale TinyMCE in WordPress. Questo tutorial ha anche coperto alcune delle basi dell'API TinyMCE e dei filtri di WordPress disponibili per le integrazioni TinyMCE.

Abbiamo aggiunto del codice in modo che, quando un utente fa clic sul nostro pulsante personalizzato, gli venga chiesto di selezionare del testo nell'Editor Visuale, che potrà poi collegare a un URL a sua scelta. Infine, il nostro plugin sostituisce il testo selezionato con una versione collegata che contiene una classe CSS personalizzata chiamata button.

Speriamo che questo tutorial ti abbia aiutato a imparare come creare un plugin TinyMCE per WordPress. Potresti anche voler consultare la nostra guida su come creare un plugin specifico per il tuo sito WordPress.

Se ti è piaciuto questo articolo, iscriviti al nostro Canale YouTube per tutorial video su WordPress. Puoi anche trovarci su Twitter e Facebook.