# Collection

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

### Example

```javascript
{
    "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.

```javascript
{
    "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

```javascript
[]
```

### 2 items collection

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

### Nested collection

```javascript
[
  {
    "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.

```javascript
{
    "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](https://products.monterosa.co/mic/developer-guide/app-specs/elements-spec#labels) 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](https://products.monterosa.co/mic/developer-guide/app-specs/data-structures#field-set).
* `description` optional attribute is supported for adding a tooltip for the corresponding field