THIS IS ARCHIVED DOCUMENTATION

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

This is for:

Developer System Administrator

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

Why Translate Fields

Coveo for Sitecore 4.1 (September 2018)

Translating Sitecore field names to the Coveo field name format to avoid field name collisions is no longer necessary. The new and recommended approach is to avoid field name translation as much as possible.

Consequently, since the September 2018 version of Coveo for Sitecore 4.1, field name translation isn’t applied by default on fresh installs of the software. This default behavior is driven by the <setting name="Coveo.Indexing.PreferSourceSpecificFields" value="false" /> setting in the Coveo.SearchProvider.config file. The default behavior can be overridden on a field-by-field basis using the isSourceSpecific parameter (see Understanding The Coveo Search Provider Configuration File).

If you have upgraded from a pre-September 2018 version of Coveo for Sitecore 4.1 to the September 2018 version (or later), the new default field name translation behavior was not forced upon you. Hence, your instance of Coveo for Sitecore might currently be translating all (or nearly all) Sitecore fields. We strongly suggest you implement the new default field translation behavior, if you haven’t already done so. See the Coveo.SearchProvider.config section of Upgrading from August 2018 to September 2018 for instructions on how to set the default field translation behavior.

Coveo for Sitecore 4.1 (September 2018)

When working with Coveo for Sitecore, you might want to translate your fields into the Coveo format that matches the index you’re using. Field translation avoids field name collisions when many Sitecore instances are indexed in the same Coveo index (see Adding External Fields in Coveo for Sitecore).

For example, the field haslayout in the coveo_master_index might have a name like fhaslayout83756, and the same field in the coveo_web_index might be named fhaslayout34950.

All translated 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’s 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.

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

  • Master context
  • Web context
  • Web site context among many sites

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

This context is provided by the CoveoForSitecoreContext component.

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 shouldn’t 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’s 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 example, 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.