(0) Custom Widgets Introduction and Prerequisites

Knowledge base
,
1

Introduction 

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.

Prerequisites

The base technologies

The base technologies used to create the MashZone NEXTGEN user interfaces are HTML, CSS (LESS) and Javascript (AngularJS). For a better understanding of the custom widget creation process in the different chapters, it is helpful to know the basics of these 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:

HTML/CSS/Javascript tutorials/websites

AngularJS tutorials/websites

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

Where are custom widgets located?

Custom visualizations are located in the custom widgets root folder: 
<installDir>/apache-tomee-jaxrs/webapps/presto/hub/dashboard/widgets/customWidgets

Each custom widget has an own folder under the custom widgets root folder:
<installDir>/apache-tomee-jaxrs/webapps/presto/hub/dashboard/widgets/customWidgets/myCustomWidget

How are custom widgets be activated?

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.

customWidgetsModule.js 
angular.module("customWidgets", [
"myCustomWidget",
"demoWidget1Module",
"demoWidget2Module",
"demoWidget3Module",
...
]);

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:

widget_<widgetName>.less 
.panel-dashboard-default[widget-type='<widgetName>'] h3{
    text-decoration: underline;
}

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:

widget_<widgetName>.less 
.panel-dashboard-default[widget-type='<widgetName>'] {
    .panel-body{
        background-color: lighten(@brand-primary, 55%);
        color: @default-text-color;
        .title {
            font-weight: bold;
        }
    }
}

.<widgetName>{

 width: 100%;

height: 100%;

 overflow: auto;


h<span style="color:#FFD700;">3</span>{
   <span style="color:#FF0000;"> text-decoration</span>: <span style="color:#FFD700;">underline</span>;
    <span style="color:#FF0000;">text-align</span>: <span style="color:#FFD700;">center</span>;
}



}

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:

1 
angular.module('advancedWidgetModule', ['prestoDashboard.dashboardProvider']);

How to configure a custom widget?

Each custom widget has a configuration file that contains it's configurable properties.

Property Name Explanation
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
  • hideHeader: true if initially the container header should be invisible, otherwise false
  • hideBorder: true if initially the container border should be invisible, otherwise false
  • width: initial width of the widget,
  • height: initial height of the widget; if hideHeader === false the header height is part of the provided height value
  • contentMinHeight: minimum height for the widget, the container header height is not part of this value
  • contentMinWidth: minimum width for the widget
actions

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.

What are AngularJS Expressions?

AngularJS expressions are JavaScript-like code snippets that are evaluated against a scope object.
The first of the following AngularJS expressions will evaluate and therefore display the content of a scope variable.

<p>
  This is the content of the scope variable columns: {{columns}}
</p>

<p>

This is the size of the scope variable columns being of type array: {{columns.length}}

</p>

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:

image.png

image.png

image.png