Ceci est la deuxième partie de deux articles dédiés aux éditeurs WordPress. Le premier article parlait de l’éditeur de texte de WordPress, tandis que dans cet article, nous allons disséquer l’éditeur WordPress TinyMCE, et nous allons le plier à notre volonté. Suivez les instructions ci-dessous, car nous vous montrerons comment faire :

 

TinyMCE

TinyMCE est un éditeur WYSIWYG basé sur un navigateur écrit en JavaScript et publié sous forme de logiciel open source LGPL

Éditeur WordPress TinyMCE

 

Mise à jour : WordPress 5.0 changera la façon dont nous écrivons et publions le contenu. N’oubliez pas de jeter un coup d’œil à notre guide : Quoi de neuf dans WordPress 5.0 (Comment se préparer à Gutenberg)

Par défaut, WordPress l’éditeur TinyMCE fournit deux ligne de boutons pour créer, modifier et formater le contenu des publications. La première ligne (la barre d’outils principale) comprend des fonctionnalités de style et de formatage. Des contrôles supplémentaires permettent d’ajouter, de modifier et de supprimer des ancres, d’ajouter la balise <!-more->, d’activer le mode sans distraction. Tous ces boutons devraient sembler assez familiers à toute personne ayant des connaissances de base en traitement de texte.

Le bouton « Ouvrir/Fermer la barre d’outils » de la barre d’outils permet de déplier la barre d’outils de l’éditeur avancé (la deuxième rangée de boutons), qui propose un menu d’éléments de texte (paragraphe, en-têtes et texte préformaté), des commandes de style plus nombreuses et quelques fonctions supplémentaires (Coller en texte, Nettoyer la mise en forme, Caractères spéciaux, Annuler et Rétablir) qui sont très pratiques de plusieurs manières.

Caractères spéciaux

Le tableau des Caractères spéciaux permet aux utilisateurs d’ajouter rapidement des entités HTML

Enfin, le bouton point d’interrogation fournit une liste de raccourcis clavier qui améliorent l’expérience d’écriture de l’utilisateur.

Le panneau de raccourcis TinyMCE

Le panneau de raccourcis TinyMCE

Maintenant, ajoutez et stylisez votre contenu dans l’éditeur visuel, puis passez à l’éditeur de texte. Vous trouverez la structure HTML correspondante car WordPress conservera vos données lorsque vous passerez du mode visuel au mode texte.

Les barres d’outils primaires et avancées par défaut fournissent un bon nombre de fonctionnalités qui peuvent être étendues avec des boutons et des contrôles supplémentaires. Beaucoup de ces boutons sont disponibles dans TinyMCE, et nous avons juste besoin de les activer pour les mettre en action. De plus, nous pouvons ajouter un bon nombre de fonctionnalités avancées en installant une ou plusieurs des extensions existantes.

Et si tous ces boutons ne suffisent pas, nous pouvons améliorer l’éditeur avec vos fonctionnalités les plus cool, en développant des extensions personnalisées.

Ceci étant dit, commençons à plonger à partir de l’utilisation la plus simple et la plus courante de l’API.

Ajout de Styles Personnalisés à L’éditeur WordPress TinyMCE

Supposons que vous ayez besoin de fournir un moyen facile d’ajouter des styles personnalisés dans le contenu des publications depuis TinyMCE. C’est une procédure en deux étapes :

  • nous devons d’abord activer un menu déroulant caché appelé Styleselect,
  • alors nous devons définir chaque style que nous voulons ajouter au menu Styleselect.

Nous pouvons accomplir la première tâche en filtrant le tableau des boutons TinyMCE. La barre d’outils par défaut affiche une ou deux lignes de boutons, mais nous pouvons activer jusqu’à quatre lignes de barre d’outils grâce aux filtres suivants :

  • mce_buttons filtre les boutons de la barre d’outils primaire (la première ligne), qui est toujours visible ;
  • mce_buttons_2 filtre les boutons avancés de la barre d’outils (la deuxième ligne), qui peuvent être activés ou désactivés par l’utilisateur ;
  • mce_buttons_3 inactif par défaut ;
  • mce_buttons_4 inactif par défaut.

Nous pouvons hooker une fonction de callback à l’un de ces filtres pour afficher/masquer les boutons existants, comme le menu Styleselect. La fonction suivante permet d’activer le menu de la deuxième ligne :

function my_mce_buttons_2( $buttons ) {
	array_unshift( $buttons, 'styleselect' );
	return $buttons;
}
add_filter( 'mce_buttons_2', 'my_mce_buttons_2' );

La fonction PHP array_unshift précède l’élément styleselect en face du tableau $buttons.

Le menu déroulant Format affichera une liste de tous les styles CSS disponibles.

Le menu déroulant Format affichera une liste de tous les styles CSS disponibles.

Maintenant que le bouton a été activé, nous pouvons enregistrer nos styles personnalisés en filtrant un tableau de paramètres de configuration TinyMCE à travers le filtre tiny_mce_before_init.
Regardez la fonction suivante :

function my_tiny_mce_before_init( $mceInit ) {
	$style_formats = array(
		array(
			'title' => 'PHP',
			'block' => 'code',
			'classes' => 'language-php'
		)	
	);
	$mceInit['style_formats'] = json_encode( $style_formats );	
	return $mceInit;    
}
add_filter( 'tiny_mce_before_init', 'my_tiny_mce_before_init' );

L’élément style_formats est un tableau d’éléments codés en JSON. Chaque élément définit les paramètres de configuration d’un seul élément de menu. La fonction ci-dessus remplace les styles par défaut par un seul élément personnalisé qui enveloppe le texte sélectionné dans un élément code.language-php.

Le menu déroulant Styleselect contenant un seul élément personnalisé

Le menu déroulant Styleselect contenant un seul élément personnalisé

Dans notre exemple, nous définissons trois propriétés pour un seul élément de menu :

  • title : le titre de l’élément de menu ;
  • block : l’élément de bloc à produire ;
  • classes : liste séparée par des espaces des classes CSS à appliquer à la sélection.

Nous avons ajouté l’élément code sous forme de bloc, de sorte qu’il ne sera appliqué qu’une seule fois à la sélection complète. L’ajouter en tant qu’élément inline appliquerait la balise de code à chaque ligne sélectionnée.

Nous pouvons ajouter d’autres éléments et les regrouper par catégorie, comme le montre l’exemple suivant :

function my_tiny_mce_before_init( $mceInit ) {
	$style_formats = array(
		array(
			'title' => 'Code language',
			'items' => array(
				array(
					'title' => 'PHP',
					'block' => 'code',
					'classes' => 'language-php'
				),
				array(
					'title' => 'CSS',
					'block' => 'code',
					'classes' => 'language-css'
				),
				array(
					'title' => 'HTML',
					'block' => 'code',
					'classes' => 'language-html'
				)
			)
		)	
	);

	$mceInit['style_formats'] = json_encode( $style_formats );
	
	return $mceInit;    
}
add_filter( 'tiny_mce_before_init', 'my_tiny_mce_before_init' );

L’élément style_formats est un tableau multidimensionnel de paramètres. Dans cet exemple, nous avons ajouté un élément de premier niveau (langage de code) et trois sous-éléments (PHP, CSS, HTML). L’image ci-dessous montre le menu résultant.

Nous pouvons regrouper les éléments de menu et réduire la taille du menu à l'écran.

Nous pouvons regrouper les éléments de menu et réduire la taille du menu à l’écran.

TinyMCE applique les styles aux éléments sélectionnés, mais n’est pas au courant de ces styles, donc ils ne seront pas appliqués au contenu de l’éditeur. Si un aperçu en temps réel est nécessaire, nous devrons enregistrer une feuille de style personnalisée avec l’option fonction add_editor_style() :

/**
 * Registers an editor stylesheet for a custom theme.
 */
function my_theme_add_editor_styles() {
	add_editor_style( 'css/my-editor-style.css' );
}
add_action( 'admin_init', 'my_theme_add_editor_styles' );

Cette fonction enregistre une feuille de style qui sera utilisée par WordPress TinyMCE pour styliser le contenu dans l’éditeur.

Supposons, par exemple, que nous voulions appliquer différentes couleurs au code PHP, CSS et HTML. Pour accomplir cette tâche, nous ajouterons les déclarations suivantes dans la feuille de style css/my-editor-style.css :

.language-php{ color: red; }
.language-css{ color: green; }
.language-html{ color: blue; }

TinyMCE produira la sortie affichée dans l’image suivante.

add editor styles

Note : Nous n’avons examiné que quelques paramètres de configuration, mais l’API TinyMCE donne aux développeurs un grand contrôle sur l’éditeur. Voir la documentation de TinyMCE pour la liste complète des éléments et propriétés avec quelques exemples d’utilisation.

Activer les Boutons Masqués de WordPress TinyMCE

