- Creating and Making Use of a New Result Template
- Editing the Content of a Result Template
- Creating a Simple Listing Page
- Applying Filtering and Ranking Rules
- Routing Search Queries to Query Pipelines
- Inserting and Configuring a Global Search Box
- Inserting and Customizing a Distance Resources Component
- Configuring Custom Ranges for a Date Range or Numeric Range Facet
- Inserting Custom Components in an Existing Search Interface
- Integrate the Search Interface in an Existing Page
- Translating Fields to the Coveo Format
- Overriding Coveo for Sitecore Hive Initialization Options
- Duplicating a Coveo for Sitecore Component to Modify Its HTML
- Creating a Custom Hive Component - Multi-Sort Tutorial
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
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 is not 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. Refer to the
Coveo.SearchProvider.config section of Upgrading from August 2018 (4.1.518.18) to September 2018 (4.1.590.21) for instructions on how to set the default field translation behavior.
When working with Coveo for Sitecore, you might want to translate your fields into the Coveo format that matches the index you are using. Field translation avoids field name collisions 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 have a name like
fhaslayout83756, and the same field in the
coveo_web_index might be named
All translated field names receive prefix f and a numerical suffix made of one to five digits. Spaces are converted to
z are converted to
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
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 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 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.
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>
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.
Coveo for Sitecore provides a static helper method meant to translate fields. Try applying the following code:
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>
<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.