THIS IS ARCHIVED DOCUMENTATION

Understanding Prebinding Helpers in Coveo for Sitecore Hive

This is for:

Developer System Administrator

This page covers what prebiding is and why Coveo for Sitecore Hive requires it.

For a list of Prebinding Helpers, see Prebinding Helpers List Reference.

Understanding Prebinding Helpers

Prebinding Helpers are methods that are executed before the initialization of the Search Interface.

Those helpers allow you to quickly leverage the current context values in the markup, without requiring JavaScript code.

Coveo for Sitecore Hive uses the helpers for various purposes.

Using a Prebinding Method

The syntax is the following:

<div data-prebind-{ATTRIBUTETOUSE}="{METHODTOAPPLY}"></div>

You can use the fieldTranslator helper method on the field attribute this way:

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

When the Search Interface is initialized, if this div is inside the Search Interface, the fieldTranslator will be applied to the myfield value.

This gives the following result, given by the fieldTranslator method:

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

Conceptually, you can read the prebinding operation like the following: field = fieldTranslator("myfield").

Here is the step-by-step process using the previous example, where the element variable is the HTML element reference for the div:

  • Extract the field from which to pick the value. 
    • In the previous example, data-prebind-field will be applied to the field attribute.
  • Extract the attribute value for field.
    • In the previous example, element.dataset.field returns @myfield.
  • Extract the prebinding method to use.
    • In the previous example, fieldTranslator
  • Apply the prebinding method to the extracted attribute value.
    • In the previous example, fieldTranslator("@myfield").
  • Take the result of this method, and set it back in the markup.
    • In the previous example, fieldTranslator("@myfield") returned @fmyfield2053.
    • This sets element.dataset.field = "@fmyfield2053.

There are many helpers that you can use, but the logic behind the prebinding mechanics remains the same.

Registering Your Own Helper

You can register a custom helper method using the following call:

CoveoForSitecore.Prebiding.registerPrebindHelper("HELPERNAME", handler);

For example, if you choose the name isUserLoggedIn, you can use this method in the markup using:

<div data-prebind-logged-in="isUserLoggedIn"></div>

With the following handler:

function isUserLoggedInPrebindHandler() {
    return myOtherService.isUserLoggedIn();
}
CoveoForSitecore.Prebiding.registerPrebindHelper("isUserLoggedIn", isUserLoggedInPrebindHandler);

After prebinding has been applied and assuming the user is logged in, the markup should look like the following:

<div data-logged-in="true" data-prebind-logged-in="isUserLoggedIn"></div>

The data-logged-in attribute was added because the prebinding method isUserLoggedIn was applied to the logged-in attribute.

You need to register your custom prebiding methods before the Search Interface initialization call.

For advanced usage, the handler methods takes two parameters:

function myCustomPrebindingMethod(value, originalElement) {
    return transformValue(value);
}

The first parameter is the original value in the markup. For example, with the following markup, value would be something.

<div data-custom-attribute="something" data-prebind-custom-attribute="customPrebinding"></div>

The second parameter is the HTML element reference where the prebinding method is applied. Use it if you need to fetch any other information set directly on the element.

Applying Prebinding to Elements Not in a Search Interface

You can use the following methods to call prebinding on a specific element:

CoveoForSitecore.Prebinding.applyPrebindingOnElement(element);

You  can also apply prebinding on all its children:

CoveoForSitecore.Prebinding.applyPrebindingOnChildren(element);