Overview
The repeater field allows you to create a set of sub fields which can be repeated again and again whilst editing content!
Any type of field can be added as a sub field which allows you to create and manage very customized data with ease!
Demo
Settings
| Name | Description |
|---|---|
| Sub Fields | Define the sub fields which will appear as cells in the repeater table |
| Minimum Rows | Set a limit on how many rows of data are required |
| Maximum Rows | Set a limit on how many rows of data are allowed |
| Layout | Change the layout style. The table layout is shown in the screenshot above and looks like a standard table with rows and columns. The row layout will not use columns, instead all sub fields are added underneath each other in blocks (good when you have too many sub fields to fit next to each other) |
| Button Label | Customize the ‘Add row’ button text |
Template usage
The repeater field is essential a wrapper for a group of sub fields, so to loop through the rows of data and target the sub field values, you must make use of a few extra functions. These are described below:
Basic Loop
This example shows how to loop through and display data with the have_rows, the_row and the_sub_field functions
<?php
// check if the repeater field has rows of data
if( have_rows('repeater_field_name') ):
// loop through the rows of data
while ( have_rows('repeater_field_name') ) : the_row();
// display a sub field value
the_sub_field('sub_field_name');
endwhile;
else :
// no rows found
endif;
?>Advanced Loop
This example will make use of the get_sub_field function to store variables within the loop
<?php if( have_rows('repeater_field_name') ): ?>
<ul class="slides">
<?php while( have_rows('repeater_field_name') ): the_row();
// vars
$image = get_sub_field('image');
$content = get_sub_field('content');
$link = get_sub_field('link');
?>
<li class="slide">
<?php if( $link ): ?>
<a href="<?php echo $link; ?>">
<?php endif; ?>
<img src="<?php echo $image['url']; ?>" alt="<?php echo $image['alt'] ?>" />
<?php if( $link ): ?>
</a>
<?php endif; ?>
<?php echo $content; ?>
</li>
<?php endwhile; ?>
</ul>
<?php endif; ?>Basic Loop (before version 4.3.0)
The functions have_rows and the_row were added in v4.3.0. Prior to this, a function called has_sub_field was available (and still is) to loop through the rows of data. There is 1 key difference to this function and that is you cannot use it within an if statement
<?php if(get_field('repeater_field_name')): ?>
<ul>
<?php while(has_sub_field('repeater_field_name')): ?>
<li>sub_field_1 = <?php the_sub_field('sub_field_1'); ?>, sub_field_2 = <?php the_sub_field('sub_field_2'); ?>, etc</li>
<?php endwhile; ?>
</ul>
<?php endif; ?>Basic Loop (PHP foreach loop)
This example shows how you can use get_field function to return all the row data for a repeater field. This is useful for querying the data for a specific row.
<?php
$rows = get_field('repeater_field_name');
if($rows)
{
echo '<ul>';
foreach($rows as $row)
{
echo '<li>sub_field_1 = ' . $row['sub_field_1'] . ', sub_field_2 = ' . $row['sub_field_2'] .', etc</li>';
}
echo '</ul>';
}Get the first row from a repeater
This example shows how to find the first row from a repeater and display an image found in that row.
<?php
$rows = get_field('repeater_field_name' ); // get all the rows
$first_row = $rows[0]; // get the first row
$first_row_image = $first_row['sub_field_name' ]; // get the sub field value
// Note
// $first_row_image = 123 (image ID)
$image = wp_get_attachment_image_src( $first_row_image, 'full' );
// url = $image[0];
// width = $image[1];
// height = $image[2];
?>
<img src="<?php echo $image[0]; ?>" />Get a random row from a repeater
This example shows how to find a random row from a repeater and display an image found in that row.
<?php
$rows = get_field('repeater_field_name' ); // get all the rows
$rand_row = $rows[ array_rand( $rows ) ]; // get a random row
$rand_row_image = $rand_row['sub_field_name' ]; // get the sub field value
// Note
// $first_row_image = 123 (image ID)
$image = wp_get_attachment_image_src( $rand_row_image, 'full' );
// url = $image[0];
// width = $image[1];
// height = $image[2];
?>
<img src="<?php echo $image[0]; ?>" />FAQ
Activating the repeater field
The repeater field is a premium add-on which can be purchased, downloaded and activated from the add-ons page.
How is the data saved?
The repeater field saves all it’s data in the wp_postmeta table. If your repeater field is called “gallery” and contains 2 sub fields called “image” and “description”, this would be the database structure of 2 rows of data:
// meta_key meta_value
gallery 2 // number of rows
gallery_0_image 6 // sub field value
gallery_0_description "some text" // sub field value
gallery_1_image 7 // sub field value
gallery_1_description "some text" // sub field value