Skip to content

Commit 962e302

Browse files
NickVolynkinNickVolynkin
committed
readme: Explain implementation steps
1 parent e89c668 commit 962e302

1 file changed

Lines changed: 121 additions & 18 deletions

File tree

‎README.md‎

Lines changed: 121 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,14 @@
44
[![](https://img.shields.io/badge/💬_Leave_Feedback-feecdd?style=flat-square)](#does-this-example-address-your-development-requirementsobjectives)
55
<!-- default badges end -->
66

7-
# DevExpress VCL Reports—Generate a PDF Report Using a Headless (non-GUI) application
7+
# DevExpress VCL Reports — Generate a Report Using a Headless (non-GUI) Application
88

9-
This example uses the DevExpress VCL Reports components to generate a PDF report using a command line application.
10-
The example demonstrates the capabilities of VCL Reports for producing reports in backend applications, webservers, or command line applications, all without the need for a GUI.
9+
This example uses the DevExpress VCL Reports to generate a PDF report using a command line application.
10+
The example demonstrates the capabilities of VCL Reports for producing reports in backend applications, Windows services,
11+
or plain command line applications, all without the need for a GUI.
1112

12-
The example includes projects for both [Delphi](./Delphi) and [C++Builder](./CPB).
13+
> ![Example of a PDF report produced by the command line application, showing customer order number 11077](./images/report.png)
1314
14-
> ![Example of a PDF report produced by the command line application, showing an alphabetical list of products](./images/report.png)
1515

1616
## Prerequisites
1717

@@ -20,21 +20,119 @@ See: [DevExpress Reports Prerequisites](https://docs.devexpress.com/VCL/405773/E
2020
> [!Note]
2121
> An application using VCL Reports in headless mode does not require the `WebView2Loader.dll` library (unlike GUI applications).
2222
23-
## Implementation Details
24-
25-
By following the steps outlined in this example, you'll create an application that produce the
26-
[DevExpress VCL Reports](https://docs.devexpress.com/VCL/405469/ExpressReports/vcl-reports).
2723

28-
### Prepare a Template Report Layout
24+
## Implementation Details
2925

30-
An application needs a template report layout, created in the [Report Designer](https://docs.devexpress.com/VCL/405469/ExpressReports/vcl-reports).
26+
By following the steps outlined in this example, you'll create an application that imports a report layout from a file,
27+
connects it with a data source, and exports a ready report to a PDF file.
3128

32-
You can [store a report layout in a REPX file](https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-file)
33-
or [in a database](https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-database).
3429

35-
This example loads a report layout from the [`Order.repx`](./Order.repx) file.
30+
### Step 1: Initialize a Report and Import a Report Layout
3631

37-
###
32+
An application needs a template report layout, created in the [Report Designer](https://docs.devexpress.com/VCL/405469/ExpressReports/vcl-reports).
33+
You can [import a report layout from a REPX file](https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-file)
34+
or [read a layout from a database](https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-database).
35+
36+
The current example imports a report layout from the `Order.repx` file.
37+
38+
**Delphi:**
39+
```pas
40+
// Step 1: Create a report instance and load the report layout
41+
AReport := TdxReport.Create(nil); // AReport: TdxReport;
42+
try
43+
// Set an internal report name (does not affect the exported PDF content and file name)
44+
AReport.ReportName := 'OrderReport';
45+
// Load the report layout from the specified file
46+
AReport.Layout.LoadFromFile('..\Order.repx');
47+
// ...
48+
finally
49+
AReport.Free;
50+
end;
51+
```
52+
53+
54+
### Step 2: Create a Database Connection
55+
56+
A VCL Report requires a source of data, which is usually represented by a database connection.
57+
The current example is using SQLite with the Northwind example database stored in `nwind.db`.
58+
59+
```pas
60+
// Step 2: Create a database connection
61+
// AConnection: TdxBackendDatabaseSQLConnection;
62+
AConnection := TdxBackendDatabaseSQLConnection.Create(nil);
63+
try
64+
// Assign a database name matching the name specified in the report layout
65+
AConnection.DisplayName := 'NWindConnectionString';
66+
// Assign a connection string to use the local SQLite database
67+
AConnection.ConnectionString := 'XpoProvider=SQLite; Data Source=..\nwind.db; Mode=ReadOnly';
68+
// ...
69+
finally:
70+
AConnection.Free;
71+
end:
72+
```
73+
74+
To learn more, follow the guide: [VCL Backend: Supported Database Systems](https://docs.devexpress.com/VCL/405703/ExpressCrossPlatformLibrary/vcl-backend/vcl-backend-supported-database-systems).
75+
76+
77+
### Step 3: Define Report Parameter Values
78+
79+
A report layout may have one or more parameters.
80+
VCL Reports use parameters to modify database queries and produce different reports using the same layout and data.
81+
For example, `Order.repx`has a single `OrderIDParameter` used to produce reports on customer orders with given Order IDs.
82+
83+
To modify parameters, load them using the `LoadParametersFromReport` method and assign values to members of the `Report.Parameters` list:
84+
85+
**Delphi:**
86+
```pas
87+
// Step 3: Define Report Parameter Values
88+
AReport.LoadParametersFromReport;
89+
// Set the value of the "OrderIdParameter" parameter in the report layout
90+
// AReportParameter: TdxReportParameter;
91+
for AReportParameter in AReport.Parameters do
92+
if AReportParameter.Name = 'OrderIdParameter' then
93+
AReportParameter.Value := '11077';
94+
```
95+
96+
97+
### Step 4: Export and Save to a File
98+
99+
Once you have configured a report and a data source, and defined report parameters.
100+
you can export a report to one or more formats.
101+
102+
The current example exports a PDF report and saves it to a file:
103+
104+
**Delphi:**
105+
```pas
106+
// Step 4: Export a report to PDF
107+
AStream := TMemoryStream.Create; // AStream: TMemoryStream;
108+
try
109+
// Export a report to PDF format and save it to a memory stream
110+
AReport.ExportToPDF(AStream);
111+
// Write the content of the memory stream to a file
112+
AStream.SaveToFile('Order_11077.pdf');
113+
finally
114+
AStream.Free;
115+
end;
116+
```
117+
118+
### Export Multiple Reports
119+
120+
Headless approach allows you to efficiently export multiple reports using the same layout and data, but different parameter combinations.
121+
Repeat steps 3 and 4 for each parameter combination.
122+
123+
**Delphi:**
124+
125+
```pas
126+
// Find each report parameter
127+
for AReportParameter in AReport.Parameters do
128+
if AReportParameter.Name = 'OrderIdParameter' then
129+
AOrderParameter := AReportParameter;
130+
131+
for OrderID in OrderIDList:
132+
// Assign values to report parameters
133+
AOrderParameter.Value = OrderID;
134+
// Proceed with step 4
135+
```
38136

39137

40138
## Files to Review
@@ -44,11 +142,16 @@ This example loads a report layout from the [`Order.repx`](./Order.repx) file.
44142
You view and edit this file using the [file storage example application](https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-file).
45143
- [`nwind.db`](./nwind.db) contains the Northwind example database.
46144

145+
47146
## Documentation and Examples
48147

49-
- [Documentation: DevExpress VCL Reports](https://docs.devexpress.com/VCL/405469/ExpressReports/vcl-reports)
50-
- [Example: Store Report Layouts within Text Files](https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-file)
51-
- [Example: Store Report Layouts in a Database](https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-database)
148+
- [Introduction to VCL Reports](https://docs.devexpress.com/VCL/405469/ExpressReports/vcl-reports)
149+
- [Tutorial: Create a table report using the Report Wizard](https://docs.devexpress.com/VCL/405760/ExpressReports/getting-started/create-table-report-using-report-wizard)
150+
- [How to store report layouts in REPX files (example application)](https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-file)
151+
- [How to store report layouts in a database (example application)](https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-database)
152+
- [How to use SQLite as a data source for reports (as demonstrated in the current example)](https://docs.devexpress.com/VCL/405750/ExpressCrossPlatformLibrary/vcl-backend/database-engines/vcl-backend-sqlite-support)
153+
- [API reference: `TdxReport.Layout` Property](https://docs.devexpress.com/VCL/dxReport.TdxReport.Layout)
154+
- [API reference: `TdxBackendDatabaseSQLConnection` Component](https://docs.devexpress.com/VCL/dxBackend.ConnectionString.SQL.TdxBackendDatabaseSQLConnection)
52155

53156

54157
<!-- feedback -->

0 commit comments

Comments
 (0)