Getting Started with Reports
This section contains the instructions for using the report wizard and the report detail view for creating and executing reports.
Examples in this section are based on the sample Library application, whose source code is available on GitHub.
Project Setup
-
Download and unpack the source code of the Jmix Samples project, or clone it using Git:
git clone https://github.com/jmix-framework/jmix-samples-2
-
Open the
jmix-samples
project in Studio as described in the Opening Existing Project section. -
Select the Library Jmix Application configuration and run the application as described in the Starting Application section.
-
Log in to the Library application with username and password
admin
/admin
.
To run the wizard, open the Report list view and click Create → Using wizard.
The following types of reports can be created using the wizard:
-
Report for single entity.
-
Report for list of entities.
-
Report for list of entities, selected by query.
The process of creating a report using the wizard includes three steps:
-
Creating a data structure of a report.
-
Editing of report regions.
-
Saving the report.
The created report can be modified using the report detail view and run through the report list view or using special actions (RunListEntityReportAction
, RunSingleEntityReportAction
, etc.).
Using Report Wizard
For an easy start, the reports add-on comes with a report wizard, a visual tool for a quick report creation, including data structure and template design.
In this section, you will create a report with an overview of the book’s main data and authors of that book. The report template will be a document in the DOCX format, and the generated report will be saved as a PDF file.
Open the Reports → Reports item in the main menu of the application and click Create → Using wizard. Enter the following parameters on the first step of the wizard:
-
Report Entity:
Book
. -
Template Type: DOCX.
-
Report Name:
Book Record
. -
Report Type:
Report for single entity
.
Defining Attributes
On the next step of the wizard, specify the attributes of the Book
entity and the linked LiteratureType
entity that should be reflected in the report: Book.name
, Book.summary
, Book.literatureType.name
. Those attributes form the so-called "simple region".
Click OK to move to the next step - report regions editing.
The appeared view contains a list of named regions - bands that display related data. The wizard enables adding several plain-text regions to the template in order to display different data sets.
A set of entity attributes loaded to a particular region can be modified by clicking the link represented as the list of the selected attributes. You can also add a new region by clicking Add simple region.
If the entity contains collection attributes, the Add tabulated region button will appear. It enables adding a region for tabular data display.
So, to display a list of associated authors of this Book
entity, we’ll create another data band. Click on the Add tabulated region button.
Select Book.authors
in the Entity tree lookup dialog.
Then select the authors.firstName
and authors.lastName
attributes.
When all report regions are configured, you can move on to the final step: saving the report. At this point, you can view the complete report template, or change the name and format of the output file to one of the available types. Select PDF report output type.
After clicking the Save button, the standard report detail view comes up. Now you can fine-tune the report.
Configuring Output Document
Switch to the Template tab in the report detail view.
The output document for this report contains one template defined initially through the report wizard. The output type is set to PDF, while the template file is DOCX.
Click on the template file name and open it, for example, via LibreOffice. Change the template content according to the picture:
The templates of the reports can be found in the demo project under reports/templates. |
Click to the Upload button of the Report template dialog and select the updated template.
Additionally, it is possible to define the filename of the output document. This can either be a static filename or it can be programmatically configured.
In our case, the filename should look like this for the book with the name "The 20th Century Art Book": Book Record - The 20th Century Art Book.pdf
.
To achieve this, we can configure a pattern which references a particular band: ${Root.title}.pdf
.
Root.title
refers to the title
value of the Root
data band.
Switch on the Bands tab. Select the Root
band and check the Multi Datasets checkbox.
Create a new title
dataset.
A groovy based data set will define the value for the title
attribute like this:
def bookName = params["entity"]["name"] (1)
return [
["title" : "Book Record - $bookName"] (2)
]
1 | The params variable gives access to different external parameters. params["entity"] refers to the selected book instance. |
2 | A List of Maps has to be returned from this groovy script. Under the title key, it will put the target filename. |
Running Report from Books View
Additionally, we can enable the report run on the book list view. To do this, we will declare a standard RunListEntityReport in the book-list-view.xml
view descriptor:
<hbox id="buttonsPanel" classNames="buttons-panel">
<!-- ... -->
<button id="printBtn" action="booksDataGrid.reportPrint"/> (1)
</hbox>
<dataGrid id="booksDataGrid"
width="100%"
minHeight="20em"
dataContainer="booksDc">
<actions>
<!-- ... -->
<action id="reportPrint" type="report_runListEntityReport"
text="Print details"/> (2)
</actions>
</dataGrid>
1 | Add a button with run report action. |
2 | The type attribute defines a specific report_runListEntityReport action type. |
Then we should link our report with the Book
list view. In the report detail view, switch to the Roles and views tab and add the Book.list
view from the dropdown list to the table below:
Save the report.
Now you can run the report for any book by selecting it in the table and simply clicking the Print details button.
The output is as follows:
Creating Report Manually
In this section you will create a more complex report without using the wizard.
The report will contain the list of publications grouped by literature types and books.
The upper part of the report will contain an information about the report creator and the date of the report. A table with a sequential grouping by literature type and books will be listed below.
The report will have the following settings:
-
Template Type: XLSX.
-
Report Name:
Publications grouped by types and books
.
Creating Template
Create a Template for publications by type.xlsx
template for our report using Microsoft Office or LibreOffice.
This report template contains named regions (type
, book
, publisher
) for three datasets of dependent bands and, additionally, named regions for the column header (tableheader
) and for additional information about the report (header
).
The templates of the reports can be found in the demo project under reports/templates. |
Defining Report Structure
Open the Reports → Reports view in the main menu of the application and click Create → New.
The Report details tab of the report detail view is shown.
Define the report name - Publications grouped by types and books
.
Click on the Create template button.
The Report template dialog is opened. Upload the created template and define the output name pattern.
Let’s create report bands.
-
The header band contains the dataset with the Groovy script which outputs the name of the current user and the current date.
import io.jmix.core.security.CurrentAuthentication; import io.jmix.core.TimeSource; def user = currentAuthentication.getUser().getUsername(); def currentDate = timeSource.currentTimestamp(); return [["generated_by":user, "generated_when":currentDate]]
-
The tableheader band is blank, it is used to display the table header.
-
The type band outputs the list of literature types by running the following JPQL query:
select b.literatureType.id as typeId, b.literatureType.name as type from Book b
-
The book band, which is a child band of the type, outputs the books by running the following JPQL query:
select b.id as bookId, b.name as bookName from Book b where b.literatureType.id = ${type.typeId}
This query uses the parent band field
typeId
as a parameter. This provides dependency between the parent and child bands. -
The publisher band, which is a child of the book band, outputs the book publications by running the following JPQL query:
select bp.publisher.name as publisher, bp.year as year, bp.city as town from BookPublication bp where bp.book.id = ${book.bookId}
This query uses the parent band field
bookId
as parameter.
The report looks as follows in the report detail view:
Running Report from Run Reports View
Once the report is saved, you can run it through the run reports view.
The output is as follows: