Get Started
- 4 minutes to read
This document describes the basic principles of the DevExpress ASP.NET MVC extensions.
Why “Extensions”?
We extended the standard HtmlHelper class with the DevExpress() method. The method returns the ExtensionsFactory object that allows you to add DevExpress ASP.NET MVC extensions to your application.
How to Declare
The ExtensionsFactory helper methods accept extension specific settings (an [ExtensionName]Settings object) as a parameter and return an [ExtensionName]Extension object. This object contains methods that allow you to bind the extension to data and insert the HTML code rendered by the extension into the page output.
For instance, to declare the NavBar extension, define the NavBarSettings object and pass it to the ExtensionsFactory.NavBar method as a parameter. The method returns the NavBarExtension object. Call the Bind(Object) method to bind the extension to the model, then call the GetHtml() method to render the extension HTML code.
@{
var nbSettings = new NavBarSettings();
// You should always specify the Name property.
nbSettings.Name = "nbDataBindingToModel";
nbSettings.AutoCollapse = true;
nbSettings.Width = Unit.Parse("100%");
Html.DevExpress().NavBar(nbSettings).Bind(Model).GetHtml()
}
Define Extension Settings
You can define the extension settings in the following ways (note that you should always specify the Name property):
Define settings in a delegate method.
@Html.DevExpress().TextBox( settings => { // Define the extension settings here. settings.Name = "textBox"; }).GetHtml()Define a settings object in a View and pass it to a helper method.
@{ var tbSettings = new TextBoxSettings(); // Define the extension settings here. tbSettings.Name = "textBox"; Html.DevExpress().TextBox(tbSettings).GetHtml(); }Define a settings object in a Controller and pass it to a helper method 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(); // Define the extension settings here. s.Name = "myTextBox"; ViewBag.MyTextBoxSettings = s; return View(); } } }@Html.DevExpress().TextBox(ViewBag.MyTextBoxSettings).GetHtml()
Bind an Extension to Data
Use the Bind or BindList method to bind a data-aware extension to a data source.
@Html.DevExpress().ListBox(settings => {
settings.Name = "lbModels";
// ...
}).BindList(Model).GetHtml()
Use data-source specific binding methods (for instance, BindToXML, BindToFolder) to bind an extensions to declarative data sources.
@Html.DevExpress().Menu( settings => {
settings.Name = "myMenu";
// ...
}).BindToSiteMap("~/App_Data/WorldCup2010.sitemap", false).GetHtml()
Refer to the following sections for more information on how to bind an extension to data: Data Binding, Binding Data Editors to Data.
How to Use Callbacks
Some DevExpress ASP.NET MVC extensions can work in callback mode.
To use an extension in callback mode, follow the steps below.
- Place an extension in a Partial View.
- Create a new action in a Controller.
- Use the CallbackRouteValues property to specify the Controller name and the action that handles the callbacks.
Refer to the following section for more information: Passing Values to a Controller Action through Callbacks.
Handle a Server Event
An [ExtensionName]Settings object contains properties that allow you to declare server-side event handlers.
The example below shows how to handle the server ItemDataBound event.
@Html.DevExpress().Menu(
settings => {
settings.Name = "myMenu";
settings.ItemDataBound = (sender, e) => {
var node = e.Item.DataItem as SiteMapNode;
if (node != null) {
if (node["title"] == "USA") {
e.Item.Text = string.Format("<b>{0}</b>", e.Item.Text);
}
}
};
}).BindToSiteMap("~/App_Data/WorldCup2010.sitemap", false).GetHtml()
In a server event handler, the sender parameter returns the configured instance of an extension denoted by the MVCx[ExtensionName] class.
Refer to the following section for more information on how to access MVCx[ExtensionName] objects: Accessing the Wrapped ASP.NET Web Forms Control.
Access an Extension on the Client
A client equivalent of a server object has the ASPxClient or MVCxClient prefix. Refer to the following topic for a list of client counterparts: Included Components.
Use the Settings.Name property value to access the client extension object.
@Html.DevExpress().TextBox(settings => {
settings.Name = "myTextBox";
}).GetHtml()
<input type="button" value="Set default text" name="setText" onclick="setDefaultText()" />
function setDefaultText() {
myTextBox.SetText("This is the default text");
}
Handle a Client Event
Use the ClientSideEvents property to access an extension’s client events. For data editors the property is available through the Settings.Properties property. For other extensions it is available directly through the Settings property.
@Html.DevExpress().Button(settings => {
settings.Name = "myButton";
settings.ClientSideEvents.Click = "onMyButtonClick";
}).GetHtml();
@Html.DevExpress().TextBox(settings => {
settings.Name = "textBox";
settings.Properties.ClientSideEvents.KeyPress= "onMyButtonClick";
}).GetHtml();
function onMyButtonClick() {
alert("Hello world");
}
Refer to the following section for more information: Client-Side API.