The report function runs reports on JasperReports Server and displays the result in a container that you provide.

This chapter contains the following sections:

Report Properties

The properties structure passed to the report function is defined as follows:

Report Functions

The report function exposes the following functions:

Report Structure

The Report Data structure represents the rendered report object manipulated by the report function. Even though it is named "data," it does not contain report data, but rather the data about the report. For example, the Report Data structure contains information about the links in the report, as explained in Customizing Links, and components of the JIVE UI, as explained in Interacting With JIVE UI Components.

Rendering a Report

To run a report on the server and render it in Visualize.js, create a report object and set its properties. The server and resource properties determine which report to run, and the container property determines where it appears on your page.

The following code example shows how to display a report that the user selects from a list.

The HTML page that displays the report uses a static list of reports in a drop-down selector, but otherwise needs only a container element.

Setting Report Parameters

To set or change the parameter values, update the params object of the report properties and invoke the run function again.

If a report has required parameters, you must set them in the report object of the initial call, otherwise you'll get an error. For more information, see Catching Report Errors.

The example above is trivial, but the power of Visualize.js comes from this simple code. 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 reports can respond to dynamic events, they become truly embedded and much more relevant to the user.

Rendering Multiple Reports

JavaScript Example:

Associated HTML:

Associated CSS:

Setting Report Pagination

To set or change the pages displayed in the report, update the pages object of the report properties and invoke the run function again.

Creating Pagination Controls (Next/Previous)

Again, the power of Visualize.js comes from these simple controls that you can access programmatically. You can create any sort of mechanism or user interface to select the page. In this example, the HTML has buttons that allow the user to choose the next or previous pages.

Associated HTML:

Creating Pagination Controls (Range)

JavaScript Example:

Associated HTML:

Exporting From a Report

To export a report, invoke its export function and specify the outputFormat property. You MUST wait until the run action has completed before starting the export. The following export formats are supported:

"pdf", "xlsx", "xls", "rtf", "csv", "xml", "odt", "ods", "docx", "json"

For CSV and JSON output, see Exporting Data From a Report. Note that the HTML output of a report is not available through Visualize.js.

The following sample exports 10 pages of the report to a paginated Excel spreadsheet:

The following sample exports the part of report associated with a named anchor:

The following example creates a user interface for exporting a report:

Associated HTML:

Exporting Data From a Report

You can also request the raw data of the report in CSV or JSON format.

The following example shows how to export data in CSV format. CSV output is plain text that you must parse to extract the values that you need.:

The following example shows how to export data in JSON format. By its nature, JSON format can be used directly as data within your JavaScript.

Refreshing a Report

JavaScript Example:

Associated HTML:

Canceling Report Execution

To stop a running report, call its cancel function:

The following example is more complete and creates a UI for a spinner and cancel button for a long-running report.

Associated HTML:

Discovering Available Charts and Formats

You can write code to discover and display the types of charts and export formats that can be specified.