Integrate Using Modules

In this article, we describe how to embed modules in the web pages of your websites or web apps.

Modules or API

Two approaches are available for integrating Site Search capabilities into your websites and web apps:

Some features are only available using one approach. You can use a combination of approaches, for example, APIs for pushing documents and deleting pushed documents and modules for searching and displaying search results.

Before you begin

Before modules are ready to embed in web pages, you must add modules to the Search page and configure the modules.

The starting point for managing modules is the Page Builder. In the upper left corner, click Edit.

Available modules

These are the available modules:

  • Search Box – Search Box modules let users search. You might only need one Search Box module for all searches. On the other hand, you might want more than one Search Box module, for example, ones to search over different topics or in different languages.

  • Results – Results modules display search results. You might only need one Search Box module for all searches. On the other hand, you might want more than one Results module, for example, ones in different languages.

  • Topic Tabs – Topic Tabs modules display a tabbed navigation element based on topics. Topics are meaningful characterizations of the data from data sources, including the source of the data. A topic can be applied to one or more data sources, and a data source can have one or more topics.

  • Facets – Facet modules let users select subsets of the search results. They are field-based groups of search results. For example, if the department field is chosen as a facet, then users can click the facets computers, appliances, and so forth to view those subsets of search results.

  • More Like This – More Like This modules display search results that are similar to the top result. This is a smart panel that adds intelligence to search and browsing experiences.

Embed modules

Embedding a Site Search Module on a web page consists of three steps:

  1. Whitelist domains – Whitelist the domains of all websites on which you will embed Site Search modules.

  2. Embed the module in a web page – In the Page Builder, copy the embeddable code. Then paste the code into the desired place on a webpage in a whitelisted domain.

Whitelist domains

Whitelist all domains on which you want to embed Site Search modules.

Specify the URI scheme (http or https), ://, and the path, for example, https://www.mycompany.com/. The path must include the fully qualified domain name (for example, www.mycompany.com). It can’t extend to a level below the top-level domain (for example, www.mcompany.com/news/ is not valid. The trailing slash is optional.

To whitelist a domain
  1. In the Site Search menu, click Embed on your website.

  2. Under Embed domain whitelist, enter the domain name, and then click Add.

Whitelist domain.

To remove a domain from the whitelist
  1. In the Site Search menu, click Embed on your website.

  2. Under Embed domain whitelist, hover over the domain you want to, and then click Delete Delete.

Embed modules in web pages

Embed modules in web pages on your website to provide Site Search functionality there.

To embed a module
  1. In the Page Builder, hover over the module you want to embed.

  2. Click Embed Embed module.

    Site Search displays a dialog box that contains two code snippets.

    Embed dialog

  3. Hover over the upper code snippet, and then click Copy.

    Paste this code into the <head> tag of every web page in a whitelisted domain on which you want to embed the module.

  4. Hover over the lower code snippet, and then click Copy.

    Paste this code into desired place in every web page in a whitelisted domain on which you want to embed the module.

Limit search to specific topics

You can limit a search to specific topics. A topic can be applied to one or more data sources, and a data source can have one or more topics.

To limit a search to specific topics

In the snippet for the Search Box, include a topics attribute in the <cloud-search-box> element. List one or more topics, separated by commas, for example:

<cloud-search-box topics="knowledge_base,documentation"></cloud-search-box>

If you use also use a Topic Tabs module, only the tabs for the requested topics will display results.

Localize modules

Localizing a module has two parts: localizing the UI language and setting the search language.

Localize the UI language

The default UI language for all embedded modules is English. If the desired language for a module is English, then you can skip this procedure.

To specify a UI language for an embedded module
  1. In the Page Builder, hover over a module on the page. The Edit Embed Delete Move control appears at the upper right of the module.

  2. Click Edit module. A dialog box appears.

  3. Select the UI language from the UI language dropdown list.

    Note
    You aren’t setting the UI language here. All you are doing is adding the correct URL parameter to the first code snippet.

    This is an example of the snippet for German:

    <!-- Lucidworks.cloud embed script -->
    <script async="false" src="https://{domain}.lucidworks.cloud/{pathname}/embed/v1/ui/loader.js?language=de"></script>
  4. Copy the snippet to the <head> element of the HTML page or pages on which you are embedding modules.

Alternatively, you can add the language URL parameter in the loader.js URL in the Lucidworks.cloud embed script snippet after copying the snippet to an HTML page or pages.

Specify the search language

Specify the search language so that Site Search can boost documents in that language, which moves the documents closer to the beginning of search results. Boosting occurs in search results in a Results module and in search results returned by the Search API. Boosting also occurs for suggested documents.

Tip
Specifying a search language doesn’t restrict results to that language.
To specify the default search language

Specify the default search language for all Search Box modules, suggested documents, and the Search API:

  1. Hover over the Search Box module, and then click Edit module.

  2. Select the language from the Default Search Language dropdown list. The language English is selected by default.

