Novice Prime Minister

    @cumul.io/vue-cumulio-dashboard

    2.0.9 • Public • Published

    Vue.js Cumul.io Dashboards

    This is a Vue.js library for embedding Cumul.io dashboards in your Vue 2 or Vue 3 application.

    Install

    npm i @cumul.io/vue-cumulio-dashboard

    Usage

    Vue 3

    import { createApp } from 'vue';
    import App from './App.vue';
    import VueCumulioDashboard from '@cumul.io/vue-cumulio-dashboard';
    
    const app = createApp(App);
    // Defines the component at app level
    app.use(VueCumulioDashboard);
    app.mount('#app');

    Vue 2

    import Vue from 'vue';
    import App from './App.vue';
    import VueCumulioDashboard from '@cumul.io/vue-cumulio-dashboard/vue2';
    
    Vue.use(VueCumulioDashboard);
    
    new Vue({
      render: (h) => h(App),
    }).$mount('#app');

    In your HTML template.

    <cumulio-dashboard
      ref="dashboardInstance"
      :dashboardId="dashboardId"
      :language="'en'">
    </cumulio-dashboard>
    
    OR
    
    <!-- Embed a Item by passing the item id as well -->
    <cumulio-dashboard
      ref="dashboardInstance"
      :dashboardId="dashboardId"
      :itemId="itemId"
      :language="'en'">
    </cumulio-dashboard>

    Available props
    Below a list of available props you can add to your cumulio-dashboard

    Property Type Description
    dashboardId string The id of the Cumul.io dashboard you wish to embed
    dashboardSlug string The slug of the Cumul.io dashboard you wish to embed (if a dashboardId is supplied that one will be used)
    itemId string The id of the Cumul.io item you wish to embed
    itemDimensions { width: number/string; height: number/string; } width and height of item only applies when itemId is provided.
    authKey string Authorization key generated via Cumul.io API
    authToken string Authorization token generated via Cumul.io API
    language string The language of the dashboard: eg. 'en' (Default: 'auto')
    screenMode string The screen mode of your dashboard: 'mobile', 'tablet', 'desktop', 'largeScreen', 'fixed' or 'auto' (Default: 'auto')
    switchScreenModeOnResize boolean true: the embedded dashboard can switch screenModes on resize of the container , false: Dashboard will keep the same screenMode (Default: true)
    loaderBackground string Background color of the loader element (Default: '#f9f9f9')
    loaderFontColor string Font color of the text of the loaders (Default: '#5a5a5a')
    loaderSpinnerColor string Spinner color of the loader (Default: 'rgba(255, 165, 0, 0.7)')
    loaderSpinnerBackground string Background color of the spinner (Default: 'rgba(169, 169, 169, 0.14)')
    appServer string Tenancy of cumul.io to connect to (Default: 'https://app.cumul.io/' for US set appServer to 'https://app.us.cumul.io/')
    timezoneId string The timezone you you wish to use in your dashboard. This timezone id needs to be a valid id that is available in the IANA timezone database, for example: Europe/Brussels or America/New_York.
    apiHost string API server to connect to (Default: 'https://api.cumul.io/' for US set apiHost to 'https://api.us.cumul.io/')
    editMode string Specifies if the embedded dashboard should be editable or not. Accepted values: "view" , "editLimited" , "editFull" . Use "view" if you don't want the embedded dashboard to be editable. (Default: "view" )
    mainColor string Optional override of the main color used in the whitelabeling of the embedded dashboard editor. If not provided, the main color of the whitelabeling colors set on the organization will be used. Should be specified as a string of rgb values (i.e. "rgb(50,50,50)").
    accentColor string Optional override of the accent color used in the whitelabeling of the embedded dashboard editor. If not provided, the accent color of the whitelabeling colors set on the organization will be used. Should be specified as a string of rgb values (i.e. "rgb(50,50,50)").



    Events

    Name Description Event Arguments
    @changedFilters Emitted when filters are changed ChangedFiltersEvent
    @customEvent Emitted when a custom event is fired CustomEvent
    @exported Emitted when export completes or fails ExportedEvent
    @itemsRendered Emitted when all items are rendered ItemsRenderedEvent
    @load Emitted when dashboard is loaded LoadEvent

    Examples

    A dashboard with a gray loader background

    <cumulio-dashboard
      ref="dashboardInstance"
      :dashboardId="dashboardId"
      :loaderBackground="'rgb(238,243,246)'">
    </cumulio-dashboard>

    A dashboard with a purple loader spinner color, screenMode mobile and switchScreenModeOnResize on false, so that the dashboard will stay in mobile mode

    <cumulio-dashboard
      ref="dashboardInstance"
      :dashboardId="dashboardId"
      :loaderSpinnerColor="'purple'"
      :screenMode="'mobile'"
      @load="logEvent"
      :switchScreenModeOnResize="false">
    </cumulio-dashboard>

    Public methods from CumulioComponent

    In Component

    ...
    
    export default {
      name: 'Example',
    
      methods: {
        // To refresh data from item / dashboard
        refreshData(itemId){
          this.$refs.dashboardInstance.refreshData(itemId);
        },
    
        // Get data from a item
        async getData(){
          const result = await this.$refs.dashboardInstance.getData('6759f444-32b8-42d8-8786-eb88fc2a194');
          console.log(result)
        },
    
      }
    
      ...
    
    }
    getDashboards(): Promise<any[]>
    // Returns an instantly resolved promise with an array of all the visible dashboards on a page with their information.
    
    getFilters(): Promise<any[]>
    // Returns an instantly resolved promise with an array of all visible dashboards with their active filters.
    
    getData(itemId: string ): Promise<any[]>
    // Returns a promise with the data of a item.
    
    setAuthorization(key: string, token: string): Promise<void>
    // Changes the authorization of all or one dashboard. Returns an empty promise.
    
    refreshData(id?: string): Promise<void>
    // Refreshes the data of a specific item when the id of that item is supplied. Without a itemId this refreshes the data in all items. Returns an empty promise.
    
    reloadDashboard(): Promise<void>
    // Reload the dashboard. (useful when the authorization is changed, and dashboard needs to be reloaded without reloading the iFrame). Returns an empty promise.
    
    exportDashboard(type?: string): Promise<Object>
    // Exports the current dashboard as either pdf or png. a container class needs to be passed as an argument and an optional type parameter. Returns a promise with information on the export.
    
    getAccessibleDashboards(): Promise<Object[]>
    // Get accessible dashboards in a integration, provide either dashboardId, dashboardSlug, container if a dashboard is already loaded.
    // Or provide authKey, apiHost and authToken
    
    setEditMode(editMode: string): Promise<void>
    // Sets the editMode of the current dashboard. Accepted parameters: view , editLimited , editFull .

    Quick links

    Cumul.io |

    Vue3 CodeSandbox Example

    Breaking Changes

    Migrating from version 1.X.X -> 2.X.X

    The way vue-cumulio-dashboard is imported for vue2 has changed. You can now import it in the following way.

    import VueCumulioDashboard from '@cumul.io/vue-cumulio-dashboard/vue2';

    Import for vue3 remains unchanged.

    import VueCumulioDashboard from '@cumul.io/vue-cumulio-dashboard';

    Migrating from version 0.X.X -> 1.X.X

    • All methods that were called on service e.g CumulioService.getFilters, CumulioService.getData ... shall now be called on component instance (Which can be obtained using $refs).
    • chartId is now called itemId, charts-rendered is now called items-rendered
    • All events are now of the format { data: { ...eventData } }, eventData is of the format
    {
      dashboardId?: string;
      dashboardSlug?: string;
      itemId?: string;
      language: string;
      name: string;
      screenMode: string;
      type: string;
      dimensions?: object; // populated depending on the event
      changed?: [];  // populated depending on the event
      filters?: [];  // populated depending on the event
      item?: string;    // populated depending on the event
      origin?: string;  // populated depending on the event
      object?: string;  // populated depending on the event
      data?: object;       // populated depending on the event
    }
    • getFilters now returns an array of filters. [...objectOfFilters], objectOfFilters is of the format
    [{
      expression: string;
      parameters: [];
      properties: {
        id: string;
        ignore?: string[];
        origin: string;
        type: string;
        viz: string;
      }
    }]

    Install

    npm i @cumul.io/vue-cumulio-dashboard

    DownloadsWeekly Downloads

    154

    Version

    2.0.9

    License

    none

    Unpacked Size

    302 kB

    Total Files

    8

    Last publish

    Collaborators

    • cumul.io_team