Skip to content

Commit a02de43

Browse files
NickVolynkinNickVolynkin
committed
readme: draft
1 parent eb23b42 commit a02de43

4 files changed

Lines changed: 153 additions & 17 deletions

File tree

‎Delphi/uData.dfm‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ object DataModule1: TDataModule1
55
Width = 740
66
PixelsPerInch = 192
77
object mdLayouts: TdxMemData
8-
Active = True
98
Indexes = <>
109
Persistent.Data = {
1110
5665728FC2F5285C8FFE3F02000000000000000D0007004C61796F7574001400
@@ -794,14 +793,17 @@ object DataModule1: TDataModule1
794793
69616C697A65723E0D0A010B0000005400610062006C0065005200650070006F
795794
0072007400}
796795
SortOptions = []
797-
Left = 408
798-
Top = 112
796+
Left = 456
797+
Top = 256
799798
object mdLayoutsLayout: TBlobField
800799
FieldName = 'Layout'
801800
end
802801
object mdLayoutsName: TWideStringField
803802
FieldName = 'Name'
804803
end
804+
object mdLayoutsName2: TStringField
805+
FieldName = 'Name2'
806+
end
805807
end
806808
object dsLayouts: TDataSource
807809
DataSet = mdLayouts

‎Delphi/uData.pas‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ TDataModule1 = class(TDataModule)
1616
dxBackendDataConnectionManager1: TdxBackendDataConnectionManager;
1717
ReportsNWindConnectionString: TdxBackendDatabaseSQLConnection;
1818
dxSkinController1: TdxSkinController;
19+
mdLayoutsName2: TStringField;
1920
procedure DataModuleCreate(Sender: TObject);
2021
procedure DataModuleDestroy(Sender: TObject);
2122
private

‎Delphi/uMainForm.pas‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,10 +79,13 @@ procedure TMainForm.btnPreviewClick(Sender: TObject);
7979
dxReport1.ShowViewer;
8080
end;
8181

82+
// Event that is called when a user saves a report layout in the Report Designer
8283
procedure TMainForm.dxReport1LayoutChanged(ASender: TdxReport);
8384
begin
8485
DataModule1.mdLayouts.Edit;
86+
// Copy the report layout data to the BLOB field
8587
DataModule1.mdLayoutsLayout.Assign(dxReport1.Layout);
88+
// Save the report name which is not included in the layout
8689
DataModule1.mdLayoutsName.AsString := dxReport1.ReportName;
8790
DataModule1.mdLayouts.Post;
8891
end;

‎README.md‎

