Legacy version 6 documentation. View current documentation.Legacy version 6 documentation. View current documentation.
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 recommend 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 search providers.
This method takes an object with a property of text and a function that is called as results are returned.
Here is an example query:
FSBL.Clients.SearchClient.search({text:"example"},function(err, response){
if(err) { console.err(err) }
else {
console.log("Array of providers and their responses\n",JSON.stringify(response,null,2));
}
});
This query returns an array of providers and the responses from each. It can be called many times per search and the callback function will get called multiple times as as more providers respond.
The first response might look like this:
[
{
"provider": {
"displayName": "Installed Workspaces",
"channel": "workspaceService.Installed Workspaces",
"providerActionCallback": true
},
"returnCallback": "Toolbar-1.Installed Workspaces",
"searchId": "898c7c4b-f383-4a7a-b090-800a9f2eadea",
"data": [
{
"score": 0,
"matches": [
{
"indices": [
[
0,
6
]
],
"value": "example"
}
],
"name": "example",
"type": "Workspace",
"description": "",
"actions": [
{
"name": "Switch"
}
],
"tags": [],
"provider": "workspaceService.Installed Workspaces"
}
]
}
]
The next response might be like this:
[
{
"provider": {
"displayName": "Installed Workspaces",
"channel": "workspaceService.Installed Workspaces",
"providerActionCallback": true
},
"returnCallback": "Toolbar-1.Installed Workspaces",
"searchId": "898c7c4b-f383-4a7a-b090-800a9f2eadea",
"data": [
{
"score": 0,
"matches": [
{
"indices": [
[
0,
6
]
],
"value": "example"
}
],
"name": "example",
"type": "Workspace",
"description": "",
"actions": [
{
"name": "Switch"
}
],
"tags": [],
"provider": "workspaceService.Installed Workspaces"
}
]
},
{
"provider": {
"displayName": "Installed Components",
"channel": "Finsemble.Installed Components",
"providerActionTitle": null,
"providerActionCallback": true
},
"returnCallback": "Toolbar-1.Installed Components",
"searchId": "898c7c4b-f383-4a7a-b090-800a9f2eadea",
"data": [
{
"name": "ChartIQ Example App",
"displayName": "ChartIQ Example App",
"score": 0.05422079049974018,
"matches": [
{
"indices": [
[
2,
2
],
[
8,
14
]
],
"value": "ChartIQ Example App",
"key": "component.displayName"
},
{
"indices": [
[
2,
2
],
[
8,
14
]
],
"value": "ChartIQ Example App",
"key": "component.type"
}
],
"icon": {
"type": "fonticon",
"path": "ff-chart-advanced"
},
"type": "Application",
"description": "",
"actions": [
{
"name": "Spawn"
}
],
"tags": [],
"provider": "Finsemble.Installed Components"
},
{
"name": "AG-Grid Example Blotter",
"displayName": "AG-Grid Example Blotter",
"score": 0.05422079049974018,
"matches": [
{
"indices": [
[
0,
0
],
[
8,
14
]
],
"value": "AG-Grid Example Blotter",
"key": "component.displayName"
},
{
"indices": [
[
0,
0
],
[
8,
14
]
],
"value": "AG-Grid Example Blotter",
"key": "component.type"
}
],
"icon": {
"type": "url",
"path": "https://assets.finsemble.com/components/ag-grid/ag-grid-logo.png"
},
"type": "Application",
"description": "",
"actions": [
{
"name": "Spawn"
}
],
"tags": [],
"provider": "Finsemble.Installed Components"
}
]
}
]
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.
The Search API allows for any Finsemble window to act as a search provider or query against the registered providers.Further details of the API can be found in Search Client API.