Comment créer un plugin TinyMCE pour WordPress

Si vous êtes un développeur WordPress, vous rencontrerez à un moment donné la personnalisation ou l'extension de l'éditeur visuel WordPress. Par exemple, vous pourriez vouloir ajouter un bouton à la barre d'outils de l'éditeur visuel pour permettre à votre client d'insérer facilement une zone de texte ou un bouton d'appel à l'action sans écrire de code HTML. Dans cet article, nous vous montrerons comment créer un plugin TinyMCE dans WordPress.

Exigences

Ce tutoriel est destiné aux utilisateurs avancés. Si vous êtes un utilisateur débutant qui souhaite simplement étendre l'éditeur visuel, consultez le plugin TinyMCE Advanced ou jetez un œil à ces conseils sur l'utilisation de l'éditeur visuel WordPress.

Pour ce tutoriel, vous aurez besoin de compétences de base en codage, d'un accès à une installation WordPress où vous pourrez le tester.

Il est déconseillé de développer des plugins sur un site web en direct. Une petite erreur dans le code peut rendre votre site inaccessible. Mais si vous devez le faire sur un site en direct, alors sauvegardez WordPress d'abord.

Créer votre premier plugin TinyMCE

Nous commencerons par créer un plugin WordPress pour enregistrer notre bouton de barre d'outils TinyMCE personnalisé. Lorsqu'il sera cliqué, ce bouton permettra à l'utilisateur d'ajouter un lien avec une classe CSS personnalisée.

Le code source sera fourni dans son intégralité à la fin de cet article, mais en attendant, créons le plugin étape par étape.

Tout d'abord, vous devez créer un répertoire dans le dossier wp-content/plugins de votre installation WordPress. Nommez ce dossier tinymce-custom-link-class.

À partir de là, nous allons commencer à ajouter notre code de plugin.

L'en-tête du plugin

Créez un nouveau fichier dans le répertoire du plugin que nous venons de créer et nommez ce fichier tinymce-custom-link-class.php. Ajoutez ce code au fichier et enregistrez-le.

/**
 * 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
 */

Ceci est juste un commentaire PHP, qui indique à WordPress le nom du plugin, ainsi que l'auteur et une description.

Dans la zone d'administration de WordPress, activez votre nouveau plugin en allant dans Plugins > Plugins installés, puis en cliquant sur Activer à côté du plugin TinyMCE Custom Link Class :

Configuration de notre classe de plugin

Si deux plugins WordPress ont des fonctions portant le même nom, cela provoquerait une erreur. Nous éviterons ce problème en encapsulant nos fonctions dans une classe.

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

}

$tinymce_custom_link_class = new TinyMCE_Custom_Link_Class;

Ceci crée notre classe PHP, ainsi qu'un constructeur, qui est appelé lorsque nous atteignons la ligne $tinymce_custom_link_class = new TinyMCE_Custom_Link_Class;.

Toutes les fonctions que nous ajouterons à l'intérieur de cette classe ne devraient pas entrer en conflit avec d'autres plugins WordPress.

Commencer à configurer notre plugin TinyMCE

Ensuite, nous devons indiquer à TinyMCE que nous pourrions vouloir ajouter notre bouton personnalisé à la barre d'outils de l'Éditeur Visuel. Pour ce faire, nous pouvons utiliser les actions de WordPress – spécifiquement, l'action init.

Ajoutez le code suivant à l'intérieur de la fonction __construct() de votre plugin :

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

Ceci vérifie si nous sommes dans l'interface d'administration de WordPress. Si c'est le cas, il demande à WordPress d'exécuter la fonction setup_tinymce_plugin à l'intérieur de notre classe une fois que WordPress a terminé sa routine de chargement initiale.

Ensuite, ajoutez la fonction 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' ) );
		
	}

Ceci vérifie si l'utilisateur WordPress actuellement connecté peut modifier les Articles ou Pages. S'il ne le peut pas, il est inutile d'enregistrer notre plugin TinyMCE pour cet utilisateur, car il ne verra jamais l'éditeur visuel.

Nous vérifions ensuite si l'utilisateur utilise l'éditeur visuel, car certains utilisateurs de WordPress le désactivent via Utilisateurs > Votre profil. Encore une fois, si l'utilisateur n'utilise pas l'éditeur visuel, nous retournons (quittons) la fonction, car nous n'avons rien d'autre à faire.

Enfin, nous ajoutons deux filtres WordPress – mce_external_plugins et mce_buttons, pour appeler nos fonctions qui chargeront le fichier Javascript requis pour TinyMCE, et ajouter un bouton à la barre d'outils TinyMCE.

Enregistrement du fichier Javascript et du bouton dans l'éditeur visuel

Ajoutons la fonction 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;

}
    

Cette fonction indique à TinyMCE qu'il doit charger les fichiers Javascript stockés dans le tableau $plugin_array. Ces fichiers Javascript indiqueront à TinyMCE quoi faire.

Nous devons également ajouter du code à la fonction add_tinymce_toolbar_button, pour informer TinyMCE du bouton que nous souhaitons ajouter à la barre d'outils :

