| <?php | |
| /** | |
| * Gravity Wiz // Gravity Forms // Round Robin | |
| * | |
| * Cycle through the choices of a designated field assigning the next available choice when an entry is submitted. The | |
| * cycle starts with the first choice progressing to the next available choice on each submission. After each choice has | |
| * been assigned it will restart from the first choice. | |
| * | |
| * This functionality is useful when distributing leads evenly to a group of sales reps, scheduling shifts such that | |
| * employees are assigned to the next available shift, and/or balancing the responsibility of any task-oriented | |
| * submission (e.g. support request, job application, contest entry). | |
| * | |
| * @version 1.1 | |
| * @author David Smith <david@gravitywiz.com> | |
| * @license GPL-2.0+ | |
| * @link http://gravitywiz.com/ | |
| */ | |
| class GW_Round_Robin { | |
| public function __construct( $args = array() ) { | |
| // set our default arguments, parse against the provided arguments, and store for use throughout the class | |
| $this->_args = wp_parse_args( $args, array( | |
| 'form_id' => false, | |
| 'field_id' => false, | |
| 'hide_field' => true, | |
| ) ); | |
| // do version check in the init to make sure if GF is going to be loaded, it is already loaded | |
| add_action( 'init', array( $this, 'init' ) ); | |
| } | |
| public function init() { | |
| add_filter( 'gform_pre_render', array( $this, 'hide_round_robin_field' ) ); | |
| add_filter( 'gform_entry_post_save', array( $this, 'apply_round_robin' ), 7, 2 ); | |
| add_filter( 'gform_email_fields_notification_admin', array( $this, 'add_round_robin_field_to_notification_email_fields' ), 10, 2 ); | |
| } | |
| public function hide_round_robin_field( $form ) { | |
| if( ! $this->_args['hide_field'] || ! $this->is_applicable_form( $form ) ) { | |
| return $form; | |
| } | |
| foreach( $form['fields'] as &$field ) { | |
| if( $field->id == $this->_args['field_id'] ) { | |
| $field->visibility = 'hidden'; | |
| } | |
| } | |
| return $form; | |
| } | |
| public function apply_round_robin( $entry, $form ) { | |
| if ( ! $this->is_applicable_form( $entry['form_id'] ) ) { | |
| return $entry; | |
| } | |
| $rotation = $this->get_rotation_values( $this->_args['field_id'], $form ); | |
| // Get the last submitted entry. | |
| $last_entry = rgar( GFAPI::get_entries( $entry['form_id'], array( 'status' => 'active' ), array( 'direction' => 'desc' ), array( 'offset' => 1, 'page_size' => 1 ) ), 0 ); | |
| // Get the value submitted for our designated field in the last entry. | |
| $last_value = rgar( $last_entry, $this->_args['field_id'] ); | |
| // Determine the next index at which to fetch our value. | |
| $next_index = empty( $last_value ) ? 0 : array_search( $last_value, $rotation ) + 1; | |
| if ( $next_index > count( $rotation ) - 1 ) { | |
| $next_index = 0; | |
| } | |
| // Get the next value based on our rotation. | |
| $next_value = $rotation[ $next_index ]; | |
| // Update the value of our designated field in the database. | |
| GFAPI::update_entry_field( $entry['id'], $this->_args['field_id'], $next_value ); | |
| // Update the value of our designated field in the $entry object that will be used to continuing processing the current submission. | |
| $entry[ $this->_args['field_id'] ] = $next_value; | |
| return $entry; | |
| } | |
| public function add_round_robin_field_to_notification_email_fields( $fields, $form ) { | |
| if( ! $this->is_applicable_form( $form ) ) { | |
| return $fields; | |
| } | |
| $rotation = $this->get_rotation_values( $this->_args['field_id'], $form ); | |
| if( filter_var( $rotation[0], FILTER_VALIDATE_EMAIL ) ) { | |
| $fields[] = GFAPI::get_field( $form, $this->_args['field_id'] ); | |
| } | |
| return $fields; | |
| } | |
| public function get_rotation_values( $field_id, $form ) { | |
| $field = GFAPI::get_field( $form, $field_id ); | |
| $rotation = array_filter( wp_list_pluck( $field->choices, 'value' ) ); | |
| return $rotation; | |
| } | |
| public function is_applicable_form( $form ) { | |
| $form_id = isset( $form['id'] ) ? $form['id'] : $form; | |
| return empty( $this->_args['form_id'] ) || $form_id == $this->_args['form_id']; | |
| } | |
| } | |
| # Configuration | |
| new GW_Round_Robin( array( | |
| 'form_id' => 123, | |
| 'field_id' => 4, | |
| ) ); |
Overview
Imagine you have a form where you’d like to automatically cycle through the choices of a designated field with every entry. The cycle starts with the first choice, progressing to the next available choice on each submission. After each choice has been assigned, it will restart from the first option.
The practicality of this is for any task-oriented form, such as sales leads, support requests, or a shift scheduler. Whatever choices are stored in the choice-based field will be cycled for each submission, evenly distributing the values across all submissions in a first-in-first-out basis.
Using the Snippet
Prerequisites
Confirm that you have Gravity Forms installed and activated and that you’ve installed the snippet.
Add a Drop Down Field
With the snippet installed, add a Drop Down Field to your form and set the choices to the different values you want to cycle through. This field will automatically be hidden by default.
Update Snippet with Form and Field ID
Update the form_id and field_id in the snippet to match your Form ID and the Field ID for your Drop Down from above.
| new GW_Round_Robin( array( | |
| 'form_id' => 123, | |
| 'field_id' => 4, | |
| ) ); |
That’s It!
When the form is submitted, the snippet will cycle to the next value in the Drop Down for every submission.
Parameters
- form_id (integer) (required) This is the Form ID where you want to cycle through the choices. There is no default value.
- field_id (integer) (required) This is the Field ID for the field where the choices are stored. There is no default value.
- hide_field (boolean) (optional) Automatically hide the choice-based field. The default value is true.
Taking It Further
This snippet should be considered a building block to create round robin forms. For an example of how this can be implemented in a real world scenario, check out the How To Evenly Distribute Leads to a Sales Team with Gravity Forms tutorial.
Did this resource help you do something awesome with Gravity Forms? Then you'll absolutely love Gravity Perks; a suite of 31+ essential add-ons for Gravity Forms with support you can count on.
having trouble installing this. can anyone assist? :)
Hello Matthew, what kind of issue are you having? Please check out our Snippet Troubleshooting section to see if these tips help you out.