Understanding Which Result Template Loads for a Result

To know which search result should use which result template, the Coveo JavaScript Search Framework looks at each result template in the order they are loaded in your search page and selects the first one that fits the result.

To determine how a result can fit your result template, you need to specify a condition on your result template. Not putting a condition on your result template will make it fit every result. This should only be done for the default result template.

You can specify a condition on a result template by using either field value conditions or JavaScript conditions.

You should always have a “default” result template with no data-field- or data-condition attribute, so that any result that match none of the previous boolean expressions can be elegantly displayed.

Such a “default” result template should always be last under a ResultList component. Otherwise, all of your results will be using the default result template.

Choosing the Appropriate Method

You should not include both data-condition and data-field- attributes in the same result template.

The data-field- method was introduced in the 1.2359.7 (March 2017) release of the Coveo JavaScript Search Framework, and is aimed at newer versions and deployments.

The data-condition method is older. It used to be the only way to evaluate result templates in the Coveo JavaScript Search Framework.

Both ways have their own advantages and disadvantages.

Method Advantages Disadvantages
data-field-
(Recommended)
  • Possible to execute inside an environment with strict Content Security Policies
  • Can be parsed and configured correctly by the Interface Editor
  • Less likely to have an unrecoverable configuration error
  • Less flexible
  • Possible that some complex conditions cannot be expressed with it
data-condition
  • Extremely flexible, since it evaluates arbitrary JavaScript boolean expressions
  • Relies on evaluating a JavaScript function, which is not allowed by stringent Content-Security-Policies. This could be considered insecure for some setups (e.g., Salesforce with Lightning Locker enabled), depending on the backend server serving the JavaScript resources
  • Harder to detect faulty logic, since there is more leeway for possible configuration errors
  • Possible to configure with invalid JavaScript syntax, which would cause the Coveo JavaScript Search Framework to become incapable of rendering results

Coveo JavaScript Search Framework 1.2359.7 (March 2017)

To use field value conditions, you need to add one or several data-field-YourFieldName attributes to the script tag of your result template, where YourFieldName is replaced by a field name from your index.

You want to create a result template for your results when their @objecttype field equals Case.

Your result template tag would include the data-field-objecttype="Case" attribute.

This attribute works with one or several values (e.g., data-field-author="Alice,Bob,Charlie") or without any (e.g., data-field-author).

When several values are specified, the result template will fit results that have at least one of the specified values for the specified field.

When a value is not specified, the result template will fit every result that has a value, regardless of what it is, for the specified field.

You can add several data-field- attributes to a single result template script tag. Each new data-field- effectively adds a AND logical operator to the logical expression. A result must thus satisfy each individual data-field- condition in a result template script tag to satisfy the entire expression.

<div class='CoveoResultList'>
  // This result template applies when the '@filetype' field of the current result matches 'Image'.
  <script id='myImageResultTemplate' class='result-template' type='text/html' data-field-filetype='Image'>
    // [ ... ] Result template code [ ... ]
  </script>
  // This result template applies when the '@filetype' field of the current result matches either 'doc' or 'pdf'.
  <script id='myDocumentResultTemplate' class='result-template' type='text/html' data-field-filetype='doc,pdf'>
    // [ ... ] Result template code [ ... ]
  </script>
  // This result template applies when the '@filetype' field of the current result matches 'html' and its '@source' field matches 'mySource'.
  <script id='myHTMLResultTemplate' class='result-template' type='text/html' data-field-filetype='html' data-field-source='mySource'>
    // [ ... ] Result template code [ ... ]
  </script>
  // This result template applies when the '@sfid' field of the current result contains any value (i.e., if it is not 'null').
  <script id='mySFIDResultTemplate' class='result-template' type='text/html' data-field-sfid>
    // [ ... ] Result template code [ ... ]
  </script>
  // If none of the previous result templates could apply to the current result, other result templates will be evaluated in order of appearance.
  // [ ... ] Other result templates with 'data-field-...' attributes. [ ... ]
  // The "default" result template applies when none of the preceding result templates could apply to the current result.
  // The default result template should always be at the end of your result list. Otherwise, it will be applied for all your results.
  <script id='myDefaultResultTemplate' class='result-template' type='text/html'>
    // [ ... ] Result template code [ ... ]
  </script>
</div>

The data-field- attributes of a result template combine to form a boolean expression which is evaluated with the current result as a context. This means that data-field-somefield refers to the @somefield field of each result.

Using JavaScript Conditions

To use JavaScript conditions, you need to add the data-condition attribute to the script tag of your result template. The JavaScript expression entered in that attribute will then be evaluated for any given result to determine whether that result should use this result template.

Most result templates rely on field values for a given result. Those field values are stored in the raw section of the result. This means that, when entering a field for your condition, you need to use the format raw.yourField.

<div class='CoveoResultList'>
  // This result template applies when the 'filetype' field value of the result is 'image'.
  <script id='myFirstResultTemplate' class='result-template' type='text/html' data-condition='raw.filetype=="image"'>
    // [ ... ] Result template code [ ... ]
  </script>
  // This result template applies when the 'price' field value of the result is larger than 500.
  <script id='mySecondResultTemplate' class='result-template' type='text/html' data-condition='raw.price>500'>
    // [ ... ] Result template code [ ... ]
  </script>
  // When none of the previous result templates could apply to the current result, other result templates will be evaluated in order of appearance.
  // [ ... ] Other result templates with 'data-condition' attributes. [ ... ]
  // The "default" result template applies if none of the preceding result templates could apply to the current result.
  // The default result template should always be at the end of your result list. Otherwise, it will be applied for all your results.
  <script id='myDefaultResultTemplate' class='result-template' type='text/html'>
    // [ ... ] Result template code [ ... ]
  </script>
</div>

However, you may want a specific result template to apply only to items boosted by a featured results rule (see Adding and Managing Query Pipeline Featured Results). You can achieve this by specifying the rule using the data-condition attribute as follows:

data-condition="isTopResult==true"

You can also add the PromotedResultsBadge component to your result template to help end-users easily identify promoted search results (see Adding Promoted Results Badges).

What’s Next?

Once you have specified a condition for your result template, you will usually want to customize its appearance to distinguish it from other search results.