Index
Edit

Array

An ordered list of data. The of property specifies which value types the array may hold.

Properties

typestring

Required. Value must be set to array.

ofarray

Defines which types are allowed as members of the array.

sortableboolean

Controls whether the user is allowed to reorder the items in the array. Defaults to true.

titlestring

Human readable label for the field.

namestring

Required. The field name. This will be the key in the data record.

hiddenboolean

If set to true, this field will be hidden in the Content Studio.

readOnlyboolean

If set to true, this field will not be editable in the content studio.

descriptionstring

Short description to editors how the field is to be used.

Options

layoutstring

If set to tags, renders the array as a single, tokenized input field. This option only works if the array contains strings.

If set to grid it will display in a grid

listarray

[ {value: <value>, title: <title>}, { … } ] renders check boxes for titles and populates a string array with selected values

editModalstring

Controls how the modal (for array content editing) is rendered. You can choose between dialog, fullscreen, fold or popover. Default is dialog.

Example: Array of strings

Vanilla, reorderable array of strings:

Schema
{
  title: 'Names',
  name: 'names',
  type: 'array',
  of: [{type: 'string'}]
}
JSON output
{
  "names": ["Wilma", "Håvard"]
}

Tokenized field (tags) is data-wise an ordinary array

Schema
// Presented as a tokenizing tag-field
{
  title: 'Tags',
  name: 'tags',
  type: 'array',
  of: [{type: 'string'}],
  options: {
    layout: 'tags'
  }
}
JSON output
{
  "tags": ["clever", "unexpected"]
}

Example: Array containing both crew members and cast members

Both crewMember and castMember are custom types defined in our schema. In this example we want an array of employees to be able to contain both crew members or cast members. The resulting array will end up containing inline instances of the actual objects. Note that in a real world example, you may want this to be references to existing cast members or crew members.

Schema
{
  title: 'Employees',
  name: 'employees',
  type: 'array',
  of: [{type: 'crewMember'}, {type: 'castMember'}]
}
JSON output
[
  {
      "_key": "5ead6b7c7dcc55ae66d504e2d9bfeff5",
      "_type": "castMember",
      "characterName": "Mark Watney",
      "externalCreditId": "53e7e85e0e0a266f9a0029aa",
      "person": {
        "_ref": "person_matt-damon",
        "_type": "reference"
      }
  },
  {
    "_key": "8c1dd384a3ab34befbe5fdd93478fc8e",
    "_type": "castMember",
    "characterName": "Melissa Lewis",
    "externalCreditId": "5466c78eeaeb8172820008e4",
    "person": {
      "_ref": "person_jessica-chastain",
      "_type": "reference"
    }
  },
  {
    "_key": "76a7e8c2547ce445294c581564bc7d75",
    "_type": "crewMember",
    "department": "Camera",
    "externalCreditId": "5607a946c3a3681218003eef",
    "externalId": 1404244,
    "job": "Helicopter Camera",
    "person": {
      "_ref": "person_john-marzano",
      "_type": "reference"
    }
  }
]

Example: Array of references

If we want castMember and crewMember to be stored as separate documents and our array should contain references to these documents, instead of the actual data.

Schema
{
  title: 'Employees',
  name: 'employees',
  type: 'array',
  of: [
    {type: 'reference', to: {type: 'castMember'}},
    {type: 'reference', to: {type: 'crewMember'}}
  ]
}
JSON output
[
  {
    "_ref": "person_harrison-ford",
    "_type": "reference"
  },
  {
    "_ref": "person_ridley-scott",
    "_type": "reference"
  }
  //...
]

Example: Predefined strings

Some times you need an array of strings presented as a set of predefined values. By using the list option, the field is presented as an array of radio buttons where the editor can toggle which strings are in the array. This handles the array as a set and the ordering is not defined.

Schema
{
  title: 'Category Set',
  name: 'categorySet',
  type: 'array',
  of: [{type: 'string'}],
  options: {
    list: [
      {title: 'Building', value: 'building'},
      {title: 'Master plan', value: 'masterPlan'},
      {title: 'Infrastructure', value: 'infrastructure'},
      {title: 'Private Home', value: 'privateHome'}
    ]
  }
}
JSON output
{
  "categorySet": ["building", "privateHome"]
}

Why the _key?

When adding data with type: 'object' to an array, each item gets assigned a persistent and unique _key-property. This is to ensure that each item can be addressed uniquely in a collaborative, realtime setting. This allows one user to edit an array item, while simultaneously another user reorders the array.

Two Limitations

  1. Due to a limitation in the data store, arrays may not currently contain arrays. Wrap nested arrays in objects.
  2. It is not possible to define arrays that contains both object types and primitive types. Arrays that hold values of primitive types (e.g. strings or numbers) can not be addressed uniquely by a key in realtime (e.g. a user may edit an array item, while at the same time another user reorders the array). As a consequence, when defining an array of primitive values, the content studio will switch to a simpler array input widget for editing. This input widget will not be able to handle object types, so for this reason it is not possible to define arrays that contains both object types and primitive types. If you should ever need an array that contains both strings and objects (e.g. movie) objects, you should instead wrap the string values in an object type (e.g. defined in-place), and give it a property that holds the string value.

This will not work:

{
  type: 'array',
  of: [
    {
      type: 'actor',
      title: 'Actor'
    },
    {
      type: 'string', /* Will not work! */
      title: 'Actor name'
    }
  ]
}

This will work:

{
  type: 'array',
  of: [
    {
      title: 'Actor',
      type: 'actor'
    },
    {
      title: 'Actor name',
      type: 'object',
      fields: [
        {
          title: 'Name',
          name: 'value',
          type: 'string'
        } 
      ]
    }
  ]
}

Previous: BooleanNext: Block