Narwhals Playing Mahjong

    @cumul.io/ngx-cumulio-dashboard
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.5 • Public • Published

    Angular Cumul.io Dashboards

    This is an Angular library for embedding Cumul.io dashboards in your Angular application.

    Table of contents

    1. Installation instructions
    2. Usage
    3. Examples
    4. Public methods
    5. Compatibility
    6. Migration from ngx-cumulio-1.X.X to ngx-cumulio-dashboard-2.X.X
    7. Quick links

    Installation instructions

    npm i @cumul.io/ngx-cumulio-dashboard --save

    OR

    ng add @cumul.io/ngx-cumulio-dashboard@latest #This also adds an entry in app.module.ts

    Usage

    In your app.module.ts import NgxCumulioDashboardModule as root

    import { NgxCumulioDashboardModule } from '@cumul.io/ngx-cumulio-dashboard';
    
    @NgModule({
        ...
      imports: [
        ...
        NgxCumulioDashboardModule
      ],
    })

    In your HTML template.

    <cumulio-dashboard
      [dashboardId]="dashboardId"
      [language]="'en'">
    </cumulio-dashboard>
    
    OR
    
    <!-- Embed a chart/item by passing the item id as well -->
    <cumulio-dashboard
      [dashboardId]="dashboardId"
      [itemId]="itemId"
      [language]="'en'">
    </cumulio-dashboard>

    Working with events

    <!-- Listening for events, logEvent is a function with console log -->
    <cumulio-dashboard [dashboardId]="dashboardId" [language]="'en'" 
      (load)="logEvent($event)"
      (customEvent)="logEvent($event)"
      (changedFilters)="logEvent($event)">
    </cumulio-dashboard>

    Available Inputs Below a list of available input options you can add to your ngx-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)").



    Examples

    A dashboard with a gray loader background

    <cumulio-dashboard
      #dashboardInstance
      [dashboardId]="'035c0304-0bfe-4b7c-8c10-a4acb8eb9d76'"
      [loaderBackground]="'rgb(238,243,246)'">
    </cumulio-dashboard>

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

    <cumulio-dashboard
      #dashboardInstance
      [dashboardId]="'55cfb99c-d602-492b-b192-6c15277fdb9a'"
      [loaderSpinnerColor]="'purple'"
      [screenMode]="'mobile'"
      [switchScreenModeOnResize]="false">
    </cumulio-dashboard>

    In Component, service can also be used to facilitate different functionality (Only refresh data is implemented here, other methods can also be implemented in similar fashion)

    import { NgxCumulioDashboardService } from '@cumul.io/ngx-cumulio-dashboard';
    ...
    
    @Component({
      ...
    })
    
    export class TestIntegrationComponent {
      @ViewChild('dashboardInstance') dashboardInstance: ElementRef;
      ...
      constructor() { }
    
      // To refresh data
      refresh() {
        this.dashboardInstance.refreshData().subscribe(); // Unsubscribe in ngOnDestroy
      }
      allFunctions() {
        this.dashboardInstance.getFilters().subscribe(console.log);
        this.dashboardInstance.getData('item-id').subscribe(console.log);
        this.dashboardInstance.reloadDashboard().subscribe(console.log);
        this.dashboardInstance.exportDashboard('png').subscribe(console.log);
        this.dashboardInstance.getAccessibleDashboards().subscribe(console.log);
      }
    }

    Public methods available on dashboardComponent instance

    getDashboards(): Observable<NgxCumulioDashboard[]>
    // Returns an instantly resolved promise with an array of all the visible dashboards on a page with their information.
    
    getData(itemId: string): Observable<ItemData>
    // Returns an array the data of a chart of a certain dashboard by adding the dashboardId or the container of the iframe.
    
    getFilters(): Observable<DashboardFilters>
    // Returns an array of active filters.
    
    setAuthorization(key: string, token: string): Observable<void>
    // Changes the authorization of all or one dashboard and refreshes the data of those dashboards
    
    refreshData(itemId?: string): Observable<void>
    // Refreshes the data of a specific chart when the id of that item is supplied. Without a itemId this refreshes the data in all items.
    
    reloadDashboard(): Observable<void>
    // Reload the dashboard. (useful when the authorization is changed, and dashboard needs to be reloaded without reloading the iFrame)
    
    exportDashboard(type?: ExportType): Observable<ExportDashboard>
    // Exports the current dashboard as either pdf or png. a container class needs to be passed as an argument and an optional type parameter.
    
    getAccessibleDashboards(): Observable<AccessibleDashboards>
    // Get accessible dashboards in a integration, make sure apiHost, authKey, authToken are set correctly on the instance.  
    
    setEditMode(editMode: DashboardEditMode): Observable<SetEditMode>
    // Sets the editMode of the current dashboard. Accepted parameters: view , editLimited , editFull .

    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

    Migration

    From ngx-cumulio-2.x.x to ngx-cumulio-3.x.x


    • getFilters() now returns an observable that continues emitting instead of emitting only once.

    From ngx-cumulio-2.0.x to ngx-cumulio-2.1.x


    - Renamed ILoadEvent -> LoadEvent, IItemsRenderedEvent -> ItemsRenderedEvent, ICustomEvent -> CustomEvent, IChangedFiltersEvent -> ChangedFiltersEvent

    From ngx-cumulio-1.x.x to ngx-cumulio-dashboard-2.x.x


    • All methods that were called on service e.g CumulioService.getFilters, CumulioService.getData ... shall now be called on component instance this.dashboardInstance.getFilters(), this.dashboardInstance.refreshData(). (see example above)
    • chart is now called itemId, chartsRendered is now called itemsRendered, chartDimensions is now called itemDimensions
    • 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;
      }
    }]

    Compatibility

    This library requires Angular version 9 and above.

    Angular
    9.x.x - 12.x.x

    For Angular version 8, please use the old library npm - ngx-cumulio Remark: that library is stable but not actively maintained anymore

    Quick links

    Cumul.io | Sample Integration | Codesandbox Example

    Install

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

    DownloadsWeekly Downloads

    727

    Version

    3.0.5

    License

    none

    Unpacked Size

    283 kB

    Total Files

    44

    Last publish

    Collaborators

    • cumul.io_team