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.

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:

Text
Number
Date
Date/time

To create a datatype 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 datatype. If you installed the sample data, the suggested folder is Input Data Types.
3. Right-click the folder and select Add Resource > Datatype from the context menu.

The Add Datatype page appears.

Add Datatype Page

4. Enter a name and optional description for the datatype. The resource ID is filled in automatically.
5. Select the type of the datatype, as well as information related to the type.

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

     Text – For text datatypes, you can specify a regular expression in the Pattern field. The expression is used to validate the text that the user submits. For instance, you could enter an expression that tests for email addresses.
     Number – With numerical datatypes, you can control the range of acceptable values by specifying minimum and maximum values and whether the specified values are themselves acceptable (Minimum is Strict/Maximum is Strict check boxes). If a Strict check box is selected, the specified value is not acceptable.

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 calender, click the calendar icon .
6. When you have defined the properties of your datatype, click Save. The datatype resource appears in the repository.

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:

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 list of values. If you installed the sample data, the suggested folder is Input Data Types.
3. Right-click the folder and select Add Resource > List of Values from the context menu.

The Add List of Values page appears.

Add List of Values Page

4. Enter a name and optional description for the datatype. The resource ID is filled in automatically.
5. Enter the name and value for each item in the list and click Add.

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.

6. When you have defined all values in the list, click Submit. The list of values resource appears in the repository.

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:

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 section 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 the input control in the repository manager. Notice that the text of the prompt that you entered in step 5

Locate a Datatype for an Input Control

10. Click Next. The input control resource is created in the repository.
11. is also used as the name for the resource.
Version: 
Feedback
randomness