管理画面のプラグインを登録する ACMS.plugins と、setup(ctx) で受け取る ctx のリファレンスです。

はじめてプラグインを書く場合は はじめてのプラグイン から読んでください。

ACMS.plugins

register(name, definition)

プラグインを登録します。

ACMS.adminReady(() => {
  ACMS.plugins.register('my-plugin', {
    version: '1.0.0',
    setup(ctx) {
      // ここでイベント購読・UI 差し込み・機能登録を行う
    },
  });
});

register() は、ACMS.adminReady() の中で呼びます（登録するタイミング を参照）。

プラグイン名は、他のプラグインと衝突しないよう配布名やベンダー名を含めた形（acme-media-tools など）を推奨します。

unregister(name)

プラグインを登録解除します。setup(ctx) の中で行ったイベント購読・機能登録・UI 差し込みはすべて自動的に解除されます。個別に後片付けを書く必要はありません。

ACMS.plugins.unregister('my-plugin'); // 登録されていた場合 true を返す

get(name) / getAll()

登録済みのプラグインを取得します。デバッグ用です。

ACMS.plugins.getAll();
// [{ name: 'my-plugin', version: '1.0.0', registrations: [{ kind: 'event', key: 'media.upload.before' }, ...] }]

registrations には、そのプラグインが何を登録したかが登録順に入ります。イベント名や Slot 名の書き間違いを調べるときに使えます。

withFillProps(Component)

Slot が渡す値を React コンポーネントで受け取るためのラッパーです。使い方は UI の差し込み（Slot / Fill） を参照してください。

setup(ctx) で使える API

ctx は次のプロパティを持ちます。

登録系のメソッドはすべて解除用の関数を返します。ふつうは使う必要はありません（unregister で一括解除されます）が、条件によって途中で外したい場合に使えます。

const off = ctx.events.on('media.upload.before', handler);
off(); // 購読を解除する

登録するタイミング

ACMS.plugins は、管理画面の JavaScript（admin.js）が実行されるまで存在しません。 admin.js は非同期で読み込まれるため、<script type="module"> のプラグインのほうが先に実行されることがあります。登録は ACMS.adminReady() の中で行ってください。admin.js の初期化が終わってから呼ばれ、すでに終わっていれば、すぐに呼ばれます。

// ○ 正しい
ACMS.adminReady(() => {
  ACMS.plugins.register('my-plugin', {
    setup(ctx) {
      ctx.events.on('media.upload.before', handler);
    },
  });
});

// × 動かないことがあります（ACMS.plugins が未定義のことがあります）
ACMS.plugins.register('my-plugin', {
  setup(ctx) {
    ctx.events.on('media.upload.before', handler);
  },
});

// × 動きません
document.addEventListener('DOMContentLoaded', () => {
  ACMS.adminReady(() => {
    ACMS.plugins.register('my-plugin', { setup(ctx) { /* ... */ } });
  });
});

DOMContentLoaded を待ったり、時間のかかる非同期処理のあとで登録したりすると、管理画面側がすでに処理を進めているため、購読が間に合わないことがあります。ACMS.adminReady() の呼び出し自体は、スクリプトが読み込まれた時点で同期的に行ってください。ACMS.adminReady() を使っても、初期化中にすでに発生したイベントは購読できません。

読み込みは <script type="module"> で行ってください（アセット API の attrs に ['type' => 'module'] を指定）。type="module" のスクリプトは、ページの解析が終わってから記述順に実行されます。

複数プラグインの実行順

同じイベントを複数のプラグインが購読した場合、登録した順に実行されます。type="module" のスクリプトは記述順に実行されるため、ふつうは JS ファイルが読み込まれた順になります。優先度の指定はありません。順序を制御したい場合は、アセット API を呼ぶ順番で調整してください。

setup が失敗したとき

setup(ctx) の中で例外が発生した場合、そのプラグインが途中まで行った登録はすべて取り消されます。半分だけ有効な状態にはなりません。

PHP から設定値を渡す（ctx.config）

PHP 側で jsModule() を使って渡した値を、ctx.config から読み取れます。

// PHP（プラグインの ServiceProvider::init() や Hook.php の afterBuild() など）
jsModule('myPlugin', [
    'apiEndpoint' => '/api/my-plugin/',
    'maxItems' => '20',
]);

// JavaScript
ACMS.plugins.register('my-plugin', {
  setup(ctx) {
    console.log(ctx.config.apiEndpoint); // '/api/my-plugin/'
  },
});

キーはプラグイン名をキャメルケースに変換したものを使います（my-plugin → myPlugin）。設定が渡されていない場合、ctx.config は空のオブジェクトになります。

値の受け渡しの制約

この値は URL のクエリ文字列として渡される仕組みのため、次の制約があります。

