DashboardParameterDialogExtension Class

A Web Dashboard extension that is the Dashboard Parameters dialog.

Declaration

export class DashboardParameterDialogExtension extends DisposableObject implements ISupportOptionExtension<DashboardParameterDialogExtensionOptions>

Remarks

To configure the extension, refer to the DashboardParameterDialogExtensionOptions class that contains the Dashboard Parameter Dialog’s options.

See the following topic for information on how to use the DashboardControl’s client-side API: Extensions Overview.

Implements

ISupportOptionExtension

Inherited Members

dispose

Inheritance

DisposableObject

DashboardParameterDialogExtension

constructor(dashboardControl)

Initializes a new instance of the DashboardParameterDialogExtension class.

Declaration

constructor(
    dashboardControl: DevExpress.Dashboard.DashboardControl,
    options?: DashboardParameterDialogExtensionOptions
)

Parameters

Name	Type	Description
dashboardControl	DashboardControl	A Web Dashboard control that owns the extension.
options	DashboardParameterDialogExtensionOptions	A DashboardParameterDialogExtensionOptions object that contains the extension options.

Properties

name Property

Specifies the unique extension name.

Declaration

name: string

Property Value

Type	Description
string	The unique extension name. The return value is `dashboardParameterDialog`.

Remarks

Use the dashboardParameterDialog name in the following cases:

Call the DashboardControl.findExtension method and pass the extension name as a parameter to access the extension.
Call the control’s option method to change the extension options.

Warning

Do not change the unique name of the extension registered in the Web Dashboard to avoid exceptions.

off Property

Unsubscribes from DashboardParameterDialogExtension events.

Declaration

off: DevExpress.Dashboard.Internal.EventSubscriber<DashboardParameterDialogExtensionEvents>

Property Value

Type	Description
EventSubscriber<DashboardParameterDialogExtensionEvents>	An event subscription.

Remarks

The extension’s on and off methods help you subscribe to and unsubscribe from events.

on Property

Subscribes to DashboardParameterDialogExtension events.

Declaration

on: DevExpress.Dashboard.Internal.EventSubscriber<DashboardParameterDialogExtensionEvents>

Property Value

Type	Description
EventSubscriber<DashboardParameterDialogExtensionEvents>	An event subscription.

Remarks

The extension’s on and off methods help you subscribe to and unsubscribe from events.

onHidden Property

A handler for the event that occurs when the Dashboard Parameter dialog is hidden.

Declaration

get onHidden(): ((e: DashboardParameterDialogArgs) => any)
set onHidden(value: ((e: DashboardParameterDialogArgs) => any))

Property Value

Type	Description
(e: DashboardParameterDialogArgs) => any	A function that is executed when the Dashboard Parameter dialog is hidden.

onShowing Property

A handler for the event that occurs before the Dashboard Parameter dialog is shown.

Declaration

get onShowing(): ((e: DashboardParameterDialogArgs) => any)
set onShowing(value: ((e: DashboardParameterDialogArgs) => any))

Property Value

Type	Description
(e: DashboardParameterDialogArgs) => any	A function that is executed before the Dashboard Parameter dialog is shown.

onShown Property

A handler for the event that occurs after the Dashboard Parameter dialog is shown.

Declaration

get onShown(): ((e: DashboardParameterDialogArgs) => any)
set onShown(value: ((e: DashboardParameterDialogArgs) => any))

Property Value

Type	Description
(e: DashboardParameterDialogArgs) => any	A function that is executed after the Dashboard Parameter dialog is shown.

showDialogButton Property

Specifies whether the Parameter button is shown in the dashboard title.

Declaration

showDialogButton: ko.Observable<boolean>

Property Value

Type	Description
Observable<boolean>	true, to show the Parameter button in the dashboard title; otherwise, false.

Remarks

You can change the values of the dashboard parameters in the Dashboard Parameters dialog. To open the dialog, click the Parameters button in the dashboard title.

You can hide the Parameters button. To do this, pass false to the showDialogButton property:

// The dashboardControl variable is the obtained DashboardControl instance.
var parameterDialogExt = dashboardControl.findExtension('dashboardParameterDialog');
parameterDialogExt.showDialogButton(false);

For more information on how to change the dashboard parameter values in the UI and in code, refer to the following article: Specify Dashboard Parameter Values.

See Also

Specify Dashboard Parameter Values

Methods

getParameters Method

Returns dashboard parameter settings and metadata.

Declaration

getParameters(): DevExpress.Dashboard.DashboardParameterCollection

Returns

Type	Description
DashboardParameterCollection	A DashboardParameterCollection object that contains parameter settings and metadata.

Example

This example shows how to change dashboard parameter values on the client.

The example uses the following methods:

DashboardParameterDialogExtension.getParameters: Returns dashboard parameter settings and metadata.
DashboardParameter.setValue: Specifies the current parameter value(s).
DashboardParameter.getDefaultValue: Returns a default parameter value.
DashboardParameterDialogExtension.show: Invokes the Dashboard Parameters dialog.

View Example

