Repeating Fields
A Repeating Fields attribute allows you to create a set of fields that can be repeated when editing a page or app item.
This lets you set up a group of fields and then the page editor can add as many sets of the fields as they want.
Some example uses of this attribute could be:
- Add an image slider. Each set of fields could be the image and image title.
- Add staff profiles to a page. Each set of fields could the the name, title, picture and biography for each staff member.
- Testimonials
- Office locations
There are a lot of uses for this attribute beyond those mentioned above.
Creating the Repeating Fields Attribute
Depending on where you are in BranchCMS you would click on the "Add a new Field" or "Add a New Attribute" button to create a new Repeating Fields attribute. Once you pick "Repeating Fields" as the Attribute Type then you can give it a name.
Near the bottom of the form you will see a section titled "Repeating Fields Configuration".
At minimum you will probably want to fill out the "Repeating Fields item name" field to give a descriptive name to what each set of fields in the Repeating Fields attribute represents.
You can also do the following configuration:
- Turn off the ability to sort items
- Turn off the ability to delete items
- Set a minimum number of items
- Set a maximum number of items
If a minimum number of items is set and if there aren't that many items when editing a page then extra sets of empty fields will be displayed to meet the minimum.
If a maximum number of items is set then you won't be able to add more than the maximum number. The "Add Another" link, Copy controls and Insert Before/Insert After links will be hidden. If the page was previously set up with more items before the maximum limit was set then those items will still show when editing the page and you won't be able to add new items. A message will show that the maximum number of items has been exceeded.
When displaying a page that uses Repeating Fields and a maximum number of items is set then only the maximum number of items will be available to the layouts/templates. If somehow there are more items then the maximum then the excess items will not be included in the array of data for the Repeating Fields set.
A few example use cases where you may want to change these configurations include:
- Your design only allows for a certain number of items on a page so you want to ensure that no more than the maximum are created.
- Your design calls for 3 boxes on a page. You can turn off deleting and then set a minimum and maximum of 3 items. This allows you the benefits of only having to create one set of fields for the Repeating Fields set and you can still sort the items.
Adding Fields to the 'Repeating Fields' Attribute
The first step is to create the Repeating Field attribute. After you do that add another attribute/field. You will see a field called "Parent Attribute". Choose the Repeating Field attribute that you just created.
You can add as many child attributes to the Repeating Fields attribute as you want. As you add them you can set the display order of the fields.
You can add any type of attribute to a Repeating Field attribute. You can even have nested Repeating Field attributes.
Accessing the Fields in Layouts or Templates
The value for this field would be an array where each item in the array contains the values for each set of fields. Typically you would use loops to access each set of values.
For an example say that you have a Repeating Field called "Slides". It has a Layout Key called "slides". There are two fields assigned to the "Slides" attribute called "Image" and "Title". The "Image" field has a Layout Key called "image" and the "Title" field has a Layout Key called "title".
Below is a basic example of how you would use these fields in your layout.
{loop items="#slides" value="slide"}
{** Build out each individual slide **}
<div class="slideshow-slide">
{#slide.image}
<p>{#slide.title}</p>
</div>
{/loop}
View the documentation on loops for more information.
User Interface Actions
There are a number of useful things that you can do when you're editing a page with a Repeating Field attribute.
- Add new items
- Expand or collapse all items
- Expand or collapse individual items
- Drag items to reorder
- Move items up or down one place
- Delete items
- Undo deleting items
- Insert a new item before or after a specific item
- Move an item to the first or last place
- Expand and collapse child Repeating Field sets.
Most of these actions are done using one of the controls in the Repeating Fields item toolbar.
Add a New Item
To add another Repeating Fields item simply click the "Add Another" link after the last item. If the Repeating Field is configured to have a name for the item then that text will show after "Add Another".
Expanding and Collapsing All Items
To collapse all items click the "Collapse all" link above all of the Repeating Field items.
To expand all items click the "Expand all" link above all of the Repeating Field items.
Expand or Collapse Individual Items
You can expand or collapse an individual item by simply double clicking on the toolbar.
You could also click the Collapse control 
to collapse an individual item.
Once collapsed you can click the Expand control 
to expand the individual item.
Drag Items to Reorder
There are two ways to drag an item to reorder it. You can click the Drag control 
and while holding down your mouse move the item up or down. Or, you can simply click anywhere in the toolbar to drag the item.
Move Items Up or Down One Place
Instead of dragging an item up or down you can use the Move Up control 
or the Move Down control 
to move an item up or down one place.
Delete Items
To delete an item you click the Delete control 
.
There isn't a prompt to confirm that you want to delete because there is the ability to easily undo a deletion.
Note that items are not actually deleted from the page until the page is saved.
Undo Deleting Items
After you delete an item you can easily undo the delete by clicking the "Undo Delete" link that shows in place of the deleted item.
More Options
The More Options control 
provides a few additional features that you can use to manage items. Clicking it will show the following menu:
Clicking "Move to first" will move the item to the first position.
Clicking "Move to last" will move the item to the last position.
Clicking "Insert before" will let you add a new item immediately before that item.
Clicking "Insert after" will let you add a new item immediately after that item.
If one of the items in the Repeating Fields set is another Repeating Fields set then a few additional options will show to manage the nested Repeating Fields set.
Clicking "Collapse children" will collapse all of the child Repeating Fields sets.
Clicking "Expand children" will expand all of the child Repeating Fields sets.