--- title: SearchUI Lightning component slug: '1375' canonical_url: https://docs.coveo.com/en/1375/ collection: coveo-for-salesforce source_format: adoc --- # SearchUI Lightning component [.version.c4sf.c4sf-edition.c4sf-pro-enterprise] [Pro and Enterprise editions](https://docs.coveo.com/en/l2590456#salesforce) 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](https://docs.coveo.com/en/1109/), the [FullSearch Lightning component](https://docs.coveo.com/en/1096/), the [CaseDeflection Lightning component](https://docs.coveo.com/en/1312/), the [CommunitySearch Lightning component](https://docs.coveo.com/en/2945/), the [CommunitySearchBox Lightning component](https://docs.coveo.com/en/2946/), and the [AttachedResults Lightning component](https://docs.coveo.com/en/3102/). To use it, you can reference it as you would for any other Lightning component, using the namespace prefix of the Coveo package. ```xml ``` Where you replace: - `` by the name of your search page. - `` by your component ID. > **Note** > > The examples given in this article refer to the [AgentPanel Lightning component](https://docs.coveo.com/en/1109/). > 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] > .Example [,xml] ``` ``` ```javascript // LightningComponentController.js doInit: function(component, event, helper) { // Get the Coveo SearchUI var coveoCustomComponent = component.find(''); coveoCustomComponent.registerBeforeInit(function (cmp, rootInterface, Coveo) { // Do something. }); } ``` ##### Where you replace: - `` by the name of your search page. - `` 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** > > You can now use every method available in the Coveo JavaScript Search Framework (see [Coveo JavaScript Search Framework - Reference Documentation](https://coveo.github.io/search-ui/globals.html#%5F%5F)). > > 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] > .Example You can use the `executeQuery` method on the `coveoSearchUI` component. ```xml ``` ```javascript // 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 ```xml ``` ```javascript // 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 ```xml ``` ```javascript // 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 ```xml ``` ```javascript // 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](https://docs.coveo.com/en/417/)) 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](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-intro.html)). ```xml ``` ```javascript // 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. ```xml ``` ```javascript // 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. ```xml ``` ```javascript // 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); } ``` ```apex // BasicApexController.cls @AuraEnabled public static Map getUserProfile() { List myProfile = [SELECT Id, Name FROM Profile WHERE Id=:userinfo.getProfileId() LIMIT 1]; return new Map{ '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](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/controllers_server_apex.htm) and [Calling a Server-Side Action](http://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/controllers_server_actions_call.htm). ## Aura event This component offers the following event: ### `ErrorEvent` This error is fired when an error occurs with the component.