React.JS Integration with Console UI

19min
Overview
The Console UI SDK enables developers to incorporate Console UI components into their applications, enabling features like authentication, headers, sidebars, modals, and more to offer a seamless app access and navigation experience to their end users.
For more information about the benefits of Console UI, see Console UI Overview.
This guide walks through the integration of Console UI SDK with your application using React.JS library.
﻿
Step 1: Installation
To get started, developers need to install the console-ui-react package. This package contains all the necessary components and utilities for the integration.
To install the package, navigate to your project directory in your terminal and run the following command:
npm install
npm install @os1-platform/console-ui-react
npm install @os1-platform/console-ui-react
﻿
This command adds the Console UI SDK to your project’s dependencies, allowing developers to import and use it within their application.
📘 Update Console Version  
You can also run the npm install @os1-platform/console-ui-react command to update Console to the latest version. 
Step 2: Integrate the SDK
To begin the integration process, developers need to import the OS1Provider function from the library. OS1Provider is a context provider that allows child components to access the Console UI features.
See the JavaScript example of how to integrate the SDK below:
JS
import { OS1Provider } from "@os1-platform/console-ui-react";

<OS1Provider
  clientId={"platform:app:ui"} // The clientId you receive after creating an app.
  loginRedirectPath={"/success"} // Path to redirect users after successfully logging in for the first time. 
  logoutRedirectPath={"/"} //Path to redirect users after logging out. 
  appId={"appId"} //The appId you recieve after creating an app 
	devOrgName={"Logisticsworld"} // Optional: Developers can  pass this parameter while testing their integration with the console in their development environment. This parameter should not be passed in production application.
  
>
  <Initiate setConsole={handleConsoleInstanceChange} /> //Your component for setting the Console UI instance.
</OS1Provider>;
import { OS1Provider } from "@os1-platform/console-ui-react";

<OS1Provider
  clientId={"platform:app:ui"} // The clientId you receive after creating an app.
  loginRedirectPath={"/success"} // Path to redirect users after successfully logging in for the first time. 
  logoutRedirectPath={"/"} //Path to redirect users after logging out. 
  appId={"appId"} //The appId you recieve after creating an app 
	devOrgName={"Logisticsworld"} // Optional: Developers can  pass this parameter while testing their integration with the console in their development environment. This parameter should not be passed in production application.
  
>
  <Initiate setConsole={handleConsoleInstanceChange} /> //Your component for setting the Console UI instance.
</OS1Provider>;
﻿
📘 Retrieve credentials﻿
Refer to the Getting Started with OS1 Platform for documentation for retrieving your credentials.
This code block does several things:
It imports the OS1Provider function which provides the SDK functionality.
It enables authentication by setting the clientID, loginRedirectPath, and logoutRedirectPath.
It uses the Initiate function to set the Console UI Instance.
Step 3: Create a Component to use the Console UI Context
After importing the OS1Provider, you’ll need to pass a function as a prop to your application with a setState method. The Console UI context enables developers to use the Console UI’s state in their client application. This state is essential to manage user sessions, permissions, navigation, and other UI elements.
To use the Console UI context, create a component that uses the ConsoleUIContext and sets its state.
See the example below to create a component:
JS
import React from "react";
import { ConsoleUIContext } from "@os1-platform/console-ui-react";

function Initiate(props) {
  const consoleInstance = React.useContext(ConsoleUIContext);
  if (consoleInstance) {
    props.setConsole(consoleInstance);
  }
}

export default Initiate;
import React from "react";
import { ConsoleUIContext } from "@os1-platform/console-ui-react";

function Initiate(props) {
  const consoleInstance = React.useContext(ConsoleUIContext);
  if (consoleInstance) {
    props.setConsole(consoleInstance);
  }
}

export default Initiate;
﻿
In this component:
The ConsoleUIContext is accessed during the React.useContext` hook.
If a Console UI instance is present, it’s set as the state of the component, allowing it to use the Console UI.
﻿
Step 4: Create a Network Client for API Requests
For an application to communicate with the backend services, developers need to establish a network client. The Console UI SDK provides the OS1HttpClient API for this purpose. This helps to create an instance of the network client with the necessary configurations and authentications.
JS
import { OS1HttpClient } from '@os1-platform/console-ui-react';

if  (consoleInstance) {
      const  instance = new OS1HttpClient(consoleInstance.authInitializer, `https://example.com`); // Base url is set in OS1HttpClient class.
 }

import { OS1HttpClient } from '@os1-platform/console-ui-react';

