MashZone NEXTGEN ships with a variety of visual components out of the box including different chart types, speedometers, image and text widgets. Additionally it provides an API to creation custom visualizations. These "custom widgets" are integrated in MashZone NEXTGEN and behave like native widgets. They consume the same data sources and support all the main functionality of native widgets, for example selection handling, emitting and receiving filter events or the configuration of actions.
This guide describes the usage of the custom widget framework and explains the implementation of custom visualizations for MashZone NEXTGEN. The user is guided through the creation of different example widgets.
All necessary and optional custom widget functionalities and building blocks will be explained, step by step and illustrated by meaningful code snippets. Each chapter will focus on one specific widget building block. Reading the documentation and trying out the example widgets will qualify the reader to understand and create simple and complex custom widgets on their own.
The base technologies
Some basics will be explained in the chapters directly. But for a good understanding of the base technologies the following websites are highly recommended:
The development environment
There is no need to set up a specific development environment. A text editor is all that is need to create and access the custom widget files right in the custom widget root folder.
To get started please have a look at the Q&A sections: Where are custom widgets located? and How are custom widgets be activated?
During development, it might be necessary to debug a custom widget. The "Chrome Developer Tools" are free to use and provide a very good toolset to debug and profile web-based applications.
Questions and Answers
Custom visualizations are located in the custom widgets root folder:
Each custom widget has an own folder under the custom widgets root folder:
Each custom widget located in the custom widgets root folder will be automatically registered and activated on server start.
Active custom widgets are registered in the file customWidgetsModule.js located in the custom widgets root folder.
Explanation: This file will be created on server start and registers the module names of all custom widgets found in the custom widgets root folder.
Hint: If a custom widget is not showing up in the widget selection control of the dashboard, have a look into this file and make sure that it was registered correctly.
How to create a custom widget menu icon?
Create an 32 x 32px image file in png format.
Name the file <widgetName>MenuIcon_32x32.png.
It is recommended to locate image files under: customWidgets/<widgetName>/assets/images.
How to style a custom widget?
There are two ways to style a custom widgets, via CSS or using LESS.
It is recommended to locate style files under: customWidgets/<widgetName>/assets/css.
Any file with the extension .css will be automatically added to the main HTML file and can be used after an initial server restart.
Styling of custom widgets via CSS
Open a new file and save it as <widgetName>Styles.css. Enter the following code:
Explanation: Each widget can be accessed using the CSS class .panel-dashboard-default and the attribute widget-type=<widget name>. The widget name is defined in the custom widget configuration file.
Hint: Do not style elements like body, div, h3, etc. directly. This will change the look and feel of the main application and might cause visualization problems.
Styling of custom widgets using LESS
It is also possible to use LESS to style custom widgets. This has the advantage that internal variables like defaultFontFamily or defaultTextColor that define the look and feel of the whole dashboard can be used.
Create a new file and save it as widget_<widgetName>.less. Enter the following code:
Explanation: Line #3 defines the background color for the custom widget. It uses the LESS utility function "lighten" and references a variable called @brand-primary which is defined in the file default.less.
Hint: Available variables can be found and added in the file default.less under <installDir>/apache-tomee-jaxrs/webapps/presto/hub/dashboard/assets/custom-look-and-feel/dashboard
Hint 2: In order to access variables that are used on application level (e.g. styling of the "Assign Data" dialog) create a file with name application_<widgetName>.less. All variables defined in application.less under <installDir>/apache-tomee-jaxrs/webapps/presto/hub/dashboard/assets/custom-look-and-feel/application can be used.
Compiling LESS into CSS
After a new LESS file has been created, the server needs to be restarted. In order to compile LESS into CSS simply open Freeform, click on Manage > Change Style Template and select the template you like to compile (default.less). Click on "Update..." and your changes will be immediately reflected in the UI.
What is a Module?
MashZone NG is based on AngularJS. Each AngularJS app has to have a module to specify the parts of the application and how they work together. This is also true for the Custom Widget Framework. Each custom widget should add its AngularJS components like controllers, services, filters, directives, etc. to its module.
A Custom Widget module has the following naming convention: <widgetName>Module.js and contains at least the following line of code:
How to configure a custom widget?
Each custom widget has a configuration file that contains it's configurable properties.
|title||The title of the widget. Shown e.g. in the widget properties popup and if not overwritten, also in the widget container header.|
|category||Determines where a widget is aligned in the widget selection control (the menu on the left side). Widgets of the same category are aligned in the same row.
It is recommended for custom visualizations use the category "customWidget".
|tooltip||Defines a language dependent tool tip which is show on mouse hover over the widget icon in the widget selection control.|
|container||These properties configure the container for the widget
A list of action keys. These actions will be shown in the widget property popup. There is a set of predefined actions that can be used if needed. Available default actions are:
Additional default actions: autoRefresh, actions, preselection
|templateUrl||Points to the custom widget view template, where the widget UI is implemented.|
|iconUrl||The icon which is shown in the widget selection control for this widget. It is recommended to use icons with 32x32 px|
|controller||Defines the name of the custom widget main controller. This property is optional.|
|resolve||In this property the widget interface is described. Here the developer can define three methods: getDataMapping, calculateCoordinateList and hasDefaultSelection.|
|actionResolver||This property provides a function which is able to resolve widget specific actions. This property is optional.|
|assignData||Points to the view template URL for the configuration part of the custom widget in the "Assign Data Dialog". This property is optional.
Data Assignment is covered in chapter 2 - Setting up data assignment.
|assignColumns||Points to the view template URL for the column assignment. This property is optional.
Data Assignment is covered in chapter 2 - Setting up data assignment.
|advancedProperties||Points to the view template URL for advanced properties. This property is optional.
Advanced properties for column configuration are covered in chapter 3 - Configuration of assigned columns.
|columnTypeConfigUrlServiceProvider||Only needed in conjunction with the assignData property. This provider defines the URL to three template files that are needed to configure column properties in the "Assign Data" dialog.
Advanced properties for column configuration are covered in chapter 3 - Configuration of assigned columns
|thresholdProperties||Points to the view template URL for threshold properties. This property is optional.
Threshold configuration is covered in chapter 4 - Configuration of thresholds
|viewModeActions||These actions will be shown in the custom widget menu in view mode.|
|actionFramework||Here the user interactions (triggers) for the action framework are defined. This property is optional.|
The first of the following AngularJS expressions will evaluate and therefore display the content of a scope variable.
See: AngularJS documentation for Angular expressions
What are AngularJS Services?
AngularJS services are objects, that are globally available in an AngularJS application and provide certain functionalists. In order to use a service, for example in an AngularJS controller, it needs to be injected.
See: AngularJS documentation for Angular services
Read in this series:
- (0) Custom widgets introduction and prerequisites
- (1) Creating a simple custom widget
- (2) Setting up data assignment
- (3) Configuration of assigned columns
- (4) Configuration of thresholds
- (5) Selection handling
- (5a) Multiple selection handling
- (6) Using filters
- (7) Creating actions
- (8) Enable multi-language support
- (9) Using the D3 library within a custom widget