Files to look at:
The example shows how to create custom properties for the Web Dashboard.
Custom properties are stored in the CustomProperties collection in a structured format. Each custom property in this collection contains the custom property's metadata.
To apply custom property values to a dashboard, you need to create an extension. The extension is a JavaScript module that you can integrate into your application. Every extension that provides custom property can be divided into the following parts:
-
Model.
The model is an object that contains the property name, type, and default value. It also specifies on which level the property is created (dashboard, dashboard item or data item container). Use the Model.registerCustomProperty property to register the custom property definition.
-
Viewer
In this part you modify the viewer part according to the saved custom property value. You can use the client methods and events to change the displayed elements.
-
Designer
This part contains designer settings. Add editors and control elements to configure and change the custom property's values in the UI. This part is not required if you use the extension in Viewer mode.
-
Event Subscription
This part contains event subscriptions.
To register an extension, attach the extension script before the control is rendered and call the registerExtension method:
<script src="~/Content/Extensions/ChartAxisMaxValueExtension.js"></script>
<script src="~/Content/Extensions/ChartConstantLinesExtension.js"></script>
<script src="~/Content/Extensions/ChartLineOptionsExtension.js"></script>
<script src="~/Content/Extensions/ChartScaleBreaksExtension.js"></script>
<script src="~/Content/Extensions/ItemDescriptionExtension.js"></script>
<script src="~/Content/Extensions/DashboardDescriptionExtension.js"></script>
<script type="text/javascript">
function onBeforeRender(sender) {
var control = sender.GetDashboardControl()
control.registerExtension(new DevExpress.Dashboard.DashboardPanelExtension(control))
control.registerExtension(new ChartScaleBreaksExtension(control))
control.registerExtension(new ChartLineOptionsExtension(control))
control.registerExtension(new ChartAxisMaxValueExtension(control))
control.registerExtension(new ChartConstantLinesExtension(control))
control.registerExtension(new ItemDescriptionExtension(control))
control.registerExtension(new DashboardDescriptionExtension(control))
}
</script>
@Html.DevExpress().Dashboard(settings => {
settings.Name = "Dashboard";
settings.Width = Unit.Percentage(100);
settings.Height = Unit.Percentage(100);
settings.UseNeutralFilterMode = true;
settings.ClientSideEvents.BeforeRender = "onBeforeRender";
settings.IncludeDashboardIdToUrl = true;
settings.IncludeDashboardStateToUrl = true;
}).GetHtml()The following example contains a set of custom properties that demonstrate different capabilities. Below you find a detailed description for every extension.
This extension enables or disables scale breaks for the Chart dashboard item.
Overview:
- Adds a custom Boolean property for a specific dashboard item (Chart).
- Integrates a Scale breaks (Custom) section into the Options menu with the CheckBox widget as an editor.
This extension changes the dash style of each series line in the Chart dashboard item.
Overview:
- Adds a string custom property for a specific data item container (Chart's series).
- Integrates a Line Options (Custom) section into the data item menu with the SelectBox widget as an editor.
This extension enables you to set a dashboard's description in the dashboard menu. The dashboard description is displayed when you hover over the info button in the dashboard title.
Overview:
- Adds a custom string property for a dashboard.
- Shows how to add a new item to the ToolBox. In this example, a new item is added to the dashboard menu.
- Demonstrates how to create complex editors using templates. In this example, it is the widgets with the TextArea and Button widgets inside.
This extension enables you to set a description for each dashboard item. The dashboard item description is displayed when you hover over the info button in the item's caption.
Overview:
- Adds a custom string property for each dashboard item.
- Integrates a Description (Custom) section into the Options menu with the predefined buttonGroup template.
- Shows how to enable or disable editors depending on a custom property's value.
This extension allows you to change the maximum value of the Y-axis in the Chart item.
Overview:
- Adds a set of custom properties with different types (number, boolean, and string) for a specific dashboard item (Chart).
- Demonstrates how to bind a custom property to a list of data items.
- Shows how to enable or disable editors depending on a custom property's value.
This extension draws constant lines for the Chart dashboard item.
Overview:
- Adds a complex custom property for a specific dashboard item (Chart).
- Shows how to work with complex custom values that are saved as an array.
- Demonstrates how to bind a custom property to a list of data items.
- Customizes export to display the result in the exported document.