--- title: Usage slug: quantic-latest-quantic-usage canonical_url: https://docs.coveo.com/en/quantic/latest/usage/ collection: quantic source_format: adoc --- # Usage You'll use the [Coveo Quantic library](https://docs.coveo.com/en/n9790069/) to assemble [Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide) (LWCs) which are managed in [Salesforce Developer Experience](https://developer.salesforce.com/developer-centers/developer-experience) (DX) projects using the [Salesforce CLI](https://developer.salesforce.com/tools/salesforcecli/). This article provides an overview of how to use Quantic by guiding you through the implementation of a [search interface](https://docs.coveo.com/en/2741/) LWC. ## Prerequisites * You've installed the Salesforce CLI, with [Dev Hub](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_setup_enable_devhub.htm) enabled in your Salesforce organization. * Although it's not necessary, we recommend that you [install](https://docs.coveo.com/en/1102/) and [configure](https://docs.coveo.com/en/1153/) [Coveo for Salesforce](https://docs.coveo.com/en/1404/) v4 or a later package. It can automatically take care of important steps at the [search token](https://docs.coveo.com/en/1346/) [authentication](https://docs.coveo.com/en/2120/) stage. ## Install Quantic Quantic is released as an [unlocked package](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_unlocked_pkg_install_pkg.htm). You can install version 3.37.1.0 using the following links: * [Install Coveo Quantic in a production environment](https://login.salesforce.com/packaging/installPackage.apexp?p0=04tKf000000DA4uIAG). * [Install Coveo Quantic in a sandbox environment](https://test.salesforce.com/packaging/installPackage.apexp?p0=04tKf000000DA4uIAG). You can also install Quantic version 3.37.1.0 with the Salesforce CLI [`package install`](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_package_commands_unified.htm#cli_reference_package_install_unified) command: [source,bash,subs="attributes,verbatim"] ``` sf package install --package 04tKf000000DA4uIAG --target-org ``` where you replace `` with your username in the target Salesforce organization. For other versions, see the package IDs or installation URLs in the [Quantic project repository](https://github.com/coveo/ui-kit/discussions). > **Note** > > Always keep your Apex code clean and compiled. > However, if you only want to compile the package Apex code during the installation, use the `--apex-compile package` option. > > [source,bash,subs="attributes,verbatim"] > ``` sf package install --apex-compile package --package 04tKf000000DA4uIAG --target-org ``` ## Create a Salesforce DX project You need a Salesforce DX project to manage your LWCs. You can [create one](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_ws_create_new.htm) with the [`project generate`](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_project_commands_unified.htm#cli_reference_project_generate_unified) command: ```bash sf project generate --name MyProject ``` Once you've created your project, you have to indicate to your Salesforce organization that you'll be using the Quantic library. Open the `sfdx-project.json` file at the root of your project folder and add the following dependency to the `packageDirectories` object: [source,json,subs="attributes"] ``` { "package": "quantic", "versionNumber": "3.37.1.NEXT", "path": "force-app/quantic/", "default": false, "dependencies": [ { "package": "Quantic", "versionNumber": "3.37.1.LATEST" } ] } ``` Make sure that you use version numbers which match the version of Quantic that's installed in your Salesforce organization. You can check which one you have with the **Installed Packages** tool in your Salesforce organization's **Setup** menu. To update to the latest version of Quantic in your Salesforce organization, repeat the [installation process](#install-quantic) with the newest package identifier. ## Assemble your component You can use Quantic by creating LWCs that assemble the target Quantic components. Because Quantic is released as an unlocked package, its components will be available under the [default namespace `c`](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/namespaces_using_default.htm). > **Tip** > > You can find [a complete example of a search interface LWC](https://github.com/coveo/ui-kit/tree/main/packages/quantic/force-app/solutionExamples/main/lwc/exampleSearch) in the Quantic project repository. ### Setup The structure of your Salesforce DX project is largely up to you. However, you may want to retrieve Quantic locally so that you can navigate to the existing Quantic components and use them as examples when building your LWC. #### Retrieve Quantic You can import the Quantic project into yours with the [`project retrieve start`](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_project_commands_unified.htm#cli_reference_project_retrieve_start_unified) command: ```bash sf project retrieve start --package-name Quantic --target-metadata-dir ./ --target-org ``` where you replace `` with your username in the target Salesforce organization. Once you've downloaded the file, unzip it and move its contents to `force-app/quantic`. #### Create your LWC Create your LWC (for example, `mySearchPage`) with the [`lightning generate component`](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_lightning_commands_unified.htm#cli_reference_lightning_generate_component_unified) command: ```bash sf lightning generate component --name mySearchPage --type lwc ``` The structure of your new LWC should look like the following: [listing] ``` mySearchPage/ ├── mySearchPage.html ├── mySearchPage.js ├── mySearchPage.js-meta.xml ``` ### HTML This is where you assemble HTML elements and leverage [Quantic components](https://docs.coveo.com/en/quantic/latest/reference/) to build your search interface LWC. ```html ``` <1> Attach the `handleResultTemplateRegistration` function on the event thrown to register [result templates](#result-templates). <2> Use the [`QuanticSearchInterface`](https://docs.coveo.com/en/quantic/latest/reference/search-components/search-search-interface/) component and set its `engine-id` and `[search-hub](https://docs.coveo.com/en/1342/)` properties, as well as any others that you require. In this example, these properties are set with variables whose default values are defined in the [XML configuration file](#xml), but you can also set specific values here, such as `search-hub="example-search-hub"`. Typically, you'll set the actual values for the properties that you expose through the XML file in the [Salesforce Experience Builder](https://help.salesforce.com/s/articleView?id=sf.community_designer_ui.htm&type=5). This search interface component is required to handle the [Headless](https://docs.coveo.com/en/headless/latest/) search engine and localization configurations. Most Quantic components require an `engine-id`, and all components that belong to a given interface must have the same `engine-id`. Sharing this `engine-id` across components is what allows the `QuanticSearchInterface` component to establish the connection between them. You must have one and only one `QuanticSearchInterface` component per `engine-id` in a given page or Digital Experience. <3> Out of the box, Quantic lets you use [Salesforce Lightning Design System](https://www.lightningdesignsystem.com/) (SLDS) styling classes. In this case, you're using the [Grid utility](https://www.lightningdesignsystem.com/utilities/grid/). <4> Use the SLDS [`gutters_direct`](https://www.lightningdesignsystem.com/utilities/grid/#Direct-Columns-Only) class, which only applies to direct children. The `gutters` class can cause styling issues with certain Quantic child components. <5> Your result templates will initialize inside the [`QuanticResultList`](https://docs.coveo.com/en/quantic/latest/reference/search-components/search-result-list/) component. > **Tip** > > You can find [a more detailed example](https://github.com/coveo/ui-kit/blob/master/packages/quantic/force-app/solutionExamples/main/lwc/exampleSearch/exampleSearch.html) in the Quantic project repository. ### XML The [XML configuration file](https://developer.salesforce.com/docs/platform/lwc/guide/reference-configuration-tags.html) is where you define the targets of your LWC. You also specify the parameters whose values are requested through the [Salesforce Experience Builder](https://help.salesforce.com/s/articleView?id=sf.community_designer_ui.htm&type=5) and can set their default values. These take precedence over the values you set in your LWC [JavaScript file](#javascript). ```xml 56.0 true <1> lightning__RecordPage lightning__AppPage lightning__HomePage lightningCommunity__Page lightningCommunity__Default <2> ``` <1> The [targets](https://developer.salesforce.com/docs/platform/lwc/guide/reference-configuration-tags.html#target) in which your LWC will be available. <2> Expose the properties that you want to be able to edit in the Salesforce Experience Builder. You can set different values for each target. You passed these variables to instantiate Quantic components in your [HTML file](#html). > **Tip** > > You can find [a more detailed example](https://github.com/coveo/ui-kit/blob/master/packages/quantic/force-app/solutionExamples/main/lwc/exampleSearch/exampleSearch.js-meta.xml) in the Quantic project repository. ### Result templates [Result templates](https://docs.coveo.com/en/quantic/latest/usage/result-template-usage/) are HTML files that determine the format of the individual result [items](https://docs.coveo.com/en/210/) in a search interface. You build them by assembling SLDS elements and Quantic components. Inside these, you can invoke the `result` variable, which is passed by the result template manager and holds various result item attributes. Typically, you'll want to define your result templates in a folder which is a sibling of your other search interface files. You'll connect them using conditions in your [JavaScript file](#javascript). [listing] ``` mySearchPage/ ├── resultTemplates/ │ ├── youtubeResultTemplate.html ├── mySearchPage.html ├── mySearchPage.js ├── mySearchPage.js-meta.xml ``` While optional, use the [`QuanticResultTemplate`](https://docs.coveo.com/en/quantic/latest/reference/result-template-components/result-template-result-template/) component. This component makes it easier to create responsive and stylistically cohesive templates by providing a recommended display structure that uses predefined and formatted [LWC slots](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-slots.html). ```html ``` <1> Wrap your template in the `QuanticResultTemplate` component. <2> Use the [`QuanticResultLabel`](https://docs.coveo.com/en/quantic/latest/reference/result-template-components/result-template-result-label/) component with the [`label`](https://docs.coveo.com/en/quantic/latest/usage/result-template-usage#label-section) slot. To instantiate this component, don't specify the engine ID, but you pass the result item. <3> In the [`date`](https://docs.coveo.com/en/quantic/latest/usage/result-template-usage#date-section) slot, pass the result's `raw.date` [field](https://docs.coveo.com/en/200/) to the [Lightning Formatted Date Time](https://developer.salesforce.com/docs/component-library/bundle/lightning-formatted-date-time/example) component. <4> The [`QuanticResult`](https://github.com/coveo/ui-kit/blob/master/packages/quantic/force-app/main/default/lwc/quanticResult/quanticResult.js) component exposes a `videoThumbnail` attribute which you can use to display the video thumbnail. > **Tip** > > You can find more [result template examples](https://github.com/coveo/ui-kit/tree/main/packages/quantic/force-app/solutionExamples/main/lwc/exampleSearch/resultTemplates) in the Quantic project repository. ### JavaScript This is where you connect your [result templates](#result-templates) with your main [HTML file](#html) using conditions. It's also where you define the variables that you used in the HTML file, whose values you set in the [XML file](#xml). ```javascript import youtubeTemplate from './resultTemplates/youtubeResultTemplate.html'; import {LightningElement, api} from 'lwc'; export default class MySearchPage extends LightningElement { @api engineId = 'example-search'; <1> @api searchHub = 'example-search-hub'; handleResultTemplateRegistration(event) { <2> event.stopPropagation(); <3> const resultTemplatesManager = event.detail; <4> const isYouTube = CoveoHeadless.ResultTemplatesHelpers.fieldMustMatch( <5> 'filetype', ['YouTubeVideo'] ); resultTemplatesManager.registerTemplates( <6> { content: youtubeTemplate, <7> conditions: [isYouTube], fields: ['ytvideoid', 'ytvideoduration'], <8> priority: 1 <9> }, ); }; } ``` <1> Define the variables that you used in the [HTML file](#html) and set their default values. The values that you set here are secondary to the ones that you set in your [XML file](#xml). <2> The function that you attached to the `onregisterresulttemplates` event in your HTML file. As its name suggests, it lets you register your result templates. <3> Since you caught the event, stop its propagation. <4> The `detail` property contains a result template manager, which you'll store in a variable. <5> Create a condition that matches YouTube videos. <6> Register the result template on the result template manager. <7> This line and the next make your `youtubeTemplate` only apply to result items that fulfill the `isYoutube` condition. If a result item doesn't match the conditions of any of your result templates, then the default Quantic one applies. <8> Specify the fields to include in the search requests made by Quantic, because you need them in your `youtubeTemplate`. By default, the Coveo [index](https://docs.coveo.com/en/204/) doesn't return all possible item field values, so you must specify any non-default fields that you want to use in your result templates. <9> Sets the priority of the result template. If the conditions of multiple templates are satisfied by a given result, the template with the highest priority is selected. If multiple templates have equal priority, the first template registered is selected. > **Tip** > > You can find [a more detailed example](https://github.com/coveo/ui-kit/blob/master/packages/quantic/force-app/solutionExamples/main/lwc/exampleSearch/exampleSearch.js) in the Quantic project repository. ### CSS You can use SLDS styling classes in your LWC markup. You can also add a `.css` file at the root of your project folder for further styling. ```css .search__grid { position: relative; padding: 12px; background: #fff; border-radius: .25rem; background-clip: padding-box; } ``` ### Search token provider If you were to [deploy](#deploy-your-project) your LWC now, it would return results. ![Quantic search page with sample results](https://docs.coveo.com/en/assets/images/quantic/usage-before-own-token-provider.png) However, these results come from a sample organization which is only meant for testing. For a real implementation, configure search token authentication in your search page. This means that each user gets their own search token, with appropriate privileges to access your organization's content. Personalized search tokens also let you use personalized [Coveo Analytics](https://docs.coveo.com/en/182/) and [machine learning](https://docs.coveo.com/en/188/) features. If you've [installed](https://docs.coveo.com/en/1102/) and [configured](https://docs.coveo.com/en/1153/) Coveo for Salesforce v4 or a later package in your Salesforce organization, it's typically enough to copy the [`CoveoTokenProvider`](https://github.com/coveo/ui-kit/blob/master/packages/quantic/force-app/coveo-token/main/default/classes/CoveoTokenProvider.cls) Apex class, along with its [`meta.xml`](https://github.com/coveo/ui-kit/blob/master/packages/quantic/force-app/coveo-token/main/default/classes/CoveoTokenProvider.cls-meta.xml) file, into your Salesforce DX project. This class can automatically fetch your Salesforce users' information to generate search tokens for them. This is the best option for most use cases. If you haven't installed Coveo for Salesforce v4 or a later package, or if the `CoveoTokenProvider` Apex class doesn't fit your needs, you'll have to implement your own search token provider. > **Tip** > > You can find [an example](https://github.com/coveo/ui-kit/tree/main/packages/quantic/force-app/custom-token) in the Quantic project repository. Once you've copied or created your search token provider Apex class, modify the [Headless](https://docs.coveo.com/en/headless/latest/) configuration in your Quantic installation so that it calls your Apex class. You can find the [`HeadlessController`](https://github.com/coveo/ui-kit/blob/master/packages/quantic/force-app/main/default/classes/HeadlessController.cls) file at `force-app/quantic/classes`. Locate the following line: ```javascript return SampleTokenProvider.getHeadlessConfiguration(); ``` and modify it so that it leverages your search token provider instead: ```javascript return YOUR_TOKEN_PROVIDER.getHeadlessConfiguration(); ``` where you replace `YOUR_TOKEN_PROVIDER` with the name of your search token provider Apex class, such as `CoveoTokenProvider` if you copied it from the Quantic project. If you've retrieved the Quantic project, you can make this change locally. After you [deploy your project](#deploy-your-project), your changes will be effective in your Salesforce organization. If you haven't retrieved Quantic locally, you can navigate to the `HeadlessController` file from the [Salesforce Developer Console](https://help.salesforce.com/s/articleView?id=sf.code_dev_console.htm&type=5) and modify it there. ## Deploy your project Deploy your project to your Salesforce organization with the [`project deploy start`](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_project_commands_unified.htm#cli_reference_project_deploy_start_unified) command: ```bash sf project deploy start --target-org ``` > **Important** > > If you get an error message, you may need to rename some files. > For example, you may need to rename the following file: > > `quantic/cspTrustedSites/QuanticCoveoPlatform.cspTrustedSite` > > to > > `quantic/cspTrustedSites/QuanticCoveoPlatform.cspTrustedSite-meta.xml` After you've deployed your project successfully, you'll be able to use your LWC in the [Salesforce Experience Builder](https://help.salesforce.com/s/articleView?id=sf.community_designer_ui.htm&type=5). ## Update Quantic The process for updating the Quantic project is similar to that for other Salesforce packages. . Start by [installing](#install-quantic) the latest version. . If you retrieved the Quantic project locally in your Salesforce DX project, you'll need to do so again to keep your project version in sync with the new one in your Salesforce organization. . The search token provider in the [`HeadlessController`](https://github.com/coveo/ui-kit/blob/master/packages/quantic/force-app/main/default/classes/HeadlessController.cls) file gets overwritten by updates. You have to replace `SampleTokenProvider` with the name of your search token provider Apex class, as you did when you [configured your search token provider](#search-token-provider). ## What's next? After you implement a main search page in an Experience Cloud site (such as Community), you'll typically want to implement a [standalone search box](https://docs.coveo.com/en/quantic/latest/usage/ssb-usage/).