LazReport Tutorial: what changed

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

Old	New		Line
1	1		## Overview
2	2
3	3		This page started as a translation of the Portuguese language [[LazReport Tutorial/pt\|Tutorial de LazReport]] (which itself appears to be a translation from a French document). It was updated for LazReport (instead of FastReport) on Lazarus (instead of Delphi), using T*Connection instead of a DBase table.
4	4
5	5		## Starting with LazReport
6	6
7	7		We're going to use a demo database which is provided by Delphi (DBDEMOS). You'll need to create a new application with a main form Form1.
8	8
9	9		We're assuming you already have your database set up as specified in [[SQLdb Tutorial0]]. If not, please do so.
10	10
11	11		### Setting up your form
12	12
13	13		Place the following components on the form:
14	14
15	15		- A T*Connection, e.g. TIBConnection:
16	16		- DatabaseName := your database, e.g. C:\Program Files\Firebird\Firebird_2_5\examples\empbuild\EMPLOYEE.FDB
17	17		- UserName, Password, HostName: as appropriatie (e.g. SYSDBA,password,\<none\> for Firebird embedded)
18	18		- Transaction: TSQLTransaction1
19	19		- TSQLTransaction
20	20		- TSQLQuery:
21	21		- Database := IBConnection1
22	22		- Active: true
23	23		- SQL: select * from employee
24	24		- TDataSource
25	25		- DataSource1.DataSet := SQLQuery1
26	26		- TfrDBDataSet
27	27		- frDbDataSet.DataSource := DataSource1
28	28		- TfrReport
29	29		- TfrDesigner
30	30		- 2 TButton
31	31		- Button1.Caption := 'Editing'
32	32		- Button2.Caption := 'Preview'
33	33
34	34		This results in:
35	35
36		-	~~<figure>~~
37		-	~~<img src="lazreptut01.png" title="lazreptut01.png" />~~
38		-	~~<figcaption>lazreptut01.png</figcaption>~~
39		-	~~</figure>~~
	36	+	![](/wiki-images/4/4f/Lazreptut01.png)
40	37
41	38		Double-click on the TfrReport icon (or right-click, Design Report) to bring up the report designer:
42	39
43		-	~~<figure>~~
44		-	~~<img src="lazreptut01b.png" title="lazreptut01b.png" />~~
45		-	~~<figcaption>lazreptut01b.png</figcaption>~~
46		-	~~</figure>~~
	40	+	![](/wiki-images/6/6a/Lazreptut01b.png)
47	41
48	42		### Setting up variables
49	43
50	44		LazReport lets you link variable names to database fields or system values, in order to spare your end users from having to decipher cryptic field names. In our example, we're going to create a variable for our database fields FIRST_NAME, LAST_NAME etc.
51	45
52	46		In the File menu, click Variables list. Now you get an overview of the defined variables:
53	47
54		-	~~<figure>~~
55		-	~~<img src="lazreptutvariableseditor.png" title="lazreptutvariableseditor.png" />~~
56		-	~~<figcaption>lazreptutvariableseditor.png</figcaption>~~
57		-	~~</figure>~~
	48	+	![](/wiki-images/d/d9/Lazreptutvariableseditor.png)
58	49
59	50		Click on the button Variables in order to define some variables. Write the contents according ot the following image. "Demo Variables" represents a category and the other entries (xxx field) represent variables. To differentiate the two, the variables start with a space.
60	51
61	52		Note. The distinction between variables and variables categories by starting variables with a space is needed unique and exclusively in this dialog (Variables List). Anywhere else (Report Designer, main source code and scripts) a variable should be invoked without spaces.
62	53
63		-	~~<figure>~~
64		-	~~<img src="lazreptutdefinevariables.png" title="lazreptutdefinevariables.png" />~~
65		-	~~<figcaption>lazreptutdefinevariables.png</figcaption>~~
66		-	~~</figure>~~
	54	+	![](/wiki-images/8/86/Lazreptutdefinevariables.png)
67	55
68	56		Finally click on OK to confirm your entries, and you'll see this:
69	57
70		-	~~<figure>~~
71		-	~~<img src="lazreptutvariablesdefined.png" title="lazreptutvariablesdefined.png" />~~
72		-	~~<figcaption>lazreptutvariablesdefined.png</figcaption>~~
73		-	~~</figure>~~
	58	+	![](/wiki-images/f/ff/Lazreptutvariablesdefined.png)
74	59
75	60		As you can see, the category we defined is shown in the ComboBox above the variables. Each variable must be linked with a field. To do this, select the variable and then the field. Do this for all variables; the screenshot shows the link for Hire date:
76	61
77		-	~~<figure>~~
78		-	~~<img src="lazreptutvarhiredatetofield.png" title="lazreptutvarhiredatetofield.png" />~~
79		-	~~<figcaption>lazreptutvarhiredatetofield.png</figcaption>~~
80		-	~~</figure>~~
	62	+	![](/wiki-images/b/b6/Lazreptutvarhiredatetofield.png)
81	63
82	64		### Objects and bands
83	65
84	66		After closing the variables editor, we're back in our report designer. You may have noticed a small number of objects in the object bar to the left of the report surface. These are:
85	67
86	68		- the mouse icon pointer
87	69		- rectangle object
88	70		- band
89	71		- picture object
90	72		- subreport
91	73		- draw lines
92	74		- insert barcode object
93	75
94		-	~~<figure>~~
95		-	~~<img src="lazreptut01b.png" title="lazreptut01b.png" />~~
96		-	~~<figcaption>lazreptut01b.png</figcaption>~~
97		-	~~</figure>~~
	76	+	![](/wiki-images/6/6a/Lazreptut01b.png)
98	77
99	78		Click the band icon, go to the report surface, and click on it to drop a band object.
100	79
101		-	~~<figure>~~
102		-	~~<img src="lazreptutinsertnewband.png" title="lazreptutinsertnewband.png" />~~
103		-	~~<figcaption>lazreptutinsertnewband.png</figcaption>~~
104		-	~~</figure>~~
	80	+	![](/wiki-images/2/29/Lazreptutinsertnewband.png)
105	81
106	82		You must click on the type of band you want to create. Select Report title and click OK.
107	83
108	84		\| Band type \| Use \|
109	85		\|----\|----\|
110	86		\| Report title \| Shown only on the first page \|
111	87		\| Report summary \| Shown only on the last page \|
112	88		\| Page header \| Shown at the top of each page \|
113	89		\| Page footer \| Shown at the bottomof each page \|
114	90		\| Master header \| Shown at the beginning of the first detail band/level \|
115	91		\| Master data \| First detail level data; repeated for each record in dataset \|
116	92		\| Master footer \| Shown at the end of the first detail band/level \|
117	93		\| Detail header \| Shown at the beginning of the second detail band/level \|
118	94		\| Detail data \| Second detail level data \|
119	95		\| Detail footer \| Shown at the end of the second detail band/level \|
120	96		\| Subdetail header \| Shown at the beginning of the third detail band/level \|
121	97		\| Subdetail data \| Third detail level data \|
122	98		\| Subdetail footer \| Shown at the end of the third detail band/level \|
123	99		\| Overlay \| Shown once on each page lower layer \|
124	100		\| Column header \| Shown at the top of every column \|
125	101		\| Column footer \| Shown at the bottom of every column \|
126	102		\| Group header \| Shown at the top of every group \|
127	103		\| Group footer \| Shown at the bottom of every group \|
128	104		\| Cross header \| Shown at the top of cross tables/pivot tables \|
129	105		\| Cross data \| Shows cross tables/pivot table data \|
130	106		\| Cross footer \| Shown at the bottom of cross tables/pivot tables \|
131	107
132	108		### Report title
133	109
134	110		In the Report title band, add a rectangle. The text editor will show up. In the first line the title of the report should be indicated. On the the second, system date and time need to be added. They are obtained by clicking Variable and then Category Other, then double-click on the desired variable (once you are familiar with the variables, you can also just type them). Now we have:
135	111
136		-	~~<figure>~~
137		-	~~<img src="lazreptutreporttitle.png" title="lazreptutreporttitle.png" />~~
138		-	~~<figcaption>lazreptutreporttitle.png</figcaption>~~
139		-	~~</figure>~~
	112	+	![](/wiki-images/a/ad/Lazreptutreporttitle.png)
