Pickles 2

フィールド一覧

フィールド は、モジュールに組み込むことができる入力欄のことです。 フィールドには様々な種類があり、それぞれ固有の入力インターフェイスを編集ウィンドウに提供します。 モジュールの設計者は、様々なフィールドを組み合わせて、各々モジュールの表現力、自由度と制約をデザインします。

ここでは、Broccoliで利用できるフィールドの種類と使い方について説明します。

フィールドの種類

フィールドには、大きく次の種類があります。

  • input フィールド
  • module フィールド
  • loop フィールド

加えて、 input フィールドはさらに細かい種類に分かれています。

inputフィールド

input フィールドは、もっとも重要なフィールド種別で、編集可能な入力欄を埋め込みます。 type 属性によりさまざまな種類の入力欄を使い分けることができます。

下記は実装例です。

info.jsoninterface に次のように実装します。

{
  "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
inputフィールドの入力欄の種類を指定します。
rows
生成される入力欄の行数を指定します。
label
編集画面に表示される入力欄の名称を指定します。
description
フィールドの説明をMarkdown形式で記述します。
default
デフォルトの値を設定します。値の形式は、typeごとに異なります。
validate
入力された値を検査するルールを指定します。 validatorjs に定義されたバリデーションルールが利用できます。
このオプションは、 Broccoli v0.3.15 で追加されました。

inputフィールドの種類

type 属性に指定できるフィールドの種類には、次のものがあります。

moduleフィールド

module フィールドは、別のモジュールをネスト可能な領域を埋め込みます。

module フィールドを配置すると、レイアウトビュー画面上にブルーのバー(アペンダー)が現れ、モジュールをドロップして追加することができるようになります。

{
    "interface": {
        "fields": {
            "modulesample1":{
                "fieldType": "module"
            }
        }
    }
}

template.html.twig では、次のように呼び出します。

{{ modulesample1 }}

input フィールドと同様、 interface.fields のキーとなる文字列 (例では modulesample1 に当たる部分)は、入力欄の物理名称として使用されます。

その他、次のオプションが利用できます。

maxLength
内包できるモジュール数の上限を設定します。
enabledChildren
このmoduleフィールドに内包できるモジュールのIDを指定します。文字列または配列で複数指定可能です。 パッケージ名は省略できます。

loopフィールド

loop フィールドは、編集者が任意の回数繰り返し記述できる領域を定義します。

loop フィールドを配置すると、レイアウトビュー画面上にグリーンのバー(アペンダー)が現れ、ダブルクリックで繰り返し領域を追加します。

info.json では、 interface に加えて subModule の定義も必要です。次のように記述します。

{
  "interface": {
    "fields": {
      "loopsample1": {
        "fieldType": "loop",
        "label":"ループフィールドのサンプル"
      }
    },
    "subModule": {
      "loopsample1":{
        "fields":{
          "text2-1":{
            "fieldType": "input",
            "type":"multitext",
            "rows":4
          } ,
          "text2-2":{
            "fieldType": "input",
            "type":"multitext",
            "rows":4
          }
        }
      }
    }
  }
}

template.html.twig では、次のように呼び出します。

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

{% 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 で追加されました。

その他、次のオプションが利用できます。

maxLength
内包できるモジュール数の上限を設定します。

旧Broccoli標準記法での書き方

Twigテンプレートによる書き方は、比較的新しいバージョンで導入された機能です。 それ以前は、 Broccoli標準記法でテンプレートを記述していました。

info.jsoninterface が定義されておらず、 template.html.twig の代わりに template.html が存在する場合に、 旧Broccoli標準記法として処理されます。

フィールドの種類

旧Broccoli標準記法では、 inputmoduleloop に加えて、次の種類があります。

  • if フィールド
  • echo フィールド

inputフィールド (旧Broccoli標準記法)

旧Broccoli標準記法では、 template.html に 次のように定義します。

{&{"input":{
  "type":"html",
  "name":"fieldname1",
  "rows":5,
  "label":"HTML入力欄のサンプル",
  "hidden":false,
  "description": "HTMLコードを入力してください。",
  "default": "<p>入力例。</p>",
  "validate": [
    "required"
  ]
}}&}

オプションとなる項目については Twigテンプレートを利用する場合と概ね共通です。

次の項目は、旧Broccoli標準記法に特有の項目です。

name
入力欄の物理名称を付与します。編集画面上には表示されません。この値により、コンテンツデータとフィールド情報とを関連付けるキーとして利用されますので、モジュールごとに重複のないように命名してください。 name 値を変更すると、すでに使用しているモジュールでリンクが切れ、入力した値が適用されなくなることがあるので注意してください。 _ENV は予約語のため、name に使用できません。
hidden
この設定にtrueを指定すると、入力欄は表示されますが、HTML上には出力されないようになります。 if フィールド や echo フィールドと組み合わせて使用する場合に、trueをセットしてください。デフォルトは false です。

moduleフィールド (旧Broccoli標準記法)

旧Broccoli標準記法では、 template.html に 次のように定義します。

<!-- 実装例 -->
<div class="unit">
{&{"module":{"name":"main","label":"メインエリア"}}&}
<!-- /.unit --></div>

name の値により、コンテンツデータとフィールド情報とを関連付けるキーとして利用されますので、モジュールごとに重複のないように命名してください。

オプションとなる項目については Twigテンプレートを利用する場合と概ね共通です。

次の項目は、旧Broccoli標準記法に特有の項目です。

name
入力欄の物理名称を付与します。詳しくは input フィールドの説明を参照ください。
hidden
inputフィールドと同様に、 hiddentrue を設定して隠し、 if フィールド と echo フィールド を組み合わせて出力制御することができます。

loopフィールド (旧Broccoli標準記法)

旧Broccoli標準記法では、 template.html に 次のように定義します。

<!-- 実装例 -->
<ul>
{&{"loop":{"name":"thumb_loop", "label":"サムネイルリスト"}}&}
    <li>リスト</li>
{&"endloop"&}
</ul>

定義領域の終了は、{&"endloop"&} で宣言します。

name の値により、コンテンツデータとフィールド情報とを関連付けるキーとして利用されますので、モジュールごとに重複のないように命名してください。

オプションとなる項目については Twigテンプレートを利用する場合と概ね共通です。

次の項目は、旧Broccoli標準記法に特有の項目です。

name
入力欄の物理名称を付与します。詳しくは input フィールドの説明を参照ください。
hidden
inputフィールドと同様に、 hiddentrue を設定して隠し、 if フィールド と echo フィールド を組み合わせて出力制御することができます。
index
ループ要素の通し番号を参照できるようにします。indexに指定した文字列が参照名になります。 同じ文字列を echo フィールドのref に指定して出力します。 一般的な配列処理と異なり、 通し番号は 1 から開始されます。

if フィールド (旧Broccoli標準記法)

ifフィールドは、与えた条件が真の場合にのみ、出力される領域を定義します。

条件分岐領域の終了は、{&"endif"&} で宣言します。

使用できる条件を説明します。

cond

条件式を配列で指定します。

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:canvasis_mode:finalize は、編集画面描画時 または 最終描画時 の条件によって出力内容を分岐する条件として利用できます。

<!-- 編集画面にのみ表示する実装例 -->
{&{"if":{"cond":[
  ["is_mode:canvas"]
]}}&}
<p>この部分は、編集画面でのみ表示されます。</p>
{&"endif"&}
<!-- 編集画面には表示しない実装例 -->
{&{"if":{"cond":[
  ["is_mode:finalize"]
]}}&}
<p>この部分は、最終描画時のみ表示され、
  編集画面では表示されません。</p>
{&"endif"&}

is_set

指定した名前のフィールドに値がセットされている場合に、内容を表示します。

<!-- 実装例 -->
{&{"input":{"type":"html","name":"sample1","label":"サンプル1"}}&}
{&{"if":{"is_set":"sample1"}}&}
<p>この部分は、sample1 に値を入力した場合のみ出力されます。</p>
{&"endif"&}

elseifフィールド, elseフィールド

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フィールド (旧Broccoli標準記法)

echoフィールドは、別のフィールドで入力された値を出力します。

<!-- 実装例 -->
{&{"input": {
  "type": "html",
  "name": "sample1",
  "label": "サンプル1",
  "hidden": true
}}&}
{&{"echo":{"ref":"sample1"}}&}

この例は、HTML入力欄 sample1 の値を、後で出力しています。 HTML入力欄自体は、"hidden":true で隠しているので、結果として、入力値は1回だけ出力されます。