Structures Reference

A Structure is a predefined, custom template that determines what should populate an array or object input.

This article covers all keys available in CloudCannon for configuring your Structures. For more information, please read our documentation on Structures in general and creating a Structure.

All Structures options are configured within the _structures key at any level in the configuration cascade.

_structures — Object#

This key defines which structures are available for Object inputs and Array inputs at a given level of the configuration cascade.

The following nested keys are available for each structure inside _structures:

id_key
style
hide_extra_inputs
reorder_inputs
remove_empty_inputs
remove_extra_inputs
values (required)

This key has no default. If undefined at higher levels of the configuration cascade, _structures will default to any values configured in the CloudCannon configuration file.

Show exampleHide example

In this example, we want to populate an Array input in the blog Collection with Related Articles, including the name, description, and url fields.

cloudcannon.config.yaml

copied

collections_config:
  blog:
    _structures:
      related_articles:
        style: select
        values:
          - preview:
              text:
                - key: name
              subtext:
                - key: url
            value:
              name: 
              description: 
              url:

cloudcannon.config.json

copied

{
  "collections_config": {
    "blog": {
      "_structures": {
        "related_articles": {
          "style": "select",
          "values": [
            {
              "preview": {
                "text": [
                  {
                    "key": "name"
                  }
                ],
                "subtext": [
                  {
                    "key": "url"
                  }
                ]
              },
              "value": {
                "name": null,
                "description": null,
                "url": null
              }
            }
          ]
        }
      }
    }
  }
}

In this example, we want to populate an Array input with Staff members, including the name, job_description, and profile_picture fields for all staff types, and the url field for Managers only.

cloudcannon.config.yaml

copied

_structures:
  staff:
    style: modal
    hide_extra_inputs: false
    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

cloudcannon.config.json

copied

{
  "_structures": {
    "staff": {
      "style": "modal",
      "hide_extra_inputs": false,
      "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"
          }
        }
      ]
    }
  }
}

Structure setup#

These keys configure how a Structure functions in CloudCannon.

style — String#

This key defines how CloudCannon shows Structure options to populate an Object or Array input. This can be using a Select-style search bar or a pop-up modal. Modals are useful when you have several value options for your Structure.

Values can be one of the following: select, or modal.

By default, this key is select.

Show exampleHide example

In this example, the related_articles Structure only has one option so a select searchbar is appropriate.

cloudcannon.config.yaml

copied

_structures:
  related_articles:
    style: select
    values:
      - value:
          name: 
          description: 
          url:

cloudcannon.config.json

copied

{
  "_structures": {
    "related_articles": {
      "style": "select",
      "values": [
        {
          "value": {
            "name": null,
            "description": null,
            "url": null
          }
        }
      ]
    }
  }
}

id_key — String#

This key defines which key within values[*].value CloudCannon should use to identify the Structure option. If CloudCannon cannot find this key in a Structure value, it will compare all other key names in the Structure value to find the correct one.

By default, this key is _type.

Show exampleHide example

In this example, we have change the id_key from the default _type to component to match our existing configuration in the content_blocks Array input.

cloudcannon.config.yaml

copied

_inputs:
  content_blocks:
    type: array
    options: 
    structures: _structures.page_components
_structures:
  page_components:
    id_key: component
    values:
      - label: Hero Component
        value:
          component: hero
          title: 
          description: 
          image_path: 
          link:
            text: 
            url: 
      - label: Feature Component
        value:
          component: feature
          image_path: 
          title: 
          description: 
          button:
            link: 
            text: 
          reversed_layout: false
      - label: Video Component
        value:
          component: video
          image_path: 
          videoUrl:

We have configured the Array input content_blocks to use the page_components Structures.

The id_key for page_components is component.

Each option in the values array has the component key with a different value to identify that option.

cloudcannon.config.json

copied

