bookmark_bordergform_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

    The current form.

  • $entry Entry Object

    The current entry.

  • $url_encode boolean

    Whether or not to encode any URLs found in the replaced value.

  • $esc_html boolean

    Whether or not to encode HTML found in the replaced value.

  • $nl2br boolean

    Whether or not to convert newlines to break tags.

  • $format string

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

Examples

1. 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' );
    $text = str_replace( $custom_merge_tag, $download_link, $text );

    return $text;
}

2. Replace {entry_time}

This example replaces a custom merge tag with the entry date and time.

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

3. 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 );

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

5. Replace {paypal_link}

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

6. 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 );

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

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

9. 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 ) {
	$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'] );

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

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.