TdxCustomDashboardControl Class

The base class for the VCL Dashboard control.

Declaration

TdxCustomDashboardControl = class(
    TdxWebBrowser
)

Remarks

TdxDashboardControl is a visual component designed to display multiple interconnected data analysis UI elements within an automatically arranged layout. Interactive data analysis elements (dashboard visualization items) include grids, charts, maps, gauges, etc.

The VCL Dashboard implementation is based on the DevExpress JavaScript Dashboard Designer and Viewer for native VCL apps (using modern WebView and ASP.NET Core/JavaScript wrappers). All required .NET and JavaScript dependencies are transparently embedded into one self-contained EXE file.

VCL Dashboards: A Dashboard Content Example

In this topic…

Prerequisites & Deployment
Getting Started
Bind to Data
- Data Connection Components
Main API Members
Code Examples
- Export Dashboard Content to PDF File
- Related GitHub-Hosted Sample Projects
Related Compiled Demo

Prerequisites & Deployment

Note

ExpressReports will require the purchase of our VCL Subscription + OR an active VCL Subscription (regular) with any active .NET subscription that includes DevExpress Reports for ASP.NET/JavaScript (these subscriptions include: Reporting, ASP.NET & Blazor (includes DevExtreme), DXperience, or Universal).
ExpressDashboards will also require the purchase of our VCL Subscription + OR an active VCL Subscription (regular) with an active Universal Subscription that includes DevExpress Business Intelligence (BI) Dashboard.

Ensure that your development environment meets ExpressDashboards and ExpressReports prerequisites:

Microsoft Windows 10 or newer.
Embarcadero RAD Studio IDE 12.3 or newer (Community Edition IDEs are not supported).
DevExpress VCL v26.1.x.
The EdgeView2 SDK package installed from the GetIt package manager.

Tip

Refer to the following topic for detailed information: VCL Reports/Dashboards App Deployment.

Getting Started

Read Tutorial: Create a Dashboard

Basic Tutorial. Follow this tutorial to create a simple dashboard application: set up a memory-based data source, load JSON data, create Bubble Map and Chart dashboard items, and bind them to data.

Featured Components: TdxDashboardControl | TdxBackendDataConnectionManager | TdxBackendInMemoryJSONConnection

Read Tutorial: Bind a Dashboard to FireDAC Data

Follow this tutorial to create a dashboard and bind it to data using standard FireDAC components (TFDQuery and TFDConnection) shipped with the RAD Studio IDE.

Featured Components: TdxDashboardControl | TdxBackendDataConnectionManager | TdxBackendDataSetJSONConnection

Read Tutorial: Bind a Dashboard to a Stored Procedure

Follow this tutorial to create a dashboard, bind it to a parametrized stored procedure, and pass dashboard parameters to that procedure using the Dashboard Designer dialog at design time.

Featured Components: TdxDashboardControl | TdxBackendDataConnectionManager | TdxBackendDatabaseSQLConnection

Bind to Data

Dashboard visualization items created using the TdxDashboardControl component can display 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 data connection class descriptions for detailed information and code examples.

Data Connection Components

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:

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

Main API Members

The list below outlines key members of the TdxCustomDashboardControl class. These members allow you to configure and manage templates as well as export dashboard content to different target formats.

Dashboard Content & Layout

Clear: Clears the dashboard control (name, layout definition, state, and parameters).
DashboardName: Specifies the dashboard name (for template/layout management and content export).
EnableCustomSql: Specifies if custom SQL queries are enabled at the TdxDashboardControl component 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.
Language: Allows you to switch between available UI and content localizations.
Layout: Provides access to the dashboard template (as individual XML strings).
OnLayoutChanged: Allows you to respond to any dashboard layout changes.
OnResolveConnection: Allows you to map different data connection components to the same data source name referenced within the current dashboard layout definition.
Parameters: Provides access to the read-only collection of dashboard parameters.

Note
The Parameters collection is automatically populated and updated from the current dashboard layout definition.
ReloadData: Reloads data from all underlying data sources on demand and updates dashboard content.

End-User Interaction

