Telerik Extensions for ASP.NET MVC

Prerequisites

Before proceeding make sure you have all the required components installed. This topic assumes that Telerik Extensions for ASP.NET MVC have been integrated in your ASP.NET MVC application. Please check Using Telerik Extensions for ASP.NET MVC in your project for additional info.
Important
When registering Telerik web assets manually via the ScriptRegistrar or StyleSheetRegistrar, never add the "min" suffix manually - this is managed by the registrars, depending on whether the site is running in debug ("debug" suffix) or release mode ("min" suffix). Adding a suffix manually will result in its duplication and the generated URL will be invalid.

Creating web asset groups

Asset groups can be defined in various locations:

  • master page
  • view page
  • partial view
Note
JavaScript and CSS files which are commonly used should be registered as web asset groups in the master page file.

Let's define a web asset group for the commonly used JavaScript files. To do so paste the following code at the end of your master page file (before the closing </body> tag):

CopyDefining asset groups
<%= Html.Telerik().ScriptRegistrar().Scripts(scripts =>
            scripts.AddGroup("CommonScript", group => 
                group.Add("~/Scripts/Core.js")
                     .Add("~/Scripts/Stuff.js")
            )
         )
%>

That code defines a new web asset group called "CommonScript" and adds two JavaScript files to the group. If you run your web application you would see that both files are output in the result HTML. You would also notice that the jQuery script is also output despite you have not registered it with the ScriptRegistrar.

CopyScriptRegistrar output
<script type="text/javascript" src="/Scripts/jquery-1.4.2.js"></script>
<script type="text/javascript" src="/Scripts/Core.js"></script>
<script type="text/javascript" src="/Scripts/Stuff.js"></script>

Important
By default the jQuery script and the JavaScript files required by Telerik Extensions for ASP.NET MVC are included in the "default" web asset group. You can add files to that group too if you wish to later combine them with the jQuery JavaScript. Here is how:
CopyAdding scripts to the default asset group
<%= Html.Telerik().ScriptRegistrar().DefaultGroup(group =>
                group.Add("~/Scripts/Core.js")
                     .Add("~/Scripts/Stuff.js")
            )
%>

Disabling jQuery

In some scenarios you may need to disable the automatic registration of the jQuery JavaScript. To do so use the jQuery method:
CopyDisabling the automatic jQuery registration
<%= Html.Telerik().ScriptRegistrar().jQuery(false)
%>

Disabling jQuery validation scripts

By default, the jQuery validation JavaScript is registered automatically if needed, for example when using Grid editing. You may want to disable this registration, e.g. in order to register a different script version manually. To do so, use the jQueryValidation method:
CopyDisabling the automatic jQuery registration
<%= Html.Telerik().ScriptRegistrar().jQueryValidation(false)
%>

Web asset combination

In the previous section we have defined our first web asset group. However the registered JavaScript files were output as separate <script> tags. While there is nothing wrong with that when the number of JavaScript files increases so will the number of requests the web browser must make in order to download them. That's where script combination comes into play.

Note
Web asset combination must be enabled if you intend to use compression and caching.

Web asset combination relies on the WebAssetHttpHandler so the same should be registered in your ASP.NET MVC application.

Registering the asset HTTP handler

  1. Open the web.config file of your ASP.NET MVC application.
  2. Locate the <httpHandlers> tag within <system.web>
  3. Paste the following markup within the <httpHandlers> tag:
    CopyAsset HTTP handler registration for ASP.NET development server, IIS6 and IIS7 classic mode
    <add verb="GET,HEAD" path="asset.axd" validate="false" type="Telerik.Web.Mvc.WebAssetHttpHandler, Telerik.Web.Mvc"/>
    Note
    The <httpHandlers> tag is used when your ASP.NET MVC application is hosted in IIS6, IIS7 in classic mode or Visual Studio's built-in web server.
  4. Locate the <handlers> tag within <system.webServer>
  5. Paste the following markup within the <handlers> tag:
    CopyAsset HTTP handler registration for IIS7 integrated mode
    <add name="AssetHandler" preCondition="integratedMode" verb="GET,HEAD" path="asset.axd" type="Telerik.Web.Mvc.WebAssetHttpHandler, Telerik.Web.Mvc"/>
    Note
    The <handlers> tag is used when your ASP.NET MVC application is hosted in IIS7 integrated mode.

After successfully registering the HTTP handler we can enable combination for the asset group which we defined in the previous section by using the Combined()()()() method:

