Defining what adds to an array

Last modified: September 21st, 2023

By default, arrays in the Data Editor allow you to create new items. Adding a new item clones the previous item and clears its data. This default behavior is convenient as there is no configuration, however, there are some limitations as a trade-off:

  • The array must always contain at least one value for the editor to clone when adding.
  • Every item in the array has the same data type or structure.

You can overcome these limitations by configuring how new array items are added manually by giving CloudCannon more context with Structures.

Alternatively, configure inline array inputs to set which input is used for array items. This also allows array to be empty.

An array with the add button highlighted

Structures#

Array add values are defined under the key _structures. These allow you to define which keys in your data should be arrays, what data should be added when Add is clicked, and how the editor can decide what item to add.

Defining your key#

The first step to configuring your structures is to define which key is used. For this example we will use the example key. If _structures is already defined, add your key to that object. Key level config in structures do not get merged; the latest defined key will be the only config. Below is the basic structure once your key is chosen:

Configuration
copied
_structures:
  example:
    # Configure example key in here
Configuration
copied
[[_structures.example]]
# Configure example key in here
Configuration
copied
{
  "_structures": {
    "example": {}
  }
}

Defining a single value#

For the first example we want editors to click Add and immediately have the following data added:

New Item Content
copied
name: 
description: 
image: 
New Item Content
copied
{
  "name": null,
  "description": null,
  "image": null
}

For this we need to add our new structure under a value key inside an array called values:

Configuration
copied
_structures:
  example:
    values:
      - value:
          name: 
          description: 
          image: 
Configuration
copied
{
  "_structures": {
    "example": {
      "values": [
        {
          "value": {
            "name": null,
            "description": null,
            "image": null
          }
        }
      ]
    }
  }
}
Configuration
copied
[[_structures.example.values]]
[_structures.example.values.value]

Our editors can now add a new value to our array and remove every array item because we have moved our add instructions into the _structures config.

An empty array with the option to add an item

Defining a second value#

For the second example we want editors to click Add and be prompted for a choice of options. We are going to add the following structure to our structures:

New Item Content
copied
heading: 
subtext: 
New Item Content
copied
{
  "heading": null,
  "subtext": null
}

For this we need to add our new structure under our previous in the array called values. Now that we have more than one option, it is important to label our values. Labels are defined on the same level as the value key with the label key. Here is our new configuration:

Configuration
copied
_structures:
  example:
    values:
      - label: First
        value:
          name: 
          description: 
          image: 
      - label: Second
        value:
          heading: 
          subtext: 
Configuration
copied
{
  "_structures": {
    "example": {
      "values": [
        {
          "label": "First",
          "value": {
            "name": null,
            "description": null,
            "image": null
          }
        },
        {
          "label": "Second",
          "value": {
            "heading": null,
            "subtext": null
          }
        }
      ]
    }
  }
}
Configuration
copied
[[_structures.example.values]]
label = "First"

  [_structures.example.values.value]

[[_structures.example.values]]
label = "Second"

  [_structures.example.values.value]
An empty array with two add options in a dropdown
An array with two add options in a dropdown and two existing items

There are a number of ways to change the way your array values look, just like the label key. These include the description, icon, image, and image_size keys. See the structures reference for more details on these keys.

Related Articles

Open in a new tab