How to: Integrate App with Console UI using Vue.JS

25min
Overview
The Console UI SDK helps developers integrate Console UI components into their applications, such as authentication, headers, sidebars, and modals. These components make it easier for users to navigate and access content. 
This guide outlines the integration of the Console UI SDK with your application using the Vue.js library. To begin, developers should install the “console-ui-vue” package in their projects. This package includes all the essential components and utilities for seamless integration.
📘Note﻿
Console UI is built using Vue.JS 3, and hence it is not compatible with earlier versions.
Step 1: Installation
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-vue
This command adds the Console UI SDK to your project's dependencies, enabling developers to import and utilize it within their application.
📘 Update Console Version  
You can also run the npm install @os1-platform/console-ui-vue command to update Console to the latest version. 
Step 2: Integration of the SDK
Start the integration process by importing the OS1Provider component from the library. This component acts as a context provider, granting child components access to Console UI features.
See the Vue.JS example of how to integrate the SDK below:
JS
<script>
    import { OS1Provider } from '@os1-platform/console-ui-vue';
    const getConsoleInit = (event:any) =>{
         consoleInit.value = event; // here consoleInit is ref which listens to an event of console UI
     }
</script>

<OS1Provider
  clientId=`sampleClientId` // This is the clientId that you get after creating an app.
  loginRedirectPath='/abc' // path that will be given when someone logins into the console UI for the first time
  logoutRedirectPath='/' //path that needs to be redirected when someone logouts from your application.
  devTenantId='tenantId' // This is an optional parameter that needs only to be passed when used in development mode.
  appId='SolutionName-appId' //initial appId on which you want to land when loading the console UI for the first time.
  @consoleInstance = "getConsoleInit" //Here function gets the value of an event that is passed from console ui and assigns its value to a variable so that it can be used in the client’s application.
>
<script>
    import { OS1Provider } from '@os1-platform/console-ui-vue';
    const getConsoleInit = (event:any) =>{
         consoleInit.value = event; // here consoleInit is ref which listens to an event of console UI
     }
</script>

<OS1Provider
  clientId=`sampleClientId` // This is the clientId that you get after creating an app.
  loginRedirectPath='/abc' // path that will be given when someone logins into the console UI for the first time
  logoutRedirectPath='/' //path that needs to be redirected when someone logouts from your application.
  devTenantId='tenantId' // This is an optional parameter that needs only to be passed when used in development mode.
  appId='SolutionName-appId' //initial appId on which you want to land when loading the console UI for the first time.
  @consoleInstance = "getConsoleInit" //Here function gets the value of an event that is passed from console ui and assigns its value to a variable so that it can be used in the client’s application.
>
﻿
Step 3: Providing Controls
Developers can provide injectable controls for headers, sidebars, or navigation bars by binding them to OS1Provider according to business requirements. 
JS
import { OS1Provider } from "@os1-platform/console-ui-vue";

 const controls = [{
     type: "AutoComplete", //Type can be TextBox,TextBoxButton,DropDown, SearchBox, AutoComplete
     width: 100, // Width as a percentage of the maximum width that is assigned to the injectable component
     placeholder: "Search Items", // Placeholder text
     id: "AutoComplete1", //Unique Id which distinguishes it from other injectable controls.
     float: "left", // Option to align items left or right
     functionBoundOption: autoComplete(), // Function that returns the value as an array of objects in the form of [{ value: string, text: string }]
 }]
  <OS1Provider
  clientId=`sampleClientId` 
  loginRedirectPath='/abc' 
  logoutRedirectPath='/' 
  devTenantId='tenantId' 
  appId='SolutionName-appId'
  :controls = "controls"
  @consoleInstance = "getConsoleInit" 
>
import { OS1Provider } from "@os1-platform/console-ui-vue";

 const controls = [{
     type: "AutoComplete", //Type can be TextBox,TextBoxButton,DropDown, SearchBox, AutoComplete
     width: 100, // Width as a percentage of the maximum width that is assigned to the injectable component
     placeholder: "Search Items", // Placeholder text
     id: "AutoComplete1", //Unique Id which distinguishes it from other injectable controls.
     float: "left", // Option to align items left or right
     functionBoundOption: autoComplete(), // Function that returns the value as an array of objects in the form of [{ value: string, text: string }]
 }]
  <OS1Provider
  clientId=`sampleClientId` 
  loginRedirectPath='/abc' 
  logoutRedirectPath='/' 
  devTenantId='tenantId' 
  appId='SolutionName-appId'
  :controls = "controls"
  @consoleInstance = "getConsoleInit" 
