Recent searches

in
Developer ReferenceConfiguration File

Structure

On this page

This key defines data formats when adding new items to arrays and objects, with options for how editors choose from available values.

Appears in

├── _inputs
│   └── *
│       ├── Object Input
│       │   └── options
│       │       ├── entries
│       │       │   └── structures
│       │       │       └── Structure
│       │       └── structures
│       │           └── Structure
│       └── Array Input
│           └── options
│               └── structures
│                   └── Structure
└── _structures
    └── Structure

Type

Object

Properties

hide_extra_inputs — boolean#

This key toggles whether CloudCannon will hide inputs that are not present in a Structure from the Data Editor.

Setting this key to true will hide inputs that are not present in a Structure from the Data Editor. Hiding these inputs does not delete the data. You can see non-structure data keys by opening a file in the Source Editor. This key has no effect if remove_extra_inputs is true.

You can also configure this behavior for specific values of a Structure using values[*].hide_extra_inputs.

Defaults to: false

Appears in: Structure.

Show examplesHide examples

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.

Copied to clipboard
_structures:
  related_articles:
    hide_extra_inputs: true
    values:
      - value: 
        name: 
        description: 
        url:
{
  "_structures": {
    "related_articles": {
      "hide_extra_inputs": true,
      "values": [
        {
          "value": null,
          "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.

Defaults to: _type

Appears in: Structure.

Show examplesHide examples

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.

Copied to clipboard
_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:
{
  "_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.

remove_empty_inputs — boolean#

This key toggles whether CloudCannon will remove empty nested inputs from an Object Input or Array Input using a given Structure before persisting them to your file.

Setting this key to true will remove empty nested inputs from an Object Input or Array Input using a given Structure before persisting them to your file. CloudCannon considers an input to be empty when its value is null, ' ', or undefined. If this key is true, empty inputs will be visible in the Data Editor but not the Source Editor. For this key to function, you must also configure id_key for the Structure, as removing inputs prevents CloudCannon from comparing Structure values.

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

You can also configure this behavior for specific values of a Structure using structure.values.[*].remove_empty_inputs.

Defaults to: false

Appears in: Structure.

Show examplesHide examples

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.

Copied to clipboard
_structures:
  event_details:
    remove_empty_inputs: true
    values:
      - value: 
        name: 
        description: 
        url: 
        time: 
        place: 
        sponsor:
{
  "_structures": {
    "event_details": {
      "remove_empty_inputs": true,
      "values": [
        {
          "value": null,
          "name": null,
          "description": null,
          "url": null,
          "time": null,
          "place": null,
          "sponsor": null
        }
      ]
    }
  }
}
remove_extra_inputs — boolean#

This key toggles whether CloudCannon will remove inputs that are not present in a Structure from a file before loading it in an Editing Interface.

Setting this key to true will remove inputs that are not present in a Structure from a file before loading it in an Editing Interface. Non-Structure inputs will not be visible in the Visual Editor, Content Editor, or Data Editor, and saving the file will remove them from the file before persisting the changes to your Git repository.

You can also configure this behavior for specific values of a Structure using values[*].remove_extra_inputs.

Defaults to: true

Appears in: Structure.

Show examplesHide examples

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

Copied to clipboard
_structures:
  related_articles:
    remove_extra_inputs: true
    values:
      - value: 
        name: 
        description: 
        url:
{
  "_structures": {
    "related_articles": {
      "remove_extra_inputs": true,
      "values": [
        {
          "value": null,
          "name": null,
          "description": null,
          "url": null
        }
      ]
    }
  }
}
reorder_inputs — boolean#

This key toggles whether CloudCannon will reorder inputs in a file to match the order defined in a given Structure.

Setting this key to false will preserve the existing order of inputs in a file, regardless of the order defined in the Structure.

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

You can also configure this behavior for specific values of a Structure using values[*].reorder_inputs.

Defaults to: true

Appears in: Structure.

Show examplesHide examples

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

Copied to clipboard
_structures:
  related_articles:
    reorder_inputs: false
    values:
      - value: 
        name: 
        description: 
        url:
{
  "_structures": {
    "related_articles": {
      "reorder_inputs": false,
      "values": [
        {
          "value": null,
          "name": null,
          "description": null,
          "url": null
        }
      ]
    }
  }
}
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.

Defaults to: select

Allowed values: select modal

Appears in: Structure.

Show examplesHide examples

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

Copied to clipboard
_structures:
  related_articles:
    style: select
    values:
      - value: 
        name: 
        description: 
        url:
{
  "_structures": {
    "related_articles": {
      "style": "select",
      "values": [
        {
          "value": null,
          "name": null,
          "description": null,
          "url": null
        }
      ]
    }
  }
}
values — Array<values[*]>#

This key defines the options available for a Structure.

You must define this key for the Structure to function.

This key has no default.

Appears in: Structure.

Show examplesHide examples

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

Copied to clipboard
_structures:
  related_articles:
    values:
      - label: Blog
        id: 
        default: true
        tabbed: false
        tags:
          - blog
        value:
          title: 
          subtitle: 
          author: 
          featured_image: 
          url: 
        _inputs:
          featured_image:
            type: image
            options:
              width: 50
              height: 50
        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
{
  "_structures": {
    "related_articles": {
      "values": [
        {
          "label": "Blog",
          "id": null,
          "default": true,
          "tabbed": false,
          "tags": [
            "blog"
          ],
          "value": {
            "title": null,
            "subtitle": null,
            "author": null,
            "featured_image": null,
            "url": null
          },
          "_inputs": {
            "featured_image": {
              "type": "image",
              "options": {
                "width": 50,
                "height": 50
              }
            }
          },
          "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"
          }
        }
      ]
    }
  }
}
values_from_glob — Array<values_from_glob[*]>#

This key defines globs that filter which files CloudCannon should use for Structure value configuration.

Values in this array are relative to the root of your repository (i.e., /, not the value of source⁠) and must end in the file extension .cloudcannon.structure-value.yml (note the singular form of "value").

You can use this key anywhere you would use the _structures.*.values key.

Please see our documentation on structures_from_glob for defining a Structure in a split Configuration File.

This key has no default.

Appears in: Structure.

Show examplesHide examples

In this example, the staff Array Input uses inline Structure values from the main Configuration File and also references another value from the boardMember.cloudcannon.structure_value.yml in the /.cloudcannon/structures/ folder.

Copied to clipboard
_inputs:
  staff:
    type: array
    options:
      structures:
        values_from_glob:
          - /.cloudcannon/structures/boardMember.cloudcannon.structure-value.yml
        values:
          - label: Employee
            value:
              name: 
              title: 
              profile_picture: 
          - label: Manager
            value:
              name: 
              title: 
              profile_picture: 
              url:
{
  "_inputs": {
    "staff": {
      "type": "array",
      "options": {
        "structures": {
          "values_from_glob": [
            "/.cloudcannon/structures/boardMember.cloudcannon.structure-value.yml"
          ],
          "values": [
            {
              "label": "Employee",
              "value": {
                "name": null,
                "title": null,
                "profile_picture": null
              }
            },
            {
              "label": "Manager",
              "value": {
                "name": null,
                "title": null,
                "profile_picture": null,
                "url": null
              }
            }
          ]
        }
      }
    }
  }
}
Copied to clipboard
label: Board
value:
  name: 
  title: 
  profile_picture: 
  url: 
  description:
{
  "label": "Board",
  "value": {
    "name": null,
    "title": null,
    "profile_picture": null,
    "url": null,
    "description": null
  }
}
Open in a new tab