To specify the search language for a specific Search Box module

In the snippet for the Search Box, include a language attribute in the <cloud-search-box> element, for example:

<cloud-search-box language="fr"></cloud-search-box>
To specify the search language in a Search API request

Include the language URL parameter in the Search API request, as shown in this example:

curl -H 'X-API-Key: 7556b805-662d-44c8-b463-d8cb0fa486e56765f6e6-dd60-4fdc-9c53-d8c03edb3a2e' 'https://fusion-search.lucidworks.cloud/search/api/v1/search?p=1&rpp=5&language=fr&fi=name,url,description&q=justin%20trudeau'

Override strings in modules

You can override the strings in modules. You can do this irrespective of whether you localize modules.

The order of overriding is:

  1. (For all modules) The default language is English. Modules use default strings for English.

  2. (For all modules on a page) The language URL parameter in the loader.js URL specifies the language. The URL parameter is in the Lucidworks.cloud embed script snippet. Each module uses the default strings for the language specified for the HTML page.

  3. (For all modules on a page) Add any string overrides to a <script> element somewhere on the page (in the <HEAD> or <BODY> element.

To override strings for all modules on a page
  1. Take this script as the starting point:

    <script>
     window.AppkitTranslations['components.breadcrumbs.clear-all'] = 'Clear all';
     window.AppkitTranslations['components.breadcrumbs.exclude'] = 'not {breadcrumb}';
     window.AppkitTranslations['components.facet.show-less'] = 'Show less';
     window.AppkitTranslations['components.facet.show-more'] = 'Show more';
     window.AppkitTranslations['components.more-like-this.subtitle'] = 'More results like <em>{result}</em>';
     window.AppkitTranslations['components.more-like-this.title'] = 'Similar Results';
     window.AppkitTranslations['components.more-like-this.top-result'] = 'the top result';
     window.AppkitTranslations['components.no-results.subtitle'] = 'If you've checked your spelling: try using more general keywords.';
     window.AppkitTranslations['components.no-results.title'] = 'Sorry: there are no results that match your search criteria.';
     window.AppkitTranslations['components.pagination.next'] = 'next';
     window.AppkitTranslations['components.pagination.previous'] = 'previous';
     window.AppkitTranslations['components.response-statistics.showing'] = 'Showing {first} - {last} of {total}';
     window.AppkitTranslations['components.response-statistics.showing-all'] = 'Showing All {total}';
     window.AppkitTranslations['components.search-box.placeholder'] = 'Search...';
     window.AppkitTranslations['components.search-box.query-suggestion-title'] = 'Suggested terms';
     window.AppkitTranslations['components.spelling-suggestions.auto-correct'] = 'Showing results for {correction}.';
     window.AppkitTranslations['components.spelling-suggestions.did-you-mean'] = 'Did you mean: {query}';
     window.AppkitTranslations['components.spelling-suggestions.no-results'] = 'No results found for {query}.';
     window.AppkitTranslations['components.tabs.all-label'] = 'All';
     window.AppkitTranslations['schema.name.default'] = '(Missing Name)';
    </script>
    Tip
    Not all of these strings are used by all modules. You only need to include the strings for all overrides you want to occur on the specific page. For simplicity’s sake, you could include all of the strings you override on every page with modules.
  2. Modify the strings as desired, in the desired target language. For example, for the English strings, you might use:

    <script>
     window.AppkitTranslations['components.breadcrumbs.clear-all'] = 'Clear breadcrumbs';
     window.AppkitTranslations['components.facet.show-less'] = 'Show fewer';
     window.AppkitTranslations['components.more-like-this.subtitle'] = 'More like <em>{result}</em>';
     window.AppkitTranslations['components.more-like-this.title'] = 'Similar Results';
     window.AppkitTranslations['components.no-results.title'] = 'Sorry, no results match your search criteria.';
     window.AppkitTranslations['components.pagination.next'] = 'Next';
     window.AppkitTranslations['components.pagination.previous'] = 'Previous';
     window.AppkitTranslations['components.spelling-suggestions.did-you-mean'] = 'Did you mean {query}?';
     window.AppkitTranslations['components.spelling-suggestions.no-results'] = 'Search query {query} gave no results.';
     window.AppkitTranslations['schema.name.default'] = '(Missing Name)';
    </script>
    Important
    We recommend that you leave the variables (in curly braces, e.g. {first}) in the strings. You can change their placement in the strings. components.spelling-suggestions.no-results is an example of changing the placement.
  3. Notice the emphasis (<em></em>) added to {result} in this default string:

     window.AppkitTranslations['components.more-like-this.subtitle'] = 'More results like <em>{result}</em>';

    You can make judicious use of emphasis in other strings, for example:

     window.AppkitTranslations['components.spelling-suggestions.did-you-mean'] = 'Did you mean: <em>{query}</em>';
    Note
    The only HTML tag you can add is <em>.

Style modules with CSS

You can use cascading style sheets (CSS) to style modules.