How It Works
- 8 minutes to read
This document covers the fundamentals of DevExpress ASP.NET MVC extensions.
Implementation Details
Why “extensions”?
DevExpress ASP.NET MVC extensions extend the standard HTML Helper class (Html) with the DevExpress() extension method (HtmlHelperExtension.DevExpress). The DevExpress() extension method returns an extensions factory object (ExtensionsFactory), which implements a set of HTML helper methods providing access directly to DevExpress ASP.NET MVC extensions.
How to declare?
The ExtensionsFactory helper methods accept extension specific settings (an [ExtensionName]Settings object that is a SettingsBase descendant) as a parameter and return the [ExtensionName]Extension object (an ExtensionBase descendant).
The [ExtensionName]Extension objects provide methods allowing you to render the extension to the View (i.e., ExtensionBase.GetHtml or ExtensionBase.Render), bind the extension to data, etc.
For example, if you declare the ListBox extension, you should call the ExtensionsFactory.ListBox extension method and pass the ListBoxSettings object to the method as a parameter. The ExtensionsFactory.ListBox extension method will return the ListBoxExtension object.
How to define settings?
Each ExtensionsFactory helper method provides two overloads that allow you to define the extension settings in the two ways listed below.
Using a settings delegate
The code example below demonstrates how to define the extension settings by using the settings delegate.
@{ // The extension settings are defined using the settings delegate. Html.DevExpress().TextBox(settings => { // Define the extension settings here. // The extension name must be defined. settings.Name = "textBox"; }).GetHtml(); }Passing a settings object to the extension method
The code example below demonstrates how to define the extension settings by passing the settings object to the extension method from the View.
@{ var tbSettings = new TextBoxSettings(); // The extension name must be defined. tbSettings.Name = "textBox"; } @{ // The extension settings are defined by passing the settings object to the TextBox() extension method. Html.DevExpress().TextBox(tbSettings).GetHtml(); }The code example below demonstrates how to define the extension settings by passing the settings object to the extension method from a Controller as a ViewBag item.
using System.Web.Mvc; namespace MyProject.Controllers { public class HomeController : Controller { public ActionResult Index() { var s = new DevExpress.Web.Mvc.TextBoxSettings(); s.Name = "myTextBox"; ViewBag.MyTextBoxSettings = s; return View(); } } }
Important
The GetHtml() or Render() method of an extension object must be called to render the HTML markup into a View. Note that calling the GetHtml() or Render() method is required; otherwise, the extension will not produce any HTML output. Refer to the Using Extensions in Razor Views document to learn about the method that should be used for each particular case.
If you use the ASPX view engine, you should use the Render (ExtensionBase.Render) method of an extension object to render the HTML markup to a View.
To learn more about declaring extensions in Views and customizing extension settings, refer to the Using Extensions in Razor Views document.
Server-Side Structure of MVC Extensions
Extension settings
To control the extension’s appearance, behavior and look-and-feel on the server side, you should modify the extension settings using the API provided by the corresponding [ExtensionName]Settings object.
In the list below, you can find some of the settings that are typically provided by the [ExtensionName]Settings objects.
Extension name
The extension’s name is used as the unique ID. On the client side, the extensions are also accessible via their names (see SettingsBase.Name).
Important
The extension name must always be defined.
Theme
You can define a theme applied to the extension (see SettingsBase.Theme).
Dimensions
The SettingsBase.Height and SettingsBase.Width properties allow you to define the extension dimensions.
Client-side events
The client-side events allow you to perform custom actions on the client in response to an end-user’s manipulations of an extension (see Client-Side API).
Callback routing logic
Some MVC extensions can load or update their content via their own callbacks. For these extensions, you can define the name of a Controller and action that will handle the extension’s callbacks by using the [ExtensionName]Settings.CallbackRouteValues property (see Using Callbacks).
Content templates
Most DevExpress MVC extensions support content templates that allow you to custom render a portion of an extension.
Data source fields
When an MVC extension retrieves a set of its items from a bound data source, you can define data source fields from which the individual item characteristics are obtained.
Collection of items
Most of our extensions can display a set of items like menu items, navbar items and groups, tabs (in PageControl and TabControl), images (e.g., in ImageGallery, ImageSlider), etc. In most cases, an extension can retrieve these items automatically from a bound data source, but you can also add the required items manually, by populating a related collection (for example, such collections can be accessed using properties like ImageSliderSettings.Items, TabControlSettings.Tabs, NavBarSettings.Groups, etc.).
Appearance settings
Visual ASP.NET MVC extensions expose the Styles property that allows you to access the style settings for the different visual elements of the extension (e.g., ImageGallerySettings.Styles). The style settings for the entire extension can be accessed via the SettingsBase.ControlStyle property.
You can change the images for different visual elements of extensions. These settings are usually available via the Images property (e.g., GridViewSettings.Images).
Binding to data
To provide a data-aware extension with data, you should bind the extension to a data source using the extension’s Bind or BindList method (e.g., GridViewExtension.Bind, ComboBoxExtension.BindList).
Certain DevExpress ASP.NET MVC extensions can be bound to a specific data source (like XML or Sitemap file or a folder), in a declarative manner using the specific data binding methods, for example BindToXML, BindToFolder, etc.
To learn more about binding extensions to data, refer to the Data Binding and Binding Data Editors to Data topics.
Note
When the DevExpress ASP.NET MVC extension is configured and bound to data, the extension’s instance is represented by the MVCx[ExtensionName] class.
For example, a GridView instance configured and bound to data is represented by the MVCxGridView class. The configured instance of the extension is the descendant of the corresponding DevExpress ASP.NET Web Forms control, so, the MVCxGridView class is the descendant of ASPxGridView.
To learn how to access MVCx[ExtensionName] objects, refer to the Declaring Server-Side Event Handlers topic (“Accessing the Wrapped ASP.NET Web Forms Control“ section).
Client-Side Structure of MVC Extensions
In addition to the server object model, the DevExpress ASP.NET MVC extensions offer an advanced client side API. The client-side API allows you to effectively manipulate the MVC extension using JS code. For example, you can expand and collapse NavBar’s groups programmatically on the client side or you can respond to end-user manipulations using the client-side events.
Client API Discoverability
Client side equivalents of server objects are named using the “ASPxClient“ or “MVCxClient“ prefix. For example, ASPxClientMenu for Menu, ASPxClientButton for Button, and MVCxClientGridView for GridView. Refer to the particular MVC extension overview to learn about the extension’s client-side counterpart.
Using the Client-Side API
An extension client object can be accessed on the client side using the extension name defined using the SettingsBase.Name property.
View code:
<script>
function setDefaultText() {
// The "myTextBox" object is the client instance of the NavBar extension.
myTextBox.SetText("This is the default text");
}
</script>
@Html.DevExpress().TextBox(settings =>
{
// The "myTextBox" name is used to access the TextBox client object on the client side.
settings.Name = "myTextBox";
}).GetHtml()
<br />
<input type="button" value="Set default text" name="setText" onclick="setDefaultText()" />
Declaring Client-Side Event Handlers
DevExpress MVC Extensions expose a number of client events, allowing you to promptly respond to end-user manipulations without the need for server-side processing.
Extension-specific client events can be accessed using the ClientSideEvents property. It is available through an extension setting object (such as GridViewSettings.ClientSideEvents) or, for data editors, through the Properties object related to a settings object (such as Properties.ClientSideEvents, which is TextBoxSettings.Properties.ClientSideEvents for TextBox).
The image below demonstrates how to access the Button’s client-side events.
The following code demonstrates how client events can be handled by implementing a separate function.
View code:
<script>
function onMyButtonClick() {
alert("Hello world");
}
</script>
@Html.DevExpress().Button(settings =>
{
settings.Name = "myButton";
settings.UseSubmitBehavior = false;
settings.ClientSideEvents.Click = "onMyButtonClick";
}).GetHtml()
Refer to the Client-Side API topic to learn more.
Using Callbacks
Certain DevExpress ASP.NET MVC extensions can work in callback mode by requesting the server via their own callbacks powered by the jQuery library. Callbacks are an efficient way to load/update extension content on demand (to minimize the initial data transfer) or to perform some lengthy functional operations (such as file uploads).
To use an extension in callback mode, in most cases you should do the following.
- Place the extension in the Partial View.
- Create a new Action within a Controller.
- Specify the names of the Controller and Action that will process the callback using a CallbackRouteValues property of an extension’s settings object.
To learn more about using callbacks with DevExpress ASP.NET MVC extensions, refer to the Using Callbacks and Passing Values to a Controller Action through Callbacks articles.