StaticSearch bind module

The JavaScript bind module can automatically or programmatically attach StaticSearch functionality to HTML <input> and result elements. Use it in situations where you want to create your own search widget using StaticSearch functionality including:

• <input> debouncing and initiating calls to the search API
• displaying results
• handling the URL querystring and hash when clicking a result link followed by the back button.

The bind module used by the web component so the processes are similar.

The following example automatically binds <input> and results elements using HTML alone:

<!-- include script once on your page -->
<script type="module" src="/search/staticsearch-bind.js"></script>

<!-- define input and result elements -->
<search>

  <input type="search" id="staticsearch_search">
  <div id="staticsearch_result"></div>

</search>

Input field attributes #

The <input> field must use the ID staticsearch_search but can have any other HTML attributes set.

StaticSearch presumes the name is q and checks its value on the querystring. You can set any other value, e.g.

<input type="search" id="staticsearch_search" name="query">

Search result attributes #

The results element must use the ID staticsearch_result but can set optional attributes:

Search results provide a found value indicating the percentage of search words found on a page, e.g. two of four search words is 0.5.

• setting minfound="0" (the default) is a logical OR. A page appears in results when it contains ANY of the search words.

• setting minfound="1" is a logical AND. A page appears in results when it contains ALL the search words.

• setting minfound="0.5" means a page appears in results when it contains at least half of the search words.

Pages still appear in relevancy order, but higher minfound values will reduce the number of results.

Overriding HTML templates #

You can change the HTML shown when displaying results using <template> elements.

Search results message #

When search results are available, you’ll see a message such as:

7 found for “web component”…

It uses the HTML code:

<p part="resultmessage">
  <span part="resultcount"></span> found for
  <span part="searchterm"></span>&hellip;
</p>

You can override this using a <template> with an ID of staticsearch_resultmessage anywhere in your HTML page. You must set the part attributes "resultmessage", "resultcount", and "searchterm" as necessary, e.g.

<template id="staticsearch_resultmessage">

  <p part="resultmessage">
    StaticSearch found
    <span part="resultcount"></span> results
    for <span part="searchterm"></span>:
  </p>

</template>

Search result item #

An ordered list (<ol part="searchresult">) contains search results. Each page result uses the HTML:

<li part="item">
  <a part="link">
    <h2 part="title"></h2>
    <p part="meta">
      <time part="date"></time> &ndash;
      <span part="words">0</span> words
    </p>
    <p part="description"></p>
  </a>
</li>

You can override this using a <template> with an ID of staticsearch_item anywhere in your HTML page. Set the part attributes "item", "link", "title", meta, date, words, and "description" as necessary, e.g. show the title but no description, date, or word count in an <article>:

<template id="staticsearch_item">

  <li part="item">
    <article>
      <h2 part="title"><a part="link"></a></h2>
    </article>
  </li>

</template>

JavaScript binding #

You can programmatically bind StaticSearch functionality to <input> and result element using JavaScript. This may be useful if you want further control or you’re using a client-side framework to dynamically create content. Consider a page with the following HTML:

<search>

  <input type="search" id="mysearch">
  <div id="myresult"></div>

</search>

Bind the elements to StaticSearch using code such as:

import { staticSearchInput, staticSearchResult } from '/search/staticsearch-bind.js';

staticSearchInput( document.getElementById('mysearch') );
staticSearchResult( document.getElementById('myresult') );

Pass the <input> element to staticSearchInput(element).

Pass the result element and an optional options object to staticSearchResult(element, options). The option object properties:

Example usage:

// custom results message
const messageTemplate = document.createElement('template');
messageTemplate.innerHTML = `
  <p part="resultmessage">
    <span part="resultcount">0</span> results found for
    <span part="searchterm"></span>:
  </p>
`;

// bind results element
staticSearchResult(
  document.getElementById('myresult'),
  {
    minFound: 0.5,  // at least half the search terms must be on a page
    minScore: 5,    // minimum relevancy score
    maxResults: 10, // maximum number of results
    messageTemplate // DOM <template> defined above
  }
);

Re-run the indexer #

Once you have added StaticSearch functionality to your static site’s templates, you should re-run the indexer to ensure word indexes are up-to-date.