Using repeatable groups

Creating a repeatable group

The Simple Meta Boxes class enables you to group several fields into a repeatable group. Repeatable groups are convenient in cases that require the same couple of fields to appear together in a repeatable manner for an undefined number of times inside a post/page. A repeatable group will allow you to duplicate an entire group, as opposed to a repeater field, which only duplicates one specific field.

By adding the repeater_group key to a metabox all the fields in that respective metabox will become a repeatable group. The value of repeater_group should be an array. The array can be empty, but you can also pass it several optional keys (arguments):

title - String. Optional. The titles for the group items. The default title is "group".

numbering - Boolean. Optional. Used to denote whether or not the group titles should be numbered. Defaults to TRUE.

numbering_prefix - String. Optional. Allows you to specify the prefix that comes before the group title number. Default to an empty string. This argument will be ignored if the numbering arguments is set to FALSE.

Let's create a group together. This group will be used on a "contact us" template and enable the end-user to specify contact details for different people. The group will only appear on the "contact us" template and will have the following fields: name, phone number and email.

$metaboxes['contact_us_fields'] = array(
    'id' => 'contact_us_fields',
    'title' => 'Contacts List',
    'page_templates' => array( 'page-contact-us.php' ),
    'repeater_group' => array(
        'title' => 'Contact Person',
        'numbering_prefix' => '#',
    ),
    'fields' => array(
        array(
            'title' => 'Name',
            'id' => 'name',
            'type' => 'text',
        ),
        array(
            'title' => 'Phone',
            'id' => 'phone',
            'type' => 'text',
        ),
        array(
            'title' => 'Email',
            'id' => 'email',
            'type' => 'email',
        ),
    )
);

Iterating over a group

Repeater groups allow you to visually bundle meta fields together inside the Wordpress GUI, and under the hood Simple Meta Boxes will create an array that will include all the group items. Continuing with the contact_us_fields group that we created in the previous section, let's edit our contact us page. Add two group items to our contacts list and save it:

Now we should have access to these items within our page-contact-us.php template for the specific page we saved. Let's see how the group looks if we retrieve and then dump it onto the page:

<pre>
<?php 
	$contacts = get_post_meta(get_the_ID(), 'contact_us_fields', TRUE);
	var_dump( $contacts );
?>
</pre>

The result would be an array of grouped items:

array(2) {
  [0]=>
  array(3) {
    ["name"]=>
    string(5) "Nadav"
    ["phone"]=>
    string(8) "89402131"
    ["email"]=>
    string(15) "test@fake.com"
  }
  [1]=>
  array(3) {
    ["name"]=>
    string(4) "John"
    ["phone"]=>
    string(9) "999888777"
    ["email"]=>
    string(12) "john@doe.com"
  }
}

Having your meta fields neatly grouped as an array makes it easy to iterate over them as a group. Let's wrap our contact information in a nice HTML syntax. Delete var_dump( $contacts ); and add the following instead:

<?php $contacts = get_post_meta( get_the_ID(), 'contact_us_fields', true ); ?>
<?php if ($contacts): //Only show the following section if a meta group exists for this page/post ?>
    <section>
	<?php foreach ($contacts as $contact): ?>
	    <article>
                <ul>
		    <li>Name: <?php echo $contact['name']; ?></li>
		    <li>Phone: <?php echo $contact['phone']; ?></li>
		    <li>Email: <?php echo $contact['email']; ?></li>
		</ul>
	    </article>
	<?php endforeach; ?>
    </section>
<?php endif; ?>