Hooks | EmDash CMS Everything

Los hooks permiten a los plugins ejecutar código en respuesta a eventos. Todos los hooks reciben un objeto de evento y el contexto del plugin, y se declaran en el momento de definición del plugin — no hay registro dinámico en tiempo de ejecución.

Esta página cubre los plugins sandboxed. Los hooks funcionan de manera idéntica en plugins nativos; los plugins nativos pueden además registrar page:fragments.

Firma del hook

Cada handler de hook toma dos argumentos:

async (event, ctx) => ReturnType;

event — datos sobre lo que acaba de ocurrir (contenido siendo guardado, medios subidos, transición de ciclo de vida, etc.)
ctx — el PluginContext con storage, KV, logging y APIs controladas por capacidades

satisfies SandboxedPlugin en la exportación por defecto infiere event del nombre del hook (el tipo de evento canónico completo) y ctx como PluginContext, por lo que los handlers no necesitan anotaciones de parámetros. Para referenciar un tipo de evento por nombre en un helper, impórtalo de emdash/plugin.

Configuración del hook

Un hook puede declararse como un handler simple o envuelto en un objeto de configuración:

Simple

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

Configuración completa

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

Opciones de configuración

Opción	Tipo	Por defecto	Descripción
`priority`	`number`	`100`	Orden de ejecución. Los números más bajos se ejecutan primero.
`timeout`	`number`	`5000`	Tiempo máximo de ejecución en milisegundos.
`dependencies`	`string[]`	`[]`	IDs de plugins que deben ejecutarse antes de este hook.
`errorPolicy`	`"abort" \| "continue"`	`"abort"`	Si detener el pipeline en caso de error.
`exclusive`	`boolean`	`false`	Solo un plugin puede ser el proveedor activo. Usado para `email:deliver` y `comment:moderate`.
`handler`	`function`	—	La función handler del hook. Requerida.

Hooks de ciclo de vida

Se ejecutan durante la instalación, activación, desactivación y eliminación del plugin.

`plugin:install`

Se ejecuta una vez cuando el plugin se añade por primera vez a un sitio.

"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: {} — Devuelve: Promise<void>

`plugin:activate`

Se ejecuta cuando el plugin se habilita (después de la instalación o cuando se re-habilita).

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

Evento: {} — Devuelve: Promise<void>

`plugin:deactivate`

Se ejecuta cuando el plugin se deshabilita (pero no se elimina).

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

Evento: {} — Devuelve: Promise<void>

`plugin:uninstall`

Se ejecuta cuando el plugin se elimina de un sitio.

"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 } — Devuelve: Promise<void>

Hooks de contenido

Se ejecutan durante operaciones de creación, actualización y eliminación de contenido del sitio.

`content:beforeSave`

Se ejecuta antes de guardar contenido. Devuelve contenido modificado, o void para dejarlo sin cambios. Lanza una excepción para cancelar.

"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 } — Devuelve: contenido modificado o void.

`content:afterSave`

Se ejecuta después de que el contenido se guarda exitosamente. Úsalo para efectos secundarios como notificaciones, logging o sincronizaciones externas.

"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 } — Devuelve: Promise<void>

`content:beforeDelete`

Se ejecuta antes de eliminar contenido. Devuelve false para cancelar; true o void lo permite.

"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 } — Devuelve: boolean | void

`content:afterDelete`

Se ejecuta después de que el contenido se elimina exitosamente.

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

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

`content:afterPublish`

Se ejecuta después de que el contenido se promueve de borrador a publicado. Requiere la capacidad content:read.