Combining Client Scripts into a Composite Script

Modified on 2011/07/02 03:51 by ASPNET — Categorized as: Uncategorized

In an ASP.NET AJAX application, the client behavior of controls is defined by using JavaScript files. Typically, a single JavaScript file defines the client behavior for a single control. If a Web page contains several controls, the browser must download several JavaScript files. The time it takes to download a single file is minimal. However, when a Web page contains many controls, the time that is required to download multiple files can affect the perceived performance of the page.

A solution is to combine multiple JavaScript files into a single file, referred to as a composite script. This reduces the number of browser requests. The result is faster download times for the user and less load on the Web server.

ASP.NET AJAX enables you to combine multiple JavaScript files into a single composite script by using composite script references in the ScriptManager control or ScriptManagerProxy control. If scripts involve dependencies, such as scripts that call functions in other scripts, you must manage the scripts so that they are registered in the appropriate order.

If the browser supports script compression, a composite script will be automatically compressed before it is sent to the browser. The only exception is Microsoft Internet Explorer 6.0, to which ASP.NET always sends the scripts uncompressed.

Creating a Composite Script

In an ASP.NET AJAX application, you can create a composite script automatically by using the ScriptManager control. To combine scripts, add the CompositeScript element and list the script references in the order that you want them included in the composite script.

The following example shows how to combine client scripts by using a ComposteScript element in the ScriptManager control. When the user clicks one of the buttons, a function in the composite script is called and the corresponding span element is updated. 
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title>Combining Scripts</title>
</head>
<body>
    <form id="form1" runat="server">
    <asp:ScriptManager ID="ScriptManager1" runat="server">
		<CompositeScript>
			<Scripts>
				<asp:ScriptReference Path="~/Scripts/Script1.js" />
				<asp:ScriptReference Path="~/Scripts/Script2.js" />
				<asp:ScriptReference Path="~/Scripts/Script3.js" />
			</Scripts>
		</CompositeScript>
	</asp:ScriptManager>
    <h2>Combining Scripts</h2>
    <p>This example shows how to combine multiple client scripts into
    a single composite script.</p>
    <div>
		<input id="Button1" type="button" value="Button 1" onclick="buttonClick1()" />
		<span id="Span1"></span><br /><br />
		<input id="Button2" type="button" value="Button 2" onclick="buttonClick2()" />
		<span id="Span2"></span><br /><br />
		<input id="Button3" type="button" value="Button 3" onclick="buttonClick3()" />
		<span id="Span3"></span>
    </div>
    </form>
</body>
</html>


To keep this example simple, the following scripts are almost identical. Each script finds the span element and writes a short message. 
function buttonClick1()
{
	var text = Sys.UI.DomElement.getElementById("Span1");
	text.innerHTML = "You clicked Button 1. (Script1)";
}
 
function buttonClick2()
{
	var text = Sys.UI.DomElement.getElementById("Span2");
	text.innerHTML = "You clicked Button 2. (Script2)";
}

function buttonClick3()
{
	var text = Sys.UI.DomElement.getElementById("Span3");
	text.innerHTML = "You clicked Button 3. (Script3)";
}

Sources for Composite Scripts

A composite script can contain script references that are based on a local path or that reference an assembly. Local path-based script references are identified with the Path attribute of the ScriptReference element. Assembly-based references are identified with the Name attribute. You cannot use a local script reference that references a script that is not on the server (that is, that references a network path).

A composite script cannot contain other composite scripts. It does not have to contain all the scripts that are used on the Web page. However, it can contain ASP.NET AJAX framework scripts, such as MicrosoftAjax.js.

The following example shows a composite script that combines a framework script, a local path-based script, and multiple assembly-based extender scripts. 
<asp:ScriptManager id="SM1" runat="server">
    <CompositeScript>
      <Scripts>
        <asp:ScriptReference Name="MicrosoftAjax.js"/>
        <asp:ScriptReference Name="Custom.Extender.1.js" 
             Assembly="Custom" />
        <asp:ScriptReference Path="Scripts/Custom2.js" />
        <asp:ScriptReference Name="Custom.Extender.2.js" 
             Assembly="Custom" />
        <asp:ScriptReference Name="Custom.Extender.3.js" 
             Assembly="Custom" />
      </Scripts>
    </CompositeScript>
</asp:ScriptManager>

In the previous example, the ScriptManager control downloads a composite script, which contains the following individual scripts in the order shown:
The ScriptPath attribute of the ScriptManager control applies to the individual scripts that are enclosed in group, but not to the resulting composite script. The script path for the composite script is defined by using the Path attribute in the CompositeScript element.

Assigning a File Name to a Composite Script

You can optionally assign a file name to a composite script by adding the Path attribute to the CompositeScript element, as shown in the following example: 
 
<asp:CompositeScript Path="~/Scripts/MyCompositeScript.js">

Note:

Do not use a comma (,) or a pipe character (|) in the script name.

Modifying Script References Dynamically

Script combining occurs after the ResolveScriptReference event has been raised. This means that you can write an event handler to modify the script references. However, you cannot modify the order in which the scripts are registered.

Sharing Composite Scripts Between Pages

To share a composite script among multiple pages and to avoid multiple downloads, you can add the composite script to a master page. Similarly, you can use themes to define a script combination.

Combining Localized Scripts

If the EnableScriptLocalization property is set to true (which is the default), the framework combines the localized versions of the scripts if they are available. The localized scripts are combined in the same order and using the same model as the original versions.

Using Composite Scripts with the UpdatePanel Control

You can create a composite script that includes scripts from controls or custom components in an UpdatePanel control. During the asynchronous postback of an UpdatePanel control, a control might try to register a script that was previously downloaded as part of the composite script. In that case, the framework removes the single script reference and replaces it with a reference to the previously downloaded composite script.

The following example shows a composite script reference that supports a custom component defined in an UpdatePanel control. 
<asp:ScriptManager id="SM1" runat="server">
    <CompositeScript>
      <Scripts>
        <asp:ScriptReference Name="MicrosoftAjax.js"/>
        <asp:ScriptReference Name="Custom.Extender.1.js" 
             Assembly="Custom" />
        <asp:ScriptReference Path="~/Scripts/Custom2.js" />
        <asp:ScriptReference Name="Custom.Extender.2.js" 
             Assembly="Custom" />
        <asp:ScriptReference Name="Custom.Extender.3.js" 
             Assembly="Custom" />
        <asp:ScriptReference Name="Custom.Extender.4.js" 
             Assembly="Custom" />
      </Scripts>
    </CompositeScript>
</asp:ScriptManager>

<asp:UpdatePanel runat="server"...>
  <ContentTemplate>
    ...
    <cc:custom4 runat="server" id="cc4"... />
    ...
  </ContentTemplate>
</asp:UpdatePanel>