Adding Input Controls

Input controls are graphical widgets the server displays with the report. Input controls perform the following functions:

Prompt the user for input
Validate the format of the input
Pass the input to the report

Based on the input, the server modifies the WHERE filter clauses in SQL parametrized queries.

Input controls correspond to the parameters defined in JRXML reports, such as $P{name}. The server maps the value that the user enters for the input control to the parameter of the same name. If you define an input control in the JasperReport and the server can’t find a parameter by the same name in the JRXML, the input control doesn’t function when the report runs.

The JRXML can define a default value for the input control. To prevent users from changing the default, you can make the input control read-only or invisible.

When you create an input control, you define, or use a predefined, datatype, for user entries. Datatypes define the expected input (numbers, text, date, or date/time) and can include range restrictions that the server enforces. The server uses the datatype to classify and validate the data.

To define a datatype, set properties on the Set the Datatype Kind and Properties page. Properties differ for other datatypes that appear on the Set the Datatype Kind and Properties page.

Type

The classification of the data, which can be Text, Number, Date, or Date-Time.

Name

The name of the datatype.

Resource ID

The unique ID of the datatype that you cannot edit.

Description

Any additional information you want to provide about the datatype.

Pattern

A regular expression that restricts the possible values of the field. Appears when the Text type.

Minimum value

The lowest permitted value for the field.

Maximum value

The highest permitted value for the field.

Minimum Is Strict

If checked, the maximum value itself is not permitted; only values less than the maximum value are permitted.

Maximum Is Strict

If checked, the minimum value itself is not permitted; only values greater than the minimum value are permitted.

You choose one of these widget types for the input control:

Boolean – A check box widget for entering a yes/no value.
Single value – A text, number, date, or date/time widget. Input can be constrained to a minimum value, maximum value, or both. Text input can also be constrained by a matching pattern. A text box widget for entering a value, or a calendar for entering date and date/time.
Multiple values – One of the following widgets that present a static list of values, or a dynamic list of values returned by a separate query, to the user.
     Drop-down list to select a single value
     Radio buttons to select a single value
     Multi-select list to select multiple values
     Check boxes to select multiple values

After determining the list of values to be presented to the user, choose the widget.

The query in the SalesByMonth.jrxml file has several input control parameters, one for each different type of input control. These procedures show you how to add each type to the report unit.

Adding a Text Input Control

The simplest input control is a text box. In this example, the datatype for the input value is a number; the server verifies that the user enters a number into the text box.

To add a text input control to the complex report example:

1. After completing steps in Uploading Undetected File Resources, click Controls & Resources in the JasperReport wizard.
2. On the Controls & Resources page, click Add Input Control.

The Locate Input Control page appears.

3. Select Define an Input Control in the next step.
4. Click Next.
5. On the Create Input Control page, accept the default type of input from the Type drop-down: Single Value.
6. Enter the other properties for the input control:

The name is referenced in the main JRXML file, so enter it exactly as shown.

     Prompt Text – The label that the user sees next to the widget for this input: Text Input Control
     Parameter Name – The name of the parameter in the report that receives the user value: TextInput
     Description – An optional description that appears only within the report wizard: leave blank in this example.
     Mandatory, Read-only, Visible – A setting that affects how the input control is displayed: check only Visible.

Properties of the Text Input Control

To reuse an input control, add it to the repository independent of any report using Add Resource > Input Control. Before using the input control in a report, check that the parameter name in the JRXML matches the name in the Create Input Control page; otherwise, the server can’t run the report.

7. Click Next.
8. In Locate Datatypes, select Define a DataType in the next step, and click Next:

Instead of defining a datatype, you can use one in the repository if its type and range are compatible with your input control.

9. In Set the Datatype Kind and Properties, enter the properties for the datatype:
a. In Type, select the format of the data that the user may enter. Select Number from the drop-down.

The number format allows users to enter integers and decimals.

