Hooks | EmDash CMS Everything

Os hooks permitem que plugins executem código em resposta a eventos. Todos os hooks recebem um objeto de evento e o contexto do plugin, e são declarados no momento da definição do plugin — não há registro dinâmico em tempo de execução.

Esta página cobre plugins sandboxed. Os hooks funcionam de forma idêntica em plugins nativos; plugins nativos podem adicionalmente registrar page:fragments.

Assinatura do hook

Todo handler de hook recebe dois argumentos:

async (event, ctx) => ReturnType;

event — dados sobre o que acabou de acontecer (conteúdo sendo salvo, mídia carregada, transição de ciclo de vida, etc.)
ctx — o PluginContext com storage, KV, logging e APIs controladas por capacidades

satisfies SandboxedPlugin no export padrão infere event a partir do nome do hook (o tipo de evento canônico completo) e ctx como PluginContext, então os handlers não precisam de anotações de parâmetros. Para referenciar um tipo de evento por nome em um helper, importe-o de emdash/plugin.

Configuração do hook

Um hook pode ser declarado como um handler simples ou envolvido em um objeto de configuração:

Simples

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

Configuração completa

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

Opções de configuração

Opção	Tipo	Padrão	Descrição
`priority`	`number`	`100`	Ordem de execução. Números mais baixos executam primeiro.
`timeout`	`number`	`5000`	Tempo máximo de execução em milissegundos.
`dependencies`	`string[]`	`[]`	IDs de plugins que devem executar antes deste hook.
`errorPolicy`	`"abort" \| "continue"`	`"abort"`	Se deve parar o pipeline em caso de erro.
`exclusive`	`boolean`	`false`	Apenas um plugin pode ser o provedor ativo. Usado para `email:deliver` e `comment:moderate`.
`handler`	`function`	—	A função handler do hook. Obrigatória.

Hooks de ciclo de vida

Executam durante a instalação, ativação, desativação e remoção do plugin.

`plugin:install`

Executa uma vez quando o plugin é adicionado a um site pela primeira vez.

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

`plugin:activate`

Executa quando o plugin é habilitado (após instalação ou quando reabilitado).

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

Evento: {} — Retorna: Promise<void>

`plugin:deactivate`

Executa quando o plugin é desabilitado (mas não removido).

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

Evento: {} — Retorna: Promise<void>

`plugin:uninstall`

Executa quando o plugin é removido de um site.

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

Hooks de conteúdo

Executam durante operações de criação, atualização e exclusão em conteúdo do site.

`content:beforeSave`

Executa antes do conteúdo ser salvo. Retorna conteúdo modificado, ou void para deixá-lo inalterado. Lance uma exceção 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 } — Retorna: conteúdo modificado ou void.

`content:afterSave`

Executa após o conteúdo ser salvo com sucesso. Use para efeitos colaterais como notificações, logging ou sincronizações 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 } — Retorna: Promise<void>

`content:beforeDelete`

Executa antes do conteúdo ser excluído. Retorna false para cancelar; true ou void 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 } — Retorna: boolean | void

`content:afterDelete`

Executa após o conteúdo ser excluído com sucesso.

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

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

`content:afterPublish`

Executa após o conteúdo ser promovido de rascunho para publicado. Requer a capacidade content:read.