Comment créer un plugin pour ParoiCMS ?

Les plugins ParoiCMS servent à étendre les fonctionnalités du CMS. Ils permettent de créer des templates utilisables depuis le thème, des utilitaires JavaScript pour la partie publique du site web, des API, des parties de schéma de sites, et des composants qui s'ajouteront dans l'espace d'administration.

Techniquement, un plugin est un package Node.js. Créer un plugin pour ParoiCMS demande donc une connaissance de Node.js et du langage JavaScript ou TypeScript.

Il est possible de publier son propre package sur un registre NPM, mais on peut aussi choisir de garder son package privé à l'intérieur d'un site web. C'est ce que nous ferons dans ce tutoriel.

Avant toute chose, il faut un site web qui tourne en local sur votre ordinateur. Si vous n'en avez pas déjà un, suivez les instructions.

Créer un plugin

La localisation du package d'un plugin est complètement libre. Vous pouvez le mettre où cela vous arrange. Pour notre exemple, nous allons simplement créer un dossier plugins dans le dossier du site web, puis nous y mettrons notre plugin.

Voici la hiérarchie des dossiers et des fichiers à créer :

Et voici comment faire :

Créer un dossier plugins dans le dossier du site web.
Dans le dossier plugins, créer un dossier fork-or-knife-plugin.
À l'intérieur du dossier fork-or-knife-plugin, créer un fichier package.json avec le contenu suivant :

{
  "name": "fork-or-knife-plugin",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "build": "npm run build:backend",
    "build:backend": "(cd backend && tsc)"
  },
  "dependencies": {
    "@paroi/data-formatters-lib": "~0.4.0"
  },
  "peerDependencies": {
    "@paroicms/public-anywhere-lib": "0",
    "@paroicms/public-server-lib": "0"
  },
  "devDependencies": {
    "@paroicms/public-anywhere-lib": "~0.6.0",
    "@paroicms/public-server-lib": "~0.12.3",
    "@types/node": "~20.14.8",
    "typescript": "~5.5.4"
  },
  "main": "backend/dist/plugin.js"
}

Dans le dossier fork-or-knife-plugin, créez un sous-dossier backend. Ajoutez dedans un fichier tsconfig.json, dont le contenu est :

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "CommonJS",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "outDir": "dist"
  },
  "include": ["src"]
}

Toujours, à l'intérieur du dossier backend, créer un dossier src avec dedans un fichier plugin.ts à créer :

import { strVal } from "@paroi/data-formatters-lib";
import type { ParoiCmsPlugin } from "@paroicms/public-server-lib";
import { dirname, join } from "node:path";

const projectDir = dirname(__dirname);
const packageDir = dirname(projectDir);
const version = strVal(require(join(packageDir, "package.json")).version);

const plugin: ParoiCmsPlugin = {
  version,
  siteInit(service) {
    console.log("fork-or-knife plugin is initialized...");
  },
};

export default plugin;

Il est temps de compiler le plugin :

cd plugins/fork-or-knife-plugin/
npm i
npm run build

Si la compilation s'est bien passée, un fichier plugins/fork-or-knife-plugin/backend/dist/plugin.js vient d'être généré.

Ce tout premier plugin ne fera pas grand chose, mais il est prêt à être utilisé.

Enregistrer le plugin dans le site web

Éditer le fichier package.json du site web. Dans la section "dependencies", ajouter :

    "fork-or-knife-plugin": "file:plugins/fork-or-knife-plugin"

Remarque : On utilise ici le chemin local vers le package de notre plugin.

Éditer le fichier site-schema.json. Dans la liste des "plugins", ajouter Le nom du plugin : "fork-or-knife-plugin". Ce nom doit correspondre à celui donné dans le package.json du plugin. Et il doit aussi correspondre au nom du package ajouté juste au-dessus dans les dépendances du package.json du site.

Si le serveur de votre site web est lancé, mieux vaut l'interrompre. Comme nous avons ajouté une dépendance, il faut relancer l'installation des dépendances :

npm i

Le serveur peut être redémarré :

npm run dev

Si le redémarrage s'est bien passé, alors affichez une page web du site local dans votre navigateur afin de charger le site. Dans le terminal, vous devriez voir apparaître :

[node] fork-or-knife plugin is initialized...
[node] [2024-08-15 19:44:06.566] INFO: Site loaded ↗

Le message "fork-or-knife plugin is initialized..." contenu dans le code de notre plugin apparaît, ce qui signifie que notre plugin est bien initialisé.

Dans les prochains tutoriels, nous verrons ce qu'il est possible de faire avec un plugin.