FAQ’s & Features

Report or document templates are standard in reporting applications. They define the layout of the documents that the report-filling process produces. Like other document template engines, PDFReporter uses document templates structured in multiple sections. Each section type has its own characteristics and behavior. Section types include title, summary, page and column headers and footers, group headers and footers, and details. Each section is made of individual elements like lines, rectangles, static and dynamic text fields, images.

FAQ’s and Feature descriptions
Creating report / document templates
There are two ways to create report templates. Editing the JRXML files using either a simple text editor, an XML editor, or the iReport Designer from Jasper Reports.  The most common use case scenario that requires dynamically built or ad hoc report templates is one in which the columns that are going to be present in a table-like report layout are not known at design time. Instead, the user will give the number of columns and their order inside the desired report at runtime.

Expression scripting language
 The default language for the report expressions is JEval, but report expressions can be written in JavaScript or any other scripting language as long as the document template engine implementation can evaluate them at runtime.

Reporting & document data
The PDFReporter library is completely agnostic and makes no assumptions about where the data it uses for filling the reports comes from. It is the responsibility of PDFReporter’ parent application to supply this data and handle the output generated by the library. PDFReporter can make use of any data that the parent application might have for generating reports because it relies on two simple things: the report parameters and the report data source. Report parameters are basically named values that are passed to the engine at report- filling time. Users can put the SQL query needed to retrieve the report data from the database in the report template itself. At runtime, the only thing the engine needs is a database connection object to connect to the desired relational database, execute the SQL query, and retrieve the report data. The main difference between parameters and the data source is that parameters are single-named values used inside report expressions for calculations or display, while the data source represents tabular data made of virtual rows and columns that the engine uses for iteration during the report-filling process. 
Generated reports or documents
The output of the report-filling process is always a pixel-perfect document, ready for viewing, printing, or exporting to other formats. These documents come in the form of serializable objects. This allows the parent application to store them or transfer them over the network if needed. At the top level, an print object contains some document-specific information, like the name of the document, the page size, and its orientation (portrait or landscape). Then it points to a collection of page objects, each page having a collection of elements that make up its content. Elements on a page are absolutely positioned at x and y coordinates within that page and have a specified width and height in pixels. They can be lines, rectangles, ellipses, images, or text, with various style settings corresponding to their type.
Filling order (Vertical/Horizontal Filling)
PDFReporter templates allow the detail section to be smaller than the specified page width so that the output can be structured into multiple columns, like a newspaper. When multiple-column report templates are used, the order used for filling those columns is important. There are two possible column orders Vertical, meaning that they run from top to bottom and then from left to right Horizontal, meaning that they first run from left to right and then from top to bottom. When filling report templates horizontally, dynamic text fields inside the detail section do not stretch to their entire text content, because this might cause misalignment on the horizontal axis of subsequent detail sections. The detail band actually behaves the same as the page and column footers, preserving its declared height when horizontal filling is used.
Exporting reports & documents
In some application environments, it is useful to transform the PDFReporter generated documents from the proprietary format into other, more popular formats like PDF. This way, users can view those reports without having to install special viewers on their systems, which is especially important in the case of documents sent over a network. Exporting means taking a print object, which represents a PDFReporter document, and transforming it into a different format. The main reason to export reports into other formats is to allow more people to view those reports. HTML reports can be viewed by anybody these days, since at least one browser is available on any system. With time, more and more output formats will be supported by the PDFReporter library. For the moment, the various exporter implementations shipped with the library produce only PDF output. HTML, WORD, RTF, XLS, ODT, CSV, and XML can be implemented.
JRXML
JRXML is the name we use when referring to XML files that represent the definition of a PDFReporter template and that comply with the mentioned XSD structure. When working with JRXML report templates, PDFReporter uses its own internal XSD files to validate the XML content it receives for processing. If the XML validation passes, it means that the supplied report design corresponds to the PDFReporter required XML structure and syntax, and the engine is able to generate the version of the report design. Valid JRXML report templates always point to the PDFReporter internal XSD files for validation. If the XSD reference is not specified, report compilation will fail abruptly. This should not be a big problem since the XSD reference is always the same and can simply be copied from previous report templates. To start with, you can copy it from the supplied samples.
JRXML encoding
When creating JRXML report templates in different languages, pay special attention to the encoding attribute that can be used in the header of the XML file. By default, if no value is specified for this attribute, the XML parser uses UTF-8 as the encoding for the content of the XML file. This is important because the report design often contains localized static texts, which are introduced when manually editing the JRXML file. For most Western European languages, the ISO-8859-1 encoding, also known as LATIN1, is sufficient.
Page size
There are two attributes at this level to specify the page size of the document that will be generated: pageWidth and pageHeight. Like all the other PDFReporter attributes that represent element dimensions and position, these are specified in pixels. PDFReporter uses the default resolution of 72 dots per inch (DPI). This means that pageWidth=”595″ will be about 8.26 inches, which is roughly the width of an A4 sheet of paper. The default page size corresponds to an A4 sheet of paper:

