Telerik Extensions for ASP.NET MVC

ASP.NET MVC 3.0 introduces the Razor view engine as an alternative to the WebForms engine. The Telerik Extensions for ASP.NET MVC offer native support for Razor starting with the 2009 Q3 Service Pack 1 release.

This help topic explains how to use the extensions with the Razor syntax and how it compares to the WebForms syntax. Please see the links at the end of the article for more information about the Razor view engine itself.

Note

All online examples are available in both Razor and WebForms syntax.

Importing namespaces

To make the Telerik Extensions for ASP.NET MVC namespace available to all pages in the application you need to edit the <system.web.webPages.razor> section in web.config:

CopyNamespace import in web.config
<system.web.webPages.razor>
<pages pageBaseType="System.Web.Mvc.WebViewPage">
    <namespaces>
        <add namespace="System.Web.Mvc" />
        <add namespace="System.Web.Mvc.Ajax" />
        <add namespace="System.Web.Mvc.Html" />
        <add namespace="System.Web.Routing" />

        <add namespace="Telerik.Web.Mvc.UI" />
    </namespaces>
</pages>
</system.web.webPages.razor>
Important

The namespaces imported in the <system.web><pages> section are not available in Razor views. They are only available for WebForms views.

You can also import namespaces to individual pages with the @using directive:

CopyNamespace import in view
@model Customer
@using Telerik.Web.Mvc.UI

@* ... *@

Declaring components

Components are typically declared using expressions - @( ... ).

The equivalent syntax in WebForms is <%= ... %>.

CopyDeclaring a Grid with multi-line expression
@(Html.Telerik().Grid(Model)
        .Name("Grid")
        .Columns(columns =>
        {
            columns.Bound(o => o.OrderID).Width(100);
            columns.Bound(o => o.Customer.ContactName).Width(200);
        })
)

You can skip the brackets if the component declaration fits on one line:

CopyDeclaring a Grid with single-line expression
@Html.Telerik().Grid(Model).Name("Grid")

Components can also be created by calling Render in a code block - @{ ... }.

The corresponding syntax in WebForms is <% ... %>.

CopyDeclaring a Grid with code block
@{Html.Telerik().Grid(Model)
        .Name("Grid")
        .Columns(columns =>
        {
            columns.Bound(o => o.OrderID).Width(100);
            columns.Bound(o => o.Customer.ContactName).Width(200);
        })
        .Render();
}

In contrast with expressions, single-line code blocks still require brackets:

CopyDeclaring a Grid with single-line code block
@{ Html.Telerik().Grid(Model).Name("Grid").Render(); }

Using templates

Templates are defined by wrapping the content in <text> tags.

CopyDeclaring a Menu template
@( Html.Telerik().Menu()
        .Name("Menu")
        .Items(menu => {
            menu.Add()
                .Text("Customer testmonials")
                .Content(
                    @<text>
                        Some text ...
                        <img    src="@Url.Content("~/Content/PanelBar/Templates/Testimonials.gif")"
                                alt="Testimonials" width="740" height="157" />
                    </text>);
        })
)

If the content consists of a single tag the <text> tags can be omitted.

CopyDeclaring a Menu template
@( Html.Telerik().Menu()
        .Name("Menu")
        .Items(menu => {
            menu.Add()
                .Text("Customer testmonials")
                .Content(
                    @<img src="@Url.Content("~/Content/PanelBar/Templates/Testimonials.gif")"
                          alt="Testimonials" width="740" height="157" />
                );
        })
)

Nested components

Templates can contain nested components, but there are limitations:

  • You can nest up to two levels deep.
  • Nested components must be declared using expressions. Using Render() will not work.
CopyDeclaring a Grid nested in DetailView
@( Html.Telerik().Grid(Model)
    .Name("Employees")
    .DetailView(detailView => detailView.Template(
        @<text>
            @(Html.Telerik().Grid(item.Orders)
                    .Name("Orders_" + item.EmployeeID)
            )
        </text>
    ))
)
Important

The item variable can be used to access the template data item.

If you need to nest componenets more than two levels deep you must use a helper. In this example the DetailView template of the innermost Grid is defined using a @helper:

CopyUsing a helper to define templates
@helper OrdersDetailViewTemplate(WebViewPage page, Order o)
{
    <text>
        @(Html.Telerik().Grid(o.Order_Details)
                .Name("OrderDetails_" + o.EmployeeID + "_" +  o.OrderID)
        )
    </text>
}

@( Html.Telerik().Grid(Model)
    .Name("Employees")
    .DetailView(detailView => detailView.Template(
        @<text>
            @(Html.Telerik().Grid(item.Orders)
                    .Name("Orders_" + item.EmployeeID)
                    .DetailView(ordersDetailView => ordersDetailView.Template(o => OrdersDetailViewTemplate(this, o)))
            )
        </text>
    ))
)
Note

Helpers are static methods and need a reference to the page and the data item to operate.

Client-side event handlers

Inline client-side event handlers must be wrapped in <text> tags.

CopyInline event handler
@(Html.Telerik().ScriptRegistrar()
    .OnDocumentReady(
    @<text>
        prettyPrint();
    </text>)
)

HTML Encoding

Markup is automatically encoded by the Razor view engine. You do not need to encode it manually or use Html.Encode

CopyEditor with value containing unencoded markup
@( Html.Telerik().Editor()
       .Name("editor")
       .Value(
            @<text> 
                <p>
                    Telerik Editor for ASP.NET MVC allows your users to edit HTML in a familiar,
                    user-friendly way.<br />
                </p>
            </text>
        )
)

You can disable the automatic encoding if you are certain that the content is safe for rendering.

CopyRendering raw markup
@Html.Raw((string)ViewData["value"])

See Also