記事保存などのタイミングで処理する
保存前・保存後・公開前などのタイミングで動くフックを整理します。必要な権限、部分更新、失敗時の違いを説明します。
目次
「いつ動かすか」を決める
記事を保存したときに記録する、公開前に必要項目を確認する。こうした処理を差し込むために、EmDashはフックを用意しています。フックは、決まった出来事に合わせてプログラムを呼び出す仕組みです。
保存と公開は別の操作なので、保存したことを知りたいのか、読者に見える状態になったことを知りたいのかを先に決めます。
よく使うタイミング
| フック | タイミング | 権限宣言 |
|---|---|---|
content:beforeSave | 保存する前 | content:write |
content:afterSave | 保存した後 | content:read |
content:beforePublish | 公開する前 | hooks.content-policy:register |
content:afterPublish | 公開した後 | content:read |
content:beforeSchedule | 予約を設定する前 | hooks.content-policy:register |
media:afterUpload | 画像などを登録した後 | media:read |
afterSaveでログが出たからといって、その記事が公開済みとは限りません。下書き保存も扱うためです。予約した記事は、予約時と実際の公開時で確認のタイミングが分かれます。
eventとctxを読む
フックにはeventとctxが渡されます。
eventは、何が起きたかの情報です。保存ならコレクション、内容、新規作成かどうかなどが入ります。ctxは、プラグインからログ、設定、データ保存などを使う窓口です。
ここでのコードは、サンドボックスの練習で作ったプラグインへ組み込む例です。先に保存時のログが出る状態を用意しておきます。
サンドボックスのsrc/plugin.tsで、次のように定義できます。登録情報のファイル(manifest)に、記事を読む権限content:readを宣言したプラグインを前提にします。
import type { SandboxedPlugin } from "emdash/plugin";
const plugin: SandboxedPlugin = {
hooks: {
"content:afterSave": async (event, ctx) => {
if (event.collection !== "posts") return;
ctx.log.info("記事の保存", {
id: String(event.content.id),
isNew: event.isNew,
});
},
},
};
export default plugin;ifは条件分岐です。今回はposts以外なら処理を終えます。これで固定ページなどの保存を、記事と混同せずに扱えます。
保存前の内容は、記事の全体とは限らない
更新時のcontent:beforeSaveには、今回送信された入力欄だけが入る場合があります。「タイトルが入っていないから空欄だ」と判断すると、別の欄だけを更新する操作まで止めてしまいます。
新規作成なのか既存記事の更新なのかを確かめたうえで、今回タイトルが送られたか、保存済みの値も読み込む必要があるかを判断します。保存前のevent.idと、保存後のevent.content.idも、同じイベントの形だと思って取り違えないようにしてください。
また、記事のスラッグは本文のフィールド集合と別です。保存前の内容へslugを追加して返しても、正しいスラッグ変更の手順にはなりません。
保存を止める方法にも違いがある
サンドボックスの保存前フックでは、決められた形式のSAVE_REJECTEDを返して、編集者向けの理由を示します。次は、すでに「空欄と判定した」分岐の中で返す部分です。
return {
__emdashSandboxHookResult: true,
version: 1,
error: {
code: "SAVE_REJECTED",
reason: "タイトルを入力してから保存してください。",
},
};ネイティブでは、ContentSaveRejectedErrorというエラーで保存を止めます。実行方式によって失敗の伝え方が違うため、例を混ぜないでください。公開前のフックは、保存前とは別に{ cancel: true, reason: "..." }という判断を返します。
理由は読者ではなく編集者が読む文章です。「検証失敗」だけでなく、何を直せば進めるかを書きます。
呼ばれないときは、権限とrunnerを見る
権限が不足したフックは、プラグイン全体の導入が成功していても登録されないことがあります。まずサーバーのログで、必要な権限(capability)がなく、フックの登録を省略したという記録がないか確認します。
サンドボックスでは、分離した環境を動かす部品(runner)が利用できないと、プラグイン自体が読み込まれません。さらに、分離runnerとネイティブでは、実行順や時間制限の扱いが同じではありません。priorityを書けば、別のサンドボックスプラグインとの順序まで必ず制御できる、と考えないようにします。
再実行と失敗を考える
保存後に外部通知を送る場合、保存が成功しても通知が失敗する可能性があります。また、再試行で通知が二重になる場合もあります。記録用の識別子や送信状態を持ち、再実行で何が起こるかを設計します。
保存後フックの中から、同じ記事を無条件で保存し直す実装も注意が必要です。再びフックが呼ばれる流れを作らないよう、処理対象と変更条件を決めます。
確認では、新規保存、部分更新、下書き、公開、予約、処理失敗を分けます。フックの正確な引数と戻り値は公式リファレンス(別タブで開く)で対象のフック名を確認してください。