Collection

Collection allows the creation of lists of objects. It produces an array. Each object is made of fields represented in a fieldset:

Example

{
    "key": "collection_field",
    "type": "collection",
    "item_label": "Item {{media_text}}",
    "description": "Contains media items ...",
    "fieldset": [
        {
            "label": "Text",
            "description": "Text is a ...",
            "key": "media_text"
        },
        {
            "label": "Image",
            "description": "Image is a ...",
            "key": "media_image"
        }
    ]
}

Collections can contain a collection as a field with only one level of nesting, which also assumes that a collection can't contain itself as a field.

{
    "key": "collection_with_nested_collection",
    "type": "collection",
    "item_label": "Item {{media_text}}",
    "description": "Contains media items ...",
    "fieldset": [
        {
            "label": "Text",
            "description": "Text is a ...",
            "key": "media_text"
        },
        {
            "label": "Nested collection",
            "description": "Nested collection is a ...",
            "key": "collection_field"
        }
    ]
}

Below are examples of format in which values of collection type are available to a client app:

Empty collection

[]

2 items collection

[
  {
    "media_text": "First item"
  }, 
  {
    "media_text": "Second item", 
    "media_colour": "#a832a2"
  }
]

Nested collection

[
  {
    "media_text": "Item #1",
    "collection_field": []
  },
  {
    "media_text": "Item #2",
    "collection_field": [
      {
        "media_text": "Nested Item #1"
      },
      {
        "media_text": "Nested Item #2",
        "media_colour": "#a832a2"
      }
    ]
  }
]

Item labels

Collection field can have item_label property. If specified, item label will be displayed instead of "Item #" text.

item_label is a handlebars template. Besides static text, field value from the fieldset can be used as a variable.

{
    "key": "participants",
    "type": "collection",
    "item_label": "Participant {{name}} from {{place}}",
    "description": "Collection of participants ...",
    "fieldset": [
        {
            "label": "Name",
            "key": "name",
            "field": "text",
            "description": "Participant's name ..."
        },
        {
            "label": "Place",
            "key": "place",
            "field": "text",
            "description": "Participant's place ..."
        }
    ]
}

Same field type restrictions are applied as for element labels.

Limitations

Collections have these limitations:

  • Default values are not supported

  • Prefill is not supported

  • mandatory flag is not supported for the collection itself, although it is supported for fields within collection items. Use items_number instead to specify the minimum and maximum number of items allowed in a collection. See Field set.

  • description optional attribute is supported for adding a tooltip for the corresponding field

Last updated