Des règles personnalisées dans OpenEdition Checklist

| Temps de lecture : 4 min

OpenEditon Checklist est très utile pour contrôler la qualité éditoriale des livres et revues électroniques. Si sa configuration par défaut convient à la plupart des publications, il reste possible d'adapter son fonctionnement à des cas plus complexes en utilisant des règles personnalisées.

Un peu d'histoire

De 2015 à 2021, j'ai développé avec OpenEdition le plugin Checklist qui permet aux rédacteurs d'effectuer un contrôle qualité de l'ensemble de leur site Lodel. Les critères vérifiés (nommés « règles ») sont prédéfinis d'après une liste de problèmes basiques fréquemment rencontrés sur les sites.

Checklist s'inspire d'un autre outil plus ancien que j'avais conçu pour un usage interne à l'époque où je travaillais chez OpenEdition. Celui-ci était conçu pour pouvoir s'adapter à des besoins très spécifiques tout en conservant la capacité de couvrir la plupart des situations classiques.

Même si Checklist se destine clairement à une utilisation plus cadrée et homogène que son prédécesseur, il m'a semblé important d'y conserver une certaine forme de souplesse. J'ai donc veillé à ce qu'il soit possible de personnaliser son fonctionnement à plusieurs niveaux.

Fonctionnement de Checklist

Pour comprendre la suite vous aurez besoin d'une connaissance minimale de JavaScript et HTML. La bibliothèque jQuery est également utilisée.

Jetons un œil au code de Checklist. En simplifiant un peu, son chargement dans la page ressemble à ça :

<!-- Insertion de Checklist -->
<script src="checklist.js"></script>

<!-- Initialisation de Checklist -->
<script>
var config = {
// La configuration de Checklist
// ...
}
window.checklist.init(config)
.then(function () {
checklist.run();
}
.catch(console.error);
</script>

La configuration de Checklist (décrite ici) contient entre autres les éléments qu'il nous sera possible de personnaliser :

  • les variables de traduction de l'interface (propriétés langs et translations),
  • la fonction qui assure la création des boutons contextuels (buttonsCreator),
  • la définition des types de notifications (types et defaultType),
  • la définition des filtres (filters),
  • la définition des notes attribuées aux documents (ratings) et la fonction qui se charge de leur calcul (computeRating),
  • la fonction responsable de la création dynamique du contexte (context),
  • et enfin ce à quoi nous allons nous intéresser ici : la définition des règles (rules).

Ajouter une règle personnalisée

Lorsque la fonction checklist.init est exécutée, elle vérifie d'abord que la variable checklistUserConfig existe dans le contexte global. Le cas échéant elle la fusionne avec la configuration par défaut.

Il est ainsi possible de surcharger la configuration par défaut du plugin en ajoutant un script avant l'appel de cette fonction (qui a lieu à la fin du <body>).

On peut par exemple insérer le script suivant à la fin du <head> de la page :

window.checklistUserConfig = {
rules: [
{
id: "lipogramme-en-z",
name: {
fr: "Paragraphe(s) contenant un z.",
},
description: {
fr: "<p>Un ou plusieurs paragraphes du texte contiennent la lettre z, ce qui est gênant si vous souhaitez écrire un lipogramme.</p>",
},
condition: "textes",
type: "warning",
displayCount: true,
action: function ($) {
var fieldName = "texte";
var $p = $("[data-field='texte'] .ckl-field-value p");

var $bad = $p.filter(function () {
return $(this).text().indexOf("z") > -1;
});

var marker = {
name: {
fr: "Lettre z",
},
target: $bad,
position: "prepend",
highlight: false,
};

this.resolve($bad.length, marker);
},
},
],
};

Ce morceau de code déclare une règle qui détectera la présence de la lettre « z » dans les paragraphes du champ « texte » des articles. Cette nouvelle fonction sera exécutée en plus des règles habituelles.

Copie d'écran d'une règle personnalisée dans Checklist

La syntaxe des règles est décrite dans la documentation de Checklist. Les règles par défaut distribuées avec le plugin peuvent également servir d'exemple pour en écrire de nouvelles.

Utilisation côté client

Comment faire à présent si nous n'avons pas la possibilité de modifier directement la maquette de Checklist sur le serveur ? C'est par exemple le cas si notre revue est hébergée sur OpenEditon Journals.

L'idée est d'exécuter le même script directement dans notre navigateur plutôt que depuis le serveur. Il faut pour cela installer l'extension de navigateur Tampermonkey et y créer le script utilisateur suivant :

// ==UserScript==
// @name Personnalisation de Checklist
// @namespace https://brrd.fr
// @version 0.1
// @description Ce script ajoute une nouvelle règle à Checklist.
// @author Thomas
// @match https://journals.openedition.org/*/?do=_checklist_view*
// @grant none
// @run-at document-start
// ==/UserScript==

(function () {
"use strict";

window.checklistUserConfig = {
rules: [
{
id: "lipogramme-en-z",
name: {
fr: "Paragraphe avec un z.",
},
description: {
fr: "<p>Un ou plusieurs paragraphes du texte contiennent la lettre z, ce qui est gênant si vous souhaitez écrire un lipogramme.</p>",
},
condition: "textes",
type: "warning",
displayCount: true,
action: function ($) {
var fieldName = "texte";
var $p = $("[data-field='texte'] .ckl-field-value p");

var $bad = $p.filter(function () {
return $(this).text().indexOf("z") > -1;
});

var marker = {
name: {
fr: "Lettre z",
},
target: $bad,
position: "prepend",
highlight: false,
};

this.resolve($bad.length, marker);
},
},
],
};
})();

Ici le code de la règle elle-même n'a pas changé. Seul l'enrobage a été modifié par rapport à l'exemple précédent pour correspondre aux prérequis de Tampermonkey.

Notons la présence de deux lignes importantes dans l'en-tête du script :

  • L'instruction @match https://journals.openedition.org/*/?do=_checklist_view* indique que le script s'exécutera pour tous les sites du domaine journals.openedition.org. Si vous souhaitez limiter l'exécution à un seul site, il faudra le préciser dans l'URL à la place du premier astérisque.
  • L'instruction @run-at document-start est nécessaire pour que le script soit exécuté avant l'initialisation de Checklist, ce qui est indispensable comme nous l'avons déjà vu.

Pour comprendre les autres lignes de l'en-tête, n'hésitez pas à consulter la documentation de Tampermonkey.

Attention ! Tampermonkey s'exécute uniquement dans votre navigateur. Par conséquent votre code peut entraîner des comportements qui seront indétectables pour les administrateurs de votre site. N'oubliez pas de désactiver ces scripts quand vous ne les utilisez plus.

Et voilà !

Vous avez écrit votre première règle personnalisée pour Checklist.

Notez que cette méthode n'est pas limitée aux règles : elle rend possible la modification de n'importe quel élément de la configuration de Checklist, comme les traductions, les menus contextuels, les notes… De quoi étendre Checklist pour en faire un outil totalement adapté à vos priorités éditoriales.