CKEDITOR5 avec Sulu

CKEditor5 qu'est-ce que c'est et pourquoi ?

CKEditor5 est un éditeur sous licence Open Source qui permet d'éditer du texte dans des applications web. L'éditeur comprend un grand nombre d'éléments que l'utilisateur pourra ajouter et supprimer à sa guise, notamment grâce à son outil de création en ligne disponible à cette adresse :

https://ckeditor.com/ckeditor-5/online-builder/

Pourquoi en parler ? Eh bien, voyez-vous, kiora.fr, le site sur lequel vous vous trouvez, est un site qui représente ladite entreprise, mais surtout un lieu où les divers intervenants (stagiaires, employés, alternants, etc.) ont l'opportunité de partager ce qu'ils découvrent et apprennent au gré de leurs missions. Pour ce faire, il a fallu prévoir quelques petites modifications au site pour permettre une bonne lecture des blogs. Pour cela, CKEditor5, qui est de prime abord déjà présent dans SULU, permet de faciliter la création d'articles avec un élément bien plaisant : le Code-Block.

<header>

<h1>Ah bah mince...c'est moche</h1>

</header>
Ce que vous voyez ci-dessus n'est pas un code-block, mais un des éléments basiques de l'éditeur CKEditor pour Sulu. Et comme vous l'avez remarqué, ce n'est pas très plaisant à lire. C'est pourquoi nous nous sommes portés sur le Code-Block.

	<header>
    	<h1>C'est mieux mais pas encore ça.</h1>
	</header>

Une nette amélioration, vous aurez plus de facilité à lire le code et à compartimenter les différents éléments que vous allez découvrir pendant la lecture des différents blogs, mais il reste quand même un menu problème qui est. Ce n'est pas comme dans l'éditeur. VSCode, PHPStorm et autres nous ont habitués à un code coloré qui nous permet de nous repérer plus facilement dans le code, peu importe son origine. C'est pour cela qu'une dernière petite retouche sera appréciée par tous.

    <header>
        <h1>Par ma barbe, c'est lisible !</h1>
    </header>

La lecture est tout de suite plus plaisant. Bien sure cela fonctionne pas seulement pour le HTML.

let problem = true;
let caffe = 0;
function pauvDev() {
 if (problem) {
   caffe++;
   return "Problème détecté ! Le développeur boit une tasse de café numéro " + caffe + " pour trouver la solution.";
 } else {
   return "Pas de problème à l'horizon. Le développeur peut savourer sa tranquillité, sans café.";
 }
}

Javascript et bien d'autre langage sont compris dans l'élément code block et sela permet de rendre l'élément ci-dessus avec une plus grande simpliciter, ce qui bien sure facilite l'écriture des blogs et leur lecture.

Maintenant je pense qu'il est temps d'expliquer comment en arriver là !

À savoir que ce que je vais vous expliquer ensuite est valable pour tous les plugins de CKEditor. Que vous souhaitiez ajouter un plugin pour la gestion des polices, la création de tableaux ou autre, la recette est la même !

La documentation de SULU nous sera très utile car elle nous permet de connaître rapidement et simplement comment ajouter un élément à SULU.

import {ckeditorPluginRegistry, ckeditorConfigRegistry} from 'sulu-admin-bundle/containers';
import Font from '@ckeditor/ckeditor5-font/src/font';

ckeditorPluginRegistry.add(Font);
ckeditorConfigRegistry.add((config) => ({
    toolbar: [...config.toolbar, 'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'],
}));

Dans l'exemple ci-dessus, il y a deux imports : le registre des plugins de CKEditor et leur configuration, ainsi qu'un package que vous pouvez voir ci-dessous.

 npm install @ckeditor/ckeditor5-font@

L'import avec Font permet de récupérer le package et de donner l'information ou il se trouve lors du build. Notons que :

ckeditorPluginRegistry.add(Font);

Devras être répéter pour chaque plugin que vous souhaiter ajouter. Par exemple pour le plugin code block et font notre build Sulu ressembleras a cela.

ckeditorPluginRegistry.add(CodeBlock);
ckeditorPluginRegistry.add(Font);
ckeditorConfigRegistry.add((config) => ({
    toolbar: [...config.toolbar, 'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', 'codeBlock'],
}));

fontSize', 'fontFamily', 'fontColor' et 'fontBackgroundColor' sont chacun un élément unique qui apparaîtrait dans la barre des tâches de CKEditor, tout comme 'codeBlock'.

Après avoir ajouté ce code dans : assets/admin/app.js

Il est maintenant temps de reconstruire le back-end avec le ou les nouveaux plugins.

Pour ce faire, il y a une manipulation très simple à faire mais avec quelques pièges que je vais vous expliquer comment éviter.

