Back to Devexpress

TdxDashboard Class

vcl-dxdashboard.md

latest12.7 KB
Original Source

TdxDashboard Class

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

Declaration

delphi
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

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

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

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.

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.

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

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

Code Examples:

Related GitHub-Hosted Example Project

View Example: Generate Dashboards in a Backend/Service Application

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;
cpp
#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
  }
}

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.

See Also

TdxReport Class

TdxDashboardControl Class

Backend for VCL Reports/Dashboards

TdxDashboard Members

dxDashboard Unit