Hooks

Hooks ermöglichen es Plugins, Code als Reaktion auf Ereignisse auszuführen. Alle Hooks erhalten ein Event-Objekt und den Plugin-Kontext, und sie werden zur Plugin-Definitionszeit deklariert — es gibt keine dynamische Registrierung zur Laufzeit.

Diese Seite behandelt sandboxed (Standard-Format) Plugins. Hooks funktionieren in nativen Plugins identisch; der einzige Unterschied besteht darin, dass native Plugins auch page:fragments registrieren können, was sandboxed Plugins nicht können.

Hook-Signatur

Jeder Hook-Handler nimmt zwei Argumente entgegen:

async (event: EventType, ctx: PluginContext) => ReturnType;

• event — Daten darüber, was gerade passiert ist (Inhalte werden gespeichert, Medien hochgeladen, Lebenszyklusübergang usw.)
• ctx — der PluginContext mit Storage, KV, Logging und capability-gesteuerten APIs

Hook-Konfiguration

Ein Hook kann als einfacher Handler oder in ein Konfigurationsobjekt eingebettet deklariert werden:

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

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

Konfigurationsoptionen

Lebenszyklus-Hooks

Werden während der Plugin-Installation, -Aktivierung, -Deaktivierung und -Entfernung ausgeführt.

plugin:install

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

"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" });
},

Event: {} — Returns: Promise<void>

plugin:activate

Wird ausgeführt, wenn das Plugin aktiviert wird (nach der Installation oder beim erneuten Aktivieren).

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

Event: {} — Returns: Promise<void>

plugin:deactivate

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

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

Event: {} — Returns: 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) {
		const result = await ctx.storage.items.query({ limit: 1000 });
		await ctx.storage.items.deleteMany(result.items.map((i) => i.id));
	}
},

Event: { deleteData: boolean } — Returns: Promise<void>

Content-Hooks

Werden während Erstellen-, Aktualisieren- und Löschen-Operationen auf Site-Inhalten ausgeführt.

content:beforeSave

Wird ausgeführt, bevor Inhalte gespeichert werden. Gibt geänderte Inhalte oder void zurück, um sie unverändert zu lassen. Werfen Sie einen Fehler, um abzubrechen.

"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;
},

Event: { content, collection, isNew } — Returns: geänderter Inhalt oder void.

content:afterSave

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

"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 }),
		});
	}
},

Event: { content, collection, isNew } — Returns: Promise<void>

content:beforeDelete

Wird ausgeführt, bevor Inhalte gelöscht werden. Gibt false zurück, um abzubrechen; true oder void erlaubt es.

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

Event: { id, collection } — Returns: boolean | void

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}`);
},

Event: { id, collection } — Returns: Promise<void>

content:afterPublish

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

Event: { content, collection } — Returns: Promise<void>

content:afterUnpublish

Wird ausgeführt, nachdem Inhalte von Live zu Entwurf zurückgesetzt wurden. Erfordert die content:read Capability.

Event: { content, collection } — Returns: Promise<void>

Medien-Hooks

media:beforeUpload

Wird ausgeführt, bevor eine Datei hochgeladen wird. Gibt geänderte Datei-Metadaten zurück oder wirft einen Fehler, um abzubrechen.

"media:beforeUpload": async (event, ctx) => {
	if (!event.file.type.startsWith("image/")) {
		throw new Error("Only images are allowed");
	}
	if (event.file.size > 10 * 1024 * 1024) {
		throw new Error("File too large");
	}
	return { ...event.file, name: `${Date.now()}-${event.file.name}` };
},

Event: { file: { name, type, size } } — Returns: geänderte Datei oder void

media:afterUpload

Wird ausgeführt, nachdem eine Datei erfolgreich hochgeladen wurde.

Event: { media: { id, filename, mimeType, size, url, createdAt } } — Returns: Promise<void>

Public-Page-Hooks

Diese ermöglichen es Plugins, zu gerenderten öffentlichen Seiten beizutragen. Templates müssen sich durch Einbinden der <EmDashHead>, <EmDashBodyStart> und <EmDashBodyEnd> Komponenten aus emdash/ui anmelden.

page:metadata

Trägt typisierte Metadaten zu <head> bei — Meta-Tags, OpenGraph-Properties, erlaubte <link> rels und JSON-LD. Verfügbar für sowohl sandboxed als auch native Plugins. Der Core validiert, dedupliziert und rendert die Beiträge; Plugins geben strukturierte Daten zurück, niemals rohes HTML.

"page:metadata": async (event, ctx) => {
	if (event.page.kind !== "content") return null;

	return {
		kind: "jsonld",
		id: `schema:${event.page.content?.collection}:${event.page.content?.id}`,
		graph: {
			"@context": "https://schema.org",
			"@type": "BlogPosting",
			headline: event.page.pageTitle ?? event.page.title,
			description: event.page.description,
		},
	};
},

Event:

{
	page: {
		url: string;
		path: string;
		locale: string | null;
		kind: "content" | "custom";
		pageType: string;
		title: string | null;
		pageTitle?: string | null;
		description: string | null;
		canonical: string | null;
		image: string | null;
		content?: { collection: string; id: string; slug: string | null };
	}
}

Returns: PageMetadataContribution | PageMetadataContribution[] | null

Contribution-Arten:

Der erste Beitrag gewinnt für jeden Dedupe-Schlüssel. Link rel ist auf eine sicherheitsgesperrte Whitelist beschränkt (canonical, alternate, author, license, nlweb, site.standard.document); href muss HTTP oder HTTPS sein.

page:fragments

Trägt rohes HTML, Scripts oder Stylesheets zu Seiten-Einfügepunkten bei. Nur für native Plugins.

Sandboxed Plugins können diesen Hook nicht verwenden, da dessen Ausgabe als First-Party-Code im Browser des Besuchers ausgeführt wird, außerhalb jeder Sandbox-Grenze. Für sandbox-sichere Seitenbeiträge verwenden Sie page:metadata. Siehe Native Plugins: Page Fragments, wenn Sie diese Oberfläche benötigen.

Hook-Ausführungsreihenfolge

Hooks werden in dieser Reihenfolge ausgeführt:

1. Hooks mit niedrigeren priority-Werten werden zuerst ausgeführt.
2. Bei gleichen Prioritäten werden Hooks in Plugin-Registrierungsreihenfolge ausgeführt.
3. Hooks mit dependencies warten darauf, dass diese Plugins abgeschlossen sind.

// Plugin A
"content:afterSave": { priority: 50, handler: async () => {} }

// Plugin B
"content:afterSave": { priority: 100, handler: async () => {} }

// Plugin C
"content:afterSave": {
	priority: 200,
	dependencies: ["plugin-a"],   // waits for A even if its priority would normally be later
	handler: async () => {},
}

Fehlerbehandlung

Wenn ein Hook einen Fehler wirft oder das Timeout überschreitet:

• errorPolicy: "abort" — die gesamte Pipeline stoppt und die ursprüngliche Operation kann fehlschlagen.
• errorPolicy: "continue" — der Fehler wird protokolliert und die verbleibenden Hooks werden weiterhin ausgeführt.

"content:afterSave": {
	timeout: 5000,
	errorPolicy: "continue",
	handler: async (event, ctx) => {
		await ctx.http!.fetch("https://unreliable-api.com/notify");
	},
},

Timeouts

Hooks haben standardmäßig 5000ms. Erhöhen Sie das Timeout für langsamere Arbeiten:

"content:afterSave": {
	timeout: 30000,
	handler: async (event, ctx) => {
		// Long-running operation
	},
},

Hook-Referenz

Siehe die Hook-Referenz für vollständige Event-Typen und Handler-Signaturen.