Using Result Template Helpers

While developing your own result templates, you will most likely need to use the FieldValue component, which displays the value of the field of the displayed result.

When using a FieldValue component, you might want to adapt the way those field values are displayed to better suit your needs.

To this end, you can use the helpers available with the Coveo JavaScript Search Framework (see ICoreHelpers).

The helper functions can be used either with HTML or Underscore templates.

You want to display the value of your @edition field in your result template. However, you know the value for this field can be long, and want to ensure that it does not exceed 30 characters when presented in your result template.

To do that, you decide to use the shorten helper function.

  • Using HTML templates:
<div class="CoveoFieldValue" data-field="@edition" data-helper="shorten" data-helper-options-length="30">
  • Using Underscore templates:
<%=shorten(edition, 30)%>

Creating Custom Result Template Helpers

If standard result template helpers do not meet your needs, you may want to implement your own. This section explains how to create, register, and use custom result template helpers.

  1. Register your helper:

     Coveo.TemplateHelpers.registerTemplateHelper("<HELPER_NAME>", (value, options) => {
       // `<HELPER_NAME>` is a unique name for your custom helper.
       // `value` is the field value.
       // `options` is an object.
       // The function must return a string or template string.
     });
    
  2. Call your helper from a FieldValue component:

     <div class="CoveoFieldValue"
       data-field="<FIELD_NAME>"
       data-helper="<HELPER_NAME>"
       data-helper-options="{ optionA: 'Value A', optionB: 'Value B', optionN: 'Value N' }">
     </div>
    

    or in an Underscore template (see Using Underscore Result Template):

     <%= <HELPER_NAME>(<FIELD_NAME>, {optionA: 'Value A', optionB: 'Value B', optionN: 'Value N'}) %>
    

    If you configure your template helper to return an HTML element, the htmlValue option of a FieldValue component must be true. Otherwise, the value returned by the template helper renders as text rather than as an HTML element.

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

     Coveo.TemplateHelpers.registerTemplateHelper("temperatureDisplay", function(temperature) {
       switch(true) {
         case (temperature < 32):
           return 'freezing';
         case (temperature < 64):
           return 'cold';
         case (temperature < 77):
           return 'warm';
         case (temperature < 86):
           return 'hot';
         default:
           return 'scorching';
       }
     })
    
     <div class="CoveoFieldValue"
       data-field="@temperature"
       data-helper="temperatureDisplay">
     </div>
    
  2. You want to include a phone number on result list items. When end users using mobile devices click on this number, their phone application opens and dials the number.

     Coveo.TemplateHelpers.registerTemplateHelper("phoneNumber", function(number) {
       return `<a href="tel:${number}">${number}</a>`
     })
    
     <div
       class="CoveoFieldValue"
       data-field="@mobilenumber"
       data-helper="phoneNumber"
       data-html-value="true">
     </div>
    
  3. You want to output a <span> element with a certain width, height, and border radius (e.g., 25px width / height and 50% border-radius to output a circle), and use the @color value as the background-color

     Coveo.TemplateHelpers.registerTemplateHelper("textStylist", (value, options) => {
       var 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>`
     });
    
     <div class="CoveoFieldValue"
       data-field="@color"
       data-helper="textStylist"
       data-helper-options="{size: 'medium', shape: 'circle'}"
       data-html-value="true" >
     </div>