Jump to content
  • 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
    Getting the Embed Code of 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 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 vz-icon-ChartSelector.png.9d26e0b9c8ef9edc2635c65b433c0efd.png 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:

    note-icon-ns_28x28.png.ffdb00a907ac902be80b327fa27e3a99.png

    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, your Visualize.js app should label the container so that your users know the content of the view may change.

    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:

    1. Log into JasperReports Server and browse the repository to find the Ad Hoc view you want to embed.
    2. Open the Ad Hoc view so that it is displayed in the server's Ad Hoc Editor.
    3. Click the js-Viewer-icon-EmbedCode.png.a95de4695525211f1a6081b20af64ce5.png
    4. The Ad Hoc Embed Code dialog shows you the Visualize.js code and a preview of the view as it is currently saved. Select Copy Code to copy the entire code block to your clipboard. You can also highlight selected parts of the code and use Ctrl-C (Command-C on Mac OS), for example if you want only the main function.

    The Embed Code of an Ad Hoc View

    js-AdHoc-GetEmbedCode.png.590cad78e0e3894c90d35ae7e3dff440.png

    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.

    5. Alternatively, select Open in JSFiddle to load the same code into a new Fiddle, an online JavaScript viewer and interactive editor. This lets you modify the JavaScript or HTML, and add CSS if desired, then see the results in real time.

    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 vz-icon-ChartSelector.png.31ff4857c74d083d18ce217ade52778c.png 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.

    note-icon-ns_28x28.png.8c2b7db7a36d7a787b5315d3d0b591a1.png

    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.


    User Feedback

    Recommended Comments

    There are no comments to display.



    Guest
    This is now closed for further comments

×
×
  • Create New...