/**
* 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;
}

Cela ajoute deux éléments au tableau des boutons TinyMCE : un séparateur (|) et le nom programmatique de notre bouton (custom_link_class).

Enregistrez votre plugin, puis modifiez une Page ou un Article pour afficher l'éditeur visuel. Il y a de fortes chances que la barre d'outils ne s'affiche pas pour le moment :

Ne vous inquiétez pas – si nous utilisons la console d'inspection de notre navigateur web, nous verrons qu'une erreur 404 et une notification ont été générées par TinyMCE, nous indiquant qu'il ne trouve pas notre fichier Javascript.

C'est une bonne chose – cela signifie que nous avons enregistré avec succès notre plugin personnalisé TinyMCE, et que nous devons maintenant créer le fichier Javascript pour indiquer à TinyMCE quoi faire.

Création du plugin Javascript

Créez un nouveau fichier dans votre dossier wp-content/plugins/tinymce-custom-link-class et nommez-le tinymce-custom-link-class.js. Ajoutez ce code dans votre fichier js :

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

Cela appelle la classe TinyMCE Plugin Manager, que nous pouvons utiliser pour effectuer un certain nombre d'actions liées aux plugins TinyMCE. Plus précisément, nous ajoutons notre plugin à TinyMCE en utilisant la fonction add.

Cela accepte deux éléments ; le nom du plugin (custom_link_class) et une fonction anonyme.

Si vous êtes familier avec le concept de fonctions en programmation, une fonction anonyme est simplement une fonction sans nom. Par exemple, function foobar() { ... } est une fonction que nous pourrions appeler ailleurs dans notre code en utilisant foobar().

Avec une fonction anonyme, nous ne pouvons pas appeler cette fonction ailleurs dans notre code – elle n'est appelée qu'au moment où la fonction add() est invoquée.

Enregistrez votre fichier Javascript, puis modifiez une Page ou un Article pour afficher l'Éditeur Visuel. Si tout a fonctionné, vous verrez la barre d'outils :

Pour l'instant, notre bouton n'a pas été ajouté à cette barre d'outils. C'est parce que nous avons seulement indiqué à TinyMCE que nous sommes un plugin personnalisé. Nous devons maintenant indiquer à TinyMCE quoi faire – c'est-à-dire, ajouter un bouton à la barre d'outils.

Mettez à jour votre fichier Javascript, en remplaçant votre code existant par le suivant :

(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',
		});	
	});
})();

Remarquez que notre fonction anonyme a deux arguments. Le premier est l'instance editor – c'est l'Éditeur Visuel de TinyMCE. De la même manière que nous pouvons appeler diverses fonctions sur le PluginManager, nous pouvons également appeler diverses fonctions sur l'editor. Dans ce cas, nous appelons la fonction addButton, pour ajouter un bouton à la barre d'outils.

Enregistrez votre fichier Javascript et retournez à votre Éditeur Visuel. À première vue, rien ne semble avoir changé. Cependant, si vous placez votre curseur de souris à droite de la dernière icône de la première rangée, vous devriez voir apparaître une info-bulle :

Nous avons ajouté avec succès un bouton à la barre d'outils, mais il a besoin d'une image. Ajoutez le paramètre suivant à la fonction addButton, sous la ligne 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:

Définir une commande à exécuter

Pour l'instant, si vous cliquez sur le bouton, rien ne se passera. Ajoutons une commande à TinyMCE lui indiquant quoi faire lorsque notre bouton est cliqué.

Dans notre fichier Javascript, ajoutez le code suivant sous la fin de la section editor.addButton :

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

Rechargez notre Éditeur Visuel, cliquez sur le bouton et une alerte apparaîtra confirmant que nous venons de cliquer sur le bouton :

Remplaçons l'alerte par une invite, demandant à l'utilisateur le lien qu'il souhaite associer au texte sélectionné dans l'éditeur visuel :

// 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>');
});

Ce bloc de code effectue plusieurs actions.

Premièrement, nous vérifions si l'utilisateur a sélectionné du texte à lier dans l'éditeur visuel. Sinon, il verra une alerte lui indiquant de sélectionner du texte à lier.

Ensuite, nous lui demandons d'entrer un lien, en vérifiant à nouveau s'il l'a fait. S'il a annulé, ou n'a rien entré, nous ne faisons rien d'autre.

Enfin, nous exécutons la fonction execCommand sur l'éditeur TinyMCE, en exécutant spécifiquement l'action mceReplaceContent. Cela remplace le texte sélectionné par notre code HTML, qui comprend un lien d'ancre avec la classe « button », en utilisant le texte que l'utilisateur a sélectionné.

Si tout a fonctionné, vous verrez que votre texte sélectionné est maintenant lié dans les vues Éditeur visuel et Texte, avec la classe définie sur button :

Résumé

Nous avons créé avec succès un plugin WordPress qui ajoute un bouton à l'éditeur visuel TinyMCE dans WordPress. Ce tutoriel a également couvert certaines bases de l'API TinyMCE et des filtres WordPress disponibles pour les intégrations TinyMCE.

Nous avons ajouté du code de sorte que lorsqu'un utilisateur clique sur notre bouton personnalisé, il est invité à sélectionner du texte dans l'éditeur visuel, qu'il peut ensuite lier à une URL de son choix. Enfin, notre plugin remplace le texte sélectionné par une version liée contenant une classe CSS personnalisée appelée button.

Nous espérons que ce tutoriel vous a aidé à apprendre comment créer un plugin TinyMCE pour WordPress. Vous voudrez peut-être aussi consulter notre guide sur comment créer un plugin WordPress spécifique au site.

Si cet article vous a plu, abonnez-vous à notre chaîne YouTube pour des tutoriels vidéo WordPress. Vous pouvez également nous trouver sur Twitter et Facebook.