About Prebinding Helpers in Coveo Hive

This is for:

Developer System Administrator
Warning
Legacy feature

This article pertains to the Coveo Hive framework which is now in maintenance mode.

Choose one of Coveo’s more modern, lightweight, and responsive libraries for any future search interface development. See the search interface Implementation guide for more details.

This page covers what prebinding is and why Coveo Hive requires it.

Note

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

About Prebinding Helpers

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

These helpers let you quickly leverage the current context values in the markup, without requiring JavaScript code.

Coveo Hive uses the helpers for various purposes.

Using a Prebinding Method

The syntax is the following:

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

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.

Important

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);