Common Formatters | Yext Hitchhikers Platform
We have a bunch of functions, referred to as formatters, that will make it easy to add more complex formatting to a field. You can see the whole list of Formatter functions available in the theme by navigating to themes > answers-hitchhiker-theme > static > js > formatters.js.
To use a formatter in your data mappings, you’ll just need to add Formatter. to the beginning of the function name.
We’ll walk through the most commonly used formatters here.
emailLink(profile)
This will return the mailto link for the first email in the Emails profile field.
url: Formatter.emailLink(profile)getDirectionsUrl(profile)
We can use this formatter to construct a Get Directions URL to Google Maps based on the address field on an entity.
url: Formatter.getDirectionsUrl(profile)joinList(list, separator)
This is an incredibly helpful formatter that will return a list field on an entity with whatever separator you indicate. For example, on a Jobs card, you could add a subtitle with a comma-separated list for text list field called Positions Available (Part Time, Full Time), and a description with a - separated list of the locations a job is available at (text list field called Locations Available).
If there is no separator defined, it will default to ,.
subtitle: Formatter.joinList(profile.c_positionsAvailable),
details: Formatter.joinList(profile.c_locationsAvailable, "-"),Note: if you are mapping a list field to a section on the card that already accepts a list (ex. Services), you don’t need to use this formatter.
image(profile.field)
The image formatter handles some important behavior for images that help it render appropriately on the card at the right size. It returns an object with a url and alternateText, so you’ll want to specify the URL field when you map this to the image on a template.
To use the image formatter, you’ll use null-checking. Here, we’re checking to see if the Job Photo field is filled out for a Job entity - if it is, we’ll use our formatter and grab the URL returned. Otherwise, we won’t show an image.
image: profile.c_jobPhoto ? Formatter.image(profile.c_jobPhoto).url : null,generateCTAFieldTypeLink(profile.field)
This formatter is essential if you are using a field of type Call To Action.
Because you are able to add different types of links via this field (ex. mailto: for email, tel: for phone, as well as regular URLs), we need a formatter to be able to correctly construct the link for all these use cases.
You’ll see this in the standard card mappings for the links of CTAs.
url: Formatter.generateCTAFieldTypeLink(profile.c_primaryCTA),Rich Text Formatter
Rich text fields are stored in markdown, another markup language (similar to HTML). In order to interpret these fields as HTML that the page can render, we use a function direct from the Search library - formatRichText(). The formatRichText function accepts three parameters: the field to format, the field name to pass to the analytics event, and the target. These instructions apply to anyone on JS version 1.4.0 or higher.
As of Theme 1.29, rich text also supports truncation. The formatRichText function accepts two additional parameters to make this possible: the character limit and the string used to truncate the rich text.
Wherever you’re using a rich text field, you must use this formatter in order to render correctly on the page.
| Parameter | Type | Description | Required | Default |
|---|---|---|---|---|
| fieldName | Field reference | The API name of the field to format | Yes | N/A |
| eventOptionsFieldName | String | Passed as the fieldName to the analytics event. Should be the same as the fieldName specified | No, but strongly recommended | Null |
| target | String or object with keys for each link type(see below) | The target attribute for the href. | No | Null, so will use the browser default of “_self” |
| characterLimit | Integer | The character limit for truncation | No | Null |
| suffix | String | The text used to truncate the RTF | No | … |
Basic Example
An example of a common use case is for FAQ Answer fields, as these all allow rich text formatting by default.
details: profile.answer ? ANSWERS.formatRichText(profile.answer, "answer", linkTarget) : null,Advanced Example
If you want to vary the target depending on the link type, you can use the field c_myRichTextField to set the targets as follows:
- Set any “email” links to target _top (parent frame)
- Set “phone” links to target _self (same window)
- Set “url” links to target _blank (open in a new window)
If “c_myRichTextField” is not populated, fall back to the description field.
details: profile.c_myRichTextField ? ANSWERS.formatRichText ( profile.c_myRichTextField 'c_myRichTextField', { email: '_top', phone: '_self', url: '_blank'}) : profile.description
Rich Text Styling
By default, the following styling will be applied:
- Bold, underline, and italics styling
- Bulleted and numbered lists
You can see an example of all this formatting below:
