Working with a specific static site generator?
Customize CloudCannon's documentation to suit your SSG.
Great! We'll show you documentation relevant to .
You can change this any time using the dropdown in the navigation bar.
What is a structure?#
A structure is a predefined, custom template that determines what should populate an array or object input. With the click of a button, you can easily add fields to an array or object from your list of predefined structures.
Structures are excellent for creating items you want to repeat across your site. An image gallery structure might contain fields for an image, an author, and a caption. A testimonial structure might contain fields for a quote and an author. An array using page-building components might reference several structures for common content blocks, such as a hero image, call to action, or video block.
Once you have defined your structures, your team members can easily add, remove, reorder, and update structure content using the Data Editor or the sidebar of the Visual or Content Editor.
In this article, we’ll cover how to:
- Create a basic structure
- Reference a structure in an array or object input
- Add multiple structures to the same key
For more information, including a list of all keys available for structure configuration, please read our reference documentation for structures.
Structures and arrays#
Structures and arrays go hand-in-hand. The array input contains an ordered list of related items, while a structure is a template that determines what data CloudCannon should add to new array items. By creating structures, you can define different objects that your team members can add to arrays within your site.
When you first connect your site files and make them editable in the Data Editor, CloudCannon will automatically detect arrays in your front matter and data files.
You can add new items to your arrays without the need for configuration. Clicking the + Add button for an array will clone the last array item and clear the data from the new item to create a blank array object. This behavior is convenient if you have simple arrays, or do not want to configure structures.
The default array behavior may not be right for you if:
- Your array does not contain at least one object.
- You want to have different object types in your array.
Because the default behavior clones existing array items, CloudCannon will prevent you from removing the last item from an array if you do not have a structure configured. Additionally, cloning existing items does not allow for variation of object types. You can add different objects to the array manually using the Source Editor. However, this can become inefficient to maintain.
You can overcome these limitations by configuring data structures to add to your arrays.
Alternatively, configure inline array inputs to set which input is used for array items. Inline array inputs also allow an array to be empty.
Structures and objects#
Structures also work for individual objects. The object input can contain a maximum of one value. After you reference a structure key from an object input, team members can select which structure they want to add to that object. Once a value is selected, you cannot add more until the value is replaced or deleted.
Create a structure#
In CloudCannon, you can configure structures under the key called _structures
.
You can configure _structures
at any level of the configuration cascade. Global structures, which you can reference from any array or object input on your site, are configured in your global configuration file. For more information about how to define structures at other levels of the configuration cascade, read our reference documentation on structures in the configuration cascade.
Let’s create a structure in the global configuration file.
Currently, you cannot configure the values for your structures in the Configuration GUI.
To create a structure:
- Navigate to your global configuration file and open it in the Source Editor.
- Identify the
_structures
key, or create one. - Add your structure within the
_structures
key. - Save your changes to the global configuration file.
Here is an example of a basic structure:
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 example
. You can name your structure anything you want.
The example.values
key can contain an array of structures. We will cover multiple structures stored under a single key later in this article.
This is the first structure in the group named example
. Each structure must contain a value
key defining what fields should populate new items of this type. This structure contains fields for name
, description
, and image
. For more information on keys available for structure configuration, please read our reference documentation for structures.
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 example
. You can name your structure anything you want.
The example.values
key can contain an array of structures. We will cover multiple structures stored under a single key later in this article.
This is the first structure in the group named example
. Each structure must contain a value
key defining what fields should populate new items of this type. This structure contains fields for name
, description
, and image
. For more information on keys available for structure configuration, please read our reference documentation for structures.
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 example
. You can name your structure anything you want.
The example.values
key can contain an array of structures. We will cover multiple structures stored under a single key later in this article.
This is the first structure in the group named example
. Each structure must contain a value
key defining what fields should populate new items of this type. This structure contains fields for name
, description
, and image
. For more information on keys available for structure configuration, please read our reference documentation for structures.
In the above code, we have created a simple structure under the key example
. This structure contains the fields for name
, description
, and image
. This structure can be referenced in any array or object input.
In this example, the inputs called “name”, “description”, and “image” should also be configured somewhere in the configuration cascade. For more information, read our documentation on configuring your inputs.
Reference a structure in an array or object input#
We can reference a structure in any number of array or object inputs. The benefits of referencing the same structure in many inputs are:
- It allows you to maintain consistency and reduce repetition across your site.
- There is no need to rename your existing inputs or structures.
- When you want to update a structure, you only need to do so in one place.
To reference a structure in an input:
- Navigate to your global configuration file and open it in the Source Editor.
- Identify the
_inputs
key and the input you want to reference the structure from, or create them. - Reference your structure using the
options.structures
key within your array or object input. - Save your changes to the global configuration file.
Here is an example of an array input referencing a structure:
The _inputs
key contains all the inputs defined at a given level of the configuration cascade.
The key name of your array or object input. In this code, we have called our input array_one
.
The options
key contains configuration options for this input. For more information on configuring your inputs, read our documentation on configuring your inputs.
The options.structures
key is set to _structures.example
, referencing the structure named “example”.
The _inputs
key contains all the inputs defined at a given level of the configuration cascade.
The key name of your array or object input. In this code, we have called our input array_one
.
The options
key contains configuration options for this input. For more information on configuring your inputs, read our documentation on configuring your inputs.
The options.structures
key is set to _structures.example
, referencing the structure named “example”.
The _inputs
key contains all the inputs defined at a given level of the configuration cascade.
The key name of your array or object input. In this code, we have called our input array_one
.
The options
key contains configuration options for this input. For more information on configuring your inputs, read our documentation on configuring your inputs.
The options.structures
key is set to _structures.example
, referencing the structure named “example”.
Once you save the global configuration file, clicking the + Add button below the array will add an item with the same fields as your structure.
Let’s go over an example.
We want to create a single structure for storing links. The “links” structure will contain fields for url
, logo
, and text
. Every time a team member adds a new item to an array that references the structure links
, the structure will populate the new item with the fields for url
, logo
, and text
.
In this example, there are two arrays which we want to add links to. The first array input is called header_social_media
, and lists all the social media platforms we want to link to from our website header. The second array input is called footer_affliate_links
, and lists our affiliate links in the website footer.
Here is an example of how we might create the structure for links
and reference it in the input configuration for header_social_media
and footer_affliate_links
:
The _inputs
key containing our two arrays.
The key for the array header_social_media
.
The options.structures
key is set to _structures.links
.
The key for the array footer_affliate_links
.
As with #3, the options.structures
key is set to _structures.links
.
The _structures
key contains all the structures defined at a given level of the configuration cascade.
The key name for our structure group is links
.
The structure within links
. This structure contains fields for url
, logo
, and text
.
The _inputs
key containing our two arrays.
The key for the array header_social_media
.
The options.structures
key is set to _structures.links
.
The key for the array footer_affliate_links
.
As with #3, the options.structures
key is set to _structures.links
.
The _structures
key contains all the structures defined at a given level of the configuration cascade.
The key name for our structure group is links
.
The structure within links
. This structure contains fields for url
, logo
, and text
.
The _inputs
key containing our two arrays.
The key for the array header_social_media
.
The options.structures
key is set to _structures.links
.
The key for the array footer_affliate_links
.
As with #3, the options.structures
key is set to _structures.links
.
The _structures
key contains all the structures defined at a given level of the configuration cascade.
The key name for our structure group is links
.
The structure within links
. This structure contains fields for url
, logo
, and text
.
Let’s populate both arrays to see the links
structure in action.
We’ve added the link for “cloudcannon.com” to the header_social_media
array and “example.com” to the footer_affliate_links
array.
Here is how the arrays look in the sidebar of the Content Editor.
The arrays for header_social_media
and footer_affliate_links
are in the same file in this example. However, this does not have to be the case. You can add an array or object input to one file, define those inputs in a second file, and define the structure in a third, provided that all definitions have access to one another in the configuration cascade.
For more information on this topic, read our reference documentation on structures in the configuration cascade.
If your structure and input key names happen to match, CloudCannon will automatically reference the structure for you, provided that the structure and input are defined in the correct levels of the configurations cascade. This behavior is convenient if you do not want to configure your inputs to reference a structure. However, we recommend choosing different names due to the benefits outlined at the beginning of this section.
Add multiple structures to the same key#
CloudCannon can store multiple structures under a single key. By creating an array of structures under a single key, you can provide your team with a selection of object templates for any array or object input.
When referencing a key that contains multiple structures, all the structures within that key are available. Therefore, the key becomes the name of a group of structures rather than a single structure.
Here is an example of multiple structures under one key:
The key name of your group of structures. In this code, we have called our structure example
.
The example.values
key contains an array of structures. Each structure in this array is named using the label
key. You can also name a structure by configuring your structure previews.
The first structure in the group named example
. This structure contains fields for name
, description
, and image
.
The second structure in the group named example
. This structure is different from the first, containing fields for heading
and subtext
.
The key name of your group of structures. In this code, we have called our structure example
.
The example.values
key contains an array of structures. Each structure in this array is named using the label
key. You can also name a structure by configuring your structure previews.
The first structure in the group named example
. This structure contains fields for name
, description
, and image
.
The second structure in the group named example
. This structure is different from the first, containing fields for heading
and subtext
.
The key name of your group of structures. In this code, we have called our structure example
.
The example.values
key contains an array of structures. Each structure in this array is named using the label
key. You can also name a structure by configuring your structure previews.
The first structure in the group named example
. This structure contains fields for name
, description
, and image
.
The second structure in the group named example
. This structure is different from the first, containing fields for heading
and subtext
.
You can have as many structures under one key as you want. As you create multiple structures, it is important to name each one. In this example, we will use the label
key. Define your label
on the same level as the value
key using the label
. You can also name your structures by configuring your structure previews.
Multiple structures appear as a dropdown menu when you click the + Add button below an array or object.
However, as you create more structures, a dropdown may not be the best way to view them. You can create a searchable pop-up modal to view your structures using the style
key.
The style
key is set to modal
. Define the style key on the same level as the values
key under the name of your structures group.
The style
key is set to modal
. Define the style key on the same level as the values
key under the name of your structures group.
The style
key is set to modal
. Define the style key on the same level as the values
key under the name of your structures group.
The style
key has two values: “select” and “modal”. When the style
key is not configured, CloudCannon sets the style to select
by default.
When set to select
, clicking the + Add button for an array or object creates a dropdown menu. When set to modal
, the + Add button will create a pop-up modal. To switch to a modal, set the style
key to modal
.
You can configure your structure previews to alter how each structure appears in the dropdown menu or pop-up modal. For more information, including how to use images, icons, and descriptions to customize your structures, read our documentation on configuring your structure previews.