gform_merge_tag_filter

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

add_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.

add_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.

add_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}

add_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      = "<a href='http://maps.google.com/maps?q={$address_qs}' target='_blank' class='map-it-link'>Map It</a>";
    }
    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.

add_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.

add_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.

add_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

add_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.

add_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.

add_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} ).

add_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.

add_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.

add_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.

add_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 .= '<li>' . wp_kses_post( GFCommon::selection_display( $item, $field, '', true ) ) . '</li>';
			}
		}

		if ( empty( $items ) ) {
			$value = '';
		} else {
			$value = "<ul class='bulleted'>$items</ul>";
		}

	}

	return $value;
}, 10, 6 );

This example shows how you can change the output of a Consent field by using the :value modifier with the field merge tag to return the checkbox label.

add_filter( 'gform_merge_tag_filter', function ( $value, $merge_tag, $modifier, $field, $raw_value, $format ) {
    if ( $merge_tag != 'all_fields' && $field->type == 'consent' && ( $merge_tag === $field->id . '.1' ) && $modifier == 'value' && $value ) {
        $value = $field->checkboxLabel;
    }

    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()