• 数値・真偽値はすべて文字列になります。 PHP の 20（数値）は JavaScript では '20'（文字列）、true / false は '1' / '0' になります。数値として使う場合は Number() で変換してください。
• null はキーごと消えます。 JavaScript 側でそのキー自体が存在しなくなります。
• 入れ子は5段までです。 それより深い構造は正しく復元されません。深い設定を渡したい場合は、フラットなキーにするか、JSON 文字列を1つ渡して JavaScript 側で JSON.parse() してください。

翻訳を追加する（ctx.i18n）

ctx.i18n.addResources(lng, resources) で、プラグインの文言を追加できます。名前空間はプラグイン名に固定されるため、本体や他のプラグインとキーが衝突しません。同じ言語へ何度でも追加でき、既存の内容とマージされます。

ACMS.adminReady(() => {
  ACMS.plugins.register('my-plugin', {
    setup(ctx) {
      ctx.i18n.addResources('ja', { greeting: 'こんにちは' });
      ctx.i18n.addResources('en', { greeting: 'Hello' });
    },
  });
});

参照するときは 名前空間:キー の形で書きます。上の例なら、ACMS.i18n('my-plugin:greeting') が現在の言語の文言を返します。setup(ctx) の実行中は翻訳の準備が終わっていないことがあるため、文言の参照は画面を操作したときの処理（イベントのハンドラなど）の中で行ってください。unregister すると、そのプラグインの翻訳も破棄されます。

キーボードショートカット一覧への追加（ctx.keyboardShortcuts）

registerCategory(id, category) と registerShortcut(id, shortcut) で、キーボードショートカット一覧のモーダルに項目を追加できます。shortcut.categoryId には、同じプラグインで登録したカテゴリーの id を指定します。

デバッグ

• ACMS.plugins.getAll() — 登録内容を確認する。
• 開発中はコンソールの警告を確認してください。 すでに発生済みのイベントを後から購読した場合など、動かない原因になる状況で警告が出ます（本番ビルドでは出ません）。

変更履歴

管理画面の操作に処理を割り込ませる仕組みです。購読できるイベントの一覧は イベント一覧 にあります。

基本の使い方

ACMS.plugins.register('my-plugin', {
  setup(ctx) {
    ctx.events.on('media.upload.success', (event) => {
      console.log(`${event.items.length} 件アップロードされました`);
    });
  },
});

プラグインを作らずに購読することもできます。

ACMS.events.on('media.upload.success', (event) => { /* ... */ });

ただし ctx.events.on() を使うと、プラグインの登録解除時に自動で購読も解除されるため、通常はプラグインの中で書くことを推奨します。

イベント名の読み方

{機能}.{操作}.{タイミング}     例: media.upload.before

タイミングは6種類あります。

イベントには、処理を止められるゲートと、知らせるだけの通知の2種類があります。どちらかは名前では決まらず、イベント一覧 の「種別」列（中止可 / 通知）で確認してください。たとえば unit-editor.command.before は名前が .before で終わりますが、通知のみのイベントです。

処理を止めたり値を書き換えたりできるのは、種別が「中止可」のイベントだけです。 通知イベントのハンドラには中止のための引数が渡されず、戻り値も無視されます。

ゲートでできること

種別が「中止可」のイベントのハンドラは、第2引数に中止用のオブジェクト（以降 gateCtx）を受け取ります。できることは4つです。

ctx.events.on('media.upload.before', async (event, gateCtx) => {
  // 非同期のチェック
  if (!(await isAllowed(event.files))) {
    gateCtx.cancel('この操作は許可されていません');
    return;
  }

  // 中止（理由なし）
  if (event.files.length === 0) {
    gateCtx.cancel();
    return;
  }

  // 値の書き換え（大きすぎるファイルを除く）
  event.files = event.files.filter((file) => file.size < 5_000_000);
});

中止のしかた

• gateCtx.cancel() — 理由を表示せずに中止します。
• gateCtx.cancel('理由') — 理由を添えて中止します。この文字列はそのまま利用者に表示されます（画面によってはダイアログや通知として表示されます）。ユーザーの操作を止める場合は、理由を添える方を推奨します。

cancel() は呼んだ時点で中止が確定します。return false や { cancel: true } のような戻り値では中止できません（jQuery の return false など、別の目的で書いた戻り値で意図せず中止されるのを避けるためです）。

値の書き換えについて

書き換えられる範囲はイベントごとに違います（イベント一覧 の「変更できるもの」列を参照）。たとえば、

• media.update.before — 送信内容（formData）を書き換えられます。
• media.upload.before — すでにあるファイルを除外することはできますが、新しいファイルに差し替えることはできません。
• media.delete.before — 対象の絞り込みはできません。除外したい場合は全体を中止してください。

実行順とルール

• ハンドラは登録順に1つずつ実行されます。並列実行はされません。
• ゲートのイベントでは、前のハンドラが書き換えた値が次のハンドラに渡ります。
• どれか1つのハンドラが gateCtx.cancel() を呼んだ場合、そのハンドラの処理が終わった後、残りのハンドラは実行されません。
• ハンドラの中で例外が発生した場合も中止として扱われ、コンソールにエラーが記録されます。
• 通知イベントでは、あるハンドラが例外を投げても他のハンドラと管理画面の動作は継続します。
• 優先度の指定はありません。 実行順は登録順（＝JS の読み込み順）だけで決まります。

過去のイベントは届きません

ACMS.events は、購読した時点より後に発生したイベントにだけ反応します。すでに発生済みのイベントは再生されません。

そのため、購読はスクリプトの読み込み時にトップレベルで行ってください（プラグイン API の「登録するタイミング」参照）。

起動時の処理を書く

「管理画面の準備ができたら実行したい」処理は、購読より先にすでに完了しているかどうかを確認してください。準備完了は一度しか発生しないため、購読が間に合わないことがあります。

function onAdminReady() {
  // 実行したい処理
}

if (ACMS.readyStates.adminReady === 'complete') {
  onAdminReady();
} else {
  ACMS.events.on('acms.state.admin-ready', onAdminReady);
}

ACMS.Ready() は従来どおり使えます（内部でこの仕組みを使っています）。

従来のイベントとの関係

a-blog cms はこれまで、DOM の CustomEvent（acms.media-updated など）と ACMS.dispatchEvent / ACMS.addListener でイベントを提供してきました。

• 従来のイベントは今後も発火します。 既存のテーマ・プラグインの購読を書き換える必要はありません。
• 新しく書く場合は ACMS.events を使ってください。中止・値の書き換え・非同期の待機は ACMS.events のゲートにしかありません。
• 対応表は イベント一覧 の「従来のイベントとの対応」にあります。

独自のイベントを発火する

ACMS.events.gate() と ACMS.events.notify() は主に a-blog cms 本体が使う API ですが、プラグインが自分のイベントを発火することもできます。一覧に載っていない名前も使えます。

// 発火する側（中止できるイベント）
const result = await ACMS.events.gate('my-plugin.sync.before', { items });
if (result.canceled) {
  if (result.reason) {
    ACMS.Library.dialog.alert(result.reason);
  }
  return;
}

// 発火する側（知らせるだけのイベント）
await ACMS.events.notify('my-plugin.sync.success', { items: result.payload.items });

// 購読する側
ctx.events.on('my-plugin.sync.before', (event, gateCtx) => { /* ... */ });

gate() の戻り値は次の形です。

notify() は戻り値を返しません。

イベント名は {機能}.{操作}.{タイミング} の規約に合わせ、機能名にはプラグイン名を使うと衝突を避けられます。中止できるようにしたい場合は gate() で発火し、名前を .before で終わらせてください。

変更履歴

ACMS.events で購読できるイベントの一覧です。使い方は イベント（ACMS.events） を参照してください。

• 「種別」が 中止可 のイベントは、ハンドラの第2引数 gateCtx の cancel() で操作を中止できます。値の書き換えは、受け取った値のプロパティを直接書き換えて行います（イベント の「ゲートでできること」参照）。
• 「通知」のイベントは、戻り値を返しても無視され、中止もできません。

メディア

エントリー

モジュール

プレビュー・タイムマシン

入力フィールド

同じ種類のフィールドが複数ある画面では、すべてのフィールドの変更が同じイベントで届きます。 どのフィールドかを判定するには target を確認してください。

画面共通の UI

フォームの検証

ユニットエディター

起動

購読より先に完了しているかどうかを確認してください（イベント の「起動時の処理を書く」参照）。

従来のイベントとの対応

以下の DOM イベント（document.addEventListener で購読するもの）と ACMS.dispatchEvent 経由のイベントは、今後も発火します。既存の購読はそのままで動作します。新しく書く場合は右列のイベントを使ってください。

変更履歴

管理画面のあらかじめ決められた位置に、独自のボタンやパネルを追加できます。

差し込み位置（Slot）とは

管理画面の特定の場所に用意された、名前付きの差し込み口です。追加のみができます。 既存のボタンを消したり、置き換えたりはできません。

差し込みは ctx.ui.fill(差し込み位置の名前, 内容) で行います。

DOM で差し込む

React を使わない場合はこちらです。渡された要素に自由に DOM を追加できます。

ACMS.plugins.register('my-plugin', {
  setup(ctx) {
    ctx.ui.fill('media.edit-modal.footer', (el) => {
      const button = document.createElement('button');
      button.type = 'button';
      button.className = 'acms-admin-btn';
      button.textContent = '外部システムに送信';
      button.addEventListener('click', () => sendToExternal());
      el.append(button);

      // 画面が閉じられたときに呼ばれる（省略可）
      return () => button.remove();
    });
  },
});

