The Hawksearch Handlebars UI script is published via the @bridgeline-digital/hawksearch-handlebars-ui npm package.

Installation Steps

npm Package

If your website does not already have a package.json file in the root, run npm init to generate one.
Run npm install --save @bridgeline-digital/hawksearch-handlebars-ui to install the latest version.

Update your HTML to import the script file, set your Configuration, and add the appropriate elements to your page. Below is a basic sample implementation:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Hawksearch Handlebars UI</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <script type="text/javascript">
      var Hawksearch = Hawksearch || {};

      Hawksearch.config = {
        clientId: "f51060e1c38446f0bacdf283390c37e8"
      };
    </script>
    <script src="node_modules/@bridgeline-digital/hawksearch-handlebars-ui/dist/hawksearch-handlebars-ui.js" defer></script>
  </head>

  <body>
    <h1>Hawksearch Handlebars UI</h1>
    <hawksearch-search-field></hawksearch-search-field>
    <hawksearch-search-results></hawksearch-search-results>
  </body>
</html>

Content Delivery Network (CDN)

This library is also available through jsDelivr, a high-performance global content delivery network built to consume npm packages.

To configure your website to use the CDN, simply update your HTML to import the script file, set your Configuration, and add the appropriate elements to your page. Below is a basic sample implementation:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Hawksearch Handlebars UI</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <script type="text/javascript">
      var Hawksearch = Hawksearch || {};

      Hawksearch.config = {
        clientId: "f51060e1c38446f0bacdf283390c37e8"
      };
    </script>
    <script src="//cdn.jsdelivr.net/npm/@bridgeline-digital/hawksearch-handlebars-ui@1.0.10/dist/hawksearch-handlebars-ui.js" defer></script>
  </head>

  <body>
    <h1>Hawksearch Handlebars UI</h1>
    <hawksearch-search-field></hawksearch-search-field>
    <hawksearch-search-results></hawksearch-search-results>
  </body>
</html>

It is highly recommended to target a specific version, especially if there are customizations, to avoid potentially breaking changes in the future.

For example, instead of including the script at https://cdn.jsdelivr.net/npm/@bridgeline-digital/hawksearch-handlebars-ui/dist/hawksearch-handlebars-ui.js, you can use https://cdn.jsdelivr.net/npm/@bridgeline-digital/hawksearch-handlebars-ui@1.0.0/dist/hawksearch-handlebars-ui.js.

Configuration

Configuration is controlled by the Hawksearch.config global object. Below is the object model used:

interface HawksearchConfig {
    clientId: string;
    breakpoints?: {
        tablet: number;
        desktop: number;
    };
    css?: {
        customStyles?: string | Array<string>;
        defaultStyles?: boolean;
    };
    endpoints?: {
        search: string;
        tracking: string;
    };
    fieldMappings?: {
        description?: string;
        imageUrl?: string;
        price?: string;
        salePrice?: string;
        title?: string;
        type?: string;
        url?: string;
    };
    formatting?: {
        cultureIsoCode?: string;
        currencyIsoCode?: string;
    };
    placeholderImageUrl?: string;
    queryStringMappings?: {
        disableSpellcheck?: string;
        facet?: string;
        page?: string;
        pageSize?: string;
        query?: string;
        searchWithin?: string;
        sort?: string;
    };
    templates?: HawksearchTemplates;
    trackingEnabled?: boolean;
    urlPrefixes?: {
        assets?: string;
        content?: string;
    };
}

General

Property	Required	Default Value
`clientId`	Yes		The ID of your Hawksearch installation
`placeholderImageUrl`	No		The URL of an image to load if the image associated with a search result fails to load
`trackingEnabled`	No	`true`	Allows you to specify whether user actions are tracked for analytical purposes

Breakpoints

These values are used to identify which breakpoints are used to target different device types. This is used to determine which content items are displayed in Content Zone components.

Property	Required	Default Value
`breakpoints.tablet`	No	740
`breakpoints.desktop`	No	990

These values should only need to be entered if using a completely custom user interface as the default values align with the default CSS styles.

CSS

The components included in this library utilize the Shadow DOM which means they do not inherit styles from the page they are included on. The following properties enable CSS customization:

Property	Required	Default Value	Description
`css.customStyles`	No		To load a custom stylesheet into the Shadow DOM for use with this library, you can assign either a URL or an array of URLs to this property.
`css.defaultStyles`	No	`true`	A simple, generic layout is provided out-of-the-box. For heavily-customized implementations, this property can be set to `false` to prevent loading the default styles.

Endpoints

By default, this library points to the default development server. When ready to promote your implementation to another environment, you can override these values to use the URLs provided by your Hawksearch team.

Property	Required
`endpoints.search`	No
`endpoints.tracking`	No

Field Mappings

The components used in this library rely on several properties that are common to all implementations. These options allow you to specify which attributes of each item are mapped to each property if different from the default values.

