Repeat parts of a page

Some parts of a page are a list of the same thing: pictures in a gallery, testimonials, team members, the steps of a process. Write one entry's markup inside <sb-repeater>, and editors can add, remove and reorder the entries in edit mode. Each entry has its own copy of the slots inside it.

1. Wrap one entry

<div class="gallery">
    <sb-repeater key="gallery" count="3" max="24">
        <figure>
            <sb-image key="picture" src="/img/placeholder.jpg" alt="" />
            <figcaption><sb-text key="caption">A caption for the picture</sb-text></figcaption>
        </figure>
    </sb-repeater>
</div>
  • key names the repeater. It follows the slot key rules and must be unique on the page.
  • count is how many entries the page shows until an editor changes them. It defaults to 1.
  • max is the most entries an editor can add. Leave it out for no limit.

The markup inside is each entry's default, as with any slot. Partials work inside a repeater too.

How it renders

The <sb-repeater> tag is not rendered. Its content is repeated once per entry, directly inside the parent element, so the page's CSS applies to the entries as it would to hand-written ones. Selectors such as .gallery figure:nth-child(even) alternate the entries' look, and keep alternating as editors add entries.

How the content is stored

Each entry is numbered from 1, and the slots inside it are stored under the repeater's key and the entry's number: gallery.1.picture, gallery.1.caption, gallery.2.picture and so on. The number of entries is saved with the page, so it is drafted, published, previewed and rolled back with the rest of the page.

The numbers are positions. Removing entry 2 of 4 moves entries 3 and 4, with their content, to 2 and 3; moving an entry swaps the content of the two positions. The removed entry stays in the page's history.

Inside an <sb-scope>, the scope's key comes first: <sb-scope key="side"> around <sb-repeater key="notes"> stores side.notes.1.note. Every full key must still be at most 100 characters, entry number included.

How editors use it

In edit mode a dashed frame goes round the whole repeating section:

  • Add entry, on the frame's bottom edge, adds an entry at the end, showing the markup defaults, ready to edit. It is unavailable at max.
  • Each entry has a small bar of buttons just above its top-right corner. Up and Down move the entry.
  • Remove removes the entry, after asking. The last entry cannot be removed.

The page makes room for these buttons, so they never cover the entry or anything inside it, such as a shared fragment.

Each of these is saved as a draft straight away, together with any other unsaved changes on the page, and the page reloads to show the new order. Visitors see the change when the page is published.

Mistakes and how they show up

These are logged as slot errors, and shown on the page when SunBird:ShowSlotErrors is on (see Make a page editable):

  • a repeater without a key, or with an invalid key
  • two repeaters, or a repeater and a slot, with the same key on one page
  • a repeater inside another repeater: repeaters cannot be nested
  • a repeater in a layout or a section
  • count or max below 1, or count above max

With the setting off, a repeater used wrongly shows its markup once, as written.

If max is lowered in code below the number of entries an editor has saved, the page shows only the first max.

Edit this page