Skip to content

Commit 903d9e2

Browse files
NickVolynkinNickVolynkin
committed
readme: Explain implementation steps
1 parent e89c668 commit 903d9e2

1 file changed

Lines changed: 117 additions & 19 deletions

File tree

‎README.md‎

Lines changed: 117 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,13 @@
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-
14-
> ![Example of a PDF report produced by the command line application, showing an alphabetical list of products](./images/report.png)
13+
> ![Example of a PDF report produced by the command line application, showing customer order number 11077](./images/report.png)
1514
1615
## Prerequisites
1716

@@ -22,19 +21,113 @@ See: [DevExpress Reports Prerequisites](https://docs.devexpress.com/VCL/405773/E
2221
2322
## Implementation Details
2423

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).
24+
By following the steps outlined in this example, you'll create an application that imports a report layout from a file,
25+
connects it with a data source, and exports a ready report to a PDF file.
2726

28-
### Prepare a Template Report Layout
27+
### Step 1: Initialize a Report and Import a Report Layout
2928

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

39132

40133
## Files to Review
@@ -46,9 +139,14 @@ This example loads a report layout from the [`Order.repx`](./Order.repx) file.
46139

47140
## Documentation and Examples
48141

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)
142+
143+
- [Introduction to VCL Reports](https://docs.devexpress.com/VCL/405469/ExpressReports/vcl-reports)
144+
- [Tutorial: Create a table report using the Report Wizard](https://docs.devexpress.com/VCL/405760/ExpressReports/getting-started/create-table-report-using-report-wizard)
145+
- [How to store report layouts in REPX files (example application)](https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-file)
146+
- [How to store report layouts in a database (example application)](https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-database)
147+
- [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)
148+
- [API reference: `TdxReport.Layout` Property](https://docs.devexpress.com/VCL/dxReport.TdxReport.Layout)
149+
- [API reference: `TdxBackendDatabaseSQLConnection` Component](https://docs.devexpress.com/VCL/dxBackend.ConnectionString.SQL.TdxBackendDatabaseSQLConnection)
52150

53151

54152
<!-- feedback -->

0 commit comments

Comments
 (0)