How to: Integrate your existing application with the Console UI
The Console UI acts as the glue that binds the application and the end-user together. After you register your App in the OS1 developer portal and integrate it with the Console UI, it is ready to be made available to end-users on their respective landing pages.
For more information about Console UI, see Console UI Overview.
This guide walks through the installation and installation of the Console UI SDK in your application.
Installation
Run the following command in your project to install the console-ui-react-sdk
package:
npm install @foxtrotplatform/console-ui-react-sdk
Usage
Step 1: Integrate the SDK
Import the OS1Provider
function from the library and use it to enable authentication and render the header and sidebar. Next, pass a function as a prop to your application with a setState
method that sets the state of the Console UI instance.
import { OS1Provider } from "@foxtrotplatform/console-ui-react-sdk";
<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={"SolutionName-appId"} //The appId you recieve after creating an app
devOrgName={"delhivery"} // Optional: Only pass this parameter when using development mode.
>
<Initiate setConsole={handleConsoleInstanceChange} /> //Your component for setting the Console UI instance.
</OS1Provider>;
Step 2: Create a Component to use the Console UI Context
Create a component that uses the ConsoleUIContext
and sets its state to be used by the client application.
import React from "react";
import { ConsoleUIContext } from "@foxtrotplatform/console-ui-react-sdk";
function Initiate(props) {
const consoleInstance = React.useContext(ConsoleUIContext);
if (consoleInstance) {
props.setConsole(consoleInstance);
}
}
export default Initiate;
Create a Network Client for API Requests
Use the OS1HttpClient
API to set up a network client for API requests, passing the authInitializer
property from ConsoleUIContext
:
import { OS1HttpClient } from '@foxtrotplatform/console-ui-react-sdk';
class NetworkClient {
public readonly instance: any;
constructor(`instanceName`) {
this.instance = OS1HttpClient.createClient({
baseURL: `https://abc.preprod.fxtrt.io/core/api/v1/aaa`,
},`instanceName`);
}
}
Displaying Toast Notifications
Use the Toast
function to display toast notifications in your web application.
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 clientId={"platform:app:ui"} loginRedirectPath={"/fms/success"} logoutRedirectPath={"/"} devOrgName={"delhivery"} appId={"Single Leg-app:435858a9-1238-5ca9-b100-a5d46d108910"} elementId={"toastElement"} toastConfig={toastConfig} />
Each toast element should have a unique
elementId
.
Add Modal Components
Utilize the modal
function to incorporate modal components into your webpage:
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
clientId={"platform:app:ui"}
loginRedirectPath={"/fms/success"}
logoutRedirectPath={"/"}
devOrgName={"delhivery"}
appId={"Single Leg-app:435858a9-1238-5ca9-b100-a5d46d108910"}
elementId={"modalElement"}
modalConfig={modalConfig}
/>;
Listen for the event when a button is clicked; `event.details will contain the modal element ID.
Customize Header Controls
Customize the header by passing injectable controls as props to the OS1Provider
component.
import { OS1Provider } from "@foxtrotplatform/console-ui-react-sdk";
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 have up to 3 injectable controls, and each must have a unique ID.
Events from Injectable Controls
Use the ConsoleUIContext
state variable to listen for events emitted by injectable controls.
const { consoleInstance } = props;
if (consoleInstance) {
consoleInstance
.eventBus()
.on(consoleInstance.events().OnChangeEvent, (e) =>
window.console.log(e)
);
}
_Exposed events include
OnChangeEvent
,OnBlurEvent
,OnScrollEvent
,OnClickEvent
, andOnFocusEvent
forinjectableID
Console Settings
Configuring Request Headers
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)
You can manage these headers using the following options:
withAccess
withTid
withUserInfo
withAuth
Notes
- By default, all headers are set to
true
. To remove a header from a request, set its value tofalse
. - Access tokens are verified and regenerated (if expired) every time an API request is made.
- The
x-coreos-userinfo
header contains the user ID. - The
x-coresos-auth
header contains the ID token.
See the sample snippet:
import NetworkClient from "./networkClient";
const handleClick = () => {
//here consoleInstance is the state variable of ConsoleUIContext;
if (consoleInstance) {
const client1 = new NetworkClient(consoleInstance.authInitializer); //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,
};
client1.users.('45', reqHeaders).catch(function (err) {
console.log('errr', err);
console.log('error', JSON.stringify(err));
});
};
};
Contact Us Page
You can provide a support link for customers by using the Contact Us page. We provide the following:
- A text area describing user's issues in detail
- An option to upload a screenshot that may help clarify a user's issue.
This will then create a ticket to track the support request.
Timezone Settings
Users can change the application's timezone. Initially, the timezone is set according to the tenant's preferences, but users can change it according to their needs. The chosen timezone will be stored in the browser's local storage.
Time Conversion and Retrieval
The SDK exposes the converTime
and currentTimeZone
functions:
convertTime
: Converts the time in your application to your desired format.currentTimeZone
: Returns the current timezone stored in the browser.
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());
}
Customizing App Navigation
End users can choose what happens when they click on an app in the Console side navigation menu. They can select whether they would like to open it in the current window or a new tab by opening the 'User preferences' in the profile dropdown and selecting the desired option under Set App Redirect Behavior.
Updated about 4 hours ago