Generic Dashboard/Widgets functionality with AngularJS (directive)
Generic Dashboard/Widgets functionality with AngularJS (directive)
Generic AngularJS component/directive providing dashboard/widgets functionality.
Adding/removing widgets
Widgets are instantiated dynamically (from corresponding directive or template)
Widgets drag and drop (with jQuery UI Sortable)
Horizontal and vertical widgets resize
Fluid layout (widgets can have percentage-based width, or have width set in any other unit)
Any directive or template can be a widget
Connecting widgets to real-time data (WebSocket, REST, etc.)
Changing widget data source dynamically (from widget options)
Saving widgets state to local storage
Multiple Dashboard Layouts
This project welcomes new contributors.
You acknowledge that your submissions to DataTorrent on this repository are made pursuant the terms of the Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0.html) and constitute "Contributions," as defined therein, and you represent and warrant that you have the right and authority to do so.
When adding new javascript files, please prepend the Apache v2.0 license header, which can be found in CONTRIBUTING.md file.
Simple demo (minimum dependencies) [source code]
Advanced demo (charts, visualization, data sources, etc.) [source code]
UI Console (very complex application; REST, WebSocket and Socket.IO data sources; dashboard customization; etc.) [source code]
Widget Library using the dashboard [source code]
Project is built with Gulp.
$ npm install -g gulp
$ gulpExample of including dependencies from CDN here
See demo (several widgets) for a quick start.
Running demo.
$ bower install
$ gulp build:demo
$ gulp serveApplication will be available at http://localhost:3000/
With bower:
bower install malhar-angular-dashboardFor legacy reasons, this bower module is also registered as angular-ui-dashboard.
Manually:
Download the zip of this repo and use the files in the dist folder.
Load dist/malhar-angular-dashboard.js and dist/malhar-angular-dashboard.css in your html:
Also be sure to add it to your apps dependency list:
angular.module('yourApp', [
// other dependencies
'ui.dashboard'
]);Widgets inherit controller scope (so normally different widgets will have bindings to different controller scope properties).
DataModel has direct access to widget scope, each widget has separate instance of DataModel.
Include the dashboard directive on the element you wish to place widgets in:
It is possible to use your own template for the dashboard and widget markup (replacing dashboard/dashboard.html). To do so, include a template-url attribute on the element to become dashboard:
dashboardOptions in the above html is required and should be an object available on the current scope. The options on said object are as follows:
| key | type | default value | required | description |
|---|---|---|---|---|
| widgetDefinitions | Array | n/a | yes | List of Widget Definition Objects. See below for available options on those. |
| defaultWidgets | Array | n/a | yes | List of objects where an object is { name: [NAME_OF_WIDGET_DEFINITION] }. TODO: Allow just list of names. |
| widgetButtons | Boolean | true | no | Display buttons for adding and removing widgets. |
| storage | Object | null | no | If defined, this object should implement three methods: setItem, getItem, and removeItem. See the Persistence section below. |
| storageId | String | null | no (yes if storage is defined) |
This is used as the first parameter passed to the three storage methods above. See the Persistence section below. |
| storageHash | String | '' | no | This is used to validate/invalidate loaded state. See the Persistence section below. |
| stringifyStorage | Boolean | true | no | If set to true, the dashboard state will be converted to a JSON string before being passed to storage.setItem. Likewise, it will be passed through JSON.parse after being retrieved from storage.getItem. See the Persistence section below. |
| explicitSave | Boolean | false | no | The dashboard will not automatically save to storage for every change. Saves must instead be called explicitly using the saveDashboard method that is attached to the option event upon initialization. |
| sortableOptions | Object | n/a | no | Allows to specify the various sortable options of the underlying jQuery UI Sortable. |
| hideWidgetSettings | Boolean | false | no | If true, the cog button in the top right corner of each widget will not be present. |
| hideWidgetClose | Boolean | false | no | If true, the "x" button in the top right corner of each widget will not be present. |
| settingsModalOptions | Object | see below | no | The options object to be passed to the $uibModal service for widget settings. See the Custom Widget Settings section below. |
| onSettingsClose | Function | see below | no | The success callback for when a widget settings dialog is closed by the user. See the Custom Widget Settings section below. |
| onSettingsDismiss | Function | see below | no | The error callback for when a widget settings dialog is dismissed by the user. See the Custom Widget Settings section below. |
Upon instantiation, this options object is endowed with a few API methods for use by outside code: addWidget, loadWidgets, saveDashboard and loadDashboard.
You can think of Widget Definition Objects as a class and the widgets on the page as instances of those classes. The options for a Widget Definition Object are:
| key | type | default value | required | description |
|---|---|---|---|---|
| name | String | n/a | true | Name of Widget Definition Object. If no templateUrl, template, or directive are on the Widget Definition Object, this is assumed to be a directive name. In other words, the directive attribute is set to this value. |
| title | String | n/a | false | Default title of widget instances |
| attrs | Object | n/a | false | Map of attributes to add to the markup of the widget. Changes to these will be stored when using the storage option |
| templateUrl | String | n/a | false | URL of template to use for widget content |
| template | String | n/a | false | String template (ignored if templateUrl is present) |
| directive | String | n/a | false | HTML-injectable directive name (eg. "ng-show") |
| dataModelType | Function or String | n/a | false | Constructor for the dataModel object, which provides data to the widget (see below for more information). |
| dataModelOptions | Object | n/a | false | Arbitrary values to supply to the dataModel. Available on dataModel instance as this.dataModelOptions. Serializable values in this object will also be saved if storage is being used (see the Persistence section below). |
| dataModelArgs | Object | n/a | false | Object to be passed to data model constructor function. This object is not serialized by default and if defined should be present in widget definitions. |
| dataAttrName | String | n/a | false | Name of attribute to bind widgetData model |
| storageHash | String | n/a | false | This is analogous to the storageHash option on the dashboard, except at a widget-level instead of a dashboard-wide level. This can be helpful if you would only like to invalidate stored state of one widget at a time instead of all widgets. |
| settingsModalOptions | Object | see below | no | Overrides same-named option in dashboard options for this widget. See the Custom Widget Settings section below. |
| size | Object | n/a | false | Widget size, e.g { width: '50%', minWidth: '27%', height: '250px' } |
| style | Object | n/a | false | Widget style, e.g { float: 'right' } |
| enableVerticalResize | Boolean | true | false | Option to enable/disable vertical resize. Should be provided in "widgetDefinitions" since it is not serialized by default. |
| onSettingsClose | Function | see below | no | Overrides same-named option in dashboard options for this widget. See the Custom Widget Settings section below. |
| onSettingsDismiss | Function | see below | no | Overrides same-named option in dashboard options for this widget. See the Custom Widget Settings section below. |
| serialize | Function | see below | no | Define this to override how this widget gets saved to storage. See persistence section below. |
As of v1.0.0, you can also add arbitrary data to your WDOs and this data will be copied to your widget. Keep in mind though, that if you want to SAVE some of this arbitrary info with storage, you will need to implement your own serialize method that includes this (see the persistence section below).
Widgets width and height is controlled with size attribute (serialized by default). Width can be both unit and percentage based.
Example
{
name: 'fluid',
directive: 'wt-fluid',
size: {
width: '50%',
minWidth: '27%',
height: '250px'
}
}Widgets can be resized both horizontally and vertically and size is serialized.
When widget is resized 'widgetResized' event is broadcasted to the widget scope.
The best way to provide data to a widget is to specify a dataModelType in the Widget Definition Object (above). This function is used as a constructor whenever a new widget is instantiated on the page.
If dataModelType is a string it will be looked up with $injector (it should be valid AngularJS provider/factory/service).
In most cases data model should implement the following methods: init, and destroy.
Please see widget directive file for implementation details.
setupThis function is called once when a widget is instantiated. It takes two arguments: (1) the instance of the WidgetModel constructor that corresponds to the widget instance, and (2) the scope of the widget.
initThis function is called once when a widget is instantiated. This function does not take any arguments.
destroyThis function is called when the widget is removed from the dashboard. It does not take any arguments. It should be used to clean up any listeners that may otherwise hang around, e.g. unsubscribing to a WebSocket topic or RESTful endpoint.
It is recommended to prototypically extend from the WidgetDataModel constructor, which implements t
No open issues yet, or sync has not completed.