Hooks | EmDash CMS Everything

Mit Hooks können Plugins Code als Reaktion auf Ereignisse ausführen. Alle Hooks erhalten ein Ereignisobjekt und den Plugin-Kontext, und sie werden zum Zeitpunkt der Plugin-Definition deklariert – es gibt keine dynamische Registrierung zur Laufzeit.

Diese Seite behandelt sandboxed Plugins. Native Plugins verwenden dieselben Hook-Namen und Ereignistypen, nutzen aber die In-Process-Hook-Pipeline und können zusätzlich page:fragments registrieren. Das Ablehnen von Speichervorgängen in der Sandbox und das Fehlerverhalten isolierter Runner werden weiter unten beschrieben.

Hook-Signatur

Jeder Hook-Handler nimmt zwei Argumente entgegen:

async (event, ctx) => ReturnType;

event — Daten darüber, was gerade passiert ist (gespeicherter Inhalt, hochgeladene Medien, Lebenszyklusübergang usw.)
ctx — der PluginContext mit Speicher, KV, Logging und durch Capabilities abgesicherten APIs

Wenn Sie die Definition einer Konstante vom Typ SandboxedPlugin zuweisen, wird event aus dem Hook-Namen abgeleitet (der vollständige kanonische Ereignistyp) und ctx als PluginContext, sodass Handler keine Parameter-Annotationen benötigen. Exportieren Sie diese Konstante als Default-Export. Um einen Ereignistyp in einer Hilfsfunktion namentlich zu referenzieren, importieren Sie ihn aus emdash/plugin.

Hook-Konfiguration

Ein Hook kann als reiner Handler deklariert oder in ein Konfigurationsobjekt eingewickelt werden. Bevorzugen Sie die reine Form, es sei denn, das Plugin unterstützt zusätzlich gezielt die Ausführung im selben Prozess und benötigt die unten beschriebenen Metadaten.

Einfach

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

Vollständige Konfiguration

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

Konfigurationsoptionen

Option	Typ	Standard	Beschreibung
`priority`	`number`	`100`	Ausführungsreihenfolge. Niedrigere Zahlen werden zuerst ausgeführt.
`timeout`	`number`	`5000`	Maximale Ausführungszeit in Millisekunden.
`exclusive`	`boolean`	`false`	Nur ein Plugin kann der aktive Anbieter sein. Wird für `email:deliver` und `comment:moderate` verwendet.
`handler`	`function`	—	Die Hook-Handler-Funktion. Erforderlich.

Erforderliche Capabilities

Mehrere Hooks legen geschützte Daten offen oder können einen Vorgang verändern. EmDash registriert sie nur, wenn das Manifest die passende Capability deklariert:

Hooks	Capability	Grund
`content:beforeSave`	`content:write`	Der Hook kann übermittelte Inhalte ersetzen.
`content:beforePublish`, `content:beforeSchedule`, `content:beforeUnpublish`	`hooks.content-policy:register`	Die Hooks können Änderungen am Veröffentlichungsstatus ablehnen.
Andere `content:*`-Hooks	`content:read`	Ihre Ereignisse legen Inhalte offen oder identifizieren einen Eintrag.
`media:beforeUpload`	`media:write`	Der Hook kann Upload-Metadaten ersetzen oder den Upload stoppen.
`media:afterUpload`	`media:read`	Sein Ereignis legt das gespeicherte Medienelement offen.
`email:beforeSend`, `email:afterSend`	`hooks.email-events:register`	Die Hooks prüfen Ereignisse im Lebenszyklus von E-Mails.
`email:deliver`	`hooks.email-transport:register`	Der Hook wird zum Anbieter des E-Mail-Transports.
Alle `comment:*`-Hooks	`users:read`	Kommentarereignisse können Kontaktinformationen der Autoren und Anfragemetadaten enthalten.
`page:fragments`	`hooks.page-fragments:register`	Der Hook fügt Seiteninhalte erster Hand ein und ist nur nativ verfügbar.

Lebenszyklus-Hooks, cron und page:metadata haben keine Registrierungs-Capability. Deklarieren Sie die aufgeführte Capability auch dann, wenn ein Hook nur sein Ereignis liest und die passende ctx-API nicht aufruft. Die Deklaration gibt dem Betreiber eine zutreffende Einwilligungsabfrage, sichert die ctx-API ab und ist erforderlich, wenn das Plugin im selben Prozess läuft. Capabilities und Sicherheit erklärt die Auswirkung zur Laufzeit.

