A Text input is an editing interface for plain text content. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.
These instructions assume that you know what type of Text input you want to configure and where in the configuration cascade. For more information, please read our documentation on Text inputs, inputs in general, and the configuration cascade.
To configure a Text input:
- Open your website files in your local development environment, or log in to CloudCannon and select the Site for which you want to configure your input.
- Navigate to the location in the configuration cascade where you want to configure your input. This can be the root of your CloudCannon Configuration File, within the
collections_config.*key in your CloudCannon Configuration File, a Schema file, the frontmatter of a markup file, or any where you configure a Structure. - Identify the
_inputskey, or create one at that level of the configuration cascade. - Add an input name key for your input under the
_inputskey (a.k.a.,_inputs.*). We recommend naming your input something simple that indicates the function or context. - Add the
typekey under your input name key, with the valuetext,textarea, oremail. - (Optional.) Add any other general configuration keys (e.g.,
label,comment,context) under your input name key. - (Optional.) Add any specific configuration keys under
_inputs.*.options(e.g.,show_count,empty_type).
CloudCannon will now apply this input configuration to all markup files that use your input name key, without needing to save your configuration. This allows you to make changes to your input configuration and see those changes affect inputs live.
When you are happy with your input configuration, you must save your input configuration.
_inputs:
blog_title:
type: text
page_description:
type: textarea
contact_address:
type: email
All inputs are defined under the _inputs key, regardless of where they are in the configuration cascade.
This Text input is called blog_title.
The value of the type key determines the input type. This is a text input.
This Textarea input is called page_description.
The value of the type key determines the input type. This is a textarea Text input.
This Email input is called contact_address.
The value of the type key determines the input type. This is a email Text input.
{
"_inputs": {
"blog_title": {
"type": "text"
},
"page_description": {
"type": "textarea"
},
"contact_address": {
"type": "email"
}
}
}All inputs are defined under the _inputs key, regardless of where they are in the configuration cascade.
This Text input is called blog_title.
The value of the type key determines the input type. This is a text input.
This Textarea input is called page_description.
The value of the type key determines the input type. This is a textarea Text input.
This Email input is called contact_address.
The value of the type key determines the input type. This is a email Text input.
When you add your input key name to a data or markup file, your configured Text input will appear in the Data Editor, Visual Editor, or Content Editor.
blog_title: The benefits of static sites
page_description: This page is about how to configure your inputs.
contact_address: support@cloudcannon.com
Input configuration options#
General configuration options are available for all input types. You can define the label, comment, and context box for your Text input, whether it is hidden or disabled, and how CloudCannon should handle configuration at multiple levels of the configuration cascade.
Specific configuration options for Text inputs include configuring how CloudCannon handles empty values. You can also add input validation to require a value, specify the minimum and maximum value length, or match a regular expression. For Textarea inputs, you can configure a character counter.
Here is an example of a Text input using some of the most commonly used configuration keys.
_inputs:
seo_description:
type: textarea
label: SEO Description
comment: Enter a description for search engines
options:
show_count: true
empty_type:
required: true
max_length: 160
{
"_inputs": {
"seo_description": {
"type": "textarea",
"label": "SEO Description",
"comment": "Enter a description for search engines",
"options": {
"show_count": true,
"empty_type": null,
"required": true,
"max_length": 160
}
}
}
}For a complete list of configuration keys available for inputs please read our inputs reference documentation.
These keys configure the appearance and functionality of Text inputs in CloudCannon.
This key toggles a character counter.
Available for Textarea input only.
This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.
Value must be one of the following:
string- an empty value for this input will be stored as "".null- an empty value for this input will be stored as a null value (default). This does not apply to TOML files.
This key determines whether CloudCannon should display an icon at the beginning of the text field and which icon it should display. The value must match a name from the Material Icons list.
This key has no default.
Show exampleHide example
In this example, we have added the person icon to the beginning of the text field to visually add context.
_inputs:
author:
options:
icon: person
{
"_inputs": {
"author": {
"options": {
"icon": "person"
}
}
}
}This key toggles whether CloudCannon requires this Input to have a value. If set to true, CloudCannon will require you to enter a value to save your changes, or discard your unsaved changes.
By default, this key is false (i.e, CloudCannon does not require this Input to have a value).
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Show exampleHide example
In this example, we want to require our team to enter an author value for markup files with this Input.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
{
"_inputs": {
"author": {
"type": "text",
"comment": "Enter the name of the author for this blog post.",
"options": {
"required": true
}
}
}
}This key defines a custom error message that explains why a value has failed the validation criteria from options.required. This key requires you to define options.required.
This key has no default.
This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.
Show exampleHide example
In this example, we prompt our team to use enter an Input value using a required message.
_inputs:
author:
type: text
comment: Enter the name of the author for this blog post.
options:
required: true
required_message: You are not allowed to leave this blank.
{
"_inputs": {
"author": {
"type": "text",
"comment": "Enter the name of the author for this blog post.",
"options": {
"required": true,
"required_message": "You are not allowed to leave this blank."
}
}
}
}This key defines the maximum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any non-negative integer. If this key is set to 0, CloudCannon requires the Input to be empty. If options.min_length is also configured, this key cannot be a smaller number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, allow_create must be set to true.
Show exampleHide example
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input limits you to a maximum of 125 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
{
"_inputs": {
"seo_description": {
"type": "markdown",
"comment": "Enter a brief description of this blog.",
"options": {
"max_length": 125,
"min_length": 25
}
}
}
}This key defines a custom error message that explains why a value has failed the validation criteria from options.max_length. This key requires you to define options.max_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Show exampleHide example
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
{
"_inputs": {
"seo_description": {
"type": "markdown",
"comment": "Enter a brief description of this blog.",
"options": {
"max_length": 125,
"max_length_message": "You are only allowed 125 characters.",
"min_length": 25,
"min_length_message": "Please write more than 25 characters."
}
}
}
}This key defines the minimum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.
Value can be any positive integer. If options.max_length is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, allow_create must be set to true.
Show exampleHide example
In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input requires a minimum of 25 characters.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
min_length: 25
{
"_inputs": {
"seo_description": {
"type": "markdown",
"comment": "Enter a brief description of this blog.",
"options": {
"max_length": 125,
"min_length": 25
}
}
}
}This key defines a custom error message that explains why a value has failed the validation criteria from options.min_length. This key requires you to define options.min_length.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Show exampleHide example
In this example, we prompt our team to enter a valid number of characters using a custom message.
_inputs:
seo_description:
type: markdown
comment: Enter a brief description of this blog.
options:
max_length: 125
max_length_message: You are only allowed 125 characters.
min_length: 25
min_length_message: Please write more than 25 characters.
{
"_inputs": {
"seo_description": {
"type": "markdown",
"comment": "Enter a brief description of this blog.",
"options": {
"max_length": 125,
"max_length_message": "You are only allowed 125 characters.",
"min_length": 25,
"min_length_message": "Please write more than 25 characters."
}
}
}
}This key defines a regular expression that the Input value must match. When configured, CloudCannon will require you to enter a value that matches the REGEX pattern. If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.
Value must be a valid REGEX string. If your REGEX string includes a \ character and CloudCannon Configuration File is a .yml file, use single quotes ' around the string to avoid a build error.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, allow_create must be set to true.
Show exampleHide example
In this example, we want our team to add an email address to the contact_email Input using the correct email format.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: Please use the format ___@___.__
{
"_inputs": {
"contact_email": {
"type": "email",
"options": {
"pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
"pattern_message": "Please use the format ___@___.__"
}
}
}
}This key defines the message that explains which regular expression an Input will accept. This key requires you to define options.pattern.
This key has no default.
This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.
Show exampleHide example
In this example, we prompt our team to use the correct email format in the contact_email Input using a pattern message.
_inputs:
contact_email:
type: email
options:
pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
pattern_message: Please use the format ___@___.__
{
"_inputs": {
"contact_email": {
"type": "email",
"options": {
"pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
"pattern_message": "Please use the format ___@___.__"
}
}
}
}Valid values#
Text inputs can have multiple valid values for empty, single line, and multiline content. Here are some examples of valid values for the key text. These work for Text, Textarea, and Email inputs.
Empty/null value:
text:
Any valid string (quoted or unquoted):
text: ""text: ''text: any stringtext: "any string"text: 'any string'
Any valid multiline string:
-
text: >
multiline string -
text: >-
multiline string -
text: >+
multiline string -
text: |
multiline string -
text: |-
multiline string -
text: |+
multiline string
Any valid string:
text = ""text = "any string"
Any valid escaped string:
text = ''text = 'any string (literal)'
Any valid multiline string:
-
text = """
multiline string""" -
text = """\
multiline string (trimmed) \
""" -
text = '''
literal multiline string'''
Null value:
"text": null
Any valid string:
"text": """text": "any string"
Any valid multiline string:
"text": "multiline \n string"
Unconfigured Text inputs#
In some cases, CloudCannon can still detect a Text input even if you have not configured it.
CloudCannon will interpret any unconfigured input with the key name:
textareaordescription, or that ends in_textareaor_description, as a Textarea input.emailoremail_address, or that ends in_emailor_email_address, as an Email input.
CloudCannon will interpret any unconfigured input with a string value as a Text input, provided that the key name does not match the naming convention for any other input type.
image_description: A beautiful forest scene
This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.
We recommend configuring your inputs for greater control over their functionality and appearance.