Advanced Javascript Usage

If you don't want to let Stork's Javascript library handle the DOM manipulation and file retrieval, or if you want more control over when those events happen on your webpage, you can use Stork's advanced Javascript API to programmatically manage how your webpage interacts with Stork.

To begin, you'll still need to load the Stork Javascript library onto your webpage using the script tag below or by self-hosting Stork:

<script src="https://files.stork-search.net/releases/v1.6.0/stork.js"></script>
<!-- Or -->
<script src="https://your-url.com/stork@v1.6.0.js"></script>

There are three "lifecycle" methods when working with the Stork frontend: initialization, index registration, and, if you choose, DOM attachment. These three events must take place in order, but each can be safely retried.

Initialization

To download and load the WASM blob, call:

stork.initialize()

This will load the WASM from the Stork CDN. If you are self-hosting Stork, you can pass in an optional parameter that defines the location of the WASM blob, which must be hosted with the MIME type application/wasm:

stork.initialize('https://your-url.com/stork@v1.6.0.wasm')

The initialize() method returns a promise that will succeed when initialization succeeds, and will fail when initialization fails.

Index registration

You can kick off the next process, index registration, before the initialize method's promise has completed. Registering an index will download and cache the search index, a file that you need to have generated beforehand using the Stork command-line tool.

stork.downloadIndex("yourIndexName", "https://your-url.com/index-file.st")

This method takes the same three arguments that stork.register() takes. Like the initialization method, the downloadIndex() method also returns a promise that succeeds when the index has been downloaded, and fails when the index fails to download.

If an index has already been successfully downloaded with the given identifier, Stork will not re-download and re-parse the index file; it will succeed the returned promise without performing any operations. To force Stork to overwrite the index, pass in the following configuration option:

stork.downloadIndex(
    "yourIndexName", 
    "https://your-url.com/index-file.st",
    { forceOverwrite: true }
)

Attaching to the DOM

Like registration, you can attach Stork to the DOM before the WASM is downloaded or the index is downloaded. To attach Stork to the DOM, make sure you have elements that exist in your DOM in this format:

<input data-stork="yourIndexName" />
<div data-stork="yourIndexName-output"></div>

where foo is the name with which you registered a Stork index. Then, you can register Stork by calling:

stork.attach("yourIndexName")

Stork will display loading and error states as part of the <input>, and will handle user input and display search results automatically.

This method does not return a value; it will throw if there is no HTML to which it can attach.

Calling this method while Stork is already attached to existing DOM methods will remove and re-attach Stork. Calling this method after another script has removed the Stork-handled DOM elements is safe; Stork will remove the event listeners so they do not leak.

Manually building a Stork interface

If you don't want to use the Stork DOM, you can call stork.search() to search an index. The method will return an array of results (see the Javascript API reference for more details) which you can insert onto your page however you see fit.

stork.search("yourIndexName", "search query")

It is an error to call this method before the initialization and registration promises have completed successfully.