Sign in Join
Wiki copytemporary

LazReport Documentation: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

OldNewLine
11## Overview
22
33LazReport is a group of components to add reporting capabilities to applications. It uses a visual designer to create banded reports and includes a report engine with previewer and an interpreter to run user scripts. The report designer can be invoked at runtime.
44
55## License
66
77LazReport is based on FreeReport 2.32 and thanks to Fast Reports Inc. it's available under modified LGPL, the same license as the Lazarus LCL. See files lazreport/license.txt, license-rus.txt and license-lazreport.txt for details.
88
99## Authors
1010
1111FreeReport was created for Fast Reports Inc.
1212
1313LazReport initial port was made by Olivier Guilbaud.
1414
1515Lazarus integration and fixes by Jesus Reyes A.
1616
1717Many contributors, see lazreport/doc/contributors.txt file
1818
1919## Installation
2020
2121To install LazReport in the Lazarus IDE:
2222
23231. Open LazReport Package. Menu: Package-\>Open Package File (.lpk)...
24242. Open file components/lazreport/source/lazreport.lpk
25253. Install
2626
2727The next time Lazarus is started, it should show a LazReport tab in the component palette.
2828
2929## Documentation
3030
3131Developer's manual and User Guides specific for LazReport are yet to be written. In the mean time, most LazReport features are described in the FreeReport Developer's Manual (see components/lazreport/doc/fr_eng.odt (or fr_eng.pdf) in your Lazarus installation). Platform specific things described there like OLE objects are not implemented in LazReport, also some examples or pictures make reference to samples available only on Delphi.
3232
3333Until LazReport documentation is elaborated, this Wiki page will be used as a documentation container; maybe in the future the missing documentation could be generated from here. Users are welcomed to add topics that they feel need to be documented.
3434
3535### Operators
3636
3737The following operators are supported:
3838
3939| Operator type | Operators |
4040|----|----|
4141| Logical | \>, \<, BUT, AND, NOT, =, \< \>, \> =, \< = |
4242| Mathematical\|\|-, *, +, MOD, / | |
4343
4444### Functions
4545
4646The following functions are available for use:
4747
4848#### Statistical functions
4949
5050SUM(\<X \>)
5151Returns the sum of values represented by \<X\>, which is generally a data field.
5252
5353AVG(\<X \>)
5454Returns the average of \<X\> values.
5555
5656COUNT
5757Count the number of occurrences.
5858
5959MIN(\<X \>)
6060Returns the lowest value of all values represented by \<X\>
6161
6262MAX(\<X \>)
6363Returns the highest value of all values represented by \<X\>
6464
6565#### Date functions
6666
6767> **Note:** December 2013: inspection of lr_pars source code seems to indicate these functions work with the current locale date format, which limits interoperability. To do: verify this; extend function with an extra format parameter which defaults to e.g. ISO8601
6868
6969FORMATDATETIME(\<X\>, \<Y \>)
7070Returns \<Y\> TDateTime in format \<X\>. \<X\> uses the default syntax for [Lazarus formats](http://www.freepascal.org/docs-html/rtl/sysutils/formatdatetime.html).
7171
7272FORMATFLOAT(\<X\>, \<Y \>)
7373Returns the numeric value \<Y\> in format \<X\>. \<X\> uses the default syntax for [Lazarus formats](http://www.freepascal.org/docs-html/rtl/sysutils/formatfloat.html).
7474
7575STRTODATE(\<X \>)
7676Returns the TDateTime(? not date?) representation of string \< X \>. \< X \> must be formatted correctly.
7777
7878STRTOTIME(\<X \>)
7979Returns the TDateTime time part representation of string \< X \>. \< X \> must be formatted correctly.
8080
8181#### String functions
8282
8383LOWERCASE(\<X \>)
8484Returns lowercase \<X\>
8585
8686UPPERCASE(\<X \>)
8787Returns uppercase \<X\>
8888
8989NAMECASE(\<X \>)
9090Returns \<X\> with initial capitals
9191
9292COPY(\<X\>, \<Y\>, \<Z \>)
9393Similar to Pascal Copy: returns string \<X\> from position \< Y \> for \< Z \> characters.
9494
9595#### Numeric functions
9696
9797FRAC(\<X \>)
9898Returns the decimal part of number \< X \>
9999
100100INT(\<X \>)
101101Returns the integer part of number \< X \>
102102
103103ROUND(\<X \>)
104104Returns the number \< X \> rounded to an integer (up? down? nearest integer? banker's rounding?)
105105
106106STR(\<X \>)
107107Returns the string representation of number \< X \>
108108
109109#### Logical/boolean functions
110110
111111IF(\<X\>, \<Y\>, \<Z\>)
112112Returns \< Y \> if expression \< X \> is true. If false, returns \< Z \>.
113113
114114### Adding your own functions
115115
116116Though it is probably not needed much, LazReport allows you to define your own functions. As mentioned, see [[LazReport Documentation|LazReport Documentation#Documentation]] for an overview of existing functions.
117117
118118To add your own functions:
119119
120120#### Add template to definition file
121121
122122> **Note:** This was taken from the Delphi/FastReport/FreeReport tutorial in Portuguese. It should be verified and probably modified to work with current Lazarus/LazReport
123123
124124You need to define your functions following the following template in the file FR.lng (**is this still the correct name for Lazreprot?**):
125125
126126, FCT = CATEGORY\|FCT (\<X\> \<Y\>, \<z\>)\|Help
127127
128128where:
129129
130130- FCT is the function name.
131131- CATEGORY is the category name.
132132- FCT (\<X\> \<Y\>, \<z\>), is the layout of the required parameters, with a maximum of 3 parameters.
133133- Help Is a small help text which should allow the user to understand the purpose of the function.
134134- \| is a separator.
135135
136136Each parameter is separated by commas and can be an expression, a constant, a variable, a field or data. Alphanumeric type constants should be limited by a character. The variables are delimited by **and**.
137137
138138Data fields are limited to the variables and have the following format:
139139
140140Dataset_Name. "Field_Name"
141141
142142Let's add the SQRT and POS functions by adding the following lines to **FR.lng** todo: still the same name?
143143
144144SQRT = Mathematics and Trigonometry\|SQRT(\<X\>)\|Returns the square root of \<X\>\
145145POS = Strings\|POS(\<X\>,\<Y\>) Returns the position of string \<X\> within string \<Y\>
146146
147147#### Add function source code
148148
149149A function definition is nice, but we haven't specified how these functions work. Therefore, some source code to add the functions POS and SQRT below:
150150
151151``` pascal
152152Unit FR_OGFct;
153153
154154interface
155155
156156implementation
157157
158158uses FR_Pars, FR_Class; // Standard declarations needed for Lazreport!! Note: FR_pars etc? Are these names ok?
159159
160160type
161161 // Our own functions are declared here.
162162 TfrOGFunctionLibrary = class(TfrFunctionLibrary)
163163 public
164164 constructor Create; override;
165165 procedure DoFunction(FNo:integer procedure; p1, p2,
166166 p3:Variant; var valley:string); override;
167167 p3:Variant; var valley:string);
168168 end;
169169
170170//**************************
171171// * TfrOGFunctionLibrary
172172constructor TfrOGFunctionLibrary.Create;
173173begin
174174 inherited Create;
175175 // Add our functions to the list of available functions:
176176 with List do
177177 begin
178178 Add('POS');
179179 Add('SQRT');
180180 end;
181181end;
182182
183183Procedure TfrOGFunctionLibrary.DoFunction(FNo:Integer procedure;
184184 p1, p2, p3:Variant; Var valley:String); //valley?
185185Var
186186 Par1, Par2: Varying;
187187 Result: Variantying; //variantying? variant?
188188begin
189189 Try
190190 Case FNo of //this is the index of the functions as added in the constructor
191191 0 :
192192 begin // POS function
193193 Par1:=VarToStr(Parser.Calc(p1));
194194 Par2:=VarToStr(Parser.Calc(P2));
195195 Result:=Pos(Par1,Par2);
196196 end;
197197 1 : // SQRT function
198198 Result:=SQRT(Parser.Calc(P1));
199199 end;
200200 Except
201201 // String with error details
202202 Result:='Error in function '+List.Strings[FNo];
203203 end;
204204 Val:=VarToStr(Result); // Resulting string
205205end;
206206
207207Procedure DoInit;
208208begin
209209 frRegisterFunctionLibrary(TfrOGFunctionLibrary);
210210end;
211211```
212212
213213Save the report then File\>List and this window will appear:
214214
215-<figure>
216-<img src="imagem21.jpg" title="imagem21.jpg" />
217-<figcaption>imagem21.jpg</figcaption>
218-</figure>
215+![](/wiki-images/1/10/Imagem21.jpg)
219216
220217You may notice the appearance of a small (...) button, active only in the case of an expression. Click below to open the editor:
221218
222-<figure>
223-<img src="imagem22.jpg" title="imagem22.jpg" />
224-<figcaption>imagem22.jpg</figcaption>
225-</figure>
219+![](/wiki-images/0/0f/Imagem22.jpg)
226220
227221You may notice the similarity. If you click the Add button it will load the editor parameters:
228222
229-<figure>
230-<img src="imagem23.jpg" title="imagem23.jpg" />
231-<figcaption>imagem23.jpg</figcaption>
232-</figure>
223+![](/wiki-images/2/23/Imagem23.jpg)
233224
234225Depending on the number of parameters, you have more or less edit areas. The (...) button makes it possible to open the expression generator to set the parameter.
235226
236227### Export Filters
237228
238229LazReport has the ability to save the report displayed in the preview window using a user-defined format. It has an extension mechanism with support for plugins that can be used to add any amount of export filters.
239230
240231An export filter is a specially designed class which is registered in LazReport and allows you to save the report using one or more formats.
241232
242233When LazReport is installed, it includes some filters ready for use, these are: TfrTextExportFilter for exporting report as plain text, TfrCSVExportFilter used for exporting the report as CSV format and TfrHTMExportFilter for exporting the report as simple html file. Also included are some packages that provide additional filters, these are (see Menu Package-\>Install/Uninstall Packages ...): lrCairoExport (components/lazreport/source/addons/cairoexport/lrCairoExport.lpk) which provides support for exporting to PDF and PS formats by using the Cairo Graphics Library and lr_extexp (components/lazreport/source/addons/imgexport/lr_extexp.lpk) with support for improved html export and some image formats like BMP, JPG and PNG. Also included in LazReport is the LazReportPDFExport (components/lazreport/source/addons/pdfexport/LazReportPDFExport.lpk) package, this package provides PDF export using [[PowerPDF]] which is available in Lazarus-CCR repository.
243234
244235A filters package is installed in the same way as any other Lazarus Package; after restarting Lazarus, the filters (usually) appear as icons in the LazReport tab on the Component Palette.
245236
246237An export filter is added to your application by simply dragging one of these icons to a form or data module where TfrReport component exists, this is automatically registered and remains ready to use.
247238
248239This can also be done manually by including the export filter unit name in the Uses clause of the unit where TfrReport is used.
249240
250241LazReport export filters are invoked using one of two ways:
251242
2522431. Save the report in the preview window. Using this method (pressing the Save button) when the Save As dialog is presented, the user can choose a format from the list of registered formats. The list is populated by all registered export filters.
2532442. Through code using the TfrReport ExportTo method. See below for an example:
254245
255246``` pascal
256247 if TheReport.PrepareReport then
257248 TheReport.ExportTo(TfrHTMExportFilter, 'exportedfile.html');
258249```
259250
260251Where TheReport holds an instance of TfrReport component. In this sample a TfrHTMExportFilter is used to generate a file named 'exportedfile.html'. It's not necessary to prepare the report again if it has been prepared previously.
261252
262253In order to use TfrHTMExportFilter the developer has to drag and drop an instance of the TfrHTMExportFilter component from the LazReport tab in the component palette to the form in the Form Designer. As an alternative the unit **lr_e_htm.pas** file can be added to the unit uses clause.
263254
264255Since LazReport 0.9.6, export filters support has been enhanced: now export filters can take parameters which users can customize either by changing values directly or by presenting the end user some UI. In order to make changes in parameters, the developer can create an event handler for TfrReport.OnExportFilterSetup event, available by selecting the TfrReport component and selecting the Events tab in Object Inspector.
265256
266257The OnExportFilterSetup (of type TExportFilterSetup) event handler takes an argument sender of type TfrExportFilter, in order to use this type, the **lr_class.pas** unit must be added to the unit uses clause. All ExportFilter clases share this event and the developer has to type-cast the sender argument to the desired export filter class, for example:
267258
268259``` pascal
269260if sender is TfrHTMExportFilter then
270261begin
271262 TfrHTMExportFilter(sender).UseCSS := false;
272263end;
273264```
274265
275266Below a description of available export filters.
276267
277268#### TfrExportFilter
278269
279270TfrExportFilter is the base class of all export filters, and defines two properties that can be modified by the developer in the OnExportFilterSetup event:
280271
281272- **BandTypes**: TfrBandTypes. this is a set of band types, only bands included in this set are actually exported; the other bands on the report will be ignored. Using this property a developer could for example export only the master band content, leaving titles, headers and footers out of exported output by doing:
282273
283274``` pascal
284275sender.BandTypes := [btMasterData];
285276```
286277
287278By default, all bands are processed but TfrCSVExportFilter changes this property to process only master header, column header and master data bands.
288279
289280- **UseProgressbar**: boolean. This property enables or disables showing the progress bar while processing the export filter. This property is false by default.
290281
291282#### TfrTextExportFilter
292283
293284inheritance: TfrExportFilter \<- TfrTextExportFilter\
294285located in: components/lazreport/source/**lr_e_txt.pas** file included with the LazReport package.
295286
296287TfrTextExportFilter is the base class of text based export filters. This export filter tries to make a text representation of a graphical report by fitting the original graphical coordinates into a more coarse grid where each unit is of "UsedFont" pixels, depending on the value of UsedFont value, the exported output may more or less represent the layout of objects in graphical report. Beside the properties inherited from TfrExportFilter class, TfrTextExportFilter define two more properties.
297288
298289- **UsedFont**:integer. this property define the pixel dimensions on the output grid, objects on report are fitted into this grid by reclaculating each x and y position. The default value is 10, if user changes this value to 0 or less, LazReport will show automatically a dialog asking for the UsedFont value, if user enter a invalid value, a 10 value will be used. The 10 value is used because is the value that better fits the usual reports which are made with fonts 10-13 points.
299290- **UseBOM**:boolean. This property enable the inclusion of UTF-8 Byte Order Mark character at the start of text output (see [BOM](http://en.wikipedia.org/wiki/Byte_order_mark)) needed by some editors/viewers, by default no BOM is used in exported output.
300291
301292#### TfrCSVExportFilter
302293
303294inheritance: TfrExportFilter \<- TfrTextExportFilter \<- TfrCSVExportFilter\
304295located in: components/lazreport/source/**lr_e_csv.pas** file included in LazReport package.
305296
306297This special text export filter produces Comma Separated Value output (actually any character can be used as separator), it differs from its ancestor in that it doesn't try to create text layout representation of graphical report, instead, for each record output it tries to guess the fields order from the source report, it then produce a list of fields using a separator defined by the user. Beside the properties inherited from its ancestor classes it defines some properties to customize the generated output.
307298
308299- **QuoteType**:TfrQuoteType. This property controls whether the generated field value should be wrapped using specified quote char or not. Possible values are *qtNone*, *qtQuoteChar* and *qtAutoQuote*. With *qtNone* the field value is never wrapped, *qtQuoteChar* will use the character specified by property **QuoteChar**, any instance of **QuoteChar** already present in field value is duplicated. *qtAutoQuote* first try to find if any instance of **separator** or **QuoteChar** is already present in field value, if affirmative it behaves as if *qtQuoteChar* has been specified, on the contrary case, the field value is not wrapped just as if *qtNone* has been specified. **QuoteType** property is set to *qtQuoteChar* by default.
309300- **QuoteChar**:TUTF8Char. This holds the character to be used to wrap the field value in case of **QuoteType** of value *qtQuoteChar* has been specified or deduced if *qtAutoQuote* is set. Any instance of this character in the field value will be duplicated. by default **QuoteChar** is set to the " character.
310301- **Separator**:TUTF8Char. This is the character used to separate the fields in each record, by default is set to the ',' (COMMA) character but any UTF-8 valid character could be used. Some CSV files are actually TAB separated files, to get this, set Separator:=#9;
311302
312303The CSV exporter do not use the inherited UsedFont property value so any value set will be ignored. With default property values, TfrCSVExportFilter will produce Excel compatible files, the only caveat is that Excel will not recognize the file as UTF-8 encoded. To force Excel to recognize the encoding automatically, set the property **UseBOM** to true.
313304
314305#### TfrHTMExportFilter
315306
316307inheritance: TfrExportFilter \<- TfrTextExportFilter \<- TfrHTMExportFilter.\
317308Located in: components/lazreport/source/**lr_e_htm.pas** in LazReport package.
318309
319310This special text export filter produces valid "HTML 4.01 Transitional" output. Currently it defines only one additional property.
320311
321312- **UseCSS**:boolean. This property controls whether or not the produced output include CSS information, this property is set to true by default.
322313
323314### Scripting Language
324315
325316A simple scripting language (interpreter) for a Pascal-like language is included in LazReport.
326317
327318Some notes:
328319
329320- the interpreter seems to expect semicolons after each line
330321- the interpreter cannot handle nested if statements
331322
332323Example:
333324
334325``` pascal
335326 if [[PAY]>0] then begin
336327 if[[LATE_FEE]=1] then Text:=[MSGL2];
337328 else Text:= [MSGL1];
338329 end;
339330```
340331
341332The above won't compile, while this will:
342333
343334``` pascal
344335 if[[LATE_FEE]=1] then Text:=[MSGL2]
345336 else Text:= [MSGL1];
346337```
347338
348339Source: [forum thread](http://forum.lazarus.freepascal.org/index.php/topic,22902.0.html).
349340
350341### Examples
351342
352343You can find some examples in your Lazarus installation under components\lazreport\samples.
353344
354345#### Running total
355346
356347To calculate the total for values of each page added to the total on the previous page, follow these steps:
357348
358349- Make sure you have a report with a master data band connected to a dataset
359350- Place a text inside that band and double click to open its editor.
360351- In the editor, check the script option on the top left.
361352- In the script window, paste the following code
362353
363354``` pascal
364355 IF [Line#] = 1 then RunTotal := [Dbf1."MTH_NO"]
365356 else RunTotal := RunTotal +[Dbf1."MTH_NO"];
366357```
367358
368359
369360of course you need to replace \[dbf1."MTH_NO"\] with your field, the one you want a running total.
370361
371362- Click OK to save the changes.
372363- Reopen the editor by double clicking on the text object
373364- Click the "Variable" button.
374365- Select the fr variables category in the drop down combo.
375366- Double click the RunTotal variable to be placed on Memo.
376367- Click OK and then press Preview.
377368
378369Source: [Issue \#17198](https://bugs.freepascal.org/view.php?id=17198)
379370
380371### Tutorial
381372
382373Please see [[LazReport Tutorial]].
383374
384375### See also
385376
386377- [Creating and printing a report](http://www.pp4s.co.uk/main/tu-db-firebird-demo3.html)
387378
388379## Report Designer
389380
390381- Menu: File-\>Save As ...
391382 - Templates Notice:
392383 - While saving the current report, the user can select an arbitrary directory in the Save As dialog, in the case of templates (.lrt extension), the selected directory is ignored. Templates are always stored in the **Templates Directory**. The **Templates Directory** value can be set by either changing the frTemplateDir global variable (lr_desgn.pas unit) or by setting the TemplateDir property in a TfrDesigner component. The TemplateDir property will overwrite the frTemplateDir global variable if both are used. The **Templates Directory** can be an absolute path or a relative to program path directory, if this directory do not exists, LazReport will try to create it on the first use. If the TemplateDir property or the frTempateDir variable are not set, LazReport will try to save the templates in the program directory.
393384 - Binary templates format (.frt) is not recommended, as binary formats are hard to keep compatible with newer (or older) LazReport versions. If possible use .lrt file extension (XML file format).
394385
395386## Quick Start
396387
397388### Report Records from a Dataset
398389
399390In this sample we will design a report to print records from a dataset derived component (TDbf, TSQLQuery, TZTable, TZQuery, Etc.). First it's assumed that LazReport is already installed and the dataset component, called "Dbf1" here, is already configured and active.
400391
4013921. From LazReport tab, select TfrReport component and drop it in Form Designer, it will be named "frReport1".
4023932. Drop a TfrDbDataset component, it will be named "frDbDataset1"
4033943. Drop a TButton, it will be named Button1, change its name to "btnShowReport"
4043954. With frDbDataset1 selected in Object Inspector select "Dbf1" for the "Dataset" property
4053965. Now select frReport1 and using the same procedure link its "Dataset" property to "frDbDataset1":
406- <center>
407-
408- <figure>
409- <img src="lrformsetup.png" title="lrformsetup.png" />
410- <figcaption>lrformsetup.png</figcaption>
411- </figure>
412-
413- </center>
397+ ![](/wiki-images/4/46/Lrformsetup.png)
4143986. Right Click frReport1 and select "Design Report" from the menu, LazReport report designer will appear.
4153997. From Designer window, select menu Tools-\>Tools-\>Insert DB Fields, Insert fields Dialog will appear.
4164008. In field list select the fields you want in the report
4174019. Check "Include Headers" and "Include Bands" options, the result should be something like this:
418- <center>
419-
420- <figure>
421- <img src="lrinsertfieldsdialog.png" title="lrinsertfieldsdialog.png" />
422- <figcaption>lrinsertfieldsdialog.png</figcaption>
423- </figure>
424-
425- </center>
402+ ![](/wiki-images/7/7d/Lrinsertfieldsdialog.png)
42640310. Press the "Ok" button, LazReport will arrange bands and fields like this:
427- <center>
428-
429- <figure>
430- <img src="lrreportwithfields.png" title="lrreportwithfields.png" />
431- <figcaption>lrreportwithfields.png</figcaption>
432- </figure>
433-
434- </center>
404+ ![](/wiki-images/4/43/Lrreportwithfields.png)
43540511. Press the preview button ![](/wiki-images/b/bb/Lrprevieweye.png), LazReport will then arrange things and show:
436- <center>
437-
438- <figure>
439- <img src="lrpreviewreport.png" title="lrpreviewreport.png" />
440- <figcaption>lrpreviewreport.png</figcaption>
441- </figure>
442-
443- </center>
406+ ![](/wiki-images/4/43/Lrpreviewreport.png)
44440712. Save the report with Menu File-\>Save, select the same directory as the current project and name it as listing1.lrf
44540813. Close the report designer.
44640914. Double click btnShowReport and type the following code:
447410
448411``` pascal
449412 frReport1.LoadFromFile('listing1.lrf');
450413 frReport1.ShowReport;
451414```
452415
453416## Bug reports
454417
455418Please report problems using the [lazarus/freepascal bugtracker](http://www.freepascal.org/mantis/main_page.php), project: "Lazarus Packages", Category "LazReport".
456419
457420For patches, please submit a bug report and attach the patch to it.
458421
459422---
460423*From the Free Pascal wiki, page "LazReport Documentation", as it stood on 2022-02-05 after a change by Slawek, 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).*

Back to history