What are Visual Data Bindings?

Visual Data Bindings tell CloudCannon which element on your page corresponds to which piece of data. You add an HTML attribute naming the data, and that element becomes editable in the Visual Editor.

In the Visual Editor, CloudCannon positions a clickable overlay absolutely over each bound element. Clicking the overlay reveals controls for editing, reordering, and removing the value behind it, and clicking off the overlay clears the selection.

Which controls appear depends on the binding:

• Edit — the default control for a bound value.
• Details — replaces Edit when you are viewing a file you cannot edit.
• Add — replaces Edit when the binding ends in the [+] suffix. A binding with that suffix shows no control at all when you cannot edit the file.

A binding that targets an array item gets these controls alongside Edit:

• Move Up, Move Down, Move Left, Move Right — CloudCannon shows the pair matching how the items are laid out on the page. Move Up and Move Left are unavailable on the first item, and Move Down and Move Right are unavailable on the last.
• Remove — removes the item. Clicking it reveals a second Remove button, and the removal only happens when you click that one. Remove is unavailable on the only item in an array.

Selecting an array item also reveals an add control above and below it. Clicking either one opens a Context Menu with two options:

• Add new — adds an empty item in that position.
• Duplicate — copies the item you clicked from into that position.

A bound element can contain other bound elements. A child binding only becomes clickable once you select its parent, which keeps the page from filling with overlapping overlays. Items in the same array are an exception: selecting one array item leaves its siblings clickable, so you can move along a list without reselecting the parent each time.

Add a data binding#

Add the data-cms-bind attribute to any element, with a value naming the data you want to edit. Start from the root of your data and name each step toward the value, separating objects and properties with a dot. Denote an array item with a zero-based index in square brackets.

• #title targets the title of the current page.
• #seo.title targets the title inside the seo object.
• #people[0] targets the first item in an array named people.
• #people[0].title targets the title of the first item in that array.

The leading # is optional for a binding that targets a single value. CloudCannon strips it, so title and #title resolve to the same value.

Keep the # on array items. CloudCannon finds an item's siblings by matching the #-prefixed attribute, so an item bound without it behaves as though it has no siblings: Move Down and Move Right stay unavailable, and Remove is unavailable on the first item.

<h1 data-cms-bind="#title">Edit the title</h1>

Append to an array

A binding ending in [+] renders a single Add button instead of Edit. Clicking it appends a new item to the end of that array, without opening the Context Menu.

<button data-cms-bind="#people[+]">Add a person</button>

Control overlay stacking#

Binding overlays can cover navigation elements and other high-stacking parts of your page. CloudCannon positions them from a base z-index of 9000, placing selection states and controls in the few levels above it.

Set the --editor-panel-zindex CSS variable to move that base. If your navigation sits at a z-index of 100, a base of 90 puts the overlays behind it.

:root {
  --editor-panel-zindex: 90;
}