ParameterValues.js

function onBeforeRender(s) {
    var dashboardControl = s.GetDashboardControl();
    if (dashboardControl) {
        dashboardControl.on('dashboardEndUpdate', function () { setParameterValues(dashboardControl); })
    }
}

function setParameterValues(control) {
    var parameterDialogExt = control.findExtension('dashboardParameterDialog');
    $("#setParameterValuesButton").dxButton({
        text: 'Specify Parameter Values',
        onClick: function () {
            var parameters = parameterDialogExt.getParameters();
            var paramCategory = parameters.getParameterByName("categoryParameter"),
                paramStartDate = parameters.getParameterByName("startDateParameter");
            paramCategory.setValue("Condiments");
            paramStartDate.setValue(new Date(2015, 3, 1));
        }
    });
    $("#resetParameterValuesButton").dxButton({
        text: 'Reset Parameter Values',
        onClick: function () {
            var parameters = parameterDialogExt.getParameters();
            var paramCategory = parameters.getParameterByName("categoryParameter"),
                paramStartDate = parameters.getParameterByName("startDateParameter");
            paramCategory.setValue(paramCategory.getDefaultValue());
            paramStartDate.setValue(paramStartDate.getDefaultValue());
        }
    });
    $("#showParametersDialog").dxButton({
        text: 'Show Parameters Dialog',
        onClick: function () {
            parameterDialogExt.show();
        }
    });
}

See Also

Specify Dashboard Parameter Values

hide Method

Closes the Dashboard Parameters dialog.

Declaration

hide(): void

renderContent(element) Method

Renders the content of the Dashboard Parameter dialog inside the specified DOM element.

Declaration

renderContent(
    element: JQuery | Element
): DevExpress.Dashboard.ParameterDialogContent

Parameters

Name	Type	Description
element	Element \| JQuery<HTMLElement>	A DOM element where the content of the Dashboard Parameter dialog is rendered.

Returns

Type	Description
ParameterDialogContent	A content of the Dashboard Parameter dialog.

show Method

Invokes the Dashboard Parameters dialog.

Declaration

show(): void

Example

This example shows how to change dashboard parameter values on the client.

The example uses the following methods:

DashboardParameterDialogExtension.getParameters: Returns dashboard parameter settings and metadata.
DashboardParameter.setValue: Specifies the current parameter value(s).
DashboardParameter.getDefaultValue: Returns a default parameter value.
DashboardParameterDialogExtension.show: Invokes the Dashboard Parameters dialog.

View Example

ParameterValues.js

function onBeforeRender(s) {
    var dashboardControl = s.GetDashboardControl();
    if (dashboardControl) {
        dashboardControl.on('dashboardEndUpdate', function () { setParameterValues(dashboardControl); })
    }
}

function setParameterValues(control) {
    var parameterDialogExt = control.findExtension('dashboardParameterDialog');
    $("#setParameterValuesButton").dxButton({
        text: 'Specify Parameter Values',
        onClick: function () {
            var parameters = parameterDialogExt.getParameters();
            var paramCategory = parameters.getParameterByName("categoryParameter"),
                paramStartDate = parameters.getParameterByName("startDateParameter");
            paramCategory.setValue("Condiments");
            paramStartDate.setValue(new Date(2015, 3, 1));
        }
    });
    $("#resetParameterValuesButton").dxButton({
        text: 'Reset Parameter Values',
        onClick: function () {
            var parameters = parameterDialogExt.getParameters();
            var paramCategory = parameters.getParameterByName("categoryParameter"),
                paramStartDate = parameters.getParameterByName("startDateParameter");
            paramCategory.setValue(paramCategory.getDefaultValue());
            paramStartDate.setValue(paramStartDate.getDefaultValue());
        }
    });
    $("#showParametersDialog").dxButton({
        text: 'Show Parameters Dialog',
        onClick: function () {
            parameterDialogExt.show();
        }
    });
}

See Also

Specify Dashboard Parameter Values

start Method

Contains code that is executed when you register the dashboard extension.

Declaration

start(): void

stop Method

Contains code that is executed when you unregister the dashboard extension.

Declaration

stop(): void

subscribeToContentChanges(callback) Method

Allows you to handle any changes in the collection of dashboard parameters.

Declaration

subscribeToContentChanges(
    callback: (newValue: DevExpress.Dashboard.DashboardParameterCollection) => void
): ko.Subscription

Parameters

Name	Type	Description
callback	(newValue: DashboardParameterCollection) => void	A function that is called on any changes in the collection of dashboard parameters.

Returns

Type	Description
ko.Subscription	A KnockoutSubscription object that allows you to terminate a subscription.

Remarks

The subscribeToContentChanges method is used in the custom Parameter item.

The method allows you to subscribe to any changes in the collection of dashboard parameters:

when you change dashboard parameter settings (the type, the default parameter value, the parameter name, and so on)
when you remove a dashboard parameter from the DashboardParameterCollection
when you add a dashboard parameter to the DashboardParameterCollection.

See Also

Specify Dashboard Parameter Values