gform_merge_tag_data

Description

Use this filter to add, remove or modify the data that will be used to replace merge tags found in the specified string. This includes the $entry data used to replace field-based merge tags. Note: this filter is not triggered during form display, it is intended for implementing custom merge tags which are used in notifications, confirmations, and feed add-ons.

Usage

The following would apply to all forms.

add_filter( 'gform_merge_tag_data', 'your_function_name', 10, 4 );

Parameters

  • $data array

    Data that will be used to replace merge tags. Array keys represent available merge tags. Values can be accessed by specifying a property: {entry:date_created}. Value can be an array of data or a callable function.

    $data['customTag'] = 'my_func_to_retrieve_data';
    $data['anotherTag'] = array(
        'testKey' => 'Test Value'
    );

    Callable functions will be passed the current $entry and $form objects.

    function my_func_to_retrieve_data( $entry, $form ) {
        return array(
            'key1' => 'value1',
            'key2' => 'value2'
        );
    }

    This data can be accessed with merge tags by specifying the data key and the desired property. Examples:

    • {customTag:key1} outputs “value1”
    • {anotherTag:testKey} outputs “Test Value”
  • $text string

    The current text that will be parsed for merge tags.

  • $form Form Object

    The current form object.

  • $entry Entry Object

    The current form object.

Examples

1. Provide Custom Data

add_filter( 'gform_merge_tag_data', 'my_custom_merge_tag_data', 10, 4 );
function my_custom_merge_tag_data( $data, $text, $form, $entry ) {
    $data['myCustomTag'] = array(
        'key1' => 'Value One',
        'key2' => 'Value Two'
    );
    return $data;
}

2. Entry creator

This example shows how to add a {created_by} merge tag e.g. {created_by:roles} to return a comma separated string containing the roles assigned to the user who created the entry.

add_filter( 'gform_merge_tag_data', function ( $data, $text, $form, $entry ) {
	$data['created_by'] = array();
	if ( ! empty( $entry['created_by'] ) ) {
		$user                             = new WP_User( $entry['created_by'] );
		$data['created_by']               = get_object_vars( $user->data );
		$data['created_by']['first_name'] = $user->get( 'first_name' );
		$data['created_by']['last_name']  = $user->get( 'last_name' );
		$data['created_by']['roles']      = implode( ', ', $user->roles );
	}

	return $data;
}, 10, 4 );

Changelog

  • 2.1.1.11
    Added the $entry parameter.
  • 2.0
    Introduced.

Source Code

This filter is located in GFCommon::replace_variables() in common.php.