if  (consoleInstance) {
      const  instance = new OS1HttpClient(consoleInstance.authInitializer, `https://example.com`); // Base url is set in OS1HttpClient class.
 }
﻿
In the code snippet above, the OS1HttpClient function accepts the base URL for your API endpoints as well as an instance name. This setup allows your application to handle all API interactions via the instance object.
﻿
Step 5: Displaying Toast Notifications
Developers can use toast notifications to show transient, non-disruptive messages to their end users. This enables apps to quickly notify users of successful operations, pending tasks, or potential errors. Developers can use the OS1Toast function from the SDK to use this feature in their web application.
JS
const toastConfig = {
   bgColor: "yellow", // background color of the toast [green,red,yellow,black,white]
   message: "Operation Successful", // message that will be shown inside the toast [128 character limit]
   timeout: 10, // time in seconds after which toast will disappear
   icon: "error", // icon that will be appearing before the message [info,error,warning,success,failure,none]
   closeButton: true, // denotes whether the close button will be present on the right of the toast
}

<OS1Toast elementId={"toastElement"} toastConfig={toastConfig} />
const toastConfig = {
   bgColor: "yellow", // background color of the toast [green,red,yellow,black,white]
   message: "Operation Successful", // message that will be shown inside the toast [128 character limit]
   timeout: 10, // time in seconds after which toast will disappear
   icon: "error", // icon that will be appearing before the message [info,error,warning,success,failure,none]
   closeButton: true, // denotes whether the close button will be present on the right of the toast
}

<OS1Toast elementId={"toastElement"} toastConfig={toastConfig} />
﻿
Each toast element should have a unique elementID. This allows developers to manage multiple toast notifications effectively and ensures that they can control each notification individually when required. ConsoleInstance is the instance of Console UI that is being used in the client app to use Console UI features.
﻿
Step 6: Add Modal Components
Developers can use modals for obtaining user confirmation, providing important information, or capturing user input. To integrate a modal component in your application, use the OS1Modal function from the SDK. See the example code below:
JS
const modalConfig = {
  title: "Deactivate", // Title of the modal [96 characters limit]
  message: "Do you want to continue?", // message that will be appearing on the modal
  icon: "info", // icon that will be appearing along with the message [info,error,warning,success,failure,none]
  buttons: [
    // maximum two buttons allowed
    {
      id: "button-element-1", // unique id of the button
      backgroundColor: "green", // background color of the button
      text: "Cancel", // text appearing on the button
      event: "upEvent", // unique name of the custom event that will be triggered on click
    },
  ],
};
<OS1Modal
  elementId={"modalElement"}
  modalConfig={modalConfig}
/>;
const modalConfig = {
  title: "Deactivate", // Title of the modal [96 characters limit]
  message: "Do you want to continue?", // message that will be appearing on the modal
  icon: "info", // icon that will be appearing along with the message [info,error,warning,success,failure,none]
  buttons: [
    // maximum two buttons allowed
    {
      id: "button-element-1", // unique id of the button
      backgroundColor: "green", // background color of the button
      text: "Cancel", // text appearing on the button
      event: "upEvent", // unique name of the custom event that will be triggered on click
    },
  ],
};
<OS1Modal
  elementId={"modalElement"}
  modalConfig={modalConfig}
/>;
﻿
Listen for the event when a button is clicked; event.details will contain the modal element ID.
Step 7: Customize Header Controls
Developers can personalize header controls by passing injectable controls as properties to the OS1Provider component. This enables developers to tailor the look and feel of the header to match their application’s style and needs, improving the end-user experience. See the example JavaScript below for implementation:
JS

import { OS1Provider } from "@os1-platform/console-ui-react";

 const controls = [{
     type: "AutoComplete", //Type can be TextBox,TextBoxButton,DropDown, SearchBox, AutoComplete
     width: 100, // width as percentage of the maximum width that is assigned to injectable component
     placeholder: "Search Items", // placeHolder text
     id: "AutoComplete1", //Unique Id which distinguish it with other injectable controls.
     float: "left", // Option to align items left or right
     functionBoundOption: autoComplete(), // Function that returns a value as an array of object in the form of [{ value: string, text: string }]
 }]
  <OS1Provider clientId={"platform:app:ui"} loginRedirectPath={"/fms/success"} logoutRedirectPath={"/"} devOrgName={"delhivery"} controls ={controls} appId={'SolutionName-appId'}>
             <Initiate setConsole={handleConsoleInstanceChange} />
 </OS1Provider>



