gform_merge_tag_filterDescriptionUsageParametersExamples1. Exclude fields2. Add an Address field modifier3. List field column4. Address field5. Date field6. File upload field7. :urlencode modifier8. Checkbox field :unchecked modifier9. :decode modifier10. Number field11. Age modifier12. Output Checkboxes field as listPlacementSinceSource Code
Description
Use this filter to dynamically change the merge tag output. Useful when filtering field types from being displayed in the {all_fields} merge tag, or implementing custom field types that require the merge tag output to be different from the value stored with the entry.
Usage
1add_filter( 'gform_merge_tag_filter', 'filter_merge_tag', 10, 6 );
Parameters
$value string
The current merge tag value to be filtered. Replace it with any other text to replace the merge tag output, or return 「false」 to disable this field』s merge tag output.
$merge_tag string
If the merge tag being executed is an individual field merge tag (i.e. {Name:3}), this variable will contain the field』s ID. If not, this variable will contain the name of the merge tag (i.e. all_fields).
$modifier string
The string containing any modifiers for this merge tag. For example, 「value,nohidden」 would be the modifiers for the following merge tag: {all_fields:value,nohidden}.
$field Field Object
The current field.
$raw_value Mixed
The raw value submitted for this field.
$format string
Whether the text is formatted as html or text.
Examples
1. Exclude fields
This example excludes any hidden fields from the {all_fields} merge tag as well as adds a placeholder text for the field whose ID is 2.
1234567891011add_filter( 'gform_merge_tag_filter', 'filter_all_fields', 10, 6 );function filter_all_fields( $value, $merge_tag, $modifier, $field, $raw_value, $format ) { if ( $merge_tag == 'all_fields' && $field->type == 'hidden' ) { return false; } elseif ( $merge_tag == 'all_fields' && $field->id == '2' ) { return 'Call us for details'; } else { return $value; }}
This example extends the default nohidden modifier to also exclude fields with the visibility setting set to hidden.
1234567add_filter( 'gform_merge_tag_filter', function ( $value, $merge_tag, $modifier, $field, $raw_value, $format ) { if ( $merge_tag == 'all_fields' && $modifier == 'nohidden' && ( $field->type == 'hidden' || $field->visibility == 'hidden' ) ) { return false; } return $value;}, 10, 6 );
2. Add an Address field modifier
This example adds a new modifier to the address field which replaces the field value with a map link. {Address:15:map_link}
123456789add_filter( 'gform_merge_tag_filter', 'address_map_link', 11, 6 );function address_map_link( $value, $merge_tag, $modifier, $field, $raw_value, $format ) { if ( $field->type == 'address' && $merge_tag != 'all_fields' && $modifier == 'map_link' && ! empty( $raw_value ) ) { $address_qs = GFCommon::implode_non_blank( ' ', $raw_value ); $address_qs = urlencode( $address_qs ); $value = "Map It"; } return $value;}
3. List field column
This example outputs a comma separated string containing the values for a specific column of a list field. The merge tag {list:10:2} would get the values for column 2 of field 10.
12345678910111213141516171819202122232425262728add_filter( 'gform_merge_tag_filter', function ( $value, $merge_tag, $modifier, $field, $raw_value, $format ) { if ( $field->type == 'list' && $merge_tag != 'all_fields' && is_numeric( $modifier ) ) { // count the actual number of columns $choices = $field->choices; $column_count = count( $choices ); if ( $column_count > 1 ) { // subtract 1 from column number as the choices array is zero based $column_num = $modifier - 1; // get the column label so we can use that as the key to the multi-column values $column = rgars( $choices, "{$column_num}/text" ); // get the list fields values from the $entry $values = unserialize( $raw_value ); $column_values = array(); // loop through the rows and get only the column value we are interested in foreach ( $values as $value ) { $column_values[] = rgar( $value, $column ); } $value = GFCommon::implode_non_blank( ', ', $column_values ); } } return $value;}, 10, 6 );
4. Address field
This shows how you can exclude the Address field from the merge tag output when using one of the country specific types and all the fields other five inputs are left empty by the user.
123456789101112131415add_filter( 'gform_merge_tag_filter', function ( $value, $merge_tag, $options, $field, $raw_value, $format ) { if ( $field->type == 'address' ) { if ( rgempty( $field->id . '.1', $raw_value ) && rgempty( $field->id . '.2', $raw_value ) && rgempty( $field->id . '.3', $raw_value ) && rgempty( $field->id . '.4', $raw_value ) && rgempty( $field->id . '.5', $raw_value ) && ! rgempty( $field->id . '.6', $raw_value ) ) { return false; } } return $value;}, 10, 6 );
5. Date field
This shows how you can reformat a date field value.
12345678add_filter( 'gform_merge_tag_filter', function ( $value, $merge_tag, $options, $field, $raw_value, $format ) { if ( $field->type == 'date' ) { return date_i18n( 'l jS F Y ', strtotime( $raw_value ) ); } return $value;}, 10, 6 );
6. File upload field
This example shows how you can change the output of a single file upload field
123456789add_filter( 'gform_merge_tag_filter', function ( $value, $merge_tag, $modifier, $field, $raw_value, $format ) { if ( $merge_tag != 'all_fields' && $field->type == 'fileupload' ) { $value = str_replace( ' ', '%20', $raw_value ); $pathinfo = pathinfo( $value ); $value = rgar( $pathinfo, 'basename' ); } return $value;}, 10, 6 );
7. :urlencode modifier
This example shows how you can implement a custom modifier which when found will cause the value to be urlencoded.
1234567add_filter( 'gform_merge_tag_filter', function ( $value, $merge_tag, $modifier, $field, $raw_value, $format ) { if ( $merge_tag != 'all_fields' && $modifier == 'urlencode' ) { $value = urlencode( $value ); } return $value;}, 10, 6 );
8. Checkbox field :unchecked modifier
This example shows how you can implement a custom modifier which when found will return only the list of choices which were not selected when the form was submitted.
12345678910111213add_filter( 'gform_merge_tag_filter', function ( $value, $merge_tag, $modifier, $field, $raw_value, $format ) { if ( $field->type == 'checkbox' && $modifier == 'unchecked' ) { $value = array(); foreach ( $field->inputs as $input ) { $input_value = rgar( $raw_value, $input['id'] ); $value[] = $input_value ? '' : $input['label']; } $value = GFCommon::implode_non_blank( ', ', $value ); } return $value;}, 10, 6 );
9. :decode modifier
This example shows how you can implement a custom modifier which when found will convert any special HTML entities found in the value back to characters. Note: Bear in mind this filter only runs for form fields merge tags, so you can』t use this for other merge tags types ( e.g. {entry_url} ).
1234567add_filter( 'gform_merge_tag_filter', function ( $value, $merge_tag, $modifier, $field, $raw_value, $format ) { if ( $merge_tag != 'all_fields' && $modifier == 'decode' ) { $value = htmlspecialchars_decode( $value ); } return $value;}, 10, 6 );
10. Number field
This example shows how you can change the output of a Number field by using the :value modifier with the field merge tag to return the raw unformatted value.
1234567add_filter( 'gform_merge_tag_filter', function ( $value, $merge_tag, $modifier, $field, $raw_value, $format ) { if ( $merge_tag != 'all_fields' && $field->type == 'number' && $modifier == 'value' ) { $value = $raw_value; } return $value;}, 10, 6 );
11. Age modifier
This example shows how you can implement a custom modifier which when found will return the age based on the date field value.
123456789add_filter( 'gform_merge_tag_filter', function ( $value, $merge_tag, $modifier, $field, $raw_value, $format ) { if ( $field->type == 'date' && $modifier == 'age' ) { $today = new DateTime(); $diff = $today->diff( new DateTime( $raw_value ) ); $value = $diff->y; } return $value;}, 10, 6 );
12. Output Checkboxes field as list
This example shows how you can implement the custom modifier :list that when added to a checkboxes field merge tag will output the choices as an HTML list instead of the default comma separated values.
123456789101112131415161718192021add_filter( 'gform_merge_tag_filter', function ( $value, $merge_tag, $modifier, $field, $raw_value, $format ) { if ( $field->type == 'checkbox' && $modifier == 'list' && ! empty( $raw_value ) ) { $items = ''; foreach ( $raw_value as $key => $item ) { if ( ! rgblank( $item ) ) { $items .= '
' . wp_kses_post( GFCommon::selection_display( $item, $field, '', true ) ) . '
'; } } if ( empty( $items ) ) { $value = ''; } else { $value = "
"; } } return $value;}, 10, 6 );
Placement
This code should be placed in the functions.php file of your active theme.
Since
$format parameter added in version 2.4.8.12.
$raw_value parameter added in version 1.7.
Source Code
This filter is located in the following methods in common.php:
GFCommon::replace_variables()
GFCommon::get_submitted_fields()
