JasperReports Ultimate Guide - Sample Reference - Schema Reference - Configuration Reference - API (Javadoc)
JasperReports - List Component Sample (version 4.6.0)

Illustrates the usage of the list component element.

Download All Sample Source Files
Browse Sample Source Files on SVN


Main Features in This Sample

Using the Built-in List Component


top
Using the Built-in List ComponentDocumented by Sanda Zaharia


Description / Goal
How to render simple listings using the built-in list component and a subdataset.

Since
3.5.1

Other Samples
/demo/samples/table


The Built-in List Component - Overview

The most common way to process data from datasources/queries different from the report's datasource/query is to use subreports. But working with subreports always requires to create and compile separate report templates, one per each subreport, even for the most simple situation that can be imagined.
For instance, let's consider a subreport containing a single textfield, ready to be used in a detail band. In this case we need a separate report template containing this only textfield to be created and then maintained along with the master report, in order to generate a column of data at fill time. This particular layout is easily recognized as a list of data. So, why not use a dedicated list component instead, which combines the advantages of subreports with a specific mechanism to avoid separate report templates creation and maintenance?
This is the main purpose of the built-in list component. It also provides support for complex content, so that users may define more than single textfields as list content elements, as shown in the following section.

The List Component Schema

According to the components schema, a list needs only two elements in order to become functional: a dataset run and a list content.
  • jr:datasetRun - the dataset run used to store information about list datasource/connection/subdataset and various useful parameters. The jr: namespace prefix may be omitted in the JRXML template.
  • c:listContents - this element stores the layout information for list entries. The layout will be repeated for each row in the dataset. Any JR element may be part of a list content.
<element name="list" substitutionGroup="jr:component">
  <complexType>
    <complexContent>
      <extension base="jr:componentType">
        <sequence>
          <element ref="jr:datasetRun" minOccurs="1" maxOccurs="1" />
          <element ref="c:listContents" />
        </sequence>
        <attribute name="printOrder" use="optional" default="Vertical">
          <simpleType>
            <restriction base="string">
              <enumeration value="Vertical" />
              <enumeration value="Horizontal" />
            </restriction>
          </simpleType>
        </attribute>
        <attribute name="ignoreWidth" type="boolean" use="optional"/>
      </extension>
    </complexContent>
  </complexType>
</element>

<element name="listContents">
  <complexType>
    <sequence>
      <choice minOccurs="0" maxOccurs="unbounded">
        <element ref="jr:break" />
        <element ref="jr:line" />
        <element ref="jr:rectangle" />
        <element ref="jr:ellipse" />
        <element ref="jr:image" />
        <element ref="jr:staticText" />
        <element ref="jr:textField" />
        <element ref="jr:subreport" />
        <element ref="jr:pieChart" />
        <element ref="jr:pie3DChart" />
        <element ref="jr:barChart" />
        <element ref="jr:bar3DChart" />
        <element ref="jr:xyBarChart" />
        <element ref="jr:stackedBarChart" />
        <element ref="jr:stackedBar3DChart" />
        <element ref="jr:lineChart" />
        <element ref="jr:xyLineChart" />
        <element ref="jr:areaChart" />
        <element ref="jr:xyAreaChart" />
        <element ref="jr:scatterChart" />
        <element ref="jr:bubbleChart" />
        <element ref="jr:timeSeriesChart" />
        <element ref="jr:highLowChart" />
        <element ref="jr:candlestickChart" />
        <element ref="jr:meterChart" />
        <element ref="jr:thermometerChart" />
        <element ref="jr:multiAxisChart" />
        <element ref="jr:stackedAreaChart" />
        <element ref="jr:ganttChart" />
        <element ref="jr:elementGroup" />
        <element ref="jr:crosstab" />
        <element ref="jr:frame" />
        <element ref="jr:componentElement" />
        <element ref="jr:genericElement" />
      </choice>
    </sequence>
    <attribute name="height" use="required" type="unsignedInt"/>
    <attribute name="width" use="optional" type="unsignedInt"/>
  </complexType>
</element>
One can see that the list content may contain any of the report elements defined in the JasperReports schema.
The printOrder attribute in the list component specifies how to render the list elements: in a vertical sequence or in a horizontal one. The default value is Vertical.
The ignoreWidth flag is used when the print order is Horizontal to indicate the list behavior when the width set for the list component is reached. Unless the flag is set to true, the list list will break by default when the critical width is reached. By default the flag is unset.
The listContents element can be customized with 2 attributes:
  • height - specifies the height of each list entry and is mandatory.
  • width - specifies the width of each list entry and is optional.
