Console-UI-React Integration

31min
Overview
This document provides step-by-step instructions for integrating the Console UI using React.js. It covers the setup process, configurations, and example code snippets to help you get started effectively.
Prerequisites
Before you start the integration process, ensure that you have the following systems installed:
Node.js and npm
Basic knowledge of React.js
Access to the OS1 Developer Portal to obtain your Client ID and App ID.
Integration Steps
Step 1: Install Console UI
Start by installing the @os1-platform/console-ui-react library in your React project using npm:
JS
bash
npm install @os1-platform/console-ui-react
bash
npm install @os1-platform/console-ui-react
﻿
Step 2: Authentication Setup
Before integrating the Console UI, you need to set up authentication. This involves obtaining the following credentials:
Client ID: This is a unique identifier for your application.
App ID: This identifies your application within the platform.
Steps to Obtain Credentials
1. Register Your Application:
Go to the Developer Portal.
Register your application by providing necessary details such as the application name, description, and redirect URIs.
2. Obtain Client ID and App ID:
After registering, you will receive your Client ID and App ID. Keep these credentials secure as you will use them in your application.
3. Configure Redirect Paths:
Set up redirect paths for login and logout in your application settings in the Developer Portal to ensure smooth authentication flow.
Step 3: Set Up Console Configuration
In this step, we configure the Console UI using the `OS1Provider` component, which allows us to manage the console's settings and access its functionalities throughout the application.
Import Required Modules
 We start by importing React and the `OS1Provider` from the Console UI library, which are necessary for creating our application component and providing the Console UI context.
 2.   Define the Console Configuration:
We create a consoleConfig object that holds important configuration values needed to connect to the Console UI. This includes:
clientId: A unique identifier for your application that is required for authentication.
loginRedirectPath: The path to which the application will redirect users after they successfully log in.
logoutRedirectPath: The path to which the application will redirect users after they log out.
devTenantId: An optional parameter for development mode that can help in testing.
appId: A unique identifier for your application within the Console UI platform.
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 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 integral to 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.
Note: Remember that the x-coreos-access token is checked and refreshed (if expired) for each API request. 
The x-coreos-userinfo and x-coreos-auth headers contain the USER ID and ID token respectively. 
The x-coreos-auth contains the id_token. If you want to use X-Coreos-Request-Id, that is generated by the library and also needs to send request headers, then send the requestId parameter as undefined.
Example: Configuring Request Headers
JS
const handleClick = () => {
  // here consoleInstance is the state variable of ConsoleUIContext;
  if (consoleInstance) {
    const client = new OS1HttpClient(
      consoleInstance.authInitializer,
      `https://abc.domain.com`
    ); // consoleInstance.authInitializer is an instance of AAA class that we get from ConsoleUI Context
    const reqHeaders = {
      withAccess: false,
      withTid: false,
      withUserInfo: false,
      withAuth: false,
    };

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

    client
      .get(`/users`)
      .then((response) => {
        console.log('API response', response.data);
      })
      .catch(function (err) {
﻿
JS
console.error('Error', err);
      });

    // This example covers the case when requestId is generated from console and requestHeaders are passed
    client
      .post(`/todos`, { todo: 'study' }, undefined, reqHeaders)
      .then((response) => {
        console.log('API response', response.data);
      })
      .catch(function (err) {
        console.error('Error', err);
      });
  }
};
console.error('Error', err);
      });

    // This example covers the case when requestId is generated from console and requestHeaders are passed
    client
      .post(`/todos`, { todo: 'study' }, undefined, reqHeaders)
      .then((response) => {
        console.log('API response', response.data);
      })
      .catch(function (err) {
        console.error('Error', err);
      });
  }
};
﻿
Step 4: Set Up OS1 Provider
Set up the OS1Provider component in your application:
JS
import React from 'react';
import { OS1Provider } from '@os1-platform/console-ui-react';
import Initiate from './Initiate'; // Your component for setting the Console UI instance

const App = () => {
  return (
    <OS1Provider
      clientId={`yourClientId`} // Replace with your actual Client ID
      loginRedirectPath={'/abc'} // Path after first-time login
      logoutRedirectPath={'/'} // Path after logout
      devTenantId={'tenantId'} // Optional: for development mode
      appId={'yourAppId'} // Replace with your actual App ID
    >
      <Initiate setConsole={handleConsoleInstanceChange} />
    </OS1Provider>
  );
};

export default App;
import React from 'react';
import { OS1Provider } from '@os1-platform/console-ui-react';
import Initiate from './Initiate'; // Your component for setting the Console UI instance

