Visualize.js - API Notes and Samples (v5.6)

Please Note - Newer examples available

This Wiki article is for the VIsualize.js implementation released with JasperReports Server v5.6.  Visualize.js was changed significantly with JasperReports Server v6.0 - see this page for more up to date 

Including visualize.js into your Web page

To use visualize.js, you need to load the visualize.js Javscript library. This will initialize visualize.js.

Ordinary usage

Load visualize with defaults

<script src="http://<your JRS instance>/jasperserver-pro/client/visualize.js"></script>

Load API

Method GET
URL {schema}://{host}:{port}/{contextPath}/client/visualize.js?{options}
Content-Type application/javascript

Options

Name Description Supported Defaults
userLocale Provide user locale JasperReports Server supported locales Default for JRS
logEnabled Enable or disable logging true / false true
logLevel Logging level debug|info|warn|error error
baseUrl JasperReports Server deployment URL any URL pointing to the JasperReports Server deployment {schema}://{host}:{port}/{contextPath} from request

Customize with parameters

You can use the parameters outlined above in the visualize.js Javascript load.

<script src="http://<your JRS instance>/client/visualize.js?userLocale=fr&log=true"></script>

Basic usage in a Web page

To establish connection and get object with access to JasperReports Server functionality

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

Use deferred instead of callback

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

Samples

Using JSFiddle

JSFiddle is a playground for web developers, a tool which may be used in many ways. You can use it as an online editor for snippets built from HTML, CSS and JavaScript. The links to the "JSFiddles" below show visualize.js Javascript in action.

To use them:

  1. Install JasperReports Server with the sample databases and reports

  2. Select a JSFiddle link below

  3. Change the relevant URLs in the JSFiddle HTML to point to your installed JasperReports Server

    • from: <script type='text/javascript' src="http://visualizejs-preview.eng.jaspersoft.com:8080/jasperserver-pro-branch/client/visualize.js"></script>

    • to: <script type='text/javascript' src="http://<your JasperReports Server>/jasperserver-pro/client/visualize.js"></script>

  4. Run the JSFiddle

Copying Fiddle Components

So you've looked over one of our samples and want to use it to implement the feature in your own web page. There are three panels to the fiddle for source input, an HTML, Javascript and CSS panel.

There are also a set of controls on the left of the panels. One of the items in that set of controls is called External Resources. It allows you to enter JS libraries that would be included in your code with <script></script> tags.

If you just copy what's in the HTML panel without checking what might be referenced in the External Resources control, your <script></script> referenced JS Libraries would be incomplete. In the example above, you would need to include the jquery-2.1.0.js library in the HTML as:

<script type='text/javascript' src="http://code.jquery.com/jquery-2.1.0.js"></script>

The entry under External Resources is the URL link that you would use in the src atttribute.

With these caveats, enjoy fiddling with these fiddles.


Authentification

Information about reporting/analytic resources

Report rendering

Events

JIVE

Exports

Repository

Input Controls

Diagnostic

Workflows - Advanced usage

Working with server session

Destroy session

visualize({
    server: "http://bi.example.com",
    auth: {
        name : "joeuser",
        password: "joeuser"
    }
}).done(function(v){    
 
        //.........
        //later in code
 
        v.logout()
          .then(function(){
              alert("Session Destroyed");
          })
          .fail(function(err){
             alert(err.message);
          });       
}).fail(function(err){
    alert(err.message);
});

Login with another credentials

visualize({
    server: "http://bi.example.com",
    auth: {
        name : "joeuser",
        password: "joeuser"
    }
}).done(function(v){    
 
        //.........
        //later in code
 
        v.logout()
         .then(function(){
              return v.login({
                   "token": "43322-fds-34ddd"
              });
          })
          .fail(function(err){
             alert(err.message);
          });       
 
}).fail(function(err){
    alert(err.message);
});

Common configs between few visualize calls

API Sugar

//Common configs, only once
visualize.config({
    server: "http://bi.example.com",
    auth: {
        name : "joeuser",
        password: "joeuser"
    }
});
 
//...
 
