gform_custom_merge_tags

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

Placement

Your code snippet can be placed in an HTML field on your form or in a theme custom JavaScript file.

See also the JavaScript/jQuery section in this article: Where Do I Put This Code?

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