Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
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:
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' ) ) )) ));
add_group method expects two parameters:
idmust be a unique identifier of the group.
argsshould 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' ) ) )) ));
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
$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.
When a repeater field has a single group you can choose between two layouts:
"standard") uses a normal meta box.
"table") will skip the box and display fields as the columns of a table.
In PHP this wroks through the
$repeater_field->set_layout( 'table' );
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) 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
$field->set_chooser_type( 'dropdown' );
|Text in the button||
|Placeholder with multiple groups||
||Drag an item here to create a new entry.|
|Placeholder with a single group||
||Please click the "<add_text>" button to add a new entry.|
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
$field->set_background_color( '#008B8B' )
Groups are added to a repeater field through the
add_group method. It accepts either:
argsparameters. In this case the method will create a new group based on the parameters.
Ultimate_Fields\Container\Repeater_Groupobject - 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
add_location. Additionally, you can use the following options:
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 );
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
"both" as options.
$group->set_popup_mode( 'popup' );
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 )
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.
$repeater_group->set_title_background( '#ff0000' ); $repeater_group->set_title_color( '#fff' ); $repeater_group->set_border_color( '#000' );
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
$repeater_group->set_icon( 'dashicons-format-image' );
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.
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
the_value and etc:
Once you are inside the loop you can use two additional groups of functions:
get_group_typewill return the ID of the current group, while
the_group_typewill display it.
Value functions: Those functions display and return the sub-values from the current group. They must always be wrapped by the
have_groupsloop. All of those functions expect a single parameter, which is the name of the sub-field.
get_sub_valuereturns the raw sub-value, like
get_the_sub_valuereturn a processed sub-value, like
the_sub_valuedisplays a processed sub-value, like