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

[toc on_off::hide=0 box::collapsed=1]

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

Options

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

• Login with SSO token (from JasperReports Server configured to integrate with CAS server)

• Login with plain text credentials

• Login with hooks

• Destroy session

• Change user locale

• Advanced

  • UI for Login/Logout

  • UI for Login/Logout with SSO token

  • Share common config between 'visualize' calls

Information about reporting/analytic resources

• Discover available types, formats etc.

Report rendering

• Render report

• Pagination (Next/Previous)

• Pagination (Range)

• Cancel Report Execution

• Refresh

• Isolate Report

• Composition of 4 reports

Events

• Listen for change page totals

• Track report completed status

• Listen to pageFinal event

• Customize report's DOM before render

JIVE

• Enable default JIVE UI

• Use 'static' id to select JIVE components

• Change Chart Type

• Undo / Undo All / Redo JIVE actions + 'canUndo' and 'canRedo' events

• Change table column sorting order

• Change table column filters

• Change table column basic formatting

• Change table column conditional formatting

• Change crosstab column order

• Change crosstab rows order

Hyperlinks

• Basic Customization

• Drill-Down in separate container

• Use links as data

Exports

• Export report

Repository

• Resources search

Input Controls

• Get input controls data

• Bind input control to report

Diagnostic

• Scope Checker

• Diagnostic tool

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
         }
    });
});

More operations with resources search

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

• Visualize.js - API Notes and Samples - Report

InputControls

• Visualize.js - API Notes and Samples - Input Controls

Resources Search

• Visualize.js - API Notes and Samples - ResourcesSearch

Error Handling

• Visualize.js - API Notes and Samples - Error Handling