API Reference - Visualize.js

The JavaScript API exposed through Visualize.js allows you to embed and dynamically interact with reports. With Visualize.js, you can create web pages and web applications that seamlessly embed reports and complex interaction. You can control the look and feel of all elements through CSS and invent new ways to merge data into your application. Visualize.js helps you make advanced business intelligence available to your users.

This chapter contains the following sections:

Requesting the Visualize.js Script
Contents of the Visualize.js Script
Usage Patterns

Each function of Visualize.js is then described in the following chapters:

API Reference - login and logout
API Reference - resourcesSearch
API Reference - report
API Reference - inputControls
API Reference - dashboard
API Reference - Errors

The last chapters demonstrate more advanced usge of Visualize.js:

API Usage - Report Events
API Usage - Hyperlinks
API Usage - Interactive Reports
Visualize.js Tools

Requesting the Visualize.js Script

The script to include on your HTML page is named visualize.js. It is located on your running instance of JasperReports Server. Later on your page, you also need a container element to display the report from the script.

<!-- Provide the URL to visualize.js -->
<script src="http://bi.example.com:8080/jasperserver-pro/client/visualize.js"></script>
<!-- Provide a container for the report -->
<div id="container"></div>

You must specify a domain name or IP address where your server is running, using localhost causes errrors.

The content of visualize.js is type='text/javascript', but that is the default so you usually don't need to include it.

You can specify several parameters when requesting the script:

Parameter Type or Value Description
userLocale locale string Specify the locale to use for display and running reports. It must be one of the locales supported by JasperReports Server. The default is the locale configured on the server.
logEnabled true|false Enable or disable logging. By default, it is enabled (true).
logLevel debug|info|warn|error Set the logging level. By default the level is error.
baseUrl URL The URL of the JasperReports Server that will respond to visualize requests. By default, it is the same server instance that provides the script.
_opt true|false When true, the Javascript is optimized (reduced in size). By default, this parameter is false. Turning on optimization also improves the encapsulation of the Visualize.js library and may reduce undesirable side-effects. See the example belo

The following request shows how to use script parameters:

<script src="http://bi.example.com:8080/jasperserver-pro/client/

If you notice undesirable side-effects when including the Visualize.js library, set the optimization flag to provide better protection, also known as encapsulation. For example, the Visualize.js functions might interfere with collapse functions on your menus. To turn on optimization and reduce side-effects such as this one, set the optimize flag when you load Visualize.js, as shown in the following example:

<script src="http://bi.example.com:8080/jasperserver-pro/client/visualize.js?_opt=true"></script>

Contents of the Visualize.js Script

The Visualize.js script itself is a factory function for an internal JrsClient.

 *  Establish connection with JRS instance and generate
 *  ready to use client
 *  @param {Object} properties - configuration to connect to JRS instance
 *  @param {Function} callback - optional, successful callback
 *  @param {Function} errorback - optional, invoked on error
 *  @param {Function} always - optional, invoked always
function visualize(properties, callback, errorback, always){}
 *  Store common configuration, to share them between visualize calls
 *  @param {Object} properties - configuration to connect to JRS instance
function visualize.config(properties);

You write JavaScript in a callback that controls what the client does. The following code sample shows the functions of the JrsClient that are available to you:

{    /**
     * Perform authentification with provided auth object
     * @param auth {object}  - auth properties
    login : function(auth){},
     * Destroy current auth session
    logout : function() {},
     * Create and run report component with provided properties
     * @param properties {object}  - report properties
     * @returns {Report} report - instance of Report
    report : function(properties){},
     * Create and run controls for provided controls properties
     * @param properties {object}  - input controls properties
     * @returns {Options} inputControls instance
    inputControls : function(properties){},
     * Create and run resource search component for provided properties
     * @param properties {object}  - search  properties
     * @returns {Options} resourcesSearch instance
    resourcesSearch : function(properties){}

These functions are described in the remaining API reference chapters.

Usage Patterns

After specifying the authentication information, you write the callback that will execute inside the client provided by visualize.js.

    server: "http://bi.example.com",
    auth: {
        name : "joeuser",
        password: "joeuser"
}, function(v){
    //'v' is a client to JRS instance under  "http://bi.example.com"
    //session established for joeuser/joeuser
    var report = v.report(...);
}, function(err){

The following sample shows how to use the always callback:

    server: "http://bi.example.com",
    auth: {
        name : "joeuser",
        password: "joeuser"
}).always(function(err, v) {
    if (err) {
    v.report(); // use v here

Testing Your JavaScript

As you learn to use Visualize.js and write the JavaScript that embeds your reports into your web app, you should have a way to run and view the output of your script.

In order to load Visualize.js, your HTML page containing your Javascript must be accessed through a web server. Opening a static file with a web browser does not properly load the iFrames needed by the script.

One popular way to view your Visualize.js output, is to use the jsFiddle online service. You specify your HTML, JavaScript, and optional CSS in 3 separate frames, and the result displays in the fourth frame.

Another way to test your JavaScript is to use the app server bundled with JasperReports Server. If you deploy the server from the installer with the Apache Tomcat app server, you can create an HTML file at the root of the server web app, for example:


Write your HTML and JavaScript in this file, and then you can run Visualize.js by loading the file through the following URL:


Cross-Domain Security

After developing your web application and embedding Visualize.js, you will deploy it to your users through some web domain, for example bi-enabled.myexample.com. For testing, JasperReports Server accepts Visualize.js requests from any domain, and your web app will display embedded reports and dashboards. However, once you go into production, you should add security and make sure that the server responds only to Visualize.js requests from your web app. This is called cross-site request forgery (CSRF) protection.

JasperReports Server includes a configurable whitelist of domains, and it only responds to Visualize.js requests from those domains. Add your web domain to this whitelist, and no other web apps on malicious domains can access your server. In addition to whitelisted domains, JasperReports Server always responds to requests that originate from the same domain as the server itself.

To configure the cross-domain whitelist:

1. Log in as system administrator (superuser).
2. Select Manage > Server Settings then Server Attributes.
3. The server attribute named domainWhitelist contains a regular expression that matches allowed domains. Set it as follows:
When your Visualize.js web app is on another domain, such as in this example, create a regular expresion to match the protocol, domain name and port numbers. You can also match multiple subdomains or several port numbers as in this example:

domainWhitelist = http://*.myexample.com:80\d0

The server translates this simplified expression into the proper regular expression ^http://.*\.myexample\.com:80\d0$. If you want to avoid the translation, put ^ $ around your value.

When your Visualize.js web app is on the same domain as your JasperReports Server set the value to <blank> (no value) so that no other domain has access:

domainWhitelist = <blank>

It is also possible to limit the domains accessing the JasperReports Server for each organization. For advanced configuration details, see the section on cross-domain whitelists in the JasperReports Server Security Guide.

For more information about setting attributes see the JasperReports Server Administrator Guide.