Repeater Element
Description
Repeaters allow you to configure a Content Type so that it can include another content type inside it. Content editors can then "Add another" to make for an intuitive editing experience.
This allows for the easy creation of content types that are made of repeated elements, such as:
- Carousels and sliders
- Accordions and tabbed content
- Card rows and feature blocks
- FAQs and more
How to Configure Repeater Elements
While creating or editing a content type (Assets > Content Types) you'll now have the ability to select a new element type called "Repeater".
When you select this element type, a new "Flyout screen" will be displayed automatically that allows you to choose which Content Type should be repeated.
You must choose:
- Which Content Type should be repeated
- Which Content Layout should be the "default" layout for output
- The minimum number of times this can be repeated
- The lowest value that can be selected is 0.
- A minimum of "0" makes the Repeater field "Not required"
- This number must be less than or equal to the "maximum" field
- The lowest value that can be selected is 0.
- The maximum number of times this can be repeated
- The lowest value that can be selected is 1.
- This number must be greater than or equal to the "minimum" field
- The largest allowed value is 100.
Be sure to click "Apply and Close" to save your settings. You can edit these settings in the future by clicking the "Repeater" link in the element listing table (Note: The default Content Type being repeated cannot be changed after a Repeater element is saved).
Now when Content editors add Content using this Content type they'll see the repeated content item inline and get the option to "Add another" (until the maximum is reached).
Important Considerations
- A Content Type can have several Repeater elements.
- When selecting the Content Type to be repeated:
- You cannot select any System Content Types
- You cannot select any Content Types with no content layouts
- You cannot select any Content Types that already have a Repeater element
- The Primary Group, Workflows, and Minimum user levels set on "Repeated Content Types" are ignored.
- Only the Primary Group, Workflow, and Minimum user level on the "Parent" Content type is respected.
- A "Repeated Content Type" cannot be deleted. The Repeater element must be removed first.
- Similarly, the Default content layout selected in a Repeater Content Configuration cannot be renamed or deleted.
Outputting Repeaters
You can output a Repeater element via T4 Tags or Handlebars Helpers.
T4 Tags
To output a Repeater element with a T4 tag you must set the output="repeater"
. For example:
<t4 type="content" name="Individual Slide" output="repeater" />This will output the repeater's default layout (set in the Repeater Element Config) for each repeated content item an editor has added.
You can choose to override this default layout and output a different content layout of the Repeated content item if you need to. To do this, set the layout="text/layout-name"
. For example:
<t4 type="content" name="Individual Slide" output="repeater" layout="text/slide"/>
This T4 tag can be created using the T4 Tag generator. The T4 tag generator will also provide you with a link to the Content Type if you need to make modifications.
Handlebars Helpers
To output a Repeater element with Handlebars you can use the standard publish Helper. For example:
This will output the repeater's default layout (set in the Repeater Element Config) for each repeated content item an editor has added.
You can choose to override this default layout and output a different content layout of the Repeated content item if you need to. To do this, use the repeater Helper and provide a layout like so:
Handlebars gives you even more control over the output of Repeaters content if you need it. The Repeaters Helper can be passed into an each Helper to give you total control over how a repeater is output. For example:
See the full Handlebars documentation to learn more.
Creating Content with a repeater element
The Content editing experience for using repeaters is intuitive.
When a new content item is created that contains a Repeater element the user will see the Repeated content types inline. If the Repeater is configured with a "minimum repeats" greater than zero, then the content will already include some repeated items and the user can start filling out the fields.
The user has the ability to "Add another" and they can remove and reorder repeated items as needed. The user can collapse the repeated items into an accordion if they don't need to see all elements.
Removing a repeated item
To remove a repeated content item (AKA Repeater instance) a user can click the "Remove" button.
Once an item is removed it can be retrieved by rolling back the history of the content item to a previous version.
Reordering a repeated item
There are several ways to reorder repeater items as we wanted to support lots of different users and use cases.
- Editors can drag and drop repeater instances to reorder them
- Editors can click the "reorder" button and then use the arrows to move up or down
- Editors can click the "reorder" button and then type in the position they want this repeated item to be moved to
The order is consistent on each edit. There is currently no way to allow a "random" order at edit time.
Converting Existing Content to Repeaters
Admins have the ability to move existing content into a Repeater.
To do this they should:
- Create a new Content Type that uses a Repeater element
- Configure it to repeat an existing content type
- Add this new Content Type to a section
- Click "Add existing content"
- Select existing content from the site structure
The content will be moved from its current section into the repeater. This action cannot be undone.
Note: You cannot add mirrored content to a repeater. Unmirror it first before adding.
Repeaters and Multiple Languages
Repeaters supports multiple languages.
When you add repeater instances in one languages they will be automatically available for translation in other languages immediately.
It's important to note that Repeaters will expect the number of repeated items to be the same in all languages.
The order of repeated content items is independent across languages, so reordering items in one language will not reorder them in another.
Known Limitations
We'd love to hear what's important to you with this feature so we can add improvements in future releases. The following are known limitations with Repeaters.
- Repeaters cannot be "nested". You cannot repeat a content Type that itself has a Repeater element.
- Repeaters cannot be used with System Content Types (Such as Media, Section Meta Data, Extended User, Access Control etc)
- Repeaters can be used in Direct Edit, but inline Direct Edit will come in a future release.
- It is not possible to set Review Dates, Expiry Dates, or Publish Dates on repeated content items (Only on the parent content)
- It is not possible to use a content link to link to a repeated content item (Only the parent content item)