Mods

Fichiers concernés :

• fichiers dans mods/
• available-mods.json

---

Dans le jargon d'ItsBetter, les mods sont des fonctionnalités modulables ajoutées à l'extension à l'aide de fichiers CSS et JS.

Déclaration d'un mod

Pour que le service worker de l'extension détecte le mod et l'ajoute à la liste de ceux disponibles pour l'utilisateur, celui-ci doit être déclaré dans le fichier available-mods.json.
Un mod se présente sous la forme suivante dans available-mods.json :

{
    "id": "mod-float-perso-menu",
    "title": "Menu personnel flottant",
    "desc": "Transforme le menu personnel en menu flottant et unifie son apparence",
    "frame": "main",
    "default-state": true,
    "chromium-files": ["/mods/float-perso-menu/float-perso-menu.css"],
    "firefox-files": ["/mods/float-perso-menu/float-perso-menu.css"],
    "matches": ["https://*.itslearning.com/*"],
    "version": "v1.0",
    "hidden": false
}

• id : identifiant unique utilisé par le service worker de l'extension pour identifier le mod ; il doit être de la forme mod-nom-du-mod
• title : titre du mod affiché dans le popup de l'extension
• desc : description du mod affichée dans le popup de l'extension
• frame : main pour que les fichiers du mod soient injectés dans la frame principale uniquement ou all pour qu'ils soient injectés dans toutes les frames (iframes)
• default-state : true pour que le mod soit activé par défaut quand l'utilisateur installe l'extension ou la met à jour, ou au contraire false
• chromium-files : liste des chemins des fichiers CSS et/ou JS mélangés nécessaires pour faire fonctionner le mod sur les navigateurs basés sur Chromium ; un chemin est de la forme /mods/nom-du-mod/votre-fichier
• firefox-files : liste des chemins des fichiers CSS et/ou JS mélangés nécessaires pour faire fonctionner le mod sur Firefox ; un chemin est de la forme /mods/nom-du-mod/votre-fichier

Note 1 : le / initial n'est pas obligatoire

Note 2 : les fichiers listés pour chromium-files et firefox-files peuvent être identiques si les deux types de navigateurs les font fonctionner de la même manière ; certaines fonctionnalités sont propres à chacun d'entre eux, il faudra donc dans ce cas créer un fichier pour les navigateurs basés sur Chromium et un autre pour Firefox

• Facultatif (non implémenté pour l'instant) matches : la ou les URL pour laquelle/lesquelles le mod sera appliqué
• version : la version du mod affichée dans le popup de l'extension
• hidden : true pour que le mod soit affiché dans le popup de l'extension, ou au contraire false

Création des fichiers nécessaires

Une fois que le mod est déclaré, il faut créer les fichiers CSS et/ou JS nécessaires à son fonctionnement dans le dossier mods/nom-du-mod/. Chaque fichier requis doit être ajouté à la liste correspondant à la clé chromium-files et/ou firefox-files dans available-mods.json. Attention : chaque nom de fichier doit être unique, il est donc recommandé d'utiliser le nom du mod suivi si besoin d'un suffixe.
De même, toutes les ressources nécessaires au mod (par exemple des images) doivent être stockées dans mods/nom-du-mod/. Elles ne doivent cependant pas être déclarées : seul vos fichiers CSS et/ou JS devront y accéder.

Développement d'un mod

À chaque modification du fichier available-mods.json, il est nécessaire d'actualiser l'extension dans le gestionnaire d'extensions de Chrome avec le bouton Mettre à jour.
En revanche, une actualisation de la page Itslearning suffit pour que les nouvelles modifications apparaissent lors des modifications des fichiers du mod.

Conseils

• Pour comprendre le fonctionnement interne d'Itslearning et repérer les classes/id des éléments à modifier, il est absolument nécessaire de s'aider des outils de développement fournis par Chrome (Ctrl+Maj+i).
• Les fichiers injectés ne sont pour l'instant pas prioritaires dans l'ordre de chargement des ressources par le navigateur. Il sera donc très souvent nécessaire d'ajouter !important dans les règles CSS d'un mod pour remplacer celles d'Itslearning.
• Lors de l'obtention d'éléments du DOM en JavaScript, il faut garder en tête que ceux-ci ne se trouvent pas forcément dans la frame où est injecté le fichier JS. Il peut donc être intéressant d'utiliser des structures adaptées pour éviter les erreurs dans la console, comme par exemple :

try {
    ...
} catch (e) {
    ...
}