SearchUI Lightning component

This is for:

In this article

Usage
Options
Methods
Aura Event

The SearchUI Lightning component is a Lightning wrapper around a Coveo search-ui framework implementation.

It takes care of loading your search page content, of initializing the search-ui framework, and it provides customization options.

Usage

This component is used by the AgentPanel Lightning component, the FullSearch Lightning component, the CaseDeflection Lightning component, the CommunitySearch Lightning component, the CommunitySearchBox Lightning component, and the AttachedResults Lightning component.

To use it, you can reference it as you would for any other Lightning component, using the namespace prefix of the Coveo package.

<!-- LightningComponent.cmp -->
<aura:component access="global" >
  <aura:handler name="init" value="{!this}" action="{!c.doInit}" />
  <CoveoV2:SearchUI name="<NAME_OF_YOUR_SEARCH_PAGE>" aura:id="<YOUR_COMPONENT_ID>"></CoveoV2:SearchUI>
</aura:component>

Where you replace:

<NAME_OF_YOUR_SEARCH_PAGE> by the name of your search page.
<YOUR_COMPONENT_ID> by your component ID.

Note

The examples given in this article refer to the AgentPanel Lightning component. However, keep in mind that you can also use the SearchUI Lightning component with all the other components listed above and with a custom component.

When using a custom component, the .get('v.searchUI') element isn’t required when instantiating the script, as the following example demonstrates:

Example

<!-- LightningComponent.cmp -->
<CoveoV2:SearchUI name="<NAME_OF_YOUR_SEARCH_PAGE>" aura:id="<YOUR_COMPONENT_ID>"></CoveoV2:SearchUI>

// LightningComponentController.js
doInit: function(component, event, helper) {
  // Get the Coveo SearchUI
  var coveoCustomComponent = component.find('<YOUR_COMPONENT_ID>');

  coveoCustomComponent.registerBeforeInit(function (cmp, rootInterface, Coveo) {
  // Do something.
  });
}

Where you replace:

<NAME_OF_YOUR_SEARCH_PAGE> by the name of your search page.
<YOUR_COMPONENT_ID> by your component ID.

Options

name

As of the Coveo for Salesforce v5 release

The name of the Page Content record that contains the HTML code of your search interface.
Prior Coveo for Salesforce versions

The name of the Visualforce component that contains the HTML code of your search interface.

Default value is searchui.

searchHub

The name of the search hub to enforce when authenticating a query with this search token, which can also be used in query pipeline condition statements.

This option should have the same value as name.

Methods

Note

Coveo for Salesforce 3.24

You can now use every method available in the Coveo JavaScript Search Framework (see Coveo JavaScript Search Framework - Reference Documentation).

However, the first element, which represents the HTML root of your search interface, is provided for you. You don’t have to specify it.

Example

You can use the executeQuery method on the coveoSearchUI component.

<!-- LightningComponent.cmp -->
<aura:component implements="force:hasRecordId,force:hasSObjectName,flexipage:availableForRecordHome">
  <CoveoV2:AgentPanel aura:id="coveoAgentPanel" sObjectName="{!v.sObjectName}" recordId="{!v.recordId}"></CoveoV2:AgentPanel>
  <lightning:button variant="base" label="Execute" title="Execute" onclick="{! c.handleClick }"/>
</aura:component>

// LightningComponentController.js
doInit: function(component, event, helper) {
  // Get the Coveo Insight Panel Lightning Component
  var coveoAgentPanel = component.find('coveoAgentPanel');
  // Get the Coveo SearchUI base component
  var coveoSearchUI = coveoAgentPanel.get('v.searchUI');
  // Apply the customization
  coveoSearchUI.executeQuery();
}

registerBeforeInit

Registers a function to be executed before the search-ui will be initialized.

This function will receive as parameter:

this component
the Coveo SearchInterface
the Coveo namespace

<!-- LightningComponent.cmp -->
<aura:component implements="force:hasRecordId,force:hasSObjectName,flexipage:availableForRecordHome">
  <CoveoV2:AgentPanel aura:id="coveoAgentPanel" sObjectName="{!v.sObjectName}" recordId="{!v.recordId}"></CoveoV2:AgentPanel>
  <aura:handler name="init" value="{!this}" action="{!c.doInit}" />
