@bridgeline-digital/hawksearch-handlebars-ui

HawkSearch Handlebars UI v6.2.3

The HawkSearch Handlebars UI package allows you to add a highly-customizable search results page to your website powered by HawkSearch.

Installation

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:
<!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="module" src="node_modules/@bridgeline-digital/hawksearch-handlebars-ui/dist/index.js"></script>
<script type="text/javascript">
addEventListener('hawksearch:loaded', () => {
HawkSearch.init({
clientId: 'YOUR_CLIENTID_HERE'
});
});
</script>
</head>
<body>
<h1>HawkSearch Handlebars UI</h1>
<hawksearch-search-field></hawksearch-search-field>
<hawksearch-search-results></hawksearch-search-results>
<hawksearch-landing-page></hawksearch-landing-page>
</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)(models/Configuration.html), 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="module" src="//cdn.jsdelivr.net/npm/@bridgeline-digital/hawksearch-handlebars-ui/dist/hawksearch-handlebars-ui.min.js"></script>
<script type="text/javascript">
addEventListener('hawksearch:loaded', () => {
HawkSearch.init({
clientId: 'YOUR_CLIENTID_HERE'
});
});
</script>
</head>
<body>
<h1>HawkSearch Handlebars UI</h1>
<hawksearch-search-field></hawksearch-search-field>
<hawksearch-search-results></hawksearch-search-results>
<hawksearch-landing-page></hawksearch-landing-page>
<hawksearch-recommendations widget-id="WIDGET_ID_HERE"></hawksearch-recommendations>
</body>
</html>

Note: 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/index.js, you can use https://cdn.jsdelivr.net/npm/@bridgeline-digital/hawksearch-handlebars-ui@latest/dist/hawksearch-handlebars-ui.min.js.

Custom Build

If you plan to make considerable customizations, it may be preferable to compile a custom script building on top of the HawkSearch Handlebars UI library. To do this, it is recommended to use Vite by performing the following steps:

  1. Run npm create vite@latest in your console
    1. Enter a project name
    2. Select Vanilla for your framework
    3. Select TypeScript for your variant
  2. Open the newly-created project folder in your console
  3. Run npm install --save @bridgeline-digital/hawksearch-handlebars-ui to install the HawkSearch Handlebars UI package
  4. Open the project folder in your editor of choice
  5. Delete the default files created under public and src with the exception of vite-env.d.ts
  6. Create a new index.ts file under src with the following contents:
import HawkSearch from '@bridgeline-digital/hawksearch-handlebars-ui';

HawkSearch.init({
clientId: 'YOUR_CLIENTID_HERE'
});
  1. Replace the contents of index.html in the project folder with the following:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>HawkSearch Handlebars UI</title>
<script type="module" src="/src/index.ts"></script>
</head>
<body>
<h1>HawkSearch Handlebars UI</h1>
<hawksearch-search-field></hawksearch-search-field>
<hawksearch-search-results></hawksearch-search-results>
<hawksearch-landing-page></hawksearch-landing-page>
<hawksearch-recommendations widget-id="WIDGET_ID_HERE"></hawksearch-recommendations>
</body>
</html>
  1. Run npm run dev to preview your changes locally
  2. Run npm run build to generate a compiled JavaScript file which you can deploy to your website by adding a script tag:
<script type="module" src="URL_TO_UPLOADED_FILE_HERE"></script>
  1. Add your HawkSearch elements to your website:
<hawksearch-search-field></hawksearch-search-field>
<hawksearch-search-results></hawksearch-search-results>
<hawksearch-landing-page></hawksearch-landing-page>
<hawksearch-recommendations widget-id="WIDGET_ID_HERE"></hawksearch-recommendations>

Custom Templates

To create a custom component templates, perform the following steps:

  1. Create a templates folder under src or in any other structure that you like
  2. Create a .hbs (Handlebars) file in the templates folder, such as search-results-item.hbs containing your Handlebars template
  3. In your index.ts file, import the new template file with a ?raw flag and assign it to the corresponding component:
import HawkSearch from '@bridgeline-digital/hawksearch-handlebars-ui';
import searchResultsItemTemplate from './templates/search-results-item.hbs?raw';

HawkSearch.init({
clientId: 'YOUR_CLIENTID_HERE',
components: {
'search-results-item': {
template: searchResultsItemTemplate
}
}
});

Landing Pages and Recommendations

To display a landing page or recommendations instead of search results, simply replace <hawksearch-search-results></hawksearch-search-results> with <hawksearch-landing-page></hawksearch-landing-page> or <hawksearch-recommendations widget-id="YOUR_WIDGETID_HERE"></hawksearch-recommendations>.

Configuration

Configuration is set through the HawkSearch.config global object. For more information, see HawkSearchConfig.

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 response received from 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);
});

Note: This object is the processed AutocompleteResponse model, not the initial 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 response received from 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);
});

hawksearch:search-failed

This event is fired if the search operation fails due to some error.

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

console.log(searchResponseError);
});

Note: This object is the processed SearchResponse model, not the initial response from HawkSearch.

Recommendations

hawksearch:before-recommendations-executed

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

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

console.log(recommendationsRequest);
});

hawksearch:after-recommendations-executed

This event is fired after every recommendations operation. This can be used to modify the raw response received from the HawkSearch API.

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

console.log(recommendationsResponse);
});

hawksearch:recommendations-completed

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

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

console.log(recommendationsResponse);
});

Note: This object is the processed RecommendationsResponse model, not the initial response from HawkSearch.