openfin-search-api v1.0.4

OpenFin Search API

The OpenFin Search API is a framework for searching, fetching, aggregating and actioning data through application interopability.

Getting Started

There are two options for using this package.

Import the NPM package:

import "openfin-search-api";

Or import the script fron our CDN.

<script src="https://cdn.openfin.co/openfin-search-api/index.js" />

Searching for Data

// Subscribe to a search topic.
const searchTopic = await fin.Search.subscribe("foo");

/* Search for data with query `bar`.
   This will return a generator which can be called multiple times 
   while their are pending responses from search data providers. */
const generator = searchTopic.search("bar");
while(true) {
    const { value, done } = await generator.next();

    // Default algorithm for aggregating search results for multiple providers.
    const results = fin.Search.aggregate(value);

    // Implementation specifc rendering logic.
    render(results);

    // If done is true, all search providers have responded with their data.
    if (done) {
        break;
    }
}

Actioning Search Results

// Subscribe to a search topic.
const searchTopic = await fin.Search.subscribe("foo");

// Get search results.
const generator = searchTopic.search("bar");
const { value } = await generator.next();
const results = fin.Search.aggregate(value);

/* Sends the first search result in the response back to the 
   respective provider, such that the provider can action the result. */
const firstSearchResult = results[0];
await firstSearchResult.dispatch();

Registering a Search Data Provider

// Example backend query.
function getSearchResults(query) {
    const res = await fetch("/search?q=" + encodeURIComponent(query));
    if (!res.ok) {
        throw new Error("uh oh something went wrong");
    }
    const json = await res.json();

    /* All results must have the `name` and `description` 
       field at the very least for rendering purposes. */
    return json.map(myResult => ({
        name: myResult.nameAttribute,
        description: myResult.descriptionAttribute,
        data: myResult.customMetadata
    }));
}

// Example function for actioning a result from `getSearchResults`.
function openWindowForSearchResult(result) {
    window.open(result.data.url);
}

// Subscribe to a search topic.
const searchTopic = await fin.Search.subscribe("foo");

/* The `name` and `onSearch` attributes are required for a data provider.

   The `onSearch` function will be called back when the topic is searched 
   on. (ex. `searchTopic.search(query)`)

   The `onResultDispatch` function will be called back when a search result 
   is dispatched. (ex. `searchResult.dispatch()` is called.) */
const provider = { 
    name: "bar", 
    onSearch: getSearchResults, 
    onResultDispatch: openWindowForSearchResult 
};

/* Register a search data provider. 
 
   When someone calls `searchTopic.search("my query")` 
   the `onSearch` function will be called back for the provider.
   
   If `searchResult.dispatch()` is called on a search result 
   generated by this provider `onResultDispatch` will be called back. */ 
await searchTopic.register(provider);

Control Search Topic Subscriptions

const searchTopic = await fin.Search.create("foo");

// Only hosts in the list can subscribe to the search topic.
const allowedHosts = ["www.vendor.com"];
searchTopic.onSubscription(identity => {
    // Get the URL of the subscribing identity.
    const info = await fin.View.wrapSync(identity).getInfo();
    const url = new URL(info.url);

    if (allowedHosts.findIndex(url.host) === -1) {
        // Throwing an error will deny the subscription.
        throw new Error("Not authorized to subscribe to `foo` search topic.");
    }
});