ASPxDashboard.CustomParameters Event

Occurs before data is loaded from the data store and allows you to change parameter values before they are passed to a data query.

Namespace: DevExpress.DashboardWeb

Assembly: DevExpress.Dashboard.v23.1.Web.WebForms.dll

NuGet Package: DevExpress.Web.Dashboard

Declaration

C#

public event CustomParametersWebEventHandler CustomParameters

VB.NET

Public Event CustomParameters As CustomParametersWebEventHandler

Event Data

The CustomParameters event's data class is CustomParametersWebEventArgs. The following properties provide information specific to this event:

Property	Description
DashboardId	Gets the identifier of the required dashboard.
Parameters	Gets or sets dashboard parameters. Inherited from CustomParametersEventArgs.

Remarks

The CustomParameters event allows you to access a collection of dashboard parameters (e.Parameters) and change actual parameter values, parameter settings, or even add new parameters.

To set parameter values at runtime, handle the ASPxDashboard.SetInitialDashboardState event. A user can change these values in the Dashboard Parameters dialog.

Security Consideration

Parameter values specified in the CustomParameters event handler are set before executing a data query. They are not displayed in the Dashboard Parameters dialog. However, if the IncludeHiddenParameters client property is enabled (for example, DashboardExcelExportOptions.IncludeHiddenParameters), a user can still get access to all hidden parameters with their values.

Encode the passed parameter value if possible. Do not store any sensitive information in dashboard parameters that isn’t encrypted.

Example

This example shows how to pass a hidden dashboard parameter to a custom SQL query. In this example, the ASPxDashboard.CustomParameters event is handled to change the dashboard parameter’s default value before it is passed to the query.

1. Create a dashboard parameter. In the parameter’s settings, disable the Visible checkbox to hide the parameter from users. In this example, the dashboard parameter’s name is CountryDashboardParameter.

2. To allow custom SQL query execution on the server, set the AllowExecutingCustomSql property to true. To allow users to edit a custom SQL string, set the EnableCustomSql property to true. Specify the query in the SQL String editor and bind the query parameter to the dashboard parameter you created earlier. This query contains a query parameter named CountryParameter.

3. Handle the ASPxDashboard.CustomParameters event and specify the default value.

   As the result, a user see a dashboard based on the data from the SQL query with the CountryParameter query parameter’s value specified in the ASPxDashboard.CustomParameters event handler (Brazil).

View Example

WebForm1.aspx.cs

using DevExpress.DashboardWeb;
using DevExpress.DataAccess.Web;
using System;
using System.Linq;

namespace ASPxDashboard_CustomParameters {
    public partial class WebForm1 : System.Web.UI.Page {
        protected void Page_Load(object sender, EventArgs e) {
            DashboardFileStorage dashboardFileStorage = new DashboardFileStorage("~/App_Data/Dashboards");
            ASPxDashboard1.SetConnectionStringsProvider(new ConfigFileConnectionStringsProvider());
            ASPxDashboard1.SetDashboardStorage(dashboardFileStorage);
            ASPxDashboard1.CustomParameters += ASPxDashboard1_CustomParameters;
        }

        protected void ASPxDashboard1_CustomParameters(object sender, CustomParametersWebEventArgs e) {
            var countryParam = e.Parameters.FirstOrDefault(p => p.Name == "CountryDashboardParameter");
            if (countryParam != null) {
                countryParam.Value = "Brazil";
            }
        }
    }
}

WebForm1.aspx.vb

Imports DevExpress.DashboardWeb
Imports DevExpress.DataAccess.Web
Imports System
Imports System.Linq

Namespace ASPxDashboard_CustomParameters

    Public Partial Class WebForm1
        Inherits Web.UI.Page

        Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
            Dim dashboardFileStorage As DashboardFileStorage = New DashboardFileStorage("~/App_Data/Dashboards")
            ASPxDashboard1.SetConnectionStringsProvider(New ConfigFileConnectionStringsProvider())
            ASPxDashboard1.SetDashboardStorage(dashboardFileStorage)
            AddHandler ASPxDashboard1.CustomParameters, AddressOf Me.ASPxDashboard1_CustomParameters
        End Sub

        Protected Sub ASPxDashboard1_CustomParameters(ByVal sender As Object, ByVal e As CustomParametersWebEventArgs)
            Dim countryParam = e.Parameters.FirstOrDefault(Function(p) Equals(p.Name, "CountryDashboardParameter"))
            If countryParam IsNot Nothing Then
                countryParam.Value = "Brazil"
            End If
        End Sub
    End Class
End Namespace

WebForm1.aspx (C#)

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="WebForm1.aspx.cs" 
    Inherits="ASPxDashboard_CustomParameters.WebForm1" %>

<%@ Register Assembly="DevExpress.Dashboard.v21.2.Web.WebForms, Version=21.2.15.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a" 
    Namespace="DevExpress.DashboardWeb" TagPrefix="dx" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>
</head>
<body>
    <form id="form1" runat="server">
    <div style="position:absolute; left:0; right:0; top:0; bottom:0;">
        <dx:ASPxDashboard ID="ASPxDashboard1" runat="server" 
            AllowExecutingCustomSql="true"
            EnableCustomSql="true"
            Height="100%" Width="100%">
        </dx:ASPxDashboard>
    </div>
    </form>
</body>
</html>

WebForm1.aspx (VB.NET)

<%@ Page Language="VB" AutoEventWireup="true" CodeBehind="WebForm1.aspx.vb" 
    Inherits="ASPxDashboard_CustomParameters.WebForm1" %>

<%@ Register Assembly="DevExpress.Dashboard.v21.2.Web.WebForms, Version=21.2.15.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a" 
    Namespace="DevExpress.DashboardWeb" TagPrefix="dx" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>
</head>
<body>
    <form id="form1" runat="server">
    <div style="position:absolute; left:0; right:0; top:0; bottom:0;">
        <dx:ASPxDashboard ID="ASPxDashboard1" runat="server" 
            AllowExecutingCustomSql="true"
            EnableCustomSql="true"
            Height="100%" Width="100%">
        </dx:ASPxDashboard>
    </div>
    </form>
</body>
</html>

Related GitHub Examples

The following code snippet (auto-collected from DevExpress Examples) contains a reference to the CustomParameters event.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

C#

web-forms-dashboard-use-different-caches/CS/WebFormsDashboardUseDifferentCaches/Default.aspx.cs#L41

    ASPxDashboard1.CustomParameters += ASPxDashboard1_CustomParameters;
}

VB.NET

web-forms-dashboard-use-different-caches/VB/WebFormsDashboardUseDifferentCaches/Default.aspx.vb#L39

    AddHandler ASPxDashboard1.CustomParameters, AddressOf ASPxDashboard1_CustomParameters
End Sub