Launcher

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.

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, Global 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 Global Layouts. At the top, you can find a search bar that's not just a simple item filter, but a fully functional global search implemented using the search capabilities 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.

Available since io.Connect Desktop 10.0

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

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 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:

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.

Favorite items 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.

Layout Sharing

Available since io.Connect Desktop 10.5

When 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:

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:

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

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

⚠️ Note that custom Launchpad apps must use @interopio/components-react 5.0 or later in order to provide the Layout sharing options.

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 library. This is the same component used by the default Launchpad of io.Connect Desktop.

To create a custom launcher:

1. Implement the launcher with the <Launchpad /> component.
2. Configure the launcher as a shell app of io.Connect Desktop.
3. Customize the launcher styles.

For a quick start, use the Launchpad template built with the <Launchpad /> component. The template is also available as the launchpad template app of the io.Connect seed project.

The <Launchpad /> component renders a fully functional Launchpad without the need for any additional configuration. Use its components prop to change the components in the Launchpad header and to choose the sections that the Launchpad shows. Use the hooks exported by IOLaunchpadDesktop to read and change the Launchpad state from your own components and to interact with the Launchpad panels and popups.

Setup

Render the Launchpad within the <IOConnectProvider /> component of the @interopio/react-hooks library. Initialize the @interopio/desktop library and add the required Workspaces, Search, and Modals APIs, as demonstrated in the Launchpad template.

The Launchpad depends on a set of React context providers from @interopio/components-react. They supply the theme, platform preferences, notifications, downloads data, Launchpad state, panels, and popups that the Launchpad requires to operate properly. If a provider is missing, the Launchpad functionality that depends on it won't work. You must render the <Launchpad /> component within all of them, in the order demonstrated in the template and the following example.

You must also import the CSS files for the Launchpad and for the features it uses.

The following example demonstrates how to render the default Launchpad:

import { IOConnectProvider } from "@interopio/react-hooks";
import IODesktop from "@interopio/desktop";
import IOWorkspaces from "@interopio/workspaces-api";
import IOSearch from "@interopio/search-api";
import IOModals from "@interopio/modals-api";
import {
    ThemeProvider,
    PlatformPrefsProvider,
    IOActivePanelRenderer,
    IODownloadManager,
    IOLaunchpadDesktop,
    IONotifications
} from "@interopio/components-react";
import "@interopio/workspaces-ui-react/dist/styles/workspaces.css";
import "@interopio/components-react/dist/styles/components/ui/dropdown-menu.css";
import "@interopio/components-react/dist/styles/components/ui/overlay-scrollbars-container.css";
import "@interopio/components-react/dist/styles/features/active-panel-renderer/styles.css";
import "@interopio/components-react/dist/styles/features/notifications/styles.css";
import "@interopio/components-react/dist/styles/features/preferences/styles.css";
import "@interopio/components-react/dist/styles/features/profile/styles.css";
import "@interopio/components-react/dist/styles/features/launchpad/styles.css";
import "@interopio/components-react/dist/styles/features/launchpad-desktop/styles.css";

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

const settings = {
    desktop: {
        factory: IODesktop,
        config: {
            libraries: [IOWorkspaces, IOSearch, IOModals],
            appManager: "full",
            apps: true,
            layouts: "full"
        }
    }
};

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

export default App;

The complete setup is available in the Launchpad template.

⚠️ Note that to provide the Layout sharing options in your custom Launchpad, you must use @interopio/components-react 5.0 or later and @interopio/desktop 6.23 or later.

⚠️ Note that if using Layout sharing, you must enable the Apps API by setting the apps property of the configuration object for initializing the @interopio/desktop library to true. Currently, the Launchpad also requires the legacy App Management API to be enabled, with the appManager property of the configuration object set to "full".

Header

The Launchpad header contains the search bar and an area on each side of it. To set the components in these areas, use the BeforeSearch and AfterSearch properties of the header object in the components prop.

If you don't set a property, the Launchpad will render the default components for that area. To leave an area empty, set its property to null. If you set a property to a React component, the Launchpad will render your component instead of all default components in that area.

By default, the area before the search bar contains the <DragHandle /> and <LogoButton /> components. The area after the search bar contains the <ExtendedArea />, <NotificationsButton />, and <MainContextMenu /> components. All default components are exported, so you can combine them with your own components. To remove a default component, compose the area without it.

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

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

const {
    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 = () => <Launchpad components={components} />;

Default Components

The following default components are available for the Launchpad header:

All default components accept the standard HTML attributes of a <div> element, such as className and style.

Logo Button

Use the props of the <LogoButton /> component to change the logo and the click behavior without replacing the component:

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:

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 }
    ]
};

const MyLaunchpad = () => <Launchpad components={components} />;

Custom Sections

The <Section /> component has the following props:

The config object has the following properties:

A section can contain individual items, as well as folders with items. You can group items in folders within a section by using nested objects in the items array. Each folder can contain items and other folders.

An object describing a folder has the same properties as the config object of the section.

An object describing an individual item has the following properties:

Each object in the contextMenuActions array has the following properties:

The statusPill object has the following properties:

Handling Item Clicks

To define what happens when the user clicks on a section item or selects an action from its context menu, use the onItemClick callback of the <Section /> component.

The callback receives as an argument an object with the following properties:

The following example demonstrates creating a section with an app and a folder with a Workspace. The app has a context menu action for opening a help page:

import { useContext } from "react";
import { IOConnectContext } from "@interopio/react-hooks";
import { IOLaunchpadDesktop } from "@interopio/components-react";

const { Section } = IOLaunchpadDesktop;

const config = {
    id: "research-section",
    title: "Research",
    items: [
        {
            id: "market-news",
            title: "Market News",
            type: "application",
            description: "Latest market headlines",
            contextMenuActions: [
                { name: "open-help", displayName: "Open Help" }
            ]
        },
        {
            id: "reports-folder",
            title: "Reports",
            items: [
                { id: "Client Reports", title: "Client Reports", type: "workspace" }
            ]
        }
    ]
};

const ResearchSection = () => {
    const io = useContext(IOConnectContext);

    const onItemClick = ({ item, selectedContextMenuActionName }) => {
        if (selectedContextMenuActionName === "open-help") {
            io.windows.open(`${item.id}-help`, `https://example.com/help/${item.id}`);
            return;
        }

        if (item.type === "application") {
            const options = { name: item.id };

            io.apps.instances.start(options);
        } else if (item.type === "workspace") {
            io.workspaces.restoreWorkspace(item.id);
        }
    };

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

Hooks

The IOLaunchpadDesktop object exports hooks for reading and changing the Launchpad state and manipulating the Launchpad panels and popups. Use them in components that you render within the Launchpad providers, such as your header components and custom sections.

The following sections describe the available hooks and the tools they provide for interacting with the Launchpad state, panels, and popups.

Pinned, Docked & Collapsed State

The useLaunchpadContext() hook returns an object with the following properties:

Panels

The usePanelPopupContext() hook returns an object with the following properties:

The following panel IDs are available:

If the Launchpad is collapsed, expand it before opening a panel so that the panel is visible.

The following example demonstrates adding a button for opening the Platform Preferences panel before the Launchpad menu:

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

const {
    Launchpad,
    ExtendedArea,
    NotificationsButton,
    MainContextMenu,
    useLaunchpadContext,
    usePanelPopupContext
} = IOLaunchpadDesktop;

const PreferencesButton = () => {
    const { isDocked, isCollapsed, setIsCollapsed } = useLaunchpadContext();
    const { openPanel } = usePanelPopupContext();

    const onClick = async () => {
        // Expand the Launchpad so that the panel is visible.
        if (!isDocked && isCollapsed) {
            await setIsCollapsed(false);
        }

        openPanel("preferences");
    };

    // The `non-draggable` class allows the button to receive clicks in the header.
    return <button className="non-draggable" onClick={onClick}>Preferences</button>;
};

const AfterSearch = () => (
    <>
        <ExtendedArea />
        <NotificationsButton />
        <PreferencesButton />
        <MainContextMenu />
    </>
);

const components = { header: { AfterSearch } };

const MyLaunchpad = () => <Launchpad components={components} />;

Sections Popup

When the Launchpad is docked, its sections appear in a popup that the user opens by clicking the logo button. If you replace the <LogoButton /> component with your own component, use the useLaunchpadBodyPopupContext() hook to control this popup. The hook returns an object with the following properties:

Configuration

Once you have implemented a launcher, you must host it, create an app definition 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:

{
    "shell": true
}

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

{
    "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:

{
    "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:

{
    "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":

{
    "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 file of io.Connect Desktop to false:

{
    "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:

{
    "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:

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

Available since io.Connect Desktop 9.9

To customize the io.Connect Launchpad styles, use the CSS variables provided by the io.Connect themes.