Broccoliモジュールのテンプレートは、Twig テンプレートエンジンを用いて記述することができます。
次の条件が満たされる場合に、Twigテンプレートモジュールであると解釈されます。
info.json に interface が定義されていること。template.html.twig が設置されていること。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 (デフォルト)、module、loop のいずれかです。
fieldType が loop の場合、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 で追加されました。
_ENV.lang_ENV.lang には、編集画面の言語設定が格納されます。
_ENV.lang は、 Broccoli v0.4.4 で追加されました。
_ENV.data_ENV.data には、編集画面から入力されたデータが格納されます。
_ENV.data.modId にはモジュールIDが格納されます。_ENV.data.fields[fieldName] には各フィールドの入力データが格納されます。_ENV.data.anchor には、モジュールのアンカー名が格納されます。_ENV.data.dec には各フィールドの埋め込みコメントが格納されます。_ENV.data は、 Broccoli v0.4.4 で追加されました。
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>
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>