Array inputs

An Array input lets your team members create a list of inputs or grouped inputs. Array inputs can contain nested inputs of any type, including other Arrays and Objects. There is no limit to how many nested layers you can create within an Array. Creating a list of inputs, or input groups, is useful for organizing your data.

You can populate an Array input by defining an entry input type or by using predefined templates called structures. For more information on structures, please read our structures documentation.

For each input you can configure which structures are associated with the input, the appearance of the preview card, and how CloudCannon handles empty values. You can also use the general configuration options available for all inputs.

Array#

The Array input provides a user interface for lists of inputs or input groups. Each item in an Array is sometimes called an "entry". Entries in an Array can be a single value, an input, or an Object containing several inputs. Array inputs appear as a series of cards in the Data Editor or sidebar of the Visual or Content Editor.

For entries that use a key name (i.e., Objects, Arrays, or single inputs), the card will preview some of the content within the key. This can include images, strings, and key names. You can configure the preview settings for these cards.

Simpler entries with no key name, such as text, number, or boolean values, do not use cards. Instead, they appear as editable inline fields.

Array inputs can contain a mixture of inline fields and cards simultaneously.

You can reorder, clone, add, and delete new entries in the list using the Context menu. You can also add new entries using the + Add button below the Array — the text on this button will differ depending on the key name of your input.

By default, adding a new entry to an Array input will clone the last entry in the Array.

When you click on a card in the Array, it will open to show the nested inputs within that Array entry. The Back button at the top of the entry will return you to the parent scope.

You can configure an Array input using the type key with the value array. Define the type key under your input key name within _inputs. For more information, please read our documentation on configuring your inputs.

_inputs:
  staff:
    type: array

{
  "_inputs": {
    "staff": {
      "type": "array"
    }
  }
}

Once configured, the Array input will appear in the Data Editor or sidebar of the Visual or Content Editor when you add it to a data file or the front matter of a markup file.

---
staff:
  - name: Karen Key
    position: Project Manager
    image: /images/team/karen_key.jpg
  - name: Holly James
    position: Engineering Team Lead
    image: /images/team/holly_james.jpg
---

Page content goes here.

Populating an Array input#

Without additional configuration, default Array inputs become misconfigured when empty.

In default Array inputs, CloudCannon will clone the last entry in the Array to add a new entry. This method is not possible with an empty Array. You can configure the entry input type or create a structure to avoid this issue and support empty Arrays.

Entry input type#

The entry input type defines what type of input CloudCannon should use to populate an Array or Object. Defining the entry input type for an Array input allows the Array to be empty without becoming misconfigured. All new entries added to an Array input will match the input type specified by the entry input type.

Array inputs with a defined entry input type avoid the issue of becoming misconfigured when empty. Because you have specified which input type to use in the Array, CloudCannon can repopulate the input if you delete the contents of the Array or create a new instance of that input.

You can configure the entry input type for your Array input under the _inputs key. To specify future entries within a particular Array, use the key name of the Array followed by the [*] characters. Define the type of input for those entries with the type key.

_inputs:
  gallery:
    type: array
  gallery[*]:
    type: image

{
  "_inputs": {
    "gallery": {
      "type": "array"
    },
    "gallery[*]": {
      "type": "image"
    }
  }
}

Structured Arrays#

A structured Array allows your team to select a predefined template to populate the inputs.

Structured Array inputs appear similar to the default input. However, unlike the default Array input, when you click the + Add button to add a new array entry, CloudCannon will prompt you to select which structure to use.

Structured Array inputs avoid the issue of becoming misconfigured when empty. Because you have configured at least one structure and linked it to your input, CloudCannon can repopulate the input if you delete the contents of the Array or create a new instance of that input.

You can configure an Array input using the structures key. Define the structures key under options within your input key name. The value of the structures key can be a string or an object.

If you have defined your structures elsewhere under the _structures key, you can reference it by using the key name as the value (i.e., _structures.key_name).

_inputs:
  staff:
    type: array
    options:
      structures: _structures.staff_members

{
  "_inputs": {
    "staff": {
      "type": "array",
      "options": {
        "structures": "_structures.staff_members"
      }
    }
  }
}

Alternatively, you create an Array called values to define your structures directly within your input configuration.

_inputs:
  staff:
    type: array
    options:
      structures:
        values:
          - label: Manager
            icon: face
            value:
              name: 
              job_description: 
              profile_picture: 
              url: 
          - label: Employee
            icon: support_agent
            value:
              name: 
              job_description: 
              profile_picture: 

{
  "_inputs": {
    "staff": {
      "type": "array",
      "options": {
        "structures": {
          "values": [
            {
              "label": "Manager",
              "icon": "face",
              "value": {
                "name": null,
                "job_description": null,
                "profile_picture": null,
                "url": null
              }
            },
            {
              "label": "Employee",
              "icon": "support_agent",
              "value": {
                "name": null,
                "job_description": null,
                "profile_picture": null
              }
            }
          ]
        }
      }
    }
  }
}

Options#

You can configure Array inputs using the options key under your input key, inside of _inputs.

page_sections: 
_inputs:
  page_sections:
    type: array
    options:
      structures: _structures.components
      preview:
        text:
          - key: name
        subtext:
          - key: description
        image:
          - key: my_image
        icon: article
      empty_type: string

{
  "page_sections": null,
  "_inputs": {
    "page_sections": {
      "type": "array",
      "options": {
        "structures": "_structures.components",
        "preview": {
          "text": [
            {
              "key": "name"
            }
          ],
          "subtext": [
            {
              "key": "description"
            }
          ],
          "image": [
            {
              "key": "my_image"
            }
          ],
          "icon": "article"
        },
        "empty_type": "string"
      }
    }
  }
}

Array inputs have the following options available:

Unconfigured Array inputs#

In some cases, CloudCannon can still detect an Array input even if you have not configured it.

CloudCannon will interpret any unconfigured input with a list of nested values or keys as an Array input. You cannot create structured Array inputs without configuration.

animals:
  - bear
  - lizard
  - swan
  - name: Dog
    fun_fact: Man's best friend.
    image: /images/my-dog.png

This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.