vcl-dxdashboard.md
A non-visual VCL Dashboard container designed to generate and export dashboard content.
TdxDashboard = class(
TPersistent
)
The TdxDashboard class implements a dashboard model container with dedicated APIs for template (layout) management, content export operations, etc.
You can create a TdxDashboard class instance to generate and export dashboard content without direct user interaction[1]. This scenario can be useful for console applications, REST/Web API backends, Windows Services, workflow/scheduler jobs, etc.
Note
The ExpressDashboards Suite is available as a Community Technology Preview (CTP). Please review our pre-release software notes if you plan on using ExpressDashboards.
The TdxDashboard class uses the same data connection components and data binding techniques as the visual TdxDashboardControl component.
Dashboard visualization items within a dashboard layout are populated with data from different sources stored in memory or a database. The TdxBackendDataConnectionManager component allows you to manage data connection components designed to work with different data sources.
Tip
You can create data connection components directly in code, without TdxBackendDataConnectionManager.
Refer to the data connection class descriptions for detailed information and code examples.
TdxBackendDataSetJSONConnection
A component designed to work with data in one or multiple VCL-compatible datasets (TDataSet descendants).
Use the TdxBackendDataSetJSONConnection component if you need to use TdxDashboardControl/TdxDashboard and TdxReport components together with VCL-compatible data sources.
Refer to the following help topic for step-by-step instructions on using the TdxBackendDataSetJSONConnection component in your project:
VCL Reports/Dashboards: How to Use Data Source and Data Set Components
TdxBackendInMemoryJSONConnection
A component designed for interaction with local (in-memory) or remote JSON data accessible through a Web API service endpoint.
Refer to the following help topic for step-by-step instructions on using the TdxBackendInMemoryJSONConnection component as a data source for TdxDashboard/TdxDashboardControl and TdxReport:
VCL Reports/Dashboards: How to Use Memory-Based or Remote API Data Sources
TdxBackendDatabaseSQLConnection
A DevExpress XPO-based component designed to fetch data from the following relational databases:
SQLite | Microsoft SQL Server/Azure SQL | PostgreSQL | Oracle Database | MySQL | Firebird
Tip
This component is based on the DevExpress XPO ORM engine (powered by ADO.NET).
TdxBackendDatabaseSQLConnection has built-in support for Microsoft SQL/Azure SQL and SQLite engines (you can use them without additional dependencies and extra configuration).
Refer to the following topic for a complete list of supported database engines and corresponding connection string examples:
VCL Reports/Dashboards: Supported Database Engines
The list below outlines key members of the TdxDashboard class. These members allow you to configure/manage templates and export dashboard content to different target formats.
Specifies if custom SQL queries are enabled at the TdxDashboard container instance level.
Important
Enable custom SQL queries only if you ensure that you follow best practices and implement user read/write privileges at the database level using the tools available for your relational database management system.
LanguageAllows you to switch between available UI and content localizations.LayoutProvides access to the dashboard template (as individual strings in the XML format).NameSpecifies the dashboard name (for template/layout management and content export).Parameters
Provides access to the read-only collection of dashboard parameters.
Note
The Parameters collection is populated and updated automatically from the current dashboard layout definition.
Provides access to the dashboard state (as individual strings in the JSON format).
Allows you to load and apply previously saved dashboard user interaction states.
ExportToExports the current dashboard to a file or stream in any supported format.
View Example: Generate Dashboards in a Backend/Service Application
The following code example configures a memory-based data source (TdxBackendInMemoryJSONConnection), loads an XML dashboard layout, and exports dashboard content to a PDF file without user interaction:
uses
dxBackend.ConnectionString.JSON, // Declares the TdxBackendInMemoryJSONConnection component
dxDashboard; // Declares the TdxDashboard class
// ...
procedure TMyForm.cxExportButtonClick(Sender: TObject);
var
ADashboard: TdxDashboard;
AJSONDataConnection: TdxBackendInMemoryJSONConnection;
AMemoryStream: TMemoryStream;
AFileName, AJSONData: string;
begin
// Define a table that consists of three columns ("id", "Region", and "Sales") and five data rows:
AJSONData :=
'[{"id": 1, "Region": "Asia", "Sales": 4.7685},' + // Row #1
'{"id": 2, "Region": "Australia", "Sales": 1.9576},' + // Row #2
'{"id": 3, "Region": "Europe", "Sales": 3.3579},' + // Row #3
'{"id": 4, "Region": "North America", "Sales": 3.7477},' + // Row #4
'{"id": 5, "Region": "South America", "Sales": 1.8237}]'; // Row #5
AJSONDataConnection := TdxBackendInMemoryJSONConnection.Create(Self); // Creates a data connection
try
AJSONDataConnection.Name := 'JSONData'; // Assigns a name to the created data connection
AJSONDataConnection.SetJSONValue(AJSONData); // Assigns the defined JSON data string
ADashboard := TdxDashboard.Create(Self); // Creates a TdxDashboard container
try
ADashboard.Layout.LoadFromFile('MyDashboardLayout.xml'); // Loads an XML dashboard layout
ADashboard.Name := 'MyDashboard'; // Defines a dashboard name
AMemoryStream := TMemoryStream.Create; // Creates a memory stream
try
// Export dashboard content to the created memory stream in the PDF format
ADashboard.ExportTo(TdxDashboardExportFormat.PDF, AMemoryStream, AFileName);
AMemoryStream.SaveToFile(AFileName); // Saves the resulting PDF file
finally
AMemoryStream.Free; // Releases the memory stream
end;
finally
ADashboard.Free; // Releases the TdxDashboard container
end;
finally
AJSONDataConnection.Free; // Releases the data connection
end;
end;
#include "dxBackend.ConnectionString.JSON.hpp" // Declares the TdxBackendInMemoryJSONConnection component
#include "dxDashboard.hpp" // Declares the TdxDashboard class
// Add the following linker directives to the corresponding CPP source file:
#pragma link "dxDashboard" // Required to use dxDashboard.hpp declarations
#if defined(_WIN64) // Required to use dxBackend.ConnectionString.JSON.hpp declarations
#pragma link "dxBackend.ConnectionString.JSON.o"
#else
#pragma link "dxBackend.ConnectionString.JSON.obj"
#endif
// ...
void __fastcall TMyForm::cxExportButtonClick(TObject *Sender)
{
TdxDashboard *ADashboard;
TdxBackendInMemoryJSONConnection *AJSONDataConnection;
TMemoryStream *AMemoryStream;
UnicodeString AFileName;
// Define a table that consists of three columns ("id", "Region", and "Sales") and five data rows:
UnicodeString AJSONData =
"[{\"id\": 1, \"Region\": \"Asia\", \"Sales\": 1.9576}," // Row #1
"{\"id\": 2, \"Region\": \"Australia\", \"Sales\": 1.9576}," // Row #2
"{\"id\": 3, \"Region\": \"Europe\", \"Sales\": 3.3579}," // Row #3
"{\"id\": 4, \"Region\": \"North America\", \"Sales\": 3.7477}," // Row #4
"{\"id\": 5, \"Region\": \"South America\", \"Sales\": 1.8237}]" // Row #5
AJSONDataConnection = new TdxBackendInMemoryJSONConnection(this); // Creates a data connection
try
{
AJSONDataConnection->Name = "JSONData"; // Assigns a name to the created data connection
AJSONDataConnection->SetJSONValue(AJSONData); // Assigns the defined JSON data string
ADashboard = new TdxDashboard(this); // Creates a TdxDashboard container
try
{
ADashboard->Layout->LoadFromFile("MyDashboardLayout.xml"); // Loads an XML dashboard layout
ADashboard->Name = "MyDashboard"; // Defines a dashboard name
AMemoryStream = new TMemoryStream(); // Creates a memory stream
try
{
// Export dashboard content to the created memory stream in the PDF format
ADashboard->ExportTo(TdxDashboardExportFormat::PDF, AMemoryStream, AFileName);
AMemoryStream->SaveToFile(AFileName); // Saves the resulting PDF file
}
__finally
{
delete AMemoryStream; // Releases the memory stream
}
}
__finally
{
delete ADashboard; // Releases the TdxDashboard container
}
}
__finally
{
delete AJSONDataConnection; // Releases the data connection
}
}
TObject TPersistent TdxDashboard
Footnotes
See Also