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.

To create a structure:

1. Navigate to your global configuration file and open it in the Source Editor.
2. Identify the _structures key, or create one.
3. Add your structure within the _structures key.
4. Save your changes to the global configuration file.

Here is an example of a basic structure:

_structures:
  example:
    values:
      - value:
          name: 
          description: 
          image: 

{
  "_structures": {
    "example": {
      "values": [
        {
          "value": {
            "name": null,
            "description": null,
            "image": null
          }
        }
      ]
    }
  }
}

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.

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:

1. Navigate to your global configuration file and open it in the Source Editor.
2. Identify the _inputs key and the input you want to reference the structure from, or create them.
3. Reference your structure using the options.structures key within your array or object input.
4. Save your changes to the global configuration file.

Here is an example of an array input referencing a structure:

_inputs:
  array_one:
    type: array
    options:
      structures: _structures.example

{
  "_inputs": {
    "array_one": {
      "type": "array",
      "options": {
        "structures": "_structures.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:

_inputs:
  header_social_media:
    type: array
    options:
      structures: _structures.links
  footer_affliate_links:
    type: array
    options:
      structures: _structures.links
_structures:
  links:
    values:
      - value:
          url: 
          logo: 
          text: 

{
  "_inputs": {
    "header_social_media": {
      "type": "array",
      "options": {
        "structures": "_structures.links"
      }
    },
    "footer_affliate_links": {
      "type": "array",
      "options": {
        "structures": "_structures.links"
      }
    }
  },
  "_structures": {
    "links": {
      "values": [
        {
          "value": {
            "url": null,
            "logo": null,
            "text": null
          }
        }
      ]
    }
  }
}

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.

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:

_structures:
  example:
    values:
      - label: First
        value:
          name: 
          description: 
          image: 
      - label: Second
        value:
          heading: 
          subtext: 

{
  "_structures": {
    "example": {
      "values": [
        {
          "label": "First",
          "value": {
            "name": null,
            "description": null,
            "image": null
          }
        },
        {
          "label": "Second",
          "value": {
            "heading": null,
            "subtext": null
          }
        }
      ]
    }
  }
}

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.

_structures:
  example:
    style: modal
    values:
      - label: First
        value:
          name: 
          description: 
          image: 
      - label: Second
        value:
          heading: 
          subtext: 

{
  "_structures": {
    "example": {
      "style": "modal",
      "values": [
        {
          "label": "First",
          "value": {
            "name": null,
            "description": null,
            "image": null
          }
        },
        {
          "label": "Second",
          "value": {
            "heading": null,
            "subtext": null
          }
        }
      ]
    }
  }
}

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.