Post 9: iReport: Adding a simple header to your report

Adding a simple header to your report 
A header normally appears on every page of your report. The header of your report contains the data that was used to generate the report. For example, if you generate a "Monthly Customer Invoices" report, the header will tell you the name of the customer and the month for which you generated a particular copy of the report.

The header consists of a number of name-value pairs, in which the name is actually the label of a field (for example, the label can be "Customer Name" when the header shows the name of a customer) and is normally simple text. On the other hand, the value in the name-value pair is actually some application data (for example, actual name of a customer) that comes from a data source such as a relational database.In this recipe, you will learn how to place a header just below the title of your report. As an example, I am going to generate the header of a report containing list of invoices issued to a particular customer in a specific month. 

Getting ready

In order to work with this recipe, you will need the PostgreSQL database. Refer to the Post6:  iReport: Installation of PostgreSQL, which shows how you can install and run PostgreSQL. Note that your installation of PostgreSQL should be up and running before you proceed.

To inserting following the required data in database jasperdb1(only if data is not present ) then refer Post 8: iReport: Using dynamic titles thatcan change during report processing for Create a table named CustomerInvoices, Create table and copy sample data into the database.

  

You will connect iReport to your database hosted on PostgreSQL using the steps described in the Post 7:  iReport: Creating a report from relational data.

How to do it...

1. Create the ASimpleHeader.jrxml file such that the Designer tab of iReport shows an empty report with just a title (Monthly Customer Invoices).

 

2. You are about to enhance the report by adding a header. You can start by placing the label for your first name-value pair. Use the palette of components on the right of the main iReport window and drag a static text component into the Page Header section in the Designer tab of your report.

 

3. Double-click the static text and enter a label for your component (for example, "Customer Name"). Now use the mouse or keyboard arrow keys to place the static text appropriately, as shown in the following screenshot:

 

4. Now you will add a value field for your name-value pair. Drag a text field from the palette of components into the Page Header section and place it to the right of the Static Text labeled "Customer Name." A text field is just like static text except that it is attached to some data source at the backend through a database query or an XPath expression.

5. Open the Report query window by clicking the report query button to the right of the Preview tab. unfortunately, it is a bit difficult to find this button in iReport as it shows no tool tip when you move your mouse over it. Its icon is similar in shape to a standard database icon and looks like . A Report query window will appear, as shown in the following screenshot:

 

 

6. Enter the following SQL query into the Report query window:

SELECT  *  from "public"."CustomerInvoices"

WHERE "public"."CustomerInvoices"."CustomerName" = 'iTwine Technologies'

AND "public"."CustomerInvoices"."InvoicePeriod" = 'Mar14'

7. The Report query window will automatically fetch all columns of the CustomerInvoices table according to the condition given in the SQL query.You will see that all the columns of the CustomerInvoices table (that is CustomerName, CustomerPhone, InvoicePeriod, ProductName, and TotalValue) will be displayed in the lower part of the Report query window, as shown next. Click the OK button and exit the Report query window.

8. Now you have to link the CustomerName column of the CustomerInvoices table with the text field you placed into your Page Header section in step 5. Right-click the text field and select the Edit Expression option from the pop-up window, as shown here:
 
9. An Expression editor window will open. Delete the existing text ($F(field)) from the Field Expression window and then double-click the CustomerName field in the second column of the lower half of the Field Expression window and click Apply. This will attach the CustomerName column of the CustomerInvoices table with the text field. 

10. Now drag another static text and text field components as per steps 2, 3, and 4 for your second name-value pair (that is, Invoice Period = "invoicing month") as shown next. This time the static text will get Invoice Period as its label and the text field will link to the InvoicePeriod column of the CustomerInvoices table.



11. Repeat steps 8 and 9 to attach the InvoicePeriod column with the Invoice Period text field of your Page Header section. Eventually, your header will look like the following:
 

12. Switch to the Preview tab; you will see the preview of your report as shown here: 




How it works...
Open the XML tab of your report and you will see the following XML: 

1:  <?xml version="1.0" encoding="UTF-8"?>  
2:  <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="ASimpleHeader" language="groovy" pageWidth="595" pageHeight="842" columnWidth="555" leftMargin="20" rightMargin="20" topMargin="20" bottomMargin="20" uuid="5b714e3c-f08f-4a45-902f-2808f1477595">  
3:       <property name="ireport.zoom" value="1.0"/>  
4:       <property name="ireport.x" value="0"/>  
5:       <property name="ireport.y" value="0"/>  
6:       <queryString>  
7:            <![CDATA[ SELECT * from "public"."CustomerInvoices"  
8:  WHERE "public"."CustomerInvoices"."CustomerName" = 'iTwine Technologies'  
9:  AND "public"."CustomerInvoices"."InvoicePeriod" = 'Mar14']]>  
10:       </queryString>  
11:       <field name="InvoiceID" class="java.lang.Integer"/>  
12:       <field name="CustomerName" class="java.lang.String"/>  
13:       <field name="ProductName" class="java.lang.String"/>  
14:       <field name="InvoiceValue" class="java.lang.Float"/>  
15:       <field name="InvoicePeriod" class="java.lang.String"/>  
16:       <background>  
17:            <band splitType="Stretch"/>  
18:       </background>  
19:       <title>  
20:            <band height="75" splitType="Stretch">  
21:                 <staticText>  
22:                      <reportElement uuid="9156aec0-95cb-4f04-8674-8af885eb22cc" x="110" y="21" width="335" height="39"/>  
23:                      <textElement>  
24:                           <font fontName="Verdana" size="24"/>  
25:                      </textElement>  
26:                      <text><![CDATA[Monthly Customer Invoices]]></text>  
27:                 </staticText>  
28:            </band>  
29:       </title>  
30:       <pageHeader>  
31:            <band height="41" splitType="Stretch">  
32:                 <staticText>  
33:                      <reportElement uuid="02e52df6-c992-467e-b593-21b036046741" x="10" y="10" width="100" height="20"/>  
34:                      <textElement/>  
35:                      <text><![CDATA[Customer Name]]></text>  
36:                 </staticText>  
37:                 <textField>  
38:                      <reportElement uuid="af016897-6ce8-4470-8449-47ec720ea302" x="110" y="10" width="100" height="20"/>  
39:                      <textElement/>  
40:                      <textFieldExpression><![CDATA[$F{CustomerName}]]></textFieldExpression>  
41:                 </textField>  
42:                 <staticText>  
43:                      <reportElement uuid="e6b10d9f-fba6-43b6-a13a-8af8ae735dda" x="305" y="10" width="100" height="20"/>  
44:                      <textElement/>  
45:                      <text><![CDATA[Invoice Peroid]]></text>  
46:                 </staticText>  
47:                 <textField>  
48:                      <reportElement uuid="c7e391a0-4b7a-42ca-a996-08d72e8aa0c0" x="405" y="10" width="100" height="20"/>  
49:                      <textElement/>  
50:                      <textFieldExpression><![CDATA[$F{InvoicePeriod}]]></textFieldExpression>  
51:                 </textField>  
52:            </band>  
53:       </pageHeader>  
54:       <columnHeader>  
55:            <band height="61" splitType="Stretch"/>  
56:       </columnHeader>  
57:       <detail>  
58:            <band height="125" splitType="Stretch"/>  
59:       </detail>  
60:       <columnFooter>  
61:            <band height="45" splitType="Stretch"/>  
62:       </columnFooter>  
63:       <pageFooter>  
64:            <band height="54" splitType="Stretch"/>  
65:       </pageFooter>  
66:       <summary>  
67:            <band height="42" splitType="Stretch"/>  
68:       </summary>  
69:  </jasperReport>  

Notice the <queryString> tag that I have shown highlighted in the preceding JRXML code. The <queryString> tag wraps the SQL query that you authored in step 6 of this recipe. This query brings all the five columns of the customer invoice table, each of which can be attached to a text field.

You can also see a <pageHeader> tag in this JRXML code. The <pageHeader> tag represents the header of your report, which you just authored in this recipe. The <band> child of the <pageHeader> tag contains two pairs of <staticText> and <textField> tags. I have shown only one pair for clarity. You can guess that each pair corresponds to a name-value pair you dragged-and-dropped in the Page Header section of your report. Notice that the <textField> tag has a child named <textFieldExpression>. The <textFieldExpression> has an expression ($F{CustomerName}) as its content. $F{CustomerName} refers to the name of a column in the CustomerInvoices table

you linked with the text field in steps 8 and 9 of this recipe.
Changing this expression in the XML tab will affect the report in the Designer and Preview tabs as well. For example, if you delete the $F{CustomerName} expression in the XML tab, you will see that there is no content shown as the value of that text field in the Designer tab 

There's more...
If you look at the SQL query that you entered into the Report query window, you will see that the name of the customer and the invoicing month have been hardcoded in the query. This data normally comes from the user who generates the report. 

In order to allow the user to provide these values, you will need to declare a parameter and link it to your text fields (that is, the customer name and invoicing month) according to steps 3 to 9 of the Post 8: iReport: Using dynamic titles that can change during report processing. 

In this case, you also need to have a dynamic query, which will use the parameters that you have linked to your text fields. So the fixed SQL query of step 6 of this recipe will change to the following dynamic query:

SELECT * from "public"."CustomerInvoices"
WHERE "public"."CustomerInvoices"."CustomerName" = $P{CustomerName}
AND "public"."CustomerInvoices"."InvoicePeriod" =
$P{InvoiceMonth}
 
Now when you switch to the Preview tab, iReport will not show you the preview immediately. It will first ask you to provide a customer name and invoicing month. Enter Packt Publishing as the customer name and Mar09, as invoicing month; iReport will now display the preview.
Also note that, once entered, iReport remembers parameter values, so it will not ask you to re-enter parameter values each time you generate the preview. It will ask you for new parameter values only when you close and reopen your report in iReport or make any
change in the design view.