Changing how cards preview your data

CloudCannon uses configurable cards to represent your data in different places across the app, including:

1. Snippets
   • Hugo Shortcodes
   • Eleventy Shortcodes
2. Snippet Picker
3. Structures inside Array inputs
4. Structure Picker
5. Select-style inputs
6. Object inputs
7. Non-structure items inside Array inputs
8. Collection file lists

These cards are configurable using the preview key.

How to configure card previews#

The preview configuration has a number of different keys which correspond to different parts of the card display. Below is a diagram of how different keys are displayed on the cards:

Preview reference

metadata reference

Metadata is a great way to show related data in the card.

gallery reference

The gallery will render an icon if it is defined, an image over the icon once loaded and if neither exist the text will be displayed.

How cascading options work#

Most of the keys within preview are the same type of structure, which we call cascading options. This is either an Array or a single value of the following types:

• A String of the exact value (e.g "My Item")
• A reference to a key within the connected item (e.g key: title in YAML or { "key": "title" } in JSON)

# String option
preview_option: Fallback String

# or, Array cascading option
preview_option:
- key: some_key
- key: object.subkey
- Fallback String

When using an Array each item is read in order. If no content is found, the next item in the array is used. If no content is valid, the corresponding preview option will be hidden.

Below is an example of some data representing a Figure that needs previewed:

_type: figure
image_path: /image.png
alt_text: An image

When displaying this Figure we want to:

1. Always display the image icon (A String example)
2. In the text, display the image_path key falling back to the String ‘Image missing’ (An Array example)
3. In the subtext, display the alt_text key falling back to the String ‘No alternative text’ (Another Array example)

Writing this as a set of preview options will look like this:

preview:
  icon: image
  text:
    - key: image_path
    - Image missing
  subtext:
    - key: alt_text
    - No alternative text

Picker specific options#

There are two states where cards can be displayed:

1. A card connected to an existing item with it’s own data (e.g an instance of a snippet or structure on a page)
2. A card used in a “picker” where the type of item needs to be selected (e.g. adding a snippet or structure)

When a card is used in a “picker”, it is useful to override the options from the preview config. For this we use the picker_preview config which merges on top of the preview options. The options within picker_preview are the same as the options in preview.

For the same figure example we used above we want to:

1. Show the String ‘Figure’ for the text
2. Disable the subtext to prevent showing the String ‘No alternative text’

figure:
  picker_preview:
    text: Figure # Used in a picker
    subtext: false # Disables the subtext in the picker
  preview: # Used in each figure item
    icon: image
    text:
      - key: image_path
      - Image missing
    subtext:
      - key: alt_text
      - No alternative text