140	113
141	114		Click OK to exit the editor, then adjust the title rectangle to the desired size. Choose a color for the background with the Bucket Fill button on the toolbar.
142	115
143	116		### The main event: showing data in the master data band
144	117
145	118		Let's insert a master data band. LazReport prompts you for a data source; choose frDBDataSet1, the main data source for our example. The master band will be repeated for each record in the data source. You can double-click later on the band if you want to change the data source.
146	119
147		-	~~<figure>~~
148		-	~~<img src="lazreptutbanddatasource.png" title="lazreptutbanddatasource.png" />~~
149		-	~~<figcaption>lazreptutbanddatasource.png</figcaption>~~
150		-	~~</figure>~~
	120	+	![](/wiki-images/b/b7/Lazreptutbanddatasource.png)
151	121
152	122		In the left half of the band we insert a rectangle and double click. The familiar text editor appears.
153	123
154	124		Now we will add several fields in the one rectangle. If needed though, you can use one rectangle per field if you want to apply different formatting etc.
155	125
156	126		The first line Name \[Full name field\] is obtained by writing Name and then, with the Variable button, entering the variable \[Field Name\]. Alternatively, as indicated before, you can write the resulting text directly.
157	127
158	128		The next line Salary \[Salary field\] is written similarly.
159	129
160	130		The third line - Salary divided by job grade \[\[Salary field\]/\[Job grade field\]\] - is done likewise. This shows you can perform calculations with fields coming from the data source. Note the extra set of square brackets around the calculation. As you may guess, you can not only use the variables listed via the Variable button, but also database fields via DB Field.
161	131
162		-	~~<figure>~~
163		-	~~<img src="lazreptutmasterdata.png" title="lazreptutmasterdata.png" />~~
164		-	~~<figcaption>lazreptutmasterdata.png</figcaption>~~
165		-	~~</figure>~~
	132	+	![](/wiki-images/6/6a/Lazreptutmasterdata.png)
