These inputs are for values from a fixed or dynamic set of options. Useful for linking across pages, collections and data sets.
Single value select input for values from a set of options.
Select inputs are shown for inputs configured with the type select
, or for input keys matching or ending with the singular form of a data set key (e.g. color
or my_color
for data set colors
).
color: Red
ssg: jekyll
_select_data:
colors:
- Red
- Blue
ssgs:
jekyll: Jekyll
hugo: Hugo
11ty: Eleventy
spare_part: Bolt
_inputs:
spare_part:
type: select
options:
values:
- Bolt
- Nut
- Gear
color = "Red"
ssg = "jekyll"
[_select_data]
colors = ["Red", "Blue"]
[_select_data.ssgs]
jekyll = "Jekyll"
hugo = "Hugo"
11ty = "Eleventy"
spare_part = "Bolt"
[_inputs.spare_part]
type = "select"
[_inputs.spare_part.options]
values = ["Bolt", "Nut", "Gear"]
{
"color": "Red",
"ssg": "jekyll",
"_select_data": {
"colors": ["Red", "Blue"],
"ssgs": {
"jekyll": "Jekyll",
"hugo": "Hugo",
"11ty": "Eleventy"
}
}
}
{
"spare_part": "Bolt",
"_inputs": {
"spare_part": {
"type": "select",
"options": {
"values": ["Bolt", "Nut", "Gear"]
}
}
}
}
Multiple value select input for values from a set of options.
Multiselect inputs are shown for inputs configured with the type multiselect
, or for input keys matching or ending with a data set key (e.g. colors
or my_colors
for data set colors
).
colors:
- Red
ssgs:
- hugo
- 11ty
_select_data:
colors:
- Red
- Blue
ssgs:
jekyll: Jekyll
hugo: Hugo
11ty: Eleventy
spare_parts:
- Bolt
_inputs:
spare_part:
type: multiselect
options:
values:
- Bolt
- Nut
- Gear
colors = ["Red"]
ssgs = ["hugo", "11ty"]
[_select_data]
colors = ["Red", "Blue"]
[_select_data.ssgs]
jekyll = "Jekyll"
hugo = "Hugo"
11ty = "Eleventy"
spare_parts = ["Bolt"]
[_inputs.spare_parts]
type = "multiselect"
[_inputs.spare_parts.options]
values = ["Bolt", "Nut", "Gear"]
{
"colors": ["Red"],
"ssgs": ["hugo", "11ty"],
"_select_data": {
"colors": ["Red", "Blue"],
"ssgs": {
"jekyll": "Jekyll",
"hugo": "Hugo",
"11ty": "Eleventy"
}
}
}
{
"spare_parts": ["Bolt"],
"_inputs": {
"spare_parts": {
"type": "multiselect",
"options": {
"values": ["Bolt", "Nut", "Gear"]
}
}
}
}
Select and Multiselect input options are configured with options
inside an _inputs
entry.
items:
- P1
_inputs:
items:
type: multiselect
options:
values: _select_data.inventory
value_key: key
text_key: display_name
_select_data:
inventory:
- key: P1
display_name: Potion
kind: consumable
items = ["P1"]
[_inputs.items]
type = "multiselect"
[_inputs.items.options]
values = "_select_data.inventory"
value_key = "key"
text_key = "display_name"
[[_select_data.inventory]]
key = "P1"
display_name = "Potion"
kind = "consumable"
{
"items": ["P1"],
"_inputs": {
"items": {
"type": "multiselect",
"options": {
"values": "_select_data.inventory",
"value_key": "key",
"text_key": "display_name"
}
},
"_select_data": {
"inventory": [
{
"key": "P1",
"display_name": "Potion",
"kind": "consumable"
}
]
}
}
}
Select and Multiselect inputs have the following options available:
values
- Array, object or string
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
).
If set as an object or an array, the values are used directly.
If set as a string, the values are fetched from the referenced data set.
value_key
- String or array of strings
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 ['id', 'uuid', 'path', 'title', '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.
If set as an array, keys are tried in order, until a non-empty value is found. If no keys are set for a value available, the value available is not included.
If set as a string, this key is used directly. Values available are excluded if they don’t have a value for this key.
text_key
- String
Controls what key within an object value is used for the display text in the selected values and values available. Defaults to title
, then name
. Has no effect unless the available or selected value is an object. If the value is a primitive type, it is used directly.
allow_create
- Boolean
Allows new text values to be created at edit time. Defaults to false
. Has no effect on select inputs.
allow_empty
- Boolean
Provides an empty option alongside the options provided by values
. Defaults to true
. Has no effect on multiselect inputs.
Sites created before 25 November 2021 have a different default for saving collection items in order to keep existing sites working. Create a new site, or get in touch with support if you wish to update this for your site.
There are currently three sources for populating the options for a select or multiselect input:
You can populate the available options for a select or multiselect with a naming convention or set it explicitly with the input configuration options.values
.
spare_part: Bolt
_inputs:
spare_part:
type: select
options:
values:
- Bolt
- Nut
- Gear
spare_part = "Bolt"
[_inputs.spare_part]
type = "select"
[_inputs.spare_part.options]
values = ["Bolt", "Nut", "Gear"]
{
"spare_part": "Bolt",
"_inputs": {
"spare_part": {
"type": "select",
"options": {
"values": ["Bolt", "Nut", "Gear"]
}
}
}
}
In addition to having options.values
contain values directly as seen above, you can refer to one of the three available sources. Here’s how you can refer to a collection called bits_and_pieces
:
spare_part: Bolt
_inputs:
spare_part:
type: select
options:
values: collections.bits_and_pieces
spare_part = "Bolt"
[_inputs.spare_part]
type = "select"
[_inputs.spare_part.options]
values = "collections.bits_and_pieces"
{
"spare_part": "Bolt",
"_inputs": {
"spare_part": {
"type": "select",
"options": {
"values": "collections.bits_and_pieces"
}
}
}
}
You can refer to fixed data sets and data files in a similar way by changing the prefix. For example: data.inventory
and _select_data.spare_parts
.
Fixed data sets are defined in _select_data
from the configuration cascade. Best suited when providing options that do not change as content is added or removed.
Collection items are files from your defined collections. Best suited when you need to select from pages or other content files created by team members.
By default, when you save a value populated from a collection, CloudCannon saves the path without the extension inside the collection folder (e.g. choosing /staff_members/jane.md
in a staff_member
input saves the value jane
). You can use this value to map to the linked collection item in your templates.
Data files are similar to collections, usually a reserved collection for your SSG. Best suited when you need the available options editable by team members.
Processed data file sets must be arrays of strings, or objects. The value saved is either the string for arrays, or the key for objects.
By default, CloudCannon does not read data files during your build. To use this option source, instruct CloudCannon to read it by defining your data.