pageWith=”595″ pageHeight=”842″

Page orientation
The orientation attribute determines whether the documents use the Portrait or the Landscape format. PDFReporter requires you to adapt the page width and the page height when switching from Portrait documents to Landscape, and vice versa. For example, assume that you want to create an A4 report using the Portrait layout. An A4 report has approximately this size:

pageWidth=”595″ pageHeight=”842″ orientation=”Portrait”
If you decide to use the Landscape layout for your A4 document, you must be sure to modify the page width and page height accordingly, as follows:

pageWidth=”842″ pageHeight=”595″ orientation=”Landscape”

This is because PDFReporter has to know exactly the absolute width and height of the pages it will draw on, and does not necessarily consider the value supplied in the orientation attribute, at least not at report-filling time. This orientation attribute is useful only at report-printing time to inform the printer about the page orientation, and in some special exporters. The default page orientation is “Portrait”.

Styles (default, cascading, conditional
A report or document style is a collection of style settings declared at the report level. These settings can be reused throughout the entire report template when setting the style properties of report elements.

The name attribute of a <style> element is mandatory. It must be unique because it references the corresponding report style throughout the report. You can use isDefault=”true” for one of your report style declarations to mark the default for elements that do not or cannot have another style specified.

Each report style definition can reference another style definition from which it will inherit some or all of its properties. The style attribute specifies the name of the parent report style.

Sometimes users need to change a report element style at runtime based on certain conditions (for example, to alternate adjacent row colors in a report detail section). To achieve this goal, you can set some style properties to be enabled only if a specified condition is true. This is done using conditional styles.

Expressions
Expressions are a powerful feature of PDFReporter. They can be used to declare report variables that perform various calculations, group data on the report, specify report text field content, or further customize the appearance of report objects.

The JEval is used for writing report expressions.

Parameters
Parameters are object references that are passed into the report filling operations. They are very useful for passing to the report engine data that it cannot normally find in its data source.

For example, you could pass to the report engine the name of the user who launched the report filling operation if you want it to appear on the report, or you could dynamically change the title of your report.

The supplied values for the report parameters can be used in the various report expressions, in the report SQL query.

Variables
Report variables are special objects built on top of a report expression. They can simplify the report template by isolating in one place an expression that is heavily used throughout the report template, and they can perform various calculations based on the corresponding expression.
Report and document sections
PDFReporter works with templates that are structured into multiple sections, like any traditional reporting tool. At report filling time, the engine iterates through the virtual records of the supplied report data source and renders each report section when appropriate, depending on each section’s defined behavior.

For instance, the detail section is rendered for each record in the data source. When page breaks occur, the page header and page footer sections are rendered as needed.

Sections are made of one or more bands. Bands are portions of the report template that have a specified height and width and can contain report elements like lines, rectangles, images, and text fields. These sections are filled repeatedly at report generating time and make up the final document.

Main report sections
When building a report template, you must define the content and the layout of its sections. The entire structure of the report template is based on the following sections: <title>, <pageHeader>, <columnHeader>, <groupHeader>, <detail>, <groupFooter>, <columnFooter>, <pageFooter>, <lastPageFooter>, <summary>, and <background>. All report sections are optional, but of course all useful templates have at least one such section.

The title is the first section of the report. It is generated only once during the report filling process and represents the beginning of the resulting document.

The title section precedes even the page header section. To print the page header before the title section, put the elements on the page header at the beginning of the title section as well.

The page header appears at the top of each page in the generated document.

The column header appears at the top of each column in the generated document.

For each record in the data source, the engine tries to generate a detail section. The detail section can be made of multiple bands.

The column footer appears at the bottom of each column in the generated document. It never stretches downward to acquire the content of its containing text fields.

The page footer appears at the bottom of each page in the generated document. Just like the column footer section, the page footer never stretches downwards to acquire the content of its containing text fields and always retains the declared fixed height.

The summary is generated only once per report and appears at the end of the generated document, but is not necessarily the last section generated. This is because in some cases the column footer and/or page footer of the last page follows it.

If present, the last page footer, this section replaces the normal page footer section, but only on the last occurrence of the page footer, which might not be the last page if the summary is present and it overflows on multiple pages or it is rendered alone on its own last page. So it behaves more like the last page footer than the footer of the last page.

The background is a special section that is rendered on all pages and its content placed underneath all other report sections. Normal report sections are rendered one after the other, but the background section does not interfere with the other report sections and can be used to achieve watermark effects or to create the same background for all pages.

Text elements
There are two kinds of text elements in PDFReporter: static texts and text fields. As their names suggest, the first are text elements with fixed, static content, they do not change during the report-filling process, and they are used especially for introducing labels into the final document. Text fields, however, have an associated expression that is evaluated at runtime to produce the text content that will be displayed.
Fonts and unicode support
Each text element present on your report can have its own font settings. Those settings can be specified using the <font> tag available in the <textElement> tag.

Since a report template usually uses only a few types of fonts shared by different text elements, there’s no point forcing JRXML report template creators to specify the same font settings repeatedly for each text element. Instead, reference a report-level font declaration and adjust only some of the font settings, on the spot, if a particular text element requires it.

PDF encoding
Report variables are special objects built on top of a report expression. They can simplify the report template by isolating in one place an expression that is heavily used throughout the report template, and they can perform various calculations based on the corresponding expression.

When creating reports in different languages for export to PDF, make sure that you choose the appropriate character encoding type. For example, an encoding type widely used in Europe is Cp1252, also known as LATIN1. Examples of some other possible encoding types are shown below.

Latin 2: Eastern Europe Cp1250

Cyrillic Cp1251
Greek Cp1253
Turkish Cp1254

Windows Baltic Cp1257

Simplified Chinese UniGB-UCS2-H,UniGB-UCS2-V

Traditional Chinese UniCNS-UCS2-H,UniCNS-UCS2-V

Japanese UniJIS-UCS2-H, UniJIS-UCS2-V, UniJIS-UCS2-HW-H, UniJIS-UCS2-HW-V

Korean   UniKS-UCS2-H, UniKS-UCS2-V

Graphic elements
Graphic elements are the second major category of report elements. This category includes lines, rectangles, and images. They all have some properties in common, which are grouped under the attributes of the <graphicElement> tag.
Charts
The PDFReporter library does not produce charts itself. This is not one of its goals. However, it can integrate charts, barcodes, and graphics produced by other more specialized libraries.
Box elements
Text elements and images are considered “box elements” because you can surround them by a border that’s customizable on each side. When defining the border around such a box element, the user can control the width, style, and color of each of the four sides of the element, as well as the padding (the amount of blank space to reserve between the border of the element and its actual content). 
Element groups
Report elements placed in any report section can be arranged in multiple nested groups. The only reason for grouping your elements is to customize the stretch behavior of the report elements, as explained at the beginning of this chapter.

One possible value of the stretchType attribute, available for all report elements, is RelativeToTallestObject. If you choose this option, the engine tries to identify the object from the same group as the current graphic element that has suffered the biggest amount of stretch. It will then adapt the height of the current report element to the height of this tallest element of the group.

However, for this to work, you must group your elements. To do this, use the <elementGroup> and </elementGroup> tags to mark the elements that are part of the same group.

Hyperlinks, anchors and bookmarks
PDFReporter allows you to create drill down reports, which introduce tables of contents in your documents or redirect viewers to external documents using special report elements called hyperlinks.

When the user clicks a hyperlink, he or she is redirected to a local destination within the current document or to an external resource. Hyperlinks are not the only actors in this viewer-redirecting scenario. You also need a way to specify the possible hyperlink destinations in a document. These local destinations are called anchors.

There are no special report elements that introduce hyperlinks or anchors in a report template, but rather special settings that make a usual report element a hyperlink and/or an anchor.

In PDFReporter, only text field, image, and chart elements can be hyperlinks or anchors. This is because all these types of elements offer special settings that allow you to specify the hyperlink reference to which the hyperlink will point to or the name of the local anchor.

Frames
A frame is a report element that behaves like an element container. It is like a rectangle that can contain other report elements. Frames can be nested into one another to any depth. 
Page breaks and column breaks
A special break element was added to the list of elements that can be placed inside a band. This is used for introducing a page break or column break at a specified position within the band.
Generic elements
Generic report elements are like special placeholders that are put in the report template at report design time, but are dealt with only at export time, when special content is generated for them by the exporter.

A good example of a generic element use case is someone wanting to embed movies in reports exported to HTML format. PDFReporter has built in support for displaying text and images, but there is no built in element for displaying movies. But this feature can be implemented.

Subreports
A subreport is in fact a normal report that has been incorporated into another report. You can overlap subreports or make a subreport that contains other subreports, up to any level of nesting. Subreports are compiled and filled just like normal reports. Any report template can be used as a subreport when incorporated into another report template, without anything inside it having to change.

Since subreports are normal reports themselves, they are compiled and filled just like other reports. This means that they also require a data source from which to get the data when they are filled. They can also rely on parameters for additional information to use when being filled.

Returning values from subreports
Values calculated by a subreport can be returned to the parent report. More specifically, after a subreport is filled, values of the subreport variables can be either copied or accumulated to variables of the caller report.

The <returnValue> element is used inside <subreport> to specify values to be returned from the subreport.

A value returned from a subreport can simply be copied into the target master report variable, or it can be subject to a certain type of calculation made on the variable.

Crosstabs
A crosstab is a special type of report element that summarizes data into a two dimensional grid. Crosstabs usually display the joint distribution of two or more variables in the form of a table in which both rows and columns are dynamic, and in which the table cells use these variables to display aggregate data such as sums, counts, minimums, and maximums.

Crosstabs are useful because they are easy to understand, can be used with any level of data (nominal, ordinal, interval, or ratio), and provide greater insight than single statistics.

Crosstabs use an internal calculation engine for bucketing and preparing the aggregated data they display. However, sometimes it is useful to pass single values from the containing report and display them inside the crosstab. This would be the case for some crosstab header titles.

Any number of crosstab parameters can be declared inside the crosstab element. Each parameter has its own name and type, as well as its own expression used at runtime to obtain the value to pass into the crosstabs.

Barcode

PDFReporter architecture allows to include barcodes. The implementation that permit barcodes to be embedded in reports only needs to implemented in the PDFReporter library. 

Scriptlets
All the data displayed in a report comes from the report parameters and report fields. This data can be processed using the report variables and their expressions. Some variables are initialized according to their reset type when the report starts, or when a page or column break is encountered, or when a group changes. Furthermore, variables are evaluated every time new data is fetched from the data source (for every row).

But simple variable expressions cannot always implement complex functionality. This is where scriptlets come in. Scriptlets are sequences of a code that are executed every time a report event occurs. Through scriptlets, users can affect the values stored by the report variables. Since scriptlets work mainly with report variables, it is important to have full control over the exact moment the scriptlet is executed.

This feature is in an experimental stage. 

Internationalization
All reports and documents can be provided with different language support and evaluated at runtime. Ressource bundles aren’t supported. Best practice on mobile devices; use one template for each language and / or save language settings in separated db-tables or xml’s that can be evaluated during runtime. Please contact us on Internationalization once you run into the topic. 
Encrypted PDF
In some cases, users might want to encrypt the PDF documents generated by PDFReporter so that only authorized viewers can have access to those documents.

There are five exporter parameters for this:

IS_ENCRYPTED: When set to Boolean.TRUE, this parameter instructs the exporter to encrypt the resulting PDF document. By default PDF files are not encrypted.

IS_128_BIT_KEY: The PDF exporter can encrypt the files using either a 40-bit key or a 128-bit key. By default, it uses a 40-bit key, but if you set this flag to Boolean.TRUE, it can be configured to use a 128-bit key for stronger encryption.

USER_PASSWORD: This parameter specifies the password required from a normal PDF file user to access the document.

OWNER_PASSWORD: This parameter specifies the password required from the owner of the PDF file to access the document. The owner usually has more permissions. If this password is not set, an arbitrary string will be used when encrypting so that access is denied to all would be owners.

PERMISSIONS: This exporter parameter accepts values representing the PDF permissions for the generated document. The open permissions for the document can be AllowPrinting, AllowModifyContents, AllowCopy, AllowModifyAnnotations, AllowFillIn, AllowScreenReaders, AllowAssembly, and AllowDegradedPrinting. Permissions can be combined by applying bitwise OR to them.

PDF version and compression
Some applications require marking the generated files with a particular PDF specifications version.

The PDF_VERSION exporter parameter accepts values, but only a few values are recognized as valid, so users have to use constants to point to the PDF specification version.

Since version 1.5, the PDF format supports compression. By default, the PDF exporter in PDFReporter does not create compressed PDF documents, but this feature can be turned on using the IS_COMPRESSED exporter parameter. Note that because compressed PDFs are available only since PDF version 1.5, the PDF version of the resulting document is set to 1.5 automatically if compression is turned on.

PDF/A
We support PDF/A compliant export ( PDF/A-1a and PDF/A-1b variants only).
Digital signed PDF
Here is a description on how to digital sign pdf documents.
Report & document designer
The PDFReporter Studio is an open source authoring tool that can create complex reports from any kind of mobile platform through the PDFReporter library. It is written in 100% pure Java and is distributed with source code according to the GNU General Public License.

Through an intuitive and rich graphic interface, PDFReporter Studio lets you rapidly create any kind of report very easily. PDFReporter Studio enables engineers who are just learning this technology to access all the functions of PDFReporter, as well as helping skilled users to save a lot of time during the development of very elaborate reports.