<html xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:jr="http://jasperreports.sourceforge.net/jasperreports">
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>JasperReports 4.0.2 - Jasper Sample</title>
<style type="text/css">
.title {
font-family: Arial, Verdana, Helvetica, sans-serif;
font-size: 28px;
font-weight: normal;
}
.toc {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.name {
font-family: Courier New, Courier, serif;
font-size: 16px;
font-weight: bold;
}
.label {
font-family: Arial, Verdana, Helvetica, sans-serif;
font-size: 12px;
font-weight: bold;
font-style: italic;
}
.description {
font-family: Arial, Verdana, Helvetica, sans-serif;
font-size: 12px;
font-weight: normal;
}
.value {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.element {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.attribute {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: bold;
}
.code {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.copy {
font-decoration: none;
font-family: Verdana, Arial, Helvetica, sans-serif;
font-size: 8pt;
font-style: normal;
color: #000000;
}
.subtitle {
font-family: inherit;
font-size: inherit;
font-style: inherit;
font-weight: bold;
text-decoration: none;
color: inherit;
}
</style>
</head>
<body bgcolor="#FFFFFF">
<a name="top"></a>
<table cellspacing="0" cellpadding="0" border="0" width="100%">
<tr>
<td colspan="2" align="right"><span class="element"><a href="../../sample.reference.html">Sample Reference</a> - <a href="../../schema.reference.html">Schema Reference</a> - <a href="../../config.reference.html">Configuration Reference</a> - <a href="http://jasperreports.sourceforge.net/api/index.html">API (Javadoc)</a></span>
<br>
</td>
</tr>
<tr>
<td colspan="2">
<hr size="1">
</td>
</tr>
<tr valign="middle">
<td nowrap="true"><span class="title">JasperReports - Jasper Sample (version 4.0.2)</span></td><td align="right"><img src="../../resources/jasperreports.png" border="0"></td>
</tr>
<tr>
<td colspan="2">
<hr size="1">
</td>
</tr>
</table>
<br>
<span class="description"><span class="description">Shows how different features of the library could be used to generate a complex document.</span></span>
<br>
<br>
<span class="element"><a href="http://sourceforge.net/projects/jasperreports/files/jasperreports/JasperReports%204.0.2/jasperreports-4.0.2-project.zip/download" target="_blank">Download All Sample Source Files</a></span>
<br>
<span class="element"><a href="http://jasperforge.org/scm/viewvc.php/tags/jr-4-0-2/jasperreports/demo/samples/jasper/?root=jasperreports" target="_blank">Browse Sample Source Files on SVN</a></span>
<table width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
<td style="width: 20px;">
<br>
</td><td>
<br>
</td>
</tr>
<tr>
<td colspan="2"><span class="label">Main Features in This Sample</span></td>
</tr>
<tr>
<td>
<br>
</td><td><span class="element"><a href="#groups">Data Grouping</a></span></td>
</tr>
<tr>
<td>
<br>
</td><td><span class="element"><a href="#csvmetadataexport">Exporting to CSV Format Using Report Metadata</a></span></td>
</tr>
<tr>
<td>
<br>
</td><td><span class="element"><a href="#conditionalstyles">Conditional Styles</a></span></td>
</tr>
</table>
<table width="100%" cellspacing="0" cellpadding="0" border="0">
<tr>
<td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td width="80%">
<br>
</td><td width="20%">
<br>
</td>
</tr>
<tr>
<td colspan="6" align="right"><a name="groups"></a><a href="#top" class="toc">top</a></td>
</tr>
<tr>
<td colspan="6">
<hr size="1">
</td>
</tr>
<tr valign="top">
<td><img src="../../resources/jr-16x16.png" border="0"></td><td colspan="4"><span class="name">Data Grouping</span></td><td align="right"><span class="copy">Documented by
<a href="mailto:shertage@users.sourceforge.net" class="copy">Sanda Zaharia</a></span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr valign="top">
<td>
<br>
</td><td nowrap="true"><span class="label">Description / Goal</span></td><td>
<br>
</td><td colspan="3"><span class="description">
How to group data at different levels and perform aggregate calculations using report groups.
</span></td>
</tr>
<tr valign="top">
<td>
<br>
</td><td colspan="1"><span class="label">Since</span></td><td>
<br>
</td><td colspan="3"><span class="description">0.1.0</span></td>
</tr>
<tr valign="top">
<td>
<br>
</td><td nowrap="true"><span class="label">Other Samples</span></td><td>
<br>
</td><td colspan="3">
<table width="100%" cellspacing="0" cellpadding="0" border="0">
<tr>
<td><span class="element"><a href="../datasource/index.html">/demo/samples/datasource</a></span></td>
</tr>
</table>
</td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr>
<td>
<br>
</td><td colspan="5"><span class="description">
<a name="grouping_overview" href="../../sample.reference/jasper/index.html#grouping_overview" class="subtitle">Grouping Data in JasperReports</a>
<br>
<br>
A report's content can be better organized if the report data are grouped by meaningful criteria. For instance,
a shipping report becomes more relevant when its data are grouped by product type, or by customer's country, etc.
<br>
And as a bonus, grouped data allow statistic calculations to be performed and additional statistic information
to be added to the report at runtime.
<br>
As seen above, there are multiple reasons of grouping and aggregating data before they are represented. In JasperReports
there are two ways to accomplish this:
<ul>
<li>If a report query is declared, it could be customized to retrieve already aggregated data from the data source
(A SQL query could use the <span class="code"><code>GROUP BY</code></span> clause and statistical functions, for example). The main advantage
is that the JR engine needs no more to prepare data before representing it, and the report is running faster in this
case. The main disadvantage is that one cannot use the group imbrication, along with group header and footer facilities,
so the data presentation can be realized in simplified layouts only.</li>
<li>If a rich presentation context of data grouping is required, one could use the report <span class="code"><code><group/></code></span>
elements. Groups represent a flexible way to organize data on a report. In this case, the engine iterates through
records in the data source and retrieves only those according to the grouping criteria.</li>
</ul>
A report group has three components:
<ul>
<li>Group expression - contains the data grouping criteria. When the value of the group expression
changes during the iteration through the data source at report-filling time, a group rupture occurs
and the corresponding <groupFooter> and <groupHeader> sections are inserted into the
resulting document.</li>
<li>Group header section - a multiband section containing header additional information.</li>
<li>Group footer section - a multiband section containing footer additional information.</li>
</ul>
<b>Note</b>:
<ul>
<li>The order of groups declared in a report template is important because groups contain each other.
One group contains the following group, and so on. When a larger group encounters a rupture, all
subsequent groups are reinitialized.</li>
<li>You can declare as many groups as you want in a report.</li>
<li>In order to get an accurate data representation, the data in the data source should be
already ordered according to the group expressions used in the report. One can either perform data
sorting through the report query, or use the <span class="code"><code><sortField/></code></span> element.</li>
</ul>
<a name="attributes" href="../../sample.reference/jasper/index.html#attributes" class="subtitle">Group Attributes</a>
<br>
<br>
Any group in a report can be customized through its attributes:
<ul>
<li>
<span class="code"><code>name</code></span> - Acts as a group identifier. This attribute is mandatory, and should be unique per report.</li>
<li>
<span class="code"><code>isStartNewColumn</code></span> - Instructs the engine to start a new column when a new group starts. The default
value is <span class="code"><code>false</code></span>.</li>
<li>
<span class="code"><code>isStartNewPage</code></span> - Instructs the engine to start a new page when a new group starts. The default
value is <span class="code"><code>false</code></span>.</li>
<li>
<span class="code"><code>isResetPageNumber</code></span> - If <span class="code"><code>true</code></span>, when a new group starts, the built-in <span class="code"><code>PAGE_NUMBER</code></span>
variable will be reset. The default value is <span class="code"><code>false</code></span>.</li>
<li>
<span class="code"><code>isReprintHeaderOnEachPage</code></span> - Instructs the engine to print the group header on each page containing
the group data. The default value is <span class="code"><code>false</code></span>.</li>
<li>
<span class="code"><code>minHeightToStartNewPage</code></span> - Represents the minimum amount of vertical space at
the bottom of the page or column, measured in pixels, that prevents the group from starting a
new page of its own.</li>
<li>
<span class="code"><code>footerPosition</code></span> - Specifies the rendering position of the group footer on the page. Possible values are:
<span class="code"><code>Normal</code></span>, <span class="code"><code>StackAtBottom</code></span>, <span class="code"><code>ForceAtBottom</code></span>, <span class="code"><code>CollateAtBottom</code></span>.
The default value is <span class="code"><code>Normal</code></span>.</li>
<li>
<span class="code"><code>keepTogether</code></span> - If <span class="code"><code>true</code></span>, prevents the group from splitting on its first break attempt.
The default value is <span class="code"><code>false</code></span>.</li>
</ul>
<a name="variables" href="../../sample.reference/jasper/index.html#variables" class="subtitle">Data Grouping and Report Variables</a>
<br>
<br>
Report variables are special objects built on top of a report expression in order to apply the code
reusability during the report design stage. Report templates are a lot simplified when expressions
frequently used throughout the report template are declared in a single place as objects that can
be referenced by their name as unique identifier.
<br>
Another great advantage of declaring expressions as variables is the ability to perform various
calculations based on their corresponding expression.
<br>
A report variable is characterized by the following attributes:
<ul>
<li>
<span class="code"><code>name</code></span> - The variable's name used as unique identifier. It is mandatory.</li>
<li>
<span class="code"><code>class</code></span> - The class name of the variable's values. The default class is <span class="code"><code>java.lang.String</code></span>
</li>
<li>
<span class="code"><code>resetType</code></span> - Indicates when the variable should be reinitialized during the report-filling process. Possible
values are:<span class="code"><code>None</code></span>, <span class="code"><code>Report</code></span>, <span class="code"><code>Page</code></span>, <span class="code"><code>Column</code></span>, <span class="code"><code>Group</code></span>. The default
value is <span class="code"><code>Report</code></span>.</li>
<li>
<span class="code"><code>resetGroup</code></span> - If the <span class="code"><code>resetType</code></span> is set to <span class="code"><code>Group</code></span>, indicates the name of the group
which triggers the variable reinitializing each time it breaks.</li>
<li>
<span class="code"><code>incrementType</code></span> - Indicates when the variable should be incremented during the report-filling process. Possible
values are:<span class="code"><code>None</code></span>, <span class="code"><code>Report</code></span>, <span class="code"><code>Page</code></span>, <span class="code"><code>Column</code></span>, <span class="code"><code>Group</code></span>. The default
value is <span class="code"><code>None</code></span>.</li>
<li>
<span class="code"><code>incrementGroup</code></span> - If the <span class="code"><code>incrementType</code></span> is set to <span class="code"><code>Group</code></span>, indicates the name of the group
which triggers the variable increment each time it breaks.</li>
<li>
<span class="code"><code>calculation</code></span> - Indicates the built-in calculation type to be performed on the variable expression value. Possible
values are:<span class="code"><code>Nothing</code></span>, <span class="code"><code>Count</code></span>, <span class="code"><code>DistinctCount</code></span>, <span class="code"><code>Sum</code></span>, <span class="code"><code>Average</code></span>, <span class="code"><code>Lowest</code></span>,
<span class="code"><code>Highest</code></span>, <span class="code"><code>StandardDeviation</code></span>, <span class="code"><code>Variance</code></span>, <span class="code"><code>System</code></span>, <span class="code"><code>First</code></span>. The default
value is <span class="code"><code>Nothing</code></span>.</li>
<li>
<span class="code"><code>incrementerFactoryClass</code></span> - The name of the incrementer factory class.</li>
</ul>
<b>Note</b>: With every iteration through the data source, variables are evaluated/incremented in the same order as they are
declared. Therefore, the order of variables as they appear in the report template is very important.
<br>
For more about report variables one can consult also the
<a href="http://jasperforge.org/uploads/publish/jasperreportswebsite/trunk/tutorial.html#Variables" target="_blank" class="element">tutorial</a>.
<br>
<br>
Being familiarized with variables, it's time to focus back on data grouping. Report variables are very useful objects in a report,
that can operate on any collection of data. Since groups are aggregating data in meaningful collections, variables could be used
to perform operations at group level too. As seen above, they can be reset or incremented any time a group breaks, and can be used
to perform various built-in calculations over parameters, other variables and/or field values in a group.
<br>
Related to groups, there is a special built-in counting variable, used to count the number of records in a group. This type of variables
are always named with the related group's name followed by the <span class="code"><code>_COUNT</code></span> suffix. In this sample we'll find some usage examples
of this group counting variables.
<br>
<br>
<a name="jasper_sample" href="../../sample.reference/jasper/index.html#jasper_sample" class="subtitle">The Jasper Sample</a>
<br>
<br>
This sample illustrates how groups can be used to produce documents with complex data grouping in a
multicolumn layout. The <span class="code"><code>reports/FirstJasper.jrxml</code></span> file describes a shipping report presented
in a 2-column layout, with data organized according to several specific grouping criteria.
<br>
The 2-column layout is given by the <span class="code"><code>columnCount="2"</code></span> attribute setting in the
<span class="code"><code><jasperReport/></code></span> element.
<br>
<br>
Further, one can see the report query retrieving data ordered by the <span class="code"><code>ShipCountry</code></span> field:
<pre>
<queryString><![CDATA[SELECT * FROM Orders WHERE OrderID <= $P{MaxOrderID} ORDER BY ShipCountry]] ></queryString></pre>
Next in the report are defined some variables related to groups:
<pre>
<variable name="FirstLetter" class="java.lang.String" resetType="None">
<variableExpression><![CDATA[$F{ShipCountry}.substring(0, 1).toUpperCase()]] ></variableExpression>
</variable>
<variable name="FreightSumFirstLetterGroup" class="java.lang.Double" resetType="Group"
resetGroup="FirstLetterGroup" calculation="Sum">
<variableExpression><![CDATA[$F{Freight}]] ></variableExpression>
</variable>
<variable name="FreightSumCountryGroup" class="java.lang.Double" resetType="Group"
resetGroup="CountryGroup" calculation="Sum">
<variableExpression><![CDATA[$F{Freight}]] ></variableExpression>
</variable>
<variable name="FreightSumColumn" class="java.lang.Double" resetType="Column" calculation="Sum">
<variableExpression><![CDATA[$F{Freight}]] ></variableExpression>
</variable>
<variable name="FreightSumPage" class="java.lang.Double" resetType="Page" calculation="Sum">
<variableExpression><![CDATA[$F{Freight}]] ></variableExpression>
</variable>
<variable name="FreightSumReport" class="java.lang.Double" calculation="Sum">
<variableExpression><![CDATA[$F{Freight}]] ></variableExpression>
</variable>
<variable name="DateHighestCountryGroup" class="java.sql.Timestamp" resetType="Group"
resetGroup="CountryGroup" calculation="Highest">
<variableExpression><![CDATA[$F{OrderDate}]] ></variableExpression>
</variable>
<variable name="RegionCountCountryGroup" class="java.lang.Integer" resetType="Group"
resetGroup="CountryGroup" calculation="Count">
<variableExpression><![CDATA[$F{ShipRegion}]] ></variableExpression>
</variable></pre>
Now let's take a look at the groups themselves:
<pre>
<group name="FirstLetterGroup" isStartNewColumn="true" isReprintHeaderOnEachPage="true"
minHeightToStartNewPage="200">
<groupExpression><![CDATA[$V{FirstLetter}]] ></groupExpression>
<groupHeader>
<band height="25">
...
<textField>
<reportElement mode="Opaque" x="130" y="14" width="140" height="11" forecolor="#ff0000"
backcolor="#ffdddd" style="Sans_Bold"/>
<textFieldExpression class="java.lang.String"><![CDATA[$V{FirstLetter}]] ></textFieldExpression>
</textField>
</band>
</groupHeader>
<groupFooter>
<band height="15">
...
<textField>
<reportElement x="45" y="1" width="25" height="11" forecolor="#ff0000" style="Sans_Bold"/>
<textElement textAlignment="Right"/>
<textFieldExpression class="java.lang.Integer"><![CDATA[$V{FirstLetterGroup_COUNT}]] ></textFieldExpression>
</textField>
...
<textField pattern="0.00">
<reportElement x="170" y="1" width="60" height="11" forecolor="#ff0000" style="Sans_Bold"/>
<textElement textAlignment="Right"/>
<textFieldExpression class="java.lang.Double"><![CDATA[$V{FreightSumFirstLetterGroup}]] ></textFieldExpression>
</textField>
<textField evaluationTime="Auto">
<reportElement x="230" y="1" width="40" height="11" forecolor="#ff0000" style="Sans_Bold"/>
<textElement textAlignment="Right"/>
<textFieldExpression>
<![CDATA[
msg("{0,number,0.00}%",
new Double(100d * $V{FreightSumFirstLetterGroup}.doubleValue() / $V{FreightSumReport}.doubleValue()))
]] >
</textFieldExpression>
</textField>
</band>
</groupFooter>
</group></pre>
According to the group expression above, the <span class="code"><code>FirstLetterGroup</code></span> groups data with the same
first letter of the <span class="code"><code>ShipCountry</code></span> field. All countries starting with the same letter
will be grouped together. When the first letter changes, the <span class="code"><code>FirstLetterGroup</code></span> group
will break.
<br>
One can see also, from attribute settings, that this group will start in a new column, each time
printing its header too, and requires a minimum 200px amount of vertical space in order to prevent
starting on a new page by its own.
<br>
Another interesting element here is the built-in variable <span class="code"><code>FirstLetterGroup_COUNT</code></span> which
counts the number of records in the group. One could notice the variable's name consisting in the
related group's name followed by the <span class="code"><code>_COUNT</code></span> suffix.
<br>
Other report variables, such as <span class="code"><code>FreightSumFirstLetterGroup</code></span> and <span class="code"><code>FreightSumReport</code></span>
were used too, in order to perform statistic calculations.
<br>
<br>
Now let's jump to the next group in the report. The <span class="code"><code>FirstLetterGroup</code></span> group contains records
for all countries starting with the same letter. It means that for groups containing more than one country, records
for different countries are mixed together, and this might be not a very good idea. Obviously, a better data grouping
procedure is required. For instance, to create a child group inside the <span class="code"><code>FirstLetterGroup</code></span> for each distinct
country starting with that letter. So, the information will become more readable and significant than before.
<br>
This is what the second group in the report does, the <span class="code"><code>CountryGroup</code></span>:
<pre>
<group name="CountryGroup" isReprintHeaderOnEachPage="true">
<groupExpression><![CDATA[$F{ShipCountry}]] ></groupExpression>
<groupHeader>
<band height="15">
...
<textField evaluationTime="Group" evaluationGroup="CountryGroup" pattern="EEE, MMM d, yyyy">
<reportElement x="170" y="2" width="100" height="11" style="Sans_Bold"/>
<textElement textAlignment="Right"/>
<textFieldExpression class="java.sql.Timestamp"><![CDATA[$V{DateHighestCountryGroup}]] ></textFieldExpression>
</textField>
</band>
</groupHeader>
<groupFooter>
<band height="15">
...
<textField>
<reportElement mode="Opaque" x="45" y="0" width="25" height="11" backcolor="#c0c0c0" style="Sans_Bold"/>
<textElement textAlignment="Right"/>
<textFieldExpression class="java.lang.Integer"><![CDATA[$V{CountryGroup_COUNT}]] ></textFieldExpression>
</textField>
...
<textField pattern="0.00">
<reportElement mode="Opaque" x="170" y="0" width="60" height="11" backcolor="#c0c0c0" style="Sans_Bold"/>
<textElement textAlignment="Right"/>
<textFieldExpression class="java.lang.Double"><![CDATA[$V{FreightSumCountryGroup}]] ></textFieldExpression>
</textField>
<textField evaluationTime="Auto">
<reportElement mode="Opaque" x="230" y="0" width="40" height="11" backcolor="#c0c0c0" style="Sans_Bold"/>
<textElement textAlignment="Right"/>
<textFieldExpression><![CDATA[msg("{0,number,0.00}%", new Double(100d * $V{FreightSumCountryGroup}.doubleValue() / $V{FreightSumFirstLetterGroup}.doubleValue()))]] ></textFieldExpression>
</textField>
</band>
</groupFooter>
</group>
</pre>
Here one can observe another built-in counting variable: <span class="code"><code>CountryGroup_COUNT</code></span>. Again some other report variables
are used to perform various calculations: <span class="code"><code>DateHighestCountryGroup</code></span>, <span class="code"><code>FreightSumCountryGroup</code></span>,
<span class="code"><code>FreightSumFirstLetterGroup</code></span>. The group header will also be reprinted on each new page.
<br>
<br>
At this stage we can represent data in a user-friendly form, well separated by countries and country first letters, in a
2-columns layout. What else could be done to separate data better than that?
<br>
Well, there is one more thing. What if for a given country there are thousands of records? One after one, after one, and so
on. Thousands of records looking the same, with nothing special to separate them, increasing a lot the eye's effort... It
doesn't sound very good, indeed.
<br>
This is why the third group in the report is present. It is an empty dummy group that breaks after every 5 records, introducing
a supplementary amount of vertical space between the resulting 5-records groups:
<pre>
<group name="BreakGroup">
<groupExpression><![CDATA[new Boolean($V{BreakGroup_COUNT}.intValue() > 5)]] ></groupExpression>
<groupHeader>
<band height="5">
</band>
</groupHeader>
<groupFooter>
<band height="5">
</band>
</groupFooter>
</group></pre>
Once finished the data grouping work, the report template continues with its usual sections, such as <span class="code"><code>title</code></span>,
<span class="code"><code>title</code></span>, <span class="code"><code>pageHeader</code></span>, <span class="code"><code>columnHeader</code></span>, <span class="code"><code>detail</code></span>, <span class="code"><code>columnFooter</code></span>,
<span class="code"><code>pageFooter</code></span> and <span class="code"><code>summary</code></span>.
<br>
At this moment the sample is ready to be ran.
<br>
<br>
<a name="running_sample" href="../../sample.reference/jasper/index.html#running_sample" class="subtitle">Running the Sample</a>
<br>
<br>
Running the sample requires the <a href="http://ant.apache.org/" target="_blank" class="element">Apache Ant</a> library. Make sure that <span class="code"><code>ant</code></span> is already installed on your system (version 1.5 or later).
<br>
In a command prompt/terminal window set the current folder to <span class="code"><code>demo/hsqldb</code></span> within the JasperReports source project and run the <span class="code"><code>> ant runServer</code></span> command.
It will start the HSQLDB server shipped with the JasperReports distribution package. Let this terminal running the HSQLDB server.
<br>
Open a new command prompt/terminal window and set the current folder to <span class="code"><code>demo/samples/jasper</code></span> within the JasperReports source project and run the <span class="code"><code>> ant test view</code></span> command.
<br>
It will generate all supported document types containing the sample report in the <span class="code"><code>demo/samples/jasper/build/reports</code></span> directory.
<br>
Then the report will open in the JasperReports internal viewer.
</span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr>
<td colspan="6" align="right"><a name="csvmetadataexport"></a><a href="#top" class="toc">top</a></td>
</tr>
<tr>
<td colspan="6">
<hr size="1">
</td>
</tr>
<tr valign="top">
<td><img src="../../resources/jr-16x16.png" border="0"></td><td colspan="4"><span class="name">Exporting to CSV Format Using Report Metadata</span></td><td align="right"><span class="copy">Documented by
<a href="mailto:" class="copy"></a></span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr valign="top">
<td>
<br>
</td><td nowrap="true"><span class="label">Description / Goal</span></td><td>
<br>
</td><td colspan="3"><span class="description">
Shows how to export the report to CSV format using metadata associated with report elements at design time, to mark data columns.
</span></td>
</tr>
<tr valign="top">
<td>
<br>
</td><td colspan="1"><span class="label">Since</span></td><td>
<br>
</td><td colspan="3"><span class="description">4.0.0</span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr>
<td>
<br>
</td><td colspan="5"><span class="description">
[Under Construction]
</span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr>
<td colspan="6" align="right"><a name="conditionalstyles"></a><a href="#top" class="toc">top</a></td>
</tr>
<tr>
<td colspan="6">
<hr size="1">
</td>
</tr>
<tr valign="top">
<td><img src="../../resources/jr-16x16.png" border="0"></td><td colspan="4"><span class="name">Conditional Styles</span></td><td align="right"><span class="copy">Documented by
<a href="mailto:shertage@users.sourceforge.net" class="copy">Sanda Zaharia</a></span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr valign="top">
<td>
<br>
</td><td nowrap="true"><span class="label">Description / Goal</span></td><td>
<br>
</td><td colspan="3"><span class="description">
Shows how to define and use a conditional style in a report template.
</span></td>
</tr>
<tr valign="top">
<td>
<br>
</td><td colspan="1"><span class="label">Since</span></td><td>
<br>
</td><td colspan="3"><span class="description">1.2.0</span></td>
</tr>
<tr valign="top">
<td>
<br>
</td><td nowrap="true"><span class="label">Other Samples</span></td><td>
<br>
</td><td colspan="3">
<table width="100%" cellspacing="0" cellpadding="0" border="0">
<tr>
<td><span class="element"><a href="../scriptlet/index.html">/demo/samples/scriptlet</a></span></td>
</tr>
<tr>
<td><span class="element"><a href="../crosstabs/index.html">/demo/samples/crosstabs</a></span></td>
</tr>
<tr>
<td><span class="element"><a href="../list/index.html">/demo/samples/list</a></span></td>
</tr>
</table>
</td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr>
<td>
<br>
</td><td colspan="5"><span class="description">
<a name="styles_overview" href="../../sample.reference/jasper/index.html#styles_overview" class="subtitle">Conditional Styles</a>
<br>
<br>
In JasperReports styles are the bricks used to generate the report elements appearance.
Styles mean anything about fonts, but also mean borders, horizontal and vertical alignment,
element transparency or opacity, background and foreground colors, format patterns, text markup
information, text rotation, and so on... Almost anything needed to set up a complex,
elegant and meaningful element look and feel.
<br>
However, there are situations when the L&F depends on certain conditions determined only at runtime.
The most common example is the necessity to use alternate row colors in a table with a large number
of rows, in order to better distinguish between them. When the total number of rows is unknown at report
design time, or if the row is used in the detail section, a tool for setting up different backgrounds
for the same cell is definitely required.
<br>
And here come conditional styles to get some help.
<br>
<br>
Conditional styles consist in two elements: a <span class="code"><code>Boolean</code></span> condition expression and a style. When the
condition evaluates to <span class="code"><code>true</code></span>, the corresponding style is applied. In the
<a href="#jasper" target="_blank" class="element">Jasper</a> sample one can see a conditional style definition:
<pre>
<style name="Sans_Normal" isDefault="true" fontName="DejaVu Sans" fontSize="8" isBold="false" isItalic="false" isUnderline="false" isStrikeThrough="false"/>
<style name="OrderIdStyle" style="Sans_Normal">
<conditionalStyle>
<conditionExpression><![CDATA[new Boolean($F{OrderID}.intValue() % 10 == 0)]] ></conditionExpression>
<style forecolor="#ff0000" isBold="true"/>
</conditionalStyle>
</style></pre>
The <span class="code"><code>OrderIdStyle</code></span> defined above derives from the <span class="code"><code>Sans_Normal</code></span> parent style.
Usually, elements with <span class="code"><code>OrderIdStyle</code></span> will have the default black forecolor and a normal
font weight. But when the condition expression evaluates to <span class="code"><code>true</code></span> (this happens each time
the <span class="code"><code>OrderID</code></span> field value is a multiple of 10) the element's style changes: the forecolor
becomes red and the font is displayed in bold style.
<br>
Therefore, when applied, a conditional style will override the properties of its parent style.
<br>
<br>
A style definition may contain many conditional styles, any of them inheriting from the parent style.
In this case, all conditions that evaluate to <span class="code"><code>true</code></span> will append their own style properties
to the existing style, in the same order they were defined in the report (the second style will be
appended to the first one, and so on). If more than one conditional style affect the same style property,
the property value will be done by the first conditional style in the styles sequence which evaluates its
condition to <span class="code"><code>true</code></span>.
<br>
Here is a more elaborate example:
<pre>
<style name="alternateStyle" fontName="Arial" forecolor="red">
<conditionalStyle>
<conditionExpression><![CDATA[new Boolean($V{REPORT_COUNT}.intValue() % 2 == 0)]] ></conditionExpression>
<style forecolor="blue"/>
</conditionalStyle>
<conditionalStyle>
<conditionExpression><![CDATA[new Boolean($F{AMOUNT}.intValue() > 10000)]] ></conditionExpression>
<style isBold="true"/>
</conditionalStyle>
<conditionalStyle>
<conditionExpression><![CDATA[new Boolean($F{AMOUNT}.intValue() > 20000)]] ></conditionExpression>
<style isBold="false" isItalic="true"/>
</conditionalStyle>
</style></pre>
One can see above that on each even row the element forecolor becomes blue. More than that, if the <span class="code"><code>AMOUNT</code></span>
field value is greater than 10,000, the second conditional style evaluates to <span class="code"><code>true</code></span>, and the element
displays in bold font (this doesn't affect the red color or blue color set by the first conditional style, because the
forecolor and font weight properties do not interfere). Further, if the <span class="code"><code>AMOUNT</code></span> field value is greater than
20,000, the font style becomes italic, without affecting the font color. But because any value greater than
20,000 is also greater than 10,000, then the <span class="code"><code>isBold="false"</code></span> font weight is no more applied, because
both conditions <span class="code"><code>>10,000</code></span> and <span class="code"><code>>20,000</code></span> evaluate to <span class="code"><code>true</code></span> and <span class="code"><code>isBold="true"</code></span>
style was appended first.
<br>
<br>
<b>Note:</b>
<ul>
<li>By default, the style condition expressions are evaluated during the report filling at the moment they are actually used.
The conditional expression evaluation is performed with the current values of referenced variables and fields in that moment,
regardless of the evaluationTime attribute of the element itself.If the condition expression of the style needs a delayed evaluation,
just like the value of the text field or the image element that uses the conditional style, the
<span class="code"><code>net.sf.jasperreports.style.evaluation.time.enabled</code></span> configuration property should be set to <span class="code"><code>true</code></span>.</li>
<li>Conditional styles cannot be defined in style templates (see the <a href="../templates/index.html" target="_blank" class="element">Templates</a> sample).
This is because style templates store styles with properties available for a large group of reports, while conditional styles
are styles depending on conditions, variables and parameters specific to each report apart. However, styles defined in style
templates can be used as parent styles for conditional styles.</li>
<li>Other examples of conditional styles can be found in <a href="../scriptlet/index.html" target="_blank" class="element">Scriptlet</a>, <a href="../list/index.html" target="_blank" class="element">List</a> and
<a href="../crosstabs/index.html" target="_blank" class="element">Crosstabs</a> samples.</li>
</ul>
</span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
</table>
<br>
<table cellspacing="0" cellpadding="0" border="0" width="100%">
<tr>
<td>
<hr size="1">
</td>
</tr>
<tr>
<td align="center"><span class="copy">© 2001-2010 Jaspersoft Corporation <a href="http://www.jaspersoft.com" target="_blank" class="copy">www.jaspersoft.com</a></span></td>
</tr>
</table>
</body>
</html>