{
  "_inputs": {
    "content_blocks": {
      "type": "array",
      "options": null,
      "structures": "_structures.page_components"
    }
  },
  "_structures": {
    "page_components": {
      "id_key": "component",
      "values": [
        {
          "label": "Hero Component",
          "value": {
            "component": "hero",
            "title": null,
            "description": null,
            "image_path": null,
            "link": {
              "text": null,
              "url": null
            }
          }
        },
        {
          "label": "Feature Component",
          "value": {
            "component": "feature",
            "image_path": null,
            "title": null,
            "description": null,
            "button": {
              "link": null,
              "text": null
            },
            "reversed_layout": false
          }
        },
        {
          "label": "Video Component",
          "value": {
            "component": "video",
            "image_path": null,
            "videoUrl": null
          }
        }
      ]
    }
  }
}

We have configured the Array input content_blocks to use the page_components Structures.

The id_key for page_components is component.

Each option in the values array has the component key with a different value to identify that option.

hide_extra_inputs — Boolean#

This key toggles whether inputs that are not present in the Structure are visible in the Data Editor. Hiding these inputs does not delete the data. You can see structured data keys from outside a Structure by opening a file in the Source Editor. This key has no effect if remove_extra_inputs is true.

By default, this key is false (i.e, non-structure inputs are visible in the Data Editor).

Show exampleHide example

In this example, we don't want inputs outside of those listed in the Structure (e.g., old inputs from deprecated versions of this Structure) to appear in the Data Editor.

cloudcannon.config.yaml

copied

_structures:
  related_articles:
    hide_extra_inputs: true
    values:
      - value:
          name: 
          description: 
          url:

cloudcannon.config.json

copied

{
  "_structures": {
    "related_articles": {
      "hide_extra_inputs": true,
      "values": [
        {
          "value": {
            "name": null,
            "description": null,
            "url": null
          }
        }
      ]
    }
  }
}

reorder_inputs — Boolean#

This key toggles whether inputs in a file are reordered to match the order in the Structure.

By default, this key is true (i.e, inputs are reordered to match the Structure).

Show exampleHide example

In this example, we want to preserve the order of the inputs in a file over the order in the associated Structure.

cloudcannon.config.yaml

copied

_structures:
  related_articles:
    reorder_inputs: false
    values:
      - value:
          name: 
          description: 
          url:

cloudcannon.config.json

copied

{
  "_structures": {
    "related_articles": {
      "reorder_inputs": false,
      "values": [
        {
          "value": {
            "name": null,
            "description": null,
            "url": null
          }
        }
      ]
    }
  }
}

remove_empty_inputs — Boolean#

This key toggles whether CloudCannon will remove empty nested inputs from an Object or Array input that uses this Structure when you save the input configuration. CloudCannon consideres an input to be empty when its value is null, ' ', or undefined.

If this key is set to true, the id_key must be configured for this Structure, as removing inputs prevents CloudCannon from comparing Structure values. You can bring back empty inputs removed from an Object or Array input by re-adding the structure to the input.

By default, this key is false (i.e, CloudCannon does not remove empty inputs).

Show exampleHide example

In this example, we want to delete any unnecessary nested inputs (i.e., input we choose not to provide a value for) from Object or Array inputs referenceing the event_details Structure.

cloudcannon.config.yaml

copied

_structures:
  event_details:
    remove_empty_inputs: true
    values:
      - value:
          name: 
          description: 
          url: 
          time: 
          place: 
          sponsor:

cloudcannon.config.json

copied

{
  "_structures": {
    "event_details": {
      "remove_empty_inputs": true,
      "values": [
        {
          "value": {
            "name": null,
            "description": null,
            "url": null,
            "time": null,
            "place": null,
            "sponsor": null
          }
        }
      ]
    }
  }
}

remove_extra_inputs — Boolean#

This key toggles whether inputs that are not present in the Structure are removed from the file before CloudCannon loads it in an editing interface. Saving the file will push this change to your Git repository.

By default, this key is false(i.e., inputs not present in the Structure are not removed from the file).

Show exampleHide example

In this example, we want to delete old inputs that are not in the Structure from the associated file.

cloudcannon.config.yaml

copied

_structures:
  related_articles:
    remove_extra_inputs: true
    values:
      - value:
          name: 
          description: 
          url:

cloudcannon.config.json

copied

{
  "_structures": {
    "related_articles": {
      "remove_extra_inputs": true,
      "values": [
        {
          "value": {
            "name": null,
            "description": null,
            "url": null
          }
        }
      ]
    }
  }
}

Structure values#

All Structure values are configured under the _structures.values key.

