テンプレートの挿入

拡張アプリで様々な拡張をする場合、プログラムだけではなく管理ページを拡張したい場合があると思います。例えば、モジュールID化したいため、モジュール選択肢のテンプレートを拡張したい、拡張アプリ用の管理画面ページ（設定ページ）を作りたいなどです。

対応バージョン: Ver. 3.2 .24 で、差し込みエントリーに callable（HTML を返す関数）を渡せるようになりました。

仕組み

差し込みポイントは、システムテーマのテンプレートに置かれた Admin_InjectTemplate モジュールです。id 属性が差し込みポイントの種別になります。

<!-- BEGIN_MODULE Admin_InjectTemplate id="admin-main" --><!-- END_MODULE Admin_InjectTemplate -->

プラグインは InjectTemplate::add() で「この $type のときはこの内容を出す」と登録します。管理画面の描画時に、登録された内容がこの位置へ差し込まれます。

API

Acms\Services\Common\InjectTemplate はシングルトンです。singleton() で取得して使います。

add(string $type, string|callable $entry): void

差し込みポイント $type に内容を登録します。同じ $type に複数回登録でき、登録順に出力されます。

$entry は次のどちらかを渡せます。

use Acms\Services\Common\InjectTemplate;
use Acms\Services\Facades\Twig;

$inject = InjectTemplate::singleton();

// (1) 標準テンプレートのパスを渡す（従来の方法）
$inject->add('admin-module-select', PLUGIN_DIR . 'MyPlugin/template/module-select.html');

// (2) callable を渡して Twig の描画結果を差し込む
$inject->add('admin-main', static function (): string {
    return Twig::renderTemplate('@myplugin/admin/main.twig');
});

get(string $type): array

$type に登録されたエントリーの配列を返します。通常はフレームワーク側が描画時に呼ぶため、拡張側で直接使う場面は多くありません。

利用できる差し込みポイント

標準で用意されている主な $type です。配置場所はシステムテーマのテンプレートです。

admin-module-config-{モジュール名} の {モジュール名} には、対象モジュールの名前が入ります（例: admin-module-config-Sample）。

差し込みポイントは利用テーマ側のテンプレートにも置けます。独自の差し込みポイントを増やしたい場合は、テンプレートに Admin_InjectTemplate モジュールを id 付きで配置し、同じ id を $type として add() してください。

callable と文字列パスの使い分け

• Twig テンプレートで画面を組むなら callable を渡し、その中で Twig::renderTemplate() を呼びます。

• 既存の 標準テンプレートを差し込むなら文字列パスを渡します。従来どおりの書き方です。

• callable が空文字を返した場合、その分は出力されません。条件によって出し分けたいときに利用できます。

注意点

• callable は管理画面の描画時に実行されます。重い処理を避け、表示に必要な HTML を返すことに徹してください。

• 文字列パスと callable は同じ $type に混在できます。登録順に連結されます。

関連ドキュメント

• プラグイン（拡張アプリ）で Twig 管理画面を作る

• Twig 拡張 API

• 拡張アプリの開発