Référence des Hooks

Les hooks permettent aux plugins d’intercepter et de modifier le comportement d’EmDash à des points spécifiques du cycle de vie du contenu, des médias, des e-mails, des commentaires et des pages.

Aperçu des hooks

Le tableau suivant liste chaque hook, ce qui le déclenche, ce qu’il peut modifier et s’il est exclusif :

Hooks de contenu

content:beforeSave

S’exécute avant la sauvegarde du contenu dans la base de données. Utilisez-le pour valider, transformer ou enrichir le contenu.

import { definePlugin } from "emdash";

export default definePlugin({
	id: "my-plugin",
	version: "1.0.0",
	hooks: {
		"content:beforeSave": async (event, ctx) => {
			const { content, collection, isNew } = event;

			// Ajouter des horodatages
			if (isNew) {
				content.createdBy = "system";
			}
			content.modifiedAt = new Date().toISOString();

			// Retourner le contenu modifié
			return content;
		},
	},
});

Event

interface ContentHookEvent {
	content: Record<string, unknown>; // Données de contenu
	collection: string; // Slug de collection
	isNew: boolean; // True pour création, false pour mise à jour
}

Valeur de retour

• Retourner l’objet de contenu modifié pour appliquer les changements
• Retourner void pour passer sans modification

content:afterSave

S’exécute après la sauvegarde du contenu. Utilisez-le pour les effets de bord comme les notifications, l’invalidation du cache ou la synchronisation externe.

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

    if (collection === "posts" && content.status === "published") {
      // Notifier le service externe
      await ctx.http?.fetch("https://api.example.com/notify", {
        method: "POST",
        body: JSON.stringify({ postId: content.id }),
      });
    }
  },
}

Valeur de retour

Aucune valeur de retour attendue.

content:beforeDelete

S’exécute avant la suppression du contenu. Utilisez-le pour valider ou empêcher la suppression.

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

    // Empêcher la suppression de contenu protégé
    const item = await ctx.content?.get(collection, id);
    if (item?.data.protected) {
      return false; // Annuler la suppression
    }

    // Autoriser la suppression
    return true;
  },
}

Event

interface ContentDeleteEvent {
	id: string; // ID de l'entrée
	collection: string; // Slug de collection
}

Valeur de retour

• Retourner false pour annuler la suppression
• Retourner true ou void pour autoriser

content:afterDelete

S’exécute après la suppression du contenu. Utilisez-le pour les tâches de nettoyage.

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

    // Nettoyer les données associées
    await ctx.storage.relatedItems.delete(`${collection}:${id}`);
  },
}

content:afterRestore

S’exécute après la restauration de contenu supprimé. Nécessite la capacité content:read.

hooks: {
  "content:afterRestore": async (event, ctx) => {
    ctx.log.info(`Restored ${event.collection}/${event.content.id}`);
  },
}

content:afterSchedule

S’exécute après la planification de contenu pour publication future. Nécessite la capacité content:read.

hooks: {
  "content:afterSchedule": async (event, ctx) => {
    ctx.log.info(`Scheduled ${event.collection}/${event.content.id}`);
  },
}

content:afterUnschedule

S’exécute après la déplanification de contenu planifié. Nécessite la capacité content:read.

hooks: {
  "content:afterUnschedule": async (event, ctx) => {
    ctx.log.info(`Unscheduled ${event.collection}/${event.content.id}`);
  },
}

Event

interface ContentStateChangeEvent {
	content: Record<string, unknown>;
	collection: string;
}

Valeur de retour

Aucune valeur de retour attendue.

Hooks de médias

media:beforeUpload

S’exécute avant le téléversement d’un fichier. Utilisez-le pour valider, renommer ou rejeter des fichiers.

hooks: {
  "media:beforeUpload": async (event, ctx) => {
    const { file } = event;

    // Rejeter les fichiers de plus de 10Mo
    if (file.size > 10 * 1024 * 1024) {
      throw new Error("File too large");
    }

    // Renommer le fichier
    return {
      name: `${Date.now()}-${file.name}`,
      type: file.type,
      size: file.size,
    };
  },
}