>
﻿
📘NOTE﻿
It's important to note that a maximum of 3 injectable controls are allowed, each assigned a unique ID.
Learn more about ﻿How to configure different injectable controls.﻿
Step 4: Adding the Toast Component
Render the Toast component on your webpage using the Toast function. Each configured Toast component must have a unique element ID.
Shown below is an example of configuring a Toast component:
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 the 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 the 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" />
﻿
Step 5: Adding the Modal Component
Use the modal function to configure modal components on your webpage. Listen for a button click event; the event.details will contain the modal element ID.
See the example below for configuring a modal component:
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 appear 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 appear 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"
/>;
﻿
Step 6: Using a Variable
Use a variable containing the emitted event value from the Console UI. This variable can be combined with the current instance to listen for events emitted by injectable controls.
JS
const { consoleInstance } = props;
if (consoleInstance) {
  consoleInstance.eventBus().on(props.consoleInstance.events().OnChangeEvent, e => window.console.log(e))
}
const { consoleInstance } = props;
if (consoleInstance) {
  consoleInstance.eventBus().on(props.consoleInstance.events().OnChangeEvent, e => window.console.log(e))
}
﻿
📘NOTE﻿
Currently exposed events for injectableIDs are OnChangeEvent, OnBlurEvent, OnScrollEvent, OnClickEvent, OnFocusEvent, and OnSearchEvent.
Use the OS1HttpClient class to create its instance and then use that instance to call the API. Incorporate the authInitializer property from ConsoleUiContext as a constructor parameter.
JS
import { OS1HttpClient } from '@os1-platform/console-ui-vue';

 setup(props: any) {
 let consoleInit = ref();

 watch(
   () => props.consoleInstance,
   (newConsoleInstance) => {
     consoleInit.value = new  OS1HttpClient(newConsoleInstance.authInitializer, 'https://os1devs.sandbox.getos1.com')
   }
 );
 }
import { OS1HttpClient } from '@os1-platform/console-ui-vue';

 setup(props: any) {
 let consoleInit = ref();

 watch(
   () => props.consoleInstance,
   (newConsoleInstance) => {
     consoleInit.value = new  OS1HttpClient(newConsoleInstance.authInitializer, 'https://os1devs.sandbox.getos1.com')
   }
 );
 }
﻿
Step 7: Configuring Headers
Utilize the REST API method on the instance created for the OS1HttpClient. 
This automatically configures headers for requests originating from NetworkClient, adding an access token, tenant ID, user info, or auth token headers to the actual request.
withAccess
withTid
withUserInfo
withAuth
Note
By default, all of these headers are set to true. To exclude them from the request, provide the value as false against these headers.
The access token is verified and, if expired, regenerated each time an API request is initiated.
The x-coreos-userinfo header includes the userId, and the x-coreos-auth header contains the id_token.
If the developer wants to use X-Coreos-Request-Id, they can pass the requestId parameter as undefined. This header is generated by the library and requires sending request headers. 
JS
const handleClick = () => {
//here consoleInstance is the state variable of ConsoleUIContext;
    if (props.consoleInstance) {
        const reqHeaders: any = {
            withAccess: false,
            withTid: false,
            withUserInfo: false,
            withAuth: false,
        };
         consoleInit.get(`/users`).then(response => {
          console.log("api response", response.data)
         }).catch(function (err) {
             console.error('error', err);
         });

      //This example covers cases when requestId is generated from the console and requestHeaders are passed
         consoleInit.post(`/todos`,{ "todo": "study" }, undefined, reqHeaders).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 (props.consoleInstance) {
        const reqHeaders: any = {
            withAccess: false,
            withTid: false,
            withUserInfo: false,
            withAuth: false,
        };
         consoleInit.get(`/users`).then(response => {
          console.log("api response", response.data)
         }).catch(function (err) {
             console.error('error', err);
         });

      //This example covers cases when requestId is generated from the console and requestHeaders are passed
         consoleInit.post(`/todos`,{ "todo": "study" }, undefined, reqHeaders).then(response => {
             console.log("api response", response.data)
         }).catch(function (err) {
             console.error('error', err);
         });
     };
};
﻿
Using the Help Button
Click on the “Need Help” button to query about any application or to use the product guide.
Click on the “Raise a Ticket” button and use the “Contact Us” page, to query about any application.
The text area is available to describe the issue in detail.
Additionally, upload screenshots if any, as it may help to understand the issue.
Once the query along with the details is received the support team will contact the developer.
Click on the “Product Guide” button to learn about the product.
Changing Time Zone
Developers can change the application's timezone by using the function provided by Console UI. The convertTime function converts time, while currentTimeZone retrieves the current timezone. When the timezone is updated, the UpdateTimeZoneEvent is emitted.
convertTime function is exposed to the developers, it converts the time of the developer’s application in their desired format, and currentTimeZone function gives the developer the current timezone that is stored in the browser. When TimeZone is updated it emits an UpdateTimeZoneEvent event.
JS
if (props.consoleInstance) {
  console.log(
    props.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(props.consoleInstance.currentTimeZone());
}
if (props.consoleInstance) {
  console.log(
    props.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(props.consoleInstance.currentTimeZone());
}
﻿
Step 8: Generating Access Token
To generate an Access Token, developers can use the getAuthenticationTokens method. For user info, the getUser method can be used. Authentication status can be checked using isAuthenticated(), calling the authInitializer method from the console UI context.
JS
if (props.consoleInstance) {
        const accessToken = await consoleInstance.authInitializer.getAuthenticationTokens();
        const userInfo = await consoleInstance.authInitializer.getUser();
        const isUserAuthenticated = await consoleInstance.authInitializer.isAuthenticated();
    }
if (props.consoleInstance) {
        const accessToken = await consoleInstance.authInitializer.getAuthenticationTokens();
        const userInfo = await consoleInstance.authInitializer.getUser();
        const isUserAuthenticated = await consoleInstance.authInitializer.isAuthenticated();
    }
﻿
Configuration for Injectable Controls offered
Certain standard parameters are passed to all injectable controls:
type: Specifies the type of injectable control (e.g., TextBox, TextBoxButton, AutoComplete, DropDown, SearchBox).
width: Defines the maximum percentage width.
placeholder: Displays placeholder text.
id: A unique identifier for the control.
float: An optional parameter indicating the component type.
How to configure different Injectable Controls in the Console UI
Here, configurations for different injectable controls are provided. Up to 3 injectable controls can be used.
Textbox
Configuration for adding a "textbox" in Console UI, emitting OnChange and OnBlur events.
JS
{
            type: "TextBox", 
            width: 100, 
            placeholder: "Search Package",
            float: "left", 
            id: "TextBox1" 
            attributes: {
                maxlength: "50";
            } 
        }
{
            type: "TextBox", 
            width: 100, 
            placeholder: "Search Package",
            float: "left", 
            id: "TextBox1" 
            attributes: {
                maxlength: "50";
            } 
        }
﻿
NOTE
Here, “attributes” is an optional parameter that holds an object defining whether any attributes should be assigned to injectable controls.
OnChange and OnBlur events are emitted by this injectable control.
TextBoxButton
Configuration for adding a "TextBoxButton", allowing customization of button appearance:
JS
{
    type: "TextBoxButton", 
    width: 100, 
    placeholder: "Search Package", 
    float: "left", 
    id: "TextBoxButton1"
    attributes: {
        maxlength: "50";
    } 
    button: true, 
    buttonText: "Search", 
    buttonColor: "red"
  }
{
    type: "TextBoxButton", 
    width: 100, 
    placeholder: "Search Package", 
    float: "left", 
    id: "TextBoxButton1"
    attributes: {
        maxlength: "50";
    } 
    button: true, 
    buttonText: "Search", 
    buttonColor: "red"
  }
﻿
Note
The default value of the button is false. Developers can change the value to true for adding a TextBoxButton and can provide buttonText and buttonColor, to specify the outlook of a button.
Here, “attributes” is an optional parameter that holds an object defining whether any attributes should be assigned to injectable controls.
OnChange is emitted when the developer changes the text in the input box and OnClick is emitted when the user clicks on the button.
SearchBox
Configuration for adding a "SearchBox" with a lens icon:
JS
{
          type: "SearchBox", 
          width: 100, 
          placeholder: "Search Package",
          float: "right", 
          id: "SearchBox1"
          attributes: { maxlength: "50"; } 
          lensIcon: true 
        }
{
          type: "SearchBox", 
          width: 100, 
          placeholder: "Search Package",
          float: "right", 
          id: "SearchBox1"
          attributes: { maxlength: "50"; } 
          lensIcon: true 
        }
﻿
Note
LensIcon is an optional attribute, if it is set to true then lensIcon will display itself in injectable control.
Here, “attributes” is an optional parameter that holds an object defining whether any attributes should be assigned to injectable controls.
OnChange, onBlur, and onFocus are the events that are emitted on the input box, developers can use these events as per their app requirements.
AutoComplete
Configuration for adding an "AutoComplete" control with dynamic options:
JS
{
  type: "AutoComplete", 
  width: 100, 
  placeholder: "Search Package", 
  float: "right",
  id: "AutoComplete1" 
  functionBoundOption: autoComplete(), // This field can be a function that returns an array of Objects or a normal array of objects in the form of [{ value: string, text: string }],
  }
{
  type: "AutoComplete", 
  width: 100, 
  placeholder: "Search Package", 
  float: "right",
  id: "AutoComplete1" 
  functionBoundOption: autoComplete(), // This field can be a function that returns an array of Objects or a normal array of objects in the form of [{ value: string, text: string }],
  }
﻿
Note
The functionBoundOption is passed when options are static and they can be passed in the form of [{ value: string, text: string }]. The developer can declare this as the value of this field or can pass the function that returns the value in the above-mentioned format.
For setting options dynamically, the developer can set the hasAsyncFunctionBoundOption. Then, call functionBoundAutoCompleteOption from @os1-platform/console-ui-react and pass an 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. The second parameter contains the ID of the 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. The second parameter contains the ID of the dropdown on which we want to load the values
}
﻿
OnChange, onBlur, OnClick, and onScroll are the events that are emitted on the input box. Developers can use these events as per their app requirements.
DropDown
Configuration for adding a "DropDown" control with options, including initial values.
JS
{
  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 the 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 that returns an array of Objects or a normal array of objects in the form of [{ value: string, text: string }],
  }
{
  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 the 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 that returns an array of Objects or a normal array of objects in the form of [{ value: string, text: string }],
  }
﻿
Note
The functionBoundOption is passed when options are static and can be passed in the form of [{ value: string, text: string }]. Developers can declare the string & text as the values of this field or can pass the function that returns the value in above mentioned format.
To establish dynamic options, developers can configure the hasAsyncFunctionBoundOption parameter. Post that, they can call the functionBoundOption from @os1-platform/console-ui-react, passing an array of objects and the dropdown's ID as parameters to the function.
To set the initial value of a dropdown, use OS1DropDownDefaultValue from @os1-platform/console-ui-react by providing the dropdown's value and ID. This can be passed only when an instance of Console UI is accessible or once Console UI has been loaded.
JS
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 need to be present in the dropdown. The second parameter contains the ID of the dropdown on which we want to load the values

OS1DropDownDefaultValue('initialValue', "DropDown1"); // Here first parameter contains the value that needs to be passed as initialValue, second Parameter is the id of the dropdown on which Id, needs to be set.
}
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 need to be present in the dropdown. The second parameter contains the ID of the dropdown on which we want to load the values

OS1DropDownDefaultValue('initialValue', "DropDown1"); // Here first parameter contains the value that needs to be passed as initialValue, second Parameter is the id of the dropdown on which Id, needs to be set.
}
﻿
OnChange, onScroll, OnClick, and onSearchEvent are the events that are emitted on the input box, developers can use these events as per their app requirements.
﻿