Home App

The @interopio/home-ui-react library offers React hooks and components that enable you to create and customize a Home App for your io.Connect Browser projects. The Home App is meant to act as a Main app in your project.

Currently, the only supported option is to build a Home App that's also a Workspaces App.

Use the Home App template in GitHub as a startup skeleton to create and customize your own Home App.

To use the @interopio/home-ui-react library in your project, execute the following command:

npm install @interopio/home-ui-react

All default components can be reused and composed with custom code. If usage of such component has been detected, its default behavior will be applied. For instance, if you use the <SlidePanel /> component, it will automatically open the panel it contains when the user clicks on its icon, without the need of custom code to induce this behavior.

Home Component

Available since io.Connect Browser 3.2

The <IOConnectHome /> component is the root component for building a Home App. Its config property is the main customization point for the Home App. It accepts all required and optional settings for initializing and configuring the Home App as the Main app of your io.Connect Browser project, for configuring the authentication mechanism and the first-time user setup flow, and also for customizing the Workspaces App and the Launchpad.

The config object of the <IOConnectHome /> component has the following properties:

⚠️ Note that currently the only supported option is to build a Home App that's also a Workspaces App, so you must configure your Main app as a Workspaces App.

The following example demonstrates a basic configuration for the <IOConnectHome /> component. The configuration provides:

• the required license key for initializing an io.Connect Browser project;
• settings for using the Main app as a Workspaces App;
• authentication settings for connecting to io.Manager when using Basic authentication;
• specifying the login mechanism for the Home App and providing optional login validation;

import { IOConnectHome } from "@interopio/home-ui-react";
import "@interopio/workspaces-ui-react/dist/styles/workspaces.css";
import "@interopio/home-ui-react/src/index.css";

const getConfig = (user) => {
    // Platform configuration.
    const platformConfig = {
        browserPlatform: {
            factory: IOBrowserPlatform,
            config: {
                // Required license key.
                licenseKey: "my-license-key",
                // Workspaces App configuration.
                workspaces: {
                    src: "/",
                    isFrame: true
                },
                // Connection to io.Manager using Basic authentication.
                manager: {
                    url: "https://my-io-manager.com:4242/api",
                    auth: {
                        basic: {
                            // Extracting the user details from the `user` argument.
                            username: user.username,
                            password: user.password
                        }
                    },
                    critical: true
                }
            }
        }
    };

    return platformConfig;
};

// Configuration for the `<IOConnectHome />` component.
const config = {
    // Retrieve the platform configuration.
    getIOConnectConfig: getConfig,
    // Login settings.
    login: {
        type: "simple",
        onLogin: async (username, password) => {
            // Custom validation logic.
            await validateUser(username, password);

            const user = { id: username, username, password };

            return user;
        }
    }
};

const App = () => {
    return <IOConnectHome config={config} />
};

export default App;

Login

The Home App provides two authentication mechanisms - simple and Auth0. The simple login consists of a form for the user credentials (username and password). You must provide a callback with your custom logic for validating the user credentials. The Auth0 login uses @auth0/auth0-react internally. It's required to provide the domain and the client ID for Auth0 authentication. You can also perform additional user validation after a successful Auth0 login, and based on the returned result, the user will be either authenticated, or automatically logged out of Auth0 and returned to the login screen. It's possible to customize the login pages for both types of login.

The following sections demonstrate how to provide configuration settings for the supported authentication mechanisms by using the config property of the <IOConnectHome /> component.

Simple Login

The following example demonstrates basic configuration for simple authentication:

import { IOConnectHome } from "@interopio/home-ui-react";
import "@interopio/workspaces-ui-react/dist/styles/workspaces.css";
import "@interopio/home-ui-react/src/index.css";

const getConfig = (user) => {
    // Define and return the required platform configuration.
};

const config = {
    getIOConnectConfig: getConfig,
    // Settings for simple login.
    login: {
        // Type must be set to `"simple"`.
        type: "simple",
        // Asynchronous callback for user validation.
        onLogin: async (username, password) => {
            // Custom validation logic.
            await validateUser(username, password);
            // Must return a `User` object.
            const user = { id: username, username, password };

            return user;
        }
    }
};

const App = () => {
    return <IOConnectHome config={config} />
};

export default App;

The login object for simple login accepts the following properties:

The callback supplied in the onLogin property must resolve with a User object with the following properties:

Auth0 Login

The following example demonstrates basic configuration for Auth0 authentication:

import { IOConnectHome } from "@interopio/home-ui-react";
import "@interopio/workspaces-ui-react/dist/styles/workspaces.css";
import "@interopio/home-ui-react/src/index.css";

const getConfig = (user) => {
    // Define and return the required platform configuration.
};

const config = {
    getIOConnectConfig: getConfig,
    // Settings for Auth0 login.
    login: {
        // Type must be set to `"auth0"`.
        type: "auth0",
        // Required settings for connecting to the Auth0 authentication provider.
        providerOptions: {
            domain: "my-domain.auth0.com",
            clientId: "my-client-id"
        }
    }
};

const App = () => {
    return <IOConnectHome config={config} />
};

export default App;

The login object for Auth0 login accepts the following properties:

The callback supplied in the validateUser property must return a result in one of the following shapes:

type ValidationResult = { ok: true } | { ok: false; message: string };

The specified error message will be shown to the user in case of an unsuccessful validation.

Customizing the Login Page

For both types of login, you can use the components property in the configuration object to provide custom components for the login page.

The components object has the following properties:

The following example demonstrates providing custom logo and heading for the simple login page:

import { IOConnectHome } from "@interopio/home-ui-react";
import "@interopio/workspaces-ui-react/dist/styles/workspaces.css";
import "@interopio/home-ui-react/src/index.css";
import logo from "./logo.png";

const getConfig = (user) => {
    // Define and return the required platform configuration.
};

const config = {
    getIOConnectConfig: getConfig,
    login: {
        type: "simple",
        onLogin: async (username, password) => {
            // Custom validation logic.
        },
        // Custom components for the login page.
        components: {
            Logo: () => <img src={logo} />,
            Heading: () => <div>My Custom Heading</div>
        }
    }
};

const App = () => {
    return <IOConnectHome config={config} />
};

export default App;

Setup Flow

To customize the first-time user setup flow of the Home App, use the setupFlow property of the config object for the <IOConnectHome /> component.

The setupFlow object has the following properties:

The following example demonstrates how to provide a custom logo for the setup flow page:

import { IOConnectHome } from "@interopio/home-ui-react";
import "@interopio/workspaces-ui-react/dist/styles/workspaces.css";
import "@interopio/home-ui-react/src/index.css";
import logo from "./logo.png";

const getConfig = (user) => {
    // Define and return the required platform configuration.
};

const config = {
    getIOConnectConfig: getConfig,
    // Setup flow settings.
    setupFlow: {
        // Custom logo for the setup flow page.
        components: {
            Logo: () => <img src={logo} />
        }
    }
};

const App = () => {
    return <IOConnectHome config={config} />
};

export default App;

Workspaces

To customize the Workspaces App of the Home App, use the workspaces property of the config object for the <IOConnectHome /> component.

The workspaces object has the following properties:

The following example demonstrates customizing the Launchpad icon and reusing the default <LaunchpadAccess /> component:

import { IOConnectHome, LaunchpadAccess } from "@interopio/home-ui-react";
import "@interopio/workspaces-ui-react/dist/styles/workspaces.css";
import "@interopio/home-ui-react/src/index.css";
import icon from "./icon.png";

const getConfig = (user) => {
    // Define and return the required platform configuration.
};

const config = {
    getIOConnectConfig: getConfig,
    // Customizing the Workspaces App with an icon for the Launchpad.
    workspaces: {
        HeaderLogoArea: () => <LaunchpadAccess icon={<img src={icon} />} />
    }
};

const App = () => {
    return <IOConnectHome config={config} />
};

export default App;

You can use the component provided to the HeaderLogoArea property to add more icons and buttons in the header area of the Workspaces App. The following example demonstrates reusing the default <NotificationsIcon />, <NotificationsPanel /> and the <SlidePanel /> components to display the Notification Panel outside the Launchpad, after the default Launchpad icon:

import {
    IOConnectHome,
    LaunchpadAccess,
    SlidePanel,
    NotificationsIcon,
    NotificationsPanel
} from "@interopio/home-ui-react";
import "@interopio/workspaces-ui-react/dist/styles/workspaces.css";
import "@interopio/home-ui-react/src/index.css";

const getConfig = (user) => {
    // Define and return the required platform configuration.
};

const config = {
    getIOConnectConfig: getConfig,
    // Extracting the Notification Panel outside the Launchpad.
    workspaces: {
        HeaderLogoArea: () => {
            return (
                <>
                    <LaunchpadAccess />
                    <SlidePanel icon={<NotificationsIcon />}>
                        {() => <NotificationsPanel />}
                    </SlidePanel>
                </>
            );
        }
    }
};

const App = () => {
    return <IOConnectHome config={config} />
};

export default App;

Launchpad

To customize the Launchpad of the Home App, use the launchpad property of the config object for the <IOConnectHome /> component.

The launchpad object has the following properties:

The components object has the following properties:

The following example demonstrates removing the Notification Panel and providing a custom component for the User Panel in the Launchpad:

import { IOConnectHome } from "@interopio/home-ui-react";
import "@interopio/workspaces-ui-react/dist/styles/workspaces.css";
import "@interopio/home-ui-react/src/index.css";
import MyCustomUserPanel from "./MyCustomUserPanel";

const getConfig = (user) => {
    // Define and return the required platform configuration.
};

const config = {
    getIOConnectConfig: getConfig,
    // Customizing the Launchpad.
    launchpad: {
        components: {
            // Removing the Notification Panel.
            NotificationsPanel: null,
            // Providing a custom User Panel.
            UserPanel: MyCustomUserPanel
        }
    }
};

const App = () => {
    return <IOConnectHome config={config} />
};

export default App;

Default Sections

The <FavoritesSection />, <WorkspacesSection /> and <ApplicationsSection /> components are the default sections of the Launchpad. You can reuse them, rearrange them and modify their behavior by passing them to the Sections property of the components object in the Launchpad configuration. Each of these components has the following properties:

The following example demonstrates rearranging the default sections, making the "Workspaces" and "Applications" sections collapsible, configuring the "Applications" section to show all items, and sorting the items in the "Favorites" section in a reverse order:

import {
    IOConnectHome,
    FavoritesSection,
    ApplicationsSection,
    WorkspacesSection
} from "@interopio/home-ui-react";
import "@interopio/workspaces-ui-react/dist/styles/workspaces.css";
import "@interopio/home-ui-react/src/index.css";

const getConfig = (user) => {
    // Define and return the required platform configuration.
};

const config = {
    getIOConnectConfig: getConfig,
    launchpad: {
        components: {
            // Customizing the default sections.
            Sections: () => {
                return (
                    <>
                        <FavoritesSection sortOrder="descending" />
                        <ApplicationsSection isSectionCollapsible={true} showAllItems={true} />
                        <WorkspacesSection isSectionCollapsible={true} />
                    </>
                );
            }
        }
    }
};

const App = () => {
    return <IOConnectHome config={config} />
};

export default App;

Custom Sections

The Sections property of the components object in the Launchpad configuration allows you to add your own custom sections to the Launchpad. You can reuse the default <Section /> component, or provide an entirely customized one.

The <Section /> component has the following properties:

The config object has the following properties:

The items array accept a list of objects each describing a section (as described above), or an item with the following properties:

The callback provided to the onItemClick property of the config object for the <Section /> component will receive as an argument an object with the following properties:

The following example demonstrates rearranging the default sections, making the "Applications" section collapsible, and adding a custom collapsible section with several items in it. Clicking on an item in the custom section will perform a predefined action:

import {
    IOConnectHome,
    FavoritesSection,
    ApplicationsSection,
    WorkspacesSection,
    Section
} from "@interopio/home-ui-react";
import "@interopio/workspaces-ui-react/dist/styles/workspaces.css";
import "@interopio/home-ui-react/src/index.css";
import icon from "./icon.png";

const getConfig = (user) => {
    // Define and return the required platform configuration.
};

// Items for the custom section in the Launchpad.
const items = [
    {
        id: "custom-item",
        title: "Custom Item",
        type: "custom-type"
    },
    {
        id: "another-custom-item",
        title: "Another Custom Item",
        type: "custom-type"
    }
];

const config = {
    getIOConnectConfig: getConfig,
    launchpad: {
        components: {
            // Rearranging the default sections, making the "Applications" section collapsible,
            // and adding a custom section with items.
            Sections: () => {
                return (
                    <>
                        <FavoritesSection />
                        <ApplicationsSection isSectionCollapsible={true} />
                        <WorkspacesSection />
                        <Section
                            config={{
                                id: "my-section-id",
                                title: "Custom Section",
                                items,
                                iconSrc: icon,
                                isCollapsible: true
                            }}
                            onItemClick={({ item }) => alert(`Clicked "${item.title}".`)}
                        />
                    </>
                );
            }
        }
    }
};

const App = () => {
    return <IOConnectHome config={config} />
};

export default App;

Styles

To use the default styles for your custom Home App, import the following CSS files:

import "@interopio/workspaces-ui-react/dist/styles/workspaces.css";
import "@interopio/home-ui-react/index.css";

To use custom styles for the Home App, simply import your CSS file after the default CSS imports to override them. Two default themes are available - "Day" and "Night" - and the trigger for switching between them is the class property of the <html> element - "light" for the "Day" theme and "dark" for the "Night" theme:

<!-- Day theme -->
<html class="light">

<!-- Night theme -->
<html class="dark">

The following lists the available hooks exported by the library:

The useIsBrowserSupported() hook returns a Boolean value that determines whether the browser is supported:

const isBrowserSupported = useIsBrowserSupported();

if (!isBrowserSupported) {
    return <div>Browser Not Supported</div>;
};

The following lists the more important main components for building a Home App:

The following lists the more important components for building a Home App that's also a Workspaces App:

The following lists the more important components comprising the Launchpad: