Comment intégrer PrismJS dans un RichText eZ Platform pour y ajouter un / des style(s) spécifique(s) ?

En tant qu’agence web, nous avons donc été amenés à réfléchir aux fonctionnalités à développer sur notre propre site; l’un des principaux constats que nous avons fait était que nous ne pouvions pas réellement partager nos compétences en matière de code avec la communauté des développeurs.

En effet, il n’y a pas de fonctionnalité prévue pour coller du code dans le back-office et qu’il apparaisse parfaitement stylisé en front-office.

Nous nous sommes donc lancés dans la création d’un custom text style permettant de coller du code de plusieurs langages dans le richText d’eZ Platform, et d’avoir un joli résultat côté front-office ! Nous partageons maintenant ce tutoriel avec vous.

Créer des ‘custom text styles’ sur eZ Platform.

Configurer le back-office pour ajouter un ‘custom text style’.

Tout d’abord, commencez par créer un fichier Yaml custom_styles.yml dans le répertoire app/Resources/config de votre projet, permettant de déclarer la configuration de votre / vos custom styles.

Il existe deux types de custom styles : block et inline, qui comme leur nom l'indique, affichent le style choisi sur la totalité du bloc sélectionné ou simplement sur le texte sélectionné dans un bloc.

Dans notre cas, le but était de pouvoir coller des blocs de code dans les langages Javascript, PHP, HTML, CSS, Sass, Twig, JSON et Yaml.

Nous avons donc déclaré un custom style de type block pour chacun de ces langages.

        ezpublish:
    system:
        admin_group:
            fieldtypes:
                ezrichtext:
                    custom_styles: [javascript_block, php_block, html_block, css_block, sass_block, twig_block, json_block, yaml_block]

ezrichtext:
    custom_styles:
        javascript_block:
            template: '@App/field_type/ezrichtext/custom_style/codebox.html.twig'
            inline: false
        php_block:
            template: '@App/field_type/ezrichtext/custom_style/codebox.html.twig'
            inline: false
        html_block:
            template: '@App/field_type/ezrichtext/custom_style/codebox.html.twig'
            inline: false
        css_block:
            template: '@App/field_type/ezrichtext/custom_style/codebox.html.twig'
            inline: false
        sass_block:
            template: '@App/field_type/ezrichtext/custom_style/codebox.html.twig'
            inline: false
        twig_block:
            template: '@App/field_type/ezrichtext/custom_style/codebox.html.twig'
            inline: false
        json_block:
            template: '@App/field_type/ezrichtext/custom_style/codebox.html.twig'
            inline: false
        yaml_block:
            template: '@App/field_type/ezrichtext/custom_style/codebox.html.twig'
            inline: false
    

On définit la liste des custom styles à référencer dans l’éditeur de texte en fonction du site access, puis on déclare chacun d’entre eux en indiquant le template qui lui correspond et s’il s’agit d’un custom style inline ou block.

Déclarer les différents libellés des custom text styles dans un fichier de traduction.

Pour afficher un libellé pertinent sur chacun de nos custom text styles en back-office, nous devons créer un / plusieurs fichiers de traduction (à vous de voir dans quel(s) langage(s) est traduit votre site web), en utilisant le système de traduction de Symfony.

Les traductions liées aux custom styles doivent être déclarées dans un fichier custom_styles.la_langue_choisie.yml dans le répertoire app/Resources/translations.

Voici à quoi doit ressembler le fichier de traduction de nos custom styles :

        ezrichtext.custom_styles.javascript_block.label: Code Javascript
ezrichtext.custom_styles.php_block.label: Code PHP
ezrichtext.custom_styles.html_block.label: Code HTML
ezrichtext.custom_styles.css_block.label: Code CSS
ezrichtext.custom_styles.sass_block.label: Code Sass
ezrichtext.custom_styles.twig_block.label: Code Twig
ezrichtext.custom_styles.json_block.label: Code JSON
ezrichtext.custom_styles.yaml_block.label: Code Yaml
    

Créer un template pour les custom text styles.

Il est maintenant temps de créer un template Twig pour nos custom styles.

Dans notre cas, un seul suffira, mais vous pouvez être amenés à créer des custom styles différents et donc à devoir en créer plusieurs en fonction de vos besoin.

