Most reports rendered in the JasperReports Server native interface have interactive abilities such as column sorting provided by a feature called JIVE: Jaspersoft Interactive Viewer and Editor. The JIVE UI is the interface of the report viewer in JasperReports Server, and the same JIVE UI is replicated on reports generated in clients using Visualize.js.

Not only does the JIVE UI allow users to sort and filter regular reports, it also provides many opportunities for you to further customize the appearance and behavior of your reports through Visualize.js.

This chapter contains the following sections:

Interacting With JIVE UI Components

The visualize.report interface exposes the updateComponent function that gives your script access to the JIVE UI. Using the structures exposed by updateComponent, you can programmatically interact with the JIVE UI to do such things as set the sort order on a specified column, add a filter, and change the chart type. In addition, the undoAll function acts as a reset.

For the API reference of the visualize.report interface, see Report Functions.

First enable the default JIVE UI, then the components of the JIVE UI are available after running a report:

Each component of the JIVE UI has an ID, but it may change from execution to execution. To refer to components of the UI, create your report in JRXML and use the net.sf.jasperreports.components.name property to name each component you want to reference, such as a column in a table. Then you can reference the object by this name, for example "sales", and use the updateComponent function.

Or:

We can also get an object that represents the named component of the JIVE UI:

The following example shows how to create buttons whose click events modify the report through the JIVE UI:

The associated HTML has buttons that will invoke the JavaScript actions on the JIVE UI:

Changing the Chart Type

If you have the name of a chart component, you can easily set a new chart type and redraw the chart.

Or:

The following example creates a drop-down menu that lets users change the chart type. You could also set the chart type according to other states in your client.

This code also relies on the report.chart.types interface described in Discovering Available Charts and Formats.

As shown in the following HTML, the control for the chart type is created dynamically by the JavaScript:

Changing the Chart Properties

Those chart components that are based on Highcharts have a lot of interactivity such as built-in zooming and animation. The built-in zooming lets users select data, for example columns in a chart, but it can also interfere with touch interfaces. With visualize.js, you have full control over these features and you can choose to allow your users access to them or not. For example, animation can be slow on mobile devices, so you could turn off both zooming and animation. Alternatively, if your users have a range of mobile devices, tablets, and desktop computers, then you could give users the choice of turning on or off these properties themselves.

The following example creates buttons to toggle several chart properties and demonstrates how to control them programmatically. First the HTML to create the buttons:

Here are the API calls to set the various chart properties:

Undo and Redo Actions

As in JasperReports Server, the JIVE UI supports undo and redo actions that you can access programmatically with Visualize.js. As in many applications, undo and redo actions act like a stack, and the canUndo and canRedo events notify your page you are at either end of the stack.

Associated HTML:

Sorting Table Columns

This code example shows how to set the three possible sorting orders on a column in the JIVE UI: ascending, descending, and no sorting.

Associated HTML:

Filtering Table Columns

This code example shows how to define filters on columns of various data types (dates, strings, numeric) in the JIVE UI. It also shows several filter operator such as equal, greater, between, contain (for string matching), and before (for times and dates).

Associated HTML:

Formatting Table Columns

The JIVE UI allows you to format columns by setting the alignment, color, font, size, and background of text in both headings and cells. You can also set the numeric format of cells, such as the precision, negative indicator, and currency. Note that the initial appearance of any numbers also depends on the locale set either by default on JasperReports Server, or specified in your script request, as described in Requesting the Visualize.js Script.

The associated HTML has static controls for selecting all the formatting options that the script above can modify in the report.

Conditional Formatting on Table Columns

The JIVE UI also supports conditional formatting so that you can change the appearance of a cell's contents based on its value. This example highlights cells in a given column that have a certain value by changing their text color and the cell background color. Note that the column name must be known ahead of time, for example by looking at your JRXML.

This example has a single button that allows the user to apply the conditional formatting when the report is loaded:

Sorting Crosstab Columns

Crosstabs are more complex and do not have as many formatting options. This example shows how to sort the values in a given column of a crosstab (the rows are rearranged). Note that the code is slightly different than Sorting Table Columns.

The associated HTML has the buttons to trigger the sorting:

Sorting Crosstab Rows

This example shows how to sort the values in a given row of a crosstab (the columns are rearranged).

The associated HTML has the buttons to trigger the sorting:

Disabling the JIVE UI

The JIVE UI is enabled by default on all reports that support it. When the JIVE UI is disabled, the report is static and neither users nor your script can interact with the report elements. You can disable it in your visualize.report call as shown in the following example:

Associated HTML: