WordPress – Ajouter des styles perso dans l’éditeur TinyMCE

L’éditeur visuel de WordPress s’est amélioré au fil du temps. Pour votre blog, vous avez probablement des styles particuliers pour le contenu de vos articles (liens, boutons, blocs de contenu, etc.) et peut-être passez-vous encore par l’éditeur HTML ?
L’éditeur visuel propose pourtant un sélecteur de styles bien pratique entièrement personnalisable.

Ces scripts ont été initialement créés pour WordPress 3.3.1.
Ils sont toujours fonctionnels pour WordPress 4.6.1 après tests effectués.

Brève présentation

L’éditeur visuel TinyMCE propose à la base deux sélecteurs, un pour les styles, un pour les types de blocs.
Sur WordPress, le sélecteur de styles a été retiré pour ne laisser la place qu’au sélecteur de blocs :

Je dis « type de bloc » car il propose par défaut uniquement des éléments de type blocs, dont le panel complet de titres.

Il est possible de réactiver dans la barre d’outils l’autre sélecteur proposant des styles.
Notez qu’il est également possible de personnaliser la feuille de style de l’éditeur afin d’y appliquer les styles visibles sur l’interface publique.
Voyons cela ensemble.

Ajouter un sélecteur de styles basique

Cette première méthode n’est pas ma préférée, mais elle permet d’activer rapidement un sélecteur fonctionnel.

Tout se passe dans le fichier functions.php de votre thème WordPress (wp-content/themes/[votre-theme]/), pour le moment. En effet, comme les styles sont directement liés à votre thème courant, il est normal d’y retrouver les codes dans ce fichier de thème.

Mise en place du code

Nous allons utiliser le hook tiny_mce_before_init qui permet d’intervenir avant l’initialisation de l’éditeur.
Nous allons récupérer une variable (un tableau) et lui insérer des données supplémentaires à initialiser.

<?php
// on exécute la fonction avant initialisation de l'éditeur
add_filter( 'tiny_mce_before_init', 'juiz_custom_tinymce' );
 
// la fonction est déclarée si elle n'existe pas déjà
if ( !function_exists('juiz_custom_tinymce')) {
	function juiz_custom_tinymce( $tools ) {
		// on ajoute "styleselect" à une liste d'outils séparés par une virgule
		// on complète ici la seconde ligne d'outils (buttons2)
		$tools['theme_advanced_buttons2'] = 'styleselect,'.$tools['theme_advanced_buttons2'];
 
		// on ajoute des commandes en ligne ou en bloc (box) à notre sélecteur
		$tools['theme_advanced_styles'] = __('Bouton').'=button, '.__('Télécharger').'=download, '.__('Démonstration').'=demo, '.__('Boîte de boutons').'=buttons-box, '.__('Exergue').'=highlight';
 
		// on retourne notre liste d'outils complétée
		return $tools; 
	}
}
?>

Je vais détailler deux parties de ce code pour que ce soit plus clair.

Ligne 10 – La liste des outils déjà existants sur la deuxième ligne de boutons a cette forme  formatselect,underline,justifyfull,forecolor,|.
Il s’agit d’une liste des outils séparés par une virgule. Le | (« trait vertical ») représente un séparateur. Pour compléter cette liste, il nous suffit de la reprendre et d’y placer juste avant notre « styleselect » accompagné de sa virgule.
Vous noterez la possibilité de remplacer « buttons2 » par « buttons1 » ou « buttons3 » afin d’insérer le sélecteur en 1ère ligne ou de créer une troisième ligne de commandes.

Ligne 12 – Chaque nouveau style s’applique soit à un élément en ligne soit à un élément de type bloc, sans distinction. Chaque style est présenté ainsi :
Nom=classe_associee. Ici le nom du bouton se trouve dans une fonction de traduction (au cas où ;))

Les limites de cette technique

À l’usage, vous vous rendrez compte que lorsque vous sélectionnez un texte et cliquez sur un style un élément span porteur de la classe associée est créé. Si l’élément sélectionné est déjà un élément en ligne (exemple : un lien) alors la classe sera ajoutée au lien. Si l’élément sélectionné est de type bloc la classe sera attribuée à l’élément (souvent un p) directement. (ce peut-être un blockquote, titre, paragraphe, etc.)

La sélection des blocs est assez désastreuse, cette technique s’applique donc plus facilement à des styles en ligne.

Ajouter un sélecteur de styles avancé

Comment faire pour ajouter un élément div avec une classe « poney » à mon ensemble de paragraphes ?
Comment faire pour appliquer un style uniquement si l’élément sélectionné est un lien ?
Comment … ?

C’est là que notre seconde technique peut vous intéresser : elle consiste en l’utilisation de tableau pour chaque style permettant de définir des paramètres précis prévus par TinyMCE et WordPress.

Mise en place du code

Comme précédemment, ajoutons notre sélecteur de styles en passant cette fois par le hook mce_buttons_2 qui permet de jouer avec un tableau PHP des différents boutons de la deuxième ligne de commandes.

<?php
add_filter( 'mce_buttons_2', 'juiz_mce_buttons_2' );
 
if ( !function_exists('juiz_mce_buttons_2')) {
	function juiz_mce_buttons_2( $buttons ) {
		array_unshift( $buttons, 'styleselect' );
 
		return $buttons;
	}
}
?>

Ce filtre est plus direct puisqu’il s’applique directement aux boutons.
La fonction PHP array_unshift() permet d’empiler un élément au début d’un tableau PHP. Ici nous empilons « styleselect » aux boutons (aux entrées de tableau donc) déjà existants.

