Adding Report Units from JRXML Files

This section presents two examples, one simple and one complex, that illustrate many aspects of uploading JRXML files to create a report unit. Each example is split into several sub-sections, one for each different kind of element in the report unit.

Each sub-section can be referenced individually when adding your own reports with different combinations of elements.

Simple Report Example

To create the simple report in this example, you need access to the following sample data installed with the server:

•    <js-install>/samples/reports/AllAccounts.jrxml

•    <js-install>/samples/image/logo.jpg files

The simple report has file resources but no input controls. The sample report resources consist of two images. Later in this chapter, a complex report example covers other types of resources:

•    Fonts

•    Resource bundles that adapt a report to other locales

•    Scriptlets

The report includes a custom query that demonstrates how a report unit can modify the JRXML report it is based upon.

Uploading the Main JRXML

To upload a report unit to the server, first set up a name in the repository. Next, upload the main JRXML file that references all other elements.

The following procedure describes how to upload a main JRXML.

To upload the main JRXML for the simple report example:

1.

Log in to the server as administrator and select View > Repository:

In this example, go to Organization > Reports > Samples.

The Set Up the Report page of the JasperReport wizard appears:

•     Name – Display name of the report: New Simple Report

•     Resource ID– Permanent designation of the report object in the repository: New_Simple_Report

•     Description – Optional description displayed in the repository: This is a simple example

The server uploads the main JRXML file and displays the list of suggested resources:

Review the hyperlinked names of images:

•     Logolink

•     AllAccounts_Res2

You must upload the suggested file resources to the report. The report cannot be validated by the server if the resources are not added.

Uploading Suggested File Resources

When the server uploads the main JRXML file, it creates a list of the resources that are referenced in the JRXML. On the Controls & Resources page of the JasperReport wizard, you can add resources and input controls to the report unit. If the report you upload does not reference any file resources, you can skip to section Defining the Data Source.

To upload the suggested file resources for the simple report example:

The Locate File Resource page appears.

The Add a Report Resource page appears:

The server uploads the file. The Add a Report Resource page appears, showing the properties for the file resource:

The JasperReport wizard returns to the Resources List page that shows the addition of all resources referenced in the main JRXML:

Defining the Data Source

Data sources belong to the report engine, in this case JasperReports Server, and cannot be defined in the main JRXML. Therefore, in the process of creating a report unit, you must define a data source in the server that the report can use. From the Data Source page, you select a data source in the repository or create a new data source on-the-fly.

To define the data source for the simple report example:

The three choices for the data source are:

•     Do not link a data source – Select or define the data source at a later time. You see an error if you run the report in this state.

•     Click here to create a new data source – Define a new data source that is available only within the report unit.

•     Select data source from repository – Select an existing data source from the repository.

Defining the Query

The query in the report unit determines what data is retrieved from a data source. You can use an existing query or define a new one. You can create multiple reports that look the same but contain different data by defining different queries for the same JRXML file. The simple report example defines a custom query that displays accounts from a single country.

To define a custom query for the simple report example:

The three choices for the query are:

•     Do not link a Query – Uses the query, if there is one, defined within the main JRXML. If there is no query in the main JRXML, you see an error when trying to run the report.

•     Click here to create a new Query – Lets you define a new query that is available only within the report unit.

•     Select a Query from the Repository – Select an existing query object previously defined and stored in the repository.

The AllAccounts.jrxml file uploaded in section Uploading the Main JRXML already contains a query. This example overrides the existing query by defining a new query in the report unit.

The Name the Query page appears where you can enter the properties for the local query. The locally defined query and its properties are visible only within the report unit.

•     Name – CanadaAccounts

•     Resource ID – CanadaAccounts

•     Description – Query for New Simple Report in User Guide

The Link a Data Source to the Query page appears.

When specifying a local query for the report unit, you can select a data source that overrides the one associated with the report unit. You can select a query from the repository or define a new one. Selecting None uses the default data source that you selected in section Defining the Data Source.

The Define the Query page appears.

SELECT * FROM accounts WHERE billing_address_country = "Canada" ORDER BY billing_address_city

The Customization page appears. No customization is required.

Saving the New Report Unit

To submit a new report unit to the repository, click Submit on any page, from the Set Up page to the Customization page, skipping pages you do not need. When you click Submit, the server validates all the elements of the report unit that you entered, and saves the new report unit in the repository with the type Report. It’s always a good idea to test the report and review the output.

After clicking Submit, a message appears at the top of the repository page, indicating that the report was successfully saved. The report appears in the repository with the properties you specified on the Set Up page:

If the report was not validated and saved, you may be prompted to review your entries.

To run the report and view the output, click its name, New Simple Report. As shown in the figure below, all the accounts listed are in Canada.

On the last page of the report are the two logo images that you added as file resources:

For more information about running reports, see section Running a Simple Report.

Complex Report Example

This section describes the creation of a more complex report than the one described in the previous section. The complex report includes a full set of input controls, a scriptlet class JAR file, and resource bundles. To create the report, you must have access to all its resources, including the SalesByMonth.jrxml file and the SalesByMonthDetail.jrxml file (the sub-report). The complex report also uses a datatype and an image in the repository that are part of the sample data installed with the server.

The example uses these resources to create a report that behaves just like the SalesByMonth report in the Reports > Samples folder of the repository. The beginning of the complex example resembles the beginning of the simple example. For detailed instructions, see sections Uploading the Main JRXML and Uploading Suggested File Resources.

The following procedure assumes you are familiar with how to add a resource as described in the previous section.

To upload the main JRXML and suggested resource files for the complex report example:

For example, go to Organization > Reports > Samples.

•     Name – New Complex Report

•     Resource ID– New_Complex_Report

•     Description – This is a complex example

On the Controls & Resources page, the list of suggested resources indicates that you need a sub-report (the SalesByMonthDetail.jrxml file) and a logo image.

Click Add Now in the same row as SalesByMonthDetail.

Click Add Now in the same row as Logo.

The Add a Report Resource page is displayed.

The second suggested resource is added.

Uploading Undetected File Resources

The JasperReport wizard cannot detect every type of resource referenced in the main JRXML. You must be aware of other file resources needed in the report and upload them from the Controls & Resources page. In addition, you must know how they are referenced and give the file resources exactly the same name so they can be associated.

The complex report example needs a scriptlet JAR and two language bundles (Java properties files).

To upload the undetected file resources for the complex report example:

On the Controls & Resources page, click Add Resource.

Name – Scriptlet

Resource ID– Scriptlet

Description – Scriptlet JAR for complex example

Adding the Scriptlet JAR as a Report Resource shows these values entered on the Add a Report Resource page:

On the Controls & Resources page, click Add Resource again.

Name – sales.properties

Resource ID – sales.properties

Description – Default English resource bundle

On the Controls & Resources page, click Add Resource again.

The Add a Report Resource page indicates that the file was successfully loaded and automatically detected as a resource bundle (a Java properties file).

Name – sales_ro.properties

Resource ID – sales_ro.properties

Description – Romanian resource bundle

Controls & Resources lists all the files:

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 is a mistake in a resource ID, remove the resource and re-add it. To remove the file resource, locate the ID in the list of resources on Controls & Resources, and click Remove at the end of the row.

Adding Input Controls

Input controls are standard graphical widgets that take user input in a pre-determined format and pass it into the report. When a report is designed and configured for input controls, a user can modify run time selections, such as the WHERE filter clauses in SQL parametrized queries. The server displays the input control widgets with the report and regenerates the report when the user changes the input values.

Input controls correspond to the parameters defined in JRXML reports, such as $P{name}. You must define an input control for every parameter in the report. The server maps the value that the user enters for the input control to the parameter of the same name. The server returns an error if there is no parameter name that matches the name of an input control.

Input controls are complex objects that can be configured in many ways. However, you must create the input controls so that they return the exact type, range, and number of values expected by the report. In general, you must define a datatype for user entries, such as number or text, that the input control accepts. You also must specify that the input control use one of the following widget types:

•    Boolean – A yes/no value determined by a check box.

•    Single value – A text, number, date, or date/time, optionally constrained by a minimum value, maximum value, or both. Text input can also be constrained by a matching pattern. Single values provide a text box for the user to enter a value, but date and date/time also provide a calendar icon.

•    Choice of multiple values – The choices offered to the user can either be a static list of values that you specify or a dynamic list of values returned by a separate query. After determining the list of values, choose the widget type:

•     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.

All choices are presented and selected by their text representation, but the report may process the input value, for example, to interpret a string of digits as a number.

The query in the SalesByMonth.jrxml file of the complex example has several parameters that require input controls. Each input control is a different type to demonstrate how each can be added to the report unit. Input controls and their datatypes can be locally defined or reused from the repository. In the example, you define most components locally to understand how to use the JasperReport wizard.

Adding a Text Input Control

The simplest input control is a text box into which the user types a value. In this example, the datatype for the value is a number, meaning that the server verifies that the user input is numeric.

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

The Locate Input Control page appears:

The name is referenced in the main JRXML file, so you must 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.

Select Number from the drop-down.

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

•     Description – An optional description that appears only within the report wizard: leave blank in this example

•     Type – Determines the format of the data that the user may enter: Number

•     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

The Controls & Resources page appears with Text Input Control in the list of resources:

Adding a Simple Check Box Input Control

A simple check box provides a true/false (boolean) input that can be used to conditionalize some part of the report.

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

4.

On the Create Input Control page, select the type of input from the Type drop-down: Boolean.

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

•     Prompt Text – Check Box Input Control

•     Parameter Name – CheckboxInput

•     Description – Leave blank in this example.

•     Mandatory, Read-only, Visible – Check only visible.

See "Entering the Properties of the Check Box Input Control" shows the Create Input Control page after you enter these properties:

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

Adding a Drop-Down Input Control

The drop-down input control gives the user a pre-determined list of choices to select from. The design of the report determines whether you must create a single-select or multi-select list. When creating the input controls you can select whether to present a single choice as a drop down list or a set of radio buttons. Multi-select controls can be either a multi-select list or a set of check boxes. Radio buttons and check boxes are usually appropriate if there are few choices, usually five or less. This example has only three pre-determined choices but uses a drop-down list.

The predetermined choices are defined in a list of values object. You can either create one locally for the input control or reuse one that you created beforehand and stored in the repository.

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

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

•     Prompt Text – List Input Control

•     Parameter Name – ListInput

•     Description – Leave blank in this example.

•     Mandatory, Read-only, Visible – Check only visible.

See "Entering the Properties of the List Input Control" shows the Create Input Control page after you enter these properties:

For this example, select Define a list of values in the next step:

•     Name – list_type

•     Resource ID – list_type

•     Description – Leave blank in this example

For each value that you want to add to the list, enter its name and value, then click Add. If you make a mistake, click Remove. The name for every item must be unique. For this example, enter:

•     Name First Item with value 1.

•     Name Second Item with value 2.

•     Name Third Item with value 3.

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:

4.

On the Create Input Control page, select the type of input from the Type drop-down: Single-Value.

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

•     Prompt Text – Date Input Control

•     Parameter Name – DateInput

•     Description – Leave blank in this example.

•     Mandatory, Read-only, Visible – Check only the visible setting.

See "Properties of the Date Input Control" shows the Create Input Control page after you enter these properties:

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

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

Adding a Query-Based Input Control

The last example of an input control shows how the choices available to the user can be dynamically based on the data. 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:

4.

On the Create Input Control page, select the type of input from the Type drop-down: Single-select Query.

•     Prompt Text – Query Input Control

•     Parameter Name – QueryInput

•     Description – Leave blank in this example.

•     Mandatory, Read-only, Visible – Use the default settings in this example.

See "Entering the Properties of the Query Input Control" shows the Create Input Control page after you enter these properties:

For a query-based input control, you can use a query stored in the repository. This example defines a query that is local to the input control with its own properties and query string.

SELECT user_name, first_name, last_name FROM users

In the Value Column, enter the user_name.

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.

The Controls & Resources page displays all the resources, including the new input controls.

Setting the Input Control Options

Set the display mode in Input Control Options to complete the configuration of input controls. The options appear at the bottom of the Controls & Resources page only after you define one or more input controls. Leave Optional JSP location blank for this example. You can use the JSP Location to specify the path to a JSP file that changes the appearance of the input controls.

To configure the display mode of input controls in the complex report example:

Proceed to section Completing the Complex Report Example to set the data source and finish the complex report example.

About Cascading Input Controls

JRXML-based reports can include input controls whose values are determined by a user's selection in other input controls. For example, consider a report that has input controls for country, state, and city. By leveraging the cascading functionality, the options in the State input control are determined by the value selected in the Country input control. When the user selects a state, the list of values includes only those in the selected state. These cascading input controls use queries to determine the values to display in each input control field.

The goal is to use input controls as parameters for a query that populates another input control. To do so, the input control's query must use a special syntax to reference a parameter name. The syntax is identical to the $P{parameterName} syntax used in queries for JasperReports.

Consider an example report that returns data identified by country and city. It includes input controls called COUNTRY and CITY. The query used by the CITY input control retrieves city names from a table called accounts based on the value selected by the COUNTRY input control, for example:

When the user selects a country from the COUNTRY input control, the value selected is used by the query of the CITY input control; the CITY input control is refreshed to show the result. Note that there are other ways to use a parameter in a query.

For an example of running a report with cascading input controls, see section Cascading Input Controls.

Completing the Complex Report Example

To finish the complex report example and validate it:

You can skip pages of the JasperReports wizard, such as Query, 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 report appears in the repository:

The server enforces the proper format defined for each input control. The Text Input Control is defined as a numeric type and accepts only valid numbers, as indicated by the message in See "Output of the New Complex Report Showing Values from the Input Controls".

In the Report Viewer, you can open the Input Controls window at any time by clicking the Options button. Clicking OK closes the Input Controls window; clicking Apply keeps it open to easily change values and run the report again.

More about Datatypes

A datatype in the server is more than just a classification of the data. It also includes validation criteria. The datatype description page contains these fields:

Localizing JRXML Reports

JRXML reports (including Topics) support the $R expressions for field names; such expressions are used to localize reports into various languages. Each $R expression refers to an entry in a resource bundle properties file that you must create. For example, if you localize a field called StoreState, you might use this JRXML:

The server looks for a label with the ID of StoreState. In order for this localization to work properly, you must create the resource bundle with the correct labels, and declare the resource bundle in the header of the JRXML file. For example:

In this header, simpleTable is the name of the resource bundle file that contains the StoreState property. iReport can help you localize the report by creating the resource bundle. When you upload the report, you must upload the resource bundle, as well. If you edit a resource bundle in iReport, you can right-click it in repository (using the JasperReports Server Plug-in) and select Replace with Current File.

Default Fonts in JasperReports Server

By default, the server uses three fonts you can use in reports:

•    DejaVu Sans

•    DejaVu Serif

•    DejaVu Sans Mono

Using the DejaVu fonts shipped with the server ensures that the fonts are always available in all environments, which in turn ensures the PDF is pixel perfect every time.

The DejaVu replace the Java logical fonts used in previous versions of the server:

•    SansSerif

•    Serif

•    Monospaced

When using the DejaVu fonts coming from JasperReports font extensions, you don’t need to set any other font attributes (such as the pdfXXX attributes) in the JRXML, nor do you need to specify font mapping. The font extension file that makes these fonts available takes care of setting font attributes and mapping.

For more information about DejaVu, refer to its SourceForge project at: http://dejavu-fonts.org/wiki/index.php?title=Main_Page.