Homepage › Learn › All › Modeling Reports

Modeling Reports

by Lucio Bordonaro
16,308 views Published on Jul 04, 2013
PDF Report
Applies to: All versions
Table of contents

Introduction

WebRatio Reports is an add-on of WebRatio aimed to design and produce professional-quality reports.

WebRatio Reports leverages on Jasper Reports, a popular open source reporting solution, and on its accompanying visual report designer (iReport), to enhance Web applications with professional quality reports complete with charts and subreports. 

In order to model reports with WebRatio 7, iReport 4.0.1 must be installed and you have to Set Custom Grid as Layout Manager on the report page.

To facilitate the work of WebRatio, it is strongly suggested to launch iReport, select Options from the Tools menu, select the Compilation and Execution tab, and perform the following action: 

  • Enable the option Use Report Directory to compile 

 

Modeling a Report Page

WebRatio Reports permits the dynamic production of reports based on the data stored in one or more entities, possibly filtered by means of run-time selectors. A step-by-step procedure on the sample project named Acme (installable using the Help > WebRatio Samples option of the main menu) is now described, in order to illustrate how to add a simple report page to a WebRatio project.

As a first step, open the Acme project and add a page to the public site view named AcmeWeb. Name the page ReportPage and set its Style to Reports. Setting such style, the page is automatically associated with the Reports/Default page template. Now it is possible to set the layout parameter Report Type in order to choose the output format: PDF (the default), RTF, or Excel. For our example, let's add to the report page the following units:

A Multi Data Unit named ProductList over the entity Product, displaying the attributes code, name, and price, and sorted by name
A Multi Data Unit named CategoryList over the entity Category, displaying the attribute Category and sorted by the same attribute
N.B.: Be sure to have placed the units in the grid and that each unit is placed once in the grid.

At this point, the modeling phase with WebRatio is more or less terminated: further refinements of the model will be required only if new report pages must be added or if the existing report pages require updates (for instance, the displayed attributes of a Multi Data Unit are changed).

 

Synchronize the Report

In order to Synchronize the report with the model Page, right-click on the Report Page and select the  Synchronize Report command. The synchronization process is based on the status of the project and of the report and provides different functionalities.

 

Creation of a new Report

If the report page has not previously associated with a report, WebRatio makes you aware of it and asks you to automatically create a report.

Basing itself on the name of the page, WebRatio creates a jrxml file under the WebContent/WEB-INF/descr folder named <PageName>.jrxml. For each unit it creates a file named as <PageName>_<UnitName>_SubReport.jrxml

Since WebRatio bases itself on page names and units names, the pages and the units names used in the report pages, must be different. In case of identical names an error is shown.

 

Creation of a Sample XML Data Source

WebRatio can automatically create a sample XML data source. This file is used to feed the sample report, named like the page jrxml file and with the suffix sample.xml (e.g. ReportPage.jrxml.sample.xml) 

 

Compile the Report

The generated jrxml report is in the source format. In order to deploy the report page, all the generated report must be compiled using iReport.

Start iReport
Open the reports and subreports.
Use the  Compile option in the main toolbar to compile each report

At any time, the WebRatio Synchronize Report is able to understand which templates are up-to-date and asks you to recompile them.

 

Preview the Report

To preview the sample report, first of all a XML datasource must be defined, through these steps:

  • Start iReport
  • Select the Report Datasources button in the main toolbar
  • On the newly opened dialog click New
  • Select the XML file data source item and then the Next button 

  • On the newly opened fill the fields with the following information:
    • Name = Acme XML Sample
    • XML File = Path to the sample.xml file
    • Enable Use the report XPath expression 

  • Click on Test and next to Save
  • Set the new datasource as the default one
  • Open the ReportPage.jrxml template, i.e. the page template
  • Select the Preview button in the secondary toolbar to generate the PDF
  • Select the Use default button on the newly opened dialog.

If the compilation process succeeds, you are able to see a very basic PDF report similar to the following:

 

Publish the Report

To publish the report on the Web application follow these steps:

  • Select the ReportPage in the Web Model
  • Generate the ReportPage using the  Generate Selection command
  • Start Tomcat
  • Right-click on the page and select the  Open in Browser command

You are able to see the generated report with the real data:

Report Structure

A basic analysis of the structure of the main report and of its subreports is mandatory, to understand how they are organized and how to extend them.

The main report is just a container of subreports. It is useful for specifying the overall title, the page header, and the page footer. For this reason, the main report works on the full XML datasource, with no specific selection subquery.

The main report includes a number of subreport elements, one for each multidata unit of the page, placed in the Detail 1 band. 

