gform_replace_merge_tags

Description

Use this filter to replace custom merge tags.

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. The code first searches for the merge tag in the $text. If found, it proceeds to retrieve the value which should 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, you can also 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 {transaction_id}

This example replaces a custom merge tag with the payment transaction id.

add_filter( 'gform_replace_merge_tags', function ( $text, $form, $entry, $url_encode ) {
	$merge_tag = '{transaction_id}';

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

	return str_replace( $merge_tag, $url_encode ? urlencode( $transaction_id ) : $transaction_id, $text );
}, 10, 4 );

Note: Since Gravity Forms 2.1.1.11 you don’t even have to use this filter to output the transaction_id or other payment details for add-ons using the add-on framework. You can use the entry merge tag with the modifier for the property you want to output. e.g. {entry:transaction_id}

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 replaces 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 id of the user which was created 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 created 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 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 a 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 );

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.