Getting started - HQL query

Before making an JRXML file you need a database query written in Hibernate Query Language. Community documentation for the HQL can be found here. After writing it can be tested at http://localhost:8080/developReport/hql.html after starting the qcadoo system. When you have query retrieving all data needed for your report you can start writing an JRXML file.

Making a JRXML file

Overview

JRXML is an XML file format used to define JasperReports reports.

Prerequisites

Before you can develop you own report file you will need the following software:

1. Eclipse IDE
2. Jaspersoft Studio as plugin for Eclipse IDE

After getting it you can setup a new plugin or add report to an existing one. To do that you will have to create a "report" directory inside "src/main/resources/<identifier>" where <identifier> is the plugin identifier.

Qcadoo Hibernate Query Report Template

Below is a template which you can use to create a new report. Your JRXML file should be put inside "report" directory you've just created.

<?xml version="1.0" encoding="UTF-8"?>
<jasperReport xmlns="http://jasperreports.sourceforge.net/jasperreports"
	      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	      xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports http://jasperreports.sourceforge.net/xsd/jasperreport.xsd"
	      name="reportName"
	      pageWidth="value"
	      pageHeight="value"
	      orientation="PortraitOrLandscape"
	      columnWidth="value"
	      leftMargin="value"
	      rightMargin="value"
	      topMargin="value"
	      bottomMargin="value"
	      isFloatColumnFooter="trueORfalse">
	<template><![CDATA["qcadooReport/report/qcadooStyles.jrtx"]]></template>

	// PARAMETER DEFINITIONS

	<queryString language="hql">
		<![CDATA[

			// HQL QUERY

		]]>
	</queryString>

	// FIELD DEFINITIONS

	<background>
		<band splitType="Stretch">

		// BACKGROUND CONTENT

		</band>
	</background>
	<title>
		<band height="value" splitType="Stretch">

		// TITLE CONTENT

		</band>
	</title>
	<pageHeader>
		<band height="value" splitType="Stretch">

		// PAGE HEADER CONTENT

		</band>
	</pageHeader>
	<columnHeader>
		<band height="value" splitType="Stretch">

		// COLUMN HEADER CONTENT

		</band>
	</columnHeader>
	<detail>
		<band height="value" splitType="Stretch">

		// REPORT DATA CONTENT

		</band>
	</detail>
	<columnFooter>
		<band height="value" splitType="Stretch">

		// COLUMN FOOTER CONTENT

		</band>
	</columnFooter>
	<pageFooter>
		<band height="value" splitType="Stretch">

		// PAGE FOOTER CONTENT

		</band>
	</pageFooter>
	<summary>
		<band height="value" splitType="Stretch">

		// SUMMARY CONTENT

		</band>
	</summary>
</jasperReport>

Tags: background, pageHeader, columnFooter and summary can be skipped.

Template Structure Overview

Below is a short description of each tag.

Adding content to the template

Parameters

Parameters are variables forwarded to a report by a form or a grid. DefaultValueExpression is not required. Attribute class refers to a java class, e.g. java.util.List.

<parameter name="parameterName" class="parameterType">
	<defaultValueExpression><![CDATA[ EXPRESSION ]]></defaultValueExpression>
</parameter>

Example usage: you can declare parameter EntityId which can be used later in where clause in database query to get rows with specific Id.

Fields

The select clause in database query (placed in <queryString> tag) picks which objects and properties to return in the query result set. Fields are used to define data types for these results. Attribute class refers to a java class, e.g. java.lang.String.

<field name="fieldName" class="fieldType"/>

Content inside <band> tag

Lines

<line>
	<reportElement style="styleName" x="value" y="value" width="value" height="value"/>
</line>

Rectangles

<rectangle>
	<reportElement x="value" y="value" width="value" height="value" backcolor="#colorValue"/>
</rectangle>

Text Fields

Text fields are the most important part of a report. By using expressions inside textFieldExpression attribute of these tags you will put data from you query to a report. You can as well put into them values of your parameters or values from properties files inside locales directory.

<textField>
	<reportElement style="styleName" x="value" y="value" width="value" height="value"/>
	<textElement textAlignment="alignment"/>
	<textFieldExpression class="dataTypeOfTheExpressionResult"><![CDATA[ EXPRESSION ]]></textFieldExpression>
</textField>

TextAlignment attribute is not required (by default it's Left).
Below you can find information about how to create expressions.

Text Field Expressions

Beside what's listed above you can also use plus sign to concatenate strings inside your expressions or create variables, e.g. "new Date()".

Styles list

Here is a list of styles from qcadooReport/report/qcadooStyles.jrtx file:

• qcadooMainDataBox
• qcadooLabel
• qcadooValue
• qcadooPageNumber
• qcadooPageNumberLine
• qcadooHeaderTitle
• qcadooHeaderLine
• qcadooHeaderDetails

Testing a report

After you finish writing a JRXML file it has to be tested. You can do it at http://localhost:8080/developReport/report.html.

Adding a report to a plugin

First you have to put information about your report inside a qcadoo-plugin.xml file. Module used for that is described here. After doing that only thing left is making a button which will generate your report. You'll have to add a group to a ribbon and then add a button to that group. It's described here.