gform_custom_merge_tags

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

Description

The gform_custom_merge_tags filter allows you to add additional merge tags that you have defined to the drop down menus where merge tags are available. Important: This filter only adds the merge tags to the drop down menus; it does not create them. They must have already been created using the gform_replace_merge_tags filter.

Usage

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

The JavaScript version filters 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 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 the 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 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?

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

The PHP filter is located in:
GFCommon::get_merge_tags() in common.php
GFCommon::insert_calculation_variables() in common.php

The JavaScript filter is located in assets/js/src/admin/components/merge-tags/utils.js