This article is meant for ASP .NET programmers who use the DevExpress controls library and implement the DashBoard component into projects in order to view charts.
Among the controls that can be found in the DevExpress package, there is also AspxDashboardViewer (Web Application) or DashboardViewer (Windows Application), a control that loads an XML with all the properties of the controls you need in a Dashboard. The source Xml for the Viewer is generated by the DashboardDesigner control, according to the procedure proposed by DevExpress:
Once the Xml is created, it can be loaded either in a Windows or a Web Application.
After the application which embeds the DashboardViewer is created and the source is set, we can see the created Dashboard. The disadvantage is that the Dashboard created with xml source is hard-coded in xml. The query can be parametrized from the Dashboard Parameters, but this method is also limited.
If we want to upload the DashBoard in a Windows Application we can dynamically modify the xml source (at runtime), then save the new version. If we want the DashBoard to be uploaded in Web Application, we have to dynamically customize the DashBoard without saving the new version in xml.
The source XML file
The tags of the xml source file that are important for dynamic modification are:
– DataConnection – parametrization of dynamic connection is necessary if the connection parameters are preserved and taken from a configuration file or if the connection to the database is done by using a user name and a password;
– DataSources – parametrization of the query for the connection to the database is necessary if the adding or deletion of a control in the DashBoard requires additional parameters for the query;
– Items – controls can be added or deleted here;
– LayoutTree – all controls added in the Items tag will need to be referenced in the layout, otherwise they will not appear in the Dashboard.
A general version of a XML source file:
File modification with the help of an application which embeds the DashboardDesigner provides information regarding the parameters that need to be specified in order to have a certain setup of controls in the Dashboard. Thus, the xml source file can be manipulated to obtain a view of the components layout and of the properties that need to be modified in order to obtain this result.
The properties of the Dashboard object which will be uploaded in the Application need to be accessed in order to modify the properties of the components that will be loaded in the DashBoard.
If a Windows (Desktop) application is generated, the access to this object can be done from anywhere in the application:
DevExpress.DashboardCommon.Dashboard d = dashboardViewer1.Dashboard;
In the case of a Web application, the access to the DashBoard object is done only by handling the DashboardLoaded event with the help of the DashboardLoadedWebEventArgs type argument:
protected void ASPxDashboardViewer1_DashboardLoaded(object sender, DevExpress.DashboardWeb.DashboardLoadedWebEventArgs e)
Dashboard dashboard = e.Dashboard;
If users who access the Web page with the DashBoard have different rights over the data viewed in the DashBoard, but especially if the Dashboard will be implemented with multi-language support, it is necessary to modify the sql query by accessing the properties of the DataSources object:
//Modification de la chaîne de connexion pour accéder à la base de données
dashboard.DataSources[“dataSource1″].SqlDataProvider.DataConnection.ConnectionString = “Data Source=localhost;Initial Catalog=Norwind;Integrated Security=SSPI”;
It is possible to modify the properties of existing components in DashBoard, if we want to modify the title, for exemple, or the argument of a graphic (modification necessary for the configuration of a multi-language medium).
//La manipulation des propriétés de composants
((PieDashboardItem)dashboard.Items[“pieDashboardItem1″]).Name = “Titre tarte”;
((PieDashboardItem)dashboard.Items[“pieDashboardItem1″]).Arguments.DataMember = “Title”;
In order to add a new graphic type component, an object with the adequate properties needs to be created:
//Ajouter une nouvelle tarte
PieDashboardItem pie = new PieDashboardItem();
pie.Name = “Pies 2″;
pie.ComponentName = “pieDashboardItem2″;
pie.DataSource = dashboard.DataSources[“dataSource1″];
For a better customization of the controls (for example of the texts which are automatically displayed on the axes, of the data view mode, of the number format) , these properties must also be added to the created component.
pie.LabelContentType = PieValueType.ValueAndPercent;
pie.TooltipContentType = PieValueType.Argument;
pie.ShowPieCaptions = false;
pie.PieType = PieType.Donut;
After the component is added to the Dashboard, it must be also added to the LayoutRoot, this property of the Dashboard being configured for the correct positioning in the Dashboard.
DashboardLayoutItem layout = new DashboardLayoutItem(pie, 51.3545347467609);
The positioning in the Dashboard of each element is done based on a ”weight” barycentre which can be calculated, but for a more precise positioning the xml source file can be modified, the new positions of the components saved and follow the values of the barycentre.
The example given uses the Northwind database available on Codeplex:
This article was intended to help programmers get accustomed with DevExpress DashBoard.
We hope it reached its goal. We are waiting for your comments; information exchange will allow us improve our collective skills.