Index
Edit

Array

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

Use options.layout and options.sortable to control list behavior. options.layout: 'tags' will only work if the array contains strings and only strings.

Properties

  • ofarray - Defines which types are allowed as members of the array.
  • optionsobject - Extra type options. See below.
  • sortableboolean - Controls whether the user is allowed to reorder the items in the array. Defaults to true.

Example: Array of Strings

// A straight, reorderable list of strings
{
  title: 'Names',
  name: 'names',
  type: 'array',
  of: [{type: 'string'}]
}

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

Options

  • layout: "tags" renders a tokenizing tag field for string arrays
  • list: [ {value: <value>, title: <title>}, { … } ] renders check boxes for titles and populates a string array with selected values
  • editModal: fold | popover| fullscreen

Example: Array which may contain crew members or 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.

{
  title: 'Employees',
  name: 'employees',
  type: 'array',
  of: [{type: 'crewMember'}, {type: 'castMember'}]
}

Example 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.

    {
      title: 'Employees',
      name: 'employees',
      type: 'array',
      of: [
        {type: 'reference', to: {type: 'castMember'}},
        {type: 'reference', to: {type: 'crewMember'}}
      ]
    }

Example 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.

{
  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'}
    ]
  ]
}

Example output:

['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. Arrays that hold values of primitive types (e.g. strings or numbers) can not be addressed uniquely by a key in a realtime setting, where one 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 is OK:

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

Previous: BooleanNext: Block Text