CloudCannon uses configurable cards to represent your data in different places across the app, including:
- Snippets
- Snippet Picker
- Structures inside Array inputs
- Structure Picker
- Select-style inputs
- Object inputs
- Non-structure items inside Array inputs
- Collection file lists
These cards are configurable using the preview
key.
Select-style inputs, Object inputs and Structure and non-structure inputs inside Array inputs support a subset of these options. The specifics are documented on each page.
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
The highest level of text shown in the preview.
The second highest level of text which is displayed over at most two lines.
Adds an icon from Google’s Material Icons beside the text and subtext on the card. Must match Material Icon name.
Defines an image to display beside the text and subtext on the card. Once the image loads it will cover the icon.
A list of items that can contain an image, icon and text. Great for related data. See metadata reference below.
Defines large image/icon preview for the card. See gallery metadata below.
metadata reference
Metadata is a great way to show related data in the card.
The text to be displayed on the metadata item.
Defines an icon from Google’s Material Icons beside the text on the metadata. Must match Material Icon name.
Defines an image path to load over the icon.
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.
Defines text to display in the centre of the gallery area if there is no icon or image.
Defines an icon from Google’s Material Icons to display in the centre of the gallery area. match Material Icon name.
Defines an image to display in the gallery area. Covers text and icon once the image is loaded.
Sets how image is displayed in the gallery. Must be cover
(default) or contain
.
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:
- Always display the
image
icon (A String example) - In the text, display the
image_path
key falling back to the String ‘Image missing’ (An Array example) - 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:
- A card connected to an existing item with it’s own data (e.g an instance of a snippet or structure on a page)
- 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:
- Show the String ‘Figure’ for the
text
- 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