Extend The Functionality Of A Dashboard

[intapiuser]

Introduction

This post describes the process for creating a new plugin that extends the functionality of the dashboard user interface.  There are several different aspects that you can modify, this document will focus on the most common use cases.

Use Cases

Here we will explain how to do it in detailed steps.

OPTION 1 - ADDING NEW OPTIONS TO MENUS

This is a fairly common use case, where new functionality needs to be added in to existing context menus. at the dashboard level.  This post will show the details of one of our plugins to show how this is possible.   This plugin adds in the option to add/edit the custom JavaScript of each widget on a dashboard.  There are only two files included with this plugin, plugin.json and addEditScriptToWidgetDashboardMenu.js.  The plugin.json file just contains the name of this plugin and the name of the JavaScript file that we need to add.  This just tells Sisense to load a plugin named addEditScriptToWidgetDashboardMenu and that it includes a file named addEditScriptToWidgetDashboardMenu.js.

{
name: "addEditScriptToWidgetDashboardMenu",
source: [
"addEditScriptToWidgetDashboardMenu.js"
],
style: []
}

The next file uses the prism.on(eventname,function) code to attach a function to a specific event.  The beforewidgetindashboardmenu event fires whenever a user clicks on a menu icon on a widget in a dashboard.  A full list of dashboard-level events can be found in our documentation here.  So whenever a user clicks on a widget's settings menu, it runs this function which adds in a new menu item (and separator line).  

var beforewidgetindashboardmenuAddItem = function(ev,args){
'use strict';
var scope = {widget:args.widget}, // initialize scope
activity = prism.$injector.get('base.services.$activity'), // get activity service
command = { // initialize edit script command
  command: prism.$command.create('dashboard.commands.editWidgetScript', { $scope: scope, $activity: activity })
},
separator = {type:"separator"}; // initialize separator
// add items to menu
args.items.push(
  separator,
  command
);
};
prism.on("beforewidgetindashboardmenu",beforewidgetindashboardmenuAddItem);

When creating new menu items, we typically add separators to group buttons based on functionality and they are simply object with a type property of "separator'.  Menu items can be individual commands, such as the example above, or can display a sub-menu with additional menu items.  When creating a single menu item with your own functions, see the reference below.

{
 caption: "my label",             // (required for all but separators) the text to display in the menu
 type: "option",                  // (optional) The following types are supported
                                  //    "option" - a radio button (clicking does not close the menu)
                                  //    "check" - check box
                                  //    "header" - header text 
                                  //    "separator" - a divider line
 execute: myFunction,             // (optional) attach a function to run whenever this menu item is clicked
                                  //    This action is called before the menu gets closed, so it may be beneficial to 
                                  //    run this asynchronously using the setTimeout function
 checked: false,                  // (optional) either true or false to determine whether to show a checkbox
                                  //    This works for radio buttons, as well
 items: [array of submenu items], // (optional) an array of menu items, which will show up in a sub-menu
 disabled: false                  // (optional) will hide the menu item when true
 hidden: false                    // (optional) will hide the menu item when true
 classes: "myClassName"           // (optional) adds a CSS class to the menu item
 confirm: false                   // (optional) when true, adds a confirmation prompt on click
                                  //    If you supply an object in the format of { critical:true, message:"some message"}
                                  //    you can override the confirmation dialog
 closing: false                   // (optional) when true, the menu closes on click for radio buttons
 change: onChangeFunction         // (optional) callback function for radio buttons, whenever the selection is changed
 customProperty1: "my value"      // (optional) add your own custom properties that get stored with each menu item
}

The plugin described here leveraged a specific event to ensure it only fires when a user clicks on a widget menu in a dashboard, but if you wanted to attach an event to a specific menu you can just use the generic beforemenu event and check the HTML element's parent to figure out which menu was clicked.  You should be able to identify it based on the classname or div id.

OPTION 2 - ADDING NEW LINKS/BUTTONS TO YOUR DASHBOARD

We currently have a few plugins in our support forums that demonstrate this (links below), but this post will walk through the process of creating a plugin that adds links to your dashboard.  Like all plugins, we need to have a plugin.json file that specifies the plugin name and all JavaScript/CSS files that need to be loaded.  If we look at the code, there is an object that has a name (of the plugin), a source property (an array of all the javascript files required), and a style property (an array of all CSS files required).  In this case, two JavaScript files are required, buttons.js and addButtons.js.  

{
 name: "addButtons",
 source: [
   "buttons.js",
   "addButtons.js" ],
 style: []
}

Looking at the buttons.js file, this is where an admin can configure what new links to add to the system.  This file was separated out, to differentiate between configuration files and  code files.  We need a place to store any extra buttons to add, so they are placed within a new property of the prism object.  This is just a way to store configuration settings, so that they can be referenced later.

// Add an array to the prism object for additional links
prism.extraButtons = [
{
 link: "http://www.google.com",
 label: "Google"
}
];

The addButtons.js file is where the links actually get created.  In order to run a function within the context of Sisense, we use prism.run( [ ] ).  The only thing added here is a function that waits for the dashboard to finish loading, then loop through all the buttons specified in buttons.js and add them as links.  There is a function createButton that takes in a url and a label, which is what a user configures in buttons.js.  We load the buttons stored in prism.extraButtons, and run this function for each one.  The function creates HTML for each button that's identical to the HTML used in the existing links.  Once the new buttons are created,  we look for the container object (which has a class of main-nav) and append the new button to that container.  Since we create the HTML identical to the existing buttons, the styling will match the CSS used by the dashboard.

prism.run([ function() {
 // Wait for the dashboard to load
 setTimeout( function() {
   // Create Button Function
   var createButton = function (url, label) {
     // Create container div
     var buttonDiv = $('<div class="nav-item"></div>');
     // Create Anchor
     var buttonAnchor = $('<a href="' + url + '">' + label + '</a>');
     // Create Divider Line
     var buttonDivider = $('<div class="line"></div>');
     // Put everything together
     buttonDiv.append(buttonAnchor);
     buttonDiv.append(buttonDivider);
     // Find navigation menu
     var navMenu = $('#main-nav');
     // Append the new button
     navMenu.append(buttonDiv);
   };
   // Add the new button
   $.each(prism.extraButtons, function() {
      // For each button
      createButton(this.link, this.label);
   });
 }, 1000);
}
]);

Relevant plugin:

• Add Additional Links to your Dashboard