b. Enter a name – Integer Type
c. Enter a resource ID – Integer_Type

The name and resource ID are required, but only visible when defining the input control.

Integer Datatype Properties

d. Leave these properties blank in this example:
Description – An optional description that appears only within the report wizard.
Minimum value – The lower bound of the value the user may enter.
Maximum value – The upper bound of the value the user may enter.
Minimum is strict – Means the minimum value itself is not allowed.
Maximum is strict – Means the maximum value itself is not allowed.
10. Click Save.

The Controls & Resources page now lists the Text Input Control.

Text Input Control in Input Controls List

Adding a Simple Check Box Input Control

A check box input control accepts true/false (boolean) input from the user.

To add a simple check box input control to the complex report example:

1. Continuing with the previous example, on the Controls & Resources page, click Add Input Control.
2. On the Locate Input Control page, click Define an Input Control in the next step.
3. Click Next.
4. On the Create Input Control page, select the type of input from the Type drop-down: Boolean.
5. Enter the other properties for the input control.
     Prompt Text – Check Box Input Control
     Parameter Name – CheckboxInput

Enter the parameter name exactly as shown because the main JRXML file references this name.

     Description – Leave blank in this example.
     Mandatory, Read-only, Visible – Check only visible.
6. Click Submit.

The Controls & Resources page appears with the new check box input control.

Adding a Drop-Down Input Control

The drop-down input control, also called a list input control, gives the user a pre-determined list of choices. As a report designer, you make these decisions about a drop-down input control:

To present a single-select or multi-select list to the user
To present a single choice as a drop-down list or a set of radio buttons
To present a multi-select control as a multi-select list or a set of check boxes

Radio buttons and check boxes usually work well for five or fewer choices. This example shows how to create an input control that presents three choices in a drop-down list. A list of values defines these choices. You can create a new list of values, dedicated to this input control, or you can use a list of values in the repository.

To add a drop-down input control to the complex report example:

1. Continuing with the previous example, on the Controls & Resources page, click Add Input Control.
2. On the Locate Input Control page, click Define an Input Control in the next step.
3. Click Next.
4. On the Create Input Control page, select the type of input from the Type drop-down: Single-select List of Values.
5. Enter the other properties for the input control:
     Prompt Text – List Input Control
     Parameter Name – ListInput

Enter the parameter name exactly as shown because the main JRXML file references this name.

     Description – Leave blank in this example.
     Mandatory, Read-only, Visible – Check only visible.
6. Click Next.
7. On the Locate List of Values page, select Define a list of values in the next step.

Instead of defining a list of values, you can use one in the repository if its values are compatible with the parameter defined in the JRXML report.

8. Click Next.
9. On the Add List of Values page, enter a name, resource ID, and optional description for the list of values. These properties aren’t visible outside of the input control. Enter these values:
     Name – list type
     Resource ID – list_type
     Description – Leave blank in this example.
10. In the Name Value panel, enter names and values to present as choices to the user:
     Enter unique names.

The server requires unique names to distinguish which item the user chose.

     Enter values of the type that match the parameter definition in the JRXML report.

After entering a name and value, click Add. If you make a mistake, click Remove.

For this example, enter:

     Name First Item with value 1.
     Name Second Item with value 2.
     Name Third Item with value 3.

Definition of the List of Values

11. Click Submit.

The Controls & Resources page appears with the new List Input control.

Adding a Date Input Control

This example of adding a date input control uses a datatype that already exists in the sample data in the repository.

To add a date input control to the complex report example:

1. On the Controls & Resources page, click Add Input Control.
2. On the Locate Input Control page, select Define an Input Control in the next step, then click Next.
3. On the Create Input Control page, select the type of input from the Type drop-down: Single-Value
4. Enter the other properties for the input control:
     Prompt Text – Date Input Control
     Parameter Name – DateInput

Enter the parameter name exactly as shown because the main JRXML file references this name.

     Description – Leave blank in this example.
     Mandatory, Read-only, Visible – Check only the visible setting.
