Template Tags

There are several settings in Participants Database and its add-ons that use a template. For example, settings that define an email body. These templates are designed to use the values from the current record, so that when they are displayed, the values form the record are incorporated into the content.

To show content from the record, “template tags” are used (these are sometimes also called “placeholders” or “placeholder tags” or “value tags”). The template tag to show a value from a field in the record is the name of the field (not its title!) enclosed in brackets. For example, to show the user’s first name, you could use this tag: [first_name]

This is a super-simple approach, and it’s automatic: the tag is replaced with the field’s display value, so that it can be included as content in the final rendering of the template. For example, if an image-upload field is included as a template tag, it will show the image. If a field that has several values stored, it will show those values as a comma-separated list so that it will look right in the final content.

Note that under some circumstances, you can run into trouble if you are using a field name that is the same as the name of a defined shortcode (for example: “gallery”). Most of the time, it’s not a problem, the plugin attempts to avoid the issue, but this is something to be aware of.

Some Settings That Use Template Tags

  • Signup Response Email
  • Signup Response Email Subject
  • Signup Thanks Message
  • Signup Notification Email
  • Signup Notification Email Subject
  • Record Update Notification Email
  • Record Update Email Subject

…and there are several more. Any time there is a communication that might need to include information from the record, template tags are available for that purpose.

The Email Expansion Kit add-on makes extensive use of template tags in it’s email templates.

Additional Template Tag Values: Titles, Raw Value

For each template tag that represents a field’s value, there are two or three additional tags that can be used:

  • [title:{$fieldname}] shows the title of the field. This is passed through translation filters.
  • [value:{$fieldname}] shows the raw value (value without any HTML) of the field. This is useful when you want to set up some special HTML and need a value without tags to plug into the code.
  • [url:{$fieldname}] this tag is only available to file- or image-upload fields, it provides the full URL of the media item. This can be useful for use in custom HTML.

The way these work is {$fieldname} is replaced by the name of the field…for example, to show a field with its title, you could use something like this in your template:

<p>[title:first_name]: [first_name]</p>

Or, to show an image or file as a download link:

<p><a href="[url:photo]">[value:photo]</a></p>

Something like that would make it possible to do things like add tracking variables to the URL so you can use your analytics to know where people are clicking on download links.

Custom Tags

It’s also possible to create your own custom tags. You will need to know some php and be familiar with how to set up a filter handler in WordPress to create your own tags, but it is not complicated.

The filter to use is pdb-tag_template_data_before_replace and what will be passed in is an array that is indexed by the tag string with the value as what that tag will be replaced with. You can add any kind of specialized tag this way.

For a simple example, let’s say you want to use a tag that shows the person’s full name. You could set that up with a filter handler like this:

<?php
add_filter( 'pdb-tag_template_data_before_replace', function ($tag_list) {
      $tag_list['fullname'] = $tag_list['first_name'] . ' ' . $tag_list[last_name];
      return $tag_list;
} );
?>

Then in your template you could use [fullname] to show the person’s full name. The $tag_list array will have a lot of info in it, including the record ID, to use in building your custom tag.