# Launcher

Source: https://docs.interop.io/desktop/capabilities/launcher/index.html

## Overview

The io.Connect embedded launcher is an app which acts as a central hub for managing interop-enabled apps, Layouts, Workspaces, search, notifications and various **io.Connect Desktop** settings. **io.Connect Desktop** comes with an embedded launcher - the io.Connect [Launchpad](#launchpad).

## Launchpad

Available since io.Connect Desktop 9.9

The io.Connect Launchpad is the default io.Connect launcher. It's an easily customizable web app that acts as a central hub for all io.Connect features - apps, Workspaces, Layouts, notifications, platform preferences, and more.

The Launchpad starts in expanded mode and contains conveniently placed sections with easy access to all available Workspaces, apps, and Layouts. At the top, you can find search bar that's not just a simple item filter, but a fully functional global search implemented using the [search capabilities](https://docs.interop.io/desktop/capabilities/search/overview/index.md) of the io.Connect framework.

The Launchpad provides quick access to the Notification Panel, the Download Manager, the Feedback Form, and contains a menu with various platform settings. It can be moved, minimized, and collapsed to a compact horizontal toolbar in order to save screen real estate. Users who prefer the Launchpad to be always available on the screen can pin the Launchpad to the left or the right side of their monitors.

![Launchpad](https://docs.interop.io/desktop/images/launchers/launchpad.mp4)

Available since io.Connect Desktop 10.0

The Launchpad can be docked to the top of the screen for convenient access:

![Launchpad Docking](https://docs.interop.io/desktop/images/launchers/launchpad-dock.mp4)

If you dock the Launchpad, you can utilize the extended area located between the search bar and the system icons. This area can show lists of favorite items, recent items, and you can also add [custom categories](#custom_launcher-extended_area_custom_categories) in it. The extended area can be enabled and configured from the Platform Preferences panel in the Launchpad menu - it's possible to hide or show the "Favorites" and "Recent" section or to hide the item titles to save space:

![Launchpad Extended Area](https://docs.interop.io/desktop/images/launchers/launchpad-extended-area.mp4)

Available since io.Connect Desktop 10.5

The Global Layouts are listed in a Layouts section similarly to apps and Workspaces. The Layouts section is always rendered after all default and custom sections and can't be hidden or repositioned. The currently active Global Layout is displayed in a footer at the bottom of the Launchpad.

Favorites are added and removed via the context menu for each section item. Apps, Workspaces, and Global Layouts can be added to the favorite items.

The buttons for creating a new Workspace and a new Global Layout are located in the headers of the Workspaces and Layouts sections respectively.

![Launchpad Sections & Menus](https://docs.interop.io/desktop/images/launchers/launchpad-sections-menus.png)

### Layout Sharing

Available since io.Connect Desktop 10.5

When [Layout sharing](https://docs.interop.io/desktop/capabilities/windows/layouts/overview/index.md#layout_sharing) is enabled, the Layouts and Workspaces sections of the Launchpad are divided into "Public" and "Private" sections. The "Public" section contains the public Layouts and the shared Layouts that have been published by you or shared with you. Layouts with a specified folder are grouped in folders.

The context menu of the Layouts and Workspaces provides the following options for Layout sharing:

| Option | Description |
|--------|-------------|
| "Details" | Available for shared and public Layouts to their viewers. Shows the details for the Layout. |
| "Edit" | Available for private Layouts to their owner. Allows changing the name, folder, icon, and description of the Layout. |
| "Hide from Launchpad" / "Show in Launchpad" | Available for shared and public Layouts to their owner, editors, and viewers. Hides or shows the Layout in the Launchpad. To see the hidden Layouts, enable the "Show hidden Layouts and Workspaces" setting in the "Layouts" section of the Platform Preferences panel. |
| "Manage" | Available for shared and public Layouts to their owner and editors. Allows changing the users and groups with access to the Layout, as well as its name, folder, icon, and description. |
| "Publish" | Available for private Layouts to their owner. Allows sharing the Layout with the selected users and groups with view or edit permissions. Select the "Keep a private copy" option to keep your private Layout and publish a shared copy of it. |
| "Save a Private Copy" | Available for shared and public Layouts to their owner, editors, and viewers. Saves a copy of the Layout as a private one. |

The "Rename", "Save", and "Save As" options of the context menu are available only for private Layouts. To change the name of a shared or a public Layout you can edit, use the "Manage" option.

Owners and editors have the following options available in the Launchpad for working with shared and public Global and Workspace Layouts:

![Owners & Editors Options Public Layouts](https://docs.interop.io/desktop/images/launchers/layout-sharing-owner-public-layout.png)

Viewers have the following options available in the Launchpad for working with shared and public Global and Workspace Layouts:

![Viewers Options Public Layouts](https://docs.interop.io/desktop/images/launchers/layout-sharing-viewer.png)

Owners have the following options available in the Launchpad for working with private Global and Workspace Layouts:

![Owners Options Private Layouts](https://docs.interop.io/desktop/images/launchers/layout-sharing-owner-private-layout.png)

> ⚠️ *Note that custom Launchpad apps must use [`@interopio/components-react`](https://www.npmjs.com/package/@interopio/components-react) 5.0 or later in order to provide the Layout sharing options.*

## Custom Launcher

Available since io.Connect Desktop 10.5 & @interopio/components-react 4.6

The io.Connect Launchpad is available as a standalone React component that you can use to create a custom launcher for **io.Connect Desktop**. The `<Launchpad />` component is provided by the `IOLaunchpadDesktop` object of the [`@interopio/components-react`](https://www.npmjs.com/package/@interopio/components-react) library. This is the same component used by the default Launchpad of **io.Connect Desktop**.

To get started quickly, use the [Launchpad template](https://github.com/InteropIO/templates/tree/main/io-connect-desktop-launchpad) built with the `<Launchpad />` component. The template is also available as the `launchpad` [template app](https://docs.interop.io/desktop/developers/seed-project/index.md#customization-apps-using_template_apps) of the io.Connect seed project.

The `<Launchpad />` component renders a fully functional Launchpad without any additional configuration. Use its `components` prop to replace the default components in the areas before and after the search bar of the Launchpad and to customize the Launchpad sections. The default components (`<DragHandle />`, `<LogoButton />`, `<ExtendedArea />`, `<NotificationsButton />`, and `<MainContextMenu />`) are also exported, so you can compose them with your own components.

The following example demonstrates creating a custom Launchpad with a custom logo and without the button for opening the Notification Panel:

```javascript
import {
    ThemeProvider,
    PlatformPrefsProvider,
    IOActivePanelRenderer,
    IODownloadManager,
    IOLaunchpadDesktop,
    IONotifications
} from "@interopio/components-react";

const { PanelManagerProvider } = IOActivePanelRenderer;
const { DownloadManagerProvider } = IODownloadManager;
const { NotificationsProvider } = IONotifications;
const {
    LaunchpadProvider,
    LaunchpadBodyPopupProvider,
    PanelPopupProvider,
    Launchpad,
    DragHandle,
    LogoButton,
    ExtendedArea,
    MainContextMenu
} = IOLaunchpadDesktop;

// Components before the search bar.
const BeforeSearch = () => (
    <>
        <DragHandle />
        <LogoButton iconSrc="./my-logo.png" />
    </>
);

// Components after the search bar.
const AfterSearch = () => (
    <>
        <ExtendedArea />
        <MainContextMenu />
    </>
);

// Define the components outside the render function to prevent unnecessary re-mounting.
const components = { header: { BeforeSearch, AfterSearch } };

const MyLaunchpad = () => {
    return (
        <ThemeProvider>
            <PlatformPrefsProvider>
                <NotificationsProvider>
                    <DownloadManagerProvider>
                        <PanelManagerProvider>
                            <LaunchpadProvider>
                                <LaunchpadBodyPopupProvider>
                                    <PanelPopupProvider>
                                        <Launchpad components={components} />
                                    </PanelPopupProvider>
                                </LaunchpadBodyPopupProvider>
                            </LaunchpadProvider>
                        </PanelManagerProvider>
                    </DownloadManagerProvider>
                </NotificationsProvider>
            </PlatformPrefsProvider>
        </ThemeProvider>
    );
};

export default MyLaunchpad;
```

The Launchpad must be rendered within the `<IOConnectProvider />` component of the [io.Connect React Hooks](https://docs.interop.io/desktop/getting-started/how-to/interop-enable-your-apps/react/index.md) library and the required CSS files must be imported. For a complete setup, see the Launchpad template.

> ⚠️ *Note that to provide the [Layout sharing](#launchpad-layout_sharing) options in your custom Launchpad, you must use [`@interopio/components-react`](https://www.npmjs.com/package/@interopio/components-react) 5.0 or later and [`@interopio/desktop`](https://www.npmjs.com/package/@interopio/desktop) 6.23 or later.*

### Sections

Use the `sections` property of the `components` prop to specify the sections of the Launchpad and their order. It accepts an array of objects with `placementId` and `Component` properties. The default Favorites, Workspaces, and Apps sections are available as the `<FavoritesSection />`, `<WorkspacesSection />`, and `<ApplicationsSection />` components. To create a custom section, use the `<Section />` component. The default sections that you don't include in the array won't be displayed. The Layouts section is always rendered after all other sections and can't be hidden or repositioned.

The following example demonstrates adding a custom section between the Favorites and Apps sections and removing the Workspaces section:

```javascript
import { IOLaunchpadDesktop } from "@interopio/components-react";

const { Launchpad, FavoritesSection, ApplicationsSection, Section } = IOLaunchpadDesktop;

const ResearchSection = () => {
    const config = {
        id: "research-section",
        title: "Research",
        items: [
            { id: "market-news", title: "Market News", type: "application" }
        ]
    };

    const onItemClick = ({ item }) => console.log(`Clicked "${item.title}".`);

    return <Section config={config} onItemClick={onItemClick} />;
};

// Define the components outside the render function to prevent unnecessary re-mounting.
const components = {
    sections: [
        { placementId: "favorites-section", Component: FavoritesSection },
        { placementId: "research-section", Component: ResearchSection },
        { placementId: "applications-section", Component: ApplicationsSection }
    ]
};

// Render within the providers shown in the previous example.
const MyLaunchpad = () => <Launchpad components={components} />;
```

### Configuration

Once you have implemented a launcher, you must host it, create an [app definition](https://docs.interop.io/desktop/developers/configuration/application/index.md) file for it, and add it to your app store.

1. To instruct the platform that this is your shell app, set the `"shell"` top-level key to `true`:

```json
{
    "shell": true
}
```

2. To make your launcher start automatically when the platform is initiated, also set the `"autoStart"` top-level key to `true`:

```json
{
    "shell": true,
    "autoStart": true
}
```

3. To prevent the launcher from displaying itself in the list of available apps, set the `"hidden"` top-level key to `true`:

```json
{
    "shell": true,
    "autoStart": true,
    "hidden": true
}
```

4. If you don't want the users to be able to start more than one instance of your launcher, set the `"allowMultiple"` top-level key to `false`:

```json
{
    "shell": true,
    "autoStart": true,
    "hidden": true,
    "allowMultiple": false
}
```

5. Use the `"url"` property of the `"details"` top-level key to provide the location of your custom launcher and also set the other required properties - `"name"` and `"type"`:

```json
{
    "name": "my-launcher",
    "type": "window",
    "shell": true,
    "autoStart": true,
    "hidden": true,
    "allowMultiple": false,
    "details": {
        "url": "./my-custom-launcher/index.html"
    }
}
```

6. Finally, to disable the default **io.Connect Desktop** launcher, set the `"useEmbeddedShell"` top-level key in the `system.json` [system configuration](https://docs.interop.io/desktop/developers/configuration/system/index.md) file of **io.Connect Desktop** to `false`:

```json
{
    "useEmbeddedShell": false
}
```

7. Restart **io.Connect Desktop** for the changes to take effect and start using your custom launcher.

### Extended Area Custom Categories

Available since io.Connect Desktop 10.0

To add custom categories to the extended area of the Launchpad that is available when the Launchpad is docked, use the `"extendedAreaCategories"` property of the `"customProperties"` top-level key in the Launchpad [app definition](https://docs.interop.io/desktop/developers/configuration/application/index.md):

```json
{
    "customProperties": {
        "extendedAreaCategories": [
            {
                "name": "Client Management",
                "items": [
                    {
                        "name": "channelsclientlist",
                        "type": "application"
                    },
                    {
                        "name": "Client Info",
                        "type": "workspace"
                    }
                ]
            }
        ]
    }
}
```

Each object in the `"extendedAreaCategories"` array has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"name"` | `string` | **Required.** Name for the category to be displayed in the Launchpad extended area. |
| `"items"` | `object[]` | **Required.** Array of objects describing the items (apps and Workspaces) to be displayed in the specified category. |

Each object in the `"items"` array has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"name"` | `string` | **Required.** The name of an app as specified in its app definition, or the name of a Workspace to be displayed in the category list. |
| `"type"` | `"application"` \| `"workspace"` | **Required.** The type of the item to be displayed in the category list - an app or a Workspace. |

## Styles

Available since io.Connect Desktop 9.9

To customize the io.Connect Launchpad styles, use the [CSS variables](https://docs.interop.io/desktop/developers/platform-styles/index.md#launchpad) provided by the io.Connect themes.