Sign in Join
Wiki copytemporary

FPReport: what changed

Revision 3 to 4. Removed lines have a minus sign; added lines have a plus sign.

OldNewLine
11## Architecture
22
3-FPReport is a banded reporting tool.
3+FPReport is a banded reporting tool.
44
5-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.
5+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.
66
7-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.
7+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.
88
9-Once the report is created, it can be saved to disk, or rendered. Rendering is the act of creating visual output.
9+Once the report is created, it can be saved to disk, or rendered. Rendering is the act of creating visual output.
1010
11-Various renderers have been implemented:
11+Various renderers have been implemented:
1212
13-- To [[PDF]]. The PDF renderer is the renderer of choice
14-- 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.
15-- To HTML: each page is rendered as a HTML page using appropriate CSS markup.
13+ * To [[PDF]]. The PDF renderer is the renderer of choice
14+ * 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.
15+ * To HTML: each page is rendered as a HTML page using appropriate CSS markup.
1616
17-
1817Parts that cannot be rendered as HTML and CSS will be rendered as an image and placed in the HTML page.
1918
20-- To the LCL (a canvas).
19+ * To the LCL (a canvas).
2120
22-
2321This is in fact the basis of the preview, the designer and the printing support.
2422
25-- To an AggPas canvas. AggPas is a powerful graphics library, and this renderer is similar in scope to the FPImage renderer
26-- To fpGUI - this can be used to preview the report in a FPGUI report
23+ * To an AggPas canvas. AggPas is a powerful graphics library, and this renderer is similar in scope to the FPImage renderer
24+ * To fpGUI - this can be used to preview the report in a FPGUI report
2725
2826## units
2927
30-fpreport
28+**fpreport**
29+
3130To create a report in code, this unit is all that is necessary.
3231
3332It contains the basic report, page, bands and elements.
3433
35-fpreportstreamer
34+**fpreportstreamer**
35+
3636This unit contains the streamer, which reads/writes a report definition from/to file.
3737
38-fpjsonreport
38+**fpjsonreport**
39+
3940This unit contains a report class that can be dropped on a Lazarus form/Datamodule:
4041
4142the report definition will be written to the form file.
4243
43-fpreportdb
44+**fpreportdb**
45+
4446This unit contains the data loop component **TFPReportDatasetData** , which bases the loop on data from a dataset.
4547
46-fpreportpdfexport
48+**fpreportpdfexport**
49+
4750This unit contains the PDF exporter **TFPReportExportPDF**.
4851
4952An instance of this class can be used to export a report to PDF.
5053
51-fpreporthtmlexport
54+**fpreporthtmlexport**
55+
5256This unit contains the HTML exporter **TFPReportExportHTML**.
5357
5458An instance of this class can be used to export a report to HTML pages.
5559
56-fpreportfpimageexport
60+**fpreportfpimageexport**
61+
5762This unit contains the image exporter **TFPReportExportfpImage**.
5863
5964An instance of this class can be used to export a report to any supported image format.
6065
6166## Report structure
6267
63-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.
68+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.
6469
65-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.
70+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.
6671
67-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.
72+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.
6873
69-Every band contains one or more elements (a descendent of **TFPReportElement**).
74+Every band contains one or more elements (a descendent of **TFPReportElement**).
7075
71-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
76+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
7277
73-- A Memo. This is a text element which prints a text.
78+ * A Memo. This is a text element which prints a text.
7479
75-
7680The text can contain placeholders, which will be calculated every time the memo is printed.
7781
78-- A checkbox. This is a graphical element, which prints a checkbox (checked or not)
79-- A image. This is a graphical element, which prints an image.
80-- A shape. This is an element which can print one of a series of geometrical shapes.
82+ * A checkbox. This is a graphical element, which prints a checkbox (checked or not)
83+ * A image. This is a graphical element, which prints an image.
84+ * A shape. This is an element which can print one of a series of geometrical shapes.
8185
82-The elements share some common features, such as the ability to draw a frame around it, and to have a background color.
86+The elements share some common features, such as the ability to draw a frame around it, and to have a background color.
8387
8488## Types of bands
8589
86-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.
90+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.
8791
8892### DataBand
8993
90-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.
94+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.
9195
9296### Report title and Summary
9397
94-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.
98+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.
9599
96100### Page Header and Footer
97101
98-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.
102+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.
99103
100104### Data Header and Footer
101105
102-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.
106+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.
103107
104108### Group Header and Footer
105109
106-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**)
110+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**)
107111
108-This band can be added once for each data loop on the report.
112+This band can be added once for each data loop on the report.
109113
110114### Column Header and Footer
111115
112-A report can be on multiple columns. At the head of each column (on every page), a header can be printed using the Column Header band (**TFPReportColumnHeaderBand**). At the bottom of a column (again, on every page), a column footer band (**TFPReportColumnFooterBand**) can be printed.
116+A report can be on multiple columns. At the head of each column (on every page), a header can be printed using the Column Header band (**TFPReportColumnHeaderBand**). At the bottom of a column (again, on every page), a column footer band (**TFPReportColumnFooterBand**) can be printed.
113117
114-This band can be added once for each page in the report.
118+This band can be added once for each page in the report.
115119
116120### Child band
117121
118-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.
122+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.
119123
120-This band can be placed an arbitrary number of times on the report.
124+This band can be placed an arbitrary number of times on the report.
121125
122126## Printable elements
123127
124-On a band, you can drop one or more printable elements. A printable element is one of the following:
128+On a band, you can drop one or more printable elements. A printable element is one of the following:
125129
126-- a Memo. This is a text element. The text can contain formulas, and a limited set of HTML tags, such as bold, italic, underline and font or anchor tags.
130+ * a Memo. This is a text element. The text can contain formulas, and a limited set of HTML tags, such as bold, italic, underline and font or anchor tags.
127131
128-The formulas will be evaluated, and the result will be substituted in the text.
132+The formulas will be evaluated, and the result will be substituted in the text.
129133
130-- A Shape: this is one of several shapes such as a circle, square, triangle or straight lines in various orientations.
131-- An image: You can embed any image in your report. All image formats as supported by FPC fcl-image can be used.
132-- A checkbox. This is a special case of the image component: it uses 2 images, one for true, the other for false values.
134+ * A Shape: this is one of several shapes such as a circle, square, triangle or straight lines in various orientations.
135+ * An image: You can embed any image in your report. All image formats as supported by FPC fcl-image can be used.
136+ * A checkbox. This is a special case of the image component: it uses 2 images, one for true, the other for false values.
133137
134-Which one is used depends on the value of an expression which is evaluated every time the checkbox is printed.
138+Which one is used depends on the value of an expression which is evaluated every time the checkbox is printed.
135139
136-- A Barcode element. This element is in a separate unit (fpreportbarcode) and can be used to draw one of many types of barcode.
137-- a QRcode element. This element is in a separate unit (fpreportqrcode) and can be used to draw a QR code. It has some properties to determine the kind of barcode and how to position it.
140+ * A Barcode element. This element is in a separate unit (fpreportbarcode) and can be used to draw one of many types of barcode.
141+ * a QRcode element. This element is in a separate unit (fpreportqrcode) and can be used to draw a QR code. It has some properties to determine the kind of barcode and how to position it.
138142
139143## Data loops
140144
141-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.
145+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.
142146
143-Clearly, the data loop determines the number of pages in a rendered report.
147+Clearly, the data loop determines the number of pages in a rendered report.
144148
145-Currently, 5 kinds of data loop are available:
149+Currently, 5 kinds of data loop are available:
146150
147-- A user data loop.
151+ * A user data loop.
148152
149-
150153This loop is entirely event driven, and the various events are used to fetch the data.
151154
152-- A DB data loop.
155+ * A DB data loop.
153156
154-
155157This 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.
156158
157-- A TFPObjectList based loop.
159+ * A TFPObjectList based loop.
158160
159-
160161This uses RTTI of the objects to expose the data in the loop.
161162
162-- A TCollection based loop.
163+ * A TCollection based loop.
163164
164-
165165Similar to the TFPObjectList loop, this uses RTTI of the objects to expose the data in the loop.
166166
167-- A JSON array/Object based loop.
167+ * A JSON array/Object based loop.
168168
169-
170169This takes a JSON array (or object) and will loop over the elements in the array.
171170
172171### Data loop structure
173172
174-Data loops appear on several levels, they determine the structure of the report.
173+Data loops appear on several levels, they determine the structure of the report.
175174
176-- The page can have a data loop.
177-- The main (master) data band. Only one such band can exist on the page.
175+ * The page can have a data loop.
176+ * The main (master) data band. Only one such band can exist on the page.
178177
179-
180178This is the main data loop for the page.
181179
182-- Detail data bands.
180+ * Detail data bands.
183181
184-
185182The loop of these bands are run every time the master data band of the detail data bands is printed.
186183
187184Detail data bands can be nested, a detail data band can be the master of another detail data band.
188185
189-Per page in the report, the engine will determine the main data loop for that page.
186+Per page in the report, the engine will determine the main data loop for that page.
190187
191-This is the first data band's data loop, if the data band has no master. This will be used to start rendering the bands on that page.
188+This is the first data band's data loop, if the data band has no master. This will be used to start rendering the bands on that page.
192189
193-Usually, Page.Data will be Nil.
190+Usually, Page.Data will be Nil.
194191
195-But, if it is set, and it is different from the main data loop on the page, the complete page (and any loops on it) is rendered for each record in the page.data loop.
192+But, if it is set, and it is different from the main data loop on the page, the complete page (and any loops on it) is rendered for each record in the page.data loop.
196193
197-If the main data loop equals the page data loop, the logic is as if the Page.Data is Nil (for backwards compatibility).
194+If the main data loop equals the page data loop, the logic is as if the Page.Data is Nil (for backwards compatibility).
198195
199-For each band that has sub-bands, the engine will run a a similar loop over sub-bands.
196+For each band that has sub-bands, the engine will run a a similar loop over sub-bands.
200197
201198### User data loop
202199
203-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.
200+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.
204201
205-OnOpen
202+**OnOpen**
203+
206204Called when the data loop is 'opened'.
207205
208206This can be used to set up the actual data.
209207
210-OnFirst
208+**OnFirst**
209+
211210Called when the reporting engine needs to position the data loop on the first record.
212211
213-OnGetValue
212+**OnGetValue**
213+
214214Called when the reporting engine needs to get a value of a field.
215215
216-OnGetNames
216+**OnGetNames**
217+
217218Called before opening the data loop, it is used to retrieve the list of fields in the data loop
218219
219-OnNext
220+**OnNext**
221+
220222Called to signal that the data loop should go to the next record
221223
222-OnGetEOF
224+**OnGetEOF**
225+
223226Called to see if there are any more records in the data loop.
224227
225-OnClose
228+**OnClose**
229+
226230Called when the report is finished, and the data loop is no longer needed.
227231
228232### DB Data loop
229233
230-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.
234+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.
231235
232236### Collection Data loop
233237
234-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.
238+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.
235239
236240### ObjectList Data loop
237241
238-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.
242+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.
239243
240-The object list data loop loops over the items in an object list.
244+The object list data loop loops over the items in an object list.
241245
242-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.
246+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.
243247
244248### JSON Data loop
245249
246-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.
250+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.
247251
248-The JSON data loop loops over the items in a JSON Array or object.
252+The JSON data loop loops over the items in a JSON Array or object.
249253
250-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
254+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
251255
252-It assumes all the objects/arrays in the list are identical in structure.
256+It assumes all the objects/arrays in the list are identical in structure.
253257
254-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)
258+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)
255259
256260## Loading and Saving to file
257261
258-By itself, TFPReport has no concept of file formats.
262+By itself, TFPReport has no concept of file formats.
259263
260-It only knows a streamer class. For this reason, it has no LoadFromFile/SaveToFile methods. The only currently supported streamer class is **TFPReportJSONStreamer**, which can be used to save and load a report design to/from file.
264+It only knows a streamer class. For this reason, it has no LoadFromFile/SaveToFile methods. The only currently supported streamer class is **TFPReportJSONStreamer** , which can be used to save and load a report design to/from file.
261265
262-The [[FPReport Usage]] page explains how to load a report from file.
266+The [[FPReport Usage]] page explains how to load a report from file.
263267
264-For the same reason, a TFPReport cannot be used to store information in a lazarus .lfm file.
268+For the same reason, a TFPReport cannot be used to store information in a lazarus .lfm file.
265269
266-The **TFPJSONReport** class (unit **fpjsonreport**) descends from **TFPReport**, and combines it with the JSON streamer. If you want to be able to automatically load a design from file, or store it in the lazarus .dfm file, you are better off using this class.
270+The **TFPJSONReport** class (unit **fpjsonreport**) descends from **TFPReport** , and combines it with the JSON streamer. If you want to be able to automatically load a design from file, or store it in the lazarus .dfm file, you are better off using this class.
267271
272+
273+
268274## Data management
269275
270-By itself the TFPReport component does not have knowledge of datasets. It only knows an abstract data loop.
276+By itself the TFPReport component does not have knowledge of datasets. It only knows an abstract data loop.
271277
272-If you design a report using the report designer, the stand-alone designer writes data definitions to the JSON it creates. However, the report itself ignores this information, and no datasets or other data loops will be created.
278+If you design a report using the report designer, the stand-alone designer writes data definitions to the JSON it creates. However, the report itself ignores this information, and no datasets or other data loops will be created.
273279
274-In order to load and use the information about data in the report design, you can use a **TFPReportDataManager** component.
280+In order to load and use the information about data in the report design, you can use a **TFPReportDataManager** component.
275281
276-Just point the **FPJSONReport** instance's *DataManager* property to the instance of the **TFPReportDataManager** component, and it will instantiate the necessary datasets, and couple them to the report.
282+Just point the **FPJSONReport** instance's _DataManager_ property to the instance of the **TFPReportDataManager** component, and it will instantiate the necessary datasets, and couple them to the report.
277283
278-The [[FPReport Usage]] page explains how to do this.
284+The [[FPReport Usage]] page explains how to do this.
279285
280286## More Info
281287
282-- The [[FPReport Usage]] page explains how to create a basic report.
283-- The [[FPReport Designer]] page explains how to use the stand-alone report designer.
284-- The [[FPReport Custom elements]] page explains how to create custom elements for the reporting engine
285-- The [[FPReport Lazarus support]] page gives an overview of how FPReport can be used in Lazarus.
288+ * The [[FPReport Usage]] page explains how to create a basic report.
289+ * The [[FPReport Designer]] page explains how to use the stand-alone report designer.
290+ * The [[FPReport Custom elements]] page explains how to create custom elements for the reporting engine
291+ * The [[FPReport Lazarus support]] page gives an overview of how FPReport can be used in Lazarus.
286292
287293### FAQ
288294
289-See the FAQ -\> [[FPReport FAQ]]
295+See the FAQ -> [[FPReport FAQ]]
290296
291297---
292-*From the Free Pascal wiki, page "FPReport", as it stood on 2020-01-06 after a change by PascalR, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*
298+*From the Free Pascal wiki, page "FPReport", as the Internet Archive kept it on 2025-05-17, last changed on 2025-02-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*

Back to history