Structures are part of the CloudCannon configuration cascade. You can configure them for your site as a whole and for a specific page or collection. You can define your structures in the following places:
- The global configuration file
- Collection configuration
- Schema configuration
- File front matter
- Within another structure
When you define a structure in multiple places, CloudCannon uses the highest priority source and does not merge the structures. For example, a structure defined in the front matter of a file will take priority over one defined in collections.
Define a structure at the collection level#
To configure for an individual collection, use the _structures key under your collection in collections_config.
Here is a structure configuration for the collection Blog:
collections_config:
blog:
_structures:
example:
style: select
values:
- label: Product
value:
name:
description:
image:
The collections_config key contains all the collections and any configuration for those collections.
The blog key matches our collection “Blog”.
The _structures key contains all the structures defined at a given level of the configuration cascade. In this code, structures defined here will only be available inside the collection “blog”.
The key name for our structure group is example. Under example we have defined a single structure labelled “Product” with the fields for name, description, and image.
{
"collections_config": {
"blog": {
"_structures": {
"example": {
"style": "select",
"values": [
{
"label": "Product",
"value": {
"name": null,
"description": null,
"image": null
}
}
]
}
}
}
}
}The collections_config key contains all the collections and any configuration for those collections.
The blog key matches our collection “Blog”.
The _structures key contains all the structures defined at a given level of the configuration cascade. In this code, structures defined here will only be available inside the collection “blog”.
The key name for our structure group is example. Under example we have defined a single structure labelled “Product” with the fields for name, description, and image.
The structures defined under the key example will only be available for array or object inputs in the collection "Blog".
Define a structure within another structure#
You can nest structures by defining a structure within another structure. These “sub-structures” will only affect arrays within the containing structure.
For this example, we want to create a page builder called page_sections. Within the structure for the page_sections array, let’s create an option for a hero, content, and call-to-action section. Then, within the option for content, let’s define a second structure for the array elements. The elements structure will have the options for text and image.
Here is our structure configuration:
---
page_sections: []
---
_inputs:
page_sections:
type: array
options:
structures: _structures.page_sections
_structures:
page_sections:
values:
- label: Hero
icon: title
value:
_type: hero
title:
description:
- label: Content
icon: subject
value:
_type: content
content: []
_inputs:
content:
type: array
options:
structures: _structures.elements
_structures:
elements:
values:
- label: Text
icon: article
value:
content:
_inputs:
content:
type: textarea
- label: Image
icon: image
value:
image:
description:
- label: Call to action
icon: smart_button
value:
_type: cta
url:
content:
The _inputs key contains all the inputs defined at a given level of the configuration cascade.
The key name of the array or object input which contains the sub-structure. In this code, we have called our input page_sections. The options.structures key is set to _structures.page_sections.
The _structures key contains all the structures defined at a given level of the configuration cascade.
The key name of your structure. In this code, we have called our structure page_sections.
Under the key page_sections we have defined three structures. The second structure is labelled "Content", and contains a sub-structure.
The Structure labelled "Content" contains an array named content. We will populate this array with a structure defined within a structure.
The _inputs key contains all the inputs defined at a given level of the configuration cascade. In this case, inputs defined here are only available within the item "content".
Within the structure labelled "Content", we have defined another structure.
The key name of your sub-structure. In this code, we have called our sub-structure elements. The structures defined under elements will only be available within the item "Content" where page_sections is used in an aray or object input.
{
"_inputs": {
"page_sections": {
"type": "array",
"options": {
"structures": "_structures.page_sections"
}
}
},
"_structures": {
"page_sections": {
"values": [
{
"label": "Hero",
"icon": "title",
"value": {
"_type": "hero",
"title": null,
"description": null
}
},
{
"label": "Content",
"icon": "subject",
"value": {
"_type": "content",
"content": []
},
"_inputs": {
"content": {
"type": "array",
"options": {
"structures": "_structures.elements"
}
}
},
"_structures": {
"elements": {
"values": [
{
"label": "Text",
"icon": "article",
"value": {
"content": null
},
"_inputs": {
"content": {
"type": "textarea"
}
}
},
{
"label": "Image",
"icon": "image",
"value": {
"image": null,
"description": null
}
}
]
}
}
},
{
"label": "Call to action",
"icon": "smart_button",
"value": {
"_type": "cta",
"url": null,
"content": null
}
}
]
}
}
}The _inputs key contains all the inputs defined at a given level of the configuration cascade.
The key name of the array or object input which contains the sub-structure. In this code, we have called our input page_sections. The options.structures key is set to _structures.page_sections.
The _structures key contains all the structures defined at a given level of the configuration cascade.
The key name of your structure. In this code, we have called our structure page_sections.
Under the key page_sections we have defined three structures. The second structure is labelled "Content", and contains a sub-structure.
The Structure labelled "Content" contains an array named content. We will populate this array with a structure defined within a structure.
The _inputs key contains all the inputs defined at a given level of the configuration cascade. In this case, inputs defined here are only available within the item "content".
Within the structure labelled "Content", we have defined another structure.
The key name of your sub-structure. In this code, we have called our sub-structure elements. The structures defined under elements will only be available within the item "Content" where page_sections is used in an aray or object input.
Let’s populate the arrays for page_sections and elements with sample content to see this substructure in action. Here is how the arrays look in the sidebar of the Content Editor.
For more information, read our reference documentation on using the configuration cascade.