Select and Multiselect inputs

A Select or Multiselect input lets your team members select a value (or values) for data from a predefined list of options. Select inputs allow a single value, whereas Multiselect inputs allow multiple values.

There are four types of Select input:

• Select
• Multiselect
• Choice
• Multichoice

For each input, you can configure whether users can create their own values, if inputs can be empty, the appearance of input values, a list of options for data values, add ID keys to each value option, and how CloudCannon handles empty values. You can also use the general configuration options available for all inputs.

You must configure how the value options in your Select or Multiselect input are populated for this input to function. There are three ways to populate the list of options for a Select or Multiselect input:

• Fixed data sets
• Collection items
• Data files

Select#

The Select input provides an editing interface for data with multiple predefined options. Only one value is allowed at a time. In the Data Editor, predefined options appear in a dropdown menu.

This input has the same function as a Choice input but a different appearance.

You can configure a Select input using the type key with the value select. Define the type key under your input key name within _inputs. For more information, please read our documentation on configuring your inputs.

_inputs:
  blog_author:
    type: select

{
  "_inputs": {
    "blog_author": {
      "type": "select"
    }
  }
}

Once configured, the Select input will appear in the Data Editor or sidebar of the Visual or Content Editor when you add it to a data file or the front matter of a markup file.

---
blog_author: Author A
---

Content goes here.

Multiselect#

The Multiselect input provides an editing interface for data with multiple predefined options. Several values are allowed at a time. In the Data Editor, predefined options appear in a dropdown menu.

This input has the same function as a Multichoice input but a different appearance.

You can configure a Multiselect input using the type key with the value multiselect. Define the type key under your input key name within _inputs. For more information, please read our documentation on configuring your inputs.

_inputs:
  blog_tags:
    type: multiselect

{
  "_inputs": {
    "blog_tags": {
      "type": "multiselect"
    }
  }
}

Once configured, the Multiselect input will appear in the Data Editor or sidebar of the Visual or Content Editor when you add it to a data file or the front matter of a markup file.

---
blog_tags:
  - Opinion
  - Resource
---

Content goes here.

Choice#

The Choice input provides an editing interface for data with multiple predefined options. Only one value is allowed at a time. In the Data Editor, predefined options appear as buttons.

This input has the same function as a Select input but a different appearance.

You can configure a Choice input using the type key with the value choice. Define the type key under your input key name within _inputs. For more information, please read our documentation on configuring your inputs.

_inputs:
  priority:
    type: choice

{
  "_inputs": {
    "priority": {
      "type": "choice"
    }
  }
}

Once configured, the Choice input will appear in the Data Editor or sidebar of the Visual or Content Editor when you add it to a data file or the front matter of a markup file.

---
priority: high
---

Content goes here.

Multichoice#

The Multichoice input provides an editing interface for data with multiple predefined options. Several values are allowed at a time. In the Data Editor, predefined options appear as buttons.

This input has the same function as a Multiselect input but a different appearance.

You can configure a Multichoice input using the type key with the value multichoice. Define the type key under your input key name within _inputs. For more information, please read our documentation on configuring your inputs.

_inputs:
  theme_color:
    type: multichoice

{
  "_inputs": {
    "theme_color": {
      "type": "multichoice"
    }
  }
}

Once configured, the Multichoice input will appear in the Data Editor or sidebar of the Visual or Content Editor when you add it to a data file or the front matter of a markup file.

---
theme_color:
  - Blue
  - Green
---

Content goes here.

Populating the value options#

Without a list of options for the input value, Select and Multiselect inputs become misconfigured.

You can configure a fixed data set or reference a Collection or data file to populate the list of value options.

Fixed data sets#

A fixed data set is an array of predefined value options for your Select or Multiselect input. Fixed data sets are best suited to inputs with values that do not change often.

There are two ways to define a fixed data set: within the input configuration using the options.values key or anywhere in the configuration cascade using the _select_data key.

To define the fixed data set within your input configuration, add your array of value options within the values key in the input options.

_inputs:
  pets:
    type: multichoice
    options:
      values:
        - Dog
        - Cat
        - Rabbit

{
  "_inputs": {
    "pets": {
      "type": "multichoice",
      "options": {
        "values": [
          "Dog",
          "Cat",
          "Rabbit"
        ]
      }
    }
  }
}

To define your fixed data set elsewhere in the configuration cascade, create a nested key and array of value options within _select_data.

_select_data:
  animals:
    - Dog
    - Cat
    - Rabbit

{
  "_select_data": {
    "animals": [
      "Dog",
      "Cat",
      "Rabbit"
    ]
  }
}

Using the values key in the input options, you can reference a fixed data set defined elsewhere in the configuration cascade. Use the value _select_data.key_name, replacing key_name with the key name of your data set.

_inputs:
  pets:
    type: multichoice
    options:
      values: _select_data.animals

{
  "_inputs": {
    "pets": {
      "type": "multichoice",
      "options": {
        "values": "_select_data.animals"
      }
    }
  }
}

Collections#

A Collection is a single folder of files with a similar format. You can find your Collections in the Site Navigation sidebar. Using a Collection to populate your value options is useful when you want to reference pages or other content files created by team members (e.g., blogs, staff pages, or products).

You can reference a Collection for your Select or Multiselect input using the values key in the input options. Use the value collections.key_name, replacing key_name with the key name of your Collections.

_inputs:
  product_carousel:
    type: multiselect
    options:
      values: collections.products

{
  "_inputs": {
    "product_carousel": {
      "type": "multiselect",
      "options": {
        "values": "collections.products"
      }
    }
  }
}

Data files#

You can populate your input using a dedicated data file, which you can open and edit this file using the CloudCannon file browser. Using a data file to populate your value options is useful when you want your team members to be able to edit the available options.

Data files must contain arrays of strings or objects. The Select or Multiselect input will use the strings if the data file contains an array, and the key names if it contains objects.

- Blue
- Green
- Red

You can reference a data file for your Select or Multiselect input using the values key in the input options. Use the value data.key_name, replacing key_name with the key name of your data file.

_inputs:
  block_theme_color:
    type: select
    options:
      values: data.theme_colors

{
  "_inputs": {
    "block_theme_color": {
      "type": "select",
      "options": {
        "values": "data.theme_colors"
      }
    }
  }
}

Filters#

A filter allows you to limit the available values for a Select or Multiselect input to a subset of possible values. Filters are available for any string value of options.values including fixed data sets defined under _select_data, Collections, or data files.

Filters use structured data keys to determine the correct subset of values. Let's walk through a few examples.

In our first example, we want to create two inputs populated by different subsets of the same fixed data set. We have the following fixed data set containing important information for our Site:

_select_data:
  food:
    - name: apple
      color: red
    - name: banana
      color: yellow
    - name: pineapple
      color: yellow

{
  "_select_data": {
    "food": [
      {
        "name": "apple",
        "color": "red"
      },
      {
        "name": "banana",
        "color": "yellow"
      },
      {
        "name": "pineapple",
        "color": "yellow"
      }
    ]
  }
}

We want to configure:

1. A Multiselect input populated by all the entries in the food array and uses the name key in the input search bar to identify each entry.
2. A Choice input populated by a subset of the food array where the structured data key color has a value of yellow and uses the name key on the buttons to identify each entry.

We can configure the following filter on our input values:

_inputs:
  food:
    type: multiselect
    options:
      values: _select_data.food[*].name
  yellow_food:
    type: choice
    options:
      values: _select_data.food[?(@.color == 'yellow')].name

{
  "_inputs": {
    "food": {
      "type": "multiselect",
      "options": {
        "values": "_select_data.food[*].name"
      }
    },
    "yellow_food": {
      "type": "choice",
      "options": {
        "values": "_select_data.food[?(@.color == 'yellow')].name"
      }
    }
  }
}

In our second example, we want to create a Multiselect input populated with the files in our posts Collection as value options. More specifically, we only want files where the structured data key author has a value of Heather. We can configure the following filter on our input values:

_inputs:
  heathers_posts:
    type: multiselect
    label: Heather's Posts
    options:
      values: collections.posts[?(@.author == 'Heather')]

{
  "_inputs": {
    "heathers_posts": {
      "type": "multiselect",
      "label": "Heather's Posts",
      "options": {
        "values": "collections.posts[?(@.author == 'Heather')]"
      }
    }
  }
}

In our third example, we want to use data from a data file in multiple inputs. We have the following data file containing important information for our Site:

animals:
  - Cat
  - Dog
  - Bird
plants:
  - Tree
  - Vine
  - Shrub

We want to configure a Select input populated by the data in example_data_file.yml. More specifically, we only want values from the animals array within that data file. We can configure the following filter on our input values:

data_config:
  example_data:
    path: data/example_data_file.yml
_inputs:
  pets:
    type: select
    options:
      values: data.example_data.animals

{
  "data_config": {
    "example_data": {
      "path": "data/example_data_file.yml"
    }
  },
  "_inputs": {
    "pets": {
      "type": "select",
      "options": {
        "values": "data.example_data.animals"
      }
    }
  }
}

Options#

You can configure Select and Multiselect inputs using the options key under your input key, inside of _inputs.

_inputs:
  colors:
    type: multichoice
    options:
      allow_create: true
      allow_empty: true
      empty_type: string
      preview:
        text:
          - key: name
      values:
        - name: Pink
          hex: FFC0CB
        - name: Blue
          hex: 0000FF
        - name: Orange
          hex: FFA500
      value_key: hex

{
  "_inputs": {
    "colors": {
      "type": "multichoice",
      "options": {
        "allow_create": true,
        "allow_empty": true,
        "empty_type": "string",
        "preview": {
          "text": [
            {
              "key": "name"
            }
          ]
        },
        "values": [
          {
            "name": "Pink",
            "hex": "FFC0CB"
          },
          {
            "name": "Blue",
            "hex": "0000FF"
          },
          {
            "name": "Orange",
            "hex": "FFA500"
          }
        ],
        "value_key": "hex"
      }
    }
  }
}

Select and Multiselect inputs have the following options available:

preview:
  text:
    - key: title
    - key: name
  icon:
    - key: icon

_inputs:
  heathers_posts:
    type: multiselect
    label: Heather's Posts
    options:
      values: collections.posts[?(@.author == 'Heather')]

{
  "_inputs": {
    "heathers_posts": {
      "type": "multiselect",
      "label": "Heather's Posts",
      "options": {
        "values": "collections.posts[?(@.author == 'Heather')]"
      }
    }
  }
}

Unconfigured Select and Multiselect inputs#

In some cases, CloudCannon can still detect an Object input even if you have not configured it.

CloudCannon will interpret any key as a Select input if the key name ends in the singular form of a fixed data set you have defined under _select_data (e.g., author or blog_author for the fixed data set authors).

---
blog_author: Karen Key
---

Blog content goes here.

_select_data:
  authors:
    - Karen Key
    - Billy Mills
    - Holly James

{
  "_select_data": {
    "authors": [
      "Karen Key",
      "Billy Mills",
      "Holly James"
    ]
  }
}

This behavior is convenient if you have simple inputs or do not want to configure inputs.