Hooks | EmDash CMS Everything

Gli hooks permettono ai plugin di eseguire codice in risposta a eventi. Tutti gli hooks ricevono un oggetto evento e il contesto del plugin, e vengono dichiarati al momento della definizione del plugin — non c’è registrazione dinamica a runtime.

Questa pagina tratta i plugin sandboxed. Gli hooks funzionano in modo identico nei plugin nativi; i plugin nativi possono inoltre registrare page:fragments.

Firma dell’hook

Ogni handler di hook prende due argomenti:

async (event, ctx) => ReturnType;

event — dati su ciò che è appena accaduto (contenuto in fase di salvataggio, media caricati, transizione del ciclo di vita, ecc.)
ctx — il PluginContext con storage, KV, logging e API controllate da capacità

satisfies SandboxedPlugin sull’export predefinito inferisce event dal nome dell’hook (il tipo di evento canonico completo) e ctx come PluginContext, quindi gli handler non necessitano di annotazioni dei parametri. Per riferirsi a un tipo di evento per nome in un helper, importalo da emdash/plugin.

Configurazione dell’hook

Un hook può essere dichiarato come handler semplice o racchiuso in un oggetto di configurazione:

Semplice

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

Configurazione completa

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

Opzioni di configurazione

Opzione	Tipo	Predefinito	Descrizione
`priority`	`number`	`100`	Ordine di esecuzione. I numeri più bassi vengono eseguiti per primi.
`timeout`	`number`	`5000`	Tempo massimo di esecuzione in millisecondi.
`dependencies`	`string[]`	`[]`	ID dei plugin che devono essere eseguiti prima di questo hook.
`errorPolicy`	`"abort" \| "continue"`	`"abort"`	Se interrompere la pipeline in caso di errore.
`exclusive`	`boolean`	`false`	Solo un plugin può essere il fornitore attivo. Usato per `email:deliver` e `comment:moderate`.
`handler`	`function`	—	La funzione handler dell’hook. Obbligatoria.

Hook del ciclo di vita

Vengono eseguiti durante l’installazione, l’attivazione, la disattivazione e la rimozione del plugin.

`plugin:install`

Viene eseguito una volta quando il plugin viene aggiunto a un sito per la prima volta.

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

Evento: {} — Restituisce: Promise<void>

`plugin:activate`

Viene eseguito quando il plugin viene abilitato (dopo l’installazione o quando viene riabilitato).

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

Evento: {} — Restituisce: Promise<void>

`plugin:deactivate`

Viene eseguito quando il plugin viene disabilitato (ma non rimosso).

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

Evento: {} — Restituisce: Promise<void>

`plugin:uninstall`

Viene eseguito quando il plugin viene rimosso da un sito.

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

Evento: { deleteData: boolean } — Restituisce: Promise<void>

Hook di contenuto

Vengono eseguiti durante le operazioni di creazione, aggiornamento ed eliminazione sui contenuti del sito.

`content:beforeSave`

Viene eseguito prima del salvataggio del contenuto. Restituisce il contenuto modificato, o void per lasciarlo invariato. Lancia un’eccezione per annullare.

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

Evento: { content, collection, isNew } — Restituisce: contenuto modificato o void.

`content:afterSave`

Viene eseguito dopo il salvataggio riuscito del contenuto. Usalo per effetti collaterali come notifiche, logging o sincronizzazioni esterne.

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

Evento: { content, collection, isNew } — Restituisce: Promise<void>

`content:beforeDelete`

Viene eseguito prima dell’eliminazione del contenuto. Restituisce false per annullare; true o void lo permette.

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

Evento: { id, collection } — Restituisce: boolean | void

`content:afterDelete`

Viene eseguito dopo l’eliminazione riuscita del contenuto.

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

Evento: { id, collection } — Restituisce: Promise<void>

`content:afterPublish`

Viene eseguito dopo la promozione del contenuto da bozza a pubblicato. Richiede la capacità content:read.