V2 GETモジュールとは
V2 GETモジュールは、Twig テンプレート と連携する新しい形式の GET モジュールです。従来の GET モジュールと異なり、連想配列を返す ことで Twig 側で柔軟に表示を制御できます。
項目 | 従来の GET モジュール | V2 GET モジュール |
|---|
基底クラス | ACMS_GET
| Acms\Modules\Get\V2\Base
|
戻り値 | 文字列（HTML 等） | 配列（構造化データ） |
テンプレート | 独自テンプレートエンジン | Twig |
呼び出し | <!-- BEGIN_MODULE -->
| module() 関数
|
ディレクトリ構造
独自 V2 モジュールは extension/acms/Modules/Get/V2/ に配置します。名前空間は Acms\Custom\Modules\Get\V2、オートロード済みのため require は不要です。
extension/acms/Modules/Get/V2/
└── Sample.php
雛形と規約
雛形
<?php
namespace Acms\Custom\Modules\Get\V2;
use Acms\Modules\Get\V2\Base;
/**
* extension/acms/Modules/Get/V2/Sample.php
*
* テンプレート上では、Twig の module() 関数で呼び出されます。
*/
class Sample extends Base
{
public function get(): array
{
return [
'moduleTest' => 'Sample',
];
}
}
クラス
モジュール名とクラス名の対応
テンプレートで使用するモジュール名は アンダースコア区切り です。モジュール名の _ は名前空間・クラス名の \ に対応します。
モジュール名 | クラス名 | ファイルパス |
|---|
V2_Sample
| Acms\Custom\Modules\Get\V2\Sample
| Modules/Get/V2/Sample.php
|
V2_Own_Sample
| Acms\Custom\Modules\Get\V2\Own\Sample
| Modules/Get/V2/Own/Sample.php
|
extension/acms の独自モジュールは Acms\Custom\Modules 名前空間で解決され、標準モジュールより 後 に検索されるため、同名で上書き可能です。
出力
get() メソッドで 配列 を return します。文字列は返しません。
public function get(): array
{
return [
'items' => [...],
'count' => 10,
];
}
実行例
テンプレート（Twig）
{% set result = module('V2_Sample') %}
<p>{{ result.moduleTest }}</p>
実行結果
<p>Sample</p>
module() 関数
Twig テンプレートでは module() 関数で V2 モジュールを呼び出します。
{% set data = module(モジュール名, 識別子, コンテキスト) %}
引数 | 型 | 説明 |
|---|
第1引数 | string | モジュール名（例: 'V2_Sample'） |
第2引数 | string|null | モジュールIDの識別子。使わない場合は null |
第3引数 | array | 外部コンテキストの指定 |
{% set result = module('V2_Sample', 'my-sample', {
cid: 1,
page: 1,
limit: 10,
keyword: null,
tag: null,
field: null,
order: null,
start: null,
end: null
}) %}
モジュールID化
GETモジュールのID化 を参照してください
Base クラスのプロパティ
Acms\Modules\Get\V2\Base を継承したモジュールで利用できるプロパティです。
URL コンテキスト関連
プロパティ | 型 | 説明 |
|---|
$this->bid
| int|null | ブログID |
$this->bids
| int[] | ブログIDの配列 |
$this->cid
| int|null | カテゴリーID |
$this->cids
| int[] | カテゴリーIDの配列 |
$this->eid
| int|null | エントリーID |
$this->eids
| int[] | エントリーIDの配列 |
$this->uid
| int|null | ユーザーID |
$this->uids
| int[] | ユーザーIDの配列 |
$this->page
| int | ページ番号 |
$this->limit
| int|null | 取得件数 |
$this->keyword
| string | キーワード |
$this->tag
| string | タグ |
$this->tags
| string[] | タグの配列 |
$this->field
| string | フィールド検索 |
$this->Field
| Field_Search | フィールド検索オブジェクト |
$this->order
| string | 並び順 |
$this->start
| string | 検索開始日時 |
$this->end
| string | 検索終了日時 |
その他
プロパティ | 型 | 説明 |
|---|
$this->Get
| Field | GET パラメータ |
$this->Post
| Field_Validation | POST データ |
$this->moduleContext
| Field | モジュールコンテキスト |
$this->mid
| int|null | モジュールID |
$this->mbid
| int|null | モジュールIDのブログID |
$this->identifier
| string|null | モジュールID識別子 |
スコープと階層
スコープ（scopes）
$scopes で、URL コンテキストを local か global で取得するかを制御します。
protected $scopes = [
'uid' => 'global',
'cid' => 'global',
'eid' => 'global',
'keyword' => 'global',
'tag' => 'global',
'field' => 'global',
'start' => 'global',
'end' => 'global',
'page' => 'global',
'order' => 'global',
];
階層（axis）
$axis で、ブログ・カテゴリーの階層を指定します。
protected $axis = [
'bid' => 'self', // self | descendant-or-self | ancestor-or-self
'cid' => 'self',
];
モジュールIDのコンフィグ
モジュールIDに紐づく設定を読み込むには loadModuleConfig() を使用します。
public function get(): array
{
$config = $this->loadModuleConfig();
$limit = (int) $config->get('my_limit', 10);
$order = $config->get('my_order', 'datetime-desc');
// ...
}
ヘルパーメソッド
基本パラメータをまとめて取得するには getBaseParams() を使用します。
$params = $this->getBaseParams();
// bid, bids, cid, cids, eid, eids, uid, uids, field, keyword, tag, tags,
// start, end, page, order, limit, blogAxis, categoryAxis を含む配列
その他
カスタムフィールド
モジュールIDでカスタムフィールドを有効にしている場合、buildModuleField() でフィールドデータを取得できます。$this->customFieldsEnabled が true かつ $this->mid が設定されている場合に有効です。
$fields = $this->buildModuleField();
キャッシュ
$this->cacheLifetime が 0 より大きく、$this->identifier が設定されている場合、モジュールの実行結果がキャッシュされます。モジュールID使用時に自動的に有効化されます。
フック
V2 モジュール実行後には afterV2GetFire フックが呼ばれます。拡張アプリ等でフックを登録している場合は、レスポンス配列を加工できます。
// フックの引数: [ &$response, $this ]
管理画面でのデバッグ表示
管理者としてログインしている場合、実行結果に moduleInfo が付与されます。テンプレートで設定画面へのリンクなどを表示できます。
{{ include('/admin/module/setting.twig', { moduleInfo: result.moduleInfo }) }}
