@os1-platform/console-ui-vue

Installation and Usage

How to use?

1. Install console-ui-vue into your project.

   npm install @os1-platform/console-ui-vue

2. Use OS1Provider component of the library is to use aunthentication and render header and sidebar. Pass this as a component to your application that sets the console Ui Instance.

   • Create a function that is passed as prop to this component, that listens to an event of console UI and that event is assigned to a ref and that ref is being used in 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 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, need only to be passed when using in development mode.
     appId='SolutionName-appId' //initial appId on which you want to land when loading console ui for the first time. This is mandatory prop.
     @consoleInstance = "getConsoleInit" //here function gets value of event that is passed from console ui and assigns its value to variable so that it can be used in client's application.
   >

3. We can also provide injectable controls to our header and sidebar by binding them to OS1Provider.

   import { OS1Provider } from "@os1-platform/console-ui-vue";
   
    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 distinguish 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' 
     appId='SolutionName-appId'
     :controls = "controls"
     @consoleInstance = "getConsoleInit" 
   >

   NOTE: There can not be more than 3 injectable controls and each injectable control should be given a unique id.

4. Use the Toast function to render toast component in your webpage. For example:

   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 elementId="toastElement" :toastConfig="toastConfig" />

   NOTE: Each toast element that is to be rendered on the page should be given a unique elementId.

5. Use the Modal function to render a modal component in your webpage. For example:

   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
     elementId="modalElement"
     :modalConfig="modalConfig"
   />;

   Note:- Listen to event when button is clicked, event.details will contain the modal element Id.

6. Use variable that contains value of event that is emmited by console ui to be used in existing to listen to events emitted by injectable controls. This instance is binded with existing app to be used in it. For example:

   const { consoleInstance } = props;
   if (consoleInstance) {
     consoleInstance.eventBus().on(props.consoleInstance.events().OnChangeEvent, e => window.console.log(e))
   }

   Note:- We are exposing OnChangeEvent, OnBlurEvent, OnScrollEvent, OnClickEvent, OnFocusEvent, OnSearchEvent for injectableId's.

7. Use OS1HttpClient API to create a client variable or state for network requests and pass authInitializer property of ConsoleUiContext as a constructor parameter.

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

8. Use REST api methods, on the instance created for OS1HttpClient. Following headers are automatically configured to requests originating from the NetworkClient adding Access token(x-coreos-access) or Tenant id(x-coreos-tid) or User info(x-coreos-userinfo) or Auth token(x-coreos-auth) headers to the actual request.

• withAccess
• withTid
• withUserInfo
• withAuth

Note:

1. By default all these headers are true, pass value against these headers as false to remove from request.
2. Access token is verified and regenerated (if expired), every time an api request is made.
3. x-coreos-userinfo contains the userId.
4. x-coreos-auth contains the id_token.
5. If you want to use X-Coreos-Request-Id, that is generated by library and also need to send request headers, then send requestId parameter as undefined.

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 case when requestId is generated from 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);
         });
     };
};

9. Click on Need Help button in case you want to query about any application or want to use product guide.

   • Click on Raise a Ticket button and Use Contact Us page, if you want to query about any application.
     • We provide text area to describe the issue in details.
     • We provide option to upload screenshots if any, that may help to understand the issue.
     • We will get the query along with your details and we can contact you.`
   • Click on Product Guide button to learn about the product.

10. Option to change the timezone of the application. At initital load, time zone will be tenant specific but user can change the time zone according to his choice and it will be stored in his browser's local Storage.

11. Exposed convertTime function that converts time of the user's application in their desired format and currentTimeZone function that gives user current timezone that is stored in the browser. When TimeZone is updated it emits UpdateTimeZoneEvent event.

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

12. We have provided that defines how user navigates on Routing of tabs. Users can choose, how they want to navigate apps i.e. they want to open the app on new tab or the current tab. This is done by going into user preference in profile dropdown and select the choice in Set App Redirect Behaviour. For the first time, it will ask how, we want to redirect our apps.

13. When user clicks on subroutes, then event naming changeRoutes is emitted, which contains the details of subMenu apps and their parent app details like appId, appUrl and appName.

14. If nothing is selected then, when user clicks on app for the first time, it asks how we want to redirect the app.

15. To get Access Token, use getAuthenticationTokens method, for userInfo, use getUser, and check whether user is authenticated use isAuthenticated(). User have to use context of consoleUi and call authInitializer method of it. getTenantConfigurations method, to get all the organization based tenant data

    if (props.consoleInstance) {
        const accessToken = await consoleInstance.authInitializer.getAuthenticationTokens();
        const userInfo = await consoleInstance.authInitializer.getUser();
        const isUserAuthenticated = await consoleInstance.authInitializer.isAuthenticated();
        const tenantInfo = await consoleInstance.authInitializer.getTenantConfigurations();
    }

Configuration for Injectable Controls offered by the Library

Common parameters, that will be passed in all injectable controls:-

• type:- This field shows the type of injectable controls that is being used. Available types are TextBox, TextBoxButton, AutoComplete, DropDown, SearchBox
• width:- This field shows the maximum percentage of width that can be passed.
• placeholder:- This field displays the placeholder text, that is passed in injectable control.
• id:- This is unique id that is given to injectable controls that uniquely identifies that particular component.
• float:- This is optional component, by default every component is left floated.

TextBox:-

• To use textbox in console ui, we provide following configuration:-

        {
            type: "TextBox", 
            width: 100, 
            placeholder: "Search Package",
            float: "left", 
            id: "TextBox1" 
            attributes: {
                maxlength: “50”;
            } 
        }

• Note:-
  • Here, attributes is an optional attributes parameter that contains object which defines if any attribute needs to be set to injectable controls.
  • OnChange and OnBlur event is emitted by this injectable control.

TextBoxButton:-

• To use textbox with button in console ui, we provide following configuration:-

  {
    type: "TextBoxButton", 
    width: 100, 
    placeholder: "Search Package", 
    float: "left", 
    id: "TextBoxButton1"
    attributes: {
        maxlength: “50”;
    } 
    button: true, 
    buttonText: “Search”, 
    buttonColor: “red”
  }

• Note:-
  • Here button by default set to false, but if we set it to true, then we have to pass buttonText and buttonColor, which specifies the outlook of a button
  • Here, attributes is an optional attributes parameter that contains object which defines if any attribute needs to be set to injectable controls.
  • OnChange is emitted when we change text in input box and OnClick is emitted when user clicks on button.

Search Box:-

• To use SearchBox with Lens Icon in console ui, we provide following configuration:-

      {
          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 object which defines if any attribute needs to be set to injectable controls.
  • OnChange, onBlur, onFocus is emitted on input box.

AutoComplete:-

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

DropDown:-

• To use DropDown in console ui , we provide following configuration:-

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

• 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 functionBoundOption from @os1-platform/console-ui-react and pass 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 instance of console UI is available or console UI has 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.
  }

  • OnChange, onScroll, OnClick, OnSearch is emitted on this injectable controls

FAQ

• Which option should I select from the popup that shows when I open an app for the first time?

  • The user should choose the solution that the app belongs to when there are multiple options. The user will be redirected to selected(current) solution's first app(as per display order), if the browser's URL differs from the one current selected solution.

• Why header and sidebar is not visible?

  • This occurs when developer has not provided appId in his code, as it is mandatory.

• Why in sidebar apps are not visible?

  • Verify the subscription via the console api response. If the api displays a status of 200, examine the response. The app won't be accessible if its display order is equal to or less than 0.