The subreport elements distinguish for two properties:

  • The datasource expression, which addresses a sub-set of the full XML datasource. For instance the product list subreport is feed by a datasource obtained by applying the following XPath query: /Report/ProductList/Product
  • The subreport path, obtained by the concatenation of the parameter SUBREPORT_DIR with the subreport template name (e.g. ReportPage_ProductList_SubReport.jasper) 

As explained above, WebRatio is able to automatically generate a subreport template for each Multi Data Unit of the Report Page. Each subreport template includes a number of fields equals to the displayed attributes of the Multi Data. For instance, the product list subreport includes three fields (code, name, price). Clicking on a field in the Document structure updates the properties panel, which shows the name, the type, and the description of the field. Since the input datasource is a XML datasource, the description represents the XPath query used to extract the field from the current datasource node.

The fields declared in the subreport, accompanied by a static text displaying the field name, are placed inside the detail band. Therefore, during the run-time report construction, the report engine iterates over the nodes of the data source (/Report/ProductList/Product for the product list subreport), and at each iteration prints a detail row with the current name and value of fields.

For BLOB attributes storing images the text field items can be easily replaced with Image items.
 

Customize the Report

The refinements of a report page requires an iteration between:

iReport, working on the jrxml templates stored in the descr sub-folder of the project folder, to move the fields, add static text and images, and so on
WebRatio, to regenerate the project and update the files
The browser, to see the dynamically built reports
On the other hand, to shorten the development time, it is possible to work in offline mode, modifying and execute the template directly from iReport, using the static XML document as input datasource.

Once the template is ready, select the Report Page, select the Synchronize Report command. WebRatio is able to understand if the templates have been modified and asks you to recompile them, if you don't already compile them. 

Modify the Model

In order to mantain synchronized your reports, WebRatio is able to understad when you add a new unit or a new attribute to display to your model.

When you add a new unit to the model, synchronize the report page using the Synchronize Report command. WebRatio advise you that the report is changed and automatically adds the sub report reference to the page report.

Since the report is changed, WebRatio asks you to recompile it.

When you add a new attribute to display to a unit, synchronize the report page using the  Synchronize Report command. WebRatio advise you that the report is changed and automatically adds the field to the unit report.
 

Since the report is changed, WebRatio asks you to recompile it.

When you change the entity of a unit, synchronize the report page using the Synchronize Report command. WebRatio advise you that the report is changed and automatically updates the reference to the new entity.


Since the report is changed, WebRatio asks you to recompile it. 

Reports with Hierarchical Index Units

Besides Multi Data Units, Report pages can include Hierarchical Index Units. The Synchronize Report creates a file named as <PageName>_<LevelName>_SubReport.jrxml for each unit level. Each sublevel report is automatically referenced in the parent level subreport.

If you don't want to generate a subreport for each level, you can specify that the structure of the report must be flat. In order to create a flat report, add a Property to the Hierarchical Index Unit and name it flat. A single report named <PageName>_<UnitName>_SubReport.jrxml will be generated.

Reports with Multi Message Units

In order to permit into a report the placement of arbitrary text not specifically related to data stored in the database, Report pages can include Multi Message Units. The Synchronize Report creates a file named as <PageName>_<UnitName>_SubReport.jrxml for each multi-message unit.

Advanced Features

Static Images

You can add static images to your reports, for instance you can add the logo of your company. Follow these steps to add a static image:

  • Open the product list subreport in iReport
  • Select the Image Tool toolbar button
  • Add the image by dragging the mouse cursor on the title area
  • Cancel the dialog asking to select an image in the filesystem
  • Click on the newly added image
  • Select the button on the right of the Image Expression property in the Properties view
  • Write $P{BASE_URI} + "images/logo.png", where "images/logo.png" is the path to the image in the generated application. 

  • Compile the report

