フック | EmDash CMS Everything

フックを使うと、プラグインはイベントに応じてコードを実行できます。すべてのフックはイベントオブジェクトとプラグインコンテキストを受け取り、プラグインの定義時に宣言します。実行時の動的な登録はありません。

このページでは sandboxed プラグインを扱います。ネイティブプラグインも同じフック名とイベント型を使いますが、インプロセスのフックパイプラインを使い、さらに page:fragments を登録できます。sandbox での保存拒否と、隔離ランナーでの失敗時の動作は後述します。

フックシグネチャ

すべてのフックハンドラーは 2 つの引数を取ります。

async (event, ctx) => ReturnType;

event — 直前に起きたこと（保存中のコンテンツ、アップロードされたメディア、ライフサイクルの遷移など）に関するデータ
ctx — ストレージ、KV、ログ、capability で制御される API を備えた PluginContext

定義を SandboxedPlugin 型の定数に代入すると、event はフック名から推論され（完全な正規のイベント型）、ctx は PluginContext と推論されるため、ハンドラーにパラメータの型注釈は不要です。その定数をデフォルトエクスポートしてください。ヘルパー内でイベント型を名前で参照するには、emdash/plugin からインポートします。

フック設定

フックは、ハンドラー単体として宣言することも、設定オブジェクトで包んで宣言することもできます。プラグインが意図的なインプロセス実行にも対応し、以下で説明するメタデータが必要な場合を除き、ハンドラー単体の形式を推奨します。

シンプル

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

完全な設定

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

設定オプション

オプション	型	デフォルト	説明
`priority`	`number`	`100`	実行順序。数値が小さいほど先に実行されます。
`timeout`	`number`	`5000`	最大実行時間（ミリ秒）。
`exclusive`	`boolean`	`false`	アクティブなプロバイダーになれるプラグインは 1 つだけです。`email:deliver` と `comment:moderate` で使用します。
`handler`	`function`	—	フックハンドラー関数。必須です。

必要な capability

一部のフックは保護されたデータを公開したり、操作を変更したりできます。EmDash は、マニフェストが対応する capability を宣言している場合にのみ、それらを登録します。

フック	Capability	理由
`content:beforeSave`	`content:write`	このフックは送信されたコンテンツを置き換えられます。
`content:beforePublish`、`content:beforeSchedule`、`content:beforeUnpublish`	`hooks.content-policy:register`	これらのフックは公開状態の変更を拒否できます。
その他の `content:*` フック	`content:read`	イベントがコンテンツを公開するか、エントリを特定します。
`media:beforeUpload`	`media:write`	このフックはアップロードのメタデータを置き換えたり、アップロードを停止したりできます。
`media:afterUpload`	`media:read`	イベントが保存されたメディア項目を公開します。
`email:beforeSend`、`email:afterSend`	`hooks.email-events:register`	これらのフックはメールのライフサイクルイベントを検査します。
`email:deliver`	`hooks.email-transport:register`	このフックはメールトランスポートプロバイダーになります。
すべての `comment:*` フック	`users:read`	コメントイベントには、投稿者の連絡先情報とリクエストのメタデータが含まれる場合があります。
`page:fragments`	`hooks.page-fragments:register`	このフックはファーストパーティのページコンテンツを注入し、ネイティブ専用です。

ライフサイクルフック、cron、page:metadata には登録用の capability がありません。フックがイベントを読み取るだけで、対応する ctx API を呼び出さない場合でも、一覧にある capability を宣言してください。この宣言により、オペレーターに正確な同意プロンプトが表示され、ctx API が制御され、プラグインがインプロセスで実行されるときに必須となります。実行時の影響については Capability とセキュリティで説明しています。

ライフサイクルフック

プラグインのインストール、有効化、無効化、削除の際に実行されます。

`plugin:install`

プラグインがサイトに最初に追加されたときに 1 回だけ実行されます。

この例は、マニフェストが items ストレージコレクションを宣言していることを前提としています。

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

イベント: {} — 戻り値: Promise<void>

`plugin:activate`

プラグインが有効化されたとき（インストール後、または再有効化時）に実行されます。

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

イベント: {} — 戻り値: Promise<void>

`plugin:deactivate`

プラグインが無効化されたとき（削除はされない）に実行されます。

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

イベント: {} — 戻り値: Promise<void>

`plugin:uninstall`

プラグインがサイトから削除されたときに実行されます。

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

イベント: { deleteData: boolean } — 戻り値: Promise<void>

コンテンツフック

サイトコンテンツの作成、更新、削除の操作中に実行されます。

`content:beforeSave`

コンテンツが保存される前に実行されます。変更したコンテンツ、sandbox フックのエラー結果を返すか、変更しない場合は void を返します。

sandbox から保存を拒否するには、SAVE_REJECTED エラーを持つバージョン付きのフック結果を返します。reason には 1〜500 文字のプレーンテキストを設定してください。EmDash はプラグインを特定し、その理由を編集者に表示します。空、長すぎる、不正な形式、未知のエラー結果は、汎用のフックエラーとして保存を失敗させます。

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

reason に HTML を入れないでください。管理画面はこの値をテキストとして表示します。

ホストプロセスからは、代わりに ContentSaveRejectedError（emdash からエクスポートされています）をスローします。API はあなたのメッセージとともに SAVE_REJECTED を返します。どちらの実行モードでも、それ以外の例外は汎用の CONTENT_HOOK_ERROR レスポンスとして保存を失敗させます。

イベント: { content, collection, isNew, id, actor } — 戻り値: 変更したコンテンツ、sandbox フックエラー結果、または void。更新時、id は既存項目の ID で、content は送信されたフィールド値のみを持ちます。保存済み項目は ctx.content.get(event.collection, event.id) で読み込みます。エントリの slug は content に含まれず、フックが返した slug キーは未知のフィールドとして検証に失敗します。認証済みの REST、ビジュアル編集、MCP 保存には actor.id と数値の actor.role が含まれます。認証ユーザーなしの内部書き込みは actor を省略します。

`content:afterSave`

コンテンツが正常に保存された後に実行されます。通知、ログ記録、外部への同期といった副作用に使います。

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

イベント: { content, collection, isNew, actor } — 戻り値: Promise<void>。認証済み保存には content:beforeSave と同じ任意の actor スナップショットが含まれます。

`content:beforeDelete`

コンテンツが削除される前に実行されます。false を返すとキャンセルされ、true または void を返すと許可されます。

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

イベント: { id, collection, permanent: false } — 戻り値: boolean | void

このフックは、エントリがゴミ箱に移動される前に実行されます。ゴミ箱からエントリを恒久的に削除するときには、content:beforeDelete は再度実行されません。

`content:afterDelete`

コンテンツが正常に削除された後に実行されます。

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

イベント: { id, collection, permanent } — 戻り値: Promise<void>。permanent はエントリがゴミ箱に移されたとき false、恒久削除されたとき true です。

hooks.content-policy:register を宣言すると、コンテンツの読み取り、書き込み、公開操作へのアクセス権を得ることなく、公開、スケジュール、非公開を検査して拒否できます。

操作を許可するには void を返し、拒否するには { cancel: true, reason } を返します。理由は 1〜500 文字のプレーンテキストでなければなりません。無効な判断や予期しないエラーは、例外を公開せずにデフォルトで中止します。明示的な拒否は PUBLISH_REJECTED、SCHEDULE_REJECTED、UNPUBLISH_REJECTED を返します。

3 つのイベントはいずれも { content, collection, origin, actor? } を含みます。origin.source は api、mcp、visual-editor、plugin、scheduler、system のいずれかで、プラグインの origin には pluginId も含まれます。認証済みの人間による操作には、actor.id、数値の actor.role、対応する actor.source が含まれます。EmDash が visual-editor の origin を受け入れるのは、認証済みツールバーのレンダリングに埋め込まれた、署名付きで有効期間の短いアクショントークンからのみです。通常の API リクエストは origin を選択できません。

公開およびスケジュールのイベントでは、有効なドラフトを content.data で、ステージされた slug を content.slug で公開します。非公開のイベントでは、その操作によって削除される現在公開中のコンテンツを公開します。

`content:beforePublish`

次のフックは、コンテンツを公開する前に承認マーカーを要求します。

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

このフックは、手動、MCP、プラグイン、システム、スケジュールによる公開の前に実行されます。スケジュールされたコンテンツは、公開時刻が来たときに再度チェックされます。スケジューラーによる拒否はエントリのスケジュールを解除し、公開しても問題のない理由を保存し、影響を受けたエントリをダッシュボードに一覧表示します。スケジューラーの実行のたびに同じ恒久的な拒否を再試行することはありません。スケジュール、公開、削除のいずれかが成功すると、その記録は消去されます。エントリまたはポリシープラグインが利用できなくなった場合、管理者は古い記録を閉じることができます。

`content:beforeSchedule`

エントリに公開時刻が設定される前に実行されます。イベントには scheduledAt も含まれます。

content:beforeUnschedule フックはありません。管理者は常に将来の公開を取り消せます。