values — Array of Objects#

This key defines the options available for a Structure. You must define this key for the Structure to function.

The following nested keys are available for each entry in the values array:

id
default
tabbed
tags
value (required)
groups
label
picker_preview
preview

This key has no default.

Show exampleHide example

In this example, we want to add the title, subtitle, author, image, and url fields to Object or Array inputs that reference this Structure.

cloudcannon.config.yaml

copied

_structures:
  related_articles:
    values:
      - label: Blog
        id: 
        default: true
        tabbed: false
        tags:
          - blog
        value:
          title: 
          subtitle: 
          author: 
          image: 
          url: 
        groups:
          - heading: Titles
            inputs:
              - title
              - subtitle
          - heading: Details
            inputs:
              - author
              - image
              - url
        preview:
          text:
            - template: '{title}'
          subtext:
            - template: By {author}
          image:
            - key: image
        picker_preview:
          text: Blog
          subtext: Add a related blog
          icon: post_add

cloudcannon.config.json

copied

{
  "_structures": {
    "related_articles": {
      "values": [
        {
          "label": "Blog",
          "id": null,
          "default": true,
          "tabbed": false,
          "tags": [
            "blog"
          ],
          "value": {
            "title": null,
            "subtitle": null,
            "author": null,
            "image": null,
            "url": null
          },
          "groups": [
            {
              "heading": "Titles",
              "inputs": [
                "title",
                "subtitle"
              ]
            },
            {
              "heading": "Details",
              "inputs": [
                "author",
                "image",
                "url"
              ]
            }
          ],
          "preview": {
            "text": [
              {
                "template": "{title}"
              }
            ],
            "subtext": [
              {
                "template": "By {author}"
              }
            ],
            "image": [
              {
                "key": "image"
              }
            ]
          },
          "picker_preview": {
            "text": "Blog",
            "subtext": "Add a related blog",
            "icon": "post_add"
          }
        }
      ]
    }
  }
}

Structure values setup#

These keys configure how a particular Structure value functions in CloudCannon.

id — Boolean#

This key defines the string used to identify a given Structure value when refering to it from other input configuration.

This key has no default.

default — Boolean#

This key toggles whether CloudCannon should treat an entry in the values array as the default option for your Object or Array input. If multiple entries in the values array are set to true, CloudCannon will use the first entry.

If CloudCannon cannot determine the type of an entry within the values array based on the id_key or matching inputs in the values.value array, it will fall back to the default entry.

By default, this key is false (i.e., the entry is not the default option).

Show exampleHide example

In this example, we want the entry labelled Employee to be our default option for populating inputs configured with the staff Structure.

cloudcannon.config.yaml

copied

_structures:
  staff:
    style: modal
    values:
      - label: Employee
        default: true
        value:
          name: 
          job_description: 
          profile_picture: 
      - label: Manager
        value:
          name: 
          job_description: 
          profile_picture: 
          url:

cloudcannon.config.json

copied

{
  "_structures": {
    "staff": {
      "style": "modal",
      "values": [
        {
          "label": "Employee",
          "default": true,
          "value": {
            "name": null,
            "job_description": null,
            "profile_picture": null
          }
        },
        {
          "label": "Manager",
          "value": {
            "name": null,
            "job_description": null,
            "profile_picture": null,
            "url": null
          }
        }
      ]
    }
  }
}

tabbed — Boolean#

This key toggles whether CloudCannon should create tabs in the Data Editor if you have two layers of nested object within your Structure.

CloudCannon would create tabs automatically for Non-unified Configuration Sites, but it must be explicitly configured in the Unified Configuration file format.

By default, this key is false (i.e., Object and Array inputs using this Structure option are not tabbed).

Show exampleHide example

In this example, we want the content and style keys in our Structure to be tabs at the top of the Data Editor, with the title and text, and color and font keys nested within those tabs respectively.

cloudcannon.config.yaml

copied

_structures:
  components:
    values:
      - label: Component
        tabbed: true
        value:
          content:
            title: 
            text: 
          style:
            color: 
            font:

cloudcannon.config.json

copied

{
  "_structures": {
    "components": {
      "values": [
        {
          "label": "Component",
          "tabbed": true,
          "value": {
            "content": {
              "title": null,
              "text": null
            },
            "style": {
              "color": null,
              "font": null
            }
          }
        }
      ]
    }
  }
}

