☁️ Loving our new documentation website? Provide feedback in the CloudCannon Community! ✨

Developer ReferenceConfiguration File

options

Table of contents

Description:

This key defines options that are specific to Select Inputs.

Appears in:
└── _inputs
    └── *
        └── Select Input
            └── options
Type:
Object
Properties:
allow_createboolean#

This key toggles whether CloudCannon will allow new text values to be created at edit time.

Setting this key to true will allow new text values to be created at edit time.

Defaults to: false

Show examplesHide examples

In this example, CloudCannon will allow users to add new values to a Select Input.

Copied to clipboard
_inputs:
  category:
    type: select
    options:
      values:
        - Blog
        - News
      allow_create: true
{
  "_inputs": {
    "category": {
      "type": "select",
      "options": {
        "values": [
          "Blog",
          "News"
        ],
        "allow_create": true
      }
    }
  }
}
allow_emptyboolean#

⚠️ DEPRECATED: This key is deprecated. If you want to prevent empty values, we recommend setting _inputs.*.options.required to true instead.

This key toggles whether CloudCannon will accept empty values, and pre-select the first option if opened with an empty value.

Setting this key to true will allow CloudCannon to accept empty values.

Show examplesHide examples

In this example, CloudCannon will accept empty values for a Select Input.

Copied to clipboard
_inputs:
  category:
    type: select
    options:
      values:
        - Blog
        - News
        - Events
      allow_empty: true
{
  "_inputs": {
    "category": {
      "type": "select",
      "options": {
        "values": [
          "Blog",
          "News",
          "Events"
        ],
        "allow_empty": true
      }
    }
  }
}
empty_typestring#

This key defines how an 'empty' value will be saved. Does not apply to existing empty values.

Defaults to: null

Allowed values: null string

localestring#

This key defines the locale that CloudCannon uses to determine the number of words or graphemes in this Input, if you have max_words, min_words, max_graphemes, or min_graphemes configured.

max_graphemesnumber#

This key defines the maximum string length, in graphemes, 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.

max_graphemes_messagestring#

This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_graphemes.

max_lengthnumber#

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 examplesHide examples

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.

Copied to clipboard
_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
      }
    }
  }
}
max_length_messagestring#

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 examplesHide examples

In this example, we prompt our team to enter a valid number of characters using a custom message.

Copied to clipboard
_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."
      }
    }
  }
}
max_wordsnumber#

This key defines the maximum string length, in words, 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.

max_words_messagestring#

This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_words.

min_graphemesnumber#

This key defines the minimum string length, in graphemes, 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.

min_graphemes_messagestring#

This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_graphemes.

min_lengthnumber#

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 examplesHide examples

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.

Copied to clipboard
_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
      }
    }
  }
}
min_length_messagestring#

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 examplesHide examples

In this example, we prompt our team to enter a valid number of characters using a custom message.

Copied to clipboard
_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."
      }
    }
  }
}
min_wordsnumber#

This key defines the minimum string length, in words, 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.

min_words_messagestring#

This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_words.

patternstring#

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 examplesHide examples

In this example, we want our team to add an email address to the contact_email Input using the correct email format.

Copied to clipboard
_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 ___@___.__"
      }
    }
  }
}
pattern_flagsObject#

This key defines the flags (e.g. case-insensitive searching) for the regular expression set in options.pattern.

Show examplesHide examples

In this example, we have configured pattern flags for a text input to enable case-insensitive searching.

Copied to clipboard
_inputs:
  search_term:
    type: text
    options:
      pattern: ^[a-z]+$
      pattern_flags:
        ignore_case: true
{
  "_inputs": {
    "search_term": {
      "type": "text",
      "options": {
        "pattern": "^[a-z]+$",
        "pattern_flags": {
          "ignore_case": true
        }
      }
    }
  }
}
pattern_messagestring#

This key defines a custom error message that explains why a value has failed the validation criteria from options.pattern.

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 examplesHide examples

In this example, we prompt our team to use the correct email format in the contact_email Input using a pattern message.

Copied to clipboard
_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 ___@___.__"
      }
    }
  }
}
picker_previewObject#

This key defines the appearance of a Card when choosing an item to create. This uses preview as a base, and keys inside this object are overrides.

You can configure Card preview for Collections, Schemas, Object inputs, Array inputs, Select inputs, Structures, the Structure modal, Snippets, and the Snippet modal.

For more information about previews, please read our documentation on configuring card previews.

Show examplesHide examples

In this example, we have configured the appearance of Cards in inputs using the Structure staff when adding items.

