API Reference - Visualize.js

The JavaScript API exposed through Visualize.js allows you to embed and programmatically interact with reports dynamically. 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

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

• API Usage - Report Events
• API Usage - Report 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>

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 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.

The following request shows how to use script parameters:

<script src="http://bi.example.com:8080/jasperserver-pro/client/
             visualize.js?userLocale=fr&logLevel=debug"></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
 *  @returns {Deferred} dfd
 */
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
     * @returns {Deferred} dfd
     */
    login : function(auth){},
 
    /**
     * Destroy current auth session
     * @returns {Deferred} dfd
     */     
    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.

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

If you prefer, you can use the deferred pattern instead of the callback:

visualize({
    server: "http://bi.example.com",
    auth: {
        name : "joeuser",
        password: "joeuser"
    }
}).done(function(v){     
 
    //'v' it's a client to JRS instance under  "http://bi.example.com"
    //session established for joeuser/joeuser
 
    var report = v.report(...);
 
}).fail(function(err){
    alert(err.message);
});
Version: 
v6.0.0
v6.0.1
Feedback
randomness