Add JavaScript to the Coveo Lightning Aura components with custom code

This is for:

Developer System Administrator

During your implementation of Coveo for Salesforce, it’s common you’ll need to interact with the Coveo JavaScript Search Framework (see Use the JavaScript Search Framework (legacy)).

Tip
Leading practice

Create a static resource file in Salesforce to add your custom code (see Creating a Static Resource), and then reference the resource in a custom Lightning component which integrates the Coveo components (see Integrate Coveo Lightning Aura components in a custom component for your Experience Cloud site).

Step 1: Create a custom Lightning component

To add a custom script, you should create a custom component that looks like this:

Create a Custom Lightning Component

<aura:component implements="flexipage:availableForAllPageTypes" access="global">
    <aura:attribute name="name" type="String" default="communityCoveo" access="global" />
    <aura:attribute name="searchHub" type="String" default="" access="global" />
​
    <CoveoV2:SearchUI aura:id="searchui" name="{!v.name}" searchHub="{!v.searchHub}" />
</aura:component>>

Step 2: Create a static resource including your custom code

Now that you have your custom component, you should create a static resource in Salesforce (see Creating a Static Resource).

Important

The script runs in the context of the Coveo component.

Your function should be declared using CoveoCustomScripts, as such:

window.coveoCustomScripts['default'] = function(promise) {
  // Enter your JavaScript code here.
  // You can also use promises this way:
  var customPromise = Coveo.$.Deferred();
  setTimeout(function() {
    // Get external resources.
    customPromise.resolve();
  }, 1000)
  return customPromise;
}

You can also replace default, which executes the script for all components, with a component name to use the script only with the selected component, such as AgentPanel, FullSearch, or AttachedResults. (When referring to a custom Aura component, replace default with the name used in the Aura component you want to refer.)

Notes

Example

You want to programmatically add tablet to the query of a component on a page specifically used for tablet (see QueryBuilder), and send a custom analytics event to reflect this (see Send your own UA events). In your static resource, you enter the following code:

/**
 * @param {Promise<void>} promise A promise on which the custom script can wait on.
 * @param {Aura.Component} component The current SearchUI component instance.
 */
window.coveoCustomScripts['default'] = function (promise, component) {
  function sendMyCustomAnalytics(evt) {
    var root = evt.target;
    var myCustomEventCause = { name: 'Tablet', type: 'Product' };
    var myCustomEventMetadata = { product: 'tablet' };
    Coveo.logCustomEvent(root, myCustomEventCause, myCustomEventMetadata);
  }
  $('.CoveoSearchInterface').on('buildingQuery', function (evt, args) {
    args.queryBuilder.expression.add('tablet');
    sendMyCustomAnalytics(evt);
  });
}

Interact with the Coveo component properties

As of the October 2017 release, you can access the Coveo Lightning component properties from a static resource.

The parameter used as your component is the second one of your function.

Note

For more information on the supported component methods in Salesforce, see Component class.

 
var root = component.getElements().map(function(element) {
    return element.querySelector('.CoveoSearchInterface');
}).find(function (element) {
    return element != null;
});

Step 3: Include the custom script in your component

Now that you have a static resource, you should include your static resource in your custom component (see Integrate Coveo Lightning Aura components in a custom component for your Experience Cloud site).

To reference the static resource, in the CoveoV2:SearchUI section, add the following:

<!-- For uncompressed resources, use this format: -->
customScripts="{!$Resource.<YOUR_STATIC_RESOURCE>}"
<!-- For compressed resources, use this one: -->
customScripts="{!$Resource.<YOUR_STATIC_RESOURCE> + '<YOUR_STATIC_RESOURCE_FILE_PATH>'}"

Where you replace:

  • <YOUR_STATIC_RESOURCE> by the name of your static resource.

  • <YOUR_STATIC_RESOURCE_FILE_PATH> by the path of your static resource file (for example, /base/subdir/file.js).

Note

You can add many static resources to your CoveoV2:AgentPanel, CoveoV2:FullSearch, CoveoV2:AttachedResults, CoveoV2:CommunitySearch, CoveoV2:CommunitySearchbox, and CoveoV2:SearchUI components by using the following line:

customScripts="{!join(',',$Resource.<YOUR_FIRST_STATIC_RESOURCE>, $Resource.<YOUR_SECOND_STATIC_RESOURCE>, $Resource.<YOUR_THIRD_STATIC_RESOURCE>)}"

Where you replace: <YOUR_FIRST_STATIC_RESOURCE>, <YOUR_SECOND_STATIC_RESOURCE>, and <YOUR_THIRD_STATIC_RESOURCE> by the name of the static resources you want to add. You can add as many static resources as you want.

For more information on static resources usage, see Using Static Resources.

What’s next?