Event

interface MediaUploadEvent {
	file: {
		name: string; // Nom de fichier original
		type: string; // Type MIME
		size: number; // Taille en octets
	};
}

Valeur de retour

• Retourner les métadonnées de fichier modifiées pour appliquer les changements
• Retourner void pour passer sans modification
• Lever une erreur pour rejeter le téléversement

media:afterUpload

S’exécute après le téléversement d’un fichier. Utilisez-le pour le traitement, les miniatures ou l’extraction de métadonnées.

hooks: {
  "media:afterUpload": async (event, ctx) => {
    const { media } = event;

    if (media.mimeType.startsWith("image/")) {
      // Stocker les métadonnées d'image
      await ctx.kv.set(`media:${media.id}:analyzed`, {
        processedAt: new Date().toISOString(),
      });
    }
  },
}

Event

interface MediaAfterUploadEvent {
	media: {
		id: string;
		filename: string;
		mimeType: string;
		size: number | null;
		url: string;
		createdAt: string;
	};
}

Hooks de cycle de vie

plugin:install

S’exécute lors de la première installation d’un plugin. Utilisez-le pour la configuration initiale, la création de collections de stockage ou l’initialisation de données.

hooks: {
  "plugin:install": async (event, ctx) => {
    // Initialiser les paramètres par défaut
    await ctx.kv.set("settings:enabled", true);
    await ctx.kv.set("settings:threshold", 100);

    ctx.log.info("Plugin installed successfully");
  },
}

plugin:activate

S’exécute quand un plugin est activé (après installation ou réactivation).

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

plugin:deactivate

S’exécute quand un plugin est désactivé.

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

plugin:uninstall

S’exécute quand un plugin est supprimé. Utilisez-le pour le nettoyage.

hooks: {
  "plugin:uninstall": async (event, ctx) => {
    const { deleteData } = event;

    if (deleteData) {
      // Nettoyer toutes les données du plugin
      const items = await ctx.kv.list("settings:");
      for (const { key } of items) {
        await ctx.kv.delete(key);
      }
    }

    ctx.log.info("Plugin uninstalled");
  },
}

Event

interface UninstallEvent {
	deleteData: boolean; // L'utilisateur a choisi de supprimer les données
}

Hook Cron

cron

Se déclenche quand une tâche planifiée s’exécute. Planifiez des tâches avec ctx.cron.schedule().

hooks: {
  "cron": async (event, ctx) => {
    if (event.name === "daily-sync") {
      const data = await ctx.http?.fetch("https://api.example.com/data");
      ctx.log.info("Sync complete");
    }
  },
}

Event

interface CronEvent {
	name: string;
	data?: Record<string, unknown>;
	scheduledAt: string;
}

Hooks d’e-mail

Les hooks d’e-mail s’exécutent dans l’ordre : email:beforeSend, puis email:deliver, puis email:afterSend.

email:beforeSend

Capacité : hooks.email-events:register

Hook middleware qui s’exécute avant la livraison. Transformer les messages ou annuler la livraison.

hooks: {
  "email:beforeSend": async (event, ctx) => {
    // Ajouter un pied de page à tous les e-mails
    return {
      ...event.message,
      text: event.message.text + "\n\n—Sent from My Site",
    };

    // Ou retourner false pour annuler la livraison
  },
}

Event

interface EmailBeforeSendEvent {
	message: { to: string; subject: string; text: string; html?: string };
	source: string;
}

Valeur de retour

• Retourner le message modifié pour transformer
• Retourner false pour annuler la livraison
• Retourner void pour passer sans modification

email:deliver

Capacité : hooks.email-transport:register | Exclusif : Oui

Le fournisseur de transport. Un seul plugin peut livrer les e-mails. Responsable de l’envoi effectif du message via un service d’e-mail.