ExportFormats: Specifies export formats available to users.
OnExport: Allows you to execute code in response to dashboard content export operations or to prevent users from exporting dashboard content as a file (in any supported format).
OnDesignerFormShow | OnViewerFormShow: Allow you to customize Dashboard Designer and Dashboard Viewer dialog form settings (position, dimensions, caption, etc.).
OnStateChanged: Allows you to respond to any user interaction state changes.
ShowDesigner | ShowViewer: Display Dashboard Designer and Dashboard Viewer dialogs. Global skin and palette settings (defined using the Project Settings dialog or a TdxSkinController component) affect these dialogs.
State: 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.

Data Export

ExportTo: Exports the current dashboard to a file or stream in any supported format.
ExportToCSV | ExportToPDF | ExportToXLS | ExportToXLSX: Export the current dashboard to a file or stream in corresponding document formats.
ExportToGIF | ExportToJPG | ExportToPNG | ExportToSVG: Export the current dashboard to a file or stream in corresponding image formats.

Terminal TdxCustomDashboardControl Class Descendant

Do not use the TdxCustomDashboardControl class directly. Use the TdxDashboardControl component instead.

Code Examples

Export Dashboard Content to PDF File

The following code example exports content of a configured TdxDashboardControl component to a file in the Portable Document (PDF) format using an intermediary TMemoryStream object:

Delphi
C++

uses
  dxDashboard.Control,  // Declares the TdxDashboardControl component
  dxSplashForms,     // Declares the TdxSplashFormManager class and related types
  dxShellDialogs;    // Declares the TdxSaveFileDialog component
// ...

procedure TMyForm.cxButtonExportToPDFClick(Sender: TObject);
var
  AStream: TMemoryStream;
begin
  if not dxSaveFileDialog1.Execute(Handle) then Exit;  // Displays the "Save File" dialog
  AStream := TMemoryStream.Create;       // Creates a stream as an intermediary container
  // Displays a Wait Form before the export operation
  TdxSplashFormManager.WaitForm.Show(dxDashboardControl1.Parent);
  try
    dxDashboardControl1.ExportToPDF(AStream);   // Exports content to a stream in the PDF format
    AStream.SaveToFile(dxSaveFileDialog1.FileName);    // Saves PDF stream content to a file
  finally
    AStream.Free;                        // Releases the intermediary memory stream
    TdxSplashFormManager.WaitForm.Hide;  // Hides the Wait Form once the operation is complete
  end;
end;

#include "dxDashboard.Control.hpp"  // Declares the TdxDashboardControl component
#include "dxSplashForms.hpp"     // Declares the TdxSplashFormManager class and related types
#include "dxShellDialogs.hpp"    // Declares the TdxSaveFileDialog component

// Add the following linker directives to the corresponding CPP source file:
#pragma link "dxDashboard.Control"  // Required to use dxDashboard.Control.hpp declarations
#pragma link "dxSplashForms"     // Required to use dxSplashForms.hpp declarations
#pragma link "dxShellDialogs"    // Required to use dxShellDialogs.hpp declarations
// ...

void __fastcall TMyForm::cxButtonExportToPDFClick(TObject *Sender)
{
  if(!dxSaveFileDialog1->Execute(Handle)) { return; }  // Displays the "Save File" dialog
  TMemoryStream *AStream = new TMemoryStream();  // Creates a stream as an intermediary container
  // Displays a Wait Form before the export operation
  TdxSplashFormManager::WaitForm()->Show(dxDashboardControl1->Parent);
  try
  {
    dxDashboardControl1->ExportToPDF(AStream);  // Exports content to a stream in the PDF format
    AStream->SaveToFile(dxSaveFileDialog1->FileName);  // Saves PDF stream content to a file
  }
  __finally
  {
    delete AStream;                              // Releases the intermediary memory stream
    TdxSplashFormManager::WaitForm()->Hide();    // Hides the Wait Form once the operation is complete
  }
}

View Example: Store Dashboard Layouts in a Database View Example: Pass a Hidden Dashboard Parameter to a SQL Query

To see the TdxDashboardControl component in action, run the BI Dashboards Designer/Viewer demo in the VCL Demo Center installed with compiled DevExpress VCL demos. Click different items in the sidebar on the left to switch between demo features.

Download: Compiled VCL Demos

Tip

You can find full source code for the installed compiled Report demo in the following folder:

%PUBLIC%\Documents\DevExpress VCL Demos\MegaDemos\Product Demos\ExpressDashboards\