# OpenFin Workspace Client API

The Workspace Client APIs enable custom integrations with OpenFin Workspace.

## Prerequisites

-   [Node.js](https://nodejs.org/en/) v16.0.0 or higher
-   [npm](https://www.npmjs.com/)

## Install

With npm:

```sh
$ npm i @openfin/workspace@latest
```

With yarn:

```sh
$ yarn global add @openfin/workspace
```

## Usage and Code Samples

Prior to using Workspace, a Workspace Platform must be initialized.

### Home API

-   [Overview](https://developers.openfin.co/of-docs/docs/cli-providers)
-   [API Reference](https://developer.openfin.co/workspace/docs/api/latest/modules/home.html)

```ts
import Home, CLIProvider from '@openfin/workspace';

import { fetchMySearchResults } from "./my-fetch-implementation";

const searchQueryMap: Map<string, (query: string) => void> = new Map();

// CLIProvider or HomeProvider
const myCLIProvider: CLIProvider = {
     id: "my-cli-provider",
     title: "My CLI Provider",
     icon: "https://google.com/favicon.ico",
     onUserInput: (req) => fetchMySearchResults(req.query)
};

// register home and get back a function to inject search string into home search
const { setSearchQuery } = await Home.register(myCLIProvider);

// Store set query function in a map if you're using multiple providers
searchQueryMap.set(myCLIProvider.id, setSearchQuery);

// Call the set query function for a specific provider the search should be injected into
const searchButton = document.createElement('button');
searchButton.innerHTML = 'Search';
document.body.appendChild(searchButton);

searchButton.addEventListener('click', () => {
       searchQueryMap.get('my-cli-provider')('my search string');
});

```

### Storefront API

-   [Overview](https://developers.openfin.co/of-docs/docs/provide-storefront-content)
-   [API Reference](https://developer.openfin.co/workspace/docs/api/latest/modules/store.html)

```ts
import { Storefront, StorefrontProvider } from "@openfin/workspace";

// Declare a storefront provider
const provider: StorefrontProvider = {
    id: "my-storefront-id"
    title: "My StorefrontProvider"
    icon: "https://cdn.openfin.co/demos/notifications/generator/images/icon-blue.png"
    getApps: () => {...},
    getNavigation: () => {...},
    getLandingPage: () => {...},
    getFooter: () => {...},
    launchApp: () => {...}
    };
```

Register Storefront `provider` object.

```ts
await Storefront.register(myStorefrontProvider);
```

Show Storefront.

```ts
await Storefront.show();
```

### Dock API

-   [Overview](https://developers.openfin.co/of-docs/docs/dock-overview)
-   [API Reference](https://developer.openfin.co/workspace/docs/api/latest/modules/dock.html)

```ts
const provider: DockProvider = {
    id: 'provider-id',
    title: 'Sample Dock',
    icon: 'https://www.openfin.co/favicon-32x32.png',
    buttons: [
        {
            tooltip: 'Sample Button 1',
            iconUrl: 'https://www.openfin.co/favicon-32x32.png',
            action: {
                id: 'sampleButton1'
            }
        },
        {
            type: DockButtonNames.DropdownButton,
            tooltip: 'Sample Dropdown Button',
            iconUrl: 'https://www.openfin.co/favicon-32x32.png',
            options: [
                {
                    tooltip: 'Dropdown Button 1',
                    iconUrl: 'https://www.openfin.co/favicon-32x32.png',
                    action: {
                        id: 'dropdownButton1',
                        customData: 'dropdownButton1 clicked'
                    }
                },
                {
                    tooltip: 'Dropdown Button 2',
                    iconUrl: 'https://www.openfin.co/favicon-32x32.png',
                    action: {
                        id: 'dropdownButton2',
                        customData: 'dropdownButton2 clicked'
                    }
                }
            ]
        }
    ]
};
```

Register dock `provider` object.

```ts
await Dock.register(provider);
```

Show Dock.

```ts
await Dock.show();
```

## For more information

-   [Developer guide](https://developers.openfin.co/of-docs/docs/overview-of-workspace).
-   [API reference](https://developer.openfin.co/workspace/docs/api/latest/index.html).
-   See the [workspace-starter](https://github.com/built-on-openfin/workspace-starter) project for example code.
-   See the [versions page](https://developer.openfin.co/versions/#/?product=Workspace) for a list of all available versions.
