Adding jQuery to an empty ASP.NET web project using ScriptManager control

Adding jQuery to a web form using the script block has some disadvantages. If the application is upgraded to use the latest version of jQuery, all the web forms with the <script> tag require to be changed. Secondly, switching from the uncompressed version in the development environment to the compressed version in the release environment should be handled manually and is hence error-prone. Using the ASP.NET ScriptManager control helps you overcome this problem. It can also load jQuery directly from CDN instead of using the local copy.

Getting ready

1. Create a new ASP.NET Web Application project using the Empty template by following the steps listed in the Adding jQuery to an empty ASP.NET web project using a script block recipe. Name the project WebApplication2 (or any other suitable name).
2. Follow the steps in the preceding recipe to add the jQuery library (the uncompressed and compressed formats) to the Scripts folder.
3. Follow the steps to add a new web form to the project.

How to do it…

Following are the steps to add jQuery to ASP.NET web project using the ScriptManager control:

1. Open the web form in the Design mode.
2. Launch the Toolbox. This can be done in two ways. From the File menu at the top of the page, go to View | Toolbox. Alternatively, use the shortcut keys, Ctrl + Alt + X.
3. Go to Toolbox | AJAX Extensions, and drag and drop the ScriptManager control onto the form:
   
4. Right-click on the project in the Solution Explorer tab, and go to Add | New Item.... From the dialog box, select Global Application Class. This will add the Global.asax file to the project:
   

   Note

   The Global.asax file is an optional file that resides in the root directory of the application and responds to events at the application and session levels, such as the starting and ending an application or session.

5. Open the Global.asax file and include the following namespace at the top of the page:

   For VB, the code is as follows:

   Imports System.Web.UI

   For C#, the code is as follows:

   using System.Web.UI;

6. In the Application_Start event in the Global.asax file, add the following code to create a script that maps to jQuery:

   For VB, the code is as follows:

   Sub Application_Start(ByVal sender As Object, ByVal e As EventArgs)
      ScriptManager.ScriptResourceMapping.AddDefinition("jquery", New ScriptResourceDefinition() With {
      .Path = "~/Scripts/jquery-2.1.4.min.js",
      .DebugPath = "~/Scripts/jquery-2.1.4.js",
      .CdnPath = "https://ajax.googleapis.com/ajax/libs/jquery/2.1.4/jquery.min.js",
      .CdnDebugPath = "https://ajax.googleapis.com/ajax/libs/jquery/2.1.4/jquery.js",
      .CdnSupportsSecureConnection = True,
      .LoadSuccessExpression = "window.jQuery"})
   End Sub

   For C#, the code is as follows:

   protected void Application_Start(object sender, EventArgs e)
   {            
      ScriptManager.ScriptResourceMapping.AddDefinition("jquery", new     ScriptResourceDefinition
      {
         Path = "~/Scripts/jquery-2.1.4.min.js",
         DebugPath = "~/Scripts/jquery-2.1.4.js",
         CdnPath = "https://ajax.googleapis.com/ajax/libs/jquery/2.1.4/jquery.min.js",
         CdnDebugPath = "https://ajax.googleapis.com/ajax/libs/jquery/2.1.4/jquery.js",
         CdnSupportsSecureConnection = true,
         LoadSuccessExpression = "window.jQuery"
       });
   }

7. Open the Default.aspx web form in the Source mode. Add the following ScriptReference to the ScriptManager control:

   <asp:ScriptManager ID="ScriptManager1" runat="server">
        <Scripts>
             <asp:ScriptReference Name="jquery"  />
        </Scripts>
   </asp:ScriptManager>

   Note

   When using the ScriptManager control to add a reference to the jQuery library, the jQuery code should be placed after the ScriptManager control, that is, after the jQuery reference has been declared; otherwise, the page will throw an error. It is also important to note that the ScriptManager control should reside inside the <form> element.

8. To retrieve the jQuery files from CDN, set the EnableCdn property of the ScriptManager control to true, as follows:

   <asp:ScriptManager ID="ScriptManager1" runat="server" EnableCdn="true">
        <Scripts>
             <asp:ScriptReference Name="jquery"  />
        </Scripts>
   </asp:ScriptManager>

How it works…

This is how the ScriptManager control works:

1. The ScriptManager control can be used to load JavaScript files, such as the jQuery library. This can be done by adding the ScriptReference to jQuery in the ScriptManager control, as follows:

   <asp:ScriptReference Name="jquery"  />

2. However, we require to define this mapping. This can be done in the Global.asax file using a ScriptResourceDefinition object, which exposes the following properties:

   Property	Description
   Path	This is the release path of the script resource
   DebugPath	This is the development/debug path of the script resource
   CdnPath	This is the release path of the script resource served from a CDN
   CdnDebugPath	This is the development/debug path of the script resource served from a CDN
   CdnSupportsSecureConnection	This indicates whether the HTTPS mode needs to be used to retrieve the resource when the page is accessed using a secure connection
   LoadSuccessExpression	This is the JavaScript expression that detects whether a JavaScript file has been loaded successfully

3. The ScriptResourceDefinition object defined in Global.asax is named jquery. The ScriptManager control uses the same name to load the reference on the web form.
4. In the development/debug mode, the script is served from DebugPath while in the release mode, it is served from Path.

   Tip

   Running in development/debug and release modes

   To run the application in the development/debug mode, set the debug attribute of the <compilation> element in the web.config to true as follows:

   <system.web>
       <compilation debug="true"/>
       …..
   </system.web>  

   When the debug attribute is set to false, the application will run in the release mode.

5. If EnableCdn is set to true, the script is served from the CDN path, that is, from CdnDebugPath in the development/debug mode and CdnPath in the release mode.
6. The LoadSuccessExpression property renders an inline script to load the library from the local path in the event of a CDN failure. By right-clicking on the web page and viewing the source, note that the ScriptManager control adds a fall back mechanism when the CDN is unavailable and files are served locally instead:
   

See also

The Adding jQuery to an empty ASP.NET web project using a script block recipe