If you log in as a user, you can upload a report unit to the server, but this example requires an administrator login to access the image resources.
This section includes an example of how to add a report unit with all these resources:
• SalesByMonth.jrxml file – the main JRXML
• SalesByMonthDetail.jrxml file – a subreport
• sales.properties – an English resource bundle file
• scriptlet.jar – a scriptlet class JAR file
• JR Logo – an image in the repository
• JServer JNDI data source – a data source file in the repository
These resources are part of the sample data installed with the server. To complete this example and run the report without server errors, you need access to these resources.
The example also guides you through defining every type of input control:
• Text
• Check box
• Drop-down
• Date
• Query
If you’re not interested in creating all types of input controls, but want to work through part of the example, delete parameters for the input controls you don’t create before you run the report. For more information, see See "To remove unwanted parameters from the sample report design:".
The complex report you create in this example is almost exactly like the SalesByMonth report in the Reports Samples folder of the repository.
To upload the main JRXML and suggested resource files for the complex report unit:
1. Log into JasperReports Server as administrator and select View Repository.
|
|
If you log in as a user, you can upload a report unit to the server, but this example requires an administrator login to access the image resources. |
2. Navigate to a folder to add the report. For example, navigate to Organization Reports Samples.
3. Right-click the Samples folder and select Add Resource JasperReport from the context menu.
|
|
Add Resource only appears on the menu if your user account has write privilege to the folder. |
The Set Up the Report page appears.
4. On the Set Up the Report page, enter these properties:
• Name – New Complex Report
• Resource ID – New_Complex_Report
• Description – This is a complex report
5. Select Upload a Local File.
6. Click Browse to locate the file <js-install>/samples/reports/SalesByMonth.jrxml.
7. Click Controls & Resources.
On the Controls & Resources page, the list of suggested resources appears:
• A sub-report (the SalesByMonthDetail.jrxml file)
• A logo image
See "Suggested Resources for the Complex Report" shows the list of suggested resources.
|
|
8. On the Controls & Resources page, upload the sub-report:
Click Add Now in the same row as SalesByMonthDetail.
The Locate File Resource page appears.
| a. | Select Upload a Local File. |
| b. | Click Browse and locate the file <js-install>/samples/reports/SalesByMonthDetail.jrxml. Select SalesByMonthDetail.jrxml. |
The path to SalesByMonthDetail.jrxml appears in the Upload a Local File field.
| c. | On the Locate File Resource page, click Next. |
| d. | On the Add a Report Resource page, click Next to accept the default report resource name and resource ID. |
9. On the Controls & Resources page, upload the logo image resource:
In the same row as Logo, click Add Now.
The Locate File Resource page appears.
| e. | On the Locate File Resource page, click Select a resource from the Repository. |
| f. | Click Browse to locate the file /Images/JR Logo and select JR Logo. |
| g. | Click Next. |
The Add a Report Resource page appears.
| h. | On the Add a Report Resource page, click Next to accept the default name, resource ID, and description: Logo. |
The second suggested resource is added.
The JasperReport wizard can’t detect every type of resource referenced in the main JRXML. You need to know the names of these resources and add them to the report; otherwise, the server can’t validate the report. This document provides you with the names of these resources, but if you wanted to discover these names, use the JasperReports Server Plug-in to open the JRXML in iReport and examine its parameters and properties. For more information about the JasperReports Server Plug-in, see Accessing Reports and Domains from iReport.
These are the undetected resources in the SalesByMonth.jrxml:
• A scriptlet JAR – The scriptlet writes the message, “I’m a scriptlet in a jar,” to the last page of the report output.
• An English language resource bundle.
• The optional Romanian language resource bundle.
If you’re interested in working with a multi-lingual report, add the Romanian resource bundle. The Romanian resource bundle is part of the sample data installed with the server.
On the Controls & Resources page, upload the undetected resources to the server using exactly the same name for the resource ID as iReport uses.
To upload the undetected file resources for the complex report example:
1. Add and upload the scriptlet JAR file:
On the Controls & Resources page, click Add Resource.
| i. | On the Locate File Resource page, select Upload a Local File, and click Browse to locate the <js-install>/samples/jars/scriptlet.jar file. Select scriptlet.jar. |
The path to the file appears in the Upload a Local file field.
| j. | Click Next. |
The Add a Report Resource page appears. Scriptlet JAR Resource Properties shows that the file name scriptlet.jar appears, indicating that the server successfully loaded and automatically detected the JAR.
| k. | Enter the following information; the Resource ID is referenced in the main JRXML file, so do not change it: |
Name – Scriptlet
Resource ID– Scriptlet
Description – Scriptlet JAR for complex report
Scriptlet JAR Resource Properties shows these values entered on the Add a Report Resource page.
|
|
2. Click Next.
3. Add and upload the English resource bundle:
On the Controls & Resources page, click Add Resource again.
The Locate File Resource page appears.
| l. | Select Upload a Local File, click Browse to locate the file <js-install>/samples/resource_bundles/sales.properties. Select the file. |
The path to the resource bundle appears in the Upload a Local file field.
| m. | In Locate File Resource, click Next. |
The Add a Report Resource page indicates that the file was successfully loaded and automatically detected as a resource bundle.
| n. | Enter the following information: |
Name – sales.properties
Resource ID – sales.properties
Description – Default English resource bundle
|
|
4. Click Next.
5. Add and upload the Romanian Resource bundle:
On the Controls & Resources page, click Add Resource again.
| o. | Select Upload a Local File and click Browse to locate this file: |
<js-install>/samples/resource_bundles/sales_ro.properties
| p. | In Locate File Resource, click Next. |
The Add a Report Resource page shows that uploading the file was successful. The server recognized the type (resource bundle) and name (sales_ro.properties) of the selected resource.
| q. | Enter the following information: |
Name – sales_ro.properties
Resource ID – sales_ro.properties
|
|
Description – Romanian resource bundle
| r. | Click Next. |
Controls & Resources lists all the files:
|
|
|
List of Detected and Undetected File Resources |
If you want to upload a different file for a named resource, click its resource ID in the Resources list and locate the new file or repository object. You can also change the name and description of the resource, but not its resource ID. If there’s a mistake in a resource ID:
• Locate the ID in the list of resources on the Controls & Resources page, and click Remove.
• Re-add the resource, entering the correct resource ID.
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.
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 See "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:
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. |
| s. | Enter a name – Integer Type |
| t. | Enter a resource ID – Integer_Type |
The name and resource ID are required, but only visible when defining the input control.
|
|
|
Integer Datatype Properties |
| u. | Skip these properties: |
Description – An optional description that appears only within the report wizard: leave blank in this example.
Minimum value – The lower bound of the value the user may enter: leave blank in this example.
Maximum value – The upper bound of the value the user may enter: leave blank in this example.
Minimum is strict – Means the minimum value itself is not allowed: leave unchecked in this example.
Maximum is strict – Means the maximum value itself is not allowed: leave unchecked in this example.
10. Click Save.
The Controls & Resources page now lists the Text Input Control.
|
|
|
Text Input Control in Input Controls List |
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.
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.
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.
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.
|
|
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:
In the Value Column, enter the user_name.
| v. | In the Visible Column, enter first_name. |
| w. | Click Add. |
| x. | In the Visible Column, enter last_name. |
| y. | 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.
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.
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.
|
|
Select the data source to finish the complex report example.
You select a data source to retrieve data for the report and the query input control; otherwise, the report and the list of users in the query input control will be blank.
To select a data source and run the complex report:
1. On the Controls & Resources page of the JasperReport wizard, select Data Source.
2. On the Locate Data Source page, choose Select data source from repository.
3. Click Browse, and choose Organization Data Sources JServerJNDI Data Source. Click the Select button.
4. On Link a Data Source to the Report, click Submit.
5. On the Locate Query Page, click Submit again to save the complex report.
Skip the Query and Customization pages of the JasperReport wizard to use the default settings on those pages.
The server validates the report and a message appears indicating that the report was added to the repository. The New Complex Report appears in the repository.
6. In the Repository, click the name New Complex Report to run and view the report.
Input controls appear.
7. Enter these input values, as shown in See "Input Controls Dialog for the New Complex Report":
Text Input Control: myText
| z. | Check Box Input Control: Check the checkbox. |
| aa. | List Input Control: Select Third Item. |
| ab. | Date Input Control: Click  , select December 31, 2010. |
| ac. | Query Input Control: Select Sarah Smith from the drop-down. |
|
|
8. Click OK or Apply to run the report with the selected input, including the incorrect non-numerical input for the Text Input Control.
The server enforces the proper format defined for each input control. You defined the Text Input Control as a numeric type, so it accepts only valid numbers, as indicated by the message to specify a valid float number, as shown in See "Invalid Input Message".
|
|
9. In Text Input Control, enter 3 and click OK or Apply again.
The sample report includes a header that displays the value of each parameter received from the input controls. Values and labels for the input controls appear in the language specified by the active resource bundle, in this case English.
|
|
In the Report Viewer, you can open the Input Controls dialog at any time by clicking the Options button. Click OK to run the report using the chosen values and close the Input Controls dialog; click Apply to run the report using the chosen values, but keep the Input Controls open for choosing other values and re-running the report.
|
|
If you get an error when you run the report, open it for editing as described in Editing JRXML Report Units. Review your settings. If you can’t find the problem, edit the SalesByMonth sample report (in the repository at /reports/samples) and compare its settings to your report. |
To see the message written by the scriptlet JAR on the last page of the report, click 
in the Report Viewer.
