アセット 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() は出力の組み立て前に呼ばれるため、ここで登録すれば間に合います。
メソッド
メソッド | 説明 |
|---|---|
|
|
|
|
| インラインの |
| インラインの |
| 組み立て済みの HTML をそのまま登録する |
| 登録済みかどうかを判定する |
| 登録を取り消す |
ハンドル
第1引数のハンドルは、そのアセットを識別する名前です。他と重複しない名前を付けてください（プラグイン名を接頭辞にするのが安全です）。
すでに同じハンドルが登録されている場合、後から登録した方は無視されます（ログに記録されます）。差し替えたい場合は Asset::dequeue() で先に取り消してください。
オプション
キー | 型 | 説明 |
|---|---|---|
| string[] | 依存するハンドルの配列。指定したアセットより後に出力されます |
| string | 出力位置。 |
| array | タグに付ける属性。 |
| string / null | URL に付けるクエリ（キャッシュ対策）。ローカルのファイルは自動で付与されます |
deps は同じ position の中での順序を保証します。head と body_end をまたいだ依存指定はできません。
標準で読み込まれているアセット
依存関係の指定に使えるハンドルです。
ハンドル | 内容 |
|---|---|
| a-blog cms の基本スクリプト（設定値を含む） |
| サイト表示側の外部ライブラリ |
| サイト表示側のスクリプト |
| 管理画面の外部ライブラリ |
| 管理画面のスクリプト |
// 管理画面のスクリプトの後に読み込む
Asset::script('my-admin-tool', '/extension/acms/assets/admin-tool.js', [
'deps' => ['acms-admin'],
]);
標準のアセットを dequeue() で止めないでください
Asset::dequeue('acms-admin') のように標準のアセットを取り消すことは技術的には可能ですが、管理画面が動作しなくなります。サポート対象外です。
管理画面のプラグインを読み込む
管理画面の JavaScript 拡張を読み込む場合は、attrs に type="module" を指定してください。プラグインの登録が管理画面の処理より先に実行されることが保証されます。
Asset::script('my-plugin', '/extension/acms/assets/my-plugin.js', [
'position' => 'body_end',
'attrs' => ['type' => 'module'],
]);
複数のプラグインを読み込む場合、この API を呼んだ順にスクリプトが出力され、その順にイベントの処理が実行されます。
管理画面のテンプレートに HTML を差し込む場合
JS / CSS ではなく、管理画面に HTML を差し込みたい場合は テンプレート挿入 を使ってください。