JavaScript Search Framework Result Templates

Result templates determine the format of the individual query results in a search interface. They are embedded within a specific result layout, and a given result template can only apply when its parent result layout is selected.

When a query is successful, each result is rendered according to the first result template whose condition is satisfied by that result.

Using the Prebuilt Result Templates

The JavaScript Search Framework includes several prebuilt result templates for common content types (e.g., Salesforce, Jira, Lithium). You can use these result templates in your search interface by including the templates.js script after the framework script:

<script class="coveo-script" src="https://static.cloud.coveo.com/searchui/v2.7968/js/CoveoJsSearch.Lazy.min.js"></script>
<!-- ... -->
<script src="https://static.cloud.coveo.com/searchui/2.7968/js/templates/templates.js"></script>

Registering and Using Custom Result Templates

To register a custom result template for a given layout, you must embed a script tag in the desired ResultList component.

This tag must have the result-template class, and its type must specify which result template engine to use (i.e., text/html or text/underscore). A custom result template should also have a unique condition (e.g., data-field-documenttype="Video").

  1. Registering a custom List layout result template for PDF files using the HTML result template engine.

    <div class="ResultList" layout="list">
      <script class="result-template" type="text/html" data-field-filetype="PDF">
        <!-- ... -->
      </script>
    </div>
    
  2. Registering a custom Card layout result template for YouTube videos using the Underscore result template engine.

    <div class="ResultList" layout="card">
      <script class="result-template" type="text/underscore" data-field-filetype="YouTubeVideo">
        <!-- ... -->
      </script>
    </div>
    

For each query result, the custom result templates embedded inside the selected result layout (i.e., in the selected ResultList component) are evaluated in the order in which they appear in the markup. The first result template whose condition is satisfied by the result applies. If a result does not satisfy any custom result template conditions, and if the prebuilt result templates are available, then the prebuilt result templates are also evaluated until a condition is satisfied.

If a custom result template does not have a condition, query results will always be considered to satisfy its condition when it is evaluated. You can use such a custom result template as a default template by including it as the last result template in its parent result layout.

Since custom result templates are evaluated before the prebuilt ones, including a custom result template without a condition in a ResultList implies that the prebuilt result templates will never apply for that result layout.

Choosing a Result Template Engine

The JavaScript Search Framework supports two result template engines:

Both result template engines support JavaScript Search Framework result template components. If your use case is fulfilled by a preexisting result template component, you should use it instead of implementing your own custom component or using inline JavaScript.

HTML result templates are strictly based on standard result template CSS classes and JavaScript Search Framework result template components. They can be executed inside environments with strict content security policies (e.g., Salesforce with Lightning Locker enabled).

If needed, you can expand the capabilities of HTML result templates by developing your own custom result template components.

Registering a simple, lightweight HTML result template.

<script id="MyTemplate" type="text/html" class="result-template">
  <div class="coveo-result-frame">
    <div class="coveo-result-row">
      <div class="coveo-result-cell"
         style="width:85px;text-align:center;padding-top:7px;">
        <span class="CoveoIcon"></span>
        <div class="CoveoQuickview"></div>
      </div>
      <div class="coveo-result-cell" style="padding-left:15px;">
        <div class="coveo-result-row">
          <div class="coveo-result-cell">
            <a class="CoveoResultLink" style="font-size:18px;"></a>
          </div>
          <div class="coveo-result-cell"
             style="width:120px;text-align:right;font-size:12px">
            <span class="CoveoFieldValue" data-field="@date"
               data-helper="date"></span>
          </div>
        </div>
      </div>
    </div>
  </div>
</script>

This example renders query results as follows:

Simple HTML result template example

Underscore result templates are extremely flexible because they can execute arbitrary JavaScript code. However, they may not be compatible with, or secure enough for, strict content security policies or setups (e.g., Salesforce with Lightning Locker enabled). Moreover, Underscore result templates can become hard to read and difficult to maintain.

Instead of using Underscore result templates, consider using HTML result templates and developing your own custom result template components.

Registering a simple, lightweight Underscore result template.

<script id='MyTemplate' type='text/underscore' class='result-template'>
    // Use a Coveo helper to format the date and time,
    // referencing the raw.sysdate property of each result.
    <div class="my-date"><%- dateTime(raw.sysdate) %></div>
    // Output the excerpt of the result in a div.
    <div class='my-excerpt'><%= excerpt %></div>
</script>

While reading the Underscore template engine documentation, you may notice that you can modify the delimiters (<% %>) by changing the _.templateSettings object.

However, changing these delimiters can cause issues with the JavaScript Search Framework, as they are used internally. The JavaScript Search Framework offers alternative delimiters ({{ }}), which work the same way as the default delimiters.

This can also be useful when using the JavaScript Search Framework with certain other technologies, such as ASP.NEt or JavaServer Pages, which use the <% %> characters to let the server interpret expressions.

What’s Next?

Learn more about how to use and configure result templates.

Using Custom Icons in Result Templates

Using Result Template Helpers