The dashboard function runs dashboards on JasperReports Server and displays the result in a container that you provide. Dashboards are a collection of reports and widgets that you design on the server. Dashboards were entirely redesigned in JasperReports Server 6.0 to provide stunning data displays and seamless integration through Visualize.js.
This chapter contains the following sections:
Dashboard Properties
The properties structure passed to the dashboard function is defined as follows:
{
"title": "Dashboard Properties",
"type": "object",
"description": "JSON Schema describing Dashboard Properties",
"$schema": "http://json-schema.org/draft-04/schema#",
"properties": {
"server": {
"type": "string",
"description": "URL of JRS instance"
},
"resource": {
"type": "string",
"description": "Dashboard resource URI",
"pattern": "^/[^/~!#\\$%^|\\s`@&*()\\+={}\\[\\]:;\"'<>,?/\\|\\\\]+(/[^/~!#\\$%^|\\s`@&*()\\+={}\\[\\]:;\"'<>,?/\\|\\\\]+)*$"
}, |
"container": {
"oneOf": [
{
"type": "object",
"additionalProperties" : true,
"description": "DOM element to render report to"
},
{
"type": "string",
"description": "CSS selector for container to render report to"
}
]
},
"linkOptions": {
"type": "object",
"description": "Dashboard's parameters values",
"properties": {
"beforeRender": {
"type": "function",
"description": "A function to process link - link element pairs."
},
"events": {
"type": "object",
"description": "Backbone-like events object to be applied to JR links",
"additionalProperties" : true
}
}
},
"params": {
"type": "object",
"description": "Dashboard parameter values",
"additionalProperties": {
"type": "array"
}
}
},
"required": ["server", "resource"]
} |
Dashboard Functions
The dashboard function exposes the following functions:
define(function () {
/**
* @param {Object} properties - Dashboard properties
* @constructor
*/
function Dashboard(properties){}
//Special getters
/**
* Get any result after invoking run action
* @returns any data which supported by this bi component
*/
Dashboard.prototype.data = function(){};
//Actions
/**
* Perform main action for bi component
* Callbacks will be attached to deferred object.
*
* @param {Function} callback - optional, invoked in case of successful run
* @param {Function} errorback - optional, invoked in case of failed run
* @param {Function} always - optional, invoked always
* @return {Deferred} dfd
*/
Dashboard.prototype.run = function(callback, errorback, always){};
/**
* Render Dashboard to container, previously specified in property.
* Clean up all content of container before adding Dashboard's content
* @param {Function} callback - optional, invoked in case successful export
* @param {Function} errorback - optional, invoked in case of failed export
* @param {Function} always - optional, optional, invoked always
* @return {Deferred} dfd
*/
Dashboard.prototype.render = function(callback, errorback, always){};
|
/**
* Refresh Dashboard
* @param {Function} callback - optional, invoked in case of successful refresh
* @param {Function} errorback - optional, invoked in case of failed refresh
* @param {Function} always - optional, invoked optional, invoked always
* @return {Deferred} dfd
*/
Dashboard.prototype.refresh = function(callback, errorback, always){};
/**
* Cancel Dashboard execution
* @param {Function} callback - optional, invoked in case of successful cancel
* @param {Function} errorback - optional, invoked in case of failed cancel
* @param {Function} always - optional, invoked optional, invoked always
* @return {Deferred} dfd
*/
Dashboard.prototype.cancel = function(callback, errorback, always){};
/**
* Cancel all executions, destroy Dashboard representation if any, leave only
* properties
* @param {Function} callback - optional, invoked in case of successful cleanup
* @param {Function} errorback - optional, invoked in case of failed cleanup
* @param {Function} always - optional, invoked optional, invoked always
* @return {Deferred} dfd
*/
Dashboard.prototype.destroy = function(callback, errorback, always){};
return Dashboard;
}); |
Dashboard Structure
The Dashboard Data structure represents the rendered dashboard object manipulated by the dashboard function. Even though it is named "data," it does not contain any data in the dashboard or reports, but rather the data about the dashboard. For example, the Dashboard Data structure contains information about the items in the dashboard, called dashlets.
{
"title": "Dashboard Data",
"description": "A JSON Schema describing a Dashboard Data",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"parameters": {
"type": "array",
"description": "Dashboard parameters",
"items": {
"type": "object",
"description": "Dashboard parameter properties"
}
}
}
} |
Rendering a Dashboard
To run a dashboard on the server and render it in Visualize.js, create a dashboard object and set its properties. Like rendering a report, the resource property determine which report to run, and the container property determines where it appears on your page.
var dashboard = v.dashboard({
resource: "/public/test_dashboard",
container: "#container",
success: function() { console.log("dashboard rendered"); },
error: function(e) { alert(e); }
}); |
The following code example shows how to define a dashboard ahead of time, then render it at a later time.
var dashboard = v.dashboard({
resource: "/public/test_dashboard",
runImmediately: false
});
dashboard
.run()
.done(function() {
this
.container("#container")
.render()
.done(function() { console.log("dashboard rendered"); })
.fail(function(e) { alert(e); });
})
.fail(function(e) { alert(e); }); |
Refreshing a Dashboard
You can order the refresh or re-render of the dashboard , as well as cancel the refresh if necessary, for example if it takes too long.
var dashboard = v.dashboard({
resource: "/public/test_dashboard",
container: "#container",
runImmediately: false
});
dashboard.run().done(function() {
setTimeout(function() {
var dfd = dashboard.refresh();
// cancel refresh if it's still running after 2 seconds
setTimeout(function() {
if (dfd.state() === "pending") {
dashboard.cancel();
}
}, 2000);
}, 10000);
}); |
Using Dashboard Parameters
As with reports, dashboard allow or require parameters that the user or your application can manipulate. First, you can discover the list of available parameters:
var dashboard = v.dashboard({
resource: "/public/test_dashboard",
container: "#container",
success: function() { console.log("dashboard parameters - " + this.data().parameters); },
error: function(e) { alert(e); }
}); |
Then you read their values, modify them, and set new values. The dashboard then renders with the new input parameter values:
var dashboard = v.dashboard({
resource: "/public/test_dashboard",
container: "#container",
params: {
Country: ["USA", "Mexico", "Canada"]
},
error: function(e) { alert(e); }
});
dashboard.params(); // returns { Country: ["USA", "Mexico", "Canada"] }
......
dashboard.params({ month: ["2"] }).run();
dashboard.params(); // returns { month: ["2"] } |
In the following example, a button resets the paramters to their default values by sending a null parameter set. First the HTML to define the container and the button:
<script src="http://localhost:8080/jasperserver-pro/client/visualize.js"></script>
<button>Reset params</button>
<br/><br/>
<div id="container"></div> |
And then the JavaScript to perform the action:
function handleError(e) {
alert(e);
}
visualize({
auth: {
name: "superuser",
password: "superuser"
}
}, function (v) {
var dashboard = v.dashboard({
resource: "/public/Samples/Dashboards/1._Supermart_Dashboard",
error: handleError,
container: "#container",
params: {
Store_Country: ["Mexico"],
}
});
$("button").click(function() {
dashboard.params({}).run();
});
}); |
In another example, the script initializes the paramters and the HTML displays a button when they are ready to be applied:
<script src="http://localhost:8080/jasperserver-pro/client/visualize.js"></script>
<br/>
<button disabled>Apply params</button>
<br/><br/>
<div id="container"></div> |
And then the JavaScript to initialize the parameters and enable the button for the user:
function handleError(e) {
alert(e);
}
visualize({
auth: {
name: "superuser",
password: "superuser"
}
}, function (v) {
var initialParams = {
Country: ["USA", "Canada"]
};
var dashboard = v.dashboard({
resource: "/public/Samples/Dashboards/3.2_Inventory_Metrics",
container: "#container",
error: handleError,
params: initialParams,
success: function() {
$("button").prop("disabled", false);
buildParamsInput();
}
}); |
function buildParamsInput() {
var params = dashboard.data().parameters;
for (var i = params.length-1; i >= 0; i--) {
var $el = $("<div>" + params[i].id + ": <input type='text' data-paramId='" + params[i].id + "'/></div>");
$("body").prepend($el);
$el.find("input").val(dashboard.params()[params[i].id]);
}
}
$("button").on("click", function() {
var params = {};
$("[data-paramId]").each(function() {
params[$(this).attr("data-paramId")] = $(this).val().indexOf("[") > -1 ? JSON.parse($(this).val()) : [$(this).val()];
});
$("button").prop("disabled", true);
dashboard.params(params).run()
.fail(handleError)
.always(function() { $("button").prop("disabled", false); });
});
}); |
You can create any number of user interfaces, database lookups, or your own calculations to provide the values of parameters. Your parameters could be based on 3rd party API calls that get triggered from other parts of the page or other pages in your app. When your dashboards can respond to dynamic events, they become truly embedded and much more relevant to the user.
Setting Dashboard Hyperlink Options
When your dashboards are designed for drill-down, your users can access more reports and more data.
var dashboard = v.dashboard({
resource: "/public/test_dashboard",
container: "#container",
linkOptions: {
beforeRender: function (linkToElemPairs) {
linkToElemPairs.forEach(showCursor);
},
events: {
"click": function(ev, link){
if (link.type == "ReportExecution") {
if ("monthNumber" in link.parameters) {
v("#drill-down").report({
resource: link.parameters._report,
params: {
monthNumber: [link.parameters.monthNumber]
}
});
}
}
}
}
}
});
function showCursor(pair){
var el = pair.element;
el.style.cursor = "pointer";
} |
Closing a Dashboard
When you want to reuse a container for other contents and free the dashboard resources, use the destroy function to close it.
var dashboard = v.dashboard({
resource: "/public/test_dashboard",
container: "#container"
});
dashboard.destroy(); |