Alternatively you can use the $P{SUBREPORT_DIR} parameter, either in the main report or in any sub-report. In case of sub-report, verify that the $P{SUBREPORT_DIR} parameter is declared in the sub-report template and that the parameter is transferred from the main report to the sub-report. The expression to use is the following (don't miss the slash character):

  • $P{SUBREPORT_DIR} + "/logo.png"

Assuming that the image file is stored in the same folder of the jasper files. 

Charts

iReport fully supports the addition of charts to reports, leveraging the tight integration between JasperReports and JFreeChart. To add a very simple Pie chart to our report, showing the distribution of prices of products, follow these steps:

  • Open the product list subreport
  • Select the Summary element in the Report Inspector
  • Change the height from 0 to 250 in the Properties view
  • Select the Chart Tool toolbar button
  • Add a pie chart by dragging the mouse cursor on the summary area

To connect the pie chart with the XML datasource feeding the product list subreport:

  • Right-click on the newly added chart
  • Select Chart Data
  • Select the Details tab
  • In the Section Value tab, fill the three text fields as shown in the image below 

The result is shown in the next image.

Localization

WebRatio Reports includes a mechanism to invoke different report templates based on the current locale settings. To activate the localization of a report page, the property Localized must be set on the WebRatio page. The run-time behaviour for a user accessing the report page with locale en_US is the following:

  • First, a template named ReportPage_en_US.jasper is searched
  • If not found, a template named ReportPage_en.jasper is searched
  • If both of the above templates are not included in the run-time descriptor folder, the default template named ReportPage.jasper is used

The solution of specializing a report into a set of localized reports is useful if the layout and content of the base report is very different from the localized reports. Instead, if the localized reports differs only for a set of static labels, it is possible to use the WebRatio predefined localization:

  • For each attribute shown by a unit (for instance the code attribute), the unit report automatically includes a special field having the same name of the attribute but prefixed by i18n (for instance i18n.code). Such field can be placed into the report, and replaced at run-time by the correct localized message.
  • Additional localization keys defined in the model can be used by simply adding a custom property having name i18n and value equal to the localization message key. Select the report page and select the Synchronize Report command: in this way the main report and the units subreports are updated to include a special field named i18n.global.<messageKey>.
  • To transfer a global field i18n.global.<messageKey> from a hierarchical index unit report to levels subreports click on the subreport box in the unit report, select the button on the right of the Parameters property in the Properties View and add a parameter with name i18n.global.<messageKey> and value $F{i18n.global.<messageKey>}. Next, open the level subreport and add a parameter (not a field) named i18n.global.<messageKey>. 

Special No Result Template

WebRatio permits to specify a special report template to be used when the report page includes no data (i.e. all the included Multi Data Unit return an empty recordset). To specify the template, simply create a template named as the page jrxml, but with the suffix _NoResult.jrxml. For instance, the no result template for the Report Page is ReportPage_NoResult.jrxml.

Merging Reports

WebRatio permits to merge the PDF reports produced by multiple report pages in an easy way. To achieve this result, follow these steps:

  • Define a special page Merge and apply the page layout named Reports/MergeReports to it
  • Create one or more links from the Merge page to all the required report pages. Note that also unit links can be used, in addition to links directly starting from the page
  • At run-time, each link reaching the Merge page forces the WebRatio run-time framework to compute in turns all the report pages reachable directly from the Merge page itself, and to return the merged PDF report.
  • If the order of links automatically inferred by the merge page is not as wanted, the JSP page can be manually edited and next stored into the WebContent folder of the WebRatio project.

Conditionally Showing Elements

All the elements placed in a report structure (text fields, sub-reports, etc..) can be conditionally shown/hidden using the iReport interface. To edit the conditional expression, follow these steps:

  • Click on the element
  • Select the button on the right of the Print When Expression in the Properties View
  • Edit the Print when expression text field

The expression has the following properties:

  • Must return a java.lang.Boolean object.
  • Can reference the fields and variables defined in the report.
  • Can reference the special field named dataSize.<UnitName> where <UnitName> is the name of one of the multi-data, hierarchical index, or multi-message units placed in the report page.

To edit the expression iReport provides a user-friendly expression editor, which can be activated using the bottom right button in the expression dialog.

HTML Content

WebRatio permits to embed a limited sub-set of HTML markup inside a PDF document (please note that this feature is in beta stage and could produce unexpected results in case of complex HTML or in case of complex reports with multiple HTML text fields).

Assuming that an attribute named textChunk contains HTML markup, proceed as follow:

  • Add the attribute to the list of attributes displayed by a multi-data unit or hierarchical index unit
  • Synchronize the report
  • Open/Refresh the synchronized report
  • Locate the textChunk field and edit its expression changing it from $F{textChunk} to "HTML_TEXT::" + $F{textChunk}
  • Compile and regenerate the report
  • If required, change the Font Size and PDF Font Name properties 

Report File Name

The default file name produced by a report page is Report.<type> (where type is pdf, xls, or rtf). In order to change the report file name proceed as follow:

  • Add a multi message unit to the report page
  • Find the multi message unit in the Grid view
  • Assign to the unit the layout template ReportFileName
  • Set the Default message property of the unit or fills the unit's input parameter Shown Messages with a dynamically computed file name.

WAR Deployment

Specific actions could be required due to servlet restrictions on certain application servers in case of WAR deployment.

More specifically, if the application is generated using a deployment plan with a WAR task but without the JAR Descriptors task, Jasper Reports could fail in loading report files. In order to fix this problem, it is recommended that all the *.jasper files are placed together inside a JAR file which has to be put inside the predefined WebContent/WEB-INF/lib folder.

Please note that the abovementioned problem is absent in case the deployment plan includes both the WAR and the JAR Descriptors tasks.