Creating a Structure with multiple typed values and using it for an Object Input provides an editing interface to create predefined object values. This article covers how to switch between these predefined values once created.
A Team Member can change an object's Structure value by deleting the object and creating it again with a different value. You can let them switch an existing object in place instead by configuring the Structure's ID key as a Select Input. CloudCannon matches an object to a Structure value by its ID key if present (set with id_key, _type by default). Choosing a different option in the ID key input changes the object to match the Structure value.
For example, a page section might be a hero, a call to action, or a gallery. Each needs its own properties, but all of them share a heading and a background color. With a Select Input on the ID key, a Team Member can turn a hero into a call to action without having to recreate the value and losing the heading they have written.
Switching Structure values changes the file. Alternatively, if you want every property to stay in the file and only control which inputs a Team Member sees, hide or disable an input with an expression instead.
Configure the ID key as a Select Input#
To let Team Members switch an object between Structure values:
- Open the configuration file where you define your Structure, under
_structuresor in theoptions.structureskey of an input. - Give the ID key a unique string value in the
valueof every Structure value. - Configure the ID key as a
choiceorselectinput. List every ID key value underoptions.values, and setoptions.allow_emptytofalse. - Reference that input from every Structure value, next to
labelandvalue, with_inputs_from_globfor an input defined in its own file or_inputsfor one defined inline. - Set
remove_extra_inputsandreorder_inputson your Structure to keep data consistent. - Save your changes.
CloudCannon will show the ID key as a Select Input on the object. When a Team Member selects a different option, CloudCannon applies the matching Structure value straight away, as an unsaved change.
Every Structure value needs to reference the input, because CloudCannon only applies the inputs of the value an object currently matches. Defining the input once in its own file and referencing it with _inputs_from_glob keeps the values in step.
Keys that begin with an underscore, including the default _type, are hidden by default. If your ID key begins with an underscore, add hidden: false to its input configuration so Team Members can see the Select Input.
In the following example, the section object uses the hero, call to action, and gallery values from above. The type input lives in its own file, and each value references it.
---
section:
type: hero
heading: Welcome
background_color: '#f4efe6'
subheading: ''
image: ''
---type:
type: choice
options:
allow_empty: false
values:
- hero
- cta
- gallery{
"type": {
"type": "choice",
"options": {
"allow_empty": false,
"values": [
"hero",
"cta",
"gallery"
]
}
}
}_inputs:
section:
type: object
options:
structures:
id_key: type
reorder_inputs: true
remove_extra_inputs: true
values:
- label: Hero
_inputs_from_glob:
- /.cloudcannon/inputs/section-type.cloudcannon.inputs.yml
value:
type: hero
heading: Welcome
background_color: '#f4efe6'
subheading: ''
image: ''
- label: Call to action
_inputs_from_glob:
- /.cloudcannon/inputs/section-type.cloudcannon.inputs.yml
value:
type: cta
heading: Ready to start?
background_color: '#f4efe6'
button_text: Get started
button_link: /signup/
- label: Gallery
_inputs_from_glob:
- /.cloudcannon/inputs/section-type.cloudcannon.inputs.yml
value:
type: gallery
heading: Our work
background_color: '#ffffff'
columns: 3
images: []{
"_inputs": {
"section": {
"type": "object",
"options": {
"structures": {
"id_key": "type",
"reorder_inputs": true,
"remove_extra_inputs": true,
"values": [
{
"label": "Hero",
"_inputs_from_glob": [
"/.cloudcannon/inputs/section-type.cloudcannon.inputs.yml"
],
"value": {
"type": "hero",
"heading": "Welcome",
"background_color": "#f4efe6",
"subheading": "",
"image": ""
}
},
{
"label": "Call to action",
"_inputs_from_glob": [
"/.cloudcannon/inputs/section-type.cloudcannon.inputs.yml"
],
"value": {
"type": "cta",
"heading": "Ready to start?",
"background_color": "#f4efe6",
"button_text": "Get started",
"button_link": "/signup/"
}
},
{
"label": "Gallery",
"_inputs_from_glob": [
"/.cloudcannon/inputs/section-type.cloudcannon.inputs.yml"
],
"value": {
"type": "gallery",
"heading": "Our work",
"background_color": "#ffffff",
"columns": 3,
"images": []
}
}
]
}
}
}
}
}CloudCannon uses the type key to match the section object to a Structure value.
Orders the object's properties to match the matched Structure value.
Removes properties that the matched Structure value does not define.
Loads the type input from its own file for objects that match this Structure value. The "Call to action" and "Gallery" values reference the same file.
The ID key value for this Structure value. It matches the hero option in the Select Input.
What happens when the Structure changes#
A Team Member fills in the hero section with a heading, a subheading, an image, and a darker background:
---
section:
type: hero
heading: Spring blend is here
background_color: '#dfe8dc'
subheading: Roasted in small batches every Monday
image: /uploads/spring-blend.jpg
---They change type from hero to cta and save. The front matter now looks like this:
---
section:
type: cta
heading: Spring blend is here
background_color: '#dfe8dc'
button_text: Get started
button_link: /signup/
---heading and background_color kept their values. button_text and button_link arrived with their defaults. subheading and image were removed, and the properties follow the order of the "Call to action" value.
CloudCannon applies the same rules whenever it matches an object to a Structure value, including when a Team Member opens the file:
- Inputs both the object and the new Structure value have keep their value if they are the same type.
- Inputs only the new Structure value has are added.
- Inputs only the object has are removed when
remove_extra_inputsistrue, and kept when it isfalse. - Inputs are reordered to match the Structure value when
reorder_inputsistrue, with any remaining after those.
Removed input values are gone for good. If the Team Member switches the section back to hero, subheading and image come back as empty strings from the "Hero" value, not as the values they entered. Leaving remove_extra_inputs as false keeps those values, but the object then carries properties from every Structure value it has used, and CloudCannon saves them to the file.
You can also set remove_empty_inputs to true to drop empty inputs from the top level of the object on each switch.
For more information, please read our reference documentation on the Structure type and the options available in a Structure value.