The List Component Sample

This sample shows how to use the built-in list component for both Vertical and Horizontal printing order. In the ListReport.jrxml sample is configured a Vertical list component as follows: 
<componentElement>
  <reportElement x="0" y="25" width="250" height="20"/>
  <c:list 
    xmlns:c="http://jasperreports.sourceforge.net/jasperreports/components" 
    xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports/components http://jasperreports.sourceforge.net/xsd/components.xsd">
    <datasetRun subDataset="Addresses">
      <datasetParameter name="City">
        <datasetParameterExpression><![CDATA[$F{City}]] ></datasetParameterExpression>
      </datasetParameter>
    </datasetRun>
    <c:listContents height="14">
      <frame>
        <reportElement x="0" y="0" width="250" height="14" style="ListRow"/>
        <textField>
          <reportElement x="0" y="2" width="15" height="10" style="Sans_Small"/>
          <textElement textAlignment="Right"/>
          <textFieldExpression class="java.lang.Integer"><![CDATA[$F{Id}]] ></textFieldExpression>
        </textField>
        <textField isStretchWithOverflow="true">
          <reportElement positionType="Float" x="20" y="2" width="110" height="10" style="Sans_Small"/>
          <textElement/>
          <textFieldExpression class="java.lang.String"><![CDATA[$F{FirstName} + " " + $F{LastName}]] ></textFieldExpression>
        </textField>
        <textField isStretchWithOverflow="true">
          <reportElement positionType="Float" x="135" y="2" width="105" height="10" style="Sans_Small"/>
          <textElement/>
          <textFieldExpression class="java.lang.String"><![CDATA[$F{Street}]] ></textFieldExpression>
        </textField>
      </frame>
    </c:listContents>
  </c:list>
</componentElement>
A list containing the ID, name and address is generated for each city in the datasource and list entries are printed in the default Vertical order.
For the horizontally printed list, let's take a look to the HorizontalListReport.jrxml sample: 
<componentElement>
  <reportElement x="0" y="25" width="515" height="40"/>
  <c:list xmlns:c="http://jasperreports.sourceforge.net/jasperreports/components" 
    xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports/components http://jasperreports.sourceforge.net/xsd/components.xsd" printOrder="Horizontal">
    <datasetRun subDataset="Addresses">
      <datasetParameter name="City">
        <datasetParameterExpression><![CDATA[$F{City}]] ></datasetParameterExpression>
      </datasetParameter>
    </datasetRun>
    <c:listContents height="40" width="128">
      <frame>
        <reportElement x="4" y="0" width="120" height="38" style="ListCell" stretchType="RelativeToBandHeight"/>
        <box>
          <topPen lineWidth=".5"/>
          <bottomPen lineWidth=".5"/>
        </box>
        <textField>
          <reportElement x="0" y="2" width="100" height="12" style="Sans_SmallBold"/>
          <textElement/>
          <textFieldExpression><![CDATA["#" + $V{REPORT_COUNT} + " - " + $F{Id}]] ></textFieldExpression>
        </textField>
        <textField isStretchWithOverflow="true">
          <reportElement positionType="Float" x="10" y="14" width="110" height="12" style="Sans_Small"/>
          <textElement/>
          <textFieldExpression class="java.lang.String"><![CDATA[$F{FirstName} + " " + $F{LastName}]] ></textFieldExpression>
        </textField>
        <textField isStretchWithOverflow="true">
          <reportElement positionType="Float" x="10" y="26" width="110" height="12" style="Sans_Small"/>
          <textElement/>
          <textFieldExpression class="java.lang.String"><![CDATA[$F{Street} + ", " + $F{City}]] ></textFieldExpression>
        </textField>
      </frame>
    </c:listContents>
  </c:list>
</componentElement>
Here each list entry is printed one after another horizontally, for each city in the datasource.

Running the Sample

Running the sample requires the Apache Ant library. Make sure that ant is already installed on your system (version 1.5 or later).
In a command prompt/terminal window set the current folder to demo/hsqldb within the JasperReports source project and run the > ant runServer command. It will start the HSQLDB server shipped with the JasperReports distribution package. Let this terminal running the HSQLDB server.
In a command prompt/terminal window set the current folder to demo/samples/list within the JasperReports source project and run the > ant test view command.
It will generate all supported document types containing the sample report in the demo/samples/list/build/reports directory.
Then the generated ListReport will open in the JasperReports internal viewer.


© 2001- Jaspersoft Corporation www.jaspersoft.com