Creating custom widgets

You can use the Analytics page in IBM Process Mining to build custom widgets and analyze the data based on your requirements. You can also use these custom widgets to customize how your data is processed and displayed.

Understanding the scripts to create custom widgets

You can use the following files to successfully create a custom widget:

frontend.js: Indicates the JavaScript file that runs on your browser to process and display your data. For more information on the contents of the frontend.js file, see Understanding the frontend.js file.
view.html: Indicates the HTML file that includes the content of your widget. For more information on the contents of the view.html file, see Understanding the view.html file.
style.css: Indicates the CSS file that you can use to style your widget. For more information on the contents of the style.css file, see Understanding the style.css file.
schema: Indicates the parameter table that you can use to add configurable parameters in your custom widget. For more information on schema, see Understanding schema.

Note: For information about backend.js, refer to the previous versions of the documentation.

Understanding the frontend.js file

Using the following functions, you can configure the frontend.js file to return an object:

init(context)

This function runs when you initialize a widget. The context parameter includes two properties: element and scope. The element property indicates the jQuery object that contains the DOM node of your widget. The scope property indicates the angular context of your widget. You can also change the DOM element of your widget with jQuery or change the scope with AngularJS.

update(data, context)

This function runs whenever you reload the dashboard. The data object contains that the data that can be bound to the scope for display. The context object is similar to the parameter used in the init function. Example:

 javascript
 update: function(data, context) {
 // set your data in scope so you can use it where you need
 context.scope.data = data;}

You can also use jQuery or Underscore.js to alter your data as indicated in the following example. Example:

javascript
update: function(data, context) {
// set your data in scope after transforming it so you can use it where you need
context.scope.data = _.map(data, function(element) {
  return {
      name: element.id,
      text: element.value }; });}

resize(size, context)

This function runs whenever you resize the widget. The size object must include the width and height of the widget. The context object is similar to the parameter used in the init function.

The following code is an example of how data can be retrieved from a table widget of an another dashboard:


return {
  init: function (context) {
    var org = context.scope.utils.organizationKey;
    //context.scope.utils.organizationKey makes it possible to retrieve the organization of the current dashboard.
    var pId = context.scope.utils.projectName;
    //context.scope.utils.projectName makes it possible to retrieve the project name of the current dashboard.
    var dSlug = 'beautiful-dashboard';
    var wId = 'simpletable';
    //wId is the widget's name.
    
    var callback = function(data){
      console.info('Data: ',data);
      //Here you can process the data get by the API.
      return data;
    }
    context.scope.utils.loadWidgetData('dataFromWidget', dSlug, wId,pId, org, callback);
    //dataFromWidget is the name of the attribute from which the data of the widget view can be retrieved. 
  },
  update: function (data, context) {},
  resize: function (size, context) {}
};

You can also use a compacted code without optional arguments:


  init: function (context) {
    var dSlug = 'beautiful-dashboard';
    var wId = 'simpletable';
    context.scope.utils.loadWidgetData('dataFromWidget', dSlug, wId);
  },
//In the compacted code, organization and processId are retrieved from the currently chosen dashboard.

The dashboard slug can be retrieved from the dashboard info model:

Dashboard info

Understanding the view.html file

The view.html file contains the content of your widget.

You can use the following angular helpers to display your data and change HTML elements based on the content without modifying the DOM with JavaScript:

Expressions
Interpolation
Filters
You can use the following code to configure your widget in the view.html file:


<div>
  <p>widgetId: {{ widgetId }}</p>
  <p>utils.organizationKey: {{ utils.organizationKey }}</p>
  <p>utils.projectName: {{ utils.projectName }}</p>

  <table class="table table-striped table-condensed">
    <tr ng-repeat=" row in dataFromWidget " >
      <td>{{ row['attr-process']}}</td>
      <td>{{ row['attr-activity']}}</td>
      <td>{{ row['NOW']}}</td>
    </tr>
  </table>
</div>

Example The following example describes the contents of a view.html file based on a frontend.js file.

Assume that the frontend.js file of custom widget includes the following script:

javascript
init: function(context) {
    context.scope.myVariable = 'Plugin widget test';
    context.scope.myIntVariable = 8;
}

You can use the following scripts to create a corresponding view.html file:

<!-- the next syntax will print the content of myVariable inside the paragraph -->
<p>{{myVariable}}</p>

<!-- the next paragraph will be displayed only if myIntVariable is greater than 5 and the content will be formatted as a number -->
<p ng-if="myIntVariable > 5">{{myIntVariable | number}}</p>

For more information on scripting the view.html file, see Angular documentation.

Advanced Filters

In addition to angular filters, you can use the following custom filter based on your requirement.

formatMeasure: param

The following table describes the various parameters that you can use with the custom filter:

Parameter	Purpose
`auto`	Automatic formatter
`date`	Date formatter with localization support
`datetime`	Date and time formatter with localization support
`duration`	Duration formatter
`number`	Number formatter with localization support
`text`	Text formatter
`percentage`	Percentage formatter

Following example describes how to use the custom filters in the view.html file.

<!-- will print the date with the format based on your location i.e. 01/01/2018 -->
<p>{{myDateVariable | formatMeasure:'datetime'}}</p>

Understanding the style.css file

The style.css file contains the stylesheet for your widget. For example, the style.css file includes the contents:

p {
    font-size: 14px;
    color: red;
}

Note: The created widget is displayed in the style that is mentioned in the style.css file.

Understanding schema

The schema table contains optional parameters that you can set in the widget options.

You can use either of the following types to define parameters in schema:

string
dimension

Additional Reference

For more information on functions, objects, and parameters, see the following links:

Creating a sample custom widget

To create a custom widget, complete the following steps:

From the Projects page, open the required process.
Open the Analytics page, and open the dashboard in which you want to create the custom widget.
On the dashboard, click Edit.
On the widget panel, click the Custom icon, and then click New.

Note: You can choose any of the widgets in the menu or create a custom widget by using the scripts that are mentioned in the Understanding the scripts to create custom widgets.
On the Pending changes will be lost message box, click Yes.
On the Name box of the Info tab, type a name for the custom widget.

Do not include spaces and special characters in the name for custom widgets.
In the left pane, click Schema, and then click Add new property to manage inputs from users. For example, you can ask users to input their name to the widget by defining a Name parameter as indicated in the following figure. Do note that this is an optional feature that you can set for the widget.
In the left pane, click frontend.js, and then use the functions that are mentioned in Understanding the frontend.js file to define the script.
In the left pane, click view.html, and then use the functions that are mentioned in Understanding the view.html file to define the script.
Click Save.

The new widget is displayed in the list of custom widgets.