Note
This documentation is for v1 of the HawkSearch Handlebars UI and is no longer updated. For the latest version, please see http://handlebars-ui.hawksearch.com.

Table of Contents

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:

Code Block

language	html

<!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 unpkg 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:

Code Block

language	html

<!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="https://wwwcdn.unpkgjsdelivr.comnet/npm/@bridgeline-digital/hawksearch-handlebars-ui@1.0.19/dist/hawksearch-handlebars-ui.js" defer></script>
  </head>

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

Info

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://wwwcdn.unpkgjsdelivr.comnet/npm/@bridgeline-digital/hawksearch-handlebars-ui/dist/hawksearch-handlebars-ui.js, you can use https://wwwcdn.unpkgjsdelivr.comnet/npm/@bridgeline-digital@1.0.0digital/hawksearch-handlebars-uiui@1.0.0/dist/hawksearch-handlebars-ui.js.

Configuration

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

Code Block

language	typescript

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;
    };
    searchUrl?: string;
    templates?: HawksearchTemplates;
    trackingEnabled?: boolean;
    urlPrefixes?: {
        assets?: string;
        content?: string;
    };
}

...

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
`searchUrl`	No	`/search`	The URL of the search results page
`trackingEnabled`	No	`true`	Allows you to specify whether user actions are tracked for analytical purposes

...

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

...

Code Block

language	typescript

export interface HawksearchTemplates {
    autocomplete?: string;
    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;
    searchsearchField?: string;
    searchResults?: string;
    searchResultsItem?: string;
    searchResultsList?: string;
    searchWithinFacet?: string;
    selectedFacets?: string;
    sorting?: string;
    tabs?: string;
    tooltip?: string;
}

...

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 fires is fired after the Hawksearch Handlebars UI has been loaded. Developers can hook into this event to define custom Handlebars partials.

Code Block

language	js

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.

Code Block

language	js

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 response received from the Hawksearch API.

Code Block

language	js

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.

Code Block

language	js

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

    console.log(autocompleteResponse);
});

Info
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.

Code Block

language	js

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

    console.log(searchResponsesearchRequest);
});

hawksearch:after-search-

...

executed

This event is fired after every search operation (query, applied facet, etc.). This can be used to modify the raw response received from the Hawksearch API.

Code Block

language	js

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.

Code Block

language	js

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

    console.log(searchResponse);
});

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

Versions Compared

Old Version 26

New Version Current

Key

Installation Steps

npm Package

Content Delivery Network (CDN)

Configuration

Events

Global

hawksearch:initialized

Autocomplete

hawksearch:before-autocomplete-executed

hawksearch:after-autocomplete-executed

hawksearch:autocomplete-completed

Search

hawksearch:before-search-executed

hawksearch:after-search-

executed

hawksearch:search-completed

Page Comparison

Versions Compared

Old Version 26

New Version Current

Key

Installation Steps

npm Package

Content Delivery Network (CDN)

Configuration

Events

Global

hawksearch:initialized

Autocomplete

hawksearch:before-autocomplete-executed

hawksearch:after-autocomplete-executed

hawksearch:autocomplete-completed

Search

hawksearch:before-search-executed

hawksearch:after-search-

executed

hawksearch:search-completed