Jump to content
Changes to the Jaspersoft community edition download ×
  • This documentation is an older version of JasperReports Server Visualize.js Guide. View the latest documentation.

    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
    Ad Hoc View Functions
    Ad Hoc View Data Structure
    Rendering an Ad Hoc View
    Setting the Visualization Type
    Setting Ad Hoc View Filters
    Accessing Ad Hoc View Hyperlinks

    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 and Ad Hoc View is rendered in Visualize.js, but there is UI widget that allows users to switch between these visualizations. For example, if the Ad Hoc view appears as a table, the user can switch the view to a crosstab or pie chart.


    Unlike a report that is meant to have a static layout and look the same every time it runs, an Ad Hoc view is more of a data exploration tool that users edit often and may save in an intermediate state. In order to have consistent results, you should design and save specific Ad Hoc views that are relevant to your visualize.js user, and not allow other users on the server to modify them.

    Alternatively, you can use the dynamic nature of Ad Hoc views, for example to explicitly display the latest data visualization that has been designed and saved on the server. In this case, Visualize.js is being used to share the Ad Hoc views that are regularly updated and saved by other users on the server.

    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.

    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 same data can usually be displayed in tables, crosstabs, and charts, but it often appears slightly differently. Different charts require different data series, so not all chart types may be compatible with the data that is currently selected in the Ad Hoc view. Before changing the visualization type, you should make sure it is compatible with your Ad Hoc view.

    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.

    Open topic with navigation

    User Feedback

    Recommended Comments

    There are no comments to display.

    This is now closed for further comments

  • Create New...