DashboardControlOptions Interface
Provides options for configuring the DashboardControl.
Declaration
export interface DashboardControlOptions
Remarks
You can configure the DashboardControl‘s options when calling constructor(element). The code snippet below shows how to specify several options when creating the DashboardControl:
var dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
endpoint: "/api/dashboard",
workingMode: "ViewerOnly",
initialDashboardId: "dashboard1"
});
Refer to DashboardControl to see an HTML page example containing the DashboardControl.
Properties
ajaxRemoteService Property
Declaration
ajaxRemoteService?: AjaxRemoteServiceOptions
Property Value
Type |
---|
AjaxRemoteServiceOptions |
allowMaximizeItems Property
Specifies whether end users can maximize dashboard items.
Declaration
allowMaximizeItems?: boolean
Property Value
Type | Description |
---|---|
boolean | true, to allow maximizing dashboard items; otherwise, false. |
dataRequestOptions Property
Specifies an item’s data request mode for a dashboard.
Declaration
dataRequestOptions?: DataRequestOptions
Property Value
Type | Description |
---|---|
DataRequestOptions | A DataRequestOptions value used to specify a data request mode for a dashboard. |
Remarks
When a Web Dashboard loads data, it groups data dashboard items by master-filter items. While dashboard data is loading, the group waits when its master-filter item is loaded and then performs simultaneous separate requests for each dashboard item in this group. A blocking item temporarily blocks data receiving for detailed items: data for detailed items depends on the data from blocking items (it is the Range Filter item, single master-filter items, and filter items when the neutral filter mode is disabled).
This behavior allows you to render lightweight items with little loading time, while heavy dashboard items with long loading time are waiting for a response. In certain cases, this is not optimal behavior. For example, in Web Forms, parallel query processing is disabled. In this case, the batch requests mode allows you to improve performance when items grouped by one master-filter item are send in a one request.
encodeHtml Property
Specifies whether the DashboardControl‘s value and element content are rendered as pure HTML, or HTML markers are stripped out.
Declaration
encodeHtml?: boolean
Property Value
Type | Description |
---|---|
boolean | true if the HTML code contained within the DashboardControl’s value and element content are not executed and are converted into the corresponding text for display purposes; false if the web control’s value and element content can contain pure HTML code. |
endpoint Property
Specifies the URL used by the DashboardControl to send data requests to a server.
Declaration
endpoint?: string
Property Value
Type | Description |
---|---|
string | A string value that specifies the endpoint URL prefix used to send data requests to a server. |
Remarks
The endpoint property specifies the URL used to interact with a backend (to send data requests to a server). The value should consist of a base URL where the Web Dashboard’s server side is hosted and a route prefix - a value that is set in the MVC / .NET Core MapDashboardRoute properties. The following code snippet shows how to set the URL used by the DashboardControl to send data requests to a server:
<head>
<!-- ...-->
<script>
window.onload = function () {
DevExpress.Dashboard.ResourceManager.embedBundledResources();
var dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
endpoint: "{baseURL}/api/dashboard",
});
dashboardControl.render();
};
</script>
</head>
To learn how to perform server-side configuration to allow the DashboardControl to interact with a backend, see the following topics:
Note
If you use the Web Forms, MVC, or .NET Core controls as a client, use the DashboardBackendOptions class to configure the backend options.
extensions Property
Specifies the registered extension settings.
Declaration
extensions?: ExtensionOptions | false
Property Value
Type |
---|
ExtensionOptions |
false |
initialDashboardId Property
Specifies the identifier of the dashboard to be loaded to the DashboardControl.
Declaration
initialDashboardId?: string
Property Value
Type | Description |
---|---|
string | A string value that specifies the dashboard identifier. |
Remarks
Use the initialDashboardId option to load a dashboard with the specified identifier from the dashboard storage. The code snippet below shows how to load a dashboard with the dashboard1 identifier:
var dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
endpoint: "/api/dashboard",
initialDashboardId: "dashboard1"
});
initialDashboardState Property
Specifies the initial state of the loaded dashboard.
Declaration
initialDashboardState?: string
Property Value
Type | Description |
---|---|
string | A string value that specifies the dashboard state saved in JSON format. |
Remarks
Use the initialDashboardId option to set the identifier of the dashboard to which the state is applied.
To specify the initial dashboard state, initialize the DashboardState object on a server, save this object to JSON using the DashboardStateExtensions.SaveToJson extension method and assign the resulting string to the initialDashboardState property.
The following code shows how to pass a string that contains a dashboard state saved in JSON format to the initialDashboardState property:
var dashboardControl = new DashboardControl(this.element.nativeElement.querySelector(".dashboard-container"), {
endpoint: "https://demos.devexpress.com/services/dashboard/api",
workingMode: "Viewer",
initialDashboardState: "{\"Items\":{\"gridSalesByState\":{\"MasterFilterValues\":[[\"Nevada\"]]}}}",
});
limitVisibleDataMode Property
Specifies a data limitation mode that allows you to display a reduced form of visible data.
Declaration
limitVisibleDataMode?: LimitVisibleDataMode
Property Value
Type | Description |
---|---|
LimitVisibleDataMode | A LimitVisibleDataMode value that is the data limitation mode. |
Remarks
Data reduction is used to accelerate the rendering of visual elements and to improve the Web Dashboard performance. First, the Web Dashboard control obtains the underlying data and performs all required calculations. After that, if the Web Dashboard needs a lot of time to render the content, visible data will be limited.
loadDefaultDashboard Property
Specifies whether the default dashboard should be loaded from the dashboard storage.
Declaration
loadDefaultDashboard?: boolean
Property Value
Type | Description |
---|---|
boolean | true, to load the default dashboard from the dashboard storage; otherwise, false. |
Remarks
Note that the loadDefaultDashboard property is in effect if initialDashboardId is not specified. Otherwise, the dashboard with the specified identifier will be loaded.
onDashboardBeginUpdate Property
A handler for the event occurring when a dashboard update is initiated.
Declaration
onDashboardBeginUpdate?: (args: DashboardUpdateArgs) => void
Property Value
Type | Description |
---|---|
(args: DashboardUpdateArgs) => void | A function that is executed when a dashboard update is initiated. |
onDashboardEndUpdate Property
A handler for the event occurring after the dashboard update is performed.
Declaration
onDashboardEndUpdate?: (args: DashboardUpdateArgs) => void
Property Value
Type | Description |
---|---|
(args: DashboardUpdateArgs) => void | A function that is executed after the dashboard update is performed. |
onDashboardInitialized Property
A handler for the event occurring after the dashboard displayed in the control has been initialized.
Declaration
onDashboardInitialized?: (args: DashboardInitializedArgs) => void
Property Value
Type | Description |
---|---|
(args: DashboardInitializedArgs) => void | A function that is executed after the dashboard displayed in the control has been initialized. |
onDashboardInitializing Property
A handler for the event occurring before the dashboard displayed in the control has been initialized.
Declaration
onDashboardInitializing?: (args: DashboardInitializingArgs) => void
Property Value
Type | Description |
---|---|
(args: DashboardInitializingArgs) => void | A function that is executed before the dashboard displayed in the control has been initialized. |
onDashboardStateChanged Property
A handler for the event occurring after the current dashboard state in the Web Dashboard is changed.
Declaration
onDashboardStateChanged?: (args: DashboardStateChangedArgs) => void
Property Value
Type | Description |
---|---|
(args: DashboardStateChangedArgs) => void | A function that is executed after the state of the dashboard displayed in the Web Dashboard is changed. |
onInitializing Property
A handler for the event occurring after the control has been initialized and before the control has been rendered.
Declaration
onInitializing?: (args: {
component: DashboardControl;
}) => void
Property Value
Type | Description |
---|---|
(args: {component: DashboardControl}) => void | A function that is executed after the control has been initialized and before the control has been rendered. |
onItemBeginUpdate Property
A handler for the event occurring when a dashboard item update is initiated.
Declaration
onItemBeginUpdate?: (args: DashboardItemUpdateArgs) => void
Property Value
Type | Description |
---|---|
(args: DashboardItemUpdateArgs) => void | A function that is executed when a dashboard item update is initiated. |
onItemEndUpdate Property
A handler for the event occurring after the dashboard item update is performed.
Declaration
onItemEndUpdate?: (args: DashboardItemUpdateArgs) => void
Property Value
Type | Description |
---|---|
(args: DashboardItemUpdateArgs) => void | A function that is executed after the dashboard item update is performed. |
resizeByTimer Property
Specifies whether to redraw the DashboardControl when the size of a container is changed.
Declaration
resizeByTimer?: boolean
Property Value
Type | Description |
---|---|
boolean | true, to redraw the DashboardControl when the size of the a container is changed; otherwise, false. |
Remarks
The DashboardControl redraws itself when the size of its parent container is changed. You can set the resizeByTimer property to false to disable automatic redrawing. In this case, call the repaint method to redraw the DashboardControl.
showConfirmationOnBrowserClosing Property
Specifies whether to show a browser warning if an end-user attempts to leave the page with unsaved data.
Declaration
showConfirmationOnBrowserClosing?: boolean
Property Value
Type | Description |
---|---|
boolean | true, to show dialog; otherwise, false. |
useCardLegacyLayout Property
Specifies whether to enable the legacy card layout used prior to v17.1.
Declaration
useCardLegacyLayout?: boolean
Property Value
Type | Description |
---|---|
boolean | true, to enable the legacy card layout used prior to v17.1; otherwise, false. |
Remarks
With v17.1 and later, the Card dashboard item allows you to arrange elements within individual cards using different layout types (Stretched, Compact, etc.). By default, the Card dashboard item uses the Stretched layout type that arranges card elements so that they occupy an entire card area.
The useCardLegacyLayout property allows you to create cards in a legacy layout using the Designer mode of the Web Dashboard.
Note
Note that if you load a dashboard XML file created before v17.1, cards will be displayed in the old layout. To display such cards using the new layout, specify the required layout type in the UI or in code.
useNeutralFilterMode Property
Specifies whether to show all items in the filter elements deselected by default.
Declaration
useNeutralFilterMode?: boolean
Property Value
Type | Description |
---|---|
boolean | true, if all items in the filter elements deselected by default; otherwise, false. |
Remarks
The standard filter mode shows all items in the filter elements selected. An extra click is required to begin any actual filtering operation. This is not an optimal implementation for performance reasons, because it generates filtering criteria that are evaluated by the data layer and/or the database.
The neutral filter mode does not apply any criteria to the data source in its default state, resulting in improved performance.
See Neutral Filter Mode to learn more about the neutral filter mode.
workingMode Property
Specifies the Web Dashboard control’s working mode.
Declaration
workingMode?: WorkingMode
Property Value
Type | Description |
---|---|
WorkingMode | A value that specifies the Web Dashboard control’s working mode. |
Remarks
Use the isDesignMode property to get a value that indicates whether the Web Dashboard works in the Designer mode.
The code below shows how to specify the Web Dashboard’s working mode in a constructor:
```html
<head>
<!-- ...-->
<script>
window.onload = function () {
DevExpress.Dashboard.ResourceManager.embedBundledResources();
var dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
endpoint: "/api/dashboard",
workingMode: "Viewer" // Enables the Viewer mode.
});
dashboardControl.render();
};
</script>
</head>
```