How to include Dashboards in your Vue App? (Vue Wrapper Integration)

Introduction

With this way of integration, you will be able to include your dashboard through a native way in some VueJS application, then give this app Dashboard Engine capabilities, for example, the use of datasources outside of the dashboard for getting data in application, or the direct interaction with the API provided.

Technically, you will need a connection to the platform via websocket, which will be performed automatically with the component, following the parameters you indicate. You will also need a user with at least developer role, who has permissions on it.

Integration types

Integration in front Vue app via JS

You can obtain the vue component from the platform GitHub repository here: https://github.com/onesaitplatform/onesait-cloud-platform-dashboard-wrapper. Specifically, this is the main file that you will include in your project resources: https://github.com/onesaitplatform/onesait-cloud-platform-dashboard-wrapper/blob/main/js/vue-wrapper-component.js . A complete example with many features and functionalities can be found in the same repository, in the sample folder.

In this example, you will have to point the URLs to a platform installation (2.1.3 or more) where you will retrieve the necessary resources for the engine, as well as modify the platformbase, token and dashboard configurations to an existing one. For more information you can check the readme file of the example project: https://github.com/onesaitplatform/onesait-cloud-platform-dashboard-wrapper/blob/main/js/README.md

Integration via Vue Component:

In the case having a Vue application generated with its client, you can include the Vue component as a .vue file: https://github.com/onesaitplatform/onesait-cloud-platform-dashboard-wrapper/blob/main/vue/src/components/VueWrapperComponent.vue . In this case, this component automatically loads the needed platform libraries and adds them to the header, so you only need to include the component and use it with the necessary parameters.

Open

There is also an application example with this component in the GitHub repository.

Initial considerations

In this integration via wrapper component, you need to give an initial css style to the engine container. Specifically, you will have to include:

• height → fixed in pixels, for example: 700px

• width → may be fixed or percentage: 80%

• position → “absolute” always

Open

Another main consideration is that, since there is not a back-end template engine, you need to provide the headerlibs (or initial header fragment that we can include in the dashboards) from the main Vue application. For example, if you use a custom graphics library, you will have to load it yourself before loading the dashboard.

If you need to know the loading of the dashboard or of a specific gadget, that is to say, where the dashboard or gadget have finished their render, you have two events, one for the individual loading of each gadget and another for the complete loading (all gadgets must have been rendered correctly).

Wrapper parameters

In the wrapper, you have several parameters, some of which are required to render the component, while others are optional:

• id (required) → identifier of the dashboard instance. This parameter will identify your dashboard container. It will be useful in cases where you have several dashboards at the same time and you want to access each one with the identifier. Any identifying string value will be valid, for example “inst1“.

• token (required) → will be the OAuth bearer token generated after a user login. This token will be included without the starting “bearer” part. Through this token, the user's permissions are checked.

• dashboard (required) → id of the dashboard you want to load. It corresponds to the final part of the URL of any dashboard or integration URL. This parameter is reactive, so if you change it, the component will render the new dashboard instantly,allowing you to switch from one to the other quickly.

• platformbase (required) → base URL of the platform installation where the dashboard are. The onesaitplatform version must be 2.1.3 or higher. For example “https://gradius.onesaitplatform.com”

• editmode → defaults to false. If you change it to true, you will access the dashboard in edit mode.

• model → if you want to load the dashboard model without having to go to the platform to look for it, you can include it in its entirety in this parameter.

• i18n → false by default, and then it will not load i18n in the dashboard. If changed to true, the component will go to the platform to look for the internationalization settings of the dashboard. If it is passed an internationalization JSON, it works like the previous parameter

• api → output object that will be overwritten with the specific dashboard’s API.

• params → parameter to include the URL parameters in a JSON. In this case, the format will be a JSON whose key is the parameter to include and the value that you want to use. This parameter is reactive, so if you change it, the dashboard will be reloaded, just like if you use the gadget's unique display parameter “$gadgetid“.

• parámetro para incluir los URL parameters. En este caso el formato será un JSON con clave el parámetro a incluir y el valor que queramos usar. Este parámetros es reactivo, por lo que si cambiamos el mismo el dashboard se recargará. Así como si usamos el parámetro de visualización única del gadget “$gadgetid“.

• parameter to incluse a json of url parameters. In this case the format will be json with the key of the parameter and the value that we want to use. This param it’s reactive so if we change the param the dashboard will be reloaded with the new parameter. We can use like in url parameter the $gadgetid param in order to render a single gadget of the dashboard.

Wrapper API

Every dashboard wrapper, generate an API where you can interact with some capacilities like datalink, reading datasources and many more in VueJS app, even in local enviroment because there is no conflict for developing in this way. With this API you can create a custom, powerful UI for the dashboard for viewing or editing it.

This API is accessible both from the "api" parameter of the component and from the window object. In this window object, there will be an API for each dashboard loaded, the key of each being the id given in the component.

With this API, you will be able to do different operations that you can see in its definition:

• api.sendValue (gadgetOrigin, key, value) → works exactly like the sendValue of the template gadget. It will be necessary to indicate the id of the origin gadget, since it works with datalink relationships (gadget to gadget). The gadget id can be obtained from the "Styling" option of that gadget:

• api.sendFilter (gadgetOrigin, key, value, op, typeAction) → works like the gadget's sendFilter. You must indicate the id of the origin gadget, its field, value, and operator (“=“,”>”,”<”, …) which by default if “=“ is not passed, and the action, which if it is not passed will be filter with normal operation.

• api.ds → subapi with multidatasource api chaining operations. With this api you can retrieve data from datasource in any part of the Vue application

• subapi with multidatasource api chaining. With this API we’re going to trigger datasources in the main VueJS app for example for filling select or tables outside of the dashboard Multidatasources-datadiscovery queries in Gadget Template

• api.setModel(dashboard)/getModel → with these operations, you will be able to write or retrieve (set or get) the dashboard model.

• api.getDropElementEvent/setDropElementEvent → you can retrieve or override the behavior of the drop element in the dashboard (when using drag and drop in the wrapper).

• api.enableEventEdit/disableEventEdit → you can enable and disable event editing. If it is activated, every time you click the gadget's "edit" button, a gadgetselect event will be sent, in which the gadgetselect’s JSON will be included, for external editing tasks, for example.

• api.datalink/api.params → access to the datalink and parameter service. Within these, it is possible to generate new datalink connections or parameters.

• api.sendParam/api.sendParams → single or multiple sending of parameters to the dashboard. You can send parameters without having to reload the dashboard.

• api.gmanagerService → gadgetmanager service with which you can perform query operations on dashboard gadgets.

• api.setInlineDragType(type) → set the type of the gadget that you want to use in the inline drag (directly drag the cursor in an unoccupied area). This parameter depends on having “gridOptions.enableEmptyCellDrag” enabled: if it is not enabled, a gadget cannot be added using this method.

• api.forceRender → when we have made any changes to the dashboard we can call it to refresh the changes and force the render of the dashboard.

• force render of the dashboard, for use it when we change model or structure things.

• api.favoriteService → (From version 3.0) Allows access to favorite gadget services, in order to create, modify, delete or query them.