Using Object Inputs to edit your data

Last modified: June 1st, 2023

Object inputs in your data show as a button in the data editor. This button opens a new editor to the side, showing the inputs inside that object. This continues as you click into nested Object inputs. Each object level has a back button to return to the parent scope.

Object inputs are a great way to group related data together, and hiding complicated or infrequently edited data.

Object#

Button input to open a new level in the editor scoped to the object value in your data.

Object inputs are shown for inputs configured with the type object, or for object input values.

Screenshot of unopened object input field

Here is how this Object input looks when opened:

Screenshot of active Object input field
Value convention
copied
inputs:
  title: Click on this region to edit its contents from the Sidebar.
  image: /images/hills.png
  date: 2021-08-12T18:30:00.000Z
  categories:
    - Documentation
    - CloudCannon
  url: /documentation/articles/using-objects-to-edit-your-data/
Value convention
copied
{
  "inputs": {
    "title": "Click on this region to edit its contents from the Sidebar.",
    "image": "/images/hills.png",
    "date": "2021-08-12T18:30:00.000Z",
    "categories": [
      "Documentation",
      "CloudCannon"
    ],
    "url": "/documentation/articles/using-objects-to-edit-your-data/"
  }
}
Value convention
copied
[inputs]
title = "Click on this region to edit its contents from the Sidebar."
image = "/images/hills.png"
date = 2021-08-12T18:30:00.000Z
categories = [ "Documentation", "CloudCannon" ]
url = "/documentation/articles/using-objects-to-edit-your-data/"
Input configuration
copied
seo:
  title: How to contact us
  description: These are all the ways to contact us
_inputs:
  seo:
    type: object
Input configuration
copied
{
  "seo": {
    "title": "How to contact us",
    "description": "These are all the ways to contact us"
  },
  "_inputs": {
    "seo": {
      "type": "object"
    }
  }
}
Input configuration
copied
[seo]
title = "How to contact us"
description = "These are all the ways to contact us"

[_inputs.seo]
type = "object"

Options#

Object inputs are configured with options inside an _inputs entry.

Input configuration
copied
seo:
  page_title: About
  description: All about us!
  social_image: /images/hills.png
_inputs:
  seo:
    type: object
    options:
      preview:
        text:
          - key: page_title
        subtext:
          - key: description
        image:
          - key: social_image
        icon: travel_explore
Input configuration
copied
{
  "seo": {
    "page_title": "About",
    "description": "All about us!",
    "social_image": "/images/hills.png"
  },
  "_inputs": {
    "seo": {
      "type": "object",
      "options": {
        "preview": {
          "text": [
            {
              "key": "page_title"
            }
          ],
          "subtext": [
            {
              "key": "description"
            }
          ],
          "image": [
            {
              "key": "social_image"
            }
          ],
          "icon": "travel_explore"
        }
      }
    }
  }
}
Input configuration
copied
[seo]
page_title = "About"
description = "All about us!"
social_image = "/images/hills.png"

[_inputs.seo]
type = "object"

[_inputs.seo.options.preview]
icon = "travel_explore"

  [[_inputs.seo.options.preview.text]]
  key = "page_title"

  [[_inputs.seo.options.preview.subtext]]
  key = "description"

  [[_inputs.seo.options.preview.image]]
  key = "social_image"

Object inputs have the following options available:

empty_type - String#

Set how an empty value will be saved. Does not apply to existing empty values. Can be one of the following:

  • object - an empty value for this input will be stored as {} (default).
  • null - an empty value for this input will be stored as a null value. This does not apply to TOML files.
structures - String or object#

Provides options for value of this object. When choosing an item, team members are prompted to choose from a number of values you have defined. Has no default.

If set as an object, the structures value is used directly.

if set as a string, the structures value is fetched from the configuration cascade. This allows you to define _structures elsewhere and reference it from here.

preview - Object#

The preview definition for changing the way data within an Object input is previewed before being expanded. The options available for Object inputs are:

  • text
  • subtext
  • icon
  • image

See the preview options documentation for detailed information on setting this option.

If the input has structures, the preview from the structure definition is used instead.

preview.icon - Array, string or boolean#

Controls the icon shown on the unopened input. Must match a Material Icon name. Defaults checking the icon key, then falls back to notes.

If set to false, no icon is displayed.

If image is set, it will cover icon when loaded successfully.

preview.image - Array, string or boolean#

Controls the image shown on the unopened input. Has no default, falls back to thumbnail_image, thumbnail_image_path, image, and image_path in that order.

If set to false, no image is displayed.

If no image is found, icon is displayed instead.

preview.text - Array, string or boolean#

Controls the main text shown on the unopened input. Has no default, falls back to the first value found (prioritizing text-based values).

If set to false, no text is displayed.

preview.subtext - Array, string or boolean#

Controls the supporting text shown on the unopened input. Has no default, falls back to listing the label of each input inside the object value.

If set to false, no text is displayed.

Subtext is hidden if text and subtext is the same. If there's no text, subtext is used instead.

Object inputs now support the new preview option. Read our migration guide if you are still using the old options: text_key, subtext_key, image_key and icon.

Related Articles

Related links

Open in a new tab