Nous pouvons ajouter des boutons à l’éditeur visuel de plusieurs façons. Dans de nombreux cas, nous ne sommes pas obligés de construire un bouton personnalisé car TinyMCE fournit un bon nombre de boutons masqués que nous pouvons facilement activer.
L’un de ces boutons est le menu déroulant Styleselect, mais nous avons une longue liste de boutons inactifs que nous pouvons activer en filtrant les tableaux de boutons à travers un des filtres mce_buttons_{n} (voir la documentation de TinyMCE pour la liste complète des boutons disponibles).

Prenons l’exemple suivant :

function my_mce_buttons_3( $buttons ) {	
	$buttons[] = 'superscript';
	$buttons[] = 'subscript';
	return $buttons;
}
add_filter( 'mce_buttons_3', 'my_mce_buttons_3' );

La fonction de callback ci-dessus ajoute les éléments en superscript et en subscript à la fin du tableau $buttons.

L'image montre deux boutons supplémentaires ajoutés à la troisième ligne de la barre d'outils TinyMCE

L’image montre deux boutons supplémentaires ajoutés à la troisième ligne de la barre d’outils TinyMCE

Voici une liste des boutons masqués disponibles dans WordPress TinyMCE :

  • cut
  • copy
  • paste
  • hr
  • formatselect
  • fontselect
  • fontsizeselect
  • styleselect
  • subscript (précédemment sub)
  • superscript (précédemment sup)
  • backcolor
  • newdocument
L'image montre la barre d'outils TinyMCE avec tous les boutons disponibles

L’image montre la barre d’outils TinyMCE avec tous les boutons disponibles

Si aucun de ces boutons ne correspond à nos besoins, nous pouvons fournir plus de fonctionnalités à l’éditeur, grâce à un bon nombre d’extensions officielles.

Amélioration de L’éditeur Visuel avec les Extensions TinyMCE

Supposons que votre but est d’inclure l’élément TinyMCE Table dans l’éditeur visuel via une extension WordPress.

Tout d’abord, vous devez télécharger le paquet Dev à partir de site de TinyMCE. Décompressez le fichier zip et récupérez le fichier plugin.min.js du dossier /js/tinymce/plugin/table.

Créez les dossiers suivants dans /wp-content/plugins :

  • /wp-content/plugins/tinymce-example-plugin/
  • /wp-content/plugins/tinymce-example-plugin/mce/table

Lorsque vous avez terminé, créez un nouveau fichier tinymce-exemple-plugin.php dans le dossier racine de l’extension, et téléversez le fichier plugin.min.js dans le dossier table (voir l’image ci-dessous).

L'image montre la structure de fichier de l’extension

L’image montre la structure de fichier de l’extension

Ajoutez maintenant les lignes suivantes dans tinymce-example-plugin.php :

<?php
/**
 * @package TinyMCE_example_plugin
 * @version 1.0
 */
/*
Plugin Name: TinyMCE example plugin
Plugin URI: http://wordpress.org/extend/plugins/#
Description: This is an example plugin 
Author: Your Name
Version: 1.0
Author URI: http://yourdomain.com/
*/ 

Afin d’inclure le bouton Tableau dans l’éditeur WordPress TinyMCE nous avons juste besoin de deux filtres :
mce_buttons ajoute de nouveaux boutons à la barre d’outils primaire de TinyMCE (nous pouvons utiliser n’importe lequel des filtres
mce_buttons_{n}, selon la ligne où le bouton doit être affiché)
mce_external_plugins charge une extension TinyMCE externe.

Voici le code du fichier de l’extension :

function example_plugin_register_buttons( $buttons ) {
   $buttons[] = 'table';
	return $buttons;
}
// add new buttons
add_filter( 'mce_buttons', 'example_plugin_register_buttons' );

function example_plugin_register_plugin( $plugin_array ) {
   $plugin_array['table'] = plugins_url( '/mce/table/plugin.min.js', __FILE__ );
   return $plugin_array;
}
// Load the TinyMCE plugin
add_filter( 'mce_external_plugins', 'example_plugin_register_plugin' );

La première fonction ajoute un nouveau bouton à la barre d’outils principale, tandis que la seconde charge une extension à partir de l’URL spécifiée. La fonction plugins_url() récupère l’URL absolue vers le fichier spécifié sous le répertoire de l’extension (lire plus d’informations sur le Codex).

Maintenant nous pouvons sauvegarder le fichier et activer l’extension. L’image ci-dessous montre la barre d’outils améliorée.

table

C’est tout. En suivant la même procédure, nous pouvons ajouter toutes les extensions TinyMCE existantes dans l’éditeur visuel de WordPress.

