Repeater

Create a repeatable set of form fields that can be added and removed.

The Pulsar team

The Pulsar team

Name	Favourite food	Actions
You have not added any team members
Team Member name Favourite food PizzaGravyYorkshire Pudding

Basic usage

Twig

{{ 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() }}

HTML

<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.