The adhocView function displays an Ad Hoc view that allows users to interact with tables, crosstabs, and charts in the target container.

As of JasperReports Server 7.0, Visualize.js can render interactive Ad Hoc views in your web apps. In Visualize.js, only the table, crosstab, or chart of the Ad Hoc view is displayed, not the fields or filter panels. The server generates the user interface (UI) of an Ad Hoc view. You can also customize the appearance and behavior of the Ad Hoc view by accessing hyperlinks and setting event listeners.

This chapter contains the following sections:

Ad Hoc View Properties

The properties structure passed to the adhocView function determines the view to be displayed and its initial state. It is defined as follows:

Ad Hoc View Functions

The adhocView function exposes the following functions:

Ad Hoc View Data Structure

The data object of an adhocView contains metadata about the Ad Hoc view:

{  "title": "Ad Hoc View Data",  "description": "A JSON Schema describing Ad Hoc View Data",  "$schema": "http://json-schema.org/draft-04/schema#",  "type": "object",  "properties":{[/code]                    

Rendering an Ad Hoc View

As with reports and dashboards, Ad Hoc views run on the server and are rendered in a container on your page. First, you create an adhocView object and then set its properties. As with other objects, the resource property determines which Ad Hoc view to run, and the container property determines where it appears on your page.

Ad Hoc views are displayed in Visualize.js in the same state they are saved on the server. Only the table, crosstab, or chart of an Ad Hoc view is rendered in Visualize.js, not the design elements. Visualize.js is intended to display data, not access the underlying data structures used to create the Ad Hoc view.

However, the rendering of an Ad Hoc view includes the icon in the top left corner that allows users to switch between table, crosstab, and chart type. For example, if the Ad Hoc view appears as a table, the user can switch the view to a crosstab or chart. The user may also change the type of chart, though not all chart types work with the data in a given Ad Hoc view.

If you wish to disable the chart selector, specify the following property on the container:

In the following example, the adhocView object is created and initialized first, and then it runs and renders later on demand in the specified container.

Of course, you can add styles to change the size and placement of your Ad Hoc view container, as shown in the following CSS sample.

There are two more functions to manage your Ad Hoc view. Refresh will update the rendered view, and destroy will remove it, leaving only the adhocView object with its properties set.

Getting the Embed Code of an Ad Hoc View

As of JasperReports Server 7.9, the server can provide the code to embed any Ad Hoc view displayed in the Ad Hoc Editor. This lets you browse the repository, preview an Ad Hoc view, and get its basic embed code. You can paste this code directly in your application, and then edit it for your needs. You can also open the view's embed code in JSFiddle to see the effect of your edits in real time, then copy the final code from JSFiddle.

To copy the embed code of an Ad Hoc view:

3.

Click the

The code sample includes comments where you can enter credentials for authentication. You should also change the name of the container to match the one in your application.

As shown by the preview, Visualize.js displays the table, crosstab, or chart of the Ad Hoc views without any design elements such as data selection panel, layout band, or filter panel. Regardless of any changes you make in the Ad Hoc editor, Visualize.js always displays the latest saved version of an Ad Hoc view, as determined by the repository URL in the embed code.

When displayed through Visualize.js, an Ad Hoc view includes the icon in the top left corner that allows users to switch between table, crosstab, and chart type, though not all chart types work with the data in a given Ad Hoc view. This selector changes the appearance of the Ad Hoc view in the user's current session, but the changes can't be saved. For every new session, Visualize.js displays the default appearance of the Ad Hoc view.

Setting the Visualization Type

Visualize.js allows your code to also interact programmatically with the Ad Hoc view, to customize its appearance in response to other events or inputs. The following sections give examples of how to update the appearance of the Ad Hoc view through your code.

An Ad Hoc view has a default visualization type, either table, crosstab, or chart that is determined by its creator and saved in the repository. When you run and render an Ad Hoc view, your users will see the visualization type of the view as it was last saved. Through Visualize.js, you can change the visualization type, for example so that users first see a crosstab or a specific type of chart.

The following example shows how your code can set the visualization type by modifying the canvas object of your adhocView object during initialization.

You can also let the Ad Hoc view render with the default visualization and then change to a different the visualization type at a later time:

The available visualization types and charts are listed by the type property of the canvas object:

Setting Ad Hoc View Filters

Another way to interact programmatically with Ad Hoc views is to get and set any filters that are defined in the view. Note that unlike a report, the set of available filters in an Ad Hoc view may change if the view is modified on the server. Once an Ad Hoc view is rendered, your code should read the current filters and values before setting them.

As with reports and dashboards, filter values are called parameters and exposed through the params object. In the following example, the Country filter is known to be saved in the Ad Hoc view, so it can be set during initialization of the view, just before it is run and rendered.

You can use the metadata.inputParameters property of the data object to obtain the name and type of each current filter. The structure of the metadata.inputParameters is shown in Ad Hoc View Data Structure.

In the next example, the code requests the current filter values, processes them, and then uses the information about the current filters and values to set different values, in this case a different selection:

Accessing Ad Hoc View Hyperlinks

Hyperlinks, or simply links, are elements of the Ad Hoc view that your code can interact with. These are generally the contents of cells in a table, for example a field name in a column header or the value in a cell. As the user interacts with the Ad Hoc View, you can capture events on these elements such as clicks and then take action using the values of the element.

The elements that you can access are called outputParameters, and their structure is defined in the Ad Hoc View Data Structure. You can use the metadata.outputParameters property of the data object to obtain the name and type of each hyperlink.

Using the linkOptions properties, you can access the events on links, use the link values, and take other actions. The following example shows how to add a listener that displays link values in the console:

You can use the beforeRender property of the linkOptions to modify the appearance of elements in the Ad Hoc view. In the following example, every element is printed to the log and given the same color, but you could implement logic to highlight high or low values based on other thresholds.

The following structure defines what properties are available for values in an Ad Hoc table, also called an Ad Hoc hyperlink:

The following structure defines what properties are available for the table element of an Ad Hoc view, also called an Ad Hoc Table hyperlink. In particular, this structure gives your code access to the rows, columns, groups, and aggregation information about the Ad Hoc table:

The following example displays a lot of information about an Ad Hoc view in the console. You can use a generic script like this to examine your Ad Hoc views and determine which fields and data you can use to add interactive features.