管理画面の JavaScript 拡張
a-blog cms の管理画面に、独自の処理と UI を差し込めます。CMS 本体のファイルを書き換えずに、プラグインまたはテーマから JavaScript を1ファイル追加するだけで動きます。
実験的機能
この機能は、Ver. 3.2 の間は実験的機能として提供し、Ver. 3.3 で正式に提供する予定です。イベント名・イベントが受け取る値の構造・Slot 名・登録 API の引数は、マイナーバージョンアップで変更される可能性があります。
管理画面に追加した独自の JavaScript・CSS は、バージョンアップ後の動作を保証しません。これらを原因とする不具合は、サポートの対象外です。
このドキュメントに掲載されているイベント名・Slot 名・登録名を公開 API として扱います。掲載外のものも利用できますが、告知なく変更されることがあります。
従来の連携方法（ACMS.addListener と acms.media-updated などの DOM イベント）は今後も動作します。既存のテーマやプラグインを書き換える必要はありません。
PHP 側のフック処理・テンプレート挿入・アセット API は、この実験的機能の対象外です。従来どおりの仕様として提供しています。
できること
拡張の方法は3種類あります。
処理に割り込む（イベント）
管理画面の操作の前後に、自分の処理を挟めます。操作の直前に呼ばれるイベント（ゲート）では、操作を中止させたり、送信内容を書き換えたり、非同期の処理を待たせたりできます。どのイベントがゲートかは イベント一覧 で確認できます。
ACMS.adminReady(() => {
ACMS.plugins.register('my-plugin', {
setup(ctx) {
// 画像をアップロードする直前に確認する
ctx.events.on('media.upload.before', async (payload, gate) => {
const ok = await ACMS.Library.dialog.confirm(`${payload.files.length} 件をアップロードします`);
if (!ok) {
gate.cancel(); // 呼ぶとアップロードを中止する
}
});
},
});
});プラグインは、管理画面の JavaScript の準備が終わってから登録するため、ACMS.adminReady() の中に書きます。理由は はじめてのプラグイン で説明しています。
UI を差し込む（Slot / Fill）
管理画面のあらかじめ決められた位置に、ボタンやパネルを追加できます。
ACMS.adminReady(() => {
ACMS.plugins.register('my-plugin', {
setup(ctx) {
// メディア詳細の alt 入力欄の直後にボタンを追加する
ctx.ui.fill('media.edit-modal.field.alt', (el) => {
const button = document.createElement('button');
button.type = 'button';
button.className = 'acms-admin-btn';
button.textContent = 'alt を生成';
el.append(button);
return () => button.remove();
});
},
});
});種類を増やす（レジストリ）
ユニットの種類、ブロックの種類、一覧画面のアクションやカラムの型など、「選べるものを増やす」拡張です。
ACMS.adminReady(() => {
ACMS.plugins.register('my-plugin', {
setup(ctx) {
// エントリー一覧の各行にボタンを追加する
ctx.dataview.registerAction('entry', 'my-plugin/show-title', {
id: 'my-plugin/show-title',
label: 'タイトルを確認',
onAction: (entry) => {
ACMS.Library.dialog.alert(entry.title);
},
});
},
});
});JavaScript 側と PHP 側の役割
管理画面の見た目と操作は JavaScript、データの保存と表示側の出力は PHP が担当します。どちらを触るかは、追加したいものによって決まります。
| 追加したいもの | JavaScript | PHP |
|---|---|---|
| 操作への割り込み（保存前のチェックなど） | 必要 | 不要 |
| 管理画面へのボタン・パネル追加 | 必要 | 不要 |
| 一覧画面のアクション・カラム | 必要 | 不要 |
| オリジナルブロック | 必要 | 不要（独自タグを使う場合はサニタイズの許可設定のみ） |
| オリジナルユニット | 必要 | 必要（保存データを扱うため） |
| プラグインの設定値を JavaScript に渡す | 受け取り側 | 渡す側 |
オリジナルユニットだけは PHP の実装が必須です。登録を忘れると保存したデータが失われるため、オリジナルユニットを作る の手順に沿って作業してください。
必要な環境
- ビルド環境は不要です。
window.ACMSから必要な API をすべて呼び出せます。 - React も必須ではありません。UI を差し込むときは DOM 操作でも書けます。
- TypeScript の型補完を受けたい場合や、管理画面の React コンポーネントを使いたい場合は npm パッケージを利用できます → 開発環境と型定義
次に読むページ
- はじめてのプラグイン — まず1つ動かす（最初にここ）
- ガイド — 目的別の手順 - 一覧画面にアクションを追加する - アップロード前にチェックを入れる - オリジナルブロックを作る - オリジナルユニットを作る - 管理画面と同じ見た目で画面を作る
- リファレンス — 引くための資料 - プラグイン API - イベント（ACMS.events） / イベント一覧 - UI の差し込み（Slot / Fill） - 機能の登録（レジストリ）
- 拡張の仕組みと設計方針 — なぜこの3種類に分かれているのか