Telerik Extensions for ASP.NET MVC

With the release of ASP.NET MVC 2.0 a very powerful feature was introduced - display and edit templates. To get the basic idea of how templates work you can check the excellent series of blog posts by Brad Wilson here

Important

All Telerik UI components need a ScriptRegistrar component in order to output their JavaScript objects and register their JavaScript files. The ScriptRegistrar component should be defined *after* all other UI components in the page. If you create the components on the client-side and do not use the MVC extensions, you need to manually register all requried JavaScript files. For further information check this help topic (Step 4 - Register Scripts)

Important
Display and editor templates are NOT supported in ASP.NET MVC 1. Make sure you are using the right version of Telerik.Web.Mvc.dll.

Display Templates

Telerik Grid for ASP.NET MVC supports display templates with a few restrictions: To use a display template in Telerik Grid for ASP.NET MVC you can follow these steps:
  1. Create a folder named DisplayTemplates within your Views or Views/Shared folder. That is the default location for display templates in ASP.NET MVC.
  2. In this example we will be using a modified version of the Order object generated using Linq to SQL. We will provide display template for the Employee property. Let's add a partial view named Employee.ascx in the DisplayTemplates folder created in the previous step:
    CopyEmployee.ascx
    <%@ Control Language="C#" Inherits="System.Web.Mvc.ViewUserControl<Employee>" %>
    <%= Html.Encode(Model.FirstName) %> <%= Html.Encode(Model.LastName) %>
    The display template will show the full name of the Employee using the FirstName and LastName properties.
    Important
    In order to use display and editor templates with complex types (e.g. Employee) that complex type must be convertible from string. Use a TypeConverter to achieve the same:
    CopyTypeConverter
    [TypeConverter(typeof(EmployeeConverter))]
    public partial class Employee
    {
    }
    
    public class EmployeeConverter : TypeConverter
    {
        public override bool CanConvertFrom(ITypeDescriptorContext context, Type sourceType)
        {
            return (sourceType == typeof(string)) ? true : base.CanConvertFrom(context, sourceType);
        }
    }
  3. Finally decorate the required property of your model with the UIHintAttribute:
    CopySetting the UIHint attribute
    public class EditableOrder
    {
        // Employee.ascx will be used as display template
        [UIHint("Employee"), Required]
        public Employee Employee { get; set; }
        // Other properties omitted for brevity
    }
    Important
    The string supplied in the UIHintAttribute constructor must be the same as the name of the display template partial view without the ".ascx" extension e.g. Employee.ascx -> "Employee"

Editor Templates

Editor templates are supported with the following restriction:
  • In client-side binding scenarios (Ajax Binding or Web Service Binding) the editor template must render an HTML element whose name attribute is the same as the property name of the bound column.
To use an editor template in Telerik Grid for ASP.NET MVC you can follow these steps:
  1. Create a folder named EditorTemplates within your Views or Views/Shared folder. That is the default location for editor templates in ASP.NET MVC.
  2. In this example we will be using a modified version of the Order object generated using Linq to SQL. We will provide editor template for the Employee property - a dropdown list with listing all employees. Let's add a partial view named Employee.ascx in the EditorTemplates folder created in the previous step:
    CopyEmployee.ascx
    <%@ Control Language="C#" Inherits="System.Web.Mvc.ViewUserControl<Employee>" %>
    <%= Html.DropDownList(null /* the "name" should be null - proper "name"" attribute will be set by the runtime */, 
           new SelectList((IEnumerable) ViewData["employees"] /*a list of all employee names */, 
           "Id", "Name", Model.EmployeeID.ToString()))
    %>
    Important
    In order to use display and editor templates with complex types (e.g. Employee) that complex type must be convertible from string. Use a TypeConverter to achieve the same:
    CopyTypeConverter
    [TypeConverter(typeof(EmployeeConverter))]
    public partial class Employee
    {
    }
    
    public class EmployeeConverter : TypeConverter
    {
        public override bool CanConvertFrom(ITypeDescriptorContext context, Type sourceType)
        {
            return (sourceType == typeof(string)) ? true : base.CanConvertFrom(context, sourceType);
        }
    }
  3. In the action method populate a list with employee names which will be displayed by the dropdown list:
    CopyAction method
    public ActionResult Index()
    {
        ViewData["employees"] = new NorthwindDataContext()
                     .Employees
                      .Select(e => new 
                      { 
                           Id = e.EmployeeID, 
                           Name = e.FirstName + " " + e.LastName 
                      })
                      .OrderBy(e => e.Name);              
        // omitted for brevity
    }
  4. Decorate the required property of your model with the UIHintAttribute:
    CopySetting the UIHint attribute
    public class EditableOrder
    {
        // Employee.ascx will be used as display template
        [UIHint("Employee"), Required]
        public Employee Employee { get; set; }
        // Other properties omitted for brevity
    }
    Important
    The string supplied in the UIHintAttribute constructor must be the same as the name of the display template partial view without the ".ascx" extension e.g. Employee.ascx -> "Employee"
  5. Finally to get the value of the dropdown you can use the following code:
    CopySetting the UIHint attribute
    [AcceptVerbs(HttpVerbs.Post)]
    public ActionResult UpodateOrder(int id, int employee)
    {
        EditableOrder order = new EditableOrder
        {
          OrderID = id,
          Employee = new NorthwindDataContext().Employees.SingleOrDefault(e => e.EmployeeID == employee)
        };
    
        // Exclude Employee from the list of updated properties
        if (TryUpdateModel(order, null, null, new [] { "Employee" }))
        {
            // omitted for brevity
        }
        // omitted for brevity
    }