How It Works

Oct 29, 2020
8 minutes to read

This document covers the fundamentals of DevExpress ASP.NET MVC extensions.

Implementation Details
Server Object Model
Client Object Model
Enabling Callbacks

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
Passing a settings object to the extension method

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
Theme
Dimensions
Client-side events
Callback routing logic
Content templates
Data source fields
Collection of items
Appearance settings

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:

Razor

cshtml

<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()



<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:

Razor

cshtml

<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.