Home overview
OpenFin Home
As part of OpenFinWorkspace, the Home component helps users find content they want to open and information provided by applications or platforms registered with OpenFin Home. A Workspace platform can register a content provider with Home to provide whatever their users need to perform their work.
To make content available, an application or platform begins by registering a HomeProvider
. If multiple providers are registered with OpenFin Home, their entries are shown in the Home toolbar.
The HomeProvider
interface extends the CLIProvider
interface. In the current version of Workspace, these interfaces are identical, and some examples call CLIProvider
, while others call HomeProvider
. A best practice is to work with HomeProvider
to make sure your providers are compatible with future versions.
A HomeProvider can do the following:
- Integrate with OpenFin Home.
- Return customizable search results to Home, which can include suggested searches and filtering options. In Workspace 8.0, search results can be returned asynchronously, to improve performance. For details about how to work with the new APIs for this feature, see Support asynchronous search results.
- Give the user control over searches by carrying out searches with the selected provider.
- Set a logo icon to be displayed when the provider is selected.
Get started
The basic steps:
-
Implement the
HomeProvider
interface (orCLIProvider
). -
Register your provider with the HomeApi.
Prerequisites
Node and npm.
Install and import
-
Install the Workspace npm package:
npm i -E @openfin/workspace
-
Import OpenFin Workspace:
import { Home, CLIProvider, CLISearchListenerRequest, CLISearchResult, CLISearchListenerResponse, CLISearchResponse, CLIDispatchedSearchResult, App } from "@openfin/workspace";
Create your provider
-
Define and register your CLIProvider object:
const cliProvider: CLIProvider = { title: "My title, name: "My Provider name, icon: "url to icon", onUserInput: onUserInput, onResultDispatch: onResultDispatch, }; await Home.register(cliProvider);
The
onUserInput
property points to a function that is called when the user enters a search term. TheonResultDispatch
points to a function that is called when the user selects a search result. -
Create the onUserInput function:
const onUserInput = async ( request: CLISearchListenerRequest, response: CLISearchListenerResponse ): Promise<CLISearchResponse> => { const query = request.query.toLowerCase(); if (query.indexOf("/") === 0) { return { results: [] }; } // integrators list of Apps const apps: App[] = await getApps(); const results: CLISearchResult<any>[] = apps .map((app) => { return { key: app.appId, title: app.title, actions: [{ name: "launch-app", hotkey: "enter" }], data: app, template: "Plain", }; }) .filter((entry) => { return entry.title.includes(query); }); const result: CLISearchResponse = { results, }; return result; };
-
Create the onResultDispatch function:
const onResultDispatch = async (result: CLIDispatchedSearchResult) => { if (result.data !== undefined) { await launchApp(result.data); } else { console.warn("Unable to execute result without data being passed"); } };
The full source code
Here is a complete file for creating and registering a CLI Provider. See the Workspace Starter example for the full context for this file.
import { Home, CLIProvider, CLISearchListenerRequest, CLIFilter, CLISearchResult, CLISearchListenerResponse, CLISearchResponse, CLIDispatchedSearchResult, launchApp } from "@openfin/workspace";
import { getApps } from "./apps";
const providerName = "register-with-home-basic";
async function getResults(query?: string) : Promise<CLISearchResponse> {
let apps = await getApps();
if(Array.isArray(apps)){
let initialResults: CLISearchResult<any>[] = [];
for(let i = 0; i < apps.length; i++) {
if(apps[i].description !== undefined) {
let entry: any = {
key: apps[i].appId,
title: apps[i].title,
actions: [{ name: "launch-app", hotkey: 'enter' }],
data: apps[i],
description: apps[i].description,
shortDescription: apps[i].description,
template: "SimpleText",
templateContent: apps[i].description,
};
initialResults.push(entry);
} else {
let entry: any = {
key: apps[i].appId,
title: apps[i].title,
actions: [{ name: "launch-app", hotkey: 'enter' }],
data: apps[i],
template: "Plain"
};
initialResults.push(entry);
}
}
let finalResults;
if(query === undefined || query === null || query.length === 0) {
finalResults = initialResults;
} else {
finalResults = initialResults.filter(entry => {
let targetValue = entry.title;
if(targetValue !== undefined && targetValue !== null && typeof targetValue === "string") {
return targetValue.toLowerCase().indexOf(query) > -1;
}
return false;
});
}
let response: CLISearchResponse = {
results: finalResults
};
return response;
} else {
return {
results:[]
};
}
}
export async function register(): Promise<void> {
console.log("Initialising home.");
const queryMinLength = 3;
const onUserInput = async (request: CLISearchListenerRequest, response: CLISearchListenerResponse): Promise<CLISearchResponse> => {
let query = request.query.toLowerCase();
if(query.indexOf("/") === 0) {
return {results: [] };
}
if(query.length < queryMinLength) {
return getResults();
}
return getResults(query);
};
const onSelection = async (result:CLIDispatchedSearchResult) => {
if (result.data !== undefined) {
await launchApp(result.data);
} else {
console.warn("Unable to execute result without data being passed");
}
};
const cliProvider:CLIProvider = {
title: "Basic Workspace Platform",
name: providerName,
icon: "http://localhost:8080/favicon.ico",
onUserInput: onUserInput,
onResultDispatch: onSelection,
};
console.log("Home configured.");
return Home.register(cliProvider);
}
export async function deregister() {
return Home.deregister(providerName);
}
export async function show() {
return Home.show();
}
export async function hide() {
return Home.hide();
}
Updated 7 days ago