Hooks | EmDash CMS Everything

Les hooks permettent aux plugins d’exécuter du code en réponse à des événements. Tous les hooks reçoivent un objet événement et le contexte du plugin, et ils sont déclarés au moment de la définition du plugin — il n’y a pas d’enregistrement dynamique au runtime.

Cette page couvre les plugins sandboxed. Les hooks fonctionnent de manière identique dans les plugins natifs ; les plugins natifs peuvent en plus enregistrer page:fragments.

Signature du hook

Chaque handler de hook prend deux arguments :

async (event, ctx) => ReturnType;

event — données sur ce qui vient de se passer (contenu en cours de sauvegarde, médias uploadés, transition de cycle de vie, etc.)
ctx — le PluginContext avec storage, KV, logging et APIs contrôlées par capacités

satisfies SandboxedPlugin sur l’export par défaut infère event à partir du nom du hook (le type d’événement canonique complet) et ctx comme PluginContext, donc les handlers n’ont pas besoin d’annotations de paramètres. Pour référencer un type d’événement par nom dans un helper, importez-le depuis emdash/plugin.

Configuration du hook

Un hook peut être déclaré comme un handler simple ou enveloppé dans un objet de configuration :

Simple

hooks: {
	"content:afterSave": async (event, ctx) => {
		ctx.log.info("Content saved");
	},
},

Configuration complète

hooks: {
	"content:afterSave": {
		priority: 100,
		timeout: 5000,
		dependencies: ["audit-log"],
		errorPolicy: "continue",
		handler: async (event, ctx) => {
			ctx.log.info("Content saved");
		},
	},
},

Options de configuration

Option	Type	Par défaut	Description
`priority`	`number`	`100`	Ordre d’exécution. Les nombres plus bas s’exécutent en premier.
`timeout`	`number`	`5000`	Temps d’exécution maximum en millisecondes.
`dependencies`	`string[]`	`[]`	IDs de plugins qui doivent s’exécuter avant ce hook.
`errorPolicy`	`"abort" \| "continue"`	`"abort"`	Si le pipeline doit s’arrêter en cas d’erreur.
`exclusive`	`boolean`	`false`	Un seul plugin peut être le fournisseur actif. Utilisé pour `email:deliver` et `comment:moderate`.
`handler`	`function`	—	La fonction handler du hook. Requise.

Hooks de cycle de vie

S’exécutent pendant l’installation, l’activation, la désactivation et la suppression du plugin.

`plugin:install`

S’exécute une fois quand le plugin est ajouté à un site pour la première fois.

"plugin:install": async (_event, ctx) => {
	ctx.log.info("Installing plugin...");
	await ctx.kv.set("settings:enabled", true);
	await ctx.storage.items.put("default", { name: "Default Item" });
},

Événement : {} — Retourne : Promise<void>

`plugin:activate`

S’exécute quand le plugin est activé (après l’installation ou lors de la réactivation).

"plugin:activate": async (_event, ctx) => {
	ctx.log.info("Plugin activated");
},

Événement : {} — Retourne : Promise<void>

`plugin:deactivate`

S’exécute quand le plugin est désactivé (mais pas supprimé).

"plugin:deactivate": async (_event, ctx) => {
	ctx.log.info("Plugin deactivated");
},

Événement : {} — Retourne : Promise<void>

`plugin:uninstall`

S’exécute quand le plugin est supprimé d’un site.

"plugin:uninstall": async (event, ctx) => {
	ctx.log.info("Uninstalling plugin...");
	if (event.deleteData) {
		const result = await ctx.storage.items.query({ limit: 1000 });
		await ctx.storage.items.deleteMany(result.items.map((i) => i.id));
	}
},

Événement : { deleteData: boolean } — Retourne : Promise<void>

Hooks de contenu

S’exécutent lors des opérations de création, mise à jour et suppression sur le contenu du site.

`content:beforeSave`

S’exécute avant la sauvegarde du contenu. Retourne le contenu modifié, ou void pour le laisser inchangé. Lancez une exception pour annuler.

"content:beforeSave": async (event, ctx) => {
	const { content, collection } = event;

	if (collection === "posts" && !content.title) {
		throw new Error("Posts require a title");
	}

	if (typeof content.slug === "string") {
		content.slug = content.slug.toLowerCase().replace(/\s+/g, "-");
	}

	return content;
},

Événement : { content, collection, isNew } — Retourne : contenu modifié ou void.

`content:afterSave`

S’exécute après la sauvegarde réussie du contenu. Utilisez-le pour les effets de bord comme les notifications, le logging ou les synchronisations externes.

"content:afterSave": async (event, ctx) => {
	ctx.log.info(`${event.isNew ? "Created" : "Updated"} ${event.collection}/${event.content.id}`);

	if (ctx.http) {
		await ctx.http.fetch("https://api.example.com/webhook", {
			method: "POST",
			body: JSON.stringify({ event: "content:save", id: event.content.id }),
		});
	}
},

Événement : { content, collection, isNew } — Retourne : Promise<void>

`content:beforeDelete`

S’exécute avant la suppression du contenu. Retourne false pour annuler ; true ou void l’autorise.

"content:beforeDelete": async (event, ctx) => {
	if (event.collection === "pages" && event.id === "home") {
		ctx.log.warn("Cannot delete home page");
		return false;
	}
	return true;
},

Événement : { id, collection } — Retourne : boolean | void

`content:afterDelete`

S’exécute après la suppression réussie du contenu.

"content:afterDelete": async (event, ctx) => {
	await ctx.storage.cache.delete(`${event.collection}:${event.id}`);
},

Événement : { id, collection } — Retourne : Promise<void>

`content:afterPublish`

S’exécute après la promotion du contenu de brouillon à publié. Nécessite la capacité content:read.