FPReport

From Lazarus wiki
Revision as of 16:01, 24 June 2017 by Michael (talk | contribs)

Architecture

FPReport is a banded reporting tool.

It was designed from zero, to be able to run on a headless webserver, with minimal dependencies. An important use-case was a Linux server running in a container without X libraries installed. Creating a report is just placing squares with contents on a page, usually based on a data loop. This can be done entirely in-memory, and does not need a display or GUI.

Reports can be created entirely in code, or they can be read from a definition file. The default shipped file uses JSON as the format to store the report definition. The reports can also be designed visually, using a designer. A stand-alone designer exists, as well as the possibility to design a report within the Lazarus IDE.

Once the report is created, it can be saved to disk, or rendered. Rendering is the act of creating visual output.

Various renderers have been implemented:

  • To PDF. The PDF renderer is the renderer of choice
  • To a series of images. The FPImage renderer creates a bitmap per page, and the bitmaps can be saved in a directory in any of the supported FPImage formats.
  • To HTML: each page is rendered as a HTML page using appropriate CSS markup.
Parts that cannot be rendered as HTML and CSS will be rendered as an image and placed in the HTML page.
  • To the LCL (a canvas).
This is in fact the basis of the preview, the designer and the printing support.
  • To an AggPas canvas. AggPas is a powerful graphics library, and this renderer is similar in scope to the FPImage renderer
  • To fpGUI - this can be used to preview the report in a FPGUI report

units

fpreport
To create a report in code, this unit is all that is necessary.
It contains the basic report, page, bands and elements.
fpreportstreamer
This unit contains the streamer, which reads/writes a report definition from/to file.
fpjsonreport
This unit contains a report class that can be dropped on a Lazarus form/Datamodule:
the report definition will be written to the form file.
fpreportdb
This unit contains the data loop component TFPReportDatasetData , which bases the loop on data from a dataset.
fpreportpdfexport
This unit contains the PDF exporter TFPReportExportPDF.
An instance of this class can be used to export a report to PDF.
fpreporthtmlexport
This unit contains the HTML exporter TFPReportExportHTML.
An instance of this class can be used to export a report to HTML pages.
fpreportfpimageexport
This unit contains the image exporter TFPReportExportfpImage.
An instance of this class can be used to export a report to any supported image format.

Report structure

A report is an instance of the TFPReport class. It consists of one or multiple pages, each page is an instance of TFPReportCustomPage. The instances are available in the Pages array property of the report class. The number of pages is reported in the PageCount property.

When the report is rendered, first the first page will be rendered (according to its data loop), then the second page will be rendered, and so on.

Each page can consist of one or more bands. Some bands will appear only once in the output, others on regular places, but most bands will appear an arbitrary number of times, depending on the data which is given to the report. Typically there will be a data band which is printed once for each record in the data loop.

Every band contains one or more elements (a descendent of TFPReportElement).

Every time when the band is printed, all the elements on the band are printed. There are several types of element. The basic ones are

  • A Memo. This is a text element which prints a text.
The text can contain placeholders, which will be calculated every time the memo is printed.
  • A checkbox. This is a graphical element, which prints a checkbox (checked or not)
  • A image. This is a graphical element, which prints an image.
  • A shape. This is an element which can print one of a series of geometrical shapes.

The elements share some common features, such as the ability to draw a frame around it, and to have a background color.

Types of bands

FPReport has various types of bands. Each band has its own purpose. Some bands can appear only once in the definition of a report, other bands can appear multiple times.

DataBand

This is the band (class TFPReportDataBand) that will be printed once for each record in the report data loop. Multiple data bands can be put in a report, if they are linked in a master-detail relation.

Report title and Summary

A report title (TFPReportTitleBand) and summary (TFPReportSummaryBand) can appear once on each page of the report. The are printed once: when the report rendering is started, and when the rendering ends.

Page Header and Footer

A Page Header (TFPReportPageHeaderBand) and footer (TFPReportPageFooterBand) are printed at the top and bottom of each page. This kind of band can be added once per page. There are options to skip printing the header on the first page, and the footer on the last page.

Data Header and Footer

The data header (TFPReportDataHeaderBand) and footer (TFPReportDataFooterBand) are printed when a data loop starts, and ends. If a report contains multiple pages and uses multiple loops, then the report summary and title are printed only once, but the data header and summary are printed for every loop. This band can be added once for each data loop on the report.

Group Header and Footer

Data can be grouped based on an expression. When the value of the expression changes, a new group is started. A group is defined by placing a group header band (TFPReportGroupHeaderBand) on a page. Totals of a group can be displayed at the end of the group using a group footer (TFPReportGroupFooterBand)

This band can be added once for each data loop on the report.

Column Header and Footer

A report can be on multiple columns. At the head of each column, a header can be printed using the COlumn Header band (TFPReportColumnHeaderBand). At the bottom of a column, a column footer band (TFPReportColumnFooterBand) can be printed.

This band can be added once for each page in the report.

Child band

With the exception of Page footer and column footer bands, every band can have a child band (TFPReportChildBand) attached to it. This can be useful for aligning purposes, for example when a band contains memo that grows, and the band is configured to stretch, so the content of the memo is accomodated.

This band can be placed an arbitrary number of times on the report, but cannot be attached to Page footer and column footer bands.

Data loops

The data loop is a basic concept in the report. It can be thought of as an abstraction of an array of records: the data band will be printed for each "record" in the "array". The "fields" of each record are available to be used in an expression, and when an expression is evaluated which contains a field, then the value of the field for the current record will be used in the expression.

Clearly, the data loop determines the number of pages in a rendered report.

Currently, 2 kinds of data loop are available:

  • A user data loop.
This loop is entirely event driven, and the various events are used to fetch the data.
  • A DB data loop.
This loop is driven by a data set: the record is 1 record in the data set, the 'fields' in the record are the fields in the dataset.

Several more data loops are in the works:

  • A TFPObjectList based loop.
This will use RTTI of the objects to expose the data in the loop.
  • A TCollection based loop.
Similar to the TFPObjectList loop, this will use RTTI of the objects to expose the data in the loop.
  • A JSON array/Object based loop.
This will take a JSON array (or object) and will loop over the elements in the array.


User data loop

The user data loop is entirely event driven, and should be usable for any kind of data. The user is expected to implement several event handlers for the dataloop to implement its functionality.

OnOpen
Called when the data loop is 'opened'.
This can be used to set up the actual data.
OnFirst
Called when the reporting engine needs to position the data loop on the first record.
OnGetValue
Called when the reporting engine needs to get a value of a field.
OnGetNames
Called before opening the data loop, it is used to retrieve the list of fields in the data loop
OnNext
Called to signal that the data loop should go to the next record
OnGetEOF
Called to see if there are any more records in the data loop.
OnClose
Called when the report is finished, and the data loop is no longer needed.

DB Data loop

The dataset data loop (TFPReportDatasetData, unit fpreportdb) has some of the events of the user data loop, but in difference with the user data loop, the events are purely for the user to get feedback. The dataset data loop manages all data by itself. It will open the dataset or navigate through the dataset as the reporting engine calls the various methods.

More Info

The FPReport_Usage page explains how to create a basic report.