Ajax contorl toolkit ToolkitScriptManager Demonstration

You must add a ToolkitScriptManager control to any page that contains Ajax Control Toolkit controls. The ToolkitScriptManager performs two main functions.

First, the ToolkitScriptManager handles dependency resolution. The ToolkitScriptManager is responsible for loading all of the JavaScript files required by a set of Ajax Control Toolkit controls.

Second, the ToolkitScriptManager is responsible for optimizing JavaScript and files. The ToolkitScriptManager combines, minifies, compresses and caches JavaScript files so that they can be delivered more efficiently to the browser.

To take full advantage of the ToolkitScriptManager, and get the best performance out of a website that uses the Ajax Control Toolkit, you need to understand two features of the ToolkitScriptManager: the CombineScripts HTTP Handler and control bundles.

The ToolkitScriptManager caches all JavaScript files with a far future cache header. JavaScript files are cached for one year into the future. Caching with a far future cache header has a dramatic impact on performance because it means that scripts need to be downloaded only when someone first visits your website.

The ToolkitScriptManager serves the cached files with a version query string. If you change any of the cached JavaScript files then the version query string is changed and browsers will load the new versions of the files. All of this works automatically.

To take full advantage of caching, you should register the Ajax Control Toolkit CombineScripts HTTP Handler in your web.config file in both the <httpHandlers> and <system.webServer> sections of your root web.config file like this:

To make it easier to debug your scripts, Combining, minification, compression, and caching are enabled only in Release mode. You can enable Release mode in your web.config file by setting debug=”false” like this:

Alternatively, you can enable Release mode with the ToolkitScriptManager like this:

By default, the ToolkitScriptManager combines all of the scripts required by the entire Ajax Control Toolkit and -- after minifying and compressing the combined scripts -- serves the combined script to the browser. If you are using a subset of Ajax Control Toolkit controls in your web application then you might want to deliver only the scripts that you really need.

For example, if you only need to use the Ajax Control Toolkit Accordion extender in your web application then you might not want to include all of the JavaScript files required by other Ajax Control Toolkit controls such as the MaskedEdit and ToggleButton controls.

Or, your web application might be organized into different sections. You might want to use different subsets of the Ajax Control Toolkit controls on different pages.

You can control how the ToolkitScriptManager combines scripts by defining one or more control bundles. You define control bundles in a configuration file named AjaxControlTookit.config that you place in the root of your application. For example, the following AjaxControlToolkit.config file defines three control bundles:

The first control bundle includes the AccordionExtender, CalendarExtender, and HtmlEditorExtender controls. This bundle combines all of the JavaScript and Cascading Style Sheet files required by these three controls. Because this first control bundle does not have a name, it is the default control bundle.

You don’t need to do anything special to use the default bundle. If you declare a ToolkitScriptManager without specifying a control bundle then the default bundle is used automatically:

The second control bundle contains a single control. This bundle only contains the scripts and Cascading Style Sheet files required to use the Accordion extender. This second bundle has the name Group1. Here’s how you would use the Group1 control bundle with the ToolkitScriptManager:

Finally, the third control bundle includes both the Calendar extender and the HtmlEditor extender controls. This final bundle has the name Group2. Here’s how you would use the Group2 control bundle with the ToolkitScriptManager:

You can use control bundles with custom controls. When including a custom control in a bundle, you must also provide the name of the custom control’s assembly. For example, the following control bundle includes a custom control named AcmeHtmlEditor:

You can use <add> and <remove> elements in the AjaxControlToolkit.config file to exclude or include a particular JavaScript script from a control bundle. For example, imagine that you want to include Twitter Bootstrap in your control bundle. In that case, you can add the following <add> element to your AjaxControlToolkit.config file:

<ajaxControlToolkit>
 <scripts>
   <add name="MyApp.Scripts.bootstrap.js.bootstrap.js" 
       assembly="MyApp"/>
 </scripts> 
 
     ...
 
</ajaxControlToolkit>

In the code above, you should replace MyApp with the name of your Web Forms application.

To get this to work, you need to embed the bootstrap.js file in your Web Forms application's assembly. Open the Properties window for the bootstrap.js JavaScript file in your project and set its Build Action to the value Embedded Resource. Finally, add the following attribute to your Global.asax file:

[assembly: System.Web.UI.WebResource(
        "MyApp.Scripts.bootstrap.js.bootstrap.js", 
        "application/x-javascript")]
    

After you complete these steps, Twitter Bootstrap will be included in your JavaScript bundle (compressed, minified, bundled, and far future cached).

The ability to remove scripts from a control bundle is useful when you want to use your own version of jQuery with the Ajax Control Toolkit. To learn more about using jQuery with the Ajax Control Toolkit, read Using jQuery with the Ajax Control Toolkit

The ToolkitScriptManager uses four attributes to determine which scripts and Cascading Style Sheet files to load and combine. These attributes are server-side attributes applied to Ajax Control Toolkit controls:

• ClientScriptResource – This attribute represents a JavaScript file that has been embedded in an assembly.

• ClientCssResource – This attribute represents a Cascading Style Sheet file that has been embedded in an assembly.

• RequiredScript – This attribute loads all of the scripts required by a class or a control.

• ScriptCombine – This attribute can be used to prevent a JavaScript file from being combined with other JavaScript files.

For example, the Calendar extender control includes the following attributes:

When the ToolkitScriptManager loads the scripts required by the Calendar extender, it loads the scripts specified by the ClientScriptResource and RequiredScript attributes. In particular, it loads the Calendar.CalenderBehavior.js JavaScript file and all of the JavaScript files required by the CommonToolkitScripts, DateTimeScripts, PopupExtender, AnimationScripts, and ThreadingScripts classes.

Notice that the RequiredScript attribute accepts a number. This number represents the order in which the scripts are loaded.

If you want to create a custom control that works with the ToolkitScriptManager then you need to add these four attributes to your control.