Adding Rich Text | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

• How to use the Search rich text formatter
• How to add rich text fields to your Search experience
• How to style rich text on your Search experience

Search 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.

Changing Cards to Support Rich Text

To add rich text to a card, we’ll need to update the relevant card in several ways. Make sure you’ve forked a card that you can edit at the top-level and you’re not editing a card in the theme itself.

1. Add the rich text formatter to the field that uses rich text.
2. Either disable truncation or update the card to handle RTF truncation, depending on what theme you’re on.
3. Since the rich text formatter converts markdown to HTML, update the Handlebars template to allow the HTML to display on the page.
4. Add optional styling to the rich text.

Rich text is most commonly used for the details section of cards but you can use it with any field you have stored as a Rich Text Field in the Knowledge Graph. Make sure to update that field instead of details which is referenced throughout the rest of this unit.

1. Add Rich Text Formatter to Rich Text Field

You’ll want to use the rich text formatter for the field mapping in the card’s component.js file. Make sure to include null checking as well. Check out the Data Mappings & CTAs unit for a refresher on null checking.

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

Note, If a certain key is not provided, the target will not be set (browser default of _self will be used). In other words, in the more advanced example, you could also leave out phone: ‘_self’ and accomplish the same thing:

details: profile.c_myRichTextField ? 
  ANSWERS.formatRichText(
    profile.c_myRichTextField, 
    'c_myRichTextField',
    { 
      email: '_top', 
      url: '_blank'
    }
  )
  : profile.description

2a. Disable the Show More/Show Less Functionality (Theme 1.28 or below)

If there is HTML in a field, you must remove the show more/show less functionality if you are on Theme 1.28 or below. The risk is that with the truncation, you’d cut off a closing tag (ex. </div>, </p>), which could break the page. Comment out or delete the showMoreDetails object in the component.js file for your card.

// showMoreDetails: {
//   showMoreLimit: 750, // Character count limit
//   showMoreText: 'Show more', // Label when toggle will show truncated text
//   showLessText: 'Show less' // Label when toggle will hide truncated text
// },

2b. Use RTF Truncation: Change showMoreLimit to truncatedDetails (Theme 1.29 or above)

Theme 1.29 added support for the Show More/Show Less functionality with rich text fields. In built-in theme cards that use ANSWERS.formatRichText, the showMoreDetails object was updated to take in a new truncatedDetails property. If you want to use RTF truncation on a previously forked card or on a card you added RTF to, use truncatedDetails in place the of showMoreLimit property for the RTF card showMoreDetails. Your card component.js file will look something like:

return {
   title: profile.name, // The header text of the card
   url: profile.landingPageUrl, // If the card title is a clickable link, set URL here
   ...
   details: profile.richTextDescription ? ANSWERS.formatRichText(profile.richTextDescription, 'richTextDescription', linkTarget) : null, // The text in the body of the card
   // If the card's details are longer than a certain character count, you can truncate the
   // text. A toggle will be supplied that can show or hide the truncated text.
   // Note: If you are using rich text for the details, you should not enable this feature.
   showMoreDetails: {
     truncatedDetails: profile.richTextDescription ? ANSWERS.formatRichText(profile.richTextDescription, 'richTextDescription', linkTarget, 38) : null, // Character count limit
     showMoreText: 'Show more', // Label when toggle will show truncated text
     showLessText: 'Show less' // Label when toggle will hide truncated text
   },
   ...
}

The value for truncatedDetails is similar to details, but passes an additional parameter to ANSWERS.formatRichText: the character count that the rich text content will be truncated at, in this case 38. This character count will ignore all non-text characters, such as HTML tags and formatting. Any string value can be passed into truncatedDetails.

For example if you have the below card details:

The 3 hashbangs at the start and middle will be ignored, as well as the new line symbols. Truncating at 38 characters would result in the below HTML.

By default, an ellipsis is added to the end of the truncated text. This can be customized by adding one more parameter to ANSWERS.formatRichText to specify the suffix.

For example, to remove the ellipsis completely, you could specify a blank string instead:

ANSWERS.formatRichText(profile.richTextDescription, 'richTextDescription', linkTarget, 38, '')

3. Add {{{ }}} to the Details Section in your Handlebars Template

This ensures that the HTML is rendered on the page, instead of printed as-is or escaping the HTML. (See https://handlebarsjs.com/guide/expressions.html#html-escaping.) This is done by default in the built-in faq-accordion card. If you are forking a card, ensure that the fields that use rich text are surrounded by triple braces in the template.hbs file of the card.

<div class="HitchhikerFaqAccordion-detailsText js-HitchhikerCard-detailsText{{#if showExcessDetailsToggle}} js-hidden{{/if}}">
  {{{card.details}}}
</div>

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:

However, there might be some additional styling you want to add - for example, spacing between paragraphs and link styling. Recommended styling is below.

.HitchhikerFaqAccordion-details
{
  p, ul, ol
  {
    margin-bottom: .5rem
  }

  a
  {
    color: var(--yxt-color-brand-primary);
    text-decoration: underline;

    &:hover {
      text-decoration: none;
    }
  }
}