const App = () => {
  return (
    <OS1Provider
      clientId={`yourClientId`} // Replace with your actual Client ID
      loginRedirectPath={'/abc'} // Path after first-time login
      logoutRedirectPath={'/'} // Path after logout
      devTenantId={'tenantId'} // Optional: for development mode
      appId={'yourAppId'} // Replace with your actual App ID
    >
      <Initiate setConsole={handleConsoleInstanceChange} />
    </OS1Provider>
  );
};

export default App;
﻿
Step 5: Create the Initiate Component
Use ConsoleUIContext to set the console instance:
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 following instructions have been passed:
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.
Now that you have created the Console UI instance, it allows you to use the Console UI and configure its functionalities. Refer to the below section to learn what are the functionality you can configure, how to use them. Know everything in the sections below with the step-by-step guide. 
Configurable Functionalities
1. Injectable Controls
Injectable controls are UI components that developers can add to the Console UI to enhance user interactivity. These controls can be configured based on the application's requirements and can be injected into various parts of the console, such as the header or sidebar.
You can provide injectable controls to the header and sidebar by passing them as props to OS1Provider. Each control must have a unique ID and can be configured based on your application requirements.
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 maximum width that is assigned to injectable component
     placeholder: "Search Items", // placeHolder text
     id: "AutoComplete1", //Unique Id which distinguishes it with other injectable controls.
     float: "left", // Option to align items left or right
     functionBoundOption: autoComplete(), // Function that return value as an array of object in the form of [{ value: string, text: string }]
 }]
  <OS1Provider clientId={`sampleClientId`} loginRedirectPath={"/abc"} logoutRedirectPath={"/"} devTenantId={"tenantId"} 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 maximum width that is assigned to injectable component
     placeholder: "Search Items", // placeHolder text
     id: "AutoComplete1", //Unique Id which distinguishes it with other injectable controls.
     float: "left", // Option to align items left or right
     functionBoundOption: autoComplete(), // Function that return value as an array of object in the form of [{ value: string, text: string }]
 }]
  <OS1Provider clientId={`sampleClientId`} loginRedirectPath={"/abc"} logoutRedirectPath={"/"} devTenantId={"tenantId"} controls ={controls} appId={'SolutionName-appId'}>
             <Initiate setConsole={handleConsoleInstanceChange} />
 </OS1Provider>
﻿
Note: There can not be more than 3 injectable controls and each injectable control should be given a unique id. It can have any type mentioned in the below section. 
=A function that returns an array of suggestions based on user input.
Types of Injectable Controls
Here are the various types of injectable controls along with their configurations and examples:
A Textbox allows users to input simple text.
Configuration Example:
JS
const textboxControl = {
            type: "TextBox",
            width: 100, // Width of the textbox
            placeholder: "Search Package", // Placeholder text
            float: "left", // Positioning of the control
            id: "TextBox1"  // Unique ID for the control
            attributes: {
                maxlength: "50";
            }
        }
const textboxControl = {
            type: "TextBox",
            width: 100, // Width of the textbox
            placeholder: "Search Package", // Placeholder text
            float: "left", // Positioning of the control
            id: "TextBox1"  // Unique ID for the control
            attributes: {
                maxlength: "50";
            }
        }
﻿
Here, attributes is an optional attributes parameter that contains an object which defines if any attribute needs to be set to injectable controls.
OnChange and OnBlur events are emitted by this injectable control.
To use textbox with button in console ui, follow the below configuration:
JS
const textboxControl = {
    type: "TextBoxButton",
    width: 100,
    placeholder: "Search Package",
    float: "left",
    id: "TextBoxButton1"
    attributes: {
        maxlength: "50";
    }
    button: true,
    buttonText: "Search",
    buttonColor: "red"
  }
const textboxControl = {
    type: "TextBoxButton",
    width: 100,
    placeholder: "Search Package",
    float: "left",
    id: "TextBoxButton1"
    attributes: {
        maxlength: "50";
    }
    button: true,
    buttonText: "Search",
    buttonColor: "red"
  }
﻿
To use SearchBox with Lens Icon in console ui, we provide following configuration:
JS
const textboxControl = {
          type: "SearchBox",
          width: 100,
          placeholder: "Search Package",
          float: "right",
          id: "SearchBox1"
          attributes: { maxlength: "50"; }
          lensIcon: true
        }
const textboxControl = {
          type: "SearchBox",
          width: 100,
          placeholder: "Search Package",
          float: "right",
          id: "SearchBox1"
          attributes: { maxlength: "50"; }
          lensIcon: true
        }
