readme: draft

Author: NickVolynkin

Delphi/uData.dfm

@@ -5,7 +5,6 @@ object DataModule1: TDataModule1
   Width = 740
   PixelsPerInch = 192
   object mdLayouts: TdxMemData
-    Active = True
     Indexes = <>
     Persistent.Data = {
       5665728FC2F5285C8FFE3F02000000000000000D0007004C61796F7574001400
@@ -795,7 +794,7 @@ object DataModule1: TDataModule1
       0072007400}
     SortOptions = []
     Left = 408
-    Top = 112
+    Top = 104
     object mdLayoutsLayout: TBlobField
       FieldName = 'Layout'
     end

Delphi/uMainForm.pas

@@ -79,10 +79,13 @@ procedure TMainForm.btnPreviewClick(Sender: TObject);
   dxReport1.ShowViewer;
 end;
 
+// Event that is called when a user saves a report layout in the Report Designer
 procedure TMainForm.dxReport1LayoutChanged(ASender: TdxReport);
 begin
   DataModule1.mdLayouts.Edit;
+  // Copy the report layout data to the BLOB field
   DataModule1.mdLayoutsLayout.Assign(dxReport1.Layout);
+  // Save the report name which is not included in the layout
   DataModule1.mdLayoutsName.AsString := dxReport1.ReportName;
   DataModule1.mdLayouts.Post;
 end;

README.md

