gform_merge_tag_data

• Description
• Usage
• Parameters
• Examples
• Provide custom data.
• Add entry creator data.
• Placement
• Source Code

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

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”

Examples

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

Add entry creator data.

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

Placement

This code can be used in the functions.php file of the active theme, a custom functions plugin, a custom add-on, or with a code snippets plugin.

See also the PHP section in this article: Where Do I Put This Code?

Source Code

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