<?xml version="1.0" encoding="UTF-8"?>

<sample>

  <name>jasper</name>
  <title>Jasper Sample</title>
  <description>Shows how different features of the library could be used to generate a complex document.</description>

  <mainFeature ref="groups"/>
  <mainFeature ref="csvmetadataexport"/>
  <mainFeature ref="xlsxmetadataexport"/>
  <mainFeature ref="xlsmetadataexport"/>
  <mainFeature ref="conditionalStylesInReports"/>
  <mainFeature ref="pptxfields"/>
  
  <!-- groups -->
  
  <feature name="groups" title="Data Grouping">
    <description>
How to group data at different levels and perform aggregate calculations using report groups.
    </description>
    <since>0.1.0</since>
    <documentedBy>
      <author>
    	<name>Sanda Zaharia</name>
    	<email>shertage@users.sourceforge.net</email>
      </author>
    </documentedBy>
  	<otherSample ref="datasource"/>
    <content>
<subtitle name="grouping_overview">Grouping Data in JasperReports</subtitle>
<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 <code>GROUP BY</code> 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 <code>&lt;group/&gt;</code> 
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 &lt;groupFooter&gt; and &lt;groupHeader&gt; 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 <code>&lt;sortField/&gt;</code> element.</li>
</ul>
<subtitle name="attributes">Group Attributes</subtitle>
<br/>
<br/>
Any group in a report can be customized through its attributes:
<ul>
<li><code>name</code> - Acts as a group identifier. This attribute is mandatory, and should be unique per report.</li>
<li><code>isStartNewColumn</code> - Instructs the engine to start a new column when a new group starts. The default 
value is <code>false</code>.</li>
<li><code>isStartNewPage</code> - Instructs the engine to start a new page when a new group starts. The default 
value is <code>false</code>.</li>
<li><code>isResetPageNumber</code> - If <code>true</code>, when a new group starts, the built-in <code>PAGE_NUMBER</code> 
variable will be reset. The default value is <code>false</code>.</li>
<li><code>isReprintHeaderOnEachPage</code> - Instructs the engine to print the group header on each page containing 
the group data. The default value is <code>false</code>.</li>
<li><code>minHeightToStartNewPage</code> - 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><code>footerPosition</code> - Specifies the rendering position of the group footer on the page. Possible values are: 
<code>Normal</code>, <code>StackAtBottom</code>, <code>ForceAtBottom</code>, <code>CollateAtBottom</code>. 
The default value is <code>Normal</code>.</li>
<li><code>keepTogether</code> - If <code>true</code>, prevents the group from splitting on its first break attempt. 
The default value is <code>false</code>.</li>
</ul>
<subtitle name="variables">Data Grouping and Report Variables</subtitle>
<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><code>name</code> - The variable's name used as unique identifier. It is mandatory.</li>
<li><code>class</code> - The class name of the variable's values. The default class is <code>java.lang.String</code></li>
<li><code>resetType</code> - Indicates when the variable should be reinitialized during the report-filling process. Possible 
values are:<code>None</code>, <code>Report</code>, <code>Page</code>, <code>Column</code>, <code>Group</code>. The default 
value is <code>Report</code>.</li>
<li><code>resetGroup</code> - If the <code>resetType</code> is set to <code>Group</code>, indicates the name of the group 
which triggers the variable reinitializing each time it breaks.</li>
<li><code>incrementType</code> - Indicates when the variable should be incremented during the report-filling process. Possible 
values are:<code>None</code>, <code>Report</code>, <code>Page</code>, <code>Column</code>, <code>Group</code>. The default 
value is <code>None</code>.</li>
<li><code>incrementGroup</code> - If the <code>incrementType</code> is set to <code>Group</code>, indicates the name of the group 
which triggers the variable increment each time it breaks.</li>
<li><code>calculation</code> - Indicates the built-in calculation type to be performed on the variable expression value. Possible 
values are:<code>Nothing</code>, <code>Count</code>, <code>DistinctCount</code>, <code>Sum</code>, <code>Average</code>, <code>Lowest</code>, 
<code>Highest</code>, <code>StandardDeviation</code>, <code>Variance</code>, <code>System</code>, <code>First</code>. The default 
value is <code>Nothing</code>.</li>
<li><code>incrementerFactoryClass</code> - 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://community.jaspersoft.com/wiki/jasperreports-library-tutorial#Variables">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 <code>_COUNT</code> suffix. In this sample we'll find some usage examples 
of this group counting variables. 
<br/>
<br/>
<subtitle name="jasper_sample">The Jasper Sample</subtitle>
<br/>
<br/>
This sample illustrates how groups can be used to produce documents with complex data grouping in a 
multicolumn layout. The <code>reports/FirstJasper.jrxml</code> 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 <code>columnCount="2"</code> attribute setting in the 
<code>&lt;jasperReport/&gt;</code> element.
<br/>
<br/>
Further, one can see the report query retrieving data ordered by the <code>ShipCountry</code> field: 
<pre><![CDATA[
  <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><![CDATA[
  <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><![CDATA[
<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}%", 
            100d * $V{FreightSumFirstLetterGroup} / $V{FreightSumReport})
          ]] >
        </textFieldExpression>
      </textField>
    </band>
  </groupFooter>
</group>]]></pre>
According to the group expression above, the <code>FirstLetterGroup</code> groups data with the same 
first letter of the <code>ShipCountry</code> field. All countries starting with the same letter 
will be grouped together. When the first letter changes, the <code>FirstLetterGroup</code> 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 <code>FirstLetterGroup_COUNT</code> 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 <code>_COUNT</code> suffix.
<br/>
Other report variables, such as <code>FreightSumFirstLetterGroup</code> and <code>FreightSumReport</code> 
were used too, in order to perform statistic calculations.
<br/>
<br/>
Now let's jump to the next group in the report. The <code>FirstLetterGroup</code> 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 <code>FirstLetterGroup</code> 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 <code>CountryGroup</code>: 
<pre><![CDATA[
<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}%", 100d * $V{FreightSumCountryGroup} / $V{FreightSumFirstLetterGroup})]] ></textFieldExpression>
    </textField>
  </band>
  </groupFooter>
</group>
]]></pre>
Here one can observe another built-in counting variable: <code>CountryGroup_COUNT</code>. Again some other report variables 
are used to perform various calculations: <code>DateHighestCountryGroup</code>, <code>FreightSumCountryGroup</code>, 
<code>FreightSumFirstLetterGroup</code>. 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><![CDATA[
  <group name="BreakGroup">
    <groupExpression><![CDATA[$V{BreakGroup_COUNT} > 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 <code>title</code>, 
<code>title</code>, <code>pageHeader</code>, <code>columnHeader</code>, <code>detail</code>, <code>columnFooter</code>, 
<code>pageFooter</code> and <code>summary</code>.
<br/>
At this moment the sample is ready to be ran.
<br/>
<br/>
<subtitle name="running_sample">Running the Sample</subtitle>
<br/>
<br/>
Running the sample requires the <a href="http://ant.apache.org/">Apache Ant</a> library. Make sure that <code>ant</code> is already installed on your system (version 1.5 or later).
<br/>
In a command prompt/terminal window set the current folder to <code>demo/hsqldb</code> within the JasperReports source project and run the <code>&gt; ant runServer</code> 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 <code>demo/samples/jasper</code> within the JasperReports source project and run the <code>&gt; ant test view</code> command.
<br/>
It will generate all supported document types containing the sample report in the <code>demo/samples/jasper/build/reports</code> directory. 
<br/>
Then the report will open in the JasperReports internal viewer.

    </content>
  </feature>

  <!-- csvmetadataexport -->
  
  <feature name="csvmetadataexport" title="Exporting to CSV Format Using Report Metadata">
    <description>
Shows how to export the report to CSV format using metadata associated with report elements at design time, to mark data columns.
    </description>
    <since>4.0.0</since>
    <documentedBy>
      <author>
    	<name>Sanda Zaharia</name>
    	<email>shertage@users.sourceforge.net</email>
      </author>
    </documentedBy>
    <content>
<subtitle name="excel_output">Pixel-Perfect Requirement and Excel Output Format</subtitle>
<br/>
<br/>
Documents stored in a <api href="net/sf/jasperreports/engine/JasperPrint.html">JasperPrint</api> object are ready to be printed out in a pixel-perfect 
representation. This means that objects' own dimensions, absolute and relative positions within the document are completely preserved. The pixel-perfect 
representation is a must for the read-only or layout-oriented output formats, such as PDF or Graphics2D, but it could generate some inconvenients for 
data-oriented output formats like the Excel-based ones. In this case more important than the pixel-perfectness of the document is to allow 
the generated data in the report to be properly manipulated by the Excel engine, therefore to generate as much as possible Excel-like documents. When opening 
an Excel document, ideally is to see:
<ul>
<li>data with correct field type (numeric, currency, date, etc);</li>
<li>no extra columns/rows added by the grid generation constraints;</li>
<li>no page margins and other padding settings;</li>
<li>no page numbers;</li>
<li>no repetition of page headers;</li>
<li>data organized in columns/rows in order to allow formula calculations;</li>
<li>some report sections to be excluded/hidden;</li>
<li>outline data grouping;</li>
<li>etc.</li>
</ul>
<subtitle name="csv_metadata_export">The CSV Metadata Exporter</subtitle>
<br/>
<br/>
A possibility to extract relevant data from a pixel-perfect <api href="net/sf/jasperreports/engine/JasperPrint.html">JasperPrint</api> object in order to generate a 
data-oriented document, is to customize the export. Some properties are needed to tell the JR engine which elements should be exported and where should they be placed 
in the current sheet. The <api href="net/sf/jasperreports/engine/export/JRCsvMetadataExporter.html">JRCsvMetadataExporter</api> is designed to process such kind of 
metadata information and to generate consistent columns of data, with or without column headers on their top. 
<br/>
Before starting the export work, the CSV metadata exporter looks for the presence of the column names by calling the 
<api href="net/sf/jasperreports/export/CsvMetadataExporterConfiguration.html#getColumnNames()">getColumnNames()</api> exporter configuration setting.
One can populate this setting either directly, using the APIs, or by collecting values from the 
<a href="../../config.reference.html#net.sf.jasperreports.export.csv.column.names.{suffix}">net.sf.jasperreports.export.csv.column.names.{suffix}</a> 
properties at report level. If present, they provide a comma-separated list of column names, each one referencing a column that should be exported. For 
accurate results it's recommended that the column names in the list to follow the same order as the original columns.
<br/>
Below is an example of populating the column names via JasperReports APIs:
<pre><![CDATA[
JRCsvMetadataExporter exporter = new JRCsvMetadataExporter();
SimpleCsvMetadataExporterConfiguration configuration = new SimpleCsvMetadataExporterConfiguration();
configuration.setColumnNames(new String[]{"Name,Id"});
exporter.setConfiguration(configuration);]]></pre>
It ensures that only 2 columns will be printed out: the column with names and the column with Ids.   
<br/>
Now, that we have the column names, it's time to see which elements will be exported into these columns and how. Let's introduce the other metadata properties:
<ul>
<li><a href="../../config.reference.html#net.sf.jasperreports.export.csv.column.name">net.sf.jasperreports.export.csv.column.name</a> 
- this is an important element-level property. If the 
<a href="../../config.reference.html#net.sf.jasperreports.export.csv.column.names.{suffix}">net.sf.jasperreports.export.csv.column.names.{suffix}</a> properties are not 
present in the report, this property specifies the name of an exported column and assumes that the current element will be placed in that column. If there are defined  
<code>net.sf.jasperreports.export.csv.column.names.{suffix}</code> properties in the 
report, then the column name specified by the <code>net.sf.jasperreports.export.csv.column.name</code> 
property must be one of the names declared in the <code>net.sf.jasperreports.export.csv.column.names.{suffix}</code> properties. The current element will be placed in   
that column.</li>
<li><a href="../../config.reference.html#net.sf.jasperreports.export.csv.write.header">net.sf.jasperreports.export.csv.write.header</a> - 
a report-level flag property indicating whether the column names should be exported as column headers or not. The default value is <code>false</code>.</li>
<li><a href="../../config.reference.html#net.sf.jasperreports.export.csv.repeat.value">net.sf.jasperreports.export.csv.repeat.value</a> - 
an element-level flag property indicating whether the value associated to that column should be repeated or not when it is missing.</li>
<li><a href="../../config.reference.html#net.sf.jasperreports.export.csv.data">net.sf.jasperreports.export.csv.data</a> - 
element-level property containing the exported value for that element. By default is considered the text value of the report element itself.</li>
</ul>
In this sample only five columns are exported to CSV format: <code>ShipCountry</code>, <code>Order</code>, <code>ShipCity</code>, <code>ShipRegion</code> and 
<code>OrderDate</code>. Column headers are not exported and for the <code>ShipCity</code> column the exported data is customized using the 
<a href="../../config.reference.html#net.sf.jasperreports.export.csv.data">net.sf.jasperreports.export.csv.data</a> property. All 
these settings apply to the &lt;detail/&gt; section:
<pre><![CDATA[
<detail>
  <band height="13">
  ...
    <textField>
      <reportElement style="OrderIdStyle" x="1" y="0" width="35" height="11">
        <property name="net.sf.jasperreports.export.csv.column.name" value="Order"/>
        ...
      </reportElement>
      ...
    </textField>
    <textField textAdjust="StretchHeight">
      <reportElement positionType="Float" x="40" y="0" width="110" height="11">
        <property name="net.sf.jasperreports.export.csv.column.name" value="ShipCity"/>
        ...
        <propertyExpression name="net.sf.jasperreports.export.csv.data"><![CDATA[$F{ShipCity}]] ></propertyExpression>
        ...
      </reportElement>
    </textField>
    <textField isBlankWhenNull="true">
      <reportElement x="155" y="0" width="25" height="11">
        <property name="net.sf.jasperreports.export.csv.column.name" value="ShipRegion"/>
        ...
      </reportElement>
      ...
    </textField>
    <textField pattern="dd/MM/yyyy">
      <reportElement x="185" y="0" width="50" height="11">
        <property name="net.sf.jasperreports.export.csv.column.name" value="OrderDate"/>
        ...
      </reportElement>
      ...
    </textField>
    <textField pattern="0.00">
      <reportElement x="235" y="0" width="35" height="11">
        <property name="net.sf.jasperreports.export.csv.column.name" value="Freight"/>
        ...
      </reportElement>
      ...
    </textField>
    ...
  </band>
</detail>]]></pre>
After running the <code>&gt;ant test view</code> command the data-centric document exported with the CSV metadata exporter will be available in the 
<code>demo/samples/jasper/build/reports</code> directory as <code>FirstJasper.metadata.csv</code>.
    </content>
  </feature>

  <!-- xlsxmetadataexport -->
  
  <feature name="xlsxmetadataexport" title="Exporting to XLSX Format Using Report Metadata">
    <description>
Shows how to export the report to XLSX format using metadata associated with report elements at design time, to mark data columns.
    </description>
    <since>6.20.0</since>
    <documentedBy>
      <author>
    	<name>Sanda Zaharia</name>
    	<email>shertage@users.sourceforge.net</email>
      </author>
    </documentedBy>
    <content>
<subtitle name="xlsx_metadata_export">The Excel (.xlsx) Metadata Exporter</subtitle>
<br/>
<br/>
As shown in the section <a href="#csv_metadata_export">above</a>, the CSV metadata exporter is a very useful tool when data-oriented outputs are preferred. The only 
problem is that any format setting is dropped when the CSV file is saved. CSVs do not store layout and style, they only keep data safe. Sometimes this is not enough 
for complex documents. In vary situations data need to be presented in a more specific way, column headers should be centered, totals should appear in a bold style, some cells 
might require a particular background, etc. More than that, if we want to perform calculations on data, we need to know the associated data type. And another limitation is 
that the CSV format cannot be used to export graphic elements, like images and shapes. 
<br/>
In such cases we have to keep together relevant data with their style and formatting information. Since the CSV metadata exporter is limited to pure text-data only, 
another metadata-based exporter can be used to solve the problem. This is the <api href="net/sf/jasperreports/engine/export/XlsxMetadataExporter.html">XlsxMetadataExporter</api> 
that provides a columnar Excel (XLSX) output. It relies on equivalent metadata properties and parameters having the same meanings, but dedicated to the XLSX output format:
<ul>
<li><a href="../../config.reference.html#net.sf.jasperreports.export.xls.column.names.{suffix}">net.sf.jasperreports.export.xls.column.names.{suffix}</a></li>
<li><a href="../../config.reference.html#net.sf.jasperreports.export.xls.column.name">net.sf.jasperreports.export.xls.column.name</a></li>
<li><a href="../../config.reference.html#net.sf.jasperreports.export.xls.write.header">net.sf.jasperreports.export.xls.write.header</a></li>
<li><a href="../../config.reference.html#net.sf.jasperreports.export.xls.repeat.value">net.sf.jasperreports.export.xls.repeat.value</a></li>
<li><a href="../../config.reference.html#net.sf.jasperreports.export.xls.data">net.sf.jasperreports.export.xls.data</a> - in the XLSX metadata export this property 
is applicable for text elements only.</li>
</ul>
Another property, which is specific to XLSX metadata export only, is 
<a href="../../config.reference.html#net.sf.jasperreports.export.xls.column.width.metadata">net.sf.jasperreports.export.xls.column.width.metadata</a>. This is useful 
when we choose to export column names as column headers longer than the column width available for the non-metadata XLSX export, without affecting the non-metadata XLSX export.
<br/>
<br/>
In this sample the following columns are exported to XLSX format: <code>JasperImage</code> (which is a picture), <code>LineShape</code> (a shape element), 
<code>ShipCountry</code>, <code>Order</code>, <code>ShipCity</code>, <code>ShipRegion</code> and <code>OrderDate</code>. Column headers are exported too, 
and for the <code>ShipCity</code> column the exported data is customized using the <a href="../../config.reference.html#net.sf.jasperreports.export.xls.data">net.sf.jasperreports.export.xls.data</a> 
property. 
<br/>
<br/>
The elements were set as in the following example:
<pre><![CDATA[
<groupHeader>
  <band height="15">
    <line>
      <reportElement x="0" y="14" width="270" height="1" uuid="0d5b92e0-b24d-4223-9071-deee35fbc758">
        <property name="net.sf.jasperreports.export.xls.repeat.value" value="true"/>
        <property name="net.sf.jasperreports.export.xls.column.name" value="LineShape"/>
      </reportElement>
    </line>
    <textField>
      <reportElement style="Sans_Bold" x="10" y="2" width="150" height="11" uuid="9f8585df-e218-4084-baf2-6d190021be29">
        ...
        <property name="net.sf.jasperreports.export.xls.column.name" value="ShipCountry"/>
        <property name="net.sf.jasperreports.export.xls.column.width.metadata" value="100"/>
        <property name="net.sf.jasperreports.export.xls.repeat.value" value="true"/>
        ...
      </reportElement>
      <textFieldExpression><![CDATA[$F{ShipCountry}]] ></textFieldExpression>
    </textField>
    ...
  </band>
</groupHeader>

...

<title>
  <band height="100">
    <elementGroup>
      ...
      <image scaleImage="Clip">
        <reportElement key="TransparentImage" x="0" y="5" width="165" height="40" uuid="a16a2532-d0b4-436c-b004-6928225490f2">
          <property name="net.sf.jasperreports.export.xls.repeat.value" value="true"/>
          <property name="net.sf.jasperreports.export.xls.column.name" value="JasperImage"/>
          <property name="net.sf.jasperreports.export.xls.column.width.metadata" value="200"/>
        </reportElement>
        <imageExpression><![CDATA["jasperreports.png"]] ></imageExpression>
        <hyperlinkTooltipExpression><![CDATA["The JasperReports Logo"]] ></hyperlinkTooltipExpression>
      </image>
    </elementGroup>
    ...
  </band>
</title>

...

<detail>
  <band height="13">
  ...
    <textField>
      <reportElement style="OrderIdStyle" x="1" y="0" width="35" height="11">
        ...
        <property name="net.sf.jasperreports.export.xls.column.name" value="Order"/>
        <property name="net.sf.jasperreports.export.xls.column.width.metadata" value="50"/>
        ...
      </reportElement>
      ...
    </textField>
    <textField textAdjust="StretchHeight">
      <reportElement positionType="Float" x="40" y="0" width="110" height="11">
        ...
        <property name="net.sf.jasperreports.export.xls.column.name" value="ShipCity"/>
        ...
        <propertyExpression name="net.sf.jasperreports.export.xls.data"><![CDATA[$F{ShipCity}]] ></propertyExpression>
        ...
      </reportElement>
    </textField>
    <textField isBlankWhenNull="true">
      <reportElement x="155" y="0" width="25" height="11">
        ...
        <property name="net.sf.jasperreports.export.xls.column.name" value="ShipRegion"/>
        <property name="net.sf.jasperreports.export.xls.column.width.metadata" value="60"/>
        ...
      </reportElement>
      ...
    </textField>
    <textField pattern="dd/MM/yyyy">
      <reportElement x="185" y="0" width="50" height="11">
        ...
        <property name="net.sf.jasperreports.export.xls.column.name" value="OrderDate"/>
        <property name="net.sf.jasperreports.export.xls.column.width.metadata" value="100"/>
        ...
      </reportElement>
      ...
    </textField>
    <textField pattern="0.00">
      <reportElement x="235" y="0" width="35" height="11">
        ...
        <property name="net.sf.jasperreports.export.xls.column.name" value="Freight"/>
        <property name="net.sf.jasperreports.export.xls.column.width.metadata" value="60"/>
        ...
      </reportElement>
      ...
    </textField>
    ...
  </band>
</detail>]]></pre>
After running the <code>&gt;ant test view</code> command the data-centric document exported with the XLSX metadata exporter will be available in the 
<code>demo/samples/jasper/build/reports</code> directory in 2 forms: <code>FirstJasper.singleSheet.metadata.xlsx</code> - as single sheet document, and 
<code>FirstJasper.multiSheet.metadata.xlsx</code> - as multisheet Excel document. Notice the differences in text formatting between these files and the 
<code>FirstJasper.metadata.csv</code> CSV document.
    </content>
  </feature>

  <!-- xlsmetadataexport -->
  
  <feature name="xlsmetadataexport" title="Exporting to XLS Format Using Report Metadata">
    <description>
Shows how to export the report to XLS format using metadata associated with report elements at design time, to mark data columns.
    </description>
    <since>4.0.0</since>
    <documentedBy>
      <author>
    	<name>Sanda Zaharia</name>
    	<email>shertage@users.sourceforge.net</email>
      </author>
    </documentedBy>
    <content>
<subtitle name="xls_metadata_export">The Excel 2003 Metadata Exporter</subtitle>
<br/>
<br/>
This metadata  exporter can be used to export data in an older Microsoft Excel format (Excel 2003, or ".xls"). It is strongly recommended to use the XLSX metadata exporter instead. 
The XLSX metadata exporter is described in the <a href="#xlsx_metadata_export">The Excel (.xlsx) Metadata Exporter</a> feature section of this document. All metadata export 
properties presented in the <a href="#xlsx_metadata_export">The Excel (.xlsx) Metadata Exporter</a> feature are also applicable for the 
<api href="net/sf/jasperreports/engine/export/JRXlsMetadataExporter.html">Excel 2003 metadata exporter</api>, except 
<a href="../../config.reference.html#net.sf.jasperreports.export.xls.column.width.metadata">net.sf.jasperreports.export.xls.column.width.metadata</a>.
<br/>
<br/>
After running the <code>&gt;ant test view</code> command the data-centric document exported with the Excel 2003 metadata exporter will be available in the 
<code>demo/samples/jasper/build/reports</code> directory as <code>FirstJasper.metadata.xls</code>.
    </content>
  </feature>

  <!-- conditionalStylesInReports -->
  
  <feature name="conditionalStylesInReports" title="Conditional Styles in Reports">
    <description>
Shows how to define and use a conditional style in a report template.
    </description>
    <since>1.2.0</since>
    <documentedBy>
      <author>
    	<name>Sanda Zaharia</name>
    	<email>shertage@users.sourceforge.net</email>
      </author>
    </documentedBy>
  	<otherSample ref="scriptlet"/>
  	<otherSample ref="crosstabs"/>
  	<otherSample ref="list"/>
  	<otherSample ref="query"/>
    <content>
<subtitle  name="styles_overview">Conditional Styles</subtitle>
<br/>
<br/>
In JasperReports using styles represents the most common way 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&amp;F depends on certain conditions determined only at runtime. 
A 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. They can be defined either in the report itself, or, for some 
particular values, in style templates.
<br/>
For more information about conditional styles defined in style templates you could take a look at the 
<code><a href="../query/index.html#conditionalStylesInTemplates" target="_blank">Query</a></code> sample.
<br/>
Next we'll present conditional styles defined in reports.
<br/>
<br/>
Conditional styles consist in two elements: a <code>Boolean</code> condition expression and a style. When the 
condition evaluates to <code>true</code>, the corresponding style is applied. In the 
<a href="#jasper">Jasper</a> sample one can see a conditional style definition:
<pre><![CDATA[
  <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[$F{OrderID} % 10 == 0]] ></conditionExpression>
      <style forecolor="#ff0000" isBold="true"/>
    </conditionalStyle>
  </style>]]></pre>
The <code>OrderIdStyle</code> defined above derives from the <code>Sans_Normal</code> parent style. 
Usually, elements with <code>OrderIdStyle</code> will have the default black forecolor and a normal 
font weight. But when the condition expression evaluates to <code>true</code> (this happens each time  
the <code>OrderID</code> 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 <code>true</code> 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 <code>true</code>.
<br/>
Here is a more elaborate example:
<pre><![CDATA[
<style name="alternateStyle" fontName="Arial" forecolor="red">
  <conditionalStyle>
    <conditionExpression><![CDATA[$V{REPORT_COUNT} % 2 == 0]] ></conditionExpression>
    <style forecolor="blue"/>
  </conditionalStyle>
  <conditionalStyle>
    <conditionExpression><![CDATA[$F{AMOUNT} > 10000]] ></conditionExpression>
    <style isBold="true"/>
  </conditionalStyle>
  <conditionalStyle>
    <conditionExpression><![CDATA[$F{AMOUNT} > 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 <code>AMOUNT</code> 
field value is greater than 10,000, the second conditional style evaluates to <code>true</code>, 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 <code>AMOUNT</code> 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 <code>isBold="false"</code> font weight is no more applied, because 
both conditions <code>&gt;10,000</code> and <code>&gt;20,000</code> evaluate to <code>true</code> and <code>isBold="true"</code> 
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 
<code>net.sf.jasperreports.style.evaluation.time.enabled</code> configuration property should be set to <code>true</code>.</li>
<li>Conditional styles may be defined in style templates only when the condition expression is a simple reference to a Boolean report parameter, field or variable 
(see <code><a href="../query/index.html#conditionalStylesInTemplates" target="_blank">Query</a></code> sample). 
Also, styles defined in style templates can be used as parent styles for conditional styles defined in the report.</li>
<li>Other examples of conditional styles can be found in <code><a href="../query/index.html#conditionalStylesInTemplates" target="_blank">Query</a></code>, 
<code><a href="../scriptlet/index.html">Scriptlet</a></code>, <code><a href="../list/index.html">List</a></code> and 
<code><a href="../crosstabs/index.html">Crosstabs</a></code> samples.</li>
</ul>
 </content>
  </feature>

  <!-- pptxfields -->
  
  <feature name="pptxfields" title="Updating current date and slide numbers in PPTX export">
    <description>
Shows how to use PPTX fields to update some predefined values such as current date or slide number.
    </description>
    <since>6.8.0</since>
    <documentedBy>
      <author>
    	<name>Sanda Zaharia</name>
    	<email>shertage@users.sourceforge.net</email>
      </author>
    </documentedBy>
  	<otherSample ref="i18n"/>
    <content>
<subtitle  name="pptx_fields">Exporting text elements as PPTX fields</subtitle>
<br/>
<br/>
The following situations may frequently occur when working with PowerPoint presentations:
<ul>
<li>when a slide is removed from a presentation that displays slide numbers on each page, the remaining slides should rearrange their slide number accordingly;</li>
<li>a presentation needs to display the current date each time it is running.</li>
</ul>
In such cases we need values to be automatically updated, and this can be done if text elements are 
exported as PPTX fields with specific behavior. To do so, one can set the following text element property:
<br/>
<br/>
<code>net.sf.jasperreports.export.pptx.field.type</code>
<br/>
<br/>
There are 2 possible values for this property:
<ul>
<li><code>slidenum</code> - applies to text elements that store numeric values, and associates these elements with autogenerated slide numbers</li>
<li><code>datetime</code> - applies to text elements that store date/time values and associates these elements with the current date/time</li>
</ul>
When the property is set as <code>datetime</code>, the following date/time patterns can be processed to display the current date in PPTX:
<ul>
<li><code>MM/dd/yyyy</code></li>
<li><code>EEEE, MMMM dd, yyyy</code></li>
<li><code>dd MMMM yyyy</code></li>
<li><code>MMMM dd, yyyy</code></li>
<li><code>dd-MMM-yy</code></li>
<li><code>MMMM yy</code></li>
<li><code>MMM-yy</code></li>
<li><code>MM/dd/yyyy hh:mm a</code></li>
<li><code>MM/dd/yyyy hh:mm:ss a</code></li>
<li><code>HH:mm</code></li>
<li><code>HH:mm:ss</code></li>
<li><code>hh:mm a</code></li>
<li><code>hh:mm:ss a</code></li>
</ul>
If none of the above patterns are set for the element, the date/time will be displayed using the default pattern of the PPTX viewer.
<br/>
<br/>
<subtitle  name="pptx_field_example">PPTX field example</subtitle>
<br/>
<br/>
The following example can be found in the <code>FirstJasper.jrxml</code> file:
<pre><![CDATA[
  <textField>
    <reportElement x="200" y="5" width="75" height="20" uuid="ef35b54f-9b68-4369-84d9-5d532b22b4da">
      <property name="net.sf.jasperreports.export.pptx.field.type" value="slidenum"/>
    </reportElement>
    <textElement textAlignment="Right">
      <font size="14"/>
    </textElement>
    <textFieldExpression><![CDATA[$V{PAGE_NUMBER}]] ></textFieldExpression>
  </textField>]]></pre>
At export time this text element will be translated into a PPTX field that generates automatic slide number.
<br/>
<br/>
Another example of a <code>datetime</code> PPTX field can be found in the <a href="../i18n/index.html#pptx_field_example">i18n</a> sample.
 </content>
  </feature>

</sample>
