Using Custom Format Tags for Calculation Fields

Calculation Fields in Participants Database provide a way to generate field values based on data in the record. A prime example is the “age” field, which shows a person’s age based on their birth date and calculated against the current date. Another example would be a field that shows an average value from a list of values in the record.

Calculation fields use a calculation template to set up the calculation that is performed and the final part of that template is the “format” tag. This tag formats the final value of the calculation either for storage or for display.

Making a Custom Format Tag

It is possible to create your own format tags, and doing so can give you a lot of power to present the specific information your site works with in more readable or more informative ways.

To define a custom format tag, you need to use primarily the pdb-calc_field_format_tag_{$tag} filter. This filter is called when the named tag is found in the calculation template. It works very simply: the raw value comes in to the filter and the formatted value is returned.

A secondary filter to use is the pdb-display_only_format_tag_{$tag} filter. This filter expects a true/false value returned, and what it does is set the mode of the format tag. Format tags may work in one of two ways: either to format the value that is going to the database, or to format the stored value for display. In the latter case, this filter should be given a true.

Our Example Plugin

To show how this can work, I’ve written a simple plugin that takes the person’s age and shows the number of months if they are less than 1 years old. It also shows the the years and months if the person is less than 3 years old, and then for those over 3 years of age, ony the number of years is shown.

The “age” field is a Numeric Calculation type field that calculates the person’s age based on their birth date and the current date. You must have a birth date field (named “birthdate” here) that holds the date of birth in a “date” type field. Here is a screenshot of that field configuration:

The calculation stores the age as a timestamp, and then the [?years_or_months] tag gets the years and months information from that stored value when the field is displayed. Since the display will potentially show two values along with things like punctuation and text, it must be a “display only” field.

Here is the example plugin code, annotated to explain what it does.

To make you own custom tag, you’ll need to set the name of the tag on this line:

$tag = 'years_or_months';

This is the text that will be in the brackets. When the tag is encountered, the incoming value is converted to the desired display by the PDb_custom_format_tag::custom_tag_value() method. You will need to modify this method to get the specific display you want for your custom tag.

With a little php knowledge, you can expand this plugin to define multiple custom tags.