gform_replace_merge_tags

Description

Use the gform_replace_merge_tags filter to create your own custom merge tags.

This filter lets you dynamically replace custom merge tags with values from form entries, dynamic data, calculations, site information, user data, or external sources. Look at the examples on this page for a small taste of what is possible.

Usage

add_filter( 'gform_replace_merge_tags', 'replace_custom_merge_tags', 10, 7 );

Parameters

  • $text string

    The current text in which merge tags are being replaced.

  • $form false|Form Object

    False or the current form.

  • $entry false|Entry Object

    False or the current entry.

  • $url_encode boolean

    Whether to encode any URLs found in the replaced value.

  • $esc_html boolean

    Whether to encode HTML found in the replaced value.

  • $nl2br boolean

    Whether to convert newlines to break tags.

  • $format string

    Determines how the value should be formatted. Default is html.

Examples

Replace a custom merge tag

This example demonstrates how to replace a custom merge tag {download_link}. The code first searches for the merge tag in the $text. If found, it retrieves the value that will replace the merge tag and then returns the newly replaced string.

add_filter( 'gform_replace_merge_tags', 'replace_download_link', 10, 7 );
function replace_download_link( $text, $form, $entry, $url_encode, $esc_html, $nl2br, $format ) {
	$custom_merge_tag = '{download_link}';

	if ( strpos( $text, $custom_merge_tag ) === false ) {
		return $text;
	}

	$download_link = gform_get_meta( $entry['id'], 'gfmergedoc_download_link' );

	return str_replace( $custom_merge_tag, $download_link, $text );
}

Replace {entry_time}

This example replaces a custom merge tag with the entry date and time. If you don’t need to customize the output, use the built-in {entry:date_created} merge tag that uses the default yyyy-mm-dd hh::mm::ss format.

add_filter( 'gform_replace_merge_tags', function ( $text, $form, $entry, $url_encode, $esc_html, $nl2br, $format ) {
	$merge_tag = '{entry_time}';

	if ( strpos( $text, $merge_tag ) === false || empty( $entry ) || empty( $form ) ) {
		return $text;
	}

	return str_replace( $merge_tag, GFCommon::format_date( rgar( $entry, 'date_created' ), false, 'Y/m/d' ), $text );
}, 10, 7 );

Replace {entry_notes}

This example replaces a custom merge tag with the entry notes.

add_filter( 'gform_replace_merge_tags', 'replace_entry_notes', 10, 7 );
function replace_entry_notes( $text, $form, $entry, $url_encode, $esc_html, $nl2br, $format ) {
	$merge_tag = '{entry_notes}';

	if ( strpos( $text, $merge_tag ) === false || empty( $entry ) || empty( $form ) ) {
		return $text;
	}

	$entry_notes = '';
	$notes       = RGFormsModel::get_lead_notes( $entry['id'] );

	if ( $notes ) {
		$entry_notes .= "<br><br><strong>Additional Notes</strong><br>";
		foreach ( $notes as $note ) {
			$date        = GFCommon::format_date( $note->date_created, false );
			$entry_notes .= "<em>{$note->user_name} - {$date}</em><br>{$note->value}<br><br>";
		}
	}

	return str_replace( $merge_tag, $entry_notes, $text );
}

This example replaces a custom merge tag with the PayPal link for the feed which was used to process an entry.

add_filter( 'gform_replace_merge_tags', 'replace_paypal_link_merge_tag', 10, 7 );
function replace_paypal_link_merge_tag( $text, $form, $entry, $url_encode, $esc_html, $nl2br, $format ) {
	$merge_tag = '{paypal_link}';

	if ( strpos( $text, $merge_tag ) === false || empty( $entry ) || empty( $form ) || ! function_exists( 'gf_paypal' ) ) {
		return $text;
	}

	$feed = gf_paypal()->get_payment_feed( $entry, $form );
	if ( $feed ) {
		$submission_data = gf_paypal()->get_submission_data( $feed, $form, $entry );
		$url             = gf_paypal()->redirect_url( $feed, $submission_data, $form, $entry );
		$text            = str_replace( $merge_tag, sprintf( "<a href='%s'>Pay by PayPal</a>", $url ), $text );
	}

	return $text;
}

Replace {archive_title}

This example replaces a custom merge tag during form pre-population with the archive title where the form is located.

add_filter( 'gform_replace_merge_tags', function ( $text, $form ) {
	$merge_tag = '{archive_title}';

	if ( strpos( $text, $merge_tag ) === false || ! empty( $form ) ) {
		return $text;
	}

	return str_replace( $merge_tag, get_the_archive_title(), $text );
}, 10, 2 );

