Skip to main content
Print

Adding your own placeholder tags

Updated

Three filters let a developer add placeholder tags to the template editor, or change what the built-in tags are replaced with. This article describes them and gives a complete example.

The filters

Filter Arguments Controls
hpwe_placeholder_tags array $tags The tags listed in the template editor, as tag => description.
hpwe_placeholder_replacements array $replacements, WC_Order $order, bool $html The values used when an email is sent for a real order, as tag => value.
hpwe_placeholder_sample_replacements array $replacements, bool $html The values used by Preview in Browser and Send Test Email, as tag => value.

$html is true when the values go into the email body or heading, and false for the subject line.

Example: a shipping method tag

This adds a {shipping_method} tag. Put the code in a small custom plugin or in your child theme’s functions.php file.

add_filter( 'hpwe_placeholder_tags', function ( $tags ) {
	$tags['{shipping_method}'] = 'Shipping method chosen at checkout';
	return $tags;
} );

add_filter( 'hpwe_placeholder_replacements', function ( $replacements, $order ) {
	$replacements['{shipping_method}'] = $order->get_shipping_method();
	return $replacements;
}, 10, 2 );

add_filter( 'hpwe_placeholder_sample_replacements', function ( $replacements ) {
	$replacements['{shipping_method}'] = 'Flat rate';
	return $replacements;
} );

The first filter makes the tag appear in the editor, both in the rows of tags under the fields and in the Available Placeholder Tags box. The second supplies the real value, and the third supplies a value for previews and test emails, so that they don’t show the raw tag.

Rules for values

  • Return plain text. The plugin escapes every value itself before it goes into an HTML email, so markup in a value is shown as text.
  • Tags are matched exactly, curly brackets included, so {Shipping_Method} is not the same tag as {shipping_method}.
  • A tag with no entry in the replacements is left in the email as it was typed. An entry whose value is empty removes the tag, as happens with the example above for an order without shipping.
  • To change a built-in tag, overwrite its key in hpwe_placeholder_replacements, for example to put a # in front of {order_number}.
  • A tag whose value is a web address starting with http:// or https:// also works as the address of a link made with the editor’s link button, which puts http:// in front of the tag.
Table of Contents