Option Repeater

The Option Repeater setting, option-repeater, is an advanced setting type for adding a dynamic number of inputs to a setting. Formatted as a fieldset, options can be added, re-ordered, and removed from the repeater.

List Field Option Repeater

The following example shows a basic option-repeater definition.

// …
'options' = array(
'name' => 'options',
'type' => 'option-repeater',
'label' => __( 'Options' ) . ' <a href="#" class="nf-add-new">' . __( 'Add New' ) . '</a>',
'width' => 'full',
'group' => 'primary',
'columns' => array(
'label' => array(
'column1' => __( 'Column One' ),
'default' => '',
/* Optional */
'value' => array(
array( 'label' => 'Default Option', 'order' => 0 ),
/* Optional */
'tmpl_row' => 'nf-tmpl-custom-repeater-row'
// …

In addition to the basic setting configuration, the option-repeater expects a columns array.

Each specified column is also an array requiring a header (like table header) and a default (default value) property.

The value item must also be an array, with a key value pair for each option. For option repeater settings, the value item will create default options in the repeater.

Also, the row item specifies the template name to load for displaying custom columns. More on this soon.

Row Columns

By default, the option repeater starts with the following columns:

– Label
– Value (The values stored in the database)
– Calc Value (The value used by calculations)
– Checked (Checkbox: if the option should be selected by default)

Customizing the Option Repeater

The row used by the option repeater can be customized for use in other situations. As an example, Form Calculations only have two columns: Variable Name and Equation.

Calculations Option Repeater

Calculations Option Repeater

Row Template

Built with Backbone and Underscore, the option repeater utilizes a row template which is repeated for each option. By specifying a new row template the columns and data used by the option repeater can be customized.

The basic parts of the row template are the draggable handle for re-ordering rows and the dismissible icon for deleting a row. Between those two icons are the option columns. These columns must match the columns defined in the corresponding setting.

<script id="nf-tmpl-custom-repeater-row" type="text/template">
<! Draggable Handle for reordering rows >
<span class="dashicons dashicons-menu handle"></span>
<! Column 1 (Textbox) >
<input type="text" class="setting" value="<%= column1 %>" data-id="column1">
<! Dismissible icon for removing a row >
<span class="dashicons dashicons-dismiss nf-delete"></span>

Loading a Custom Row Template

Custom row templates can be added to the builder using the ninja_forms_builder_templates action hook.

// …
add_action( 'ninja_forms_builder_templates', 'kbj_load_custom_row_template' );
function kbj_load_custom_row_template(){
<!– Custom Row Template Here –>
// …

Full Example

[TODO] Add plugin example.