Lines changed: 144 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,30 +4,160 @@
44
[![](https://img.shields.io/badge/📖_How_to_use_DevExpress_Examples-e9f6fc?style=flat-square)](https://docs.devexpress.com/GeneralInformation/403183)
55
[![](https://img.shields.io/badge/💬_Leave_Feedback-feecdd?style=flat-square)](#does-this-example-address-your-development-requirementsobjectives)
66
<!-- default badges end -->
7-
# DevExpress VCL Reports - Store Report Layouts in a Database
87

9-
This example stores a [report layout](https://docs.devexpress.com/VCL/dxReport.TdxReport.Layout) (XML-based template) in the BLOB field of a memory-based dataset ([TdxMemData](https://docs.devexpress.com/VCL/dxmdaset.TdxMemData) inherited from the [TDataSet](https://docwiki.embarcadero.com/Libraries/Athens/en/Data.DB.TDataSet) class shipped with the standard VCL library).
8+
# DevExpress Reports for Delphi/C++Builder – Store Report Layouts in a Database
109

11-
## Testing the example
10+
This example application stores [DevExpress report layouts][TdxReport.Layout] in a database.
11+
The application allows users to create and save report layouts, modify existing layouts, and open layouts in Report Designer/Viewer.
12+
13+
To store a DevExpress Report layout to a database, you need to store the following two properties of the [TdxReport] component:
14+
15+
- [TdxReport.Layout] – an XML-based representation of the report template.
16+
This property is a `TStringList` and requires a `TBlobField` to store.
17+
- [TdxReport.ReportName] – the internal name of the layout, not included in the layout data.
18+
This value is a `string` and can be stored in a `TWideStringField`.
19+
20+
21+
## Prerequisites
22+
23+
[DevExpress Reports Prerequisites][req]
24+
25+
[req]: https://docs.devexpress.com/VCL/405773/ExpressCrossPlatformLibrary/vcl-backend/reports-dashboards-app-deployment#vcl-reportsdashboards-prerequisites
26+
27+
28+
## Test the Example
29+
30+
- Run the sample app and click **New Report** to create an empty database record.
31+
- Click **Show Designer** to display the [Report Designer][dx-report-designer] dialog.
32+
- Create a report layout using tools available within the UI.
33+
- Click the hamburger button, select the **Save** option, and close the dialog.
34+
- Close the app. The [TdxMemData] component will store layout data in the [data.dat] file between sessions.
35+
- Run the sample app again. Click **View Designer** to load the saved report layout,
36+
or **View Report** to preview a layout-based report in the [Report Viewer][dx-report-viewer] dialog.
37+
38+
39+
## Implementation Details
40+
41+
The example uses a memory-based dataset
42+
([TdxMemData] from the DevExpress library, inherited from [TDataSet], shipped with the standard VCL library).
43+
44+
Follow the steps below to store report layouts in a database of your choice, using the corresponding `TDataSet` descendant.
45+
46+
> Note:
47+
> Applications in this example isolate data components in separate data modules: [uData.pas] (Delphi) and [uData.cpp] (C++Builder).
48+
49+
### Step 1: Create a Dataset to Store Report Layout Data
50+
51+
52+
Follow these steps to create a memory-based dataset to store report layout data:
53+
54+
1. Create a [TdxMemData] component on a form (`mdLayouts` in the example).
55+
2. Create a [TDataSource] component on a form (`dsLayouts` in the example).
56+
Assign the `TDataSource.DataSet` value to the previously created dataset component:
57+
58+
![](./images/step1-2.png)
59+
3. Open the context menu and select **Field Editor…**:
60+
61+
![](./images/step1.png)
62+
4. Click **Add…** to create a BLOB field for layout data:
63+
64+
65+
### Step 2: Supply Layout Data to TdxReport
66+
67+
[TdxReport] requires a [Layout][TdxReport.Layout] and [ReportName][TdxReport.ReportName]
68+
to open the Viewer and Designer dialogs.
69+
Assign both properties by reading them from the dataset:
70+
71+
72+
### Step 3: Display Report Designer and Viewer
73+
74+
### Step 4: Handle Layout Changes
75+
76+
When a user edits and saves a report in the Report Designer,
77+
the value of [TdxReport.Layout] changes and a `LayoutChanged` event is called.
78+
Handle this event to save the updated layout to the active dataset record.
79+
80+
81+
```
82+
procedure TMainForm.dxReport1LayoutChanged(ASender: TdxReport);
83+
begin
84+
// Start editing the active dataset record
85+
DataModule1.mdLayouts.Edit;
86+
// Save the report layout to the database
87+
DataModule1.mdLayoutsLayout.Assign(dxReport1.Layout);
88+
// Save the report name which is not included in the layout
89+
DataModule1.mdLayoutsName.AsString := dxReport1.ReportName;
90+
// Finish editing and write a modified record
91+
DataModule1.mdLayouts.Post;
92+
end;
93+
```
94+
95+
### Step 5: Save the Database State when Application Exists
96+
97+
98+
99+
## Files to Review
100+
101+
- [uData.pas] (Delphi) and [uData.cpp] (C++Builder) read and store layout data in a database represented by an in-memory storage component.
102+
- [data.dat] stores layout data between application sessions.
103+
- [uMainForm.pas] (Delphi) and [uMainForm.cpp] (C++Builder) supply layout data from the data module to [TdxReport.Layout] and display Report Designer and Viewer.
104+
- [nwind.db] contains the Northwind sample database used as a data source for report content.
105+
106+
[uData.pas]: ./Delphi/uData.pas
107+
[uData.cpp]: ./CPB/uData.cpp
108+
[data.dat]: ./Delphi/data.dat
109+
[uMainForm.pas]: ./Delphi/uMainForm.pas
110+
[uMainForm.cpp]: ./CPB/uMainForm.cpp
111+
[nwind.db]: ./Delphi/nwind.db
12112

13-
* Run the sample app and click **New Report** to create an empty database record.
14-
* Click **Show Designer** to display the [Report Designer](https://docs.devexpress.com/XtraReports/119176/web-reporting/web-end-user-report-designer) dialog.
15-
* Create a report layout using tools available within the UI.
16-
* Click the hamburger button, select the **Save** option, and close the dialog.
17-
* Close the app. The [TdxMemData](https://docs.devexpress.com/VCL/dxmdaset.TdxMemData) component will store layout data between sessions.
18-
* Run the sample app again. Click **View Designer** to load the saved report layout, or **View Report** to preview a layout-based report in the [Report Viewer](https://docs.devexpress.com/XtraReports/401850/web-reporting/web-document-viewer) dialog.
19113

20114
## Documentation
21115

22-
* [TdxReport.Layout Property](https://docs.devexpress.com/VCL/dxReport.TdxReport.Layout)
23-
* [TdxBackendDataSetJSONConnection Component](https://docs.devexpress.com/VCL/dxBackend.ConnectionString.JSON.DataSet.TdxBackendDataSetJSONConnection)
116+
- [Introduction to VCL Reports][reports-intro]
117+
- [Tutorial: Create a table report using the Report Wizard][report-wizard]
118+
- [Use SQLite as a data source for reports (as demonstrated in the current example)][sqlite-data-source]
119+
- [Store report layouts in REPX files at design-time][reports-design-time-store]
120+
- API reference:
121+
- [TdxReport.ReportName]
122+
- [TdxReport.Layout] (an XML-based layout template that can be stored in the BLOB field of a database)
123+
- [TdxReport.ReportName]
124+
- [TdxMemData] (used to store report layout data in application runtime and between sessions)
125+
- [TDataSet] (ancestor of the `TdxMemData`, contains generic database connection methods)
126+
- [TdxBackendDatabaseSQLConnection] (used to supply data to reports)
127+
128+
<!-- documentation links -->
129+
[reports-intro]: https://docs.devexpress.com/VCL/405469/ExpressReports/vcl-reports
130+
[report-wizard]: https://docs.devexpress.com/VCL/405760/ExpressReports/getting-started/create-table-report-using-report-wizard
131+
[sqlite-data-source]: https://docs.devexpress.com/VCL/405750/ExpressCrossPlatformLibrary/vcl-backend/database-engines/vcl-backend-sqlite-support
132+
[reports-design-time-store]: https://docs.devexpress.com/VCL/dxReport.TdxReport.Layout#string-list-editor
133+
[dx-report-viewer]: https://docs.devexpress.com/XtraReports/401850/web-reporting/web-document-viewer
134+
[dx-report-designer]: https://docs.devexpress.com/XtraReports/119176/web-reporting/web-end-user-report-designer
135+
136+
137+
<!-- reference links -->
138+
[TdxReport]: https://docs.devexpress.com/VCL/dxReport.TdxReport
139+
[TdxReport.Layout]: https://docs.devexpress.com/VCL/dxReport.TdxReport.Layout
140+
[TdxReport.ReportName]: https://docs.devexpress.com/VCL/dxReport.TdxReport.ReportName
141+
[TdxBackendDatabaseSQLConnection]: https://docs.devexpress.com/VCL/dxBackend.ConnectionString.SQL.TdxBackendDatabaseSQLConnection
142+
[TdxBackendDataSetJSONConnection]: https://docs.devexpress.com/VCL/dxBackend.ConnectionString.JSON.DataSet.TdxBackendDataSetJSONConnection
143+
[TdxMemData]: https://docs.devexpress.com/VCL/dxmdaset.TdxMemData
144+
[TDataSet]: https://docwiki.embarcadero.com/Libraries/Athens/en/Data.DB.TDataSet
145+
146+
<!-- external documentation links -->
147+
<!-- in-repository links -->
148+
149+
150+
## More Examples
151+
152+
- [Store report layouts in REPX files][file-example]
153+
154+
[file-example]: https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-file
155+
156+
24157
<!-- feedback -->
25158
## Does This Example Address Your Development Requirements/Objectives?
26159

27160
[<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-store-layout-template-database&~~~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-store-layout-template-database&~~~was_helpful=no)
28161

29162
(you will be redirected to DevExpress.com to submit your response)
30163
<!-- feedback end -->
31-
32-
33-

0 commit comments

Comments
 (0)