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.

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.

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

TdxBackendInMemoryJSONConnection

A component designed for interaction with data stored in memory (in the JSON format).

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 Web-based TdxDashboardControl and TdxReport components together with VCL-compatible data sources.

TdxBackendDatabaseSQLConnection

A DevExpress XPO-based component designed to fetch data from an SQL database (SQL Server, PostgreSQL, SQLite, etc.).

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 Backend: 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 and Layout

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).

Parameters

Provides access to the collection of dashboard parameters.

Note

The Parameters collection is initially empty. Call the Parameters.LoadFromLayout procedure to populate the collection from the current dashboard layout definition.

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

ExportTimeout

Specifies a timeout interval (in milliseconds) for all export operations.

ExportTo

Exports the current dashboard to a file or stream in any supported format.

Code Example: 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

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;

C++

#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(AJSONDat);  // 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
  }
}

Inheritance

TObject

TPersistent

TdxDashboard

Footnotes

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