Link Formats

utm.codes makes it easy to add custom link element formatting using the WordPress Plugin API. The filter callback function receives both the value and the link element name allowing for selective application of your custom formatting.

Filter Tag: utmdc_element_pre_filters

Applied before any enabled default utm.codes filters to allow for customization of the value while maintaining default filter formats.

Example Usage

/**
 * Replace empty campaign names with the site name.
 * Note: Uses pre filter hook to ensure default filters are applied to the value for consistent formatting.
 */
add_filter(
	'utmdc_element_pre_filters',
	function( $value, $element ) {
		$is_campaign = ( 'utm_campaign' === $element );
		$blank_value = ( '' === $value );

		if ( $is_campaign && $blank_value ) {
			$value = get_bloginfo( 'name', 'display' );
		}

		return $value;
	},
	10,
	2
);

Filter Tag: utmdc_element_post_filters

Applied after any enabled default utm.codes filters, the returned value will be saved.

Example Usage

/**
 * Add a prefix of YearQuarter to Campaign Names.
 * Note: comparison is case insensitive to account for use of default lowercase filter.
 */
add_filter(
	'utmdc_element_post_filters',
	function( $value, $element ) {
		$prefix      = ( date( 'Y' ) . 'Q' . ceil( date( 'm' ) / 3 ) );
		$is_campaign = 'utm_campaign' === $element;
		$has_prefix  = strtolower( substr( $value, 0, 6 ) === strtolower( $prefix ) );

		if ( $is_campaign && ! $has_prefix ) {
			$value = $prefix . $value;
		}

		return $value;
	},
	10,
	2
);