- 1 Architecture
- 2 units
- 3 Report structure
- 4 Types of bands
- 5 Data loops
- 6 More Info
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.
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.
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.
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.
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.
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.
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.
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.
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, 5 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.
- A TFPObjectList based loop.
- This uses RTTI of the objects to expose the data in the loop.
- A TCollection based loop.
- Similar to the TFPObjectList loop, this uses RTTI of the objects to expose the data in the loop.
- A JSON array/Object based loop.
- This takes 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.
- Called when the data loop is 'opened'.
- This can be used to set up the actual data.
- Called when the reporting engine needs to position the data loop on the first record.
- Called when the reporting engine needs to get a value of a field.
- Called before opening the data loop, it is used to retrieve the list of fields in the data loop
- Called to signal that the data loop should go to the next record
- Called to see if there are any more records in the data loop.
- 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.
Collection Data loop
Similar to the DB Data loop, the collection data loop (TFPReportCollectionData, unit fpreportcontnr) 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 collection data loop loops over the items in a collection. It exposes the published properties of the collection items as fields.
ObjectList Data loop
Similar to the collection data loop, the objectlist data loop (TFPReportObjectListData, unit fpreportcontnr) 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 object list data loop loops over the items in an object list.
It exposes the published properties of the list items as fields. It assumes all the objects in the list are if the same class, and uses the first object in the list to determine the fields.
JSON Data loop
Similar to the collection data loop, the JSON data loop (TFPReportJSONData, unit fpreportjson) 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 JSON data loop loops over the items in a JSON Array or object.
It exposes the properties of the first item in the array (or object) as fields. If the first item in the array is again an array, then Column1 to ColumnN are used as field names
It assumes all the objects/arrays in the list are identical in structure.
The array can be nested inside a complex object: the Path property can be used to point the JSON Data loop to the correct location of the array (or object)