@interopio/search-api
v2.4.3
Published
Glue42 Search API
Downloads
1,410
Readme
IO Connect Search API
Apps can perform searches and provide results for others' searches.
For example, let's say an app provides Seinfeld quotes, and wants to make those quotes available to any other app. The Seinfeld app could register itself as a search provider with this:
// Registering as a provider
const provider = await glue.search.registerProvider({
name: "Seinfeld-Quotes"
});
// Registering how the provider will respond to queries
provider.onQuery(({search, sendResults, done}) => {
const textOfQuote = doStuffInternally(search);
sendResults({
type: {
name: "tv-quote",
displayName: "Seinfeld Quotes"
},
id: "quote-123",
description: textOfQuote
});
done();
})
Now, let's say an app is interested to see if there are any Seinfeld quotes with the word "architect". It would use the following function:
const query = await glue.search.query({search: "architect"});
query.onResults((result) => {
/*
// Example value for result -
{
provider: {
id: "INTERNAL_ID",
interopId: "INTERNAL_INSTANCE_ID",
name: "Seinfeld-Quotes" // The search provider's name
appName: "seinfeld-app", // The app that registered the search provider
},
result: {
type: {
name: "tv-quote",
displayName: "Seinfeld Quotes"
},
id: "quote-123",
description: "You know I always wanted to pretend I was an architect.
}
}
*/
})
Checklists
If you're writing a custom search provider, here are things to make sure you implement:
Basics
- [ ] Registering provider
- [ ] Generate and send results
Other considerations:
- [ ] Call
done()
once you are done (in case queriers are waiting ononCompleted()
) - [ ] Are you checking the
types
property? You don't want to ignore the restrictions the querier placed on their query. - [ ] Are you checking the
maxResults
property? You don't want to return more that the querier asked for. - [ ] Ditto for
maxResultsByType
- [ ] Did you set up error handling, and include the
error()
callback if necessary? - [ ] Do your queries take a long enough time that they might get cancelled? If so, are you handling
onQueryCancel
?
If you're querying a search providerm here are things to make sure you implement:
- [ ] Call the query (eg
const query = await glue.search.query({search: "My search string"})
) - [ ] Handle
onResults
(egquery.onResults(displaySearchResult)
) - [ ] Handle
onError
Other considerations:
- [ ] Is there a situation where you need to
cancel()
your query? - [ ] Do you need to limit the quantity of results you receive (using
providerLimits
)? - [ ] Do you need
onCompleted
, to see when different search providers have finished? If so, does it also make sense to include a timeout (in case a search provider doesn't indicate when they'redone()
?) - [ ] Are you interested in only certain types of content? Would it make sense to call
listTypes()
to see if the type you're looking is being provided? Would it makse sense to limit your search results to a certain type? - [ ] Are you interested in only certain providers? Would it make sense to call
listProviders()
to see if the provider you're looking is present? Would it makse sense to limit your search results to certain providers? - [ ] Sometimes, search results include
actions
. If that makes sense for your use cases, are you handling incoming actions?
API
glue.search has the following methods:
- getDebounceMS
- listProviders
- listTypes
- query
- registerProvider
- setDebounceMS
- version
registerProvider
Config options for .registerProvider()
are:
name
(required)types
(optional but recommended). If you register a custom type, it will appear in the.listTypes
method.
const provider = await glue.search.registerProvider({name: "test"});
const provider = await glue.search.registerProvider({
name: "test",
types: [
{name: "application"}
]
});
registerProvider
returns a promise that resolves to a Provider
object. This has the following available methods:
onQuery
- callback when search queries are executedonQueryCancel
- callback when an app cancels its search queryunregister
- an unregistration method.
:::tip Search providers are automatically unregistered when windows are closed. Unregistration is a good cleanup action, but may not be required. :::
The onQuery
callback provides a ProviderQuery
object, with the following properties:
- id - referenced when cancelling the query
- search - the text being searched for
- providers - the providers the querier is interested in
- types - the SearchTypes the querier is interested in
- providerLimits.maxResults - the maximum number of results the querier wants to receive from each provider
- providerLimits.maxResultsPerType - the maximum number of results PER TYPE the querier wants to recevie from each provider
- sendResult - callback for sending an individual result. (The querier receives this with the
query.onResults()
callback) - error - callback if there's an error (The querier receives this with the
query.onError()
callback) - done - callback once all results have been sent (The querier receives this with the
query.done()
callback)
When sending a result, you supply a QueryResult
object. The properties of that object are:
- type (required) - a
SearchType
(eg:{name: "application"}
) - id
- displayName
- description
- iconURL
- metadata
- action - metadata information about a method you'd want to invoke
- secondaryActions - more actions
query
You create a query object with the query()
method:
const query = await glue.search.query({search: "My search query"});
The query
method takes the following properties:
search
(required) (string) - what you're searching forproviders
(ProviderData[]
) - providers you want to limit your search totypes
(SearchType[]
) - the types of results you want to limit your search toproviderLimits.maxResults
(number) - the maximum number of results the querier wants to receive from each providerproviderLimits.maxResultsPerType
(number) - the maximum number of results PER TYPE the querier wants to recevie from each provider
The query object you receive has the following methods:
cancel()
- Cancels the query. (See provider'sonQueryCancel()
)onResults()
- Callback to receive results (See provider's query handling forsendResult()
)onCompleted()
- Callback when provider is done (See provider's query handling fordone()
)onError()
- Callback when provider has an error (See provider's query handling forerror()
)
listProviders
await glue.search.listProviders();
/*
Example results: [
{
appName: "fsbl-test-butler",
id: "INTERNAL_ID",
interopId: "INSTANCE_ID",
name: "registered-search-provider-custom-name",
},
{
appName: "tester",
id: "INTERNAL_ID",
interopId: "INSTANCE_ID",
name: "my-tester",
types: [{name: "test-type"}]
}
]
*/
listTypes
You can see what search types are available. This is especially useful if you are relying on a custom search type from another app, and want to confirm that that app has already been registered.
await glue.search.listTypes();
/*
Example results: [
{name: "customSearchType"},
{name: "application"},
{name: "layout"},
{name: "workspace"},
{name: "swimlane"},
{name: "action"}
]
*/
getDebounceMS, setDebounceMS
Default debounce: 0ms
Queries can be debounced. If you plan on querying based on individual keystrokes or mouse movements, you can potentially generate an unnecessarily large message flurry. Debouncing the queries will reduce search query traffic.
Here are examples of getting/setting the debounce time:
// Get the debounce time:
glue.search.getDebounceMS(); // returns 0 by default
// Set the debounce time to 20ms:
glue.search.setDebounceMS(20);
Actions
TBD
Developer notes
/* eslint-disable @typescript-eslint/no-explicit-any */
// package name: @interopio/search-api -> adds the Search API
// @interopio/browser-platform -> can use the package to register as a provider or use as a client, by default register as a provider for applications, workspaces, layouts and optionally actions // @interopio/browser -> can use the package to register as a provider or use as a client // GD3 -> by default register as a provider for applications, workspaces, layouts and optionally actions
// Foundation: Interop and Shared Context // lib registers: lazily two methods // lib uses: shared context to providers state management // method used when registered as provider to accept queries
// category = display name for type