You can configure your inputs to determine the editing interface for structured data in your data files or the front matter of markup files. You can also customize the appearance and functionality of each input to improve the experience for your team members.
You can configure your inputs anywhere in the configuration cascade. In this article, we will show you how to configure an input at the global level in your configuration file.
To configure your inputs:
- Navigate to your CloudCannon configuration file and open it in the Source Editor.
- Identify the
_inputskey, or create one at the top level of your configuration file. - Add the key name of your input under
_inputs. - Add the
typekey nested under your input key, with an appropriate value for the type of input you want. - Add any other keys you want to configure under your input key (e.g.,
label,comment,context,options). - Save your changes to the CloudCannon configuration file.
Once you have configured your input, you must add the input key to a data file or the front matter of a markup file. CloudCannon will display the input in the Data Editor or the sidebar of the Visual or Content Editor when you open this file.
Misconfigured inputs appear as an orange warning box in the Data Editor or the sidebar of the Visual or Content Editor. If this occurs, please ensure that your input type and values are correct.
Example#
Let’s walk through an example.
We want to create a tag system for our blog articles so that users can filter our articles by tag for better search results. For this to work, we need to add a list containing relevant tags to the front matter of each blog file. When content creators write a new blog, they can select which tags apply using a Multiselect input in the sidebar of the Content Editor.
Here’s our input configuration:
_inputs:
blog_tags:
type: multiselect
label: Blog type
comment: Select a blog type
context:
open: false
title: Help
icon: help
content: |
Blog tags help our users filter articles by topic.
options:
values:
- Opinion
- Feature
- Resource
Configure all inputs under the _inputs key anywhere in the configuration cascade.
Enter the key name of the input here. In this example, the input name is blog_tags.
This input is a Multiselect input. For more information, please read our documentation on Multiselect inputs.
The title of this input is “Blog type”. If no label is configured, CloudCannon will use the key name in title case.
The subtitle of this input is “Select a blog type”.
To help our team members use this input, we have configured a context dropdown with extra information.
Configuration options for inputs are nested keys under options.
This input has three possible values in an array under the values key: “Opinion”, “Feature”, and “Resource”.
{
"_inputs": {
"blog_tags": {
"type": "multiselect",
"label": "Blog type",
"comment": "Select a blog type",
"context": {
"open": false,
"title": "Help",
"icon": "help",
"content": "Blog tags help our users filter articles by topic.\n"
},
"options": {
"values": [
"Opinion",
"Feature",
"Resource"
]
}
}
}
}Configure all inputs under the _inputs key anywhere in the configuration cascade.
Enter the key name of the input here. In this example, the input name is blog_tags.
This input is a Multiselect input. For more information, please read our documentation on Multiselect inputs.
The title of this input is “Blog type”. If no label is configured, CloudCannon will use the key name in title case.
The subtitle of this input is “Select a blog type”.
To help our team members use this input, we have configured a context dropdown with extra information.
Configuration options for inputs are nested keys under options.
This input has three possible values in an array under the values key: “Opinion”, “Feature”, and “Resource”.
Once we add the above code to our configuration file, we need to add the input to the front matter of our blog file.
---
blog_tags:
---
The content of the blog goes here.
CloudCannon will show the blog_tags input in the Data Editor and the sidebar of the Visual or Content Editor.
General configuration options#
You can configure the appearance and functionality of inputs in CloudCannon. Some configuration keys apply to all inputs; however, CloudCannon also has default configuration options specific to each input type. For more information about configuring different input types, please see our documentation for each input type.
To configure your inputs, add configuration keys nested under your input key name inside of _inputs.
_inputs:
date_created:
type: datetime
label: Date of article creation
comment: UTC +0 timezone
context:
open: false
title: Help
icon: help
content: This field will automatically populate when you create an article.
hidden: false
instance_value: NOW
cascade: true
options:
timezone: Etc/UTC
{
"_inputs": {
"date_created": {
"type": "datetime",
"label": "Date of article creation",
"comment": "UTC +0 timezone",
"context": {
"open": false,
"title": "Help",
"icon": "help",
"content": "This field will automatically populate when you create an article."
},
"hidden": false,
"instance_value": "NOW",
"cascade": true,
"options": {
"timezone": "Etc/UTC"
}
}
}
}All inputs have the following options available:
This key defines which inputs are available at a given level of the configuration cascade.
The following nested keys are available for each input inside _inputs:
typelabelcommentcontexthiddeninstance_valuecascadeoptions
This key has no default. If undefined at higher levels of the configuration cascade, _inputs will default to any values configured in the CloudCannon configuration file.
This key changes the type of editing interface used for an input. Each input has a different appearance and functionality, processes and accepts different types of values, and has different configuration options.
Value can be one of the following: auto, checkbox, switch, code, color, datetime, date, time, file, document, image, number, range, object, array, select, multiselect, choice, multichoice, text, textarea, email, disabled, html, markdown, or url.
If the type or value of an input is misconfigured, CloudCannon will display an orange warning instead of an input. If type is not configured for an input, CloudCannon will attempt to determine input type based on value or key name conventions.
This key has no default.
This key changes the bold title text above an input.
By default, CloudCannon generate the value for from the input key name, in title case (e.g., page_title will become "Page Title").
This key changes the subtitle text above an input. CloudCannon supports a limited selection of Markdown formatting for the value of this key: links, bold, italic, subscript, superscript, and inline code.
This key has no default.
This key enables you to define a context box for extra information about an input. The following nested keys are available:
opentitleiconcontent(required)
This key has no default.
This key determines whether the context box is open to display text content by default.
By default, this key is false (i.e., closed).
This key determines the title of the context box.
By default, this key value is "Context".
This key determines which icon appears next to the context box title. The value must match an icon name from Google’s Material Icons list.
This key has no default.
This key determines the text content inside the context box. CloudCannon supports a limited selection of Markdown formatting for the value of this key: links, headings, bold, italic, subscript, superscript, and inline code.
This key is required for the context object to function.
This key has no default.
This key toggles the visibility of an input in the Data Editor or the sidebar of the Visual or Content Editor. Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input. You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key determines whether an input is automatically populated with a value when the input is created. This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
This key has no default.
This key determines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry. Usually, once an option is found in the cascade, there's no reason to keep looking. When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade. For example, define a comment globally, but use collection-specific label for inputs in different collections. You can stop the cascade at any point in the configuration cascade by setting cascade to false.
By default, this key is true (i.e., merges all configurations for an input in the cascade).
This key determines the configuration specific to each input type. If this key and nested keys are not defined, CloudCannon will use the default configuration options for that input type.
This key has no default.
For more information on options, please read our documentation on each input type.