Website logo
Docs
API Reference
Postman Collection
Release Notes
Navigate through spaces
⌘K
Introduction
Overview
Getting started with the OS1 Platform
Getting started with building Apps
Concepts
Working with Callbacks
Console UI Overview
Custom Code
Working with GraphQL
Custom Attributes Ownership
Attribute-Based Access Control (ABAC)
Data Listing and Query (DLQS) Search
Core API dev guides
Overview
Authentication And Authorization
Participant
Container
Dispatch
Orchestrator
Workflow
Secure Data Storage
File Management
State Machine
Entity
Notification
Motion Tracking System
Location
Platform Order Management
Address
Scheduler
Logistics Framework API Dev guides
Overview
LogisticsOrder API
User API
Facility API
Vehicle API
How-To Guides
Integrate Your Application with Console UI
Integrate with Participants
Integrate with Containers
Integrate with Users
Integrate with Vehicles
Integrate with Facilities
Integrate with Entities
Integrate with Dispatch
Integrate with Logistics Order
Integrate with Platform Order Management
Integrate with Location Service
Integrate with Orchestrator
GraphQl Schemas
GraphQL: Dispatch Queries
GraphQL: Order Queries
GraphQL: Workflow Queries
GraphQL: Container Queries
Platform SDKs
SDK Overview
Sample Apps
Vehicle Management App
Container App
Resources
FAQs
Glossary
Data Types Used in OS1
Development Guidelines
Entity, Event, and Reason Codes
Service/API Level Error Codes
Docs powered by Archbee
How-To Guides
Integrate Your Application wit...

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.
>


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" 
>


📘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" />


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"
/>;


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))
}


📘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')
   }
 );
 }


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

  1. By default, all of these headers are set to true. To exclude them from the request, provide the value as false against these headers.
  2. The access token is verified and, if expired, regenerated each time an API request is initiated.
  3. The x-coreos-userinfo header includes the userId, and the x-coreos-auth header contains the id_token.
  4. 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);
         });
     };
};


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());
}


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();
    }


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";
            } 
        }


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"
  }


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 
        }


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 }],
  }


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
}

  • 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 }],
  }


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.
}

  • 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.



Updated 20 Nov 2023
Did this page help you?
PREVIOUS
How to: Integrate App with Console UI using React.JS
NEXT
Implementing Server Side Events (SSE)
Docs powered by Archbee
TABLE OF CONTENTS
Overview
Step 1: Installation
Step 2: Integration of the SDK
Step 3: Providing Controls
Step 4: Adding the Toast Component
Step 5: Adding the Modal Component
Step 6: Using a Variable
Step 7: Configuring Headers
Step 8: Generating Access Token
Configuration for Injectable Controls offered
How to configure different Injectable Controls in the Console UI
Textbox
TextBoxButton
SearchBox
AutoComplete
DropDown
Docs powered by Archbee