Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Expand]WinForms Controls
[Collapse]ASP.NET Controls and MVC Extensions
 [Expand]Prerequisites
 [Expand]What's Installed
 [Expand]Common Concepts
 [Expand]ASP.NET WebForms Controls
 [Collapse]ASP.NET MVC Extensions
  [Expand]Product Information
  [Collapse]Getting Started
   [Expand]Integration into an ASP.NET MVC Project
    How It Works
  [Expand]Common Concepts
  [Expand]Grid View
  [Expand]Card View
  [Expand]Vertical Grid
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]HTML Editor
  [Expand]Image and Data Browsing
  [Expand]Docking and Popups
  [Expand]Navigation and Layout Extensions
  [Expand]File Management
  [Expand]Multi-Use Site Extensions
  [Expand]Charts
  [Expand]Pivot Grid
  [Expand]Scheduler
  [Expand]Tree List
  [Expand]Data Editor Extensions
  [Expand]Report Extensions
  [Expand]SpellChecker
 [Expand]Localization
 [Expand]Redistribution and Deployment
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

How It Works

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

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

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

    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.

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.

Expanded 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 WebForms 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 WebForms Control" section).

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

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:

Refer to the Client-Side API topic to learn more.

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

  1. Place the extension in the Partial View.
  2. Create a new Action within a Controller.
  3. 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.

Expanded See Also

How would you rate this topic?​​​​​​​