tags — Array#

This key defines which tags are associated with a given value in a Structure. You can use tags to group and filter Structure options when selecting from a modal. The style key must be set to modal for this key to function.

This key has no default.

Show exampleHide example

In this example we have three options for the page_components Structure: Hero Component, Feature Component, and Video Component. We can search the Structure modal using the image, text, button, and video tags to filter Structure values.

cloudcannon.config.yaml

copied

_structures:
  page_components:
    style: modal
    values:
      - label: Hero Component
        tags:
          - image
          - text
        value:
          title: 
          description: 
          image_path: 
          link:
            text: 
            url: 
      - label: Feature Component
        tags:
          - image
          - text
          - button
        value:
          image_path: 
          title: 
          description: 
          button:
            link: 
            text: 
          reversed_layout: false
      - label: Video Component
        tags:
          - image
          - video
        value:
          image_path: 
          videoUrl:

cloudcannon.config.json

copied

{
  "_structures": {
    "page_components": {
      "style": "modal",
      "values": [
        {
          "label": "Hero Component",
          "tags": [
            "image",
            "text"
          ],
          "value": {
            "title": null,
            "description": null,
            "image_path": null,
            "link": {
              "text": null,
              "url": null
            }
          }
        },
        {
          "label": "Feature Component",
          "tags": [
            "image",
            "text",
            "button"
          ],
          "value": {
            "image_path": null,
            "title": null,
            "description": null,
            "button": {
              "link": null,
              "text": null
            },
            "reversed_layout": false
          }
        },
        {
          "label": "Video Component",
          "tags": [
            "image",
            "video"
          ],
          "value": {
            "image_path": null,
            "videoUrl": null
          }
        }
      ]
    }
  }
}

value — Object#

This key defines which nested inputs the Structure should add to an Object or Array input. You must define this key for the Structure to function.

Nested keys can be any inputs you require in your Object or Array. For more information, please read our documentation on configuring your inputs.

This key has no default.

Show exampleHide example

In this example we want to populate the details Object input with the nested keys title, subtitle, and author we have defined under the values.value key.

cloudcannon.config.yaml

copied

_structures:
  article_information:
    values:
      - label: Blog
        value:
          title: 
          subtitle: 
          author: 
_inputs:
  details:
    type: object
    options:
      structures: _structures.article_information

cloudcannon.config.json

copied

{
  "_structures": {
    "article_information": {
      "values": [
        {
          "label": "Blog",
          "value": {
            "title": null,
            "subtitle": null,
            "author": null
          }
        }
      ]
    }
  },
  "_inputs": {
    "details": {
      "type": "object",
      "options": {
        "structures": "_structures.article_information"
      }
    }
  }
}

groups — Array of Objects#

This key defines the order and customing grouping for inputs within a Structure. Each groups can have a heading.

The following nested keys are available for each entry in the groups array:

heading
inputs

By default, CloudCannon respects the order of inputs as configured in the values.value key and does not include any groups.

Show exampleHide example

In this example, we want to separate the inputs into two groups with descriptive headings: title and subtitle under the Titles heading, and author under the Details heading.

cloudcannon.config.yaml

copied

_structures:
  article_information:
    values:
      - label: Blog
        value:
          title: 
          subtitle: 
          author: 
        groups:
          - heading: Titles
            inputs:
              - title
              - subtitle
          - heading: Details
            inputs:
              - author

cloudcannon.config.json

copied

{
  "_structures": {
    "article_information": {
      "values": [
        {
          "label": "Blog",
          "value": {
            "title": null,
            "subtitle": null,
            "author": null
          },
          "groups": [
            {
              "heading": "Titles",
              "inputs": [
                "title",
                "subtitle"
              ]
            },
            {
              "heading": "Details",
              "inputs": [
                "author"
              ]
            }
          ]
        }
      ]
    }
  }
}

Structure values display#

These keys configure how a particular Structure value appears in CloudCannon.

label — String#

This key defines the dispaly name for a given value in a Structure. The name will appear in the + Add button dropdown below an Object or Array input or in the Structures modal (if configured).

By default, this key falls back to unknown.