Lebenszyklus-Hooks

Werden bei Installation, Aktivierung, Deaktivierung und Entfernung des Plugins ausgeführt.

`plugin:install`

Wird einmalig ausgeführt, wenn das Plugin zum ersten Mal zu einer Site hinzugefügt wird.

Dieses Beispiel setzt voraus, dass das Manifest eine items-Storage-Collection deklariert:

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

Ereignis: {} — Rückgabe: Promise<void>

`plugin:activate`

Wird ausgeführt, wenn das Plugin aktiviert wird (nach der Installation oder bei erneuter Aktivierung).

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

Ereignis: {} — Rückgabe: Promise<void>

`plugin:deactivate`

Wird ausgeführt, wenn das Plugin deaktiviert (aber nicht entfernt) wird.

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

Ereignis: {} — Rückgabe: Promise<void>

`plugin:uninstall`

Wird ausgeführt, wenn das Plugin von einer Site entfernt wird.

"plugin:uninstall": async (event, ctx) => {
	ctx.log.info("Uninstalling plugin...");
	if (event.deleteData) {
		while (true) {
			const result = await ctx.storage.items.query({ limit: 100 });
			if (result.items.length === 0) break;
			await ctx.storage.items.deleteMany(result.items.map((item) => item.id));
		}
	}
},

Ereignis: { deleteData: boolean } — Rückgabe: Promise<void>

Inhalts-Hooks

Werden bei Erstellungs-, Aktualisierungs- und Löschvorgängen an Site-Inhalten ausgeführt.

`content:beforeSave`

Wird ausgeführt, bevor Inhalte gespeichert werden. Geben Sie geänderte Inhalte, ein Sandbox-Hook-Fehlerergebnis oder void zurück, um sie unverändert zu lassen.

Um einen Speichervorgang aus der Sandbox heraus abzulehnen, geben Sie ein versioniertes Hook-Ergebnis mit einem SAVE_REJECTED-Fehler zurück. Setzen Sie reason auf reinen Text mit 1 bis 500 Zeichen. EmDash identifiziert das Plugin und zeigt dem Redakteur den Grund an. Leere, zu lange, fehlerhafte und unbekannte Fehlerergebnisse lassen den Speichervorgang mit einem generischen Hook-Fehler scheitern.

"content:beforeSave": async (event, ctx) => {
	const { content } = event;
	if (typeof content.title !== "string" || content.title.trim() === "") {
		return {
			__emdashSandboxHookResult: true,
			version: 1,
			error: {
				code: "SAVE_REJECTED",
				reason: "Add a title before saving.",
			},
		};
	}

	content.title = content.title.trim();

	return content;
},

Fügen Sie kein HTML in reason ein. Der Admin rendert den Wert als Text.

Im Host-Prozess werfen Sie stattdessen ContentSaveRejectedError (exportiert aus emdash). Die API gibt SAVE_REJECTED mit Ihrer Nachricht zurück. Jede andere Ausnahme lässt den Speichervorgang in beiden Ausführungsmodi mit einer generischen CONTENT_HOOK_ERROR-Antwort scheitern.

Ereignis: { content, collection, isNew, id, actor } — Rückgabe: geänderte Inhalte, ein Sandbox-Hook-Fehlerergebnis oder void. Bei einer Aktualisierung ist id die ID des vorhandenen Elements, und content enthält nur die übermittelten Feldwerte; laden Sie das gespeicherte Element mit ctx.content.get(event.collection, event.id). Der Slug des Eintrags ist nicht Teil von content, und ein vom Hook zurückgegebener slug-Schlüssel scheitert an der Validierung als unbekanntes Feld. Authentifizierte REST-, Visual-Editing- und MCP-Speichervorgänge enthalten actor.id und die numerische actor.role. Interne Schreibvorgänge ohne authentifizierten Benutzer lassen actor weg.

`content:afterSave`

Wird ausgeführt, nachdem Inhalte erfolgreich gespeichert wurden. Verwenden Sie ihn für Nebeneffekte wie Benachrichtigungen, Logging oder externe Synchronisierungen.

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

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

Ereignis: { content, collection, isNew, actor } — Rückgabe: Promise<void>. Authentifizierte Speichervorgänge enthalten denselben optionalen actor-Snapshot wie content:beforeSave.

