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
Legacy Rich Text (v1) 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().
Check out the Update a Result Card to Support Rich Text help article for step-by-step instructions on display rich text on a result card, including how to use the rich text formatter.
Wherever you’re using a Legacy Rich Text (v1) field, you must use this formatter in order to render correctly on the page.
- To display rich text, the
formatRichTextfunction 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
formatRichTextfunction accepts two additional parameters to make this possible: the character limit and the string used to truncate the rich text.
Below are the parameters used in the rich text formatter:
| 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. Only available on Theme v1.29 or above. | No | Null |
suffix |
String | The text used to truncate the RTF. Only available on Theme v1.29 or above. | No | … |