Property	Required	Default Value	Description
`fieldmappings.description`	No	`longdescription`	Description
`fieldMappings.imageUrl`	No	`image`	Primary image URL
`fieldMappings.price`	No	`price`	The optional, original price of a product
`fieldMappings.salePrice`	No	`saleprice`	The current price of a product
`fieldMappings.title`	No	`itemname`	Name
`fieldMappings.type`	No	`type`	Type of an item (product, content, etc.)
`fieldMappings.url`	No	`url`	Primary URL

The value referred to by fieldMappings.type will result in a search result’s type property being set to product only if the value is Item or Product. All other values will resolve to content. For more information, see Search Results Items.

Formatting

Some values, such as numbers, dates, and currencies, are displayed differently depending on the location or target audience of a store or website. The following properties allow you to configure the way that these values are displayed:

Property	Required	Default Value
`culture.cultureIsoCode`	No	`en-US`
`culture.currencyIsoCode`	No	`USD`

Query String Parameters

When users perform actions such as executing a search, applying a facet, or moving to a different page in the search results, the state is stored in the query string of the current page. The following properties allow you to customize the parameter names:

Property	Required	Default Value
`queryStringMappings.disableSpellcheck`	No	`disableSpellcheck`
`queryStringMappings.facet`	No	`facet`
`queryStringMappings.page`	No	`page`
`queryStringMappings.pageSize`	No	`pageSize`
`queryStringMappings.query`	No	`query`
`queryStringMappings.searchWithin`	No	`searchWithin`
`queryStringMappings.sort`	No	`sort`

The queryStringMappings.facet value is a prefix, not a standalone parameter. For example, if a facet value for the color field is selected, the query string parameter would become facet-color.

Templates

Each Component allows its default property to be overrided. To do this, you set the following properties to either a Handlebars template string, or the ID of a template element containing a Handlebars template:

interface HawksearchTemplates {
    checkboxListFacet?: string;
    colorFacet?: string;
    contentZone?: string;
    customContent?: string;
    datePicker?: string;
    dateRangeFacet?: string;
    facetsList?: string;
    facetWrapper?: string;
    featuredItemsContent?: string;
    featuredItemsContentItem?: string;
    icon?: string;
    imageContent?: string;
    linkListFacet?: string;
    modifiedQuery?: string;
    numericRangeFacet?: string;
    pageSize?: string;
    pagination?: string;
    popularQueriesContent?: string;
    querySuggestions?: string;
    rangeSlider?: string;
    rangeSliderFacet?: string;
    recentSearchesFacet?: string;
    relatedSearchesFacet?: string;
    searchField?: string;
    searchResults?: string;
    searchResultsItem?: string;
    searchResultsList?: string;
    searchWithinFacet?: string;
    selectedFacets?: string;
    sorting?: string;
    tabs?: string;
    tooltip?: string;
}

URL Prefixes

Depending on your search configuration, URL values may be stored as fully-qualified URLs or relative URLs. In the case of relative URLs, you can use these properties to prepend a value to generate a fully-qualified URL:

Property	Required	Description
`urlPrefixes.assets`	No	This value is prepended to assets uploaded through the Hawksearch admin, such as color swatch images.
`urlPrefixes.content`	No	This value is prepended to `imageUrl` and `url` properties.

Events

Global

hawksearch:initialized

This event is fired after the Hawksearch Handlebars UI has been loaded. Developers can hook into this event to define custom Handlebars partials.

addEventListener('hawksearch:initialized', (event) => {
    Hawksearch.handlebars.registerPartial('custom-partial', 'HTML here');
});

Autocomplete

hawksearch:before-autocomplete-executed

This event is fired before every autocomplete query. This can be used to modify the raw request sent to the Hawksearch API.

addEventListener('hawksearch:before-autocomplete-executed', (event) => {
    const autocompleteRequest = event.detail;

    console.log(autocompleteRequest);
});

hawksearch:after-autocomplete-executed

This event is fired after every autocomplete query. This can be used to modify the raw request sent to the Hawksearch API.

addEventListener('hawksearch:after-autocomplete-executed', (event) => {
    const autocompleteResponse = event.detail;

    console.log(autocompleteResponse);
});

hawksearch:autocomplete-completed

This event is fired after every autocomplete query prior to data binding.

addEventListener('hawksearch:autocomplete-completed', (event) => {
    const autocompleteResponse = event.detail;

    console.log(autocompleteResponse);
});

This object is the processed AutocompleteResponse model, not the raw response from Hawksearch.

Search

hawksearch:before-search-executed

This event is fired after before every search operation. This can be used to modify the raw request sent to the Hawksearch API.

addEventListener('hawksearch:before-search-executed', (event) => {
    const searchRequest = event.detail;

    console.log(searchRequest);
});

hawksearch:after-search-executed

This event is fired after every search operation. This can be used to modify the raw request sent to the Hawksearch API.

addEventListener('hawksearch:after-search-executed', (event) => {
    const searchResponse = event.detail;

    console.log(searchResponse);
});

hawksearch:search-completed

This event is fired after every search operation prior to data binding.

addEventListener('hawksearch:search-completed', (event) => {
    const searchResponse = event.detail;

    console.log(searchResponse);
});

This object is the processed SearchResponse model, not the raw response from Hawksearch.