Skip to content

Commit 96fd8d5

Browse files
NickVolynkindmitry-eliseev-devexpressAbadzhevdennis-garavsky
committed
readme: Describe the example: test, implement, links to read
Co-authored-by: Dmitry Eliseev <dmitry.eliseev@devexpress.com> Co-authored-by: Vladimir Abadzhev <vladimira@devexpress.com> Co-authored-by: Denis Garavsky <denis.garavsky@devexpress.com>
1 parent 27e57d6 commit 96fd8d5

2 files changed

Lines changed: 182 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 182 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,191 @@
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 Reports in a Backend / Service Application
8+
9+
This example uses DevExpress Reports for Delphi/C++Builder to generate reports in a command line application.
10+
The application accepts an order ID parameter, queries the database for order data,
11+
and exports an "order" report as a PDF file.
12+
13+
This example bypasses the DevExpress Report Viewer dialog and generates a report
14+
using the DevExpress Reports backend.
15+
Use the approach demonstrated in this sample project to implement
16+
Web API backends, Windows Services, workflows, and scheduled jobs.
17+
This approach can be particularly beneficial for the following usage scenarios
18+
(reports generated without direct user interaction):
19+
20+
- Mass-export reports to PDF, DOCX, image, and other formats.
21+
- Share, email, and print report documents silently.
22+
- Implement custom report management UIs.
23+
24+
---
25+
26+
![A PDF report example generated by a command line application (demonstrates order number 11077)](./images/report.png)
27+
28+
---
29+
30+
## Prerequisites
31+
32+
[DevExpress Reports Prerequisites][req]
33+
34+
[req]: https://docs.devexpress.com/VCL/405773/ExpressCrossPlatformLibrary/vcl-backend/reports-dashboards-app-deployment#vcl-reportsdashboards-prerequisites
35+
36+
## Test the Example
37+
38+
1. Open and build the Delphi project in the RAD Studio.
39+
2. Start a console session and navigate to the _Delphi_ project directory.
40+
3. Run the app and specify the order ID (a number between 10248 and 11077):
41+
42+
```console
43+
> PDFReportGenerator.exe 11077
44+
45+
Report saved to: ..\Order_11077.pdf
46+
```
47+
4. Generate reports for other order IDs and compare generated PDF files.
48+
49+
## Implementation Details
50+
51+
Follow the steps below to create an application that imports a report layout from a file,
52+
binds the layout to data, and exports the generated report to a PDF file.
53+
54+
55+
### Step 1: Initialize a Report and Import a Report Layout
56+
57+
An application requires a template report layout previously created in the [Report Designer][designer].
58+
You can [import a report layout from a REPX file][file] or [load a layout from a database][database].
59+
60+
[designer]: https://docs.devexpress.com/VCL/405469/ExpressReports/vcl-reports
61+
[file]: https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-file
62+
[database]: https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-database
63+
64+
This example imports a report layout from the `Order.repx` file.
65+
66+
**Delphi:**
67+
```pas
68+
AReport := TdxReport.Create(nil); // AReport: TdxReport;
69+
try
70+
// Set an internal report name (does not affect the exported content)
71+
AReport.ReportName := 'Order Report';
72+
// Load the report layout from the specified file
73+
AReport.Layout.LoadFromFile('Order.repx');
74+
// ...
75+
finally
76+
AReport.Free;
77+
end;
78+
```
79+
80+
81+
### Step 2: Create a Database Connection
82+
83+
Create a database connection component to supply data to the report.
84+
This example uses a SQL connection component with a built-in SQLite engine to load the Northwind sample database stored in `nwind.db`.
85+
86+
```pas
87+
// AConnection: TdxBackendDatabaseSQLConnection;
88+
AConnection := TdxBackendDatabaseSQLConnection.Create(nil);
89+
try
90+
// Assign a database name matching the name specified in the report layout
91+
AConnection.DisplayName := 'NWindConnectionString';
92+
// Assign a connection string required to use the local SQLite database
93+
AConnection.ConnectionString := 'XpoProvider=SQLite; Data Source=nwind.db; Mode=ReadOnly';
94+
// ...
95+
finally
96+
AConnection.Free;
97+
end;
98+
```
99+
100+
For detailed information on data source management and supported database engines, refer to the following help topic:
101+
[VCL Backend: Supported Database Systems][dbms].
102+
103+
[dbms]: https://docs.devexpress.com/VCL/405703/ExpressCrossPlatformLibrary/vcl-backend/vcl-backend-supported-database-systems
104+
105+
### Step 3: Define Report Parameter Values
106+
107+
A report layout may include one or more parameters.
108+
Parameters allow you to modify database queries and generate different reports
109+
based on the same report template and underlying data.
110+
For example, `Order.repx` includes a single `OrderIDParameter` that filters data by order ID.
111+
112+
To modify parameters, load them using the `LoadParametersFromReport` method
113+
and assign values to `Report.Parameters` list members as follows:
114+
115+
**Delphi:**
116+
```pas
117+
AReport.LoadParametersFromReport;
118+
// Set the "OrderIdParameter" value in the report layout
119+
AReport.Parameters['OrderIdParameter'].Value := AOrderID;
120+
```
121+
122+
123+
### Step 4: Export Report Content to a File
124+
125+
This example exports a report to a PDF file:
126+
127+
**Delphi:**
128+
```pas
129+
AStream := TMemoryStream.Create; // AStream: TMemoryStream;
130+
try
131+
// Export a report to a memory stream in the PDF format
132+
AReport.ExportToPDF(AStream);
133+
// Save memory stream content to a file
134+
AStream.SaveToFile('Order_' + AOrderID + '.pdf');
135+
finally
136+
AStream.Free;
137+
end;
138+
```
139+
140+
### Export Multiple Reports
141+
142+
The approach outlined in this example allows you to generate and export multiple reports based on the same layout and data
143+
using a list of parameters.
144+
You need to initialize the report layout and data connection once (steps 1 and 2)
145+
and repeat steps 3 and 4 for each parameter.
146+
147+
**Delphi:**
148+
149+
```pas
150+
// ...
151+
AReport.LoadParametersFromReport;
152+
153+
for AOrderID in AOrderIDList:
154+
AReport.Parameters['OrderIdParameter'].Value := AOrderID;
155+
156+
AStream := TMemoryStream.Create; // AStream: TMemoryStream;
157+
try
158+
// Export a report to a memory stream in the PDF format
159+
AReport.ExportToPDF(AStream);
160+
// Save memory stream content to a file
161+
AStream.SaveToFile('Order_' + AOrderID + '.pdf');
162+
finally
163+
AStream.Free;
164+
end;
165+
end;
166+
```
167+
168+
169+
## Files to Review
170+
171+
- [`Delphi/PDFReportGenerator.dpr`](./Delphi/PDFReportGenerator.dpr) generates a report in non-interactive (headless) mode.
172+
- [`Order.repx`](./Order.repx) contains a report layout designed to generate a customer order report.
173+
You can view and edit this file using the [file storage example application](https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-file).
174+
- [`nwind.db`](./nwind.db) contains the Northwind sample database.
175+
176+
177+
## Documentation and Examples
178+
179+
- [Introduction to VCL Reports](https://docs.devexpress.com/VCL/405469/ExpressReports/vcl-reports)
180+
- [Tutorial: Create a table report using the Report Wizard](https://docs.devexpress.com/VCL/405760/ExpressReports/getting-started/create-table-report-using-report-wizard)
181+
- [How to store report layouts in REPX files (example application)](https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-file)
182+
- [How to store report layouts in a database (example application)](https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-database)
183+
- [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)
184+
- [API reference: `TdxReport.Layout` Property](https://docs.devexpress.com/VCL/dxReport.TdxReport.Layout)
185+
- [API reference: `TdxBackendDatabaseSQLConnection` Component](https://docs.devexpress.com/VCL/dxBackend.ConnectionString.SQL.TdxBackendDatabaseSQLConnection)
186+
7187

8-
9188
<!-- feedback -->
10-
## Does this example address your development requirements/objectives?
189+
## Does This Example Address Your Development Requirements/Objectives?
11190

12-
[<img src="https://www.devexpress.com/support/examples/i/yes-button.svg"/>](https://www.devexpress.com/support/examples/survey.xml?utm_source=github&utm_campaign=vcl-reports-filter-export-report-pdf-in-console-app&~~~was_helpful=yes) [<img src="https://www.devexpress.com/support/examples/i/no-button.svg"/>](https://www.devexpress.com/support/examples/survey.xml?utm_source=github&utm_campaign=vcl-reports-filter-export-report-pdf-in-console-app&~~~was_helpful=no)
191+
[<img src="https://www.devexpress.com/support/examples/i/yes-button.svg"/>](https://www.devexpress.com/support/examples/survey.xml?utm_source=github&utm_campaign=vcl-reports-non-interactive-export&~~~was_helpful=yes) [<img src="https://www.devexpress.com/support/examples/i/no-button.svg"/>](https://www.devexpress.com/support/examples/survey.xml?utm_source=github&utm_campaign=vcl-reports-non-interactive-export&~~~was_helpful=no)
13192

14193
(you will be redirected to DevExpress.com to submit your response)
15194
<!-- feedback end -->

‎images/report.png‎

128 KB
Loading

0 commit comments

Comments
 (0)