Visually edit simple arrays

Some webpages, or webpage components, are constructed from arrays. An array is an ordered list of data, where data is grouped into array items. Each array item could contain one or several structured data keys.

Arrays can be simple, where each item has the same structure (e.g., a testimonial component), or more complex, where each item has a different structure (e.g., a page with various components). For simple arrays, you can use Array Editable Regions and Array Item Editable Regions to enable your team to visually edit arrays, including adding, deleting, and reordering items. We'll cover complex arrays in a later step of this guide.

Arrays with identical array items#

Array content is defined using structured data keys in the front matter of hybrid files (e.g., .mdx⁠) or in data files (e.g., .yml⁠) and referenced by templating in a layout file. Simple arrays have the same structured data keys for every array item.

Let's take a look at an example.

Our website has a "Testimonials" page, where we display testimonials from customers. The page content is stored in the front matter of a Markdown file and populates a layout file.

Here is our content file, testimonials.md, containing the testimonials array with structured data keys for image, image_alt, name, job_title, and quote in each array item.

---
layout: ../layouts/TestimonialsLayout.astro
testimonials:
  - image: ../../assets/placeholder-1.jpg
    image_alt: Profile photo of D. Gale
    name: D. Gale
    job_title: CEO at Yellow Brick Industries
    quote: >-
      "In pretium libero sed velit posuere sagittis."
  - image: ../../assets/placeholder-2.jpg
    image_alt: Profile photo of S. Crow
    name: S. Crow
    job_title: CBO at Yellow Brick Industries
    quote: >-
      "Mauris at augue quis orci egestas eu in nulla."
  - image: ../../assets/placeholder-3.jpg
    image_alt: Profile photo of T. Man
    name: T. Man
    job_title: CHO at Yellow Brick Industries
    quote: >-
      "Nunc ut sem vitae tortor volutpat varius."
  - image: ../../assets/placeholder-4.jpg
    image_alt: Profile photo of C. Lion
    name: C. Lion
    job_title: CCO at Yellow Brick Industries
    quote: >-
      "Aenean pharetra orci ac tincidunt lobortis."
---

Here is an excerpt from our layout file, TestimonialsLayout.astro. This section loops over all the items in the testimonials array, and populates the layout using the values.

---
const { testimonials } = Astro.props.frontmatter;
---

<ul>
  {
    testimonials.map((testimonial) => (
      <li>
        {testimonial.image && (
          <img
            src={testimonial.image}
            alt={testimonial.image_alt}
          /> 
        )}
        <h4>{testimonial.name}</h4> 
        <p>{testimonial.job_title}</p> 
        <p>{testimonial.quote}</p> 
      </li>
    ))
  }
</ul>

Together, these files output a webpage that looks like this:

To enable visual editing for this array, we can add Array and Array Item Editable Regions to our layout file. Array Editable Regions define the boundary of the array, and Array Item Editable Regions define each array item. Array and Array Item Editable Regions work together, so we must always have both.

The <ul> element wraps the array in our layout file, with its contents looping over every array item stored under the testimonials key. To define an Array Editable Region, let's add the data-editable and data-prop HTML attributes to the <ul> DOM element. The data-editable HTML attribute defines which type of Editable Region you want to use which, in this case, is array. Alternatively, we could choose to wrap the array templating in the equivalent web component <editable-array>, however that is not as convenient as adding attributes to existing elements. Our Array Editable Region also needs a data-prop to define where our array data is stored which, in this case, will be the testimonials front matter key.

The <li> element wraps each array item in our layout file, containing the HTML structure for each testimonial's content. To define an Array Item Editable Region, let's add the data-editable HTML attribute to the <li> DOM element. The value of data-editable HTML attribute should be array-item.

If we also want to visually edit the text and images inside each array item, we can define three Text Editable Regions for the name, job title, and quote, and an Image Editable Region for our image and alt text.

Here's what our layout file should look like:

---
const { testimonials } = Astro.props.frontmatter;
---

<ul data-editable="array" data-prop="testimonials"> 
  {
    testimonials.map((testimonial) => (
      <li data-editable="array-item">
        {testimonial.image && (
          <img
            data-editable="image"
            data-prop-src="image"
            data-prop-alt="image_alt"
            src={testimonial.image}
            alt={testimonial.image_alt}
          /> 
        )}
        <h4 data-editable="text" data-prop="name">{testimonial.name}</h4> 
        <p data-editable="text" data-prop="job_title">{testimonial.job_title}</p> 
        <p data-editable="text" data-prop="quote">{testimonial.quote}</p> 
      </li>
    ))
  }
</ul>

Once we save and rebuild our Site, CloudCannon will show a yellow Editable Regions box around each array item on the Testimonials page, and around each image and text field.

When you hover over an array item, CloudCannon will show a small toolbar in the top right of the array item, containing an edit icon and a drag handle icon. Clicking the edit icon will open a Data Panel containing your array item fields. Clicking the drag handle icon will open the Context Menu, with options to add, duplicate, move, and delete the array item, while clicking and holding the drag handle icon allows you to visually move an array item to any position in the array. For a vertical array, the move options are Move up and Move down, and for a horizontal array they are Move left and Move right.

When your team adds a new testimonial in the Visual Editor, CloudCannon copies the markup of an existing array item to display it. If your team deletes every testimonial, there is no array item left to copy, so adding a new one will show a red Error Card headed Failed to render array editable region. To avoid this, we can add a <template> element inside our Array Editable Region, containing the markup CloudCannon should use for every new array item.

Here's what our layout file looks like with a <template> element:

<ul data-editable="array" data-prop="testimonials">
  <template> 
    <li data-editable="array-item">
      <h4 data-editable="text" data-prop="name"></h4>
      <p data-editable="text" data-prop="job_title"></p>
      <p data-editable="text" data-prop="quote"></p>
    </li>
  </template>
  {
    testimonials.map((testimonial) => (
      <li data-editable="array-item">
        <h4 data-editable="text" data-prop="name">{testimonial.name}</h4>
        <p data-editable="text" data-prop="job_title">{testimonial.job_title}</p>
        <p data-editable="text" data-prop="quote">{testimonial.quote}</p>
      </li>
    ))
  }
</ul>

For more information about the options CloudCannon uses to render new array items, please read our documentation on configuring Array Editable Regions.

Common errors#

If you accidentally misconfigure your Editable Regions, CloudCannon will replace them in the Visual Editor with a red Error Card headed Failed to render array editable, Failed to render array editable region when it cannot render a new array item, or Failed to render array item for a misconfigured Array Item Editable Region, followed by a message describing the problem.

Here are a few common errors you might encounter with Array Editable Regions:

• You did not define the data-prop HTML attribute.
• The value at the data-prop path is not an array (e.g., it is a string, a number, or an object, or no value exists at that path).
• You have one or more orphaned Array Item Editable Regions whose nearest parent Editable Region is not an Array Editable Region.
• CloudCannon cannot render a new array item, because your array is empty and your Array Editable Region has no <template> element.

In the next step of this guide, we'll cover how to define Editable Regions for your components.