Repeater

Purpose

The Repeater field allows you to create repeatable sets of nested fields. Here are some of the highlights:

• You can add both a single and multiple sets of sub-fields to a single repeater field.
• In single-group mode you can choose between normal layout and a table-like layout.
• You can limit the total amount of groups in total, as well as the amount of times a single group can be used.
• All field types are supported for sub-fields, meaning that you can nest repeaters as deep as you need to.

Here is a ten-minute video, describing most of the features of the Repeater field:

Creating repeaters

To start, you need to use repeater when calling Container::create. Afterwards, you must always use the add_group method of the repeater to add groups to it. Here is how a basic repeater is created:

<?php
use Ultimate_Fields\Container;
use Ultimate_Fields\Field;

Container::create( 'repeaters' )
    ->add_fields(array(
        Field::create( 'repeater', 'basic_repeater' )
            ->add_group( 'person', array(
                'fields' => array(
                    Field::create( 'text', 'name' )
                )
            ))
    ));

The add_group method expects two parameters:

1. id must be a unique identifier of the group.
2. args should be an array, which contains all arguments for the group, including fields.

The method may be called multiple times in order to add multiple groups to the field:

Container::create( 'repeaters' )
    ->add_fields(array(
        Field::create( 'repeater', 'content_blocks' )
            ->add_group( 'text', array(
                'fields' => array(
                    Field::create( 'text', 'title' ),
                    Field::create( 'textarea', 'text' )
                )
            ))
            ->add_group( 'image', array(
                'fields' => array(
                    Field::create( 'image', 'image' )
                )
            ))
    ));

Settings

The following settings apply to the whole field. Please scroll down to Group Settings to learn how to setup individual groups.

Minumum and Maximum

You can adjust the minimum and maximum amount of allowed groups in a repeater.

In the interface, use the "Limits" field to set the minimum and maximum.

In PHP you can do this throuth the set_min and set_max methods:

$repeater_field->set_min( 3 )->set_max( 10 );

If the minimum amount of items has not been reached, the field will fail validation. When the maximum has been reached, the buttons for adding and cloning groups will disappear.

Layout

When a repeater field has a single group you can choose between two layouts:

• Standard ("standard") uses a normal meta box.
• Table ("table") will skip the box and display fields as the columns of a table.

In PHP this wroks through the set_layout method:

$repeater_field->set_layout( 'table' );

Chooser type

You can change the layout of a repeater field when a single group is used. When you are using multiple groups, you can change the chooser type. There are two options for it:

• Widgets (default) works similarly to WordPress widgets by allowing users to drag a new group into the place where they need it to appear.
• Dropdown (dropdown) is useful when there you have a big amount of available grops. It uses a select element, as well as a button, in order to allow new groups to be added.

In PHP you can use the set_chooser_type method:

$field->set_chooser_type( 'dropdown' );

Strings

Text	Method	Default value
Text in the button	set_add_text	Add entry
Placeholder with multiple groups	set_placeholder_text	Drag an item here to create a new entry.
Placeholder with a single group	set_placeholder_text	Please click the "<add_text>" button to add a new entry.

Background Color

You can change the background color of the repeater.

This setting works well when you need to visually separate different levels of nested fields. Use the set_background_color method:

$field->set_background_color( '#008B8B' )

Group Settings

Groups are added to a repeater field through the add_group method. It accepts either:

• id and args parameters. In this case the method will create a new group based on the parameters.
• A Ultimate_Fields\Container\Repeater_Group object - this would be a group, which has already been initialized.

As the class name suggests, repeater groups are containers. Just like with normal containers, you can use both arguments and setters. To read more about this, please read the Arguments vs. Setters section of the Container Settings article.

Groups support the same arguments and setters as standard containers, except for set_layout and add_location. Additionally, you can use the following options:

Method name	Argument
set_edit_mode	edit_mode
set_maximum	maximum
set_title_background	title_background
set_title_color	title_color
set_border_color	border_color
set_icon	icon
set_title_template	title_template

All examples for the methods below will use methods, but keep in mind that you can use them as arguments by just removing the set_ prefix from the method name.

The following two examples are equivalent:

use Ultimate_Fields\Container;
use Ultimate_Fields\Container\Repeater_Group;
use Ultimate_Fields\Field;

// Preparation
$repeater_field = Field::create( 'repeater', 'example_repeater' );
Container::create( 'repeater_example' )
	->add_location( 'options' )
	->add_fields(array(
		$repeater_field
	));

