The Search Client API allows for any Finsemble window to act as a search provider or query against the registered
providers. Finsemble comes prepackaged with two providers:Installed Components
and Installed Workspaces
.
The provider object is the search result item. When you register a search
provider, you're expected to provide at minimum a name
and searchCallback
. The name
will allow you to identify
which provider your search results came from. We recommended that you keep all providers inside of a service so they are
available throughout the lifetime of your Finsemble application.
FSBL.Clients.SearchClient.register(
{
name: "My Search Provider", // The name of the provider
searchCallback: providerSearchFunction, // A function called when a search is initialized
itemActionCallback: searchResultActionCallback, // (optional) A function that is called when an item action is fired
providerActionTitle: "My Provider action title", // (optional) A function that is called when a provider action is fired
providerActionCallback: providerActionCallback, // (optional) The title of the provider action
},
function (err) {
console.log("Registration succeeded");
}
);
Your searchCallback
is called when a search is initiated that includes your provider. The arguments for
searchCallback
are params
and a callback
. Currently, params
only has the one parameter: text
. text
is the
string to search against. When you return results from your search provider you should return an array of resultItems
:
//searchCallback
function providerSearchFunction(params, callback) {
var results = [resultItems];
callback(null,results); // The first argument is an error;
}
//Your return results to the callback should be an array of the following:
{
name: resultName, // This should be the value you want displayed
score: resultScore, // This is used to help order search results from multiple providers
type: "Application", // The type of data your result returns
description: "Your description here",
actions: [{ name: "Spawn" }], // Actions can be an array of actions
tags: [] // This can be used for adding additional identifying information to your result
};
The resultScore
should be a number between 0 and 100, with 0 being a complete match.
The type
can be anything you want. However, "Application"
and "Workspace"
are reserved for Finsemble components
and workspaces and should only be used for those data types.
There are two types of actions that a provider can handle: item action and provider action.
Item actions sit with each result you provide and allow your provider to control what happens when that action is
invoked. When an item action is triggered, the Search Client invokes your itemActionCallback
in the provider. You get
an object with two parameters with this callback: item
and action
. item
is the search result item that triggered
the action. action
is the item in your search result actions array that was triggered (actions:[{ name: "Spawn" }]
).
//itemActionCallback
function searchResultActionCallback(params) {
/*
params is equal to
{
item:resultItem,
action:{name:"Spawn"}
}
*/
// Do something with the action here
}
The provider action is an optional singular parameter that is at the provider level. This is any action you want to
occur at the global level for the provider. An example would be if you had an app store provider that had an option for
opening an app store component at the provider level. To receive a provider action you must pass in a function when you
register through the providerActionCallback
option. You may also provide providerActionTitle
to help with displaying
your action.
//providerActionCallback
function providerActionCallback() {
// Do something with the action here
}
You call FSBL.Clients.SearchClient.search
to query against a search provider.
This method takes an object with a property of text
and a function that is called as results are returned. This
returns a combined array of all results returned from each provider, which means it can be called many times per search.
FSBL.Clients.SearchClient.search({text:"searchTerm",function(err, response){
console.log("Array of providers and their responses",response);
}})
// This is the repsonse.
{
data:[results], // This is the array of results
provider:{
channel:providerChannel,// This is the channel used by the client to communicate back to the provider
displayName:"YourName",
providerActionCallback:Boolean,// This tells us if the provider has an action at the provider level
providerActionTitle:"Your action title",// The title to display for the action
}
searchId:"UIUD",// This is used internally to identify results returned from each provider
}
invokeItemAction
allows you to send an event back to the search provider with
the item and action you'd like to trigger. Actions are defined inside of each result item: item.actions
.
Like invokeItemAction
, invokeProviderAction
allows you to call an action
at the provider level. This action is optional and up to the provider to implement. You should pass in the provider
object that is returned with your search results.
Further details of the API can be found in Search Client API.