Vous pouvez télécharger le fichier .zip de l’extension, ou voir le code PHP de cet exemple sur Gist.

Construire une Extension TinyMCE

Enfin, nous pouvons construire notre extension TinyMCE personnalisée. Supposons que vous vouliez ajouter un bouton pour permettre aux utilisateurs d’envelopper le contenu sélectionné dans les balises suivantes :

<pre><code>Selected text</code></pre>

On peut même décider d’ajouter une classe CSS à la balise <code>, pour fournir un support du surligneur de code Prism. Nous devons :

  • enregistrer un bouton TinyMCE personnalisé et dans une extension WordPress ;
  • développer l’extension TinyMCE ;

Nous savons déjà comment enregistrer une extension et ajouter un bouton dans WordPress TinyMCE :

function example_plugin_register_buttons( $buttons ) {
	$buttons[] = 'prism';
	return $buttons;
}
// add new buttons
add_filter( 'mce_buttons', 'example_plugin_register_buttons' );

function example_plugin_register_plugin( $plugin_array ) {
	$plugin_array['prism'] = plugins_url( '/mce/prism/plugin.js', __FILE__ );
	return $plugin_array;
}
// Load the TinyMCE plugin
add_filter( 'mce_external_plugins', 'example_plugin_register_plugin' );

C’est exactement le même code que dans l’exemple précédent, avec la seule différence que maintenant nous enregistrons une extension personnalisée nommée prism.
Maintenant, créons le fichier plugin.js suivant :

(function() {
	var languages = ['css', 'php', 'html', 'javascript'];
	
	tinymce.PluginManager.add( 'prism', function( editor ){
		
		var items = [];

		tinymce.each( languages, function( languageName ){
			items.push({
				text: languageName,
				onclick: function(){
					var content = tinyMCE.activeEditor.selection.getContent();
					editor.insertContent( '<pre><code class="language-' + languageName + '">' + content + '</code></pre>' );
				}
			});
		});

		editor.addButton( 'prism', {
			type: 'menubutton',
			text: 'Prism',
			icon: 'code',
			menu: items
		});

	});
})();

Ce code est aussi disponible sur Gist.

Il n’est pas dans nos objectifs de nous plonger dans les API TinyMCE, et vous trouverez tout ce que vous avez besoin de savoir dans les documents TinyMCE pour les développeurs.

Ce fichier doit être placé dans le sous-dossier de notre extension /mce/prism/. La fonction JS itère parmi les éléments du tableau des langues et pousse un nouvel objet dans le tableau des éléments pour chaque langue. La méthode addButton crée le bouton de menu Prism, et ajoute un élément de menu pour chaque élément du tableau.

Enregistrez, téléversez et rafraîchissez, et votre magnifique bouton de menu déroulant apparaîtra dans toute sa beauté.

prism menu button

Pour plus d’informations sur le développement des extensions TinyMCE, consultez la section documentation en ligne pour les développeurs.

Extension TinyMCE Advanced pour WordPress

Si vous n’êtes pas développeur, vous pouvez également améliorer l’éditeur visuel. TinyMCE Advanced est une extension WordPress gratuite qui apporte les fonctionnalités de quinze extensions TinyMCE à l’éditeur visuel par défaut.

Grâce à TinyMCE Advanced, les utilisateurs pourront ajouter, supprimer, réarranger les boutons sur les quatre lignes de la barre d’outils de l’éditeur. De plus, l’extension offre une option pour activer un menu au-dessus de la barre d’outils.

Depuis la page des réglages de l'éditeur, nous pouvons ajouter, supprimer et organiser des boutons sur la barre d'outils TynyMCE

Depuis la page des réglages de l’éditeur, nous pouvons ajouter, supprimer et organiser des boutons sur la barre d’outils TynyMCE

From the plugin options page we can enable several advanced features, like the Table button, the Font Family and Font Size menus, the Show blocks and Show invisible characters buttons.

Other options allow users to determine the editor that will be affected by new settings, and more.

TinyMCE Advanced fournit une liste complète des réglages de l'éditeur

TinyMCE Advanced fournit une liste complète des réglages de l’éditeur

Conclusions

L’API TinyMCE fournit beaucoup de choses pour jouer avec. Nous pouvons activer des fonctionnalités cachées ou enregistrer des plugins externes. Et si aucune des fonctionnalités disponibles ne nous suffit, nous pouvons nous amuser avec l’API et créer des extensions personnalisées. Avez-vous d’autres idées pour améliorer l’éditeur WordPress TinyMCE ?

19
Partages