Use custom result template helpers

This is for:

Developer

This article explains how to create your own custom result template helpers if the prebuilt helpers that are available with the JavaScript Search Framework don’t meet your needs.

Creating custom template helpers

Before you can use a custom result template helper, you must register it in the same script tag in which you initialize your search interface:

document.addEventListener("DOMContentLoaded", () => {
  // ...
  document.addEventListener("afterInitialization", () => {
    Coveo.TemplateHelpers
       .registerTemplateHelper("<NAME>", (value, options) => {
        // ...Helper function implementation...
    });
  });
  // ...
  Coveo.init(document.body);
})

where <NAME> is a unique name for your custom helper.

When the helper function is invoked, the value parameter is set to the field value to process. If specified, the options argument is a key-value store of customization options to pass to the helper.

The function must return a string or template string.

Once your helper is registered, you can call it using an HTML template or an Underscore template.

In the following HTML template example, the template helper is invoked with the current value of <FIELD_NAME> as a first argument, and the data-helper-options object as a second argument:

<div class="CoveoFieldValue"
     data-helper="<NAME>"
     data-field="<FIELD_NAME>"
     data-helper-options="{ 'OptionA': 'ValueA', 'OptionB': 'ValueB' }">
</div>

If you configure a helper to return an HTML string, you must set the htmlValue option of the FieldValue component to true (that is, data-html-value="true"). Otherwise, the value returned by the helper renders as text rather than an HTML string.

In an Underscore template, you would use a line of code like the following to invoke your helper:

<%= <NAME>(raw.<FIELD_NAME>, {optionA: 'Value A', optionB: 'Value B'}) %>

Sample use cases

Example 1

You want to output a qualitative string value based on the @temperature field (expressed in °F).

Register the helper:

Coveo.TemplateHelpers.registerTemplateHelper("temperatureDisplay", (temperature) => {
    if (temperature < 32) return "freezing";
    if (temperature < 64) return "cold";
    if (temperature < 77) return "warm";
    if (temperature < 86) return "hot";
    else return "scorching";
})

Call your helper:

<div class="CoveoFieldValue"
     data-field="@temperature"
     data-helper="temperatureDisplay">
</div>

Example 2

You want to include a phone number in result list items. When end users who are using mobile devices tap on this number, their phone application opens and dials the number.

Register the helper:

Coveo.TemplateHelpers.registerTemplateHelper("phoneNumber", function(number) {
    return `<a href="tel:${number}">${number}</a>`
})

Call your helper:

<div class="CoveoFieldValue"
     data-field="@mobilenumber"
     data-helper="phoneNumber"
     data-html-value="true">
</div>

Example 3

You want to output a <span> element with a certain width, height, and border radius (for example, 25px width/height and a 50% border-radius to output a circle), and use the @color value as the background-color.

Register the helper:

Coveo.TemplateHelpers.registerTemplateHelper("textStylist", (value, options) => {
    let style;
    if (options.shape === 'circle') {
    style = "border-radius:50%;";
    }
​
    switch(options.size) {
      case "small":
      style += "width:15px;height:15px;";
        break;
      case "medium":
      style += "width:25px;height:25px;";
        break;
      case "large":
      style += "width:35px;height:35px;";
        break;
      default:
        break;
    }
​
    return `<span style="${style} background-color:'${value}'"></span>`
});

Call your helper:

<div class="CoveoFieldValue"
     data-field="@color"
     data-helper="textStylist"
     data-helper-options="{size: 'medium', shape: 'circle'}"
     data-html-value="true">
</div>