11.2. Installation

A number of Visual Studio 2010 project templates such as ASP.NET MVC 2 and ASP.NET web application projects include the Microsoft AJAX libraries out of the box. The libraries will, however, be maintained separately from Visual Studio/.NET 4.0, so to obtain the latest release, you will need to download it from http://ajax.codeplex.com/.

11.2.1. Adding Microsoft AJAX Libraries to Your Project

The easiest (but not necessarily best) way to include the Microsoft AJAX libraries in your project is to use the ASP.NET ScriptManager control on your page:

<asp:ScriptManager runat="Server" />

ScriptManager is a great little control that takes care of referencing Microsoft script files and helps you manage your own scripts. In previous versions, ScriptManager had a dark and not so secret flaw—it loaded all the Microsoft AJAX libraries, whether you needed them or not.

Downloading unnecessary stuff is always bad, so the latest version of ScriptManager included with VS2010 offers you finer control over which scripts are included by using the new MicrosoftAjaxMode setting.

MicrosoftAjaxMode has three different settings:

• Enabled (includes all the individual ASP.NET AJAX Framework JavaScript files; this is the default setting and mimics the behavior of previous releases)

• Explicit (you specify the script files to be imported)

• Disabled (Microsoft Ajax script features disabled and no script references added)

The following code shows how to use the ScriptManager control to import just the MicrosoftAjaxCore.js script:

<asp:ScriptManager ID="NewScriptManager"
    MicrosoftAjaxMode="Explicit"
    runat="server">
  <CompositeScript>
    <Scripts>
      <asp:ScriptReference Name="MicrosoftAjaxCore.js" />
    </Scripts>
  </CompositeScript>
</asp:ScriptManager>

It is important to remember that some scripts depend on other scripts when you use the Explicit mode, so you need to also include the dependent scripts. The dependencies between the script files are shown in a diagram at this URL: www.asp.net/ajaxlibrary/Ajax%20Script%20Loader.ashx.

The client script loader is an alternative to the ScriptManager control, and I think it's a better and cleaner platform-independent method. You'll use the client script loader in the rest of this chapter, so let's take a look at it now.

11.2.2. Client Script Loader

Using the client script loader is easy. Once you have downloaded the libraries and included them in your project, you need to reference the JavaScript file Start.js. The Start.js file contains the client script loader functionality that can reference all the other script files:

<script src="../Scripts/Start.js" type="text/javascript"></script>

Once you have referenced the client script loader, you can then use its methods to load other scripts with the Sys.require() method (the following code references the new dataView component that you will look at shortly):

Sys.require(Sys.components.dataView);

The client script loader loads scripts in a very efficient and parallelized manner, taking care of resolving dependencies and ensuring that scripts are loaded only once. It even supports lazy loading and working with third-party libraries.

11.2.2.1. Referencing jQuery Scripts

You can even use the client script loader to load the jQuery or jQuery validation scripts:

Sys.require(Sys.scripts.jQuery);

Table 11-1 shows some of the scripts/components you can load with the client script loader.

Note that each of these scripts has a .debug.js version and that the AJAX control toolkit now lives in the scripts/extended directory.

11.2.2.2. Specifying Script Directories

By default, the client script loader will load scripts from the same directory in which it is located, although you can modify it by specifying a new basePath property:

Sys.loader.basePath = "../MyLocation/";

You can also specify a separate directory for jQuery scripts to be loaded from:

Sys.scripts.jQuery.releaseUrl = "../jQuery/jquery-1.3.2.js";
Sys.scripts.jQuery.debugUrl = "../ jQuery /jquery-1.3.2.js ";

11.2.2.3. Loading Custom Scripts

You can also use the parallelization capabilities of the client script loader to load your own scripts with the loadScripts() method that accepts an array of script files to load:

Sys.loadScripts(["../AnnoyingTrailingCursor.js", "../Scripts/HorribleFlashingDiv.js"]);

11.2.2.4. Lazy Loading

A good use of the loadScripts() method is to load scripts only when they are needed (called lazy loading). For example, you might have a function that is rarely called, and instead of forcing all users to have to download it, you can load it only when you need to do so:

function btnHardlyEverClicked_click()
{
  Sys.loadScripts(["../Scripts/myFunction.js"], function() {
    myFunction();
  });
}

11.2.3. Ajax Libraries Now Hosted by Microsoft

The ASP.NET AJAX and jQuery libraries are now hosted by Microsoft's content delivery network (CDN). By using DNS trickery, script files can be served from a server local to the user, thus reducing download time and load on your server (not to mention your bandwidth bill).

The following code shows how to reference the CDN version of the scripts. (The URL, version 0911, will probably change when it's release, so for the most up-to-date information, please refer to www.asp.net/ajax/cdn/.)

<script src="ajax.microsoft.com/ajax/0911/start.js"></script>

11.2.4. ScriptManager EnableCdn

The ASP.NET ScriptManager control has a new Boolean property called EnableCdn that if set to true will serve scripts from the Microsoft CDN.