gform_custom_merge_tags

• Description
• Usage
• Javascript Version
• Parameters
• Example
• PHP Version
• Parameters
• Example
• Placement
• Since
• Source Code

Description

Allows for the inclusion of custom merge tags wherever merge tag drop downs are generated.

Usage

The gform_custom_merge_tags filter has both a JavaScript version and a PHP version. These are used in different contexts based on how the merge tag selector is presented.

The JavaScript version filter available merge tags shown in selectors for all field settings rendered in the form editor.

gform.addFilter( 'gform_custom_merge_tags', function( mergeTags, formId, fields, elementId ) {
    // do stuff
 
    return mergeTags;
} );

The PHP version filters the merge tag selector used on all other settings pages.

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

Javascript Version

Parameters

• $customMergeTags array
  The custom merge tags.
• $formId string
  The ID of the current form.
• $fields Field Object[]
  An array of fields objects.
• $elementId string
  The ID of the input field.

Example

Allow date and time merge tags to be displayed in merge tag selector for calculations.

gform.addFilter( 'gform_custom_merge_tags', function( customMergeTags, formId, fields, elementId ) {
	if ( elementId != 'field_calculation_formula' ) {
		return customMergeTags;
	}
	fields.forEach( field => {
		const inputType = GetInputType( field );
		const inputLabel = GetLabel( field );
		if ( ['date', 'time'].includes( inputType ) ) {
			customMergeTags.push( {
				value: `{${ inputLabel }:${ field.id }}`,
				label: inputLabel,
			} );
		}
	} );
	return customMergeTags;
} );

PHP Version

Parameters

• $merge_tags array
  The custom merge tags.
• $form_id int
  The ID of the current form.
• $fields Field Object[]
  An array of fields objects.
• $element_id string|int
  The ID of the input field.

Example

add_filter( 'gform_custom_merge_tags', 'custom_merge_tags', 10, 4 );
function custom_merge_tags( $merge_tags, $form_id, $fields, $element_id ) {
	$merge_tags[] = array(
		'label' => 'Download Link',
		'tag'   => '{download_link}',
	);

	return $merge_tags;
}

Placement

This code should be placed in the functions.php file of your active theme.

Since

This PHP filter was added in Gravity Forms version 1.6.2. The javascript version was added in version 2.8.5.2.

Source Code

This filter is located in:
GFCommon::get_merge_tags() in common.php
GFCommon::insert_calculation_variables() in common.php
Javascript filter is located in assets/js/src/admin/components/merge-tags/utils.js