Versions Compared

Old Version 23

changes.mady.by.user Jordan Kasper

Saved on

compared with

New Version Current

changes.mady.by.user Jordan Kasper

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
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

  1. If your website does not already have a package.json file in the root, run npm init to generate one.

  2. Run npm install --save @bridgeline-digital/hawksearch-handlebars-ui to install the latest version.

  3. 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
    languagehtml
    <!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-

...

  1. field></hawksearch-search-

...

  1. 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:

Code Block
languagehtml
<!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.19/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>
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://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:

Code Block
languagetypescript
interface HawksearchConfig {
    clientId: string;
    breakpoints?: {
        tablet: number;
        desktop: number;
    };
    css?: {
        customUrlcustomStyles?: 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

css.customUrlcustomStyles

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.

...

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
languagetypescript
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
languagejs
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
languagejs
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
languagejs
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
languagejs
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.

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