Any JasperReport can be parameterized so that its generated output is a function of values given at runtime (query filters), or so that its layout is changed to accommodate different users (such as changing the title).

When writing JRXML, you can declare parameters and accommodate any runtime value that needs to be passed into the query executor, the rendering engine, or the calculation engine. However, the parameter information in a JRXML file does not provide everything JasperReports Server needs to build a complete user interface and prompt users for values. You must also define an input control resource that defines the following:

When a user runs the report, the server uses the above information to prompt the user to enter a value and validate the input. For example, consider a report that returns sales data for all of a company’s products; the user might input the name of a product to view by selecting a product name in a list.

JasperReports Server supports several types of input controls, each of which can map to certain types of parameters in the report’s JRXML. The input control also determines the kind of widget the user interacts with:

One advanced feature of single-select or multi-select input controls is that the values they present can be the result of a dynamic query. The query retrieves actual values from the data source before presenting them as choices to the user. These queries can contain parameters themselves, for example based on the logged-in user or the selection of a previous input control. Query parameters are described in the JasperReports Server Ultimate Guide.

Input controls rely on other resources in the repository, such as datatypes, static lists of values, or queries. You can manage these resources the same way you manage other resources; you can define them locally (available only to the input control) or reference them externally (reusing a resource in the repository). For more information, see Local Resources and External References.

Datatypes

Datatypes are resources that define the format of a single-value input control, for example text or numerical value. The datatype determines what users can enter in the text field so that it corresponds to the type of the parameter in the report. Furthermore, the datatype can restrict the value, for example setting a range for a number or date, or enforcing a pattern such as an email address in strings. This is all controlled through the datatype associated with the input control.

Datatypes can represent one of four types:

To create a datatype resource:

The Add Datatype page appears.

In this example, select Text as the type of our datatype; you have other options as well:

For instance, for a percent field, you might specify a minimum of 0 and a maximum of 100. If you do not want to accept 0 percent, you would check Minimum is Strict. If you want to accept 100 percent, you would clear Maximum is Strict.

•

Date and Date/Time – For these datatypes, there is a calendar widget in which you can select the desired minimum and maximum values and to make sure the configured date and date/time formats are used. To use the calendar, click the calendar icon

We have created a very basic datatype for any type of text input.

Lists of Values

List of values are resources that define a static list of values for single-select or multi-select input controls. For each selection in the list, the list defines a label presented to the user and the value passed to the report when it runs. Depending on the type of input control, the end user selects one or more of these labels as radio buttons, check boxes, or drop-down lists.

To create a list of values resource:

The Add List of Values page appears.

The name and value are both treated as strings. Users only see the label in an input control that uses the list, and the report only receives the value. To remove an item, click Remove beside its value.

Creating an Input Control

The input control resource determines how the input control functions and appears. As with other resources, input controls can be created locally as part of a JasperReport, in which case they cannot be seen outside of the JasperReport, or they can be created separately in the repository and referenced in multiple reports.

To use an input control in a report, the control must meet two conditions:

This section explains how to create an input control resource in the repository. To reference input controls in a JasperReport, see the JasperReports Server User Guide.

To create an input control resource:

The Add Input Control page appears.

In this example, select Single Value.

For this example, use the prompt Select the text for the report title.

For this example, the parameter name is title. The description is optional.

In this example, select Mandatory and Visible; you have other options as well:

Subsequent pages depend on what type of input control you chose above: