Ticket T380965
Visible to All Users

How to: Use DevExtreme Widgets in an XAF ASP.NET WebForms

created 9 years ago (modified 3 years ago)

When to use DevExtreme widgets?
DevExtreme widgets primarily target ASP.NET, SPA, or ASP.NET MVC applications. Although applications created with the eXpress App Framework are a bit different, you may want to use these widgets in specific scenarios. Here are a few examples:
- If ASP.NET controls’ capabilities and Client Side Events are not sufficient to implement the required level of interactivity, you can build a view using a сustom UserControl and DevExtreme widgets.
- When you want to display data retrieved from a third-party web service, client-side widgets can help you avoid processing this data on the server side. It is possible call the web service directly from the web browser using the AJAX technology. DevExtreme widgets better support this scenario.
You may want to use DevExtreme widgets for other reasons and this article describes how to embed them into XAF views.

How to reference required client libraries?
Although an XAF application automatically registers DevExtreme scripts (some DevExtreme widgets are used by the XAF Web UI, others by XAF modules), we suggest that you register DevExtreme scripts manually to avoid possible compatibility issues when upgrading your project to the newer version of DevExpress components.To do this, disable automatic embedding of client libraries by adding the following code to the DevExpress section in the Web.config file.
16.2+

XML
<devExpress> <resources> </resources> </devExpress>

16.1 or older:

XML
<devExpress> <settings embedRequiredClientLibraries="false" />

For more details, refer to the Embedding Third-Party Libraries article.

Download necessary JavaScript files from corresponding web sites and add them to your Web project (you can use the NuGet Package Manager for this purpose). Add references to JavaScript files into the <HEAD> section of the Default.aspx file.

ASPx
<link rel="stylesheet" type="text/css" href="Content/dx.common.css" /> <link rel="stylesheet" type="text/css" href="Content/dx.light.css" /> <script type="text/javascript" src="Scripts/jquery-1.11.3.min.js"></script> <script type="text/javascript" src="Scripts/jquery.validate.min.js"></script> <script type="text/javascript" src="Scripts/jquery.validate.unobtrusive.min.js"></script> <script type="text/javascript" src="Scripts/jquery.unobtrusive-ajax.min.js"></script> <script type="text/javascript" src="Scripts/globalize/globalize.js"></script> <script type="text/javascript" src="Scripts/dx.webappjs.js"></script> <script type="text/javascript" src="Scripts/dx.chartjs.js"></script>

A list of client libraries required by regular ASP.NET components is provided in the Embedding Third-Party Libraries article.

CSS:
If you want to use DevExtreme UI Components, it is also necessary to include CSS files corresponding to the theme that you would like to use. In most cases it is sufficient to reference the dx.common.css and dx.dark.css (or dx.light.css) files. These files are added to your project if you install the DevExtreme package using the NuGet Package Manager. You can also register them through the npm packages or CDN services. Otherwise, download the ZIP archive from the DevExtreme Web Site and find CSS files in the following directory: lib\css. Add corresponding files to your Web project and reference them in the <HEAD> section of the Default.aspx file.

ASPx
<link rel="stylesheet" type="text/css" href="css/dx.common.css" /> <link rel="stylesheet" type="text/css" href="css/dx.dark.css" />

If you want to use only the Chart Widget, CSS files are not required.

Adding DevExtreme widgets to a custom UserControl
Add UserControl using the approach described in this article: How to: Show a Custom Data-Bound Control in an XAF View (ASP.NET). Note that you do not need to add any content to UserControl and can skip the "Bind the Control to Data Using Object Space"  section.
Add the ASPxPanel  control into UserControl. This panel will be used as a container for DevExtreme widgets. If you are using the dxChartControl component, set the ASPxPanel.Height property to an absolute value, because this component is intended to inherit the height of its parent container. Handle the client-side Init  event and run a JavaScript function that adds DevExtreme widgets to ASPxPanel.

ASPx
<%@ Register Assembly="DevExpress.Web.v15.2, Version=15.2.10.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a" Namespace="DevExpress.Web" TagPrefix="dx" %> <dx:ASPxPanel ID="ASPxPanel1" runat="server" Height="500px"> <ClientSideEvents Init="function(s, e) { DxSample.OrdersChart.createWidgets(s); }" /> </dx:ASPxPanel>

To obtain a <div> element created by ASPxPanel, you can use the ASPxClientPanel.GetMainElement  method as shown below.

JavaScript
window.DxSample = window.DxSample || {}; window.DxSample.OrdersChart = { createWidgets: function (panel) { var $mainElement = $(panel.GetMainElement()); $mainElement.dxChart({..}); } };

Note: To create widgets, we suggest using the client-side Init event of the ASPxPanel component instead of the document's ready event. This is necessary because the ready event does not fire if the view item's content is reloaded during a callback. To learn how to implement the createWidgets function, refer to the online DevExtreme documentation:

Create and Configure a Component
Chart Overview

It is better not to write this code directly in UserControl's markup, because this approach prevents you from creating multiple instances of the same UserControl. Instead, put JavaScript code into a separate file and add a reference to this file to the web page. To do this, use the WebWindow.RegisterClientScriptInclude method.

C#
protected override void OnLoad(EventArgs e) { base.OnLoad(e); string url = this.ResolveClientUrl("~/Scripts/Controls/orders-chart.js"); WebWindow.CurrentRequestWindow.RegisterClientScriptInclude("orders-chart", url); }
Visual Basic
Protected Overrides Sub OnLoad(ByVal e As EventArgs) MyBase.OnLoad(e) Dim url As String = Me.ResolveClientUrl("~/Scripts/Controls/orders-chart.js") WebWindow.CurrentRequestWindow.RegisterClientScriptInclude("orders-chart", url) End Sub

Providing data loaded from the database
If you are using DevExtreme widgets to visualize data obtained from a third party service, you can use all data binding approaches described in the DevExtreme documentation: Data Layer. However, sometimes, it is necessary to obtain data directly from the database. In this situation, you can use the approach described in this article: How to: Access Server Data on the Client Side.
Add the IComplexControl  interface implementation to the UserControl class in code behind. The Setup  method of this interface will be called automatically when the view containing your UserControl is shown. Within this method, you can load data from the database, convert it to an array of simple objects, and assign the result to a custom JS property that will be available on the client side as a JavaScript array.

JavaScript
createWidgets: function (panel) { var $mainElement = $(panel.GetMainElement()); $mainElement.dxChart({ dataSource: panel.cpChartData, // .. }); }

A complete example demonstrating how to implement this approach is provided here: How to display the dxChart widget in an XAF view.

Disclaimer: The information provided on DevExpress.com and affiliated web properties (including the DevExpress Support Center) is provided "as is" without warranty of any kind. Developer Express Inc disclaims all warranties, either express or implied, including the warranties of merchantability and fitness for a particular purpose. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.

Confidential Information: Developer Express Inc does not wish to receive, will not act to procure, nor will it solicit, confidential or proprietary materials and information from you through the DevExpress Support Center or its web properties. Any and all materials or information divulged during chats, email communications, online discussions, Support Center tickets, or made available to Developer Express Inc in any manner will be deemed NOT to be confidential by Developer Express Inc. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.