﻿
Note:
Here lensIcon is optional, if it is set to true then lensIcon will be shown in injectable control.
Here, attributes is an optional attributes parameter that contains an object which defines if any attribute needs to be set to injectable controls.
OnChange, onBlur, onFocus is emitted on the input box.
To use AutoComplete in console ui, we provide following configuration:
JS
 {
  type: "AutoComplete",
  width: 100,
  placeholder: "Search Package",
  float: "right",
  id: "AutcoComplete1"
  functionBoundOption: autoComplete(), // This field can be a function which return array of Objects or normal array of objects in the form of [{ value: string, text: string }],
  }
 {
  type: "AutoComplete",
  width: 100,
  placeholder: "Search Package",
  float: "right",
  id: "AutcoComplete1"
  functionBoundOption: autoComplete(), // This field can be a function which return array of Objects or normal array of objects in the form of [{ value: string, text: string }],
  }
﻿
Note:
In this functionBoundOption is passed when options are static and they can be passed in the form of [{ value: string, text: string }], User can declare this as value of this field or can pass the function that returns the value in above mentioned format.
For setting options dynamically, user can set hasAsyncFunctionBoundOption, then they can call functionBoundAutoCompleteOption from @os1-platform/console-ui-react and pass array of objects and id of autocomplete as parameters to that function.
JS
import { functionBoundAutoCompleteOption } from '@os1-platform/console-ui-react';

if (consoleInstance) {
  functionBoundAutoCompleteOption(autoCompleteValues, 'AutoComplete1'); // here firstParament is a variable that contains the array of objects that needs to be present in the dropdown. Second parameter contains the id of dropdown on which we want to load the values
}
import { functionBoundAutoCompleteOption } from '@os1-platform/console-ui-react';

if (consoleInstance) {
  functionBoundAutoCompleteOption(autoCompleteValues, 'AutoComplete1'); // here firstParament is a variable that contains the array of objects that needs to be present in the dropdown. Second parameter contains the id of dropdown on which we want to load the values
}
﻿
OnChange, onBlur, OnClick, OnScroll is emitted on this injectable controls
A Dropdown lets users select an option from a predefined list.
Configuration Example:
JS
const dropdownControl = {
  {
  type: "DropDown", // type of injectable control
  width: 100, // maximum width in percentage that can be given
  placeholder: "Search Package", // placeholder text
  float: "right", // aligning the injectable control in left or right direction
  id: "DropDown1" // unique id that can be given to injectable control
  functionBoundOption: [{ value: "1", text: "Mobiles" },{ value:"2", text: "Laptops" }], // This field can be a function which return array of Objects or normal array of objects in the form of [{ value: string, text: string }],
  throttleTime: 300 // this is an optional parameter which enables setting throttle time for on scroll Event. By default it is 500 ms.
  }
}
const dropdownControl = {
  {
  type: "DropDown", // type of injectable control
  width: 100, // maximum width in percentage that can be given
  placeholder: "Search Package", // placeholder text
  float: "right", // aligning the injectable control in left or right direction
  id: "DropDown1" // unique id that can be given to injectable control
  functionBoundOption: [{ value: "1", text: "Mobiles" },{ value:"2", text: "Laptops" }], // This field can be a function which return array of Objects or normal array of objects in the form of [{ value: string, text: string }],
  throttleTime: 300 // this is an optional parameter which enables setting throttle time for on scroll Event. By default it is 500 ms.
  }
}
﻿
Note: 
In this functionBoundOption is passed when options are static and they can be passed in the form of [{ value: string, text: string }], User can declare this as value of this field or can pass the function that returns the value in above mentioned format.
For setting options dynamically, users can set hasAsyncFunctionBoundOption, then they can call functionBoundOption from @os1-platform/console-ui-react and pass an array of objects and id of dropdown as parameters to that function.
For setting initial Value to dropdown, OS1DropDownDefaultValue from @os1-platform/console-ui-react needs to be passed with value and id of dropdown. It can only be passed when an instance of console UI is available or console UI h
as been loaded.
import {
  functionBoundOption,
  OS1DropDownDefaultValue,
} from '@os1-platform/console-ui-react';

if (consoleInstance) {
  functionBoundOption(dropDownValues, 'Dropdown1'); // here firstParament is a variable that contains the array of objects that needs to be present in dropdown. Second parameter contains the id of dropdown on which we want to load the values
  OS1DropDownDefaultValue('initialValue', 'DropDown1'); // Here first parameter contains the value that needs to passed as  initialValue, second Parameter is the id of the dropdown on which Id, needs to be set.
}
2. Using Toast Notifications
Toast notifications are temporary messages that appear on the screen to provide feedback to the user. You can customize their content, duration, and behavior, such as allowing users to close or delete them.
Use the Toast function to render toast components in your webpage. For example:
JS
  const [toastMsg, setToastMsg] = useState<string>();
 useEffect(() => {
 if (searchParams.has('success')) {
   const message = searchParams.get('message');

   if (message === 'created') {
       setToastMsg('Vehicle created');
     }
   }
 }
}, [searchParams, setSearchParams]);

