設定画面とデータ保存を組み込む

管理者が変える設定、内部状態、一覧で扱う記録の保存先を選びます。保存用APIと設定画面、秘密値の扱いを整理します。

目次

保存するものに合わせて場所を選ぶ

管理者が切り替える設定にはctx.settings、後から検索して読む記録にはctx.storageを使います。たとえば記事保存のログを残すプラグインなら、「記録する・しない」のスイッチと、実際に残した記録を分けて保存します。ctxは、プラグインからEmDashの機能を使うための窓口です。

データ保存先例
管理者が変更する設定ctx.settings記録の有効・無効
プラグイン内部の状態ctx.kv前回の同期位置
条件で検索する記録ctx.storage記事を保存した履歴
通常の管理画面で編集する記事サイトのコレクションブログ本文

KVは、キーという名前を付けて値を取り出す方式です。大量の記録を日付で並べるなら、専用のstorageコレクションを使います。

プラグインの値を保存・取得・削除する実習では、同じキーを更新したときや、まだ値がないときの結果を試せます。

設定を読む

記事保存などのタイミングで動く処理(フック)や、プログラムから操作する窓口(API)の中では、次のように設定を読めます。

const enabled = (await ctx.settings.get<boolean>("enabled")) ?? true;
if (!enabled) return;

getは値がないとnullを返します。?? trueは、まだ保存されていないときは有効として扱う指定です。新しい設定を追加したときにも、古い利用者の環境で値がないことを想定できます。

保存するときはawait ctx.settings.set("enabled", false)のように使います。これはそのプラグインの設定で、同じキー名を使う他のプラグインの設定とは分かれています。

ネイティブに設定画面を付ける

ネイティブの例のdefinePlugin({ ... })へ、次のadminを追加すると、EmDashが設定フォームを作る方式を使えます。

admin: {
  settingsSchema: {
    enabled: {
      type: "boolean",
      label: "保存の記録を有効にする",
      default: true,
    },
  },
},

hooksは残し、保存処理の最初に先ほどのenabled確認を入れます。再ビルド・サイトへの取り込み・再起動を行い、管理画面のPluginsで対象プラグインの設定を開きます。変更にはplugins:manage権限が必要です。

スイッチを切って保存すると、次の記事保存では記録しなくなる想定です。フォームが表示できるだけでなく、実際の処理が設定に従うかまで確認します。

サンドボックスで独自の設定画面を作る場合

登録情報のファイル(manifest)に設定項目や管理ページを宣言し、画面部品を組み合わせるBlock Kitで設定画面を作る方法があります。ページを開いたpage_loadと、送信されたform_submitを処理し、入力値を検証してからctx.settingsへ保存します。

画面の表示定義だけでは保存処理は完成しません。数値の範囲や必須項目もサーバー側で確認し、設定用のルートを公開APIにしないようにします。フォームの全体例は公式のSettingsガイド(別タブで開く)を参照してください。

記録用のstorageを宣言する

サンドボックスならemdash-plugin.jsoncへ、ネイティブならdefinePlugin()の中へ次を追加します。

"storage": {
  "events": { "indexes": ["savedAt"] }
}

eventsが保存領域の名前、savedAtが並べ替えや検索に使う項目です。indexは、その項目を条件に取り出せるよう準備する指定です。

保存後フックの中では、たとえば次のように保存できます。

const savedAt = new Date().toISOString();
const contentId = String(event.content.id);
await ctx.storage.events.put(`${savedAt}:${contentId}`, {
  savedAt,
  contentId,
  collection: event.collection,
});

これは学習用の記録です。同じ記事を同時刻に複数回保存した場合も区別したいときは、記録ごとに重複しないIDを付ける方法を用意します。putは同じIDなら値を置き換えるので、「呼んだ回数ぶん必ず増える」とは限りません。

記録を読み出す

宣言したeventsから、新しい順に20件取り出す例です。

const result = await ctx.storage.events.query({
  orderBy: { savedAt: "desc" },
  limit: 20,
});

result.itemsはidとdataを持つ記録の配列です。続きがある場合はcursorを次の取得へ渡します。最初の20件だけを取って、全件取得と扱わないようにしてください。

queryで条件や並べ替えに使う項目にはindexの宣言が必要です。保存領域そのものを宣言し忘れた場合も、実行時に失敗します。

秘密値と、消さない初期化

APIキーなどを保存する場合は、設定の型をsecretとして宣言し、EMDASH_ENCRYPTION_KEYを用意します。入力欄を伏せ字にするだけでは、保存時の暗号化を指定したことにはなりません。暗号化した設定の復元には、データベースと対応する暗号化キーの両方が必要です。

設定画面へ秘密値そのものを返さず、「設定済み」という状態を示します。空欄の送信だけで既存キーを消さず、削除は明示的な操作にします。

初期化でも、既存の設定を毎回初期値に戻さないでください。再導入や再試行でも既存の値が残ることを確認します。複数の処理が同じ記録を同時に更新する場合は、getVersionedとcompareAndSetなどで、読み取った後に値が変わっていないか確かめてから更新する方法を検討します。

公式の参照元

関連ガイド

メニュー
ホーム公式ドキュメント (別タブで開く)

キーワードを入力すると、ガイドの内容から探せます。