Show exampleHide example

In this example, we want two value options for our staff structure: one called Manager and one called Employee.

cloudcannon.config.yaml

copied

_structures:
  staff:
    values:
      - label: Employee
        value:
          name: 
          job_description: 
          profile_picture: 
      - label: Manager
        value:
          name: 
          job_description: 
          profile_picture: 
          url:

cloudcannon.config.json

copied

{
  "_structures": {
    "staff": {
      "values": [
        {
          "label": "Employee",
          "value": {
            "name": null,
            "job_description": null,
            "profile_picture": null
          }
        },
        {
          "label": "Manager",
          "value": {
            "name": null,
            "job_description": null,
            "profile_picture": null,
            "url": null
          }
        }
      ]
    }
  }
}

picker_preview — Object#

This key defines the appearance of a Card. You can configure Card preview for Structures and Snippets. This key is separate from the preview key and only affects the select and modal lists.

The following nested keys are available:

text
subtext
icon
icon_color
image
metadata
gallery

By default, CloudCannon uses the values configured for preview

Show exampleHide example

In this example, we have configured different appearance for Cards in the events array and Cards in the Structures modal used to select values for the Array input.

cloudcannon.config.yaml

copied

_structures:
  events:
    style: modal
    values:
      - label: Birthday
        value:
          name: 
          date: 
          place: 
          image: 
          description: 
        preview:
          text:
            - template: '{name}s birthday event!'
          subtext:
            - template: On {date} at {place}
          image:
            - key: image
        picker_preview:
          text: Birthday
          subtext: Add someones birthday to the events array
          icon: cake
      - label: Holiday
        value:
          date: 
          place: 
          image: 
          description: 
        preview:
          text:
            - template: Holiday to {place}!
          subtext:
            - template: On {date}
          image:
            - key: image
        picker_preview:
          text: Holiday
          subtext: Add a holiday to the events array
          icon: beach_access
_inputs:
  events:
    type: array
    options:
      structures: _structures.events

cloudcannon.config.json

copied

{
  "_structures": {
    "events": {
      "style": "modal",
      "values": [
        {
          "label": "Birthday",
          "value": {
            "name": null,
            "date": null,
            "place": null,
            "image": null,
            "description": null
          },
          "preview": {
            "text": [
              {
                "template": "{name}s birthday event!"
              }
            ],
            "subtext": [
              {
                "template": "On {date} at {place}"
              }
            ],
            "image": [
              {
                "key": "image"
              }
            ]
          },
          "picker_preview": {
            "text": "Birthday",
            "subtext": "Add someones birthday to the events array",
            "icon": "cake"
          }
        },
        {
          "label": "Holiday",
          "value": {
            "date": null,
            "place": null,
            "image": null,
            "description": null
          },
          "preview": {
            "text": [
              {
                "template": "Holiday to {place}!"
              }
            ],
            "subtext": [
              {
                "template": "On {date}"
              }
            ],
            "image": [
              {
                "key": "image"
              }
            ]
          },
          "picker_preview": {
            "text": "Holiday",
            "subtext": "Add a holiday to the events array",
            "icon": "beach_access"
          }
        }
      ]
    }
  },
  "_inputs": {
    "events": {
      "type": "array",
      "options": {
        "structures": "_structures.events"
      }
    }
  }
}

For more information, please read our documentation on configuring your Card previews.

preview — Object#

This key defines the appearance of a Card. You can configure Card preview for Collections, Schemas, Object inputs, Array inputs, Select and Multiselect inputs, Structures, the Structure modal, Snippets, and the Snippet modal.

The following nested keys are available:

text
subtext
icon
icon_color
image
metadata
gallery

This key has no default.

Show exampleHide example

In this example, we have configured the appearance of file Cards in the Collection browser.

cloudcannon.config.yaml

copied

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

cloudcannon.config.json

copied

{
  "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.

cloudcannon.config.yaml

copied

_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

cloudcannon.config.json

copied

{
  "_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"
          }
        }
      ]
    }
  }
}

For more information, please read our documentation on configuring your Card previews.

Structures now support the new preview option. Read our migration guide if you are still using the old options: text_key, subtext_key, image_key, preview_image, icon, image, description, and image_size.