By default, Pages will show your custom fields as badges in the listing and record views, and when creating a field you can choose a color and some basic positioning options. For many of your uses, this may be sufficient, but for more advanced usage Pages allows you to set up custom field formatters that take the raw data and display it however you wish. We're going to use field formatters for each of our custom fields so we can control exactly how they look.
Field formatters expose both the raw and formatted field data to you, enabling you to write your own HTML to generate the output of the field. They can be simple, as most of ours will be, or as complex as you need.
The listing and record views can each have a different formatting, which will be useful in many cases (although for the way we display our Release Notes, we won't be using the display versions).
Field formats make the following variables available:
-
$label
Contains the field label, which is the name you entered for the field (e.g. "Release date") -
$value
Contains the processed field value. For example, if you have a select field, this variable contains the text of the value, not the key. -
$formValue
In contrast to the above, this contains the raw form value. For select fields it will be the key, for Yes/No fields it will be a simple boolean value, etc.
In situations where HTML is in a value, you may need to append |raw to the variable to have it correctly parsed.
Be very careful using the |raw output method. By bypassing escaping of HTML characters, you can open your site to security problems when displaying user-generated content.
We're going to add a custom formatter for our Security Release field, which if you recall shows a red warning triangle when we set the field to Yes.
To start, head over to the field listing page for our database, and click the edit icon next to the Security Release field. On the Display tab, we want to change the Listing View Format to Custom. This will show an editor where we'll enter our HTML. This is the HTML we will use:
{{if $formValue == "1"}}<span class='ipsType_large ipsType_negative ipsPos_right cRelease_security' data-ipsTooltip title='This is a security release'><i class='fa fa-warning'></i></span>{{endif}}
Let's review what is happening here. The opening HTML logic {{if $formValue == "1"}} is simply checking the value of the field. Since this is a Yes/No field, the raw form value is either 1 or 0. We only want to show the security release icon when this field is set to Yes, so if the form value is 0, it simply skips over this logic and shows nothing. Inside the {{if}} we have some simple HTML that shows a red triangle icon (see our CSS framework guides for information on the classnames). We've also added a custom classname cRelease_security that we'll use when we create our own custom CSS later
Another field we'll format is the Release Date field. This field shows a date if set, or "In Development" if no date has been set. As before, set the Listing View Format to Custom, and use this HTML:
{{if $formValue}}Released {$value}{{else}}<span class='ipsType_light'><em>In Development</em></span>{{endif}}
What we're doing here is checking if there's any form value - if there is, we know a date has been chosen, and we display the processed version contained in $value. If there isn't, then after the {{else}} we show the "In Development" text inside a span.
Here's the HTML for the other fields:
Current Release
{{if $formValue == 1}}<span class='ipsBadge ipsBadge_positive' data-ipsTooltip title='This is the most current available release'>Current Release</span>{{endif}}
Beta Release
{{if $formValue == 1}}<span class='ipsBadge ipsBadge_negative' data-ipsTooltip title='A beta is available for this version'>Beta</span>{{endif}}
Additional Information
This field is set to 'No formatting' for the Display template.
With our custom fields set up and formatted correctly, we can move on to templates.
Report Guide