Comme vous avez pu le lire ci-dessus, le nôtre s’appellera codebox.html.twig. 

        {# Custom code template #}
<pre>
    <code>
        {{ content|replace({'<pre>': '', '</pre>': ''})|trim|raw }}
    </code>
</pre>
    

Nous ouvrons des balises <pre> et <code> dans lesquelles nous plaçons le contenu de notre bloc, en veillant à bien supprimer d’abord les potentielles balises <pre> déjà présentes lors du copier / coller depuis un IDE / éditeur de code.

En soit on pourrait s’en arrêter là, mais le code collé ne serait pas stylisé et donc pas vraiment agréable à lire.

Customiser le rendu du template.

eZ Platform, tout comme Symfony, utilise le module bundler Webpack Encore pour gérer les dépendances à mettre en place sur un projet web. Combiné à Yarn, ils permettent de compiler les fichiers Sass et JS de tout le projet en fichiers minimisés. 

Pour customiser le rendu de nos custom styles dans le contenu de nos pages (des couleurs et des indentations différentes en fonction du langage écrit dans le bloc), nous avons choisi d’utiliser la librairie PrismJS, qui fait très bien le travail.

Elle fonctionne de manière assez simple, puisqu’il suffit d’ajouter une class CSS sur les balises qui contiennent du code, en spécifiant le langage voulu. 

Installer Prism JS

Nous ajoutons donc PrismJS en tant que dépendance du projet via Yarn :

        yarn add prismjs
    

Puis nous appelons les différents fichiers Sass et JS de la librairie dont nous avons besoin dans notre projet. Nous souhaitons pouvoir utiliser ces customs blocs sur tous les types de contenus du site, donc on utilise :

• Le fichier app.scss pour appeler les fichiers Sass :

        @import "~prismjs/themes/prism-tomorrow.css";
@import "~prismjs/plugins/line-numbers/prism-line-numbers.css";
    

• Le fichierapp.js pour appeler les fichiers JS :

        // Loads the prismjs package
require('prismjs');
// Loads the plugin to normalize whitespace
require('prismjs/plugins/normalize-whitespace/prism-normalize-whitespace');
// Constant loading the dependencies
const getLoader = require('prismjs/dependencies');
// Constant loading the components
const components = require('prismjs/components');

// Constants for the components to load : 
const componentsToLoad = ['twig', 'css', 'css-extras', 'scss', 'php', 'php-extras', 'json', 'yml', 'html'];
const loadedComponents = ['clike', 'markup-templating', 'javascript'];

const loader = getLoader(components, componentsToLoad, loadedComponents);
loader.load(id => {
    require(`prismjs/components/prism-${id}.min.js`);
});
    

Nous générons nos fichiers CSS et JS via la commande :

        yarn encore production
    

Dans notre fichier twig de basepagelayout.html.twig, nous appelons les deux fichiers minimisés correspondant à app.js et  app.scss (dans notre cas, ces fichiers se compilent en app.js et global.css).

Déclaration du fichier de style  global.css dans la balise <head>:

        {{ encore_entry_link_tags('global') }}
    

Déclaration du fichier de script app.js à la fin de la balise <body>:

        {{ encore_entry_script_tags('app') }}
    

Mettre à jour le template codebox.html.twig

Maintenant que nous avons ajouté la librairie, nous pouvons mettre à jour notre template codebox.html.twig afin d’ajouter les class CSS spécifiques pour chaque langage.

Nous déclarons donc une variable correspondant qui change en fonction du nom du custom style sélectionné :

        {% set prismBlockClass = '' %}

{% if name == 'javascript_block' %}
    {% set prismBlockClass = 'language-javascript' %}
{% elseif name == 'html_block' %}
    {% set prismBlockClass = 'language-html' %}
{% elseif name == 'css_block' %}
    {% set prismBlockClass = 'language-css' %}
{% elseif name == 'sass_block' %}
    {% set prismBlockClass = 'language-scss' %}
{% elseif name == 'twig_block' %}
    {% set prismBlockClass = 'language-twig' %}
{% elseif name == 'yaml_block' %}
    {% set prismBlockClass = 'language-yml' %}
{% elseif name == 'json_block' %}
    {% set prismBlockClass = 'language-json' %}
{% elseif name == 'php_block' %}
    {% set prismBlockClass = 'language-php' %}
{% endif %}

<pre class=" {{ prismBlockClass }}">
    <code class="{{ prismBlockClass }}">
        {{ content|replace({'<pre>': '', '</pre>': ''})|trim|raw }}
    </code>
</pre>
    

Et voilà, Il ne vous suffit plus qu’à vous rendre dans votre back-office, à copier du code depuis votre éditeur de code / IDE habituel et à le coller dans l’éditeur de texte eZ, en choisissant de quel type de code il s’agit !