Translating Fields to the Coveo Format in Coveo for Sitecore Hive Framework

This page explains how to translate fields in the Coveo format for a Coveo for Sitecore Hive Framework page.

Why Translate Fields

When working with Coveo for Sitecore, you need to translate your fields into the Coveo format that matches the index you are using. Sitecore field names are encoded by default before being saved in the Coveo index. The reason is to avoid field collision when multiple Sitecore instances are indexed in the same Coveo index (see Adding External Fields in Coveo for Sitecore). 

For instance, the field haslayout in the coveo_master_index might look like fhaslayout83756, and the same field in the coveo_web_index might look like fhaslayout34950.

All field names receive prefix f and a numerical suffix made of one to five digits. Spaces are converted to z32x. Letters x and z are converted to z120x and z122x. See examples below.

You have a Sitecore field called jaguar. Since it is used in more than one site, it will be translated to fjaguar34950 in one source and fjaguar83756 in an other.

You also have a Sitecore field called compatible renderings, which is encoded as fcompatiblez32xrenderings34950 in the coveo_web_index, and index name, which becomes findez120xz32xname34950 in that same index.

Thus, the way the field is translated depends on the current context:

  • Master context
  • Web context
  • Web site context among multiple sites

Translating your fields ensures that the correct field is resolved depending on the context.

This context is provided by the CoveoForSitecoreContextcomponent.

How to Translate Fields 

Given the following markup:

<div class="CoveoFacet" data-field="@myfield"></div>

The end result that you want to have is:

<div class="CoveoFacet" data-field="@fmyfield2053"></div>

This value should not be hardcoded since it could change between contexts.

The following sections present and describe two ways to leverage the context and still achieve this result. 

Using a Prebinding Helper Method 

Coveo for Sitecore Hive Framework introduces a new concept to transform markup values using the current context.

The fieldTranslator prebinding method allows for translating the field directly. Given the example from the How to Translate Fields section, you could use prebinding: 

<div class="CoveoFacet" data-field="@myfield" data-prebind-field="fieldTranslator"></div>

At run-time, when initializing the Search Interface, you should get the following markup:

<div class="CoveoFacet" data-field="@fmyfield2053" data-prebind-field="fieldTranslator"></div>

The fieldTranslator prebinding method can be used with any attribute that is a field.

This approach is the recommended one to translate fields easily.

If the attribute requires the @ character, you must put it in the original attribute value.

Using JavaScript

Coveo for Sitecore provides a static helper method meant to translate fields. Try applying the following code: 

CoveoForSitecore.Context.fields.toCoveo("myfield");

Given the example from the How to Translate Fields section, you should add a unique ID like the following code:

<div id="myfacet" class="CoveoFacet"></div>

You can then get a reference to this element using this ID with a simple JavaScript call:

<div id="myfacet" class="CoveoFacet"></div>
<script>
    var myFacetElement = document.getElementById("myfacet");
</script>

Then, set a value using the following code:

<div id="myfacet" class="CoveoFacet"></div>
<script>
    var myFacetElement = document.getElementById("myfacet");
    myFacetElement.dataset.field = CoveoForSitecore.Context.fields.toCoveo("@myfield");
</script>

When the code is executed, it should give the same end-result as the other method:

<div id="myfacet" class="CoveoFacet" data-field="@fmyfield2053"></div>

However, this approach requires a way to retrieve the original element, like an ID.

This approach is recommended if you have complex logic to compute the attribute.

For instance, you might want to build a complete query expression instead of a simple field value. You can create your expression like the following example:

<div id="mycustomexpression" class="CoveoForSitecoreFilterExpression"></div>
<script>
    var myCustomExpressionElement = document.getElementById("mycustomexpression");
    myFacetElement.dataset.scFilterExpression = CoveoForSitecore.Context.fields.toCoveo("myfield") + "==1";
</script>

This will output the following attribute:

<div id="mycustomexpression" class="CoveoForSitecoreFilterExpression" data-sc-filter-expression="@fmyfield2053==1"></div>

Prefer the Prebinding Helper method when possible.