CopyCombining web assets
<%= Html.Telerik().ScriptRegistrar().Scripts(scripts =>
            scripts.AddGroup("CommonScript", group => 
                group.Add("~/Scripts/Core.js")
                     .Add("~/Scripts/Stuff.js")
                     .Combined(true)
            )
         )
%>

Now if you run the web application again you will see only a single <script> tag output for the asset group.

Caching web asset groups

To enable enable HTTP caching of your combined web asset group you should use the CacheDurationInDays()()()() method:
CopySpecifying cache duration for web assets
<%= Html.Telerik().ScriptRegistrar().Scripts(scripts =>
            scripts.AddGroup("CommonScript", group => 
                group.Add("~/Scripts/Core.js")
                     .Add("~/Scripts/Stuff.js")
                     .Combined(true)
                     .CacheDurationInDays(365)
            )
         )
%>
Note
Caching is always disabled when your application is in debug mode (<compilation debug="true">).

Once caching is configured, the asset group won't be requested until the set duration has expired. This is important, as any changes you make to the files will not take effect until then or until the user requests a "hard refresh" (Ctrl+F5 in most browsers).

You can use file name versioning in order to propagate changes immediately. Once you change the name of a file in the group its content will be re-requested by the clients. For example, rename "Core.js" to "Core-v1.js", "Core-v2.js", etc. when you introduce important changes.

Compressing web asset groups

To enable compression of your combined web asset group you should use the Compress()()()() method:

CopyCompressing web assets
<%= Html.Telerik().ScriptRegistrar().Scripts(scripts =>
            scripts.AddGroup("CommonScript", group => 
                group.Add("~/Scripts/Core.js")
                     .Add("~/Scripts/Stuff.js")
                     .Combined(true)
                     .CacheDurationInDays(365)
                     .Compress(true)
            )
         )
%>
Important
GZIP compression dramatically reduces the size of your web assets which in turn improves the loading time of web sites. It is highly recommended to enable GZIP compression for your web assets.

Content Delivery Network support

To distribute your web asset group via content delivery network you should use the ContentDeliveryNetworkUrl()()()() method:
CopyUsing custom CDN
<%= Html.Telerik().ScriptRegistrar().Scripts(scripts =>
            scripts.AddGroup("CommonScript", group => 
                group.Add("~/Scripts/Core.js")
                     .Add("~/Scripts/Stuff.js")
                     .Combined(true)
                     .CacheDurationInDays(365)
                     .Compress(true)
                     .ContentDeliveryNetworkUrl("http://mycdn.com/CommonScript.js")
            )
         )
%>

Using Different Web Assets in Release and Debug Mode

The ScriptRegistrar and StyleSheetRegistrar allow using different web assets in release and debug site mode.

For example, if the ScriptRegistrar must register an asset with a specified name of fileName.js, it will look for script files with names in the following order, when in debug mode:

  • fileName.debug.js
  • fileName.js
  • fileName.min.js

On the other hand, when in release mode, the ScriptRegistrar will look for script files with names in the following order:

  • fileName.min.js
  • fileName.js
  • fileName.debug.js

The debug and min file name parts should not be written explicitly in the ScriptRegistrar's declaration.

Similarly, the StyleSheetRegistrar looks for fileName.min.css and fileName.css.

Change default path for styles and scripts folder

To change default path of the styles folder, you should use DefaultPath(String) method:
CopyChanging default path of the styles DefaultGroup
<%= Html.Telerik().StyleSheetRegistrar()
        .DefaultGroup(group => group.DefaultPath("~/Content")
                                    .Add("Main.css"))
%>
To change default path of the scripts folder, you should use DefaultPath(String) method:
CopyChanging default path of the scripts DefaultGroup
<%= Html.Telerik().ScriptRegistrar()
        .DefaultGroup(group => group.DefaultPath("~/Scripts")
                                    .Add("Main.js"))
%>
Important
Note that DefaultPath() should be defined before any assets in the group.

Use the combined component JavaScript file

By default all components from Telerik Extensions for ASP.NET MVC register their required JavaScript files with the ScriptRegistrar. In some cases it is better to include a single file only that contains all JavaScript dependencies. That file is called telerik.all.js and you can enable it by setting the CombinedComponentFile setting to true:
CopyUsing the combined component JavaScript file
<%= Html.Telerik().ScriptRegistrar().CombinedComponentFile(true) %>
When you do this the ScriptRegistrar will include ony telerik.all.js. The jQuery and jQuery Validate JavaScript files would be included separately because they are not part of the combined telerik.all.js file.