5. Click Next.
6. On the Locate Datatypes page, select Select a Datatype from the Repository.
7. Click Browse.
8. In Select Resource from Repository, expand Input Data Types, and select the Date Datatype.
9. Click Select.

The Locate DataTypes page shows the location of this datatype in the repository, /datatypes/DateDatatype.

10. Click Next.

The Controls & Resources page appears with the new Date Input Control.

Adding a Query-Based Input Control

A query-based input control presents a dynamically-created list of choices to the user. The server performs a query whose results are used to create the list of choices. You must perform the following tasks:

Configure the query.
Designate how to display the results in the input control.
Specify the value to pass as the corresponding parameter.

To add a query-based input control to the complex report example:

1. On the Controls & Resources page, click Add Input Control.
2. On the Locate Input Control page, select Define an Input Control in the next step.
3. Click Next.
4. On the Create Input Control page, select the type of input from the Type drop-down: Single-select Query.
5. Enter the naming properties for the input control:
     Prompt Text – Query Input Control
     Parameter Name – QueryInput

Enter the parameter name exactly as shown because the main JRXML file references this name.

     Description – Leave blank in this example.
     Mandatory, Read-only, Visible – Use the default settings in this example.
6. Click Next.

The Locate Query page appears. Options are:

     To locate a reusable query in the repository
     To define a new query dedicated to this input control
7. For this example, select Define a Query in the next step.
8. Click Next.
9. On the Name the Query page, enter naming properties for the new query. For this example, enter testQuery in both the Name and Resource ID fields.

Entering a Query Name

10. Click Next.

The Link a Data Source to the Report page appears. Options are:

     To use the same data source for the input control as you use for the report
     To define a new data source, dedicated to this input control
     To select a reusable data source from the repository
11. For this example, select Do not link a data source to use the same data source for the input control as you use for the report. You will select the data source for the report in Selecting a Data Source for Running the Complex Report.

Data Source Link for the Query Input Control

12. Click Next.
13. On the Define the Query page, select SQL from the Query Language drop-down.
14. Enter this Query String to retrieve the labels and values to be displayed for this input control:

SELECT user_name, first_name, last_name FROM users

Query String Definition

15. Click Save.
16. For each row in the results of the query, the server presents a single value, such as Sarah Smith, in the input type widget (drop-down, radio buttons, multi-choice, check boxes). On the Query Information page, name the database columns to comprise the input value presented to the user. The column names must match those in the SELECT clause of the query string exactly:
a. In the Value Column, enter the user_name.
b. In the Visible Column, enter first_name.
c. Click Add.
d. In the Visible Column, enter last_name.
e. Click Add.

For each visible column that you want to display as a choice, enter the name, then click Add. If you make a mistake, click Remove.

17. Click Submit.

The Controls & Resources page displays all the resources, including the new input controls. Input Controls and Resources shows these resources.

Next, set the input control options, described in the next section.

Setting the Input Control Options

In this procedure, you set the display mode in Input Control Options at the bottom of the Controls & Resources page. These options only appear after you add an input control to the report. Input Controls and Resources shows these options.

To configure the appearance of the input controls for the complex report example::

1. Select Pop-up window.

You can also select Separate page to display the input controls in a separate browser window, Top of page to display them above the report, or In page to display them on the side of the report.

2. Check Always prompt when you want the server to display the Input Controls dialog to prompt the user when the report runs.

The definition of input controls in this example specified Visible and not Mandatory. When input controls aren’t mandatory and Always prompt isn’t checked on the Controls & Resources page, the user must click the Options button in the report viewer to change input controls; otherwise, the report runs with default input controls

3. Leave Optional JSP Location blank for this example.

You can use the Optional JSP Location option to specify the path to a JSP file that affects the appearance of the input controls.

Input Controls and Resources

Select the data source to finish the complex report example.

Feedback