Annotations

Detailed reference on enabling highlights on HTML elements via annotations.

Inline editing is made possible by annotating HTML elements. This tells Netlify Create how to map content in the source to where it appears within the structure of the rendered page in the preview.

Here is usage information for the two data attributes used in inline editing:

Learn more about inline editing in the feature guide.

data-sb-object-id

Scopes all descendant elements within the context of the given ID value, so that any field path mentioned in HTML descendants are automatically attributed to the document with the specified ID.

Required

An object ID value must be present to enable inline editing. However, inline editing is not the only editing method available in Netlify Create.

And note that the object ID can also be specified directly in the field path.

Allowed Value

A string matching the value that uniquely identifies the document in the content source module.

Typically, the content source module will be in parity with the content source itself, using the its unique value as the document id. Exceptions to this are mentioned below.

Usage

  • 1
data-sb-object-id="object_id"
object_id
The value that uniquely identifies the document in the content source.

Example

It is conventional to attach a property similar to id to a document object being rendered in a page template or component. Basic examples are shown below.

  • 1
<div data-sb-object-id="1">...</div>

ID Exceptions

Most of the time, this value will be obvious. Content sources tend to make the uniquely-identifying value for a document easy to find.

With Git CMS, the ID value is the path to the source file, relative to the root of the project, and including the file extension.

data-sb-field-path

Provide a path (absolute or relative) from the root of the document, identifying the field to be editing in the content source, along with additional instruction on how to locate the content for that field in the DOM.

Usage and exceptions are noted below. See the inline editing feature guide for more specific examples.

Required
To be able to edit a field value inline, a field path must be provided.
Allowed Value

A string identifying the path (absolute or relative) from the root of the document, identifying the field to be editing in the content source, along with additional instruction on how to locate the content for that field in the DOM. See below for more information.

Usage

  • 1
data-sb-field-path="object_id:field_name#xpath_location"
object_id

(optional) The ID value for the document to which this field applies.

This and the trailing colon (:) are not required if the closest ancestor has specified data-sb-object-id for the same document.

field_name
Name of the field to be modified. See below for advanced behavior and patterns.
xpath_location
(optional) Additional instruction when the path name doesn't provide enough context. Some cases are presented below.

Example

It is conventional to attach a property similar to id to a document object being rendered in a page template or component. Basic examples are shown below.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
<!-- Using the full path -->
<h1 data-sb-field-path="1:title">...</h1>

<!-- With an ancestor specifying the proper document -->
<div data-sb-object-id="1">
  <h1 data-sb-field-path="title">...</h1>
</div>

<!-- With the xpath -->
<div data-sb-object-id="1">
  <img data-sb-field-path="image_url#@src" src="..." />
</div>

Advanced Field Path Patterns

There are a number of unique ways to use annotations. Here is a short list of common advanced patterns.

Find more detail and additional examples in the feature guide.

Nested Objects

Some content sources provide the ability to nest fields within other fields. This is a common case in Git CMS, where all fields for a document may live in the same document, rather than linking to document objects.

In this case, you can use dot notation to target the nested element.

  • 1
  • 2
  • 3
  • 4
<div data-sb-object-id="1">
  <!-- target: name field inside author object -->
  <span data-sb-field-path="author.name">...</span>
</div>

When a path begins with a dot, it will chain itself to the current path. This is the equivalent of the previous example.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
<div data-sb-object-id="1">
  <div data-sb-field-path="author">
    <!-- target: name field inside author object -->
    <span data-sb-field-path=".name">...</span>
  </div>
</div>

This also applies to lists, in which the index for the item in the list can be used.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
<div data-sb-object-id="1">
  <!-- target: author with index 0 -->
  <div data-sb-field-path="author.0">
    <span data-sb-field-path=".name">...</span>
  </div>
  <!-- target: author with index 1 -->
  <div data-sb-field-path="author.1">
    <span data-sb-field-path=".name">...</span>
  </div>
</div>

Changing Document Context

When a field comes from a document outside the current context, the scope can be refined with data-sb-object-id.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
<div data-sb-object-id="1">
  <!-- context: post_1 -->
  <h1 data-sb-field-path="title">Post Title</h1>
  <!-- context: author_1 -->
  <div data-sb-object-id="author_id">
    <span data-sb-field-path="name">Author Name</span>
  </div>
</div>

A full path that includes the ID will also work.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
<div data-sb-object-id="post_1">
  <!-- context: post_1 -->
  <h1 data-sb-field-path="title">Post Title</h1>
  <!-- context: author_1 -->
  <span data-sb-field-path="author_1:name">Author Name</span>
</div>

Unwrapped Children

When an element has multiple children with floating text, square brackets can target the appropriate text.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
<div data-sb-object-id="post_1">
  <!-- target: "Author Name" -->
  <span data-sb-field-path="author.name[1]">
    <span>By:</span>
    Author Name
    <span>On:</span>
    ...
  </span>
</div>