Repeater
- Central CMS
- Central Forms
- Central Connect
Create a repeatable set of form fields that can be added and removed.
Basic usage
- Twig
- HTML
{{ form.create() }}
{{
form.repeater_start({
'label': 'The Pulsar team',
'empty': 'You have not added any team members',
'headings': [
{ name: 'text', label: 'Name' },
{ name: 'select2multi', label: 'Favourite food' }
],
'max-entries': 3,
'add-new-group-text': 'Add',
'add-another-group-text': 'Add another'
})
}}
{{
form.fieldset_start({
'legend': 'Team Member'
})
}}
{{
form.text({
'label': 'name',
'id': 'repeater-text',
'name': 'text'
})
}}
{{
form.select2({
'label': 'Favourite food',
'id': 'repeater-select2multi',
'name': 'select2multi',
'multiple': true,
'options': [
{ value: 'food_pizza', label: 'Pizza' },
{ value: 'food_gravy', label: 'Gravy' },
{ value: 'food_puds', label: 'Yorkshire Pudding' }
]
})
}}
{{
form.fieldset_end()
}}
{{ form.repeater_end() }}
{{ form.end() }}
<form method="POST" enctype="application/x-www-form-urlencoded" class="form">
<div
class="repeater"
data-repeater
data-repeater-add-new-group-text="Add"
data-repeater-add-another-group-text="Add another"
data-repeater-max-entries="3"
data-repeater-preview-colspan="3"
data-repeater-initial-state="[]"
>
<div class="repeater__saved-data u-display-none" data-repeater-saved-entries-root></div>
<div class="form__group">
<span class="control__label">The Pulsar team</span>
<div class="controls">
<table class="table table--full table--horizontal repeatable__table">
<caption class="hide">The Pulsar team</caption>
<thead class="repeater__preview-headings">
<tr>
<th data-repeater-for-name="text">Name</th>
<th data-repeater-for-name="select2multi">Favourite food</th>
<th rowspan="1" colspan="1" class="shrink-to-fit">Actions</th>
</tr>
</thead>
<tbody class="repeater__preview-data" data-repeater-preview-root>
<tr class="repeater__empty-placeholder" data-repeater-preview-placeholder>
<td colspan="2">You have not added any team members</td>
<td class="table__td--align-right table-row__actions"></td>
</tr>
</tbody>
<tfoot>
<tr class="repeater__group" data-repeater-new-group>
<td class="table__form" colspan="3">
<div data-repeater-new-group-controls>
<fieldset>
<legend class="legend">Team Member</legend>
<div class="form__group">
<label for="repeater-text" class="control__label">name</label>
<div class="controls">
<input id="repeater-text" name="text" type="text" class="form__control" />
</div>
</div>
<div class="form__group">
<label for="repeater-select2multi" class="control__label">Favourite food</label>
<div class="controls">
<select id="repeater-select2multi" name="select2multi" multiple data-label="Favourite food" class="form__control select js-select2">
<option value="food_pizza">Pizza</option>
<option value="food_gravy">Gravy</option>
<option value="food_puds">Yorkshire Pudding</option>
</select>
</div>
</div>
</fieldset>
</div>
<div class="form__actions repeater__group-actions">
<button data-repeater-save-group="true" type="button" class="btn btn--primary repeater__save-group">Save</button>
<button data-repeater-cancel-save="true" type="button" class="btn btn--naked repeater__cancel-group">Cancel</button>
</div>
</td>
</tr>
</tfoot>
</table>
<button data-repeater-add-group="true" type="button" class="btn repeater__add-group">Add</button>
</div>
</div>
</div>
</form>
Dependencies
You can configure this helper using the common helper options.
var RepeaterManagerComponent = require('/path/to/Repeater/RepeaterManagerComponent'),
repeaterComponentFactory = require('/path/to/Repeater/repeaterComponentFactory');
module.exports = {
RepeaterManagerComponent,
repeaterComponentFactory,
};
(function ($) {
pulsar.repeaterManager = new pulsar.RepeaterManagerComponent(
pulsar.pulsarForm,
pulsar.repeaterComponentFactory,
$html
);
$(function () {
pulsar.repeaterManager.init();
});
}(jQuery));
Options
Option | Type | Description |
---|---|---|
label | string | The repeater input label text |
empty | string | The empty placeholder text when no items have been added |
headings | Array | An array of heading config objects: { name: string, label: string } |
max-entries | int | Maximum (inclusive) number of entries that can be added |
add-new-group-text | string | The text content of the add new entry button |
add-another-group-text | string | The text content of the add another new entry button |
Headings
The main configuration item of note is the headings
property. It is here that we define which nested components are represented as a heading in the Repeater preview. If a nested component does not have an associated heading it will still function as desired, it’s input will be saved and submitted as part of the form request. This allows a user to choose 2-3 preview headings to summarise the contents of a Repeater whilst having as many fields as required.
Headings must be described as an array of objects in the following schema:
{
headings: [
{ name: string, label: string }
]
}
The name
property refers, and must match, the corresponding nested field. The label
property is the text content of the preview column heading.
Nested fields
Nested fields are the input components inside a Repeater. All Pulsar form components should be compatible with the Repeater at the time of publishing. Any additional form components should take into consideration their repeater integration. The Repeater will remove name
attributes from inputs in order to function, therefore any stateful components that depend on this attribute may need a integration service creating. See the js/Repeater/PseudoRadioInputService.js
as an example.