166	133
167	134		You can use all kinds of operators and functions in your calculations; see [[LazReport Documentation\|LazReport Documentation#Documentation]] for an overview.
168	135
169	136		#### Formatting output
170	137
171	138		You can control how the text in the rectangles is displayed.
172	139
173	140		Let's first add a new rectangle with the Hire date field variable.
174	141
175	142		In the variable editor, let's set a format. A format is valid for all variables of a rectangle/object. To show the format editor, double click on a rectangle to get the Text Editor, then click the Format button.
176	143
177	144		Let's set the date format you want here:
178	145
179		-	~~<figure>~~
180		-	~~<img src="lazreptutformattingdate.png" title="lazreptutformattingdate.png" />~~
181		-	~~<figcaption>lazreptutformattingdate.png</figcaption>~~
182		-	~~</figure>~~
	146	+	![](/wiki-images/1/12/Lazreptutformattingdate.png)
183	147
184	148		The first ComboBox indicates the type of data (text, numeric, date, time, logical/boolean). The second lets you select a preset format.... with some obvious restrictions:
185	149
186	150		- The Text type does not allow any Number type formatting.
187	151		- The Number type requires a number of any type (Integer, Double, Currency...).
188	152		- The Date type: you can choose a pre-defined format or write a custom format like MM/DD/YY for example.
189	153
190	154		Except for Text and Logic types, you can use the formatting strings you also use in Lazarus.
191	155
192	156		Other formatting options are present on the button bar below the menu (e.g. bold, italic, highlighting).
193	157
194	158		Highlighting is very useful for emphasizing data. You can specify a condition that determines when highlighting is applied.
195	159
196	160		For that, use the keyword Value to indicate the value of the variable. Here is the highlighting for all hire dates later than 1989. Because Hire date is a TDateTime field (which internally is a float), I cheated by just using the float value of January 1st, 1990 which is 32874. By default highlighter is a simple bold on white background. You can set these parameters to an area by clicking the Highlight button.
197	161
198		-	~~<figure>~~
199		-	~~<img src="lazreptutconditionalhighlight.png" title="lazreptutconditionalhighlight.png" />~~
200		-	~~<figcaption>lazreptutconditionalhighlight.png</figcaption>~~
201		-	~~</figure>~~
	162	+	![](/wiki-images/d/df/Lazreptutconditionalhighlight.png)
202	163
203	164		#### A picture is worth...
204	165
205	166		If you haven't already, we'll need to add a PHOTO field to our test database; using an SQL statement like this (note: unfortunately different databases use different syntax; BLOB can be CLOB,IMAGE,OLE...):
206	167
207	168		`ALTER TABLE EMPLOYEE ADD PHOTO BLOB;`
208	169
209	170		Now add some test data - the example here uses jpg files - into the PHOTO field with your favourite database tool. Note: this is the way Delphi DBImage works: just binary blobs with image data. By default, Lazarus DBImage is more flexible and stores the file extension before the image data, allowing different file formats to be used. For simplicity's sake, we'll use the Delphi approach.
210	171
211	172		> Note: For this "DBImage BLOB without file extension info" to work, you'll need the patch from issue 25453/at least revision ... of LazReport
212	173
213	174		Now we have to tell the report you need to treat all data as binary jpg image files. Click on frReport1, go to Object Inspector, events and initiates a procedure OnDBImageReader:
214	175
215	176		```delphi
216	177		procedure TForm1.frReport1DBImageRead(Sender: TObject; S: TStream;
217	178		var GraphExt: string);
218	179		begin
219	180		// Force TDBImage to Delphi compatible behaviour: únicamente acepta un formato de fichero, e.g. jpg
220	181		// esto significa que los BLOBs de la base de datos deben ser justamente ficheros jpg binarios sin más datos.
221	182		GraphExt:='jpg';
222	183		end;
223	184		```
224	185
225	186		In File\>Variables List, add the SQLQuery1.PHOTO field as variable Photo field, similarly to how you did this before. If you don't see the field, you may need to set the form's SQLQuery to inactive and active again to refresh the list of columns.
226	187
227	188		Click on the Insert image... icon on the left of the window; now click on the right side of the band to drop the image control. A Picture editor shows up:
228	189
229		-	~~<figure>~~
230		-	~~<img src="lazreptutpictureeditor.png" title="lazreptutpictureeditor.png" />~~
231		-	~~<figcaption>lazreptutpictureeditor.png</figcaption>~~
232		-	~~</figure>~~
	190	+	![](/wiki-images/4/48/Lazreptutpictureeditor.png)
233	191
234	192		If you wanted to always show the same picture, you'd just need to click Load ... (or double click on the picture control) and choose your image.
235	193
236	194		However, let's press the Memo button and insert your Photo variable:
237	195
238		-	~~<figure>~~
239		-	~~<img src="lazreptutphotofield.png" title="lazreptutphotofield.png" />~~
240		-	~~<figcaption>lazreptutphotofield.png</figcaption>~~
241		-	~~</figure>~~
	196	+	![](/wiki-images/5/56/Lazreptutphotofield.png)
242	197
243	198		This turns the picture into an object associated with the data field. Press OK as needed to get back to the report designer.
244	199
245	200		Adjust height and width as needed.
246	201
247	202		You can also press F11 to show the Object Inspector which allows you to edit more if needed:
248	203
249		-	~~<figure>~~
250		-	~~<img src="lazreptutobjectinspector.png" title="lazreptutobjectinspector.png" />~~
251		-	~~<figcaption>lazreptutobjectinspector.png</figcaption>~~
252		-	~~</figure>~~
	204	+	![](/wiki-images/b/b1/Lazreptutobjectinspector.png)
253	205
254	206		Close the report editor and save the report definition (with the same name, lazreporttutorial.lrf).
255	207
256	208		If you go to File\>Preview, you'll see your report includes the images.
257	209
258	210		Close the report editor and save the report definition as lazreporttutorial.lrf.
259	211
260	212		### Detail data
261	213
262	214		To do: show how to use the detail part of master/detail. see e.g. sample in components/lazreport/samples/editor directory; see the button title "Master-Detail" Please write me.
263	215
264	216		### Loading the report from the form
265	217
266	218		Now let's write the code required to load and view or edit our report. To this add the following code to the project:
267	219
268	220		```delphi
269	221		TForm1.Button2Click(Sender procedure: TObject);
270	222		begin
271	223		frReport1.LoadFromFile('lazreporttutorial.lrf');
272	224		frReport1.ShowReport;
273	225		end;
274	226		TForm1.ButtonClick(Sender procedure: TObject);
275	227		begin
276	228		frReport1.LoadFromFile('lazreporttutorial.lrf');
277	229		frReport1.DesignReport;
278	230		end;
279	231		```
280	232
281	233		You have a preview option that gives end users a way to modify the report without changing the basic application.
282	234
283	235		### Printing
284	236
285	237		Now we're going to add features to our basic example.
286	238
287	239		Add a TButton component with Caption := 'Print...', and a TPrintDialog. Behind the scenes, a project dependency on the Printer4Lazarus packages will be added by the IDE, so make sure that package is installed.
288	240
289	241		We end up with this:
290	242
291		-	~~<figure>~~
292		-	~~<img src="lazreptutformwithprintbutton.png" title="lazreptutformwithprintbutton.png" />~~
293		-	~~<figcaption>lazreptutformwithprintbutton.png</figcaption>~~
294		-	~~</figure>~~
	243	+	![](/wiki-images/e/e3/Lazreptutformwithprintbutton.png)
295	244
296	245		Now add the printers unit to your form's uses clauses.
297	246
298	247		Put the following code in the OnClick event of the Print button:
299	248
300	249		```delphi
301	250		procedure TForm1.Button3Click(Sender: TObject);
302	251		var
303	252		FromPage, ToPage, NumberCopies: Integer;
304	253		ind: Integer;
305	254		Collap: Boolean;
306	255		begin
307	256		// Load report definition from application directory
308	257		AppDirectory:=ExtractFilePath(ParamStr(0));
309	258		frReport1.LoadFromFile('lazreporttutorial.lrf');
310	259		// Need to keep track of which printer was originally selected to check for user changes
311	260		ind:= Printer.PrinterIndex;
312	261		// Prepare the report and just stop if we hit an error as continuing makes no sense
313	262		if not frReport1.PrepareReport then Exit;
314	263		// Set up dialog with some sensible defaults which user can change
315	264		with PrintDialog1 do
316	265		begin
317	266		Options:=[poPageNums ]; // allows selecting pages/page numbers
318	267		Copies:=1;
319	268		Collate:=true; // ordened copies
320	269		FromPage:=1; // start page
321	270		ToPage:=frReport1.EMFPages.Count; // last page
322	271		MaxPage:=frReport1.EMFPages.Count; // maximum allowed number of pages
323	272		if Execute then // show dialog; if succesful, process user feedback
324	273		begin
325	274		if (Printer.PrinterIndex <> ind ) // verify if selected printer has changed
326	275		or frReport1.CanRebuild // ... only makes sense if we can reformat the report
327	276		or frReport1.ChangePrinter(ind, Printer.PrinterIndex) //... then change printer
328	277		then
329	278		frReport1.PrepareReport //... and reformat for new printer
330	279		else
331	280		exit; // we couldn't honour the printer change
332	281
333	282		if PrintDialog1.PrintRange = prPageNums then // user made page range selection
334	283		begin
335	284		FromPage:=PrintDialog1.FromPage; // first page
336	285		ToPage:=PrintDialog1.ToPage; // last page
337	286		end;
338	287		NumberCopies:=PrintDialog1.Copies; // number of copies
339	288		// Print the report using the supplied pages & copies
340	289		frReport1.PrintPreparedReport(inttostr(FromPage)+'-'+inttostr(ToPage), NumberCopies);
341	290		end;
342	291		end;
343	292		end;
344	293		```
345	294
346	295		It's a bit long, but if needed, you can create a descendant of TfrReport with an easier printing method or class , create a PrintReport (Report: string) procedure to load the report and print.
347	296
348	297		When double clicking on frReport1, in the report designer File\>Page Options menu you get this:
349	298
350	299		Select paper size:
351	300
352		-	~~<figure>~~
353		-	~~<img src="lazreptutpapersize.png" title="lazreptutpapersize.png" />~~
354		-	~~<figcaption>lazreptutpapersize.png</figcaption>~~
355		-	~~</figure>~~
	301	+	![](/wiki-images/9/90/Lazreptutpapersize.png)
356	302
357	303		Choose desired margins, number of columns, and the space between them, layout order etc. ![](/wiki-images/4/4a/Lazreptutprintoptions.png)
358	304
359	305		### Report options
360	306
361	307		Via File\>Report Options you can set a default printer that will be used for the report (using the "Select when report loaded" checkbox).
362	308
363	309		If you want to include the total number of pages with the page number on each page, you need to select Two-pass report (which tells Lazreport to build the report twice, inserting total number of pages on the second run).
364	310
365		-	~~<figure>~~
366		-	~~<img src="lazreptutreportoptions.png" title="lazreptutreportoptions.png" />~~
367		-	~~<figcaption>lazreptutreportoptions.png</figcaption>~~
368		-	~~</figure>~~
	311	+	![](/wiki-images/2/2e/Lazreptutreportoptions.png)
369	312
370	313		On the Other tab, you can fill out some report metadata, as is done on the screenshot below: ![](/wiki-images/f/f6/Lazreptutreportoptionsother.png)
371	314
372	315		### General purpose variables
373	316
374	317		Now we'll add some report variables unrelated to the database data in our example. They let you e.g. show different names according to the context.
375	318
376	319		To do this, open the report editor and select the File menu and the Variable List. Add a Test category, and a test1 variable the same way we did earlier (with a space before the variable name):
377	320
378		-	~~<figure>~~
379		-	~~<img src="lazreptutvariableseditortestvar.png" title="lazreptutvariableseditortestvar.png" />~~
380		-	~~<figcaption>lazreptutvariableseditortestvar.png</figcaption>~~
381		-	~~</figure>~~
	321	+	![](/wiki-images/8/8d/Lazreptutvariableseditortestvar.png)
382	322
383	323		The only difference is that you will not select a value field, but leave None (the default value): ![](/wiki-images/2/20/Lazreptutvariabletest.png)
384	324
385	325		Return to Lazarus (do not forget to save your report, if necessary) and set up the OnGetValue'' event of thefrReport1''' component by adding the following code:
386	326
387	327		```delphi
388	328		procedure TForm1.frReport1GetValue(const ParName: String; var ParValue: Variant
389	329		);
390	330		begin
391	331		// Conditionally assign value:
392	332		if ParName='test1' then
393	333		ParValue:='Answer: Variable "test1"'; //perhaps replace with a call to a random function or something?
394	334		end;
395	335		```
396	336
397	337		Alternatively, you can also pass the value directly to the variable using the following code:
398	338
399	339		```delphi
400	340		procedure TForm1.Button1Click(Sender:TObject);
401	341		begin
402	342		frReport1.Values.FindVariable('test').Field := QuotedStr('test1');
403	343		frReport1.ShowReport;
404	344		end;
405	345		```
406	346
407	347		## See also
408	348
409	349		- [[LazReport Tutorial/pt\|Tutorial de LazReport]] Version used as a basis for this translation.
410	350		- [[LazReport Documentation]]
411	351
412	352		---
413	353		From the Free Pascal wiki, page "LazReport Tutorial", as it stood on 2020-04-02 after a change by Volkir, 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).
414	354		Category: LazReport
415	355		Category: Lazarus
416	356		Category: Tutorials

Back to history