フィールド は、モジュールに組み込むことができる入力欄のことです。 フィールドには様々な種類があり、それぞれ固有の入力インターフェイスを編集ウィンドウに提供します。 モジュールの設計者は、様々なフィールドを組み合わせて、各々モジュールの表現力、自由度と制約をデザインします。
ここでは、Broccoliで利用できるフィールドの種類と使い方について説明します。
フィールドには、大きく次の種類があります。
input フィールドmodule フィールドloop フィールド加えて、 input フィールドはさらに細かい種類に分かれています。
input フィールドは、もっとも重要なフィールド種別で、編集可能な入力欄を埋め込みます。 type 属性によりさまざまな種類の入力欄を使い分けることができます。
下記は実装例です。
info.json の interface に次のように実装します。
{
"interface": {
"fields": {
"fieldname1": {
"fieldType": "input",
"type":"html",
"rows":5,
"label":"HTML入力欄のサンプル",
"hidden":false,
"description": "HTMLコードを入力してください。",
"default": "<p>入力例。</p>",
"validate": [
"required"
]
}
}
}
}
template.html.twig では、次のように呼び出します。
{{ fieldname1 }}
interface.fields のキーとなる文字列 (例では fieldname1 に当たる部分)は、入力欄の物理名称として使用されます。この値により、コンテンツデータとフィールド情報とを関連付けるキーとして利用されます。 この名前が変更されると、すでに使用しているモジュールでリンクが切れ、入力した値が適用されなくなることがあるので注意してください。 _ENV は予約語のため使用できません。
下記の設定値は、ほとんどの input フィールドで共通で利用できます。
type 属性に指定できるフィールドの種類には、次のものがあります。
module フィールドは、別のモジュールをネスト可能な領域を埋め込みます。
module フィールドを配置すると、レイアウトビュー画面上にブルーのバー(アペンダー)が現れ、モジュールをドロップして追加することができるようになります。
{
"interface": {
"fields": {
"modulesample1":{
"fieldType": "module",
"label": "モジュールフィールドのサンプル"
}
}
}
}
template.html.twig では、次のように呼び出します。
{{ modulesample1 }}
input フィールドと同様、 interface.fields のキーとなる文字列 (例では modulesample1 に当たる部分)は、入力欄の物理名称として使用されます。
その他、次のオプションが利用できます。
loop フィールドは、編集者が任意の回数繰り返し記述できる領域を定義します。
loop フィールドを配置すると、レイアウトビュー画面上にグリーンのバー(アペンダー)が現れ、ダブルクリックで繰り返し領域を追加します。
info.json では、 interface に加えて subModule の定義も必要です。次のように記述します。
{
"interface": {
"fields": {
"loopsample1": {
"fieldType": "loop",
"label":"ループフィールドのサンプル"
}
},
"subModule": {
"loopsample1":{
"fields":{
"text1inloop":{
"fieldType": "input",
"type":"multitext",
"rows":4
} ,
"text2inloop":{
"fieldType": "input",
"type":"multitext",
"rows":4
}
}
}
}
}
}
template.html.twig では、次のように呼び出します。
loop フィールドの編集インターフェイスを表現するために、 loopitem_start($fieldName)、 loopitem_end()、 appender($fieldName) の3つの関数を使用します。
{% for loopRow in loopsample1 %}
{{ loopitem_start('loopsample1') }}
<div>
<div>{{ loopRow.text1inloop }}</div>
<div>{{ loopRow.text2inloop }}</div>
</div>
{{ loopitem_end() }}
{% endfor %}
{{ appender('loopsample1') }}
loopitem_start($fieldName)、 loopitem_end()、 appender($fieldName) は Broccoli v0.3.15 で追加されました。
その他、次のオプションが利用できます。
Twigテンプレートによる書き方は、比較的新しいバージョンで導入された機能です。 それ以前は、 Broccoli標準記法でテンプレートを記述していました。
info.json に interface が定義されておらず、 template.html.twig の代わりに template.html が存在する場合に、 旧Broccoli標準記法として処理されます。
旧Broccoli標準記法では、 input、 module、 loop に加えて、次の種類があります。
if フィールドecho フィールド旧Broccoli標準記法では、 template.html に 次のように定義します。
{&{"input":{
"type":"html",
"name":"fieldname1",
"rows":5,
"label":"HTML入力欄のサンプル",
"hidden":false,
"description": "HTMLコードを入力してください。",
"default": "<p>入力例。</p>",
"validate": [
"required"
]
}}&}
オプションとなる項目については Twigテンプレートを利用する場合と概ね共通です。
次の項目は、旧Broccoli標準記法に特有の項目です。
name 値を変更すると、すでに使用しているモジュールでリンクが切れ、入力した値が適用されなくなることがあるので注意してください。 _ENV は予約語のため、name に使用できません。trueを指定すると、入力欄は表示されますが、HTML上には出力されないようになります。 if フィールド や echo フィールドと組み合わせて使用する場合に、trueをセットしてください。デフォルトは false です。旧Broccoli標準記法では、 template.html に 次のように定義します。
<!-- 実装例 -->
<div class="unit">
{&{"module":{"name":"main","label":"メインエリア"}}&}
<!-- /.unit --></div>
name の値により、コンテンツデータとフィールド情報とを関連付けるキーとして利用されますので、モジュールごとに重複のないように命名してください。
オプションとなる項目については Twigテンプレートを利用する場合と概ね共通です。
次の項目は、旧Broccoli標準記法に特有の項目です。
input フィールドの説明を参照ください。hidden に true を設定して隠し、 if フィールド と echo フィールド を組み合わせて出力制御することができます。旧Broccoli標準記法では、 template.html に 次のように定義します。
<!-- 実装例 -->
<ul>
{&{"loop":{"name":"thumb_loop", "label":"サムネイルリスト"}}&}
<li>リスト</li>
{&"endloop"&}
</ul>
定義領域の終了は、{&"endloop"&} で宣言します。
name の値により、コンテンツデータとフィールド情報とを関連付けるキーとして利用されますので、モジュールごとに重複のないように命名してください。
オプションとなる項目については Twigテンプレートを利用する場合と概ね共通です。
次の項目は、旧Broccoli標準記法に特有の項目です。
input フィールドの説明を参照ください。hidden に true を設定して隠し、 if フィールド と echo フィールド を組み合わせて出力制御することができます。indexに指定した文字列が参照名になります。 同じ文字列を echo フィールドのref に指定して出力します。 一般的な配列処理と異なり、 通し番号は 1 から開始されます。ifフィールドは、与えた条件が真の場合にのみ、出力される領域を定義します。
条件分岐領域の終了は、{&"endif"&} で宣言します。
使用できる条件を説明します。
条件式を配列で指定します。
condは2次元配列です。1次元目は or 条件、2次元目は and 条件として評価されます。
<!-- 実装例 -->
{&{"input":{"type":"html","name":"sample1","label":"サンプル1"}}&}
{&{"input":{"type":"html","name":"sample2","label":"サンプル2"}}&}
{&{"if":{"cond":[
[
"is_set:sample1",
"sample2==123"
]
]}}&}
<p>この部分は、sample1 に値が入力され、
かつ sample2 に 123 を入力した場合のみ出力されます。</p>
{&"endif"&}
{&{"if":{"cond":[
[
"sample1==123",
"sample2!=123"
]
]}}&}
<p>この部分は、sample1 に 123 が入力され、
かつ sample2 に 123 以外の値が入力された場合のみ出力されます。</p>
{&"endif"&}
is_mode:canvas と is_mode:finalize は、編集画面描画時 または 最終描画時 の条件によって出力内容を分岐する条件として利用できます。
<!-- 編集画面にのみ表示する実装例 -->
{&{"if":{"cond":[
["is_mode:canvas"]
]}}&}
<p>この部分は、編集画面でのみ表示されます。</p>
{&"endif"&}
<!-- 編集画面には表示しない実装例 -->
{&{"if":{"cond":[
["is_mode:finalize"]
]}}&}
<p>この部分は、最終描画時のみ表示され、
編集画面では表示されません。</p>
{&"endif"&}
指定した名前のフィールドに値がセットされている場合に、内容を表示します。
<!-- 実装例 -->
{&{"input":{"type":"html","name":"sample1","label":"サンプル1"}}&}
{&{"if":{"is_set":"sample1"}}&}
<p>この部分は、sample1 に値を入力した場合のみ出力されます。</p>
{&"endif"&}
ifフィールドは、 elseifフィールド, elseフィールド と組み合わせて複数の条件を定義することができます。
<!-- 実装例 -->
{&{"input":{"type":"html","name":"sample1","label":"サンプル1"}}&}
{&{"if":{"cond": [
[
"sample1==123"
]
]}}&}
<p>この部分は、sample1 に値 123 を入力した場合のみ出力されます。</p>
{&{"elseif":{"cond": [
[
"sample1==456"
]
]}}&}
<p>この部分は、sample1 に値 456 を入力した場合のみ出力されます。</p>
{&"else"&}
<p>この部分は、その他の場合のみ出力されます。</p>
{&"endif"&}
echoフィールドは、別のフィールドで入力された値を出力します。
<!-- 実装例 -->
{&{"input": {
"type": "html",
"name": "sample1",
"label": "サンプル1",
"hidden": true
}}&}
{&{"echo":{"ref":"sample1"}}&}
この例は、HTML入力欄 sample1 の値を、後で出力しています。
HTML入力欄自体は、"hidden":true で隠しているので、結果として、入力値は1回だけ出力されます。