• 引数 el は、差し込み位置に用意された空の要素です。
• この要素の中身は管理画面側から書き換えられません。 自分で追加した DOM がいつのまにか消えることはありません。
• 戻り値の関数は、その画面が閉じられたときに呼ばれます。イベントリスナーの解除などに使ってください。

差し込み位置が渡す値（下の一覧の「受け取れる値」）を DOM 版で使うことはできません。値が必要な場合は次の React 版を使ってください。

React で差し込む

管理画面と同じ React を使えます。値を受け取らない場合は、引数のないコンポーネントをそのまま渡します。

ACMS.plugins.register('my-plugin', {
  setup(ctx) {
    ctx.ui.fill('preview.actions', function MyButton() {
      return ACMS.Library.React.createElement('button', { type: 'button', className: 'acms-admin-btn' }, '送信');
    });
  },
});

差し込み位置の値を受け取る

編集中のメディアやエディターの情報を受け取りたい場合は、ACMS.plugins.withFillProps() でラップします。

ACMS.plugins.register('my-plugin', {
  setup(ctx) {
    const { withFillProps } = ACMS.plugins;

    ctx.ui.fill(
      'media.edit-modal.field.alt',
      withFillProps(({ item, previewSrc, setAlt }) =>
        ACMS.Library.React.createElement(
          'button',
          {
            type: 'button',
            className: 'acms-admin-btn',
            onClick: async () => {
              const alt = await generateAlt(previewSrc);
              setAlt(alt);
            },
          },
          'alt を自動入力'
        )
      )
    );
  },
});

JSX で書きたい場合は 開発環境と型定義 を参照してください。

差し込み位置の一覧

補足:

• media.edit-modal.field.alt は、管理画面の設定で alt 入力欄を非表示にしている場合、この差し込み位置も一緒に非表示になります。
• setAlt(値) を使うと、入力欄の表示・内部の値・高さの自動調整がまとめて更新されます。getAlt() は現在の値を返します。
• getFormData() は、その時点で保存されようとしている内容を FormData として返します。
• preview.actions は、プレビューのキャプチャまたは共有が有効なときだけ表示されます。

同じ位置に複数のプラグインが差し込んだとき

JS が読み込まれた順に並びます。 優先度の指定はありません。順序を制御したい場合は、アセット API の登録順で調整してください。

差し込む UI の見た目を合わせる

管理画面と同じ見た目にするには、管理画面の CSS クラスをそのまま使えます。

button.className = 'acms-admin-btn acms-admin-btn-primary';

• クラス名の一覧 → スタイルガイド
• 実際の表示とバリエーション → Storybook の Button
• React コンポーネントとして使う → npm パッケージ

変更履歴

「選べるものを増やす」拡張です。ユニットの種類、ブロックの種類、一覧画面のアクションやカラムの型などを追加できます。

イベントとの使い分け

登録できるもの

すべて setup(ctx) の中で呼びます。

ユニットとブロックの追加手順は、専用のガイドを参照してください。

• オリジナルユニットを作る
• オリジナルブロックを作る
• 一覧画面にアクションを追加する

名前の付け方

同じ名前で2回登録するとエラーになります。 他のプラグインと衝突しないよう、プラグイン名を接頭辞にした名前を付けてください。

ctx.dataview.registerAction('entry', 'acme-tools/export', {
  id: 'acme-tools/export',
  label: 'エクスポート',
  onAction: (entry) => {
    window.location.href = `/api/acme-tools/export/?eid=${entry.id}`;
  },
});

一覧画面の登録（registerAction / registerBulkAction / registerMenu）は、第1引数の view ごとに名前が独立しています。'entry' と 'module' で同じ名前を使っても衝突しません。

標準の機能との関係

標準の機能を上書きすると、そのブログ全体に影響します。意図しない場所に影響しないよう、独自の名前を使うことを推奨します。

登録内容を確認する

ACMS.plugins.getAll();
// registrations に、そのプラグインが登録した内容が一覧で入っています

従来の方法との併用

エントリー一覧・モジュール一覧のカスタマイズには、従来から ACMS.Config.entryAdminConfig / moduleAdminConfig の getActions / getBulkActions / getMenus を使う方法があります。

• 従来の方法も今後も動作します。 既存のコードを書き換える必要はありません。
• レジストリで登録した内容は、標準の定義の後ろに追加された状態で従来の関数にも渡ります。そのため両方を併用できます。
• 新しく書く場合はレジストリを推奨します。プラグインの登録解除時に自動で外れるためです。

一覧のカラムの並び替えや削除（getColumns）と表示値の加工（getValues）には、現時点でレジストリの代替がありません。従来の方法を使ってください。

変更履歴