アセット API（JS / CSS の登録及び読み込み）

JavaScript / CSS ファイルを、ハンドル（名前）と依存関係で宣言して読み込む API です。

これまで Hook.php の afterBuild($res) でレスポンスの HTML を文字列置換して <script> を差し込んでいた作業を、この API に置き換えられます。読み込み順は依存関係から自動的に決まります。

対応バージョン: Ver. 3.2.29 以降

基本の使い方

use Acms\Services\Facades\Asset;

Asset::script('my-plugin', '/extension/acms/assets/my-plugin.js', [
    'position' => 'body_end',
    'attrs' => ['type' => 'module'],
]);

出力は </body> の直前に差し込まれます。

どこから呼ぶか

// extension/acms/Hook.php
public function afterBuild(&$res)
{
    // エントリー詳細ページだけで読み込む
    if (defined('VIEW') && VIEW === 'entry') {
        \Acms\Services\Facades\Asset::script('my-entry-script', '/extension/acms/assets/entry.js', [
            'deps' => ['acms-vendor'],
            'position' => 'body_end',
        ]);
    }
}

afterBuild() は出力の組み立て前に呼ばれるため、ここで登録すれば間に合います。

メソッド

ハンドル

第1引数のハンドルは、そのアセットを識別する名前です。他と重複しない名前を付けてください（プラグイン名を接頭辞にするのが安全です）。

すでに同じハンドルが登録されている場合、後から登録した方は無視されます（ログに記録されます）。差し替えたい場合は Asset::dequeue() で先に取り消してください。

オプション

deps は同じ position の中での順序を保証します。head と body_end をまたいだ依存指定はできません。

標準で読み込まれているアセット

依存関係の指定に使えるハンドルです。

acms-admin は position が head のアセットです。Asset::script() の position の既定は body_end なので、上の例のままでは別の位置への依存指定となり、依存は無視されます（ログに「不明なハンドル」の通知が残ります）。依存を効かせるには 'position' => 'head' を付けます。

// 管理画面のスクリプトの後に出力する（同じ head 内で並べる）
Asset::script('my-admin-tool', '/extension/acms/assets/admin-tool.js', [
    'position' => 'head',
    'deps' => ['acms-admin'],
]);

deps が保証するのは HTML 上の出力順だけです。acms-admin は async 付きのため、deps に指定しても実行の順序までは保証されません。管理画面のスクリプトの初期化後に動かしたい処理は、「管理画面のプラグインを読み込む」の書き方（ACMS.adminReady()）を使ってください。

管理画面のプラグインを読み込む

管理画面の JavaScript 拡張を読み込む場合は、attrs に type="module" を指定してください。module スクリプトは HTML の解析が終わった後、DOMContentLoaded より前に実行されます。

ただし、管理画面のスクリプト（acms-admin）は async 付きで読み込まれるため、実行されるタイミングは保証されません。プラグインのスクリプトより先に実行される場合もあれば、後になる場合もあります。プラグインのスクリプトが先に実行された場合、その時点では ACMS.plugins や ACMS.Library はまだありません。ACMS.adminReady() で管理画面の初期化完了を待ってから登録してください。

Asset::script('my-plugin', '/extension/acms/assets/my-plugin.js', [
    'position' => 'body_end',
    'attrs' => ['type' => 'module'],
]);

// /extension/acms/assets/my-plugin.js（type="module" で読み込む）
ACMS.adminReady(() => {
  ACMS.plugins.register('my-plugin', {
    setup(ctx) {
      // ここでイベントの購読・UI の差し込みなどを行う
    },
  });
});

ACMS.adminReady() で待った場合は、管理画面の初期化が終わった後の登録になります。イベントの購読や UI の差し込みは問題ありませんが、ユニット定義（registerUnitDefinition）のように管理画面の初期化時に読み出される登録は、反映されているかを確認してください。

ACMS.adminReady() は、管理画面の初期化が終わっていればすぐに、まだなら終わるのを待ってから、コールバックを呼びます。公開側のページ（ログインしていない訪問者など、管理画面のスクリプトが読み込まれない場合）ではコールバックが呼ばれないため、上のコードは何もしません。

複数のプラグインを読み込む場合、この API を呼んだ順にスクリプトが出力され、その順にイベントの処理が実行されます。

→ 管理画面の JavaScript 拡張（拡張ポイント一覧）

管理画面のテンプレートに HTML を差し込む場合

JS / CSS ではなく、管理画面に HTML を差し込みたい場合は テンプレート挿入 を使ってください。