</aura:component>

// LightningComponentController.js
doInit: function(component, event, helper) {
  // Get the Coveo Insight Panel Lightning Component
  var coveoAgentPanel = component.find('coveoAgentPanel');
  // Get the Coveo SearchUI base component
  var coveoSearchUI = coveoAgentPanel.get('v.searchUI');
  // Apply the customization
  coveoSearchUI.registerBeforeInit(function (cmp, rootInterface, Coveo) {
      // Do something.
  });
}

registerAfterInit

Registers a function to be executed after the component initialization.

This function will receive as parameter:

this component
the Coveo SearchInterface
the Coveo namespace

<!-- LightningComponent.cmp -->
<aura:component implements="force:hasRecordId,force:hasSObjectName,flexipage:availableForRecordHome">
  <CoveoV2:AgentPanel aura:id="coveoAgentPanel" sObjectName="{!v.sObjectName}" recordId="{!v.recordId}"></CoveoV2:AgentPanel>
  <aura:handler name="init" value="{!this}" action="{!c.doInit}" />
</aura:component>

// LightningComponentController.js
doInit: function(component, event, helper) {
  // Get the Coveo Insight Panel Lightning Component
  var coveoAgentPanel = component.find('coveoAgentPanel');
  // Get the Coveo SearchUI base component
  var coveoSearchUI = coveoAgentPanel.get('v.searchUI');
  // Apply the customization
  coveoSearchUI.registerAfterInit(function (cmp, rootInterface, Coveo) {
      // Do something.
  });
}

executeImmediate

Executes a function immediately within the Coveo context.

This function will receive as parameter:

this component
the Coveo SearchInterface
the Coveo namespace

<!-- LightningComponent.cmp -->
<aura:component implements="force:hasRecordId,force:hasSObjectName,flexipage:availableForRecordHome">
  <CoveoV2:AgentPanel aura:id="coveoAgentPanel" sObjectName="{!v.sObjectName}" recordId="{!v.recordId}"></CoveoV2:AgentPanel>
  <aura:handler name="init" value="{!this}" action="{!c.doInit}" />
</aura:component>

// LightningComponentController.js
doInit: function(component, event, helper) {
  // Get the Coveo Insight Panel Lightning Component
  var coveoAgentPanel = component.find('coveoAgentPanel');
  // Get the Coveo SearchUI base component
  var coveoSearchUI = coveoAgentPanel.get('v.searchUI');
  // Apply the customization
  coveoSearchUI.executeImmediate(function (cmp, rootInterface, Coveo) {
      // Do something.
  });
}

proxyAddEventListener

Binds a function to an event on the SearchInterface without exposing the DOM element, which is blocked by Lightning Locker.

This function expects two arguments: the event to listen on (see Events) and a function handler to be executed when the event occurs, which receives the same arguments as the usual search-ui event handlers.

Important

There are exceptions: no arguments that contain DOM elements can be used this way because of Lightning Locker SecureDOM (see Introducing The Lightning Locker For Lightning Components).

<!-- LightningComponent.cmp -->
<aura:component implements="force:hasRecordId,force:hasSObjectName,flexipage:availableForRecordHome">
  <CoveoV2:AgentPanel aura:id="coveoAgentPanel" sObjectName="{!v.sObjectName}" recordId="{!v.recordId}"></CoveoV2:AgentPanel>
  <aura:handler name="init" value="{!this}" action="{!c.doInit}" />
</aura:component>

// LightningComponentController.js
doInit: function(component, event, helper) {
  // Get the Coveo Insight Panel Lightning Component
  var coveoAgentPanel = component.find('coveoAgentPanel');
  // Get the Coveo SearchUI base component
  var coveoSearchUI = coveoAgentPanel.get('v.searchUI');
  // Apply the customization
  coveoSearchUI.proxyAddEventListener('doneBuildingQuery', function (e, args) {
      // Do something.
      // Example: args.queryBuilding.advancedExpression.addContext(...)
  });
}

Leading practice

You should always register Coveo JavaScript Search event handlers before the init call of your search interface.

setSearchInterfaceOptions

Sets the Search Interface options without having to pass the DOM elements associated to the Lightning Locker.

Notes

Ensure to call this before initialization or the options will be ignored.
Typically, you want to set the options of the SearchInterface before the search-ui framework is initialized to capture them.

<!-- LightningComponent.cmp -->
<aura:component implements="force:hasRecordId,force:hasSObjectName,flexipage:availableForRecordHome">
  <CoveoV2:AgentPanel aura:id="coveoAgentPanel" sObjectName="{!v.sObjectName}" recordId="{!v.recordId}"></CoveoV2:AgentPanel>
  <aura:handler name="init" value="{!this}" action="{!c.doInit}" />
</aura:component>

// LightningComponentController.js
doInit: function(component, event, helper) {
  // Get the Coveo Insight Panel Lightning Component
  var coveoAgentPanel = component.find('coveoAgentPanel');
  // Get the Coveo SearchUI base component
  var coveoSearchUI = coveoAgentPanel.get('v.searchUI');
  // Register this to be executed before the search-ui initialization.
  coveoSearchUI.registerBeforeInit(function (cmp, rootInterface, Coveo) {
    // Apply the customization
    coveoSearchUI.setSearchInterfaceOptions({
      SearchInterface: {
        pipeline: 'myPipeline'
      }
    });
  });
}

addPreInitPromise

Adds a promise to resolve before the search interface initialization.

Example

The initialization of the Coveo search-ui framework waits until the server-side action returns to add the profile name of the current user into each query context.

Note

Keep in mind that every action added before initialization can significantly slow down the time before the first search results are displayed to the users.

<!-- LightningComponent.cmp -->
<aura:component implements="force:hasRecordId,force:hasSObjectName,flexipage:availableForRecordHome">
  <CoveoV2:AgentPanel aura:id="coveoAgentPanel" sObjectName="{!v.sObjectName}" recordId="{!v.recordId}"></CoveoV2:AgentPanel>
  <aura:handler name="init" value="{!this}" action="{!c.doInit}" />
</aura:component>

// LightningComponentController.js
doInit: function(component, event, helper) {
  var coveoAgentPanel = component.find('coveoAgentPanel');
  var coveoSearchUI = coveoAgentPanel.get('v.searchUI');
  // Call an action from an Apex Controller
  var action = component.get('c.getUserProfile');
  // Create a new promise to resolve when the Server-side action returns.
  var getUserProfileNamePromise = new Promise(function (resolve, reject) {
    action.setCallback(this, function (response) {
      var state = response.getState();
      if (state === 'SUCCESS') {
        var responseValue = response.getReturnValue();
        // On doneBuildingQuery, adds the return value of the server-side action to the context.
        coveoSearchUI.proxyAddEventListener('doneBuildingQuery', function (e, args) {
          var qb = args.queryBuilder;
          qb.addContext(responseValue);
        });
        // Once we have the user profile name, resolve the pre-init promise.
        resolve();
      } else if (state === 'ERROR') {
        // If there was an error, reject the promise.
        // Handle the error.
        reject(new Error(response.getError()));
      }
    });
  });
  // Executes the server-side action.
  $A.enqueueAction(action);
  // Add the promise to the list of promises the searchUI is waiting on before it initializes.
  coveoSearchUI.addPreInitPromise(getUserProfileNamePromise);
}

// BasicApexController.cls
@AuraEnabled
public static Map<String,Object> getUserProfile() {
  List<Profile> myProfile = [SELECT Id, Name FROM Profile WHERE Id=:userinfo.getProfileId() LIMIT 1];
  return new Map<String,Object>{ 'user_profile' => myProfile[0].Name };
}

Note

For more information on how to get information from an Apex server-side controller, see Apex Server-Side Controller Overview and Calling a Server-Side Action.

Aura Event

This component offers the following event:

ErrorEvent

This error is fired when an error occurs with the component.