const toastConfig = {
   bgColor: "green", // background color of the toast [green,red,yellow,black,white]
   message: toastMsg, // message that will be shown inside the toast [128 character limit]
   timeout: 10, // time in seconds after which toast will disappear
   icon: "success", // 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 [toastMsg, setToastMsg] = useState<string>();
 useEffect(() => {
 if (searchParams.has('success')) {
   const message = searchParams.get('message');

   if (message === 'created') {
       setToastMsg('Vehicle created');
     }
   }
 }
}, [searchParams, setSearchParams]);

const toastConfig = {
   bgColor: "green", // background color of the toast [green,red,yellow,black,white]
   message: toastMsg, // message that will be shown inside the toast [128 character limit]
   timeout: 10, // time in seconds after which toast will disappear
   icon: "success", // 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} />
﻿
In the above example, developers can set the toast message on the events, then can set the message in the state variable and can use it in their react app.
Note: Each toast element that is to be rendered on the page should be given a unique elementId.
3. Implement Modal
Use the Modal function to render a modal component in your webpage. For example:
JS
 const [modalMsg, setModalMsg] = useState<string>();
 useEffect(() => {
 if (searchParams.has('success')) {
   const message = searchParams.get('message');

   if (message === 'created') {
       setModalMsg('Vehicle created successfully');
     }
   }
 }
}, [searchParams, setSearchParams]);
const modalConfig = {
  title: 'Vehicle Created', // Title of the modal [96 characters limit]
  message: modalMsg, // message that will be appearing on the modal
  icon: 'success', // 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: 'Ok', // text appearing on the button
      event: 'upEvent', // unique name of the custom event that will be triggered on click
    },
  ],
};

 useEffect(() => {
    window.addEventListener('upEvent', (event) => {
       document.getElementById('modaleElement')?.classList.toggle('hidden');
    });
}, []);

<OS1Modal elementId={'modalElement'} modalConfig={modalConfig} />;
 const [modalMsg, setModalMsg] = useState<string>();
 useEffect(() => {
 if (searchParams.has('success')) {
   const message = searchParams.get('message');

   if (message === 'created') {
       setModalMsg('Vehicle created successfully');
     }
   }
 }
}, [searchParams, setSearchParams]);
const modalConfig = {
  title: 'Vehicle Created', // Title of the modal [96 characters limit]
  message: modalMsg, // message that will be appearing on the modal
  icon: 'success', // 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: 'Ok', // text appearing on the button
      event: 'upEvent', // unique name of the custom event that will be triggered on click
    },
  ],
};

 useEffect(() => {
    window.addEventListener('upEvent', (event) => {
       document.getElementById('modaleElement')?.classList.toggle('hidden');
    });
}, []);

<OS1Modal elementId={'modalElement'} modalConfig={modalConfig} />;
﻿
In the above example, a modal message has been set up using toast. The button on modal has been assigned a unique event name, and the developer can listen to that event and perform various operations on that basis.
 Note: Listen to the event when the button is clicked, event.details will contain the modal element Id.
4. 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.
Use the state variable of ConsoleUIContext context to listen to events emitted by injectable controls. This instance is usually passed as a prop to apps. For example:
const { consoleInstance } = props;
if (consoleInstance) {
  consoleInstance
    .eventBus()
    .on(consoleInstance.events().OnChangeEvent, (e) =>
      window.console.log(e)
    );
}
Note: We are exposing OnChangeEvent, OnBlurEvent, OnScrollEvent, OnClickEvent, OnFocusEvent, OnSearchEvent for injectableId's.
5. Create a Network Client for API Requests
Use OS1HttpClient API to create a client variable for network requests and pass the authInitializer property of ConsoleUiContext as a constructor parameter.
import { OS1HttpClient } from '@os1-platform/console-ui-react';
if (consoleInstane) {
  var client = new OS1HttpClient(
    consoleInstane.authInitializer,
    `https://abc.domain.com`
  ); // Base url is set in OS1HttpClient class.
}
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.
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());
}
﻿
Updated 27 Jan 2025
Did this page help you?
Console SDK
Vue.JS Integration with Console UI