// Use arguments
$repeater_field->add_group( 'image', array(
	'title'  => __( 'Image' ),
	'icon'   => 'dashicons dashicons-format-image',
    'fields' => array(
        Field::create( 'image', 'image' )
    )
));

// Create manually
$group = Repeater_Group::create( 'image' )
    ->set_title( __( 'Image' ) )
    ->set_icon( 'dashicons dashicons-format-image' )
	->add_fields(array(
		Field::create( 'image', 'image' )
	));

$repeater_field->add_group( $group );

Edit Mode

Repeater groups support two edit modes and you can choose whether a group should use one or both of them.

Inline mode is the default mode, which uses a (meta-) box in order to display the fields inline.

Popup mode shows the fields of the group in a full-screen popup. It is useful for when there are a lot of fields to edit in a group, as there is more space to do so.

In PHP you should use the set_edit_mode method of the group or the edit_mode argument. Both of them support "inline", "popup" and "both" as options.

$group->set_popup_mode( 'popup' );

Maximum Occurrences

In the UI, use the "Maximum occurences" setting to limit the amount of times a group can be added to a single field.

In PHP, use the set_max method or max argument of the group:

$group->set_max( 3 )

Colors

You can adjust the folowing colors of each group:

• Title Background
• Title Color
• Border Color

In PHP all methods for colors expect a single parameter - a hexadecimal color string.

Examples:

$repeater_group->set_title_background( '#ff0000' );
$repeater_group->set_title_color( '#fff' );
$repeater_group->set_border_color( '#000' );

Icon

You can change the icon, which appears next to the group title when the group is being used. This icon will not appear in the chooser.

Because of the fact that Ultimate Fields loads styles danymically only when a field is displayed, there is no possibility to control whether an icon font set should be loaded or not. Therefore, the repeater field only supports Dashicons icons.

In PHP you can use the set_icon method or the icon argument:

$repeater_group->set_icon( 'dashicons-format-image' );

Title Template

You can set a custom template for the title of a group. This can be done by using a template, compatible with Underscore.js.

$group = Repeater_Group::create( 'peron' )
    ->add_fields(array(
        Field::create( 'text', 'first_name' ),
        Field::create( 'text', 'last_name' )
    ))
    ->set_title_template( '<%= first_name %> <%= first_name %>' );

Within the template, you can use all avialble field names as local variables. In this example, we are using the first and last name in order to generate a full name, which will be displayed in the title-bar of the group even when it is collapsed.

Usage

The article Using field values explains how to use the values of standard fields. Even though the repeater is also a field, its value consists of the values of its sub-fields, which require a slightly different approach. Before we examine each of those functions individually, let's take a look at a couple of examples:

<!-- Using the values of a repeater with a single group -->
<?php while( have_groups( 'team' ) ): the_group() ?>
<div class="person">
    <h4><?php the_sub_value( 'first_name' ) ?> <?php the_sub_value( 'last_name' ) ?></h4>
</div>
<?php endwhile ?>

<!-- Using the values of a repeater with multiple groups (content_blocks) -->
<?php while( have_groups( 'content_blocks' ) ): the_group() ?>
<div class="block block-<?php the_group_type() ?>">
    <?php if( 'image' == get_group_type() ): ?>
        <?php the_sub_value( 'image' ) ?>
    <?php else if( 'text' == get_group_type() ): ?>
        <?php if( get_sub_value( 'title' ) ): ?>
        <h3><?php the_sub_value( 'title' ) ?></h3>
        <?php endif; ?>

        <?php the_sub_value( 'text' ) ?>
    <?php endif ?>
</div>
<?php endwhile ?>

As you can see, the way to use repeater values looks very similar to the WordPress loop: There is a while loop with a have_groups() function and a call to the_group during every iteration.

The only difference is that while have_posts does not require any parameters, have_group requires the same parameters that are used for get_value, the_value and etc: $name and $type.

Once you are inside the loop you can use two additional groups of functions:

• Group functions: get_group_type will return the ID of the current group, while the_group_type will display it.
• Value functions: Those functions display and return the sub-values from the current group. They must always be wrapped by the have_groups loop. All of those functions expect a single parameter, which is the name of the sub-field.
  • get_sub_value returns the raw sub-value, like get_value.
  • get_the_sub_value return a processed sub-value, like get_the_value.
  • the_sub_value displays a processed sub-value, like the_value.