TdxDashboard Class

A non-visual VCL Dashboard container designed to generate and export dashboard content.

Declaration

TdxDashboard = class(
    TPersistent
)

Remarks

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. In addition, the TdxDashboard class declares ShowDesigner and ShowViewer procedures and corresponding API members, similar to those available for the TdxReport component.

In this topic…

Prerequisites & Deployment
Bind to Data
- Data Connection Components
Main API Members
Code Examples

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.

Bind to Data

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.

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 TdxDashboard class. These members allow you to configure/manage templates and export dashboard content to different target formats.

Dashboard Content & Layout

Clear: Clears the dashboard container (name, layout definition, state, and parameters).
EnableCustomSql: 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.
Language: Allows you to switch between available UI and content localizations.
Layout: Provides access to the dashboard template (as individual strings in the XML format).
Name: Specifies the dashboard name (for template/layout management and content export).
OnLayoutChanged: Allows you to respond to layout definition changes made using the Dashboard Designer dialog.
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 populated and updated automatically from the current dashboard layout definition.

End-User Interaction

ExportFormats: Specifies export format groups available to users in Dashboard Designer and Dashboard Viewer dialogs.
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.

Code Examples

Export Dashboard Content to PDF Without User Interaction

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:

Delphi
C++

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
  }
}

Save Dashboard Layout to File on Every Change

The following code example saves the current Dashboard layout to a file in the XML format every time a user saves pending changes in the Dashboard Designer dialog:

Delphi
C++

uses
  dxDashboard;  // Declares the TdxDashboard class
// ...

procedure TMyForm.dxDashboard1LayoutChanged(ASender: TdxDashboard);
begin
  ASender.Layout.SaveToFile(ASender.Name + '.xml');
end;

#include "dxDashboard.hpp"  // Declares the TdxDashboard class

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

void __fastcall TMyForm::dxDashboard1LayoutChanged(TdxDashboard *ASender)
{
  ASender->Layout->SaveToFile(ASender->Name + ".xml");
}

Modify Dashboard Viewer Form Settings

The following code example demonstrates an OnViewerFormShow event handler that modifies caption, dimensions, and position of the Dashboard Viewer dialog when it is displayed:

Delphi
C++

uses
  dxDashboard;  // Declares the TdxDashboard class
//...

procedure TMyForm.dxDashboard1ViewerFormShow(ASender: TObject; AForm: TForm);
begin
  AForm.Caption := 'My Dashboard Viewer';  // Changes the Dashboard Viewer form caption
  AForm.WindowState := wsNormal;             // Switches from maximized to the normal form state
  AForm.Position := poScreenCenter;          // Centers the dialog on the screen
  AForm.Width := 1200;                       // Specifies the dialog width
  AForm.Height := 800;                       // Specifies the dialog height
end;

#include "dxDashboard.hpp"  // Declares the TdxDashboard class

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

void __fastcall TMyForm::dxDashboard1ViewerFormShow(TObject *ASender, TForm *AForm)
{
  AForm->Caption = "My Dashboard Viewer";  // Changes the Dashboard Viewer form caption
  AForm->WindowState = wsNormal;             // Switches from maximized to the normal form state
  AForm->Position = poScreenCenter;          // Centers the dialog on the screen
  AForm->Width = 1200;                       // Specifies the dialog width
  AForm->Height = 800;                       // Specifies the dialog height
}

View Example: Generate Dashboards in a Backend/Service Application

Inheritance

TObject

TPersistent

TdxDashboard

If you need to display interactive data analysis elements (dashboard visualization items) such as grids, charts, maps, and gauges, use the TdxDashboardControl component.

Controls

FREE UTILITIES

Controls and Extensions

FREE UTILITIES

Controls

FREE UTILITIES

Controls and Extensions

FREE UTILITIES

TdxDashboard Class

Declaration

Remarks

Prerequisites & Deployment

Bind to Data

Data Connection Components

Main API Members

Dashboard Content & Layout

End-User Interaction

Data Export

Code Examples

Export Dashboard Content to PDF Without User Interaction

Save Dashboard Layout to File on Every Change

Modify Dashboard Viewer Form Settings

Inheritance

TdxDashboard Class

Declaration

Remarks

Prerequisites & Deployment

Bind to Data

Data Connection Components

Main API Members

Dashboard Content & Layout

End-User Interaction

Data Export

Code Examples

Export Dashboard Content to PDF Without User Interaction

Save Dashboard Layout to File on Every Change

Modify Dashboard Viewer Form Settings

Related GitHub-Hosted Example Project

Inheritance