Dashboard Parameters

• 5 minutes to read

Dashboard parameters are dynamic values that replace constants in queries, filters, and calculated fields. Parameters allow users to transform or filter data in the same dashboard without changes to its template. For example, users can specify a date or select customers and refresh the dashboard to display new data.

To use a dashboard parameter:

1. Create and configure a parameter in the Dashboard Designer.
2. Reference the parameter in a dashboard tile filter, query, or calculated field.
3. Supply a value in the Dashboard Parameters dialog or in code.

Create and Reference Parameters

Create and manage dashboard parameters in the Parameters section of the DASHBOARD MENU:

For each parameter, specify a unique name, data type, and default value or value source. You can also specify a label, visibility, editor state, and other settings. Refer to the following help topics for detailed information on parameter creation and usage:

• Create and Configure Dashboard Parameters
• Use Dashboard Parameters

Supply Parameter Values

The Dashboard Parameters dialog displays an editor for each visible parameter. The parameter type and value source determine the editor type and available values.

Click the Dashboard Parameters icon (1) at the top to open the dialog. Specify parameter values (2) and click the Submit button (3) to update the dashboard:

Tip

You can hide parameters from the Dashboard Parameters dialog and still use their values to filter dashboard data. Refer to the following help topic for instructions: Hidden Dashboard Parameters.

Refer to the following help topic for detailed instructions: Dashboard Parameters Dialog.

Access Parameters in Code

Use the TdxDashboard.Parameters/TdxCustomDashboardControl.Parameters collection to read or modify dashboard parameter properties at runtime. The collection is automatically populated from the dashboard template. The parameter list is read-only but you can assign parameter values and change visibility.

Use the following collection members to access parameters:

• ParamByName returns a parameter by name or raises an exception if the target parameter does not exist.
• FindParam returns a parameter by name or returns nil or nullptr if the target parameter does not exist.
• Items and Count allow you to access or iterate through parameters by index.

Code Example: List Dashboard Parameters

Delphi

uses
  dxDashboard.Control,      // Declares the TdxDashboardControl class
  dxDashboard.Parameters,   // Declares the TdxDashboardParameter class
  dxMessageDialog,          // Declares the TdxMessageDialogForm class
  System.StrUtils;          // Provides advanced string management routines

procedure TForm1.cxButton1Click(Sender: TObject);
var
  AList: TStringList;
  AParameter: TdxDashboardParameter;
begin
  // Create a TStringList instance
  AList := TStringList.Create;
  try
    // Iterate through dashboard parameters
    for AParameter in dxDashboardControl1.Parameters do
      AList.Add(Format('- %s', [
        // Use the parameter Name if Description is missing
        IfThen(AParameter.Description <> '', AParameter.Description, AParameter.Name)
      ]));
    // Display the parameter list or a notification message if the list is empty
    if AList.Count > 0 then
      dxShowMessage(AList.Text)
    else
      dxShowMessage('The dashboard has no parameters.');
  finally
    AList.Free;
  end;
end;

C++

#include "dxDashboard.Control.hpp"      // Declares the TdxDashboardControl class
#include "dxDashboard.Parameters.hpp"   // Declares the TdxDashboardParameter class
#include "dxMessageDialog.hpp"          // Declares the TdxMessageDialogForm class

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

void __fastcall TForm1::cxButton1Click(TObject* Sender) {
  TStringList* AList = new TStringList();
  try {
    // Iterate through dashboard parameters
    for (int i = 0; i < dxDashboardControl1->Parameters->Count; i++) {
      TdxDashboardParameter* AParameter = dxDashboardControl1->Parameters->Items[i];
      UnicodeString ALabel;
      // Use the parameter Name if Description is missing
      if (AParameter->Description.IsEmpty())
        ALabel = AParameter->Name;
      else
        ALabel = AParameter->Description;
      AList->Add(Format(L"- %s", ARRAYOFCONST((ALabel))));
    }
    // Display the parameter list or a notification message if the list is empty
    if (AList->Count > 0)
      dxShowMessage(AList->Text);
    else
      dxShowMessage(L"The dashboard has no parameters.");
  }
  __finally {
    delete AList;
  }
}

Tutorials

The following tutorial creates a parameter, assigns its value, and passes the value to a data source:

Read Tutorial: Bind a Dashboard to a Parameterized Stored Database Procedure

Follow this tutorial to create an application that obtains data from a stored database procedure and passes a dashboard parameter as a procedure parameter.

Sample GitHub Projects

This section lists all public GitHub repositories (DevExpress-Examples) that demonstrate primary usage scenarios for dashboard parameters:

View Example: Generate Dashboards in a Backend/Service Application

This example filters dashboard data by country name.

View Example: Pass a Hidden Dashboard Parameter to a SQL Query

This example displays sales data for a selected country. The example passes the country to the underlying SQL query as a hidden dashboard parameter.

Related Compiled Demo

To see the dashboard export functionality in action, run the BI Dashboards Designer/Viewer demo in the VCL Demo Center installed with compiled DevExpress VCL demos. Select any demo in the sidebar on the left, click the Export button, and use any export option listed in the menu.

Download: Compiled VCL Demos

Compiled DevExpress demos ship with source code installed in the Public Documents folder (%PUBLIC%) for all users (default). You can find all project and source code files for the BI Dashboards Designer/Viewer demo in the following folder:

Default Installation Path

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

Tip

Project and source code files for all compiled DevExpress VCL Demos are maintained in a public repository hosted on GitHub:

View Example: DevExpress VCL Demos