Search

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.

Registering a search provider

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");
    }
);

Receiving a search request

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.

Handling actions

There are two types of actions that a provider can handle: item action and provider action.

Item actions

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
}

Provider action

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
}

Querying search providers

Search

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

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.

invokeProviderAction

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.

See also

Further details of the API can be found in Search Client API.