`content:beforeDelete`

Wird ausgeführt, bevor Inhalte gelöscht werden. Geben Sie false zurück, um abzubrechen; true oder void erlaubt das Löschen.

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

Ereignis: { id, collection, permanent: false } — Rückgabe: boolean | void

Dieser Hook wird ausgeführt, bevor ein Eintrag in den Papierkorb verschoben wird. Wird ein Eintrag dauerhaft aus dem Papierkorb entfernt, läuft content:beforeDelete nicht erneut.

`content:afterDelete`

Wird ausgeführt, nachdem Inhalte erfolgreich gelöscht wurden.

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

Ereignis: { id, collection, permanent } — Rückgabe: Promise<void>. permanent ist false, wenn der Eintrag in den Papierkorb verschoben wurde, und true, wenn der Eintrag dauerhaft entfernt wurde.

Deklarieren Sie hooks.content-policy:register, um Veröffentlichung, Planung oder Rücknahme der Veröffentlichung zu prüfen und abzulehnen, ohne Lese-, Schreib- oder Veröffentlichungszugriff auf Inhalte zu erhalten.

Geben Sie void zurück, um die Aktion zu erlauben, oder { cancel: true, reason }, um sie abzulehnen. Der Grund muss 1–500 Zeichen reinen Text enthalten. Ungültige Entscheidungen und unerwartete Fehler brechen standardmäßig ab, ohne die Ausnahme offenzulegen. Explizite Ablehnungen geben PUBLISH_REJECTED, SCHEDULE_REJECTED oder UNPUBLISH_REJECTED zurück.

Alle drei Ereignisse enthalten { content, collection, origin, actor? }. origin.source ist api, mcp, visual-editor, plugin, scheduler oder system; Plugin-Origins enthalten außerdem pluginId. Authentifizierte menschliche Aktionen enthalten actor.id, die numerische actor.role und die passende actor.source. EmDash akzeptiert den visual-editor-Origin nur über das signierte, kurzlebige Aktions-Token, das in einem authentifizierten Toolbar-Rendering eingebettet ist; gewöhnliche API-Anfragen können ihren Origin nicht wählen.

Veröffentlichungs- und Planungsereignisse legen den wirksamen Entwurf in content.data und den vorbereiteten Slug in content.slug offen. Ereignisse zur Rücknahme der Veröffentlichung legen die aktuell live geschalteten Inhalte offen, die die Aktion entfernen würde.

`content:beforePublish`

Der folgende Hook verlangt eine Freigabemarkierung, bevor Inhalte live gehen können:

"content:beforePublish": async (event) => {
	const data = event.content.data;
	const approvalStatus =
		typeof data === "object" && data !== null && "approval_status" in data
			? data.approval_status
			: undefined;
	if (approvalStatus !== "approved") {
		return { cancel: true, reason: "Approve this entry before publishing." };
	}
},

Dieser Hook wird vor der manuellen, der MCP-, der Plugin-, der System- und der geplanten Veröffentlichung ausgeführt. Geplante Inhalte werden erneut geprüft, wenn ihr Veröffentlichungszeitpunkt eintritt. Eine Ablehnung durch den Scheduler hebt die Planung des Eintrags auf, speichert den öffentlich unbedenklichen Grund und listet den betroffenen Eintrag im Dashboard auf, statt dieselbe dauerhafte Ablehnung bei jedem Scheduler-Tick erneut zu versuchen. Eine erfolgreiche Planung, Veröffentlichung oder Löschung löscht den Datensatz. Ein Administrator kann einen veralteten Datensatz verwerfen, wenn der Eintrag oder das Richtlinien-Plugin nicht mehr verfügbar ist.

`content:beforeSchedule`

Wird ausgeführt, bevor ein Eintrag einen Veröffentlichungszeitpunkt erhält. Das Ereignis enthält außerdem scheduledAt.

Es gibt keinen content:beforeUnschedule-Hook. Ein Administrator kann eine zukünftige Veröffentlichung immer abbrechen.

`content:beforeUnpublish`

Wird ausgeführt, bevor live geschaltete Inhalte entfernt werden.

`content:afterPublish`

Wird ausgeführt, nachdem Inhalte vom Entwurf zu live befördert wurden. Erfordert die Capability content:read.