Support complex search queries programmatically

In Workspace 10 and later, you can pass a search query string to Home with a new API. This lets you include a query builder app in your OpenFin implementation, for example, and pass the queries your users create with the app as strings to the Workspace API.

How it works

When you register a Home provider, a HomeRegistration object is returned that includes a new setSearchQuery function.

You generate a search query string with whatever tools are appropriate to your environment -- a query builder form, for example. Make sure that the queries your tooling generates are rendered to strings. You then pass the appropriate search query string to the setSearchQuery function. You specify the search results for your user's query as the value of the onUserInput method you include when you register your HomeProvider.

For details and for an example that includes the case of multiple home providers, see the related API reference.

You can call the setSearchQuery function only for the registered provider.


For the complete flow to register a HomeProvider, see Home overview.

When you create and register your provider, however, include the setSearchQuery function. The following example assumes that your query builder app includes the appropriate function to render search results as a string.

import Home, CLIProvider from '@openfin/workspace';
// Replace with your query builder function, or other function to represent complex search string
import { fetchMySearchResults } from "./my-fetch-implementation";
// CLIProvider or HomeProvider
const myCLIProvider: CLIProvider = {
    id: "a-home-provider",
    title: "A CLI Provider",
    icon: "",
    onUserInput: (req) => fetchMySearchResults(req.query)
// register home and get back the function to inject search string into home search
const { setSearchQuery } = await Home.register(myCLIProvider);
// Call the set query function for a specific provider the search should be injected into
// Your HTML provides the `button` ID and related functionality.
const searchButton = document.getElementById('button');
searchButton.addEventListener('click', () => {
    setSearchQuery('search string from fetchMySearchResults');