Premièrement, l'un des éléments les plus importants pour ne pas vous faire avoir et perdre du temps : les versions de Sulu et des packages utilisés sont très importantes !

    "dependencies": {
        "@ckeditor/ckeditor5-code-block": "^34.2.0",
        "@ckeditor/ckeditor5-font": "^34.2.0",

VERSION Sulu	Version CKEditor
2.1	18.0
2.2	23.0
2.3	27.1.0
2.4	31.0.0
2.5	34.2.0

Notre version de Sulu est en 2.5.x, ce qui explique pourquoi nos packages sont en 34.2.0. Notez que l'erreur que vous rencontrerez si vous ne mettez pas la bonne version de CKEditor pour votre Sulu sera la suivante :

Erreur CKEditor : modules dupliqués

Si vos packages sont de versions différentes : problème !

Si vos packages sont d'une version antérieure ou supérieure à la vôtre : problème !

Simple et concis, la lecture de ce blog vous épargnera de devoir fouiller les 'Issues' de GitHub pour connaître le problème et la solution. De rien !

Ensuite vient le moment fatidique d'implémenter la modification dans Sulu, ce qui requiert de reconstruire à nouveau le build. Et là encore une fois, on arrive à un petit problème :

Documentation : Construire à nouveau le front-end d'administration

bin/adminconsole sulu:admin:update-build

Une commande simple, et si elle fonctionnait pour ajouter des plugins à CKEditor, serait la fin de ce blog. Mais non. Car voyez-vous, CKEditor nécessite une version spécifique de Node pour s'installer. Donc, nous allons devoir effectuer cette modification manuellement.

Pour cela, nous allons utiliser Docker, l'un des logiciels favoris de Kiora, mais vous pouvez le faire manuellement avec le lien ci-dessus qui vous guidera.

La première commande qui va nous intéresser est la suivante :

docker run --rm --interactive --tty --volume ${PWD}:/var/project node:14.16.0 /bin/bash

docker run: Cette commande est utilisée pour créer et exécuter un conteneur Docker à partir d'une image Docker.

--rm: Cette option indique à Docker de supprimer le conteneur une fois qu'il a terminé son exécution. Cela garantit que le conteneur ne reste pas encombrant une fois son travail terminé.

--interactive ou -i: Cette option permet de garder le terminal ouvert pour permettre une interaction avec le conteneur.

--tty ou -t: Cette option alloue un pseudo-terminal (TTY) pour le conteneur, ce qui permet également une interaction avec le terminal.

--volume ${PWD}:/var/project: Cette option monte le répertoire courant de l'hôte (actuel où vous exécutez la commande) dans le répertoire /var/project du conteneur. Cela permet au conteneur d'accéder aux fichiers du répertoire de l'hôte.

node:14.16.0: C'est l'image Docker à partir de laquelle le conteneur est créé. Dans ce cas, c'est l'image officielle de Node.js version 14.16.0.

/bin/bash: C'est la commande qui sera exécutée à l'intérieur du conteneur une fois qu'il sera démarré. Cela ouvrira un shell bash à l'intérieur du conteneur, permettant à l'utilisateur d'interagir avec l'environnement du conteneur.

Si vous souhaitez une explication de chaque élément de cette commande c'est juste au-dessus ! Sinon, après que l'image est été créer avec une version de node correct il est temps de faire la suite.

cd /var/project

rm -rf assets/admin/node_modules && rm -rf vendor/sulu/sulu/node_modules && rm -rf vendor/sulu/sulu/src/Sulu/Bundle/*/Resources/js/node_modules

rm -rf assets/admin/package-lock.json && rm -rf vendor/sulu/sulu/package-lock.json && rm -rf vendor/sulu/sulu/src/Sulu/Bundle/*/Resources/js/package-lock.json

La première commande vous permet de rentrer dans votre projet si vous avez créé l'image Docker à la racine et les deux suivantes vous permettent de nettoyer votre ancienne version de Node afin de pouvoir la reconstruire d'une manière qui fonctionnera.

cd /var/project/assets/admin
npm install
npm run build

Ces trois commandes sont les dernières dont vous aurez besoin pour créer votre build. Si toutefois vous n'avez pas encore installé vos packages, lancez la commande de la première ligne pour entrer dans l'administration et installez vos packages !

npm install @ckeditor/ckeditor5-font@34.2.0 <-- Assurez vous d'installer la bonne version en ajoutant @xx.xx.xx

Ensuite, avec npm install, vous allez récupérer et installer tous les packages présents dans votre package.json, et npm run build va créer votre propre version de Sulu avec les plugins CKEditor installés.

npm install
npm run build

Et ainsi, avec ces deux dernières commandes, votre Sulu fonctionne, si vous avez respecté les bonnes versions!