Creating Custom Client Script in ASP.NET AJAX

Introduction

Microsoft ASP.NET AJAX provides features that help you create client script and integrate it into ASP.NET applications. This includes a type system and extensions to existing ECMAScript (JavaScript) objects to give them the richness of .NET Framework classes. It also provides the ScriptManager control to manage these script libraries and any custom script in your application.

Creating Scripts

The Microsoft AJAX Library includes features that contribute to a richer, more powerful JavaScript development experience.

The Type class adds object-oriented features such as classes and inheritance to JavaScript programming. Any JavaScript object that is registered by using the Type class automatically has access to this functionality. For more information, see Extending JavaScript with ASP.NET AJAX.

The following example shows how to use the Type class to create and register a namespace and a class in a JavaScript file:

cs

Type.registerNamespace("Demo");

Demo.Person = function(firstName, lastName, emailAddress) {
    this._firstName = firstName;
    this._lastName = lastName;
    this._emailAddress = emailAddress;
}

Demo.Person.prototype = {

    getFirstName: function() {
        return this._firstName;
    },

    getLastName: function() {
        return this._lastName;
    },

    getName: function() {
        return this._firstName + ' ' + this._lastName;
    },

    dispose: function() {
        alert('bye ' + this.getName());
    }
}
Demo.Person.registerClass('Demo.Person', null, Sys.IDisposable);

// Notify ScriptManager that this is the end of the script.
if (typeof(Sys) !== 'undefined') Sys.Application.notifyScriptLoaded();

Extensions to JavaScript base types provide additional functionality for those types. For more information about these extensions, see the following topics:

• Array Type Extensions

• Boolean Type Extensions

• Date Type Extensions

• Error Type Extensions

• Number Type Extensions

• Object Type Extensions

• String Type Extensions

The Sys.Debug class provides extensive debugging capabilities. For more information, see ASP.NET AJAX Debugging and Tracing Overview and the Sys.Debug class overview.

Component developers can create debug and retail versions of script files that are automatically managed by the ScriptManager control. You can identify debug versions of script files by including ".debug" as part of the script file name. For example, the following script file names identify retail and debug versions of a file:

• Retail: MyScript.js

• Debug: MyScript.debug.js

Integrating Client Script into ASP.NET Web Applications

Any ASP.NET Web page can access a script file by referring to it in a <script> block, as in the following example:

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

However, a script invoked in this manner cannot participate in partial-page rendering or access certain components of the Microsoft AJAX Library. To make a script file available for partial-page rendering in an ASP.NET AJAX Web application, the script must be registered with the ScriptManager control on the page. To register a script file, create a ScriptReference object that points to the file question and that adds it to the Scripts collection. The following example shows how to do this in markup:

<asp:ScriptManager ID="SMgr" runat="server">
  <Scripts>
    <asp:ScriptReference path="MyScript.js" />
  </Scripts>
</asp:ScriptManager> 

For script files to be processed correctly by the ScriptManager control, each file must include a call to the Sys.Application.notifyScriptLoaded method at the end of the file. This call notifies the application that the file has finished loading. The following example shows the code to use for this purpose:

if (typeof(Sys) !== 'undefined') Sys.Application.notifyScriptLoaded();

If your script is embedded in an assembly, you do not have to include a notification statement in the script. You also do not have to specify a path attribute in the script reference. However, you must provide the name of the assembly without the file name extension, as shown in the following example:

<asp:ScriptManager ID="SMgr" runat="server">
  <Scripts>
    <asp:ScriptReference 
        Name="MyScript.js" Assembly="MyScriptAssembly"/>
  </Scripts>
</asp:ScriptManager> 

You can also register scripts programmatically by creating script references in code and then adding them to the Scripts collection. For more information, see Dynamically Assigning ASP.NET AJAX Script References.

You can register scripts that are required for partial-page updates by using the registration methods of the ScriptManager control. You can use these methods in the following ways:

• To generate client script in code, build a block of script as a string and pass it to the RegisterClientScriptBlock) method.

• To add standalone script files that have no Microsoft AJAX Library dependencies, use the RegisterClientScriptInclude) method. 

• To add script files that are embedded in an assembly, use the RegisterClientScriptResource method.

  note

  Scripts that are registered by using these methods do not have localization support.

For a complete list of script-registration methods and their uses, see the ScriptManager control overview.

Any script blocks or inline script that you are registering must be inside the page's <form> element. Otherwise, the script is not registered with the ScriptManager control and cannot access ASP.NET AJAX functionality. For more information, see initialize Method.