Difference between revisions of "FPReport"

From Lazarus wiki
Line 1: Line 1:
== Architecture ==
== Architecture ==
FPReport is a banded reporting tool.  
FPReport is a banded reporting tool.  

Revision as of 17:09, 11 June 2017


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


To create a report in code, this unit is all that is necessary.
It contains the basic report, page, bands and elements.
This unit contains the streamer, which reads/writes a report definition from/to file.
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.
This unit contains the data loop component TFPReportDatasetData , which bases the loop on data from a dataset.
This unit contains the PDF exporter TFPReportExportPDF.
An instance of this class can be used to export a report to PDF.
This unit contains the HTML exporter TFPReportExportHTML.
An instance of this class can be used to export a report to HTML pages.
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.

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.