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.

Lets 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 on a group

Repeater groups allow you to visually bundle meta fields together inside the Wordpress GUI, but under the hood each meta field in the group is still individually saved under its own id. This means that you can use these fields without the need to handle the entire group. On the other hand it also means they are not bundles together in a code-friendly manner. However, you can handle them as a group by creating a for loop. When a group is saved Simple Meta Boxes will create an iterator meta key for it. This meta key inherits the meta box's key name and stores the number of items in said group as a string. Using this key we can iterate over the individual group meta field arrays, essentially treating them as a group. The following example uses the contact_us_fields group that we created earlier and outputs the name, phone and email for each item in the group.

    	//Retrieve all the meta field arrays as well as the group iterator
    	$post_id = get_the_ID();
    	$name = get_post_meta( $post_id, 'name', TRUE );
    	$phone = get_post_meta( $post_id, 'phone', TRUE );
    	$email = get_post_meta( $post_id, 'email', TRUE );
	$groupIterator = (int)get_post_meta( $post_id, 'contact_us_fields', TRUE );

    	//Iterate over the group items
    	for ($i = 0 ; $i < $groupIterator; $i++) 
    	{
    		echo isset($name[$i])? $name[$i]: '';
    		echo isset($phone[$i])? $phone[$i]: '';
    		echo isset($email[$i])? $email[$i]: '';
    	}

This is a very simple example without any HTML formatting but it nonetheless shows how to iterate on a group. There are three important things to note regarding this example:

• Since meta keys are always saved as strings this example uses type casting to ensure that the group iterator (in this case $groupIterator) will be a valid integer.
• isset is being used while accessing meta field keys to prevent cases in which some fields in the group might not exist. To prevent server errors it is recommended not to skip this vital step.
• Although not shown in this example it is always a good idea to escape the meta key values before echoing them.

Do you prefer to make use of a multidimensional array that contains the entire group? The following function should have you covered: