Pickles 2

モジュールテンプレートの書き方

Broccoliモジュールのテンプレートは、Twig テンプレートエンジンを用いて記述することができます。

Twigテンプレートエンジンの適用条件

次の条件が満たされる場合に、Twigテンプレートモジュールであると解釈されます。

  • info.jsoninterface が定義されていること。
  • template.html.twig が設置されていること。

入力欄の定義 (interface)

info.json に、interface をキーに、次のように定義します。

{
    "name": "Sample Module",
    "areaSizeDetection": "shallow",
    "interface": {
        "fields": {
            "text1-1":{
                "fieldType": "input",
                "type":"multitext",
                "rows":4
            },
            "text1-2":{
                "fieldType": "input",
                "type":"multitext",
                "rows":4
            },
            "loop":{
                "fieldType":"loop"
            }
        },
        "subModule":{
            "loop":{
                "fields":{
                    "text2-1":{
                        "fieldType": "input",
                        "type":"multitext",
                        "rows":4
                    } ,
                    "text2-2":{
                        "fieldType": "input",
                        "type":"multitext",
                        "rows":4
                    }
                }
            }
        }
    }
}

interface には、fields と、subModule の2つのオブジェクトを格納します。

interface.fields[$fieldName] に、フィールドを定義します。 フィールドの種類を interface.fields[$fieldName].fieldType に定義します。

フィールドの種類 fieldType は、input (デフォルト)、moduleloop のいずれかです。

fieldTypeloop の場合、interface.subModule に、サブモジュールを登録します。 loop フィールドの $fieldName と、 interface.subModule[$fieldName] とで関連付けられます。interface.subModule[$fieldName][$loopItemFieldName] 以下は、interface.fields の書き方と同じです。

フィールドの種類や詳細な使用方法については、 フィールド一覧 を参照してください。

テンプレートの書式

Twigテンプレートエンジンの書式に従います。詳しくは Twigの公式ドキュメント を参照してください。

次のサンプルは、main と名付けられた入力フィールドのコードを出力する例です。

<div>
{{ main }}
</div>

特別な変数 _ENV

特殊な値として、環境変数 _ENV が渡されます。

_ENV.mode

_ENV.mode には、レンダリングモード名が格納されます。 編集画面では canvas、最終レンダリング時には finalize のいずれかの値が入ります。

{% if _ENV.mode == 'canvas' %}
<div>ここは、編集画面でのみ出力されるコードです。</div>
{% endif %}
{% if _ENV.mode == 'finalize' %}
<div>ここは、編集画面では出力されないコードです。</div>
{% endif %}

_ENV.vars

_ENV.vars には、各フィールドに入力された値が格納されます。ここに格納される値は、 canvas モード時にも finalize モードで評価された値を取ります。

canvas モードでは、フィールドに値が入力されなかった場合、「ダブルクリックして編集してください」のような、ユーザーへ入力欄が存在することを知らせる文言がセットされることがあります。 しかし、テンプレート側では、これがユーザー指定の値なのか空白なのか判断できません。 _ENV.vars には、常に finalize モードの値がセットされるので、このような混乱を避けることができます。

{% if _ENV.vars.hogefuga %}
{{ hogefuga }}
{% else %}
<p>フィールド hogefuga には値が入力されませんでした。</p>
{% endif %}

_ENV.vars は、 Broccoli v0.3.16 で追加されました。

特別な関数

loopフィールドを表現するための関数

loopitem_start($fieldName)loopitem_end()appender($fieldName) の3つの関数は、 loop フィールドの編集インターフェイスを表現するために使用します。

{% for loopRow in loop %}
    {{ loopitem_start('loop') }}
    <div>
        <div>{{ loopRow.text1 }}</div>
        <div>{{ loopRow.text2 }}</div>
    </div>
    {{ loopitem_end() }}
{% endfor %}
{{ appender('loop') }}

loopitem_start($fieldName)loopitem_end()appender($fieldName) は Broccoli v0.3.15 で追加されました。

フィールド名に - (ハイフン) を含む場合の参照

フィールド名に - を含む場合、通常の書き方で参照しようとすると、 - が マイナスの演算記号だと解釈されて正しく値を表示できません。

この場合は、 _context の配列要素としてアクセスする方法があります。

<div>
{{ _context["sample-field-1"] }}
</div>

旧来のBroccoli標準記法

template.html.twig の代わりに template.html が設置されている場合は、旧来のBroccoli標準の記法が適用されます。

旧Broccoli標準記法では、テンプレートファイル template.html の中に、入力欄(interface)の定義とテンプレートをまとめて記述します。 {&&} に囲まれた間に JSON形式のフィールド定義を挟むのが基本書式です。

次の例は、 template.html の記述例です。

<div class="sample-module">
    <div class="sample-module__input1">
        {&{"input":{
            "type": "markdown",
            "name": "markdown-field-1",
            "label": "Markdown入力1"
        }}&}
    </div>
    <div class="sample-module__input2">
        {&{"input":{
            "type": "markdown",
            "name": "markdown-field-2",
            "label": "Markdown入力2"
        }}&}
    </div>
</div>