An Array input is an editing interface for lists of inputs or input groups. You can use this input in the Data Editor, Content Editor, or Visual Editor to edit structured data in data files or front matter. 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.
There is only one type of Array input:
- Array
Array input types#
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 Array input.
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.
Depending on how your developer has configured the Array input, clicking the + Add button will either clone the last entry in the Array, allow you to choose from predefined Structures, or add an entry that matches the Entry Input Type.
Array input appearance and behavior#
You can customize the label, comment, documentation link, and context box for all inputs regardless of type.
Depending on how your developer configured the input, your Array input may have a custom preview appearance for entry Cards, including the text, subtext, icon, icon color, icon background color, or image.
Populating an Array input#
Array inputs need a method for populating new entries. Depending on how your developer has configured the input, when you click the + Add button to add a new entry, CloudCannon will populate new entries in one of three ways: cloning another Array item, using a Structure, or using an entry Input type.
If your Array input uses the cloning method, clicking the + Add button will clone the format of the most recent entry in the Array and remove the data content. This method is the simplest and allows you to maintain the format of your Array entries, but has some drawbacks. One, you can't use multiple formats for different entries and, two, your input needs at least one entry to clone.
If your Array input uses a Structure, you can select a predefined template to populate a new entry. This method allows you to have many entry templates that are as complex as you require.
If your Array input uses an entry Input type, clicking the + Add button will add an Input of a predefined type as your new entry. This method is suitable for simple Arrays where each entry should be the same Input type.
For more information, please read our developer documentation on populating an Array input.
Input validation#
Your Array inputs may have input validation, which requires the input value to meet predefined criteria before you can save your changes. CloudCannon will warn you if your input value is invalid and provide directions on how to fix it.
CloudCannon will show a red * next to the name of your Array inputs if a value is required.
CloudCannon will warn you that errors need attention when an input nested within an Array fails input validation.
If you select a number of options under the minimum or over the maximum item number, CloudCannon will display an error message in red text under the input field.
If your input requires unique values, CloudCannon will warn you when two or more values are not unique.
For more information on configuration options, valid input values, and unconfigured input behavior, please read our developer documentation on configuring an Array input.
Misconfigured Array inputs#
You will see an orange warning box if your Array input is misconfigured.
Array inputs are misconfigured if:
- The value is not an array of strings, numbers, booleans, or keys.
- There is no value, and you have not configured a Structure or entry input type to populate the Array.
For more information on how to fix a misconfigured Array input, please read our developer documentation on configuring an Object input.