LazReport Tutorial: what changed

Revision 2 to 3. 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	36		![](/wiki-images/4/4f/Lazreptut01.png)
37	37
38	38		Double-click on the TfrReport icon (or right-click, Design Report) to bring up the report designer:
39	39
40	40		![](/wiki-images/6/6a/Lazreptut01b.png)
41	41
42	42		### Setting up variables
43	43
44	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.
45	45
46	46		In the File menu, click Variables list. Now you get an overview of the defined variables:
47	47
48	48		![](/wiki-images/d/d9/Lazreptutvariableseditor.png)
49	49
50	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.
51	51
52	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.
53	53
54	54		![](/wiki-images/8/86/Lazreptutdefinevariables.png)
55	55
56	56		Finally click on OK to confirm your entries, and you'll see this:
57	57
58	58		![](/wiki-images/f/ff/Lazreptutvariablesdefined.png)
59	59
60	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:
61	61
62	62		![](/wiki-images/b/b6/Lazreptutvarhiredatetofield.png)
63	63
64	64		### Objects and bands
65	65
66	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:
67	67
68	68		- the mouse icon pointer
69	69		- rectangle object
70	70		- band
71	71		- picture object
72	72		- subreport
73	73		- draw lines
74	74		- insert barcode object
75	75
76	76		![](/wiki-images/6/6a/Lazreptut01b.png)
77	77
78	78		Click the band icon, go to the report surface, and click on it to drop a band object.
79	79
80	80		![](/wiki-images/2/29/Lazreptutinsertnewband.png)
81	81
82	82		You must click on the type of band you want to create. Select Report title and click OK.
83	83
84	84		\| Band type \| Use \|
85	85		\|----\|----\|
86	86		\| Report title \| Shown only on the first page \|
87	87		\| Report summary \| Shown only on the last page \|
88	88		\| Page header \| Shown at the top of each page \|
89	89		\| Page footer \| Shown at the bottomof each page \|
90	90		\| Master header \| Shown at the beginning of the first detail band/level \|
91	91		\| Master data \| First detail level data; repeated for each record in dataset \|
92	92		\| Master footer \| Shown at the end of the first detail band/level \|
93	93		\| Detail header \| Shown at the beginning of the second detail band/level \|
94	94		\| Detail data \| Second detail level data \|
95	95		\| Detail footer \| Shown at the end of the second detail band/level \|
96	96		\| Subdetail header \| Shown at the beginning of the third detail band/level \|
97	97		\| Subdetail data \| Third detail level data \|
98	98		\| Subdetail footer \| Shown at the end of the third detail band/level \|
99	99		\| Overlay \| Shown once on each page lower layer \|
100	100		\| Column header \| Shown at the top of every column \|
101	101		\| Column footer \| Shown at the bottom of every column \|
102	102		\| Group header \| Shown at the top of every group \|
103	103		\| Group footer \| Shown at the bottom of every group \|
104	104		\| Cross header \| Shown at the top of cross tables/pivot tables \|
105	105		\| Cross data \| Shows cross tables/pivot table data \|
106	106		\| Cross footer \| Shown at the bottom of cross tables/pivot tables \|
107	107
108	108		### Report title
109	109
110	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:
111	111
112	112		![](/wiki-images/a/ad/Lazreptutreporttitle.png)
113	113
114	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.
115	115
116	116		### The main event: showing data in the master data band
117	117
118	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.
119	119
120	120		![](/wiki-images/b/b7/Lazreptutbanddatasource.png)
121	121
122	122		In the left half of the band we insert a rectangle and double click. The familiar text editor appears.
123	123
124	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.
125	125
126	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.
127	127
128	128		The next line Salary \[Salary field\] is written similarly.
129	129
130	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.
131	131
132	132		![](/wiki-images/6/6a/Lazreptutmasterdata.png)
133	133
134	134		You can use all kinds of operators and functions in your calculations; see [[LazReport Documentation\|LazReport Documentation#Documentation]] for an overview.
135	135
136	136		#### Formatting output
137	137
138	138		You can control how the text in the rectangles is displayed.
139	139
140	140		Let's first add a new rectangle with the Hire date field variable.
141	141
142	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.
143	143
144	144		Let's set the date format you want here:
145	145
146	146		![](/wiki-images/1/12/Lazreptutformattingdate.png)
147	147
148	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:
149	149
150	150		- The Text type does not allow any Number type formatting.
151	151		- The Number type requires a number of any type (Integer, Double, Currency...).
152	152		- The Date type: you can choose a pre-defined format or write a custom format like MM/DD/YY for example.
153	153
154	154		Except for Text and Logic types, you can use the formatting strings you also use in Lazarus.
155	155
156	156		Other formatting options are present on the button bar below the menu (e.g. bold, italic, highlighting).
157	157
158	158		Highlighting is very useful for emphasizing data. You can specify a condition that determines when highlighting is applied.
159	159
160	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.
161	161
162	162		![](/wiki-images/d/df/Lazreptutconditionalhighlight.png)
163	163
164	164		#### A picture is worth...
165	165
166	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...):
167	167
168		-	~~`ALTER TABLE EMPLOYEE ADD PHOTO BLOB;`~~
	168	+	```text
	169	+	ALTER TABLE EMPLOYEE ADD PHOTO BLOB;
	170	+	```
169	171
170	172		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.
171	173
172	174		> Note: For this "DBImage BLOB without file extension info" to work, you'll need the patch from issue 25453/at least revision ... of LazReport
173	175
174	176		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:
175	177
176	178		```delphi
177	179		procedure TForm1.frReport1DBImageRead(Sender: TObject; S: TStream;
178	180		var GraphExt: string);
179	181		begin
180	182		// Force TDBImage to Delphi compatible behaviour: únicamente acepta un formato de fichero, e.g. jpg
181	183		// esto significa que los BLOBs de la base de datos deben ser justamente ficheros jpg binarios sin más datos.
182	184		GraphExt:='jpg';
183	185		end;
184	186		```
185	187
186	188		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.
187	189
188	190		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:
189	191
190	192		![](/wiki-images/4/48/Lazreptutpictureeditor.png)
191	193
192	194		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.
193	195
194	196		However, let's press the Memo button and insert your Photo variable:
195	197
196	198		![](/wiki-images/5/56/Lazreptutphotofield.png)
197	199
198	200		This turns the picture into an object associated with the data field. Press OK as needed to get back to the report designer.
199	201
200	202		Adjust height and width as needed.
201	203
202	204		You can also press F11 to show the Object Inspector which allows you to edit more if needed:
203	205
204	206		![](/wiki-images/b/b1/Lazreptutobjectinspector.png)
205	207
206	208		Close the report editor and save the report definition (with the same name, lazreporttutorial.lrf).
207	209
208	210		If you go to File\>Preview, you'll see your report includes the images.
209	211
210	212		Close the report editor and save the report definition as lazreporttutorial.lrf.
211	213
212	214		### Detail data
213	215
214	216		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.
215	217
216	218		### Loading the report from the form
217	219
218	220		Now let's write the code required to load and view or edit our report. To this add the following code to the project:
219	221
220	222		```delphi
221	223		TForm1.Button2Click(Sender procedure: TObject);
222	224		begin
223	225		frReport1.LoadFromFile('lazreporttutorial.lrf');
224	226		frReport1.ShowReport;
225	227		end;
226	228		TForm1.ButtonClick(Sender procedure: TObject);
227	229		begin
228	230		frReport1.LoadFromFile('lazreporttutorial.lrf');
229	231		frReport1.DesignReport;
230	232		end;
231	233		```
232	234
233	235		You have a preview option that gives end users a way to modify the report without changing the basic application.
234	236
235	237		### Printing
236	238
237	239		Now we're going to add features to our basic example.
238	240
239	241		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.
240	242
241	243		We end up with this:
242	244
243	245		![](/wiki-images/e/e3/Lazreptutformwithprintbutton.png)
244	246
245	247		Now add the printers unit to your form's uses clauses.
246	248
247	249		Put the following code in the OnClick event of the Print button:
248	250
249	251		```delphi
250	252		procedure TForm1.Button3Click(Sender: TObject);
251	253		var
252	254		FromPage, ToPage, NumberCopies: Integer;
253	255		ind: Integer;
254	256		Collap: Boolean;
255	257		begin
256	258		// Load report definition from application directory
257	259		AppDirectory:=ExtractFilePath(ParamStr(0));
258	260		frReport1.LoadFromFile('lazreporttutorial.lrf');
259	261		// Need to keep track of which printer was originally selected to check for user changes
260	262		ind:= Printer.PrinterIndex;
261	263		// Prepare the report and just stop if we hit an error as continuing makes no sense
262	264		if not frReport1.PrepareReport then Exit;
263	265		// Set up dialog with some sensible defaults which user can change
264	266		with PrintDialog1 do
265	267		begin
266	268		Options:=[poPageNums ]; // allows selecting pages/page numbers
267	269		Copies:=1;
268	270		Collate:=true; // ordened copies
269	271		FromPage:=1; // start page
270	272		ToPage:=frReport1.EMFPages.Count; // last page
271	273		MaxPage:=frReport1.EMFPages.Count; // maximum allowed number of pages
272	274		if Execute then // show dialog; if succesful, process user feedback
273	275		begin
274	276		if (Printer.PrinterIndex <> ind ) // verify if selected printer has changed
275	277		or frReport1.CanRebuild // ... only makes sense if we can reformat the report
276	278		or frReport1.ChangePrinter(ind, Printer.PrinterIndex) //... then change printer
277	279		then
278	280		frReport1.PrepareReport //... and reformat for new printer
279	281		else
280	282		exit; // we couldn't honour the printer change
281	283
282	284		if PrintDialog1.PrintRange = prPageNums then // user made page range selection
283	285		begin
284	286		FromPage:=PrintDialog1.FromPage; // first page
285	287		ToPage:=PrintDialog1.ToPage; // last page
286	288		end;
287	289		NumberCopies:=PrintDialog1.Copies; // number of copies
288	290		// Print the report using the supplied pages & copies
289	291		frReport1.PrintPreparedReport(inttostr(FromPage)+'-'+inttostr(ToPage), NumberCopies);
290	292		end;
291	293		end;
292	294		end;
293	295		```
294	296
295	297		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.
296	298
297	299		When double clicking on frReport1, in the report designer File\>Page Options menu you get this:
298	300
299	301		Select paper size:
300	302
301	303		![](/wiki-images/9/90/Lazreptutpapersize.png)
302	304
303	305		Choose desired margins, number of columns, and the space between them, layout order etc. ![](/wiki-images/4/4a/Lazreptutprintoptions.png)
304	306
305	307		### Report options
306	308
307	309		Via File\>Report Options you can set a default printer that will be used for the report (using the "Select when report loaded" checkbox).
308	310
309	311		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).
310	312
311	313		![](/wiki-images/2/2e/Lazreptutreportoptions.png)
312	314
313	315		On the Other tab, you can fill out some report metadata, as is done on the screenshot below: ![](/wiki-images/f/f6/Lazreptutreportoptionsother.png)
314	316
315	317		### General purpose variables
316	318
317	319		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.
318	320
319	321		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):
320	322
321	323		![](/wiki-images/8/8d/Lazreptutvariableseditortestvar.png)
322	324
323	325		The only difference is that you will not select a value field, but leave None (the default value): ![](/wiki-images/2/20/Lazreptutvariabletest.png)
324	326
325	327		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:
326	328
327	329		```delphi
328	330		procedure TForm1.frReport1GetValue(const ParName: String; var ParValue: Variant
329	331		);
330	332		begin
331	333		// Conditionally assign value:
332	334		if ParName='test1' then
333	335		ParValue:='Answer: Variable "test1"'; //perhaps replace with a call to a random function or something?
334	336		end;
335	337		```
336	338
337	339		Alternatively, you can also pass the value directly to the variable using the following code:
338	340
339	341		```delphi
340	342		procedure TForm1.Button1Click(Sender:TObject);
341	343		begin
342	344		frReport1.Values.FindVariable('test').Field := QuotedStr('test1');
343	345		frReport1.ShowReport;
344	346		end;
345	347		```
346	348
347	349		## See also
348	350
349	351		- [[LazReport Tutorial/pt\|Tutorial de LazReport]] Version used as a basis for this translation.
350	352		- [[LazReport Documentation]]
351	353
352	354		---
353	355		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).
354	356		Category: LazReport
355	357		Category: Lazarus
356	358		Category: Tutorials

Back to history