Si on s’arrête là, on obtient un sélecteur des styles déjà déclarés par défaut dans WordPress. Ces styles sont déjà applicables via les différentes autres commandes de l’éditeur.
Nous allons les remplacer par les nôtres en injectant 3 styles bien différents pour que vous compreniez l’intérêt de cette technique.
Ajoutez ce code à la suite du précédent.

<?php
// le hook que nous avons vu en tout début d'article…
add_filter( 'tiny_mce_before_init', 'juiz_mce_before_init' );
 
if ( !function_exists('juiz_mce_before_init')) {
	function juiz_mce_before_init( $styles ) {
		// on créé un tableau contenant nos styles
		$style_formats = array (
			// chaque style est un nouveau tableau
 
			// Style "Italique et gras"
			array(
				'title' => __('Italique et gras'),
				'inline' => 'span',
				'styles' => array(
					'fontStyle' => 'italic',
					'fontWeight' => 'bold'
				)
			),
 
			// Style "bouton"
			array(
				'title' => __('Bouton'),
				'selector' => 'a',
				'classes' => 'button'
			),
 
			// Style "Exergue box"
			array(
				'title' => __('Exergue Box'),
				'block' => 'div',
				'classes' => 'highlight',
				'wrapper' => true
			)
		);
 
		// on remplace les styles existants par les nôtres
		$styles['style_formats'] = json_encode( $style_formats );
 
		return $styles;
	}
}
?>

Ce morceau de code est long, mais sur le principe il est simple à comprendre. Il faut se concentrer sur les tableaux qui génèrent les styles.
Pour être fonctionnel un style a au moins besoin d’un nom (title) et de son type. (inline, block, ou selector, représentés par les trois exemples)

Le type inline

Ligne 12 à 19 – Ce type de style permet d’ajouter un élément de type inline (un span dans notre exemple) autour de votre sélection dans l’éditeur. Il est possible de proposer à ce type de style d’y joindre une classe, ou des styles en ligne (via l’attribut style, comme c’est le cas dans l’exemple). Les styles en ligne sont alors à renseigner dans un tableau PHP (ligne 14 à 17) est sont à écrire en CamelCase pour ce qui est du nom de propriétés.

Le type selector

Ligne 22 à 26 – Ce type de style permet d’activer l’ajout d’une classe ou de styles en ligne uniquement lorsque l’élément sélectionné dans l’éditeur correspond à la valeur de selector. Dans notre exemple, la classe button ne sera ajoutée que si notre curseur dans l’éditeur se trouve sur un a (un lien).

Le type block

Ligne 29 à 34 – Ce type de style permet de créer un élément de type bloc autour de la sélection lorsque la valeur de wrapper est à true. Si la valeur de wrapper est à false, la de la sélection verra tous ses éléments de type bloc remplacés par un div de classe highlight (si on reprend les informations de l’exemple).

Voici un tableau récapitulatif .

Informations applicables pour vos styles perso

title (requis)	Le nom du style visible dans le sélecteur
selector ou block ou inline (requis)	selector – limite l’application du style à un élément HTML précis et existant (ça n’en créera pas de nouveau) block – crée un nouvel élément de type bloc avec les classes ou styles appliqués, il peut envelopper la sélection ou remplacer les blocs existants en fonction de la valeur de wrapper inline – Crée un nouvel élément de type en-ligne en enveloppant la sélection active dans l’éditeur. Il ne remplace aucune balise existante.
classes (optionnel)	une liste de classes séparées par un espace blanc, elles seront appliquées à la sélection.
styles (optionnel)	tableau PHP de styles appliqué en-ligne (attribut style) (les propriétés CSS en deux mots doivent être écrites en CamelCase. Ex: « fontWeight »)
attributes (optionnel)	tableau PHP des attributs appliqués (ex : array( 'title' => 'Le titre à écrire', 'hreflang' => 'en' ); )
wrapper (optionnel, vaut false par défaut)	passé à true, crée un nouvel élément bloc autour de tous les éléments blocs (ou en-ligne) sélectionnés
exact (optionnel,vaut false par défaut)	désactive la fonction de fusion des styles similaires, nécessaire dans certain cas précis en CSS

Vous remarquerez que styles et classes sont optionnels… c’est louche pour un sélecteur de styles. M’enfin, passons.
L’entrée permettant d’ajouter des attributs en fait bien plus qu’un simple sélecteur de styles 😉

Ajouter des styles CSS pour styler le contenu de l’éditeur

C’est bien beau d’ajouter des classes et attributs à notre contenu dans l’éditeur, mais ça ne serait pas trop mal de voir les styles correspondants s’afficher, ne serait-ce que pour nous assurer que les classes ont bien été appliquées.

Pour effectuer cela il vous suffit d’ajouter un fichier CSS à la racine de votre thème, ce fichier doit se nommer editor-style.css.
Une fois le fichier et les styles créés, il faut appliquer ce fichier dans l’administration lorsque l’éditeur est chargé. Dans functions.php ajoutez ceci :

<?php
if ( !function_exists('juiz_init_editor_styles')) {
   add_action( 'after_setup_theme', 'juiz_init_editor_styles' );
   function juiz_init_editor_styles() {
	add_editor_style();
   }
}
?>

Et le tour est joué !
N’hésitez pas à commenter si vous avez des questions, ça pourrait servir à d’autres également.

Pour ceux qui attendent des articles sur CSS, trois articles sont en cours de rédaction et vous ne serez pas déçus. Patience 😉