An Object input is an editing interface for nested structured data in data files or front matter. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.
These instructions assume that you know what subtype of Object input you want to configure and where in the configuration cascade. For more information, please read our documentation on Object inputs, inputs in general, and the configuration cascade.
To configure an Object input:
- Open your website files in your local development environment, or log in to CloudCannon and select the Site for which you want to configure your input.
- Navigate to the location in the configuration cascade where you want to configure your input. This can be the root of your CloudCannon Configuration File, within the
collections_config.*key in your CloudCannon Configuration File, a Schema file, the frontmatter of a markup file, or any where you configure a Structure. - Identify the
_inputskey, or create one at that level of the configuration cascade. - Add an input name key for your input under the
_inputskey (a.k.a.,_inputs.*). We recommend naming your input something simple that indicates the function or context. - Add the
typekey under your input name key, with the valueobject. - (Optional.) Add any other general configuration keys (e.g.,
label,comment,context) under your input name key. - Add the
subtypekey under_inputs.*.options, with the valueobject,tabbed, ormutable. - (Optional.) Add any other specific configuration keys under
_inputs.*.options(e.g.,preview,structures,groups).
CloudCannon will now apply this input configuration to all markup files that use your input name key, without needing to save your configuration. This allows you to make changes to your input configuration and see those changes affect inputs live.
When you are happy with your input configuration, you must save your input configuration.
_inputs:
seo:
type: object
options:
subtype: object
event:
type: object
options:
subtype: tabbed
terminology:
type: object
options:
subtype: mutable
All inputs are defined under the _inputs key, regardless of where they are in the configuration cascade.
This Object input is called seo.
The value of the type key determines the input type. This is an object input.
The value of the options.subtype key determines the Object input's subtype. This is an object input.
This Object input is called event.
The value of the options.subtype key determines the Object input's subtype. This is a tabbed input.
This Object input is called terminology.
The value of the options.subtype key determines the Object input's subtype. This is a mutable input.
{
"_inputs": {
"seo": {
"type": "object",
"options": {
"subtype": "object"
}
},
"event": {
"type": "object",
"options": {
"subtype": "tabbed"
}
},
"terminology": {
"type": "object",
"options": {
"subtype": "mutable"
}
}
}
}All inputs are defined under the _inputs key, regardless of where they are in the configuration cascade.
This Object input is called seo.
The value of the type key determines the input type. This is an object input.
The value of the options.subtype key determines the Object input's subtype. This is an object input.
This Object input is called event.
The value of the options.subtype key determines the Object input's subtype. This is a tabbed input.
This Object input is called terminology.
The value of the options.subtype key determines the Object input's subtype. This is a mutable input.
When you add your input key name to a data or markup file, your configured Object input will appear in the Data Editor, Visual Editor, or Content Editor.
---
seo:
title: How you can optimize publishing workflows for your content team
image: /images/logo.svg
description: CloudCannon's drafting and publishing workflows can tie all of your optimizations together, offering enhanced control, flexibility, and coordination.
event:
details:
title:
image:
description:
cast:
main_cast:
- Actor A
- Actor B
- Actor C
special_guests:
- Actor X
- Actor Y
- Actor Z
terminology:
CloudCannon: A CMS for static websites.
Input: An editing interface for structured data.
new_term: ''
---
Blog content goes here.
For Object inputs to function correctly, they must contain at least one entry. You can add entries to an Object using the Source Editor. Alternatively, you can configure a structure or a mutable Object with an entry input type to allow team members to populate and empty Object.
Input configuration options#
General configuration options are available for all input types. You can define the label, comment, and context box for your Object input, whether it is hidden or disabled, and how CloudCannon should handle configuration at multiple levels of the configuration cascade.
Specific configuration options for Object inputs include defining the format of the input, enabling structures, configuring groups and previews, and how CloudCannon handles empty values. For mutable Objects, you can also configure allowed keys, assigned structures, and label formatting.
Here is an example of an Object input using some of the most commonly used configuration keys.
_inputs:
homepage_feature:
type: object
options:
subtype: object
structures: _structures.feature_template
groups:
- heading: SEO
comment: Values for search engines to read
inputs:
- title
- description
- image
place_groups_below: false
preview:
text: Homepage Feature Image
subtext: Edit the main image in the header of the homepage.
icon: photo_library
image:
- key: image
empty_type: string
{
"_inputs": {
"homepage_feature": {
"type": "object",
"options": {
"subtype": "object",
"structures": "_structures.feature_template",
"groups": [
{
"heading": "SEO",
"comment": "Values for search engines to read",
"inputs": [
"title",
"description",
"image"
]
}
],
"place_groups_below": false,
"preview": {
"text": "Homepage Feature Image",
"subtext": "Edit the main image in the header of the homepage.",
"icon": "photo_library",
"image": [
{
"key": "image"
}
]
},
"empty_type": "string"
}
}
}
}For a complete list of configuration keys available for inputs please read our inputs reference documentation.
These keys configure the appearance and functionality of Object inputs in CloudCannon.
This key determines the appearance and function of the input. Defaults to object.
Value must be one of the following:
object— clicking on the Object card will open the second scope containing all nested inputs.mutable— all nested inputs appear on the top scope with controls to add, delete, clone, rename, or remove inputs from within the Object.tabbed— all nested objects appear as tabs in the top scope.
This key determines which predefined templates to use for populating the Object Input. When configured, team members can select a structure to populate the Object with input/input groups. This key has no default.
If configured as an object, CloudCannon will use the values directly.
If configured as a string, CloudCannon will use the matching structures value defined under _structures in the configuration cascade.
This key looks similar to entries.structures. However, the structures key applies to the Object input itself, while entries.structures applies to the entries within the object.
This key allows you to group nested inputs within the Object Input together without changing the data structure. The following nested keys are available:
headingcommentcollapsedinputsdocumentation
Each group should be a new item in the array. Ungrouped inputs appear below groups by default.
This key does not apply to Structured or Mutable Object Inputs.
This key determines the title text displayed at the top of the group. This text is visible whether a group is expanded or collapsed.
This key determines the subtitle text displayed at the top of the group. This text is visible whether a group is expanded or collapsed.
This key determines whether a group is collapsed by default. Defaults to false.
This key determines the inputs included in this group. These key names must match a key within the Object Input. Defaults to [].
This key enables you to add a custom link below the heading of the group. The following nested keys are available:
url— determines thehrefvalue of the link (String). This field is required.text— determines the visible text used in the link (String). Defaults toDocumentation.icon— determines the icon displayed next to the link. Must be a Material Icon name. Defaults toauto_stories.
This key determines whether ungrouped inputs appear below groups or above groups. Defaults to false. Has no affect if groups is not configured.
This key defines the appearance of a Card. You can configure Card preview for Collections, Schemas, Object inputs, Array inputs, Select inputs, Structures, the Structure modal, Snippets, and the Snippet modal.
The following nested keys are available:
textsubtexticonicon_coloricon_background_colorimagemetadatagallery
This key defaults to:
preview:
text:
- key: title
- key: name
icon:
- key: icon
For more information about previews, please read our documentation on configuring card previews.
Show exampleHide example
In this example, we have configured the appearance of file Cards in the Collection browser.
collections_config:
blog:
preview:
text:
- key: title
subtext:
- key: author
icon: edit_note
icon_color:
- key: color
- '#ff0000'
image:
- key: image
metadata:
- template:
- url
- icon: event
text:
- template: Published on {date|date_long}
gallery:
- key: featured_image
{
"collections_config": {
"blog": {
"preview": {
"text": [
{
"key": "title"
}
],
"subtext": [
{
"key": "author"
}
],
"icon": "edit_note",
"icon_color": [
{
"key": "color"
},
"#ff0000"
],
"image": [
{
"key": "image"
}
],
"metadata": [
{
"template": [
"url"
]
},
{
"icon": "event",
"text": [
{
"template": "Published on {date|date_long}"
}
]
}
],
"gallery": [
{
"key": "featured_image"
}
]
}
}
}
}In this example, we have configured the appearance of Cards in inputs using the Structure staff.
_structures:
staff:
values:
- value:
_type: Employee
name:
job_description:
profile_picture:
preview:
text:
- key: name
- Employee
subtext:
- key: job_description
- Description of position
image:
- key: profile_picture
icon: support_agent
- value:
_type: Manager
name:
job_description:
profile_picture:
url:
preview:
text:
- key: name
- Manager
subtext:
- key: job_description
- Description of position
image:
- key: profile_picture
icon: face
{
"_structures": {
"staff": {
"values": [
{
"value": {
"_type": "Employee",
"name": null,
"job_description": null,
"profile_picture": null
},
"preview": {
"text": [
{
"key": "name"
},
"Employee"
],
"subtext": [
{
"key": "job_description"
},
"Description of position"
],
"image": [
{
"key": "profile_picture"
}
],
"icon": "support_agent"
}
},
{
"value": {
"_type": "Manager",
"name": null,
"job_description": null,
"profile_picture": null,
"url": null
},
"preview": {
"text": [
{
"key": "name"
},
"Manager"
],
"subtext": [
{
"key": "job_description"
},
"Description of position"
],
"image": [
{
"key": "profile_picture"
}
],
"icon": "face"
}
}
]
}
}
}This key determines the title text displayed on a default Object Input card. This key has no default, and falls back to the first nested value found (prioritizing text-based values).
If set to false, no text is displayed.
This key determines the subtitle text displayed on a default Object Input card. This key has no default, and falls back to listing the label of each nested input. subtext is hidden if text and subtext are the same. If there is no text, subtext will appear in the place of text.
If set to false, no text is displayed.
This key determines the icon displaye beside the text and subtext on a Card. The value must match a name from the Google's Material Icons list.
This key defaults to checking the icon key, then falls back to the notes icon.
If set to false, no icon is displayed.
If image is defined, the image replaces icon when loaded successfully.
This key supports cascading options, which can be either an Array or a single value. Value can be one of the following:
- A String of the exact value (e.g
"edit_note") - A reference to a key within the connected item (e.g
key: iconin YAML or{ "key": "icon" }in JSON) - A String with placeholders that will be replaced with values (e.g.
template: {icon_type}in YAML or{ "template": "{icon_type}" }in JSON)
Show exampleHide example
In this example, we configure a static icon for the card.
preview:
icon: edit_note
{
"preview": {
"icon": "edit_note"
}
}In this example, we use a dynamic icon from the data.
preview:
icon:
- key: icon_type
- support_agent
{
"preview": {
"icon": [
{
"key": "icon_type"
},
"support_agent"
]
}
}This key determines the color of the icon displayed on a Card.
This key supports cascading options, which can be either an Array or a single value. Value can be one of the following:
- A String of the exact value (e.g
"#ff0000") - A reference to a key within the connected item (e.g
key: colorin YAML or{ "key": "color" }in JSON) - A String with placeholders that will be replaced with values (e.g.
template: {color_code}in YAML or{ "template": "{color_code}" }in JSON)
By default, this key is #000000 (black).
Show exampleHide example
In this example, we configure a dynamic icon color from the data with a fallback to red.
preview:
icon: edit_note
icon_color:
- key: color
- '#ff0000'
{
"preview": {
"icon": "edit_note",
"icon_color": [
{
"key": "color"
},
"#ff0000"
]
}
}In this example, we use a static icon color.
preview:
icon: nature_people
icon_color:
- '#00ff00'
{
"preview": {
"icon": "nature_people",
"icon_color": [
"#00ff00"
]
}
}This key determines the background color of the icon displayed on a Card. This is useful if your icon_color value has poor contrast on a white background.
This key supports cascading options, which can be either an Array or a single value.Value can be one of the following:
- A String of the exact value (e.g
"#ff0000") - A reference to a key within the connected item (e.g
key: colorin YAML or{ "key": "color" }in JSON) - A String with placeholders that will be replaced with values (e.g.
template: {color_code}in YAML or{ "template": "{color_code}" }in JSON)
This key has no default.
Show exampleHide example
In this example, we configure a dynamic icon background color from the data with a fallback to red.
preview:
icon: edit_note
icon_background_color:
- key: color
- '#ff0000'
{
"preview": {
"icon": "edit_note",
"icon_background_color": [
{
"key": "color"
},
"#ff0000"
]
}
}In this example, we use a static icon background color.
preview:
icon: nature_people
icon_background_color:
- '#00ff00'
{
"preview": {
"icon": "nature_people",
"icon_background_color": [
"#00ff00"
]
}
}This key determines the image displayed on a default Object Input card. This key has no default, and falls back to thumbnail_image, thumbnail_image_path, image, and image_path in that order. If no image is found, icon is displayed instead.
If set to false, no image is displayed.
This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.
Value must be one of the following:
string- an empty value for this input will be stored as "".null- an empty value for this input will be stored as a null value (default). This does not apply to TOML files.
This key toggles whether CloudCannon requires this Input to have a value. If set to true, CloudCannon will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e, CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Show exampleHide example
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
{
"_inputs": {
"author": {
"type": "text",
"comment": "Enter the name of the author for this blog post.",
"options": {
"required": true
}
}
}
}This key defines a custom error message that explains why a value has failed the validation criteria from options.required. This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Show exampleHide example
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
{
"_inputs": {
"author": {
"type": "text",
"comment": "Enter the name of the author for this blog post.",
"options": {
"required": true,
"required_message": "You are not allowed to leave this blank."
}
}
}
}If the input is a mutable Object, the following options are also available:
_inputs:
example:
type: object
options:
subtype: mutable
entries:
allowed_keys:
- image
- link
- link_or_image
structures:
values:
- id: image_template
label: Image
icon: image
value:
image:
caption:
- id: link_template
label: External link
icon: link
value:
url:
title:
assigned_structures:
link:
- link_template
image:
- image_template
link_or_image:
- image_template
- link_template
comment: Select a key name.
documentation:
url: /documentation/articles/object-inputs/
text: Documentation
icon: help
allow_label_formatting: true
{
"_inputs": {
"example": {
"type": "object",
"options": {
"subtype": "mutable",
"entries": {
"allowed_keys": [
"image",
"link",
"link_or_image"
],
"structures": {
"values": [
{
"id": "image_template",
"label": "Image",
"icon": "image",
"value": {
"image": null,
"caption": null
}
},
{
"id": "link_template",
"label": "External link",
"icon": "link",
"value": {
"url": null,
"title": null
}
}
]
},
"assigned_structures": {
"link": [
"link_template"
],
"image": [
"image_template"
],
"link_or_image": [
"image_template",
"link_template"
]
},
"comment": "Select a key name.",
"documentation": {
"url": "/documentation/articles/object-inputs/",
"text": "Documentation",
"icon": "help"
}
},
"allow_label_formatting": true
}
}
}
}This key enables you to define the appearance and function of entries in a mutable object. The following nested keys are available:
allowed_keysstructuresassigned_structurescommentdocumentation
Available for Mutable Objects only.
This key defines a limited set of key names for nested keys within your Object Input. This affects entries when adding or renaming nested keys. Defaults to [].
Available for Mutable Objects only.
This key determines which predefined templates to use for populating entries nested in the Object Input. When configured, team members can select a structure to populate the Object with input/input groups. This key has no default.
If configured as an object, CloudCannon will use the values directly.
If configured as a string, CloudCannon will use the matching structures value defined under _structures in the configuration cascade.
Available for Mutable Objects only.
This key looks similar to structures. However, the structures key applies to the Object input itself, while entries.structures applies to the entries within the object.
This key enables you to assign structures to specific key names for entries in the Object Input. When selecting an entry key name, CloudCannon will prompt to to choose one of the assigned structures for that allowed key. Structure values are referred to by their id.
Available for Mutable Objects only.
This key determines the subtitle text above the key input. This key has no default, and supports a limited selection of Markdown formatting in value text: links, bold, italic, subscript, superscript, inline code elements are allowed.
Available for Mutable Objects only.
This key enables you to add a custom link above the key input. The following nested keys are available:
url- determines thehrefvalue of the link (String). This field is required.text- determines the visible text used in the link (String). Defaults toDocumentation.icon- determines the icon displayed next to the link. Must be a Material Icon name. Defaults toauto_stories.
Available for Mutable Objects only.
This key determines whether labels on mutable object entries are formatted. Defaults to false.
Available for Mutable Objects only.
Valid values#
Here are some examples of valid values for an Object input.
Empty/null value:
object:
Any valid nested key-value pairs:
object:
key1: value1
key2: value2
nested_object:
key3: value3
Any valid nested key-value pairs:
[object]
key1 = "value1"
key2 = "value2"
[object.nested_object]
key3 = "value3"
Empty/null value:
"object": null
Any valid nested key-value pairs:
{
"object": {
"key1": "value1",
"key2": "value2",
"nested_object": {
"key3": "value3"
}
}
}
Unconfigured Object inputs#
In some cases, CloudCannon can still detect an Object input even if you have not configured it.
CloudCannon will interpret any unconfigured input with nested keys as an Object input. You cannot create structured or mutable Object inputs without configuration.
company_photo:
image:
date:
description:
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.
We recommend configuring your inputs for greater control over their functionality and appearance.