Console-UI-React Integration

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 refer to the section obtain credentials integration steps step 1 install console ui start by installing the @os1 platform/console ui react library in your react project using npm 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 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) { 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 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 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 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 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 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 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 { 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 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 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 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 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