#LyX 1.6.7 created this file. For more info see http://www.lyx.org/
\lyxformat 345
\begin_document
\begin_header
\textclass scrbook
\begin_preamble
\input{preamble.tex}
\end_preamble
\use_default_options false
\language english
\inputencoding auto
\font_roman lmodern
\font_sans helvet
\font_typewriter courier
\font_default_family default
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100
\graphics default
\float_placement H
\paperfontsize default
\spacing single
\use_hyperref true
\pdf_bookmarks true
\pdf_bookmarksnumbered false
\pdf_bookmarksopen false
\pdf_bookmarksopenlevel 1
\pdf_breaklinks false
\pdf_pdfborder false
\pdf_colorlinks false
\pdf_backref false
\pdf_pdfusetitle true
\papersize letterpaper
\use_geometry false
\use_amsmath 2
\use_esint 1
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\bullet 0 5 11 -1
\bullet 1 5 24 -1
\bullet 2 0 0 -1
\tracking_changes false
\output_changes false
\author ""
\author ""
\end_header
\begin_body
\begin_layout Standard
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
input{chapter.tex}
\end_layout
\end_inset
\end_layout
\begin_layout Chapter
\begin_inset CommandInset label
LatexCommand label
name "cha:Subreports"
\end_inset
Subreports
\end_layout
\begin_layout Standard
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
epigraph{A manager's task is to make the strengths of people effective and
their weakness irrelevant---and that applies fully as much to the manager's
boss as it applies to the manager's subordinates.}{Peter Ferdinand Drucker}
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Use of style templates, layers, resource bundles, and directory organization,
along with experience with iReport will bestow upon you the ability to
quickly create reports.
Yet if all the reports are simply copies of a master template, you will
also succeed in creating more work for yourself when the time comes to
change the design of the reports.
\end_layout
\begin_layout Standard
This chapter describes how to ensure that when you change the report design,
you can do it once and have the design be applied to all the reports at
once.
Moreover, the technique ensures that all of the reports have a consistent
design.
\end_layout
\begin_layout Standard
In this chapter:
\end_layout
\begin_layout Itemize
\series bold
Master Report.
\series default
Describes creating a single report that ensures a consistent, singular
design.
\end_layout
\begin_layout Itemize
\series bold
Detail Report.
\series default
Instructions on including report content in the master report.
\end_layout
\begin_layout Section
Master Report
\end_layout
\begin_layout Standard
A master report is a reusable report template that isolates its design elements
from content.
The report content (for example, column headers and values) can then vary
from report to report, independently of the report's appearance.
This is accomplished by adding a parameter to the master report that determines
the subreport used in the Detail band.
\end_layout
\begin_layout Standard
This concept relates to gathering the report requirements as in
\begin_inset CommandInset ref
LatexCommand ref
reference "cha:Software-Requirements-Specifications"
\end_inset
.
The more reports that have formal specifications, the easier it is to design
various components (that is, subreports) that are included in the master
report.
The subreports are organized using the hierarchy shown in
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:Example-Directory-Organization"
\end_inset
.
\end_layout
\begin_layout Subsection
Page Header
\end_layout
\begin_layout Standard
The master report includes the page header by using a subreport with the
following expression:
\end_layout
\begin_layout LyX-Code
\family typewriter
$P{COMMON_DIR} + "header.jasper"
\end_layout
\begin_layout Standard
When creating a header report template for the
\series bold
Page Header
\series default
band in the master report, note the following:
\end_layout
\begin_layout Itemize
\family typewriter
COMMON_DIR
\family default
depends on
\family typewriter
SUBREPORT_DIR
\family default
, which in turn depends on
\family typewriter
ROOT_DIR
\family default
.
\end_layout
\begin_layout Itemize
\family typewriter
COMMON_DIR
\family default
is a directory of subreports that are shared by all master reports.
\end_layout
\begin_layout Itemize
The header's page margins must be set to zero.
\end_layout
\begin_layout Itemize
The header's page width must not exceed the master report's page width.
\end_layout
\begin_layout Itemize
To render the content, the header must have a query, even if it is only:
\end_layout
\begin_deeper
\begin_layout Standard
\family typewriter
SELECT 1 AS unused
\end_layout
\end_deeper
\begin_layout Standard
For suggested information to include on each page header, read
\begin_inset CommandInset ref
LatexCommand vref
reference "sec:Design-Header"
\end_inset
.
\end_layout
\begin_layout Subsection
Parameter Passing
\end_layout
\begin_layout Standard
The parameters must be passed from the master report to the header report
and any subreports that use those parameters in their queries.
In general, to pass parameters from a master report to a subreport, you
must do the following:
\end_layout
\begin_layout Enumerate
Add the parameters to the master report.
\end_layout
\begin_layout Enumerate
Add the parameters to the subreport.
\end_layout
\begin_layout Enumerate
Associate the master report parameters with the subreport parameters.
\end_layout
\begin_layout Standard
The last step provides a good reason to name parameters across reports consisten
tly: to avoid having to rename the parameters manually in the
\series bold
Expression
\series default
column of
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:Default-Subreport-Expression"
\end_inset
.
Adding the same parameters to the master report and subreport does not
mean that parameters are automatically passed from the master report to
its subreport.
In the subsequent steps, the only user-supplied parameter is the city name,
which filters the results.
\end_layout
\begin_layout Standard
To pass parameters:
\end_layout
\begin_layout Enumerate
Open the master report.
\end_layout
\begin_layout Enumerate
Select the subreport.
\end_layout
\begin_layout Enumerate
Click the button beside
\series bold
Parameters
\series default
in the
\series bold
Properties
\series default
panel to reveal the
\series bold
Parameters
\series default
dialog.
\end_layout
\begin_layout Enumerate
Click
\series bold
Copy From Master
\series default
.
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
If the parameters do not have the same name, then you will have to manually
rename them accordingly.
\end_layout
\end_inset
\end_layout
\begin_layout Enumerate
Select the values that are not necessary.
\end_layout
\begin_layout Enumerate
Click
\series bold
Delete
\series default
.
\end_layout
\begin_deeper
\begin_layout Standard
Depending on what was deleted, the parameters will resemble
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Parameter-Passing"
\end_inset
.
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Graphics
filename captures/ireport-parameter-passing-02.png
display false
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:Parameter-Passing"
\end_inset
Parameter Passing
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\end_deeper
\begin_layout Enumerate
Click
\series bold
OK
\series default
to close the
\series bold
Parameters
\series default
dialog.
\end_layout
\begin_layout Subsection
Page Footer
\end_layout
\begin_layout Standard
Creating a subreport for the
\series bold
Page Footer
\series default
band is not trivial if you want to include page numbers.
This is not an issue because the footer information is likely the same
across all reports (see
\begin_inset CommandInset ref
LatexCommand vref
reference "sec:Design-Footer"
\end_inset
for footer content ideas).
Contrast this with reports that require different parameters.
In the latter case, the header must display those parameters, but not others
(that is, the information changes between reports).
\end_layout
\begin_layout Standard
Do not use a subreport for the
\series bold
Page Footer
\series default
band in the master report.
The point of using subreports in the master report is to avoid duplicating
content (that is, to reduce maintenance and avoid introducing bugs).
If the footer content does not change across all reports, then directly
modifying the master report's
\series bold
Page Footer
\series default
band accomplishes the goal (without needing a subreport to abstract the
content to a single place).
That is:
\end_layout
\begin_layout Itemize
Page footers usually include page numbers.
\end_layout
\begin_layout Itemize
Page numbers do not work as expected when embedded in a subreport.
\end_layout
\begin_layout Itemize
Page footers, therefore, cannot employ the same strategy used by page headers.
\end_layout
\begin_layout Itemize
Page footers are less likely to need design changes.
\end_layout
\begin_layout Itemize
Therefore, do not use a subreport for the page footer content in the master
report.
\end_layout
\begin_layout Section
Detail Report
\end_layout
\begin_layout Standard
With the title, page header, and footer taken care of, the master report
need only embed the appropriate subreport in the detail band.
This can be accomplished in a similar way as including a different style
template: change the
\series bold
Subreport Expression
\series default
to use one more parameter:
\family typewriter
SUBREPORT_FILE
\family default
.
\end_layout
\begin_layout Standard
When you
\emph on
drag and drop
\emph default
a subreport onto a band, iReport displays the dialog shown in
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Subreport-Wizard-Dialog"
\end_inset
.
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Graphics
filename captures/ireport-subreport-wizard.png
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:Subreport-Wizard-Dialog"
\end_inset
Subreport Wizard Dialog
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Whether creating a new report or embedding an existing report, eventually
iReport will prompt for the path to the subreport.
For maximum flexibility, use a parameter to set the path to the subreport
file, rather than a static absolute path reference.
The default value (shown in
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Default-Subreport-Expression"
\end_inset
) will not quite work with a master report.
If it is to display arbitrary content, the parameter value must be modified.
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Graphics
filename captures/ireport-subreport-wizard-02.png
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:Default-Subreport-Expression"
\end_inset
Default Subreport Expression
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
There are a few quick steps to complete that will prepare the report for
dynamic content:
\end_layout
\begin_layout Enumerate
Add a subreport to the master report's
\series bold
Detail 1
\series default
band.
\end_layout
\begin_layout Enumerate
Add a
\family typewriter
SUBREPORT_FILE
\family default
parameter to the master report.
\end_layout
\begin_layout Enumerate
Set the default value for
\family typewriter
SUBREPORT_FILE
\family default
appropriately.
For this example, use:
\end_layout
\begin_deeper
\begin_layout LyX-Code
\family typewriter
"city/filter"
\end_layout
\end_deeper
\begin_layout Enumerate
Change the subreport's
\series bold
Subreport Expression
\series default
to:
\end_layout
\begin_deeper
\begin_layout LyX-Code
\family typewriter
$P{SUBREPORT_DIR} + $P{SUBREPORT_FILE} + ".jasper"
\end_layout
\end_deeper
\begin_layout Enumerate
Click
\series bold
Preview
\series default
to watch the magic happen.
\end_layout
\begin_layout Standard
The
\family typewriter
SUBREPORT_FILE
\family default
parameter must contain the relative path to the subreport file, without
the file extension.
The
\series bold
Subreport Expression
\series default
will evaluate
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
Verify a report parameter value by dragging the parameter onto the report's
\series bold
Title
\series default
band, and then re-running the report.
\end_layout
\end_inset
as follows:
\end_layout
\begin_layout LyX-Code
\family typewriter
/reports/subreports/city/filter.jasper
\end_layout
\begin_layout Standard
If a report template exists at the fully qualified path, the master report
will embed the content of the subreport.
The
\series bold
Detail
\series default
band
\series bold
\series default
content can vary independently of the
\series bold
Title
\series default
and
\series bold
Page Header
\series default
bands by setting a different value for the
\family typewriter
SUBREPORT_FILE
\family default
parameter.
\end_layout
\begin_layout Standard
To see how this works:
\end_layout
\begin_layout Enumerate
Create a new subreport, similar to
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
filejrxmlfilter}
\end_layout
\end_inset
, but with a different column order (to help readily distinguish it).
\end_layout
\begin_layout Enumerate
Save it as
\begin_inset ERT
status open
\begin_layout Plain Layout
\backslash
filename{
\backslash
filejrxmlall}
\end_layout
\end_inset
in the
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
dirreportcity{}
\end_layout
\end_inset
directory.
\end_layout
\begin_layout Enumerate
Remove all parameters from the query statement (the query should re-use
the
\family typewriter
report_city
\family default
function, but return all values, rather than a filtered set).
\end_layout
\begin_layout Enumerate
Compile (or
\series bold
Preview
\series default
)
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
filejrxmlall}
\end_layout
\end_inset
.
\end_layout
\begin_layout Enumerate
Click
\series bold
Preview
\series default
on the master report tab.
\end_layout
\begin_layout Enumerate
Provide a
\family typewriter
SUBREPORT_VALUE
\family default
of
\series bold
city/all
\series default
(
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Detail-Report-for-Master-Report"
\end_inset
).
\end_layout
\begin_deeper
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Graphics
filename captures/ireport-report-parameter-prompt-02.png
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:Detail-Report-for-Master-Report"
\end_inset
Detail Report for Master Report
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\end_deeper
\begin_layout Enumerate
Click
\series bold
OK
\series default
to continue to the next
\series bold
Parameter prompt
\series default
dialog.
\end_layout
\begin_layout Enumerate
Click
\series bold
Use default
\series default
to bypass the unused
\series bold
city_filter
\series default
Parameter prompt dialog.
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
This parameter must remain in the master report because it is required by
the filter detail report.
\end_layout
\end_inset
\end_layout
\begin_layout Standard
When running the reports in a live system, the value for
\family typewriter
SUBREPORT_FILE
\family default
(a file name) must be populated by the system.
Note: The user should never be expected to provide a file name for the
report.
\end_layout
\begin_layout Section
Summary
\end_layout
\begin_layout Standard
Peter Drucker, who was a management consultant, made an observation about
the relationship between managers and subordinates that is applicable to
report implementations.
Developing by
\emph on
copy and paste
\emph default
to create reports (that is, developing a single report template and then
copying that template for each new report) is like managers who take on
the tasks of their subordinates.
Managers who can focus on the preparation, the organization, and the direction
of the work by coordinating the details of the work across subordinates
are effective managers.
A single master report that calls upon subreports to present the report's
data content is an effective report template.
\end_layout
\end_body
\end_document