readme: Add implementation details and reference

- Add a step-by-step instruction with screenshots
- Add more reference links to DevExpress and standard VCL library
- Update repository description
- Add layout.dat and revenue.dat files that store memory-based datasets
  that can be used to reproduce the example

Author: NickVolynkin

.github/meta.yml

@@ -3,4 +3,4 @@ url: vcl-dashboards-store-layout-template-database
 website: https://docs.devexpress.com/VCL/405642/ExpressDashboards/vcl-dashboards
 tags: [vcl, dashboards, layout, database]
 description: |
-  DevExpress VCL Dashboards - Store Dashboard Layouts in a Database 
+  DevExpress Dashboards for Delphi/C++Builder - Store Dashboard Layouts in a Database 

Delphi/layout.dat

@@ -5,17 +5,22 @@
 [![](https://img.shields.io/badge/💬_Leave_Feedback-feecdd?style=flat-square)](#does-this-example-address-your-development-requirementsobjectives)
 <!-- default badges end -->
 
-# DevExpress VCL Dashboards — Store Dashboard Layouts in a Database
+# DevExpress Dashboards for Delphi/C++Builder — Store Dashboard Layouts and State in a Database
 
-This sample app stores a [dashboard layout](https://docs.devexpress.com/VCL/dxDashboard.Control.TdxCustomDashboardControl.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).
+This example application stores [DevExpress dashboard layouts][TdxCustomDashboardControl.Layout]
+in a database.
+The sample allows users to create new layouts, modify existing layouts using the built-in
+Dashboard Designer, interact with dashboards, and save state or layout changes to the data source.
+
+> ![DevExpress VCL Dashboards - Database Layout Storage Example](./images/vcl-dashboard-layout-database-sample-app.png)
 
-![DevExpress VCL Dashboards - Database Layout Storage Example](/Images/vcl-dashboard-layout-database-sample-app.png)
 
 ## Prerequisites
 
-* Microsoft Windows 10 or newer
-* Embarcadero RAD Studio IDE 12.3 (Athens) or newer (Community Edition is not supported)
-* DevExpress VCL Components v25.2.3 or newer
+[DevExpress Dashboards Prerequisites][req]
+
+[req]: https://docs.devexpress.com/VCL/405773/ExpressCrossPlatformLibrary/vcl-backend/reports-dashboards-app-deployment#vcl-reportsdashboards-prerequisites
+
 
 ## Test the Example
 
@@ -26,12 +31,229 @@ This sample app stores a [dashboard layout](https://docs.devexpress.com/VCL/dxDa
 5. Close the app. The [TdxMemData](https://docs.devexpress.com/VCL/dxmdaset.TdxMemData) component will store layout data between sessions.
 6. Run the sample again. Click on grid records to switch between loaded dashboards.
 
-![DevExpress VCL Dashboards - Store Dashboard Layout Definitions in a Database](/Images/vcl-dashboards-store-layout-template-database.gif)
+> ![DevExpress VCL Dashboards — Store Dashboard Layout Definitions in a Database](./images/vcl-dashboards-store-layout-template-database.gif)
+
+
+## Implementation Details
+
+The example uses a DevExpress memory-based dataset for dashboard layout storage: [TdxMemData].
+You can modify the application to use any other [TDataSet] descendant instead.
+To review our data module implementation, see the following file: [uData.pas]/[uData.cpp].
+
+The instructions assume that you start with a Delphi or C++Builder project that already includes
+a configured data source for DevExpress Dashboards.
+The example uses a memory-based dataset as the dashboard's data source
+(see `mdRevenueByIndustry` in the data module).
+To configure a dashboard data source in your project, refer to the following tutorial:
+[Create a dashboard using the Designer Dialog][designer].
+
+### Step 1: Create a Dataset to Store Dashboard Layout and State Data
+
+1.  Add a [TdxMemData] component to the data module (`mdLayouts` in the example).
+1.  Add a [TDataSource] component to the data module (`dsLayouts` in the example). 
+    Assign the previously created dataset component to `TDataSource.DataSet`:
+
+    > <img src="./images/create-bind-data-source.png" style="width: 50%"
+      alt="Object Inspector panel displaying TDataSource properties."/>
+
+1.  Open the context menu for the dataset component and select **Field Editor…**:
+    
+    > <img src="./images/open-context-menu.png" style="width: 50%"
+      alt="Context menu for the TdxMemData component displaying a 'Field Editor' option."/>
+
+1.  Click **Add…** to create a BLOB field for layout data ([]):
+
+    > <img src="./images/create-layout-field.png" style="width: 50%"
+      alt="New Field dialog adding a 'Layout' field of type ftBlob"/>
+
+1.  Click **Add…** to create a string field for layout names:
+
+    > <img src="./images/create-name-field.png" style="width: 50%"
+      alt="New Field dialog adding a 'Name' field of type ftWideString"/>
+
+1.  Click **Add…** to create another BLOB field for dashboard stats:
+
+    > <img src="./images/create-state-field.png" style="width: 50%"
+      alt="New Field dialog adding a 'State' field of type ftBlob"/>
+
+1.  (*Optional*) Preload persistent data to the dataset to make layouts available in the application upon first launch.
+
+    This example includes a sample dashboard layout that displays revenue data from an included dataset.
+    You can preload the layout and revenue from [layout.dat] and [revenue.dat] respectively.
+    Open the context menu for the dataset component, select **Persistent Editor…**, click **Load…**, and select the file.
+    
+    > <img src="./images/create-persistent-data.png" style="width: 50%"
+      alt="Context menu for the TdxMemData component displaying a 'Persistent Editor' option."/>
+
+    Alternatively, you can use the Dashboard Designer later to import dashboard data from an XML file.
+
+
+## Step 2: Load a Dashboard Layout Definition
+
+To load a layout definition to the Dashboard Control ([TdxCustomDashboardControl]), you must specify
+dashboard name ([TdxCustomDashboardControl.DashboardName]), layout ([TdxCustomDashboardControl.Layout]),
+and, optionally, dashboard user interaction state ([TdxCustomDashboardControl.State]):
+
+```pas
+procedure TMainForm.LoadLayoutDefinition;
+begin
+  // Ensure that the dataset has at least one record or a new record is being created:
+  if (DataModule1.mdLayouts.RecordCount = 0) and (DataModule1.mdLayouts.State <> dsInsert) then
+  begin
+    dxDashboardControl1.Clear;
+    Exit;
+  end;
+  // Load dashboard name and layout from the database:
+  dxDashboardControl1.DashboardName := DataModule1.mdLayoutsName.AsString;
+  dxDashboardControl1.Layout.Assign(DataModule1.mdLayoutsLayout);
+  // Load dashboard state if it is stored in the database:
+  if not DataModule1.mdLayoutsState.IsNull then
+    dxDashboardControl1.State.Assign(DataModule1.mdLayoutsState);
+end;
+```
+
+To load a different dashboard in the Dashboard Control, assign a new dashboard name and layout.
+The assigned dashboard replaces the current layout definition and resets the dashboard state.
+
+You can also clear the Dashboard Control using [TdxCustomDashboardControl.Clear].
+
+
+### Step 3: Display the Dashboard Designer
+
+Once you assigned a dashboard layout definition to the Dashboard Control,
+you can display the [Dashboard Designer][designer] dialog:
+
+```pas
+procedure TMainForm.btnDesignClick(Sender: TObject);
+begin
+  dxDashboardControl1.ShowDesigner; // Displays the Dashboard Designer
+end;
+```
+
+### Step 4: Store Dashboard State in a Dataset
+
+When a user interacts with the dashboard in the Dashboard Control or Designer,
+the value of [TdxCustomDashboardControl.State] changes and an
+[OnStateChanged][TdxCustomDashboardControl.OnStateChanged] event is called.
+Handle this event to save dashboard state changes to the database.
+
+```pas
+procedure TMainForm.dxDashboardControl1StateChanged(
+  ASender: TdxCustomDashboardControl);
+begin
+  // Start editing the active dataset record:
+  DataModule1.mdLayouts.Edit;
+
+  // Save the current dashboard state to the active record:
+  DataModule1.mdLayoutsState.Assign(dxDashboardControl1.State);
+
+  // Finish editing and post the modified record to the database:
+  DataModule1.mdLayouts.Post;
+end;
+```
+
+### Step 5: Store Dashboard Layouts in a Dataset
+
+When a user edits and saves a dashboard in the Dashboard Designer,
+the value of [TdxCustomDashboardControl.Layout] changes and an
+[OnLayoutChanged][TdxCustomDashboardControl.OnLayoutChanged] event is called.
+Handle this event to save layout changes to the database.
+
+```pas
+procedure TMainForm.dxDashboardControl1LayoutChanged(
+  ASender: TdxCustomDashboardControl);
+begin
+  if DataModule1.mdLayoutsName.AsString <> dxDashboardControl1.DashboardName then
+  begin
+    // Create and start editing a new dataset record
+    DataModule1.mdLayouts.Append;
+    DataModule1.mdLayoutsName.AsString := dxDashboardControl1.DashboardName;
+  end
+  else
+    // Start editing the active dataset record
+    DataModule1.mdLayouts.Edit;
+
+  // Save dashboard layout to the database:
+  DataModule1.mdLayoutsLayout.Assign(dxDashboardControl1.Layout);
+  // Finish editing and post the modified record to the database:
+  DataModule1.mdLayouts.Post;
+end;
+```
+
+## Files to Review
+
+- [uData.pas]/[uData.cpp] stores dashboard layouts and supplies data to the dashboard.
+- [uMainForm.pas]/[uMainForm.cpp] loads dashboard layouts from the data module,
+  and displays Dashboard Control and Dashboard Designer.
+- [layout.dat] and [revenue.dat] store memory-based dataset states that you can load to reproduce this example.
+- [data.dat] stores the memory-based dataset state between application sessions.
+
 
 ## Documentation
 
-* [TdxCustomDashboardControl.Layout](https://docs.devexpress.com/VCL/dxDashboard.Control.TdxCustomDashboardControl.Layout)
-* [TdxBackendDataSetJSONConnection](https://docs.devexpress.com/VCL/dxBackend.ConnectionString.JSON.DataSet.TdxBackendDataSetJSONConnection)
+-   [Introduction to VCL Dashboards][dashboards-intro]
+-   [Tutorial: Create a dashboard using the Designer Dialog][designer]
+-   [Use JSON as a data source for dashboards (as demonstrated in the current example)][json-data-source]
+-   [Save dashboard layout to file on every change (code example)][save-to-file]
+-   API reference:
+    -   [TdxCustomDashboardControl] (used to display a dashboard in an application form)
+    -   [TdxCustomDashboardControl.State] (a JSON-based representation of dashboard state that can be stored in a BLOB data field)
+    -   [TdxCustomDashboardControl.Layout] (an XML-based layout template that can be stored in a BLOB data field)
+    -   [TdxCustomDashboardControl.DashboardName] (internal dashboard name that is not included in the layout or state)
+    -   [TdxCustomDashboardControl.OnStateChanged] (event called when user interacts with a dashboard and changes its state)
+    -   [TdxCustomDashboardControl.OnLayoutChanged] (event called when user edits and saves a dashboard in the Dashboard Designer)
+    -   [TdxMemData] (DevExpress in-memory dataset implementation)
+    -   [TDataSet] (contains generic database connection methods)
+    -   [TdxBackendDataSetJSONConnection] (supplies data to dashboards)
+
+
+<!-- documentation links -->
+
+[dashboards-intro]: https://docs.devexpress.com/VCL/405642/ExpressDashboards/vcl-dashboards
+[designer]: https://docs.devexpress.com/VCL/405774/ExpressDashboards/getting-started/create-dashboard-using-designer-dialog
+[json-data-source]: https://docs.devexpress.com/VCL/405747/ExpressCrossPlatformLibrary/vcl-backend/database-engines/vcl-backend-memory-based-data-storage
+[save-to-file]: https://docs.devexpress.com/VCL/dxDashboard.Control.TdxCustomDashboardControl.Layout#save-dashboard-layout-to-file-on-every-change
+[supported-dbms]: https://docs.devexpress.com/VCL/405703/ExpressCrossPlatformLibrary/vcl-backend/vcl-backend-supported-database-systems
+
+<!-- reference links -->
+[TdxCustomDashboardControl]: https://docs.devexpress.com/VCL/dxDashboard.Control.TdxCustomDashboardControl
+[TdxCustomDashboardControl.Clear]: https://docs.devexpress.com/VCL/dxDashboard.Control.TdxCustomDashboardControl.Clear
+[TdxCustomDashboardControl.DashboardName]: https://docs.devexpress.com/VCL/dxDashboard.Control.TdxCustomDashboardControl.Layout
+[TdxCustomDashboardControl.Layout]: https://docs.devexpress.com/VCL/dxDashboard.Control.TdxCustomDashboardControl.Layout
+[TdxCustomDashboardControl.State]: https://docs.devexpress.com/VCL/dxDashboard.Control.TdxCustomDashboardControl.State
+[TdxCustomDashboardControl.OnLayoutChanged]: https://docs.devexpress.com/VCL/dxDashboard.Control.TdxCustomDashboardControl.OnLayoutChanged
+[TdxCustomDashboardControl.OnStateChanged]: https://docs.devexpress.com/VCL/dxDashboard.Control.TdxCustomDashboardControl.OnStateChanged
+[TdxBackendDataSetJSONConnection]: https://docs.devexpress.com/VCL/dxBackend.ConnectionString.JSON.DataSet.TdxBackendDataSetJSONConnection
+[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
+[ftString]: https://docwiki.embarcadero.com/Libraries/Athens/en/Data.DB.TFieldType
+[ftWideString]: https://docwiki.embarcadero.com/Libraries/Athens/en/Data.DB.TFieldType
+[ftBlob]: https://docwiki.embarcadero.com/Libraries/Athens/en/Data.DB.TFieldType
+
+
+<!-- in-repository links -->
+[uData.pas]: ./Delphi/uData.pas
+[uData.cpp]: ./CPB/uData.cpp
+[data.dat]: ./Delphi/data.dat
+[layout.dat]: ./Delphi/layout.dat
+[revenue.dat]: ./Delphi/revenue.dat
+[uMainForm.pas]: ./Delphi/uMainForm.pas
+[uMainForm.cpp]: ./CPB/uMainForm.cpp
+
+
+## More Examples
+
+-   [Pass Hidden Parameters to a SQL Query][hidden-parameter-example]
+-   [Generate Dashboards in a Backend / Service Application][non-interactive-example]
+-   [Store Layouts in XML Files (DevExpress Reports for Delphi/C++Builder)][file-example]
+
+[hidden-parameter-example]: https://github.com/DevExpress-Examples/vcl-dashboards-pass-hidden-parameters-to-custom-sql-query
+[file-example]: https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-file
+[non-interactive-example]: https://github.com/DevExpress-Examples/vcl-reports-store-layout-template-database
 
 <!-- feedback -->
 ## Does This Example Address Your Development Requirements/Objectives?