V2 GET モジュールの開発

V2 GETモジュールとは

V2 GETモジュールは、Twig テンプレート と連携する新しい形式の GET モジュールです。従来の GET モジュールと異なり、連想配列を返す ことで Twig 側で柔軟に表示を制御できます。

ディレクトリ構造

独自 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',
        ];
    }
}

クラス

• Acms\Modules\Get\V2\Base を継承する

• ファイルのパスと命名規則は PSR4 に従う

• extension/acms の名前空間は Acms\Custom\Modules\Get\V2

モジュール名とクラス名の対応

テンプレートで使用するモジュール名は アンダースコア区切り です。モジュール名の _ は名前空間・クラス名の \ に対応します。

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(モジュール名, 識別子, コンテキスト) %}

{% 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 コンテキスト関連

その他

スコープと階層

スコープ（scopes）

$scopes で、URL コンテキストを local か global で取得するかを制御します。

• global: URL の情報を優先（表示ページのコンテキスト）

• local: モジュールIDの設定やテンプレート指定を優先

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 }) }}