Input Controls

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:

The range of possible values or the list of discrete values that are allowed.
The type of input, for example single-select or multi-select, and the widget to display the possible values, for example drop-down list or check boxes.
Display options such as labels and whether the value is required.
The name of the corresponding parameter in the JRXML.

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:

Boolean – Represented as a check box. These input controls return a java.lang.Boolean object to the report engine in response to the user’s selection. Boolean input controls return Boolean.TRUE or Boolean.FALSE as values, depending on whether the box is checked.
Single value – Represented as a free-form text box. You must specify a datatype, for example text or numerical value, and the user’s entry is validated against this datatype.
Single-select – Represented either as a drop-down list or a set of radio buttons. A single-select input control returns a single value.
Multi-select – Represented as a list of values (scrollable) or a set of check boxes. A multi-select input control returns a collection of values.

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.

Ad Hoc views based on Domains and Domain Topics always use locally defined input controls that are created automatically based on the chosen filters. They cannot refer to input controls stored in the repository, and you should not modify them. For more information, refer to the JasperReports Server User Guide.

Some input controls rely on queries to populate their options. These more complex controls are described in Query-based Input Controls.

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:

The parameter name in the input control must correspond to the name of the parameter in the report. No error occurs if there is a mismatch in the names, but at runtime, NULL is passed in as the value of the parameter instead of actual values.
The input control and its corresponding parameter must be of compatible datatypes (for example, both must be text types or date types). If there is a mismatch, the report fails and an exception is returned.

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:

1. Log on as an administrator.
2. Click View > Repository and expand the folder tree to locate the folder in which you want to create the input control. If you installed the sample data, the suggested folder is Input Data Types.
3. Right-click the folder and select Add Resource > Input Control from the context menu.

The Add Input Control page appears.

Add Input Control Page

4. Select the type of input control from the Type list.

In this example, select Single Value.

5. Enter the prompt to display to users explaining how to use the control.

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

6. In practice, the prompt text is often the same as the parameter, so the parameter name is automatically filled in from the prompt text. If you have used a different prompt, select the automatic name and replace it withe the exact name of the parameter associated with the control. Remember, the parameter name must be the same as in the reports that use this input control.

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

7. Select options for the control.

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

     Mandatory – Forces the end user to supply a value.
     Read-only – Displays the value of the parameter without allowing the end user to modify it.
     Visible – Makes the input control visible in the report options dialog.
8. Click Next.

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

     Boolean types do not require any further information.
     Single-value types require a datatype resource to characterize what the user may enter.
     Single-select and multi-select types based on static lists require a list of values resource.
     Single-select and multi-select types based on queries require a query resource.
9. In this single-value example, the Locate Datatype page appears. Choose the option to select a datatype from the repository and click Browse. From the repository dialog that appears, select /datatypes/TextGeneralDatatype, which is similar to the datatype we created in Datatypes.

If you choose to define a datatype, the wizard takes you through the same procedure as in section Datatypes. You can then define any datatype you need, but it is local to the input control and not reusable in other input controls.

Locate a Datatype for an Input Control

10. Click Next. The input control resource is created in the repository.
11. Locate the input control in the repository manager. Notice that the text of the prompt that you entered in step 5 is also used as the name for the resource.