I'm excited to share a recent project challenge I faced, which turned into a pretty cool discovery, a little-known gem in Gravity Forms.
The Challenge
I was knee-deep in a client project, creating a registration form. Being a big fan of Gravity Forms, it was my go-to tool from the beginning. Among its required fields was one for registering songs. Initially, I opted for a list field solution to handle song registrations. However, when the client threw a curveball and requested support for multiple musicians per song, the limitations of the list field became glaringly apparent. My first reaction was, "You can't add a list inside a list," the challenge became apparent.
So, it's time to go digging for a solution. And that's when I stumbled upon the Repeater API – a hidden gem within Gravity Forms, just waiting to be put to work.
The Repeater API
With the release of Gravity Forms 2.4, developers gained access to a new feature: the repeater field. Although still in beta and lacking a user interface, developers can take advantage of its capabilities by utilizing the Repeater API to construct these fields programmatically.
But what exactly does the Gravity Forms Repeater API offer?
In essence, a repeater field acts as a collection of other Gravity Forms fields, grouped for use within a form. Unlike traditional fields, a repeater field allows users to input multiple instances of the collection within a single form submission.
For instance, consider a contact form featuring a repeater field for phone numbers. This setup enables users to input multiple country codes, phone numbers, and associated data types in a single form submission. Similarly, a repeater field can streamline convention registrations by allowing attendees to add multiple names and job titles from the same organization.
It's important to note that repeater fields can be nested within each other, offering even greater flexibility. For example, combining a contact phone number repeater with an attendee repeater allows for multiple contact numbers per attendee.
For those seeking further information, Gravity Forms' official documentation offers detailed insights into the capabilities of the Repeater API.
Hands-on Code: Implementing the Repeater Field
After carefully reading the docs and some examples found on the internet, it's time to roll up our sleeves and dive into the code. In this section, we'll walk through the process of implementing the repeater field for songs and musicians in our Gravity Form. Let's get started!
/**
* Registers the repeater field for songs and musicians in the specified Gravity Form.
*
* @param array $form The Gravity Form object.
* @return array The modified Gravity Form object.
*/
function register_songs_repeater( $form ) {
// First, let's create our function to register the repeater field.
// Next, we want to make sure we're targeting the correct form.
// We use an early return to exit the function if it's not the right form.
if ( $form['id'] != YOUR_FORM_ID ) {
return $form;
}
}
We begin by defining a function called register_songs_repeater which takes a $form parameter representing the Gravity Form object.
Inside the function, we use a conditional statement (if) to check if the ID of the form matches the ID of the form we want to modify (YOUR_FORM_ID).
If the form ID doesn't match, we use an early return statement to exit the function and return the unmodified form object.
// Create the field for song name
$song_name_field = GF_Fields::create(
[
'type' => 'text',
'label' => esc_html__( 'Song Name', 'yourtextdomain' ),
'id' => 1011,
'formId' => $form['id'],
'pageNumber' => 1,
]
);
In this code:
We're creating a new field object for the song name using Gravity Forms' GF_Fields::create() method.
The type parameter is set to text, indicating that this field will be a text input.
The label parameter specifies the label text for the field, which in this case is "Song Name".
The id parameter assigns a unique ID to the field within the form.
The formId parameter dynamically assigns the form ID to ensure that the field is added to the correct form.
The pageNumber parameter indicates the page number of the form where this field should appear.
It's important to note that the Repeater Field supports various field types, and for a list of allowed fields and their configurations, it's recommended to refer to the documentation provided by Gravity Forms.
Now that we've set up the individual fields, it's time to bring them together within a repeater field. This allows users to register multiple songs within the same form submission, providing a seamless experience. Let's dive into the code and create the repeater field for our song registration form:
// Create a repeater for song registration and specify the fields to display inside the repeater.
$songs_repeater = GF_Fields::create(
[
'type' => 'repeater',
'description' => 'Allows users to register multiple songs within the same form submission.', // Provide a brief description of the repeater field
'id' => 1011, // Unique ID for the repeater field within the form
'formId' => $form['id'],
'label' => 'Songs', // Label for the repeater field
'addButtonText' => 'Add Song', // Text for the button to add a new song entry
'removeButtonText' => 'Remove Song', // Text for the button to remove a song entry
'pageNumber' => 1, // Page number of the form where the repeater field should appear
'fields' => [ $song_name_field ], // Fields to be displayed inside the repeater
]
);
We're creating a repeater field for song registration using the GF_Fields::create() method.
The description parameter provides a brief explanation of the repeater field, informing users about its purpose.
The id parameter assigns a unique ID to the repeater field within the form.
The label parameter specifies the label text for the repeater field, indicating that it represents songs.
The addButtonText and removeButtonText parameters define the text for the buttons to add and remove song entries, respectively.
The pageNumber parameter indicates the page number of the form where this repeater field should appear.
The fields parameter specifies the fields to be included within the repeater, in this case, we've added the field for the song name.
We are going to add another repeater field to our newly created repeater for songs. For simplicity, we'll assume the existence of other fields and dive straight into creating this repeater for musicians and performers:
// Create a repeater for musicians and performers
$musicians_repeater = GF_Fields::create(
[
'type' => 'repeater',
'label' => esc_html__( 'Musicians and Performers', 'yourtextdomain' ),
'id' => 1002,
'formId' => $form['id'],
'addButtonText' => esc_html__( 'Add', 'yourtextdomain' ),
'removeButtonText' => esc_html__( 'Remove', 'yourtextdomain' ),
'pageNumber' => 1,
'fields' => [
$full_name_field, // Field for full name of musician
$instruments_field, // Field for instruments played
$role_field, // Field for role (interpreter, performer, or both)
],
]
);
Now, we'll integrate the newly created repeater for musicians and performers into the $songs_repeater field array. This enables users to register both songs and associated musicians seamlessly within the same form submission. Here's how we'll update the $songs_repeater field array:
// Update the fields array of $songs_repeater to include the musicians repeater
$fields_array = [
$song_name_field, // Field for song name
$musicians_repeater, // Field for musicians and performers
];
// Create the repeater for songs and include the musicians repeater
$songs_repeater = GF_Fields::create(
[
'type' => 'repeater',
'label' => esc_html__( 'Songs - Name of each song in the album or EP.', 'yourtextdomain' ),
'id' => 1011, // Ensure unique ID within the form
'formId' => $form['id'],
'pageNumber' => 1,
'fields' => $fields_array, // Update fields array to include musicians repeater
]
);
And that's how you can create nested repeaters, allowing for a structured and flexible form setup. Now, let's proceed to add our nested repeater to our form, ensuring it's placed at the desired position.
To place the repeater field at a specific position in your form, you can use the array_splice() function. The fields array in Gravity Forms starts with an index of 0. By adding the repeater field at a certain index, you control its placement in the form. For example:
array_splice( $form['fields'], 10, 0, array( $songs_repeater ) );To complete our form set up, we simply return our modified form and hook it into the gform_form_post_get_meta_YOUR_FORM_ID filter. This ensures that our repeater fields are seamlessly integrated into the form. Here's the hook to add to your code:
add_filter( 'gform_form_post_get_meta_YOUR_FORM_ID', 'register_songs_repeater' );With this hook in place, our form is ready to capture song registrations along with associated musicians, providing a robust solution for our client's needs.
As always, this is how I found a solution to my challenges. Through careful planning and implementation, we've crafted a customized solution that perfectly meets our client's requirements. Happy coding!
Share this article