Home App

The @interopio/home-ui-react library offers React 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 prop 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;

Authentication

The Home App provides authentication mechanisms for simple and Auth0 login. It's also possible to integrate a custom login procedure with the Home App.

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.

For the built-in simple and Auth0 logins you can customize the login page.

When using a custom login procedure, you have to display your own login page to the user and authenticate them. After successful authentication, you have to display the <IOConnectHome /> component and pass the user credentials to it.

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

Simple Login

The following example demonstrates basic configuration for simple authentication:

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

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 { getConfig } from "./helpers";
import "@interopio/workspaces-ui-react/dist/styles/workspaces.css";
import "@interopio/home-ui-react/src/index.css";

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 simple and Auth0 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 { getConfig } from "./helpers";
import "@interopio/workspaces-ui-react/dist/styles/workspaces.css";
import "@interopio/home-ui-react/src/index.css";
import logo from "./logo.png";

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;

Custom Login

Available since io.Connect Browser 3.4

The following example demonstrates basic configuration and flow when using a custom login procedure:

import { useState } from "react";
import { IOConnectHome } from "@interopio/home-ui-react";
import { getConfig, authenticateUser, logOutUser } from "./helpers";
import MyLoginPage from "./MyLoginPage";
import "@interopio/workspaces-ui-react/dist/styles/workspaces.css";
import "@interopio/home-ui-react/src/index.css";

const App = () => {
    const [user, setUser] = useState(null);

    const config = {
        getIOConnectConfig: getConfig,
        // Settings for custom login.
        login: {
            // Type must be set to `"custom"`.
            type: "custom",
            // Provide details about the authenticated user.
            user: user: {
                id: user?.id,
                username: user?.username
            },
            // Callback that will be invoked on logout of the platform.
            onLogout: () => {
                // Use your custom logic to log out the user.
                logOutUser();

                setUser(null);
            }
        }
    };

    const logInUser = async () => {
        // Use your custom logic to authenticate the user.
        const user = await authenticateUser();

        if (user) {
            // Set the user object to provide an ID and a username for the Home App.
            setUser(user);
        };
    };

    // Display the Home App only if the user is logged in.
    return user ? <IOConnectHome config={config} /> : <MyLoginPage logInUser={logInUser} />
};

export default App;

The login object for custom login accepts the following properties:

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;

Loader

Available since io.Connect Browser 3.4

The default loader of the Home App can be customized by using the <SystemLoader /> component exported by the library, or can be replaced with your custom one. The default loader is used for different loading events in the Home App. The logo displayed for all loading events is the same, but the text is specific to each event.

To customize or replace the loader, use the SystemLoader property of the components object inside the config object for the <IOConnectHome /> component.

To replace the loader logo, use the Logo prop of the <SystemLoader /> component. All default texts will still be shown for the different loading events:

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

const getIOConnectConfig = await getConfig();

// Configuration for the `<IOConnectHome />` component.
const config = {
    getIOConnectConfig,
    components: {
        // Provide a custom icon for the default loader of the Home App.
        SystemLoader: () => <SystemLoader Logo={() => <span>My Logo</span>} />
    }
};

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

export default App;

When replacing the default loader component with your custom one, you can reuse the default texts for the different loading events, remove them, or provide your own text to be displayed for all loading events:

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

// Custom loader that will be used by the Home App for all loading events.
// Your custom component loader will receive two props - `Logo` and `text`.
// The `text` prop enables you to reuse the default texts for the different loading events.
const MyCustomLoader = ({ Logo, text }) => {
    return (
        <div>
            <MyLogo />
            <h2>{text}</h2>
        </div>
    );
};

const getIOConnectConfig = await getConfig();

// Configuration for the `<IOConnectHome />` component.
const config = {
    getIOConnectConfig,
    components: {
        // Replacing the default loader of the Home App.
        SystemLoader: MyCustomLoader
    }
};

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