hooks: {
  "email:deliver": {
    exclusive: true,
    handler: async (event, ctx) => {
      await sendViaSES(event.message);
    },
  },
}

email:afterSend

Capacité : hooks.email-events:register

Hook fire-and-forget après livraison réussie. Les erreurs sont journalisées mais ne se propagent pas.

hooks: {
  "email:afterSend": async (event, ctx) => {
    await ctx.kv.set(`email:log:${Date.now()}`, {
      to: event.message.to,
      subject: event.message.subject,
    });
  },
}

Hooks de commentaires

Les hooks de commentaires s’exécutent dans l’ordre : comment:beforeCreate, puis comment:moderate, puis comment:afterCreate. Le hook comment:afterModerate se déclenche séparément quand un administrateur change le statut d’un commentaire.

comment:beforeCreate

Capacité : users:read

Hook middleware avant le stockage d’un commentaire. Enrichir, valider ou rejeter des commentaires.

hooks: {
  "comment:beforeCreate": async (event, ctx) => {
    // Rejeter les commentaires avec des liens
    if (event.comment.body.includes("http")) {
      return false;
    }
  },
}

Event

interface CommentBeforeCreateEvent {
	comment: {
		collection: string;
		contentId: string;
		parentId: string | null;
		authorName: string;
		authorEmail: string;
		authorUserId: string | null;
		body: string;
		ipHash: string | null;
		userAgent: string | null;
	};
	metadata: Record<string, unknown>;
}

Valeur de retour

• Retourner l’événement modifié pour transformer
• Retourner false pour rejeter
• Retourner void pour passer sans modification

comment:moderate

Capacité : users:read | Exclusif : Oui

Décide si un commentaire est approuvé, en attente ou spam. Un seul fournisseur de modération est actif.

hooks: {
  "comment:moderate": {
    exclusive: true,
    handler: async (event, ctx) => {
      const score = await checkSpam(event.comment);
      return {
        status: score > 0.8 ? "spam" : score > 0.5 ? "pending" : "approved",
        reason: `Spam score: ${score}`,
      };
    },
  },
}

Event

interface CommentModerateEvent {
	comment: { /* identique à beforeCreate */ };
	metadata: Record<string, unknown>;
	collectionSettings: {
		commentsEnabled: boolean;
		commentsModeration: "all" | "first_time" | "none";
		commentsClosedAfterDays: number;
		commentsAutoApproveUsers: boolean;
	};
	priorApprovedCount: number;
}

Valeur de retour

{ status: "approved" | "pending" | "spam"; reason?: string }

comment:afterCreate

Capacité : users:read

Hook fire-and-forget après le stockage d’un commentaire. Utilisez-le pour les notifications.

hooks: {
  "comment:afterCreate": async (event, ctx) => {
    if (event.comment.status === "approved") {
      await ctx.email?.send({
        to: event.contentAuthor?.email,
        subject: `New comment on "${event.content.title}"`,
        text: `${event.comment.authorName} commented: ${event.comment.body}`,
      });
    }
  },
}

comment:afterModerate

Capacité : users:read

Hook fire-and-forget quand un administrateur change manuellement le statut d’un commentaire.

Event

interface CommentAfterModerateEvent {
	comment: { id: string; /* ... */ };
	previousStatus: string;
	newStatus: string;
	moderator: { id: string; name: string | null };
}

Hooks de page

Les hooks de page s’exécutent lors du rendu des pages publiques. Ils permettent aux plugins d’injecter des métadonnées et des scripts.

page:metadata

Capacité : Aucune requise

Contribuer des meta tags, des propriétés Open Graph, des données structurées JSON-LD ou des link tags au head de la page.

hooks: {
  "page:metadata": async (event, ctx) => {
    return [
      { kind: "meta", name: "generator", content: "EmDash" },
      { kind: "property", property: "og:site_name", content: event.page.siteName },
      { kind: "jsonld", graph: { "@type": "WebSite", name: event.page.siteName } },
    ];
  },
}

Types de contribution

type PageMetadataContribution =
	| { kind: "meta"; name: string; content: string; key?: string }
	| { kind: "property"; property: string; content: string; key?: string }
	| {
			kind: "link";
			rel: "canonical" | "alternate" | "author" | "license" | "nlweb" | "site.standard.document";
			href: string;
			hreflang?: string;
			key?: string;
	  }
	| {
			kind: "jsonld";
			id?: string;
			graph: Record<string, unknown> | Array<Record<string, unknown>>;
	  };

Le champ key déduplique les contributions — seule la dernière contribution avec un key donné est utilisée.

page:fragments

Capacité : hooks.page-fragments:register

Injecter des scripts ou du HTML dans les pages. Disponible uniquement pour les plugins natifs.

hooks: {
  "page:fragments": async (event, ctx) => {
    return [
      {
        kind: "external-script",
        placement: "body:end",
        src: "https://analytics.example.com/script.js",
        async: true,
      },
      {
        kind: "inline-script",
        placement: "head",
        code: `window.siteId = "abc123";`,
      },
    ];
  },
}

Types de contribution

type PageFragmentContribution =
	| {
			kind: "external-script";
			placement: "head" | "body:start" | "body:end";
			src: string;
			async?: boolean;
			defer?: boolean;
			attributes?: Record<string, string>;
			key?: string;
		}
	| {
			kind: "inline-script";
			placement: "head" | "body:start" | "body:end";
			code: string;
			attributes?: Record<string, string>;
			key?: string;
		}
	| {
			kind: "html";
			placement: "head" | "body:start" | "body:end";
			html: string;
			key?: string;
		};

Configuration des hooks

Les hooks acceptent soit une fonction handler soit un objet de configuration :

hooks: {
  // Handler simple
  "content:afterSave": async (event, ctx) => { ... },

  // Avec configuration
  "content:beforeSave": {
    priority: 50,        // Les valeurs basses s'exécutent en premier (défaut : 100)
    timeout: 10000,      // Temps d'exécution max en ms (défaut : 5000)
    dependencies: [],    // S'exécuter après ces plugins
    errorPolicy: "abort", // "continue" ou "abort" (défaut)
    handler: async (event, ctx) => { ... },
  },
}

Options de configuration

Contexte du plugin

Tous les hooks reçoivent un objet de contexte avec accès aux APIs du plugin :

interface PluginContext {
	plugin: { id: string; version: string };
	storage: PluginStorage;
	kv: KVAccess;
	content?: ContentAccess;
	media?: MediaAccess;
	http?: HttpAccess;
	log: LogAccess;
	site: { name: string; url: string; locale: string };
	url(path: string): string;
	users?: UserAccess;
	cron?: CronAccess;
	email?: EmailAccess;
}

Voir Aperçu des plugins — Contexte du plugin pour les exigences de capacités et les détails des méthodes.

Gestion des erreurs

Les erreurs dans les hooks sont journalisées et gérées selon errorPolicy :

• "abort" (défaut) — Arrêter l’exécution, annuler la transaction si applicable
• "continue" — Journaliser l’erreur et continuer au hook suivant

hooks: {
  "content:beforeSave": {
    errorPolicy: "continue", // Ne pas bloquer la sauvegarde si ceci échoue
    handler: async (event, ctx) => {
      try {
        await ctx.http?.fetch("https://api.example.com/validate");
      } catch (error) {
        ctx.log.warn("Validation service unavailable", error);
      }
    },
  },
}

Ordre d’exécution

Les hooks s’exécutent dans cet ordre :

1. Triés par priority (ascendant)
2. Les plugins avec dependencies s’exécutent après leurs dépendances
3. À même priorité, l’ordre est déterministe mais non spécifié

// Ceci s'exécute en premier (priorité 10)
{ priority: 10, handler: ... }

// Ceci s'exécute en deuxième (priorité 50)
{ priority: 50, handler: ... }

// Ceci s'exécute en dernier (priorité par défaut 100)
{ handler: ... }