Custom Date Merge Tag

This example shows how you can define a custom merge tag to return the current date in your desired format.

add_filter( 'gform_replace_merge_tags', function ( $text, $form, $entry, $url_encode, $esc_html, $nl2br, $format ) {
	$merge_tag = '{custom_date}';

	if ( strpos( $text, $merge_tag ) === false ) {
		return $text;
	}

	$local_timestamp = GFCommon::get_local_timestamp( time() );
	$local_date      = date_i18n( 'Y-m-d', $local_timestamp, true );

	return str_replace( $merge_tag, $url_encode ? urlencode( $local_date ) : $local_date, $text );
}, 10, 7 );

Replace {user_id}

This example replaces a custom merge tag with the user’s ID, which was retrieved from the current entry.

add_filter( 'gform_replace_merge_tags', 'replace_user_id_merge_tag', 10, 3 );
function replace_user_id_merge_tag( $text, $form, $entry ) {
	$merge_tag = '{user_id}';

	if ( strpos( $text, $merge_tag ) === false || empty( $entry ) || empty( $form ) || ! function_exists( 'gf_user_registration' ) ) {
		return $text;
	}

	$user_id = gf_user_registration()->get_user_by_entry_id( $entry['id'], true );

	return str_replace( $merge_tag, $user_id, $text );
}

Replace {username}

This example replaces a custom merge tag with the username of the user which was retrieved from the current entry.

add_filter( 'gform_replace_merge_tags', function ( $text, $form, $entry ) {
	GFCommon::log_debug( __METHOD__ . '(): Running snippet for custom {username} merge tag.' );
	$merge_tag = '{username}';

	if ( strpos( $text, $merge_tag ) === false || empty( $entry ) || ! function_exists( 'gf_user_registration' ) ) {
		return $text;
	}

	/** @var WP_User $user */
	$user = gf_user_registration()->get_user_by_entry_id( $entry['id'] );
	GFCommon::log_debug( __METHOD__ . "(): user_login for entry id {$entry['id']} is {$user->user_login}" );

	return str_replace( $merge_tag, $user->user_login, $text );
}, 10, 3 );

Replace a custom merge tag with a value from a BuddyPress profile field

This example replaces a custom merge tag with the value obtained from a custom BuddyPress profile field of type Text labeled as BP Text in BuddyPress.

// BuddyPress custom merge tag
add_filter( 'gform_replace_merge_tags', function ( $text, $form ) {
	$merge_tag = '{bpfield_bptext}'; // Change this to any name you may want to use for your merge tag

	if ( strpos( $text, $merge_tag ) === false || ! empty( $form ) ) {
		return $text;
	}

	$current_user = wp_get_current_user();

	// Change BP Text to the label defined for your field in BuddyPress
	$bp_field_content = bp_get_profile_field_data( array(
		'field'   => 'BP Text',
		'user_id' => $current_user->ID,
	) );

	return str_replace( $merge_tag, $bp_field_content, $text );
}, 10, 2 );

Replace paging merge tags

This example replaces custom merge tags with the source and target pages of multipage forms.

add_filter( 'gform_replace_merge_tags', function ( $text, $form, $entry, $url_encode, $esc_html, $nl2br, $format ) {
	$merge_tag_1 = '{source_page_number}';
	$merge_tag_2 = '{target_page_number}';

	if ( strpos( $text, $merge_tag_1 ) === false && strpos( $text, $merge_tag_2 ) === false ) {
		return $text;
	}

	$source_page = GFFormDisplay::get_source_page( rgar( $form, 'id' ) );
	$text        = str_replace( $merge_tag_1, GFCommon::format_variable_value( $source_page, $url_encode, $esc_html, $format, $nl2br ), $text );

	$target_page = GFFormDisplay::get_target_page( $form, $source_page, array() );

	return str_replace( $merge_tag_2, GFCommon::format_variable_value( $target_page, $url_encode, $esc_html, $format, $nl2br ), $text );
}, 10, 7 );

Replace multiple merge tags in one function

This example shows how to replace multiple custom merge tags with information about the current site using WordPress functions.

add_filter( 'gform_replace_merge_tags', function ( $text, $form, $entry, $url_encode, $esc_html, $nl2br, $format ) {

   $custom_merge_tags = array(
      '{site_url}'  => get_site_url(),
      '{site_name}' => get_bloginfo( 'name' )
   );
    
   return str_replace( array_keys( $custom_merge_tags ), array_values( $custom_merge_tags ), $text);

}, 10, 7 );

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

apply_filters( 'gform_replace_merge_tags', $text, $form, $entry, $url_encode, $esc_html, $nl2br, $format )

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