Repeatable Groups of Inputs

Creating a repeatable group of form inputs

Like anything else in a Form Reform form, a repeatable group of inputs is created by adding a Repeatable Group block to a page.

If you would prefer to try an example first, have a play with Example - Repeatable Groups, then come back here to read about the details.

Repeatable groups work by identifying a region of the page as a repeatable group and adding a Repeatable Group block to that region. Behind the scenes, the repeatable group is a DOM element containing the form blocks to be repeated. From a Concrete CMS point of view, this could be a container, layout, stack or any other grouping of input blocks.

To create a repeatable group, start by adding a container, layout or stack to the page and within that add Form Reform blocks for each form input in the repeatable group of inputs. Then add a Repeatable Group block to that container, layout or stack. 

In edit mode the repeatable group will now be marked with a dashed lime green outline. Check this outline contains all the form inputs that you require to be repeatable and the Repeatable Group block's toolbar. If it does not, you may need to adjust the way the Repeatable Group block selects the container, layout or stack you are using for the group.

When you save and publish the page, visitors can now add a repetition of the group of form controls by clicking the Add button in the Repeatable Group toolbar. Groups added can also be deleted and optionally sorted.

Key points

  • Every Repeatable Group must have a unique name. That name is used to identify inputs in the group and for subsequent saving and handling the group.
  • Most form input blocks including Snapshot Upload and Webcam blocks can be used in a Repeatable Group. Some blocks are necessarily unique and cannot be repeated in a group, such as a the Submit block, Message Display block, Captcha and CCM Token blocks. For details, check the list of Form Reform blocks. Form Reform will alert you to any blocks that are incompatible with Repeatable Groups.
  • Repeatable Groups cannot be nested. You can't have repeatable groups within repeatable groups.
  • You can add other kinds of block such as content blocks to Repeatable Groups. Some JavaScript dependent blocks may behave in unexpected ways depending on how they are coded.
  • The Behaviour setting for blocks in a repeatable group should match the Behaviour of the Repeatable Group block.
  • Repeatable Groups can be used in single step forms, in each step of a multi-step form, in ajax forms, in multi-step ajax forms and in tabbed forms.
  • Limits for minimum and maximum repetitions can be configured for each group.
  • You can have as many different repeatable groups as you like.

Handling a repeatable group of form inputs

Saving form data

If all you need to do is save the items in a group with the form submission, then you don't need any special processing. The Save to Default, Save to Session and Save to Cookie handlers simply serialize the data in the group with the rest of the form data and save it as they would any other data.

Processing form data

If you need to apply other processing to repeatable groups in the form handler pipeline, inputs in a repeatable group are identified in {{place_holders}} by indexing with a dot notation. For example, instead of {{form:input_name}} you can identify the first two repetitions of the group containing input_name using

{{form:group_name.0.input_name}}

{{form:group_name.1.input_name}}

That is fine if you have a fixed and required number of repetitions of a group, but it begs the question, how can you handle inputs when a group could have a variable number of repetitions?

One approach would be to build logic using Condition If / Condition Else If / Condition Else / Condition End handlers. If that is your preference, then go for it. However, there is a better way. For handling repeatable groups, we have a dedicated pair of handlers for looping over each iteration of a repeated group using Iterate Repeatable Group /  Iterate Repeatable Group End. If you are familiar with code, think of these as the form handling equivalent of a foreach loop.

Iterating through a Repeatable Group

In the Iterate Repeatable Group handler you specify the name of the input group to be iterated. All subsequent form handlers up to the Iterate Repeatable Group End handler will then be repeated for each repetition of the group. Rather than needing to specify the index of the repetition with {{form:group_name.0.input_name}} as described above, a new placeholder category group_item can be used to refer to the grouped inputs in the current repetition.

{{group_item:input_name}}

As with other categories, repeatable group_items also provide the more generic placeholders

{{group_item:all}}

{{group_item:all_formatted}}

Within each iteration you can build whatever handling you like. Build messages, send emails, save data just for that iteration, build conditional processing using complete sets of conditional handlers, create complex validation. Whatever you like.

If your handlers need to be aware of where you are in an iteration, the group category provides metadata about the iteration process.

{{group:name}} - provides the name of the group

{{group:index}} - provides the current index within the group (0...N-1)

{{group:index}} - provides the current iteration within the group (1...N)

{{group:size}} - provides the total size of the group (N)

For example, to add a simple item X of N note to a message, "Item {{group:index}} of {{group:size}".

Key points

  • Iteration of repeatable groups cannot be nested. Form Reform does not prevent you from constructing such a pipeline, but don't expect it to behave!
  • You can have iteration within a condition, or conditions within an iteration, but you cannot overlap conditions and iterations. Form Reform does not prevent you from constructing such a pipeline, but don't expect it to behave!
  • The Import Quarantine Files handler imports all files in quarantine, not just quarantined files for an iteration. Hence Import Quarantine Files should be before or after iterating through a group and not repeated within each iteration.
  • On Success / On Error handlers can jump out of iterating through a group.

Example

To learn more, don't forget we have an example to play with Example - Repeatable Groups.

Testing and debugging repeatable groups

The Options tab of the Submit block dialogue provides debugging and logging options.

See Problem Solving for more about repeatable groups and for details of logging and debug levels.

Additional Pages

Reform the way you add new input controls

If you need a specialized template or a custom input element, you can design new templates  or new block types for form elements as you would any block type.

Blocks are easy for third party addition or extension. Block templates and are the first thing any Concrete CMS developer learns to code. They are one of the easiest things to code. The underlying mechanisms are well established and reliable.

Reform what you can do with form data

Form handlers are built about the same extensible plugin system as many of my other addons (Universal Content Puller, Omni Gallery, Extreme Clean ...).

The whole system is aimed at easy extension within Form Reform, by third party addons, by agencies and by site building developers.

Handlers can be easily added to do whatever you want with the form data.

Reform where you can save form data

Saving form data with Form Reform is simply a handler in the processing pipeline. You can save to multiple locations or just one location.

If you need to save data elsewhere, such as to a dedicated table, a table provided through another addon, to another database, send it to an API, forward it to another server, or anywhere you can imagine, you can adapt or develop a form handler to do so.

The complexity of the code depends on where you are saving or sending the data, but wrapping that into a form handler plugin for Form Reform is straight forward.

The Form Reform handler plugin system is designed for easy extension.

Form Reform

Reform the way forms are built. Build a form out of blocks. Take control of how form submissions are processed and how the submitted data is stored. Easy to extend. Easy to reconfigure. Tangible data. Easy to add your own integrations.

Form Reform Display

List and display form submissions from Form Reform.

Form Reform UTM

Not just Form Reform and not just UTM! Capture and hold incoming UTM (or other) tags and make the tag values available to Form Reform and/or Conditional Redirect as {{place_holders}}. You don't need Form Reform to use this.

Form Reform Dynamics

Form handlers for querying Microsoft Dynamics, forwarding and updating form data to Microsoft Dynamics.

Snapshot

A suite of advanced image capture and upload tools. Enhanced drag and drop file uploading. Make screengrabs from within Concrete CMS. Capture images directly from device webcams. Edit images before uploading.

Form Reform Attributes, Express and Users

Save submitted forms to Express objects and user attributes. Add and remove users from groups.

Form Reform Image Picker

Form Reform Image Picker provides an image picking input block for Form Reform. The Image Picker Input is preconfigured to connect to most Omni Gallery gallery and slider display widgets, the core gallery block, and thumbnail showing templates for the core page list block. Advanced settings allow the Image Picker Input to be configured to pick images from other galleries and sliders.

Form Reform Data Picker

Form Reform Data Picker provides data picking input blocks for Form Reform. The Table Picker Input is preconfigured to connect to Universal Content Puller table display widgets. Advanced settings allow the Table Picker Input to be configured to pick data from other HTML tables.

Form Reform Developer

A growing suite of resources to assist those developing blocks, handlers and more complex forms for Form Reform.

Learn with a simple form

While you may have plans to implement some much more complex forms using Form Reform, we strongly recommend you start with a simple form such as our contact form example in order to review the basic principles of using Form Reform before you move onto anything bigger.

  1. Start by submitting the form at Getting Started - Your First Form a few times, even making some deliberate mistakes.
  2. Watch our Getting Started with Form Reform video to see how the form is built.
  3. Read through the rest of Getting Started - Your First Form for more details of how this form is built.
  4. Create a test page on your site to build your own version of Getting Started - Your First Form and experiment.
  5. Develop your test page with some of the concepts introduced by our further examples and experiment with some of the other form inputs.