Create a custom caption provider for facets

This is for:

Developer System Administrator

This tutorial provides detailed instructions on how to create and connect a custom caption provider component to a Quantic search interface. Creating a custom caption provider component is recommended when, for example, you want to override many facet captions at once.

In a nutshell, this article covers the following tasks:

Sample use case

You create a Quantic search page with facets displaying textual values. Suppose you want to translate the search page in a different language, then it would make sense to translate the facet values too.

Quantic facets

The QuanticFacetCaption component can be used to easily configure custom captions for the QuanticFacet and QuanticCategoryFacet components. However, the QuanticFacetCaption component overrides only one caption at a time.

Creating a custom caption provider component is therefore a better option when:

  • You want to override many captions at once.

  • You want to leverage Salesforce custom labels.

  • You’re required to use custom logic for formatting captions.

  • You want to share the same set of captions across many facets.

Identify the facet values to translate

The first aspect to consider when creating a custom caption provider component is to identify the facet values that need to be overridden.

Validate if you need to translate or correct values. If you need to translate values, identify which languages should be supported.

Tip
Tip

A custom caption provider is meant to provide a finite set of captions. You can apply custom formatting to the facet values, but the facet values must be known beforehand.

For this article, we will use the example of a facet on the filetype field with the values listed in the following table:

Facet value Expected caption

html

Web page

jpg

JPEG image

png

PNG image

txt

Text file

zip

Compressed file
Note

Instead of showing the file extension, we want to show the application name.

Create custom labels in Salesforce

Next, the following custom labels must be created in Salesforce.

Description Name Value

Filetype html

filetype_html

Web page

Filetype jpg

filetype_jpg

JPEG image

Filetype png

filetype_png

PNG image

Filetype txt

filetype_txt

Text file

Filetype zip

filetype_zip

Compressed file

To create custom labels

  1. From Setup, enter custom labels in the Quick Find box, and then select Custom Labels.

  2. Click the New Custom Label button.

  3. On the New Custom Label page, specify values for the Short Description, Name, and Value fields.

  4. Click Save.

  5. Repeat these steps for each custom label.

Create a custom caption provider component

Once the custom labels have been created in Salesforce:

  1. Create a custom caption provider LWC component that references your custom labels.

    Use a descriptive name such as filetypeCaptionProvider.

    Example

    filetypeCaptionProvider.html

    <template></template>

    filetypeCaptionProvider.js

    import { api, LightningElement } from 'lwc';

import html from '@salesforce/label/c.filetype_html'; 1
import jpg from '@salesforce/label/c.filetype_jpg';
import png from '@salesforce/label/c.filetype_png';
import txt from '@salesforce/label/c.filetype_txt';
import zip from '@salesforce/label/c.filetype_zip';

export default class FiletypeCaptionProvider extends LightningElement {

    labels = { 2
        'html': html,
        'jpg': jpg,
        'png': png,
        'txt': txt,
        'zip': zip,
    };

    @api get captions() { 3
        return this.labels;
    }
}
    1 Custom labels must be imported using static import. It’s not yet possible to dynamically import labels.
    2 labels is a dictionary representing the set of facet values (keys) and their corresponding caption. The imported custom labels return the localized value according to the user language.
    3 The captions property is called by the Quantic facets to retrieve the mappings required to replace a facet value by the right caption.

  2. Deploy the custom caption provider component to Salesforce.

Connect the caption provider to the search page

The final step involves adding the newly created custom caption provider component to your existing search page. To do so, you must modify your search page component markup to reference the new filetypeCaptionProvider component as follows:

  1. Make sure the facet on the filetype field looks like this:

    <c-quantic-facet field="filetype" label="File Type" engine-id={engineId}>
</c-quantic-facet>

  2. Add the filetypeCaptionProvider component this way:

    <c-quantic-facet field="filetype" label="File Type" engine-id={engineId}>
  <c-filetype-caption-provider slot="captions">
  </c-filetype-caption-provider>
</c-quantic-facet>

  3. Deploy the modified search page component to Salesforce.

Validate everything works as expected

At this point, the custom caption provider is in place, and it should be functioning properly.

To confirm that everything is working as expected, validate the following:

  • The custom captions are visible on the facet.

  • Custom captions are used in facet search.

  • When selecting a facet value with a custom caption, the same custom caption is displayed in the breadcrumb manager (see QuanticBreadcrumbManager).