@@ -4,30 +4,177 @@
 [![](https://img.shields.io/badge/📖_How_to_use_DevExpress_Examples-e9f6fc?style=flat-square)](https://docs.devexpress.com/GeneralInformation/403183)
 [![](https://img.shields.io/badge/💬_Leave_Feedback-feecdd?style=flat-square)](#does-this-example-address-your-development-requirementsobjectives)
 <!-- default badges end -->
-# DevExpress VCL Reports - Store Report Layouts in a Database
 
-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).
+# DevExpress Reports for Delphi/C++Builder – Store Report Layouts in a Database
 
-## Testing the example
+This example application stores [DevExpress report layouts][TdxReport.Layout] in a database.
+The application allows users to create and save report layouts, modify existing layouts, and open layouts in Report Designer/Viewer.
+
+To store a DevExpress Report layout to a database, you need to store the following two properties of the [TdxReport] component:
+
+-   [TdxReport.Layout] – an XML-based representation of the report template. 
+    This property is a `TStringList` and requires a `TBlobField` to store.
+-   [TdxReport.ReportName] – the internal name of the layout, not included in the layout data.
+    This value is a `string` and can be stored in a `TWideStringField`.
+
+
+## Prerequisites
+
+[DevExpress Reports Prerequisites][req]
+
+[req]: https://docs.devexpress.com/VCL/405773/ExpressCrossPlatformLibrary/vcl-backend/reports-dashboards-app-deployment#vcl-reportsdashboards-prerequisites
+
+
+## Test the Example
+
+-   Run the sample app and click **New Report** to create an empty database record.
+-   Click **Show Designer** to display the [Report Designer][dx-report-designer] dialog.
+-   Create a report layout using tools available within the UI.
+-   Click the hamburger button, select the **Save** option, and close the dialog.
+-   Close the app. The [TdxMemData] component will store layout data in the [data.dat] file between sessions.
+-   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][dx-report-viewer] dialog.
+
+
+## Implementation Details
+
+The example uses a memory-based dataset
+([TdxMemData] from the DevExpress library, inherited from [TDataSet], shipped with the standard VCL library).
+
+Follow the steps below to store report layouts in a database of your choice, using the corresponding `TDataSet` descendant.
+
+> Note:
+> Applications in this example isolate data components in separate data modules: [uData.pas] (Delphi) and [uData.cpp] (C++Builder).
+
+### Step 1: Create a Dataset to Store Report Layout Data
+
+
+Follow these steps to create a memory-based dataset to store report layout data:
+
+1.  Create a [TdxMemData] component on a form (`mdLayouts` in the example).
+2.  Create a [TDataSource] component on a form (`dsLayouts` in the example). 
+    Assign the `TDataSource.DataSet` value to the previously created dataset component:
+
+    > <img src="./images/create-bind-data-source.png" style="width: 50%" alt=""/>
+
+3.  Open the context menu of the dataset component and select **Field Editor…**:
+    
+    > <img src="./images/open-context-menu.png" style="width: 50%" alt=""/>
+
+4.  Click **Add…** to create a BLOB field for layout data:
+
+    > <img src="./images/create-layout-field.png" style="width: 50%" alt=""/>
+
+5.  Click **Add…** to create a string field for layout name:
+
+    > <img src="./images/create-name-field.png" style="width: 50%" alt=""/>
+
+6.  (*Optional*) Preload persistent data to the dataset make layouts available in the application upon first launch.
+    Open the context menu of the dataset component, select **Persistent Editor…**, click **Load…** and select a DAT file.
+    
+    This example has an example report layout designed to use data from the Northwind sample database.
+    You can preload it from [example.dat](./Delphi/example.dat).
+
+    Alternatively, you can use the Report Designer in further steps to import report data from files or raw string data.
+
+    > <img src="./images/create-persistent-data.png" style="width: 50%" alt=""/>
+
+
+### Step 2: Supply Layout Data to TdxReport
+
+[TdxReport] requires a [Layout][TdxReport.Layout] and [ReportName][TdxReport.ReportName].
+Assign both properties by reading them from the dataset:
+
+
+### Step 3: Display Report Designer and Viewer
+
+### Step 4: Handle Layout Changes
+
+When a user edits and saves a report in the Report Designer,
+the value of [TdxReport.Layout] changes and a `LayoutChanged` event is called.
+Handle this event to save the updated layout to the active dataset record.
+
+
+```pas
+procedure TMainForm.dxReport1LayoutChanged(ASender: TdxReport);
+begin
+  // Start editing the active dataset record
+  DataModule1.mdLayouts.Edit;
+  // Save the report layout to the database
+  DataModule1.mdLayoutsLayout.Assign(dxReport1.Layout);
+  // Save the report name which is not included in the layout
+  DataModule1.mdLayoutsName.AsString := dxReport1.ReportName;
+  // Finish editing and write a modified record
+  DataModule1.mdLayouts.Post;
+end;
+```
+
+### Step 5: Save the Database State when Application Exists
+
+
+
+## Files to Review
+
+-   [uData.pas] (Delphi) and [uData.cpp] (C++Builder) read and store layout data in a database represented by an in-memory storage component.
+-   [data.dat] stores layout data between application sessions.
+-   [uMainForm.pas] (Delphi) and [uMainForm.cpp] (C++Builder) supply layout data from the data module to [TdxReport.Layout] and display Report Designer and Viewer.
+-   [nwind.db] contains the Northwind sample database used as a data source for report content.
+
+[uData.pas]: ./Delphi/uData.pas
+[uData.cpp]: ./CPB/uData.cpp
+[data.dat]: ./Delphi/data.dat
+[uMainForm.pas]: ./Delphi/uMainForm.pas
+[uMainForm.cpp]: ./CPB/uMainForm.cpp
+[nwind.db]: ./Delphi/nwind.db
 
-* Run the sample app and click **New Report** to create an empty database record.
-* Click **Show Designer** to display the [Report Designer](https://docs.devexpress.com/XtraReports/119176/web-reporting/web-end-user-report-designer) dialog.
-* Create a report layout using tools available within the UI.
-* Click the hamburger button, select the **Save** option, and close the dialog.
-* Close the app. The [TdxMemData](https://docs.devexpress.com/VCL/dxmdaset.TdxMemData) component will store layout data between sessions.
-* 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.
 
 ## Documentation
 
-* [TdxReport.Layout Property](https://docs.devexpress.com/VCL/dxReport.TdxReport.Layout)
-* [TdxBackendDataSetJSONConnection Component](https://docs.devexpress.com/VCL/dxBackend.ConnectionString.JSON.DataSet.TdxBackendDataSetJSONConnection)
+-   [Introduction to VCL Reports][reports-intro]
+-   [Tutorial: Create a table report using the Report Wizard][report-wizard]
+-   [Use SQLite as a data source for reports (as demonstrated in the current example)][sqlite-data-source]
+-   [Store report layouts in REPX files at design-time][reports-design-time-store]
+-   API reference:
+    -   [TdxReport.ReportName]
+    -   [TdxReport.Layout] (an XML-based layout template that can be stored in the BLOB field of a database)
+    -   [TdxReport.ReportName]
+    -   [TdxMemData] (used to store report layout data in application runtime and between sessions)
+    -   [TDataSet] (ancestor of the `TdxMemData`, contains generic database connection methods)
+    -   [TdxBackendDatabaseSQLConnection] (used to supply data to reports)
+
+<!-- documentation links -->
+[reports-intro]: https://docs.devexpress.com/VCL/405469/ExpressReports/vcl-reports
+[report-wizard]: https://docs.devexpress.com/VCL/405760/ExpressReports/getting-started/create-table-report-using-report-wizard
+[sqlite-data-source]: https://docs.devexpress.com/VCL/405750/ExpressCrossPlatformLibrary/vcl-backend/database-engines/vcl-backend-sqlite-support
+[reports-design-time-store]: https://docs.devexpress.com/VCL/dxReport.TdxReport.Layout#string-list-editor
+[dx-report-viewer]: https://docs.devexpress.com/XtraReports/401850/web-reporting/web-document-viewer
+[dx-report-designer]: https://docs.devexpress.com/XtraReports/119176/web-reporting/web-end-user-report-designer
+
+
+<!-- reference links -->
+[TdxReport]: https://docs.devexpress.com/VCL/dxReport.TdxReport
+[TdxReport.Layout]: https://docs.devexpress.com/VCL/dxReport.TdxReport.Layout
+[TdxReport.ReportName]: https://docs.devexpress.com/VCL/dxReport.TdxReport.ReportName
+[TdxBackendDatabaseSQLConnection]: https://docs.devexpress.com/VCL/dxBackend.ConnectionString.SQL.TdxBackendDatabaseSQLConnection
+[TdxMemData]: https://docs.devexpress.com/VCL/dxmdaset.TdxMemData
+
+<!-- external documentation links -->
+[TDataSet]: https://docwiki.embarcadero.com/Libraries/Athens/en/Data.DB.TDataSet
+[TDataSource]: https://docwiki.embarcadero.com/Libraries/Athens/en/Data.DB.TDataSource
+<!-- in-repository links -->
+
+
+## More Examples
+
+-   [Store report layouts in REPX files][file-example]
+
+[file-example]: https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-file
+
+
 <!-- feedback -->
 ## Does This Example Address Your Development Requirements/Objectives?
 
 [<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)
 
 (you will be redirected to DevExpress.com to submit your response)
 <!-- feedback end -->
-
-
-