import { OS1Provider } from "@os1-platform/console-ui-react";

 const controls = [{
     type: "AutoComplete", //Type can be TextBox,TextBoxButton,DropDown, SearchBox, AutoComplete
     width: 100, // width as percentage of the maximum width that is assigned to injectable component
     placeholder: "Search Items", // placeHolder text
     id: "AutoComplete1", //Unique Id which distinguish it with other injectable controls.
     float: "left", // Option to align items left or right
     functionBoundOption: autoComplete(), // Function that returns a value as an array of object in the form of [{ value: string, text: string }]
 }]
  <OS1Provider clientId={"platform:app:ui"} loginRedirectPath={"/fms/success"} logoutRedirectPath={"/"} devOrgName={"delhivery"} controls ={controls} appId={'SolutionName-appId'}>
             <Initiate setConsole={handleConsoleInstanceChange} />
 </OS1Provider>

﻿
You can include up to three injectable controls, but each must have a unique ID.
Step 8: Managing Events from Injectable Controls
Developers can listen for events emitted by injectable controls using the ConsoleUIContext state variable. This enables your application to respond to user actions and deliver interactive experiences.
Here’s an example in JavaScript:
JS
const { consoleInstance } = props;
if (consoleInstance) {
  consoleInstance
    .eventBus()
    .on(consoleInstance.events().OnChangeEvent, (e) =>
      window.console.log(e)
    );
}
const { consoleInstance } = props;
if (consoleInstance) {
  consoleInstance
    .eventBus()
    .on(consoleInstance.events().OnChangeEvent, (e) =>
      window.console.log(e)
    );
}
﻿
﻿
Setting up Console Configuration
Customizing Console Settings can help developers integrate their applications effectively and ensure a streamlined interaction with the Console UI.
Configuring Request Headers
To securely communicate with the Console UI, the TheNetworkClient automatically configures the following headers for requests:
x-coreos-access (Access token)
x-coreos-tid (Tenant ID)
x-coreos-userinfo (User info)
x-coreos-auth (Auth token)
These headers act as work with the Console UI’s backend, passing essential authentication information with each API request. To manage these headers, the OS1 SDK provides the following options.
withAccess
withTid
withUserInfo
withAuth
Request headers are an integral part of securing and identifying requests made to the API. By default, all headers are active (true). To exclude a specific header, set its value to false.
Remember that the x-coreos-access token is checked and refreshed (if expired) for each aPI request. The x-coreos-userinfo and x-coresos-auth headers contain the USER ID and ID token respectively.
Use REST API methods, on the instance created for OS1HttpClient
See the sample code below for configuring request headers:
JS
const handleClick = () => {
//here consoleInstance is the state variable of ConsoleUIContext;
    if (consoleInstance) {
        const client = new OS1HttpClient(consoleInstance.authInitializer,`https://example.com`);
//consoleInstance.authInitializer is an instance of AAA class that we get from ConsoleUi Context
        const reqHeaders: any = {
            withAccess: false,
            withTid: false,
            withUserInfo: false,
            withAuth: false,
        };
        client.get(`/users`).then(response => {
             console.log("api response", response.data)
         }).catch(function (err) {
             console.error('error', err);
         });
    };
};


const handleClick = () => {
//here consoleInstance is the state variable of ConsoleUIContext;
    if (consoleInstance) {
        const client = new OS1HttpClient(consoleInstance.authInitializer,`https://example.com`);
//consoleInstance.authInitializer is an instance of AAA class that we get from ConsoleUi Context
        const reqHeaders: any = {
            withAccess: false,
            withTid: false,
            withUserInfo: false,
            withAuth: false,
        };
        client.get(`/users`).then(response => {
             console.log("api response", response.data)
         }).catch(function (err) {
             console.error('error', err);
         });
    };
};

﻿
Time Conversion and Retrieval
convertTime: Converts the time in your application to your desired format.
currentTimeZone: Returns the current timezone stored in the browser.
JS
const { consoleInstance } = props;
if (consoleInstance) {
  console.log(
    consoleInstance.convertTime("2014-06-01 12:00", "MM-DD-YYYY HH:mm:ss")
  ); // In this 2nd parameter i.e. format in which we want to convert time is optional.
  console.log(consoleInstance.currentTimeZone());
}
const { consoleInstance } = props;
if (consoleInstance) {
  console.log(
    consoleInstance.convertTime("2014-06-01 12:00", "MM-DD-YYYY HH:mm:ss")
  ); // In this 2nd parameter i.e. format in which we want to convert time is optional.
  console.log(consoleInstance.currentTimeZone());
}
﻿
﻿
Updated 27 Feb 2024
Did this page help you?
Console Banner API
Vue.JS Integration with Console UI