visualize(function(v){
    //'v' it's a client to JRS instance under  "http://bi.example.com"
    //session already established for joeuser/joeuser
    var report = v.report(...);
 
});
 
//...
 
visualize(function(v){
    //'v' it's a client to JRS instance under  "http://bi.example.com"
    //session already established for joeuser/joeuser
    var ic = v.inputControls(...);
});

Workflows - Render report

Sugar API

visualize(function(v){
    v("#container").report({
         resource: "/public/Samples/Reports/06g.ProfitDetailReport",
         error: function(err) {
            alert(err.message);
        }
    });
    //no results returned by call v("#container").report(...);
});

or

visualize(function(v){
    var report = v.report({
       resource: "/public/Samples/Reports/06g.ProfitDetailReport",
       container: "#container"
       error: function(err) {
            alert(err.message);
       }
    });
});

NOTE: For more information about Report look in Report

Workflows - Repository

Search for resources in public folder

visualize(function(v){
    var search = v.resourcesSearch({
         folderUri: "/public",
         recursive: false
         success: function(repo) {
            console.log(repo.data()); // resourceLookups
         }
    });
});

NOTE: Look in ResourcesSearch

Workflows - Input Controls

Get avaliable input controls state and structure

visualize(function(v){
    var ic = v.inputControls({
        resource: "/public/ReportWithControls",
        success: function(data) {
           console.log(data); // [{ "id":"Cascading_name_single_select" "options": [{ .
        }
    });
});

More operations with resources search

NOTE: Look in ResourcesSearch

Workflows - Metainformation

Report chart types (TBD: Update samples and workflows for JIVE)

visualize(function(v){
    console.log(v.report.chart.types); //returns array of available chart types
});

Resources types

visualize(function(v){
    console.log(v.reourcesSearch.types); //returns array of available reources types
});

Resources sort options

visualize(function(v){
    console.log(v.reourcesSearch.sortBy); //returns array of available sort options
});

Resources access options

visualize(function(v){
    console.log(v.reourcesSearch.accessType); //returns array of available access options
});

Report export formats

visualize(function(v){
    console.log(v.report.exportFormats);
});

Report table column types

visualize(function(v){
    console.log(v.report.table.column.types);
});

API Reference - Visualize Properties

{
    "oneOf": [
        {
            "type": "object",
            "description": "Visualize main properties",
            "properties": {
                "server": {
                    "type": "string",
                    "description": "Url to JRS instance."
                },
                "auth": {
                    "description": "Authentication Properties",
                    "type": "object",
                    "oneOf": [
                        {
                            "properties": {
                                "token": {
                                    "type": "string",
                                    "description": "SSO authentication token"
                                },
                                "headers": {
                                    "type": "object",
                                    "description": "HTTP header parameters"
                                },
                                "queryParams": {
                                    "type": "object",
                                    "description": "HTTP query parameters"
                                }
                            },
                            "additionalProperties" : false,
                            "required": ["token"]
                        },
                        {
                            "properties": {
                                "name": {
                                    "type": "string",
                                    "description": "Name of the user to authenticate"
                                },
                                "password": {
                                    "type": "string",
                                    "description": "Password of the user to authenticate"
                                },
                                "organization": {
                                    "type": "string",
                                    "description": "Organization of the user to authenticate"
                                },
                                "timezone": {
                                    "type": "string",
                                    "description": "Default user timezone to use for this session"
                                },
                                "headers": {
                                    "type": "object",
                                    "description": "HTTP header parameters"
                                },
                                "queryParams": {
                                    "type": "object",
                                    "description": "HTTP query parameters"
                                }
                            },
                            "additionalProperties" : false,
                            "required": ["name", "password"]
                        }
                    ]
                }
            },
            "required": ["server", "auth"]
        },
        {
            "$ref": "#/definitions/func"
        }
    ],
    "definitions": {
        "func" : {
            "title": "Successful callback",
            "type": "object"
        }
    }
}

API Reference - Visualize

visualize.js it's a factory function for 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);

JrsClient

'v' in our samples, look in Basic Usage for example

{
    /**
     * 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){}
}

Report

InputControls

Error Handling

Feedback