Copied to clipboard
_structures:
  staff:
    values:
      - value:
          _type: Employee
          name: 
          job_description: 
          profile_picture: 
        picker_preview:
          text:
            - key: name
            - Employee
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: support_agent
      - value:
          _type: Manager
          name: 
          job_description: 
          profile_picture: 
          url: 
        picker_preview:
          text:
            - key: name
            - Manager
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: face
{
  "_structures": {
    "staff": {
      "values": [
        {
          "value": {
            "_type": "Employee",
            "name": null,
            "job_description": null,
            "profile_picture": null
          },
          "picker_preview": {
            "text": [
              {
                "key": "name"
              },
              "Employee"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "support_agent"
          }
        },
        {
          "value": {
            "_type": "Manager",
            "name": null,
            "job_description": null,
            "profile_picture": null,
            "url": null
          },
          "picker_preview": {
            "text": [
              {
                "key": "name"
              },
              "Manager"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "face"
          }
        }
      ]
    }
  }
}
picker_viewstring#

This key defines how CloudCannon should render selectable options in the dropdown of a Select Input.

Allowed values: card text gallery gallery-left

Show examplesHide examples

In this example, we have configured a Select Input to display options using the card view.

Copied to clipboard
_inputs:
  category:
    type: select
    options:
      values:
        - Blog
        - News
        - Events
      picker_view: card
{
  "_inputs": {
    "category": {
      "type": "select",
      "options": {
        "values": [
          "Blog",
          "News",
          "Events"
        ],
        "picker_view": "card"
      }
    }
  }
}
previewObject#

This key defines the appearance of a Card.

You can configure Card preview for Collections, Schemas, Object inputs, Array inputs, Select inputs, Structures, the Structure modal, Snippets, and the Snippet modal.

For more information about previews, please read our documentation on configuring card previews.

Show examplesHide examples

In this example, we have configured the appearance of file Cards in the Collection browser.

Copied to clipboard
collections_config:
  blog:
    preview:
      text:
        - key: title
      subtext:
        - key: author
      icon: edit_note
      icon_color:
        - key: color
        - '#ff0000'
      image:
        - key: image
      metadata:
        - template:
            - url
        - icon: event
          text:
            - template: Published on {date|date_long}
      gallery:
        - key: featured_image
{
  "collections_config": {
    "blog": {
      "preview": {
        "text": [
          {
            "key": "title"
          }
        ],
        "subtext": [
          {
            "key": "author"
          }
        ],
        "icon": "edit_note",
        "icon_color": [
          {
            "key": "color"
          },
          "#ff0000"
        ],
        "image": [
          {
            "key": "image"
          }
        ],
        "metadata": [
          {
            "template": [
              "url"
            ]
          },
          {
            "icon": "event",
            "text": [
              {
                "template": "Published on {date|date_long}"
              }
            ]
          }
        ],
        "gallery": [
          {
            "key": "featured_image"
          }
        ]
      }
    }
  }
}

In this example, we have configured the appearance of Cards in inputs using the Structure staff.

Copied to clipboard
_structures:
  staff:
    values:
      - value:
          _type: Employee
          name: 
          job_description: 
          profile_picture: 
        preview:
          text:
            - key: name
            - Employee
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: support_agent
      - value:
          _type: Manager
          name: 
          job_description: 
          profile_picture: 
          url: 
        preview:
          text:
            - key: name
            - Manager
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: face
{
  "_structures": {
    "staff": {
      "values": [
        {
          "value": {
            "_type": "Employee",
            "name": null,
            "job_description": null,
            "profile_picture": null
          },
          "preview": {
            "text": [
              {
                "key": "name"
              },
              "Employee"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "support_agent"
          }
        },
        {
          "value": {
            "_type": "Manager",
            "name": null,
            "job_description": null,
            "profile_picture": null,
            "url": null
          },
          "preview": {
            "text": [
              {
                "key": "name"
              },
              "Manager"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "face"
          }
        }
      ]
    }
  }
}
requiredboolean#

This key toggles whether CloudCannon requires this Input to have a value.

Setting this key to true 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.

Defaults to: false

Show examplesHide examples

In this example, we want to require our team to enter an author value for markup files with this Input.

Copied to clipboard
_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
      }
    }
  }
}
required_messagestring#

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 examplesHide examples

In this example, we prompt our team to use enter an Input value using a required message.

Copied to clipboard
_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."
      }
    }
  }
}
value_keystring#

This key defines the key used for mapping between saved values and objects in values.

This changes how the input saves selected values to match.

Defaults to checking for "id", "uuid", "path", "title", then "name".

Has no effect unless values is an array of objects, the key is used instead for objects, and the value itself is used for primitive types.

valuesDataset Reference Values|Text Array Values|Text Object Values|Object Array Values|Object Values#

This key defines the values available to choose from.

Optional, defaults to fetching values from the naming convention (e.g. colors or my_colors for data set colors).

Show examplesHide examples

In this example, we have configured a Select Input with custom values to choose from.

Copied to clipboard
_inputs:
  category:
    type: select
    options:
      values:
        - Blog
        - News
        - Events
{
  "_inputs": {
    "category": {
      "type": "select",
      "options": {
        "values": [
          "Blog",
          "News",
          "Events"
        ]
      }
    }
  }
}
viewstring#

This key defines how selected items are rendered.

Allowed values: card text gallery gallery-left

Examples:

In this example, we have configured Select Input options including values.

Copied to clipboard
_inputs:
  category:
    type: select
    options:
      values:
        - Blog
        - News
        - Events
{
  "_inputs": {
    "category": {
      "type": "select",
      "options": {
        "values": [
          "Blog",
          "News",
          "Events"
        ]
      }
    }
  }
}
Open in a new tab