The inputControls function prepares and displays the input controls, also known as the filters, of a report. Your users interact with the controls to submit input when running reports.

As of JasperReports Server 6.4, Visualize.js supports much simpler input controls that are rendered directly by the server. All you need to do is specify the report resource and a container destination, and the server generates the UI interface that allows the user to select or enter values. You can then change the appearance of the input controls through CSS as necessary.

The previous mechanism of creating your own input control structures in JavaScript is still available to create custom input control interfaces. When creating custom input controls, your code can retrieve the input control data and generate your own input control UI interface.

This chapter contains the following sections:

Input Control Properties

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

Input Control Functions

The InputControls function exposes the following functions:

Embedding Input Controls

As of JasperReports Server 6.4, the display and use of input controls is much simpler in Visualize.js. Now, the server generates all of the UI widgets for all of the input controls of a report, and you specify the container where you want to embed them.

If you wish to generate your own UI widgets for each input control, as was required before version 6.4, it is still possible as described in Custom Input Controls. Previously written JavaScript that created custom input controls will still work.

In the simplest embedding case, you specify the URI of the report resource and a container. Only the input controls for the designated report are embedded in the container. The input controls appear on your page as standard selection boxes and drop-down selectors that the user can interact with and choose new values. The following example shows the HTML and corresponding JavaScript:

Of course, you can add styles to determine the shape and placement of your input controls container, as shown in the following CSS sample. If you wish to change the appearance of the embedded controls within the container, see Embedded Input Control Styles.

The following is a more realistic example that shows how to embed both the report and its input controls into separate containers on your page. The page also provides a button to run the report after the user has made changes to input controls:

The JavaScript embeds the report and the input controls in their respective containers, then it handles the button click to read the current values of the input controls (called parameters in this instance) and run the report using those values:

In most cases, your input controls will come from the same report that you are running. As in the example above, the URI for the report and the input controls is the same report resource. However, it is possible to use input controls from a different report, as long as the values from those input controls are compatible with the target report. Because input controls are ultimately used to create the query that fetches data for a report, the input controls of one report are compatible with another report if they are based on the same data source or Domain.

Handling Input Control Events

Because the input controls are separate from the report, events provide a way for you to make them work together or provide additional information. The inputControls instance generates a change event after the user interactively sets or selects a new input control value using the UI widgets.

The most common use is to listen for input control change events in order to run the associated report with the new input control values. In this example, the HTML sample has the report and input controls containers side by side in a row (styles or CSS not shown):

Then, the JavaScript embeds the report and the input controls in their respective containers and adds a listener for change events. If there is no error, the input control values (called params in this instance) are taken from the event and used to run the report again. This is a very common pattern when using input controls:

Another use for change events is to update other parts of your page based on the value of an input control. Such a mechanism could be used to update the title above a report, after the report is updated with a change of input controls.

In the following example, the change event triggers an update to text that displays the current value of an input control. The HTML has a placeholder for the text:

The CSS hides the text at first:

And the JavaScript catches the input control change event, then extracts the value of a given parameter to display it:

The change event can also be used to check whether the input controls entered by the user passed validation checks. Validation is defined on the server and ensures that values entered by the user are of the expected type or within a given range. The following example shows an event handler that checks the validation result:

Resetting Input Control Values

inputControls provides a function to reset all input control values to their default values. When the reset function is invoked, the display of the input controls refreshes to show their default values, that is, the initial state of the input controls before the user made any changes.

The following example has buttons to run the report and also to reset input controls. The HTML sample has the containers and buttons that are needed:

The corresponding JavaScript invokes the reset function when the button is clicked, and then it runs the report as well again:

Embedded Input Control Styles

With the embedded input controls, the server generates all of the UI widgets within your container. These UI widgets all have a standard look and feel that is controlled by CSS also generated by the server. If you wish to change the appearance of the generated input controls, you can add your own CSS with the proper class names.

In the following simple example, the HTML has a container and the JavaScript uses it for the input controls:

The following CSS will change the text color of the label of the boolean input control:

The following list shows the CSS base classes and secondary class names for the labels of each kind of input control embedded by the server. Use these in your CSS rules as shown in the example above to change the appearance of your labels.

If you want to change the style of other elements in the server's embedded input control UI, you can find the corresponding CSS classes and redefine them. To find the CSS classes, write the JavaScript to embed your input controls, then test the page in a browser. Use your browser's code inspector to look at each element of the generated input controls and locate the CSS rules that apply to it. The code inspector shows you the classes and often lets you modify values to preview the look and feel that you want to create.

Custom Input Controls

In the sections above, the UI widgets for embedded input controls are generated by the server and displayed in a given container. An alternate way to create input controls for your reports in visualize.js is to retrieve the input control values and analyze their structure so you can create your own UI widgets. These are called custom input controls.

Custom input controls require more JavaScript coding, and might be specific to a given report's input controls. In addition, handling cascading input controls is more complex and requires you to listen for change events that update the input control stucture. The following sections explain how to implement custom input controls.

Input Control Structure

The data() for InputControls is an array of InputControl objects, with the structure shown in this example:

Fetching Input Control Data

The data being output here has the input control structure shown in the previous section:

This example shows an alternate way of fetching input controls:

Creating Input Control Widgets

This example retrieves the input controls of a report and parses the structure to create drop-down menus of values for each control:

Cascading Input Controls

In order to implement cascading input controls, you must implement a change listener on the parent control and use it to trigger an update on the dependent control:

Associated HTML:

Reusing Input Control Instances

Input controls are meant to be dynamic and modified by users. By using the inputControls.params function, you can update the values of input controls and then update the corresponding report.

Reusing Input Control Data

You can store the data from the inputControls function and access the data() structure at a later time: