README
Angular Cumul.io Dashboards
This is an Angular library for embedding Cumul.io dashboards in your Angular application.
Table of contents
- Installation instructions
- Usage
- Examples
- Public methods
- Compatibility
- Migration from ngx-cumulio-1.X.X to ngx-cumulio-dashboard-2.X.X
- 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 |
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 screenmode 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/') |
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/') |
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 on 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
getData(itemId: string): Observable<object[]>
// Returns an array the data of a chart of a certain dashboard by adding the dashboardId or the container of the iframe.
getFilters(): Observable<object[]>
// Returns an array of all visible dashboards with their active filters
setAuthorization(key: string, token: string): Observable<null>
// Changes the authorization of all or one dashboard and refreshes the data of those dashboards
refreshData(itemId?: string): Observable<null>
// 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<null>
// Reload the dashboard. (useful when the authorization is changed, and dashboard needs to be reloaded without reloading the iFrame)
exportDashboard(type?: string): Observable<null>
// 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<object[]>
// Get accessible dashboards in a integration, make sure apiHost, authKey, authToken are set correctly on the instance.
setEditMode(editMode: string): Observable<null>
// Sets the editMode of the current dashboard. Accepted parameters: view , editLimited , editFull .
Events
Name | Description | Event Arguments |
---|---|---|
load | Emitted when dashboard is loaded | ILoadEvent |
itemsRendered | Emitted when items are rendered | IItemsRenderedEvent |
customEvent | Emitted when a custom event is fired | ICustomEvent |
changedFilters | Emitted when filters are changed | IChangedFiltersEvent |
Migration
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 instancethis.dashboardInstance.getFilters()
,this.dashboardInstance.refreshData()
. (see example above) chart
is now calleditemId
,chartsRendered
is now calleditemsRendered
,chartDimensions
is now calleditemDimensions
- 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