Editable Regions enable you to define exactly which data should be visually editable. When you update content in an Editable Region (or using the data panel or sidebar), CloudCannon will re-render that section of your webpage to keep the preview up to date. It doesn't matter where you store your data; Editable Regions work for values in HTML, structured data in front matter or data files, and Markup content.
Defining Editable Regions in your files is as simple as adding an HTML attribute to any DOM element (e.g., <p data-editable="text">) or inserting a web component in any file in your website that outputs to HTML (e.g., <editable-text>). You can make an entire Collection of content files visually editable in minutes.
Let's cover some of the basics of Editable Regions, including best practices for adding them to your files.
Types of Editable Regions#
There are six types of Editable Region, each of which can be defined by an HTML attribute or a web component.
- Source Editable Regions — Enable you to edit text values stored in HTML, with plain text or rich text formatting options.
- Text Editable Regions — Enable you to edit text values stored in structured data files, front matter, or Markup content, with plain text or rich text formatting options.
- Image Editable Regions — Enable you to edit image values stored in structured data files or front matter, including uploading images from your local storage, selecting existing images from your repository or DAM, and managing image details like title or alt text.
- Array and Array Item Editable Regions — Enable you to edit array values stored in structured data files or front matter, including adding, removing, and reordering array items. You can also nest Text, Image, Array, and Component Editable Regions inside array items to edit array content.
- Component Editable Regions — Enable you to edit registered Astro or React components. You can also nest Text, Image, Array, and Component Editable Regions inside your components to edit component content.
In this guide, we'll show you how to define each type of Editable Region using HTML attributes or web components. For a complete list of HTML attributes, please read our Editable Regions reference documentation.
Best practices for defining Editable Regions#
To avoid common pitfalls, here is a list of best practices for defining Editable Regions. If you have any questions, please don't hesitate to reach out to our friendly support team or start a conversation in the CloudCannon Community.
Don't change your data structure#
When adding Editable Regions to your website files, you don't need to change your file structure or data format. Editable Region HTML attributes should work seamlessly with your existing layouts and files, and web components should integrate into your files with minimal disruption.
Additionally, you can migrate to visual editing gradually by adding a few Editable Regions for key values, then adding more as needed.
Add Editable Regions to HTML and templating files#
Depending on your SSG, the format and extension of the files in your website may differ (e.g., Astro uses .astro files, Eleventy uses .liquid files). As long as they output to an HTML file after a Site build, you can add Editable Regions to any file that contains HTML content and templating.
Many websites also have a content Collection (e.g., a blog) where each file has front matter and content that populate templating fields in a layout file at build time. You can make the whole Collection visually editable by adding Editable Regions to the layout file, rather than the content files themselves.
Start from the root of your file#
A key part of defining Editable Regions is telling CloudCannon where your data is stored. CloudCannon calculates the path to your data properties relative to parent elements in your file.
To avoid misconfiguration issues where CloudCannon cannot find the data property you want to edit, it is best to start from the values closest to the root of the file (i.e., work from the parent elements to child elements) when you add Editable Regions to your files.
We recommend the following process:
- Choose a layout file you want to set up visual editing for.
- Add all the Editable Regions required for values in this file, excluding any values nested inside an array or component/partial/include.
- Add Editable Regions to parent elements that contain values you want to edit visually, such as arrays or components/partials/includes.
- Finally, open any files referenced by the first layout and continue adding Editable Regions as per steps 2 and 3 until you reach the end of your file cascade.
Adding Editable Regions to a nested component first, without adding the appropriate Editable Regions for parent elements, will result in an error.
In the next step of this guide, we'll cover how to define Editable Regions for text values stored in HTML, structured data, or Markdown.