The Microsoft AJAX Library Engine

The library is made of a few .js files downloaded to the client browser on demand. At a minimum, the core runtime script file is downloaded. All script files are incorporated as resources in the ASP.NET AJAX assembly-the System.Web.Extensions.dll file-and are extracted and injected in the client page as required by the page itself.

Adding the Microsoft AJAX library to a Web application makes JavaScript programming easier, and it automatically endows the client environment with a set of new and richer objects and object-oriented capabilities.

The Root Object of the Microsoft AJAX Library

Overall, JavaScript is an object-based language. (It’s not truly object-oriented because it doesn’t implement some of the required object-oriented concepts, such as true object inheritance.) The language features a set of built-in objects, including Function, Object, Boolean, Array, Number, and String. All intrinsic objects have a read-only property named prototype. You use the prototype property to provide a base set of functionality shared by any new instance of an object of that class. New functionality can be added to the class prototype inside of an application to extend and improve the capabilities of a given class. This is exactly what the Microsoft AJAX library does.

In the library (precisely, in the MicrosoftAjax.js file), all built-in JavaScript objects feature a richer prototype and incorporate new capabilities. For example, the library extends the JavaScript Function object with a set of methods to provide for delegates and callbacks. Here’s a brief snippet from (the debug version of) MicrosoftAjax.js that illustrates the point:

// Set the type name
Function.__typeName = 'Function'; 

// Define a callback
Function.createCallback = function Function$createCallback(method, context)
{
    var e = Function._validateParams(...);
    if (e) throw e;
    
    return function() {
        var l = arguments.length;
        if (l > 0) {
            var args = [];
            for (var i = 0; i < l; i++) {
                args[i] = arguments[i];
            }
            args[l] = context;
            return method.apply(this, args);
        }
        return method.call(this, context);
    }
} 

// Define a delegate (function pointer)
Function.createDelegate = function Function$createDelegate(
    instance, method)
{
    var e = Function._validateParams(...);
    if (e) throw e; 

    return function() {
        return method.apply(instance, arguments);
    }
}

The Function type is then associated with the Type property on the window object in the browser DOM:

window.Type = Function;

The window object is the top-level object in the JavaScript hierarchy and represents a browser window. The browser creates one window object when it opens an HTML page and additional window objects for each frame it encounters. You can access all window members by using the member name directly-that is, without prefixing it with a name that evaluates to the current window object. The window object features a number of predefined members, including the popular alert method and event object; in addition, new dynamic members can be defined on the fly.

The native Function object, referred through the nickname of Type, is extended with a number of object-oriented methods. This is accomplished by extending the prototype property that characterizes any JavaScript object. The following code shows how to add the getName method to all Microsoft AJAX library objects:

Type.prototype.getName = function Type$getName()
{
    if (arguments.length !== 0)
       throw Error.parameterCount();
    return (typeof(this.__typeName) === "undefined")
            ? "" : this.__typeName;
}

In this way, you can ask each JavaScript object to qualify itself in a reliable and precise way. In MicrosoftAjax.js, the Function object works in a way that resembles the following pseudo-class:

public class Function
{
   public static Object createCallback(Object method, Object context);
   public static Object createDelegate(Object instance, Object method);
    public static Object emptyFunction();
   public static Object emptyMethod();
   public static Object getRootNamespaces();
   public static Object isClass(Object type);
   public static Object isEnum(Object type);
   public static Object isFlags(Object type);
   public static Object isInterface(Object type);
   public static Object isNamespace(Object object);
   public static Object parse(Object typeName, Object ns);
   public static Object registerNamespace(Object namespacePath);

   public Object callBaseMethod(Object instance, Object name, Object args);
   public Object getBaseMethod(Object instance, Object name);
   public Object getBaseType();
   public Object getInterfaces();
   public Object getName();
   public Object implementsInterface(Object interfaceType);
   public Object inheritsFrom(Object parentType);
   public Object initializeBase(Object instance, Object baseArguments);
   public Object isImplementedBy(Object instance);
   public Object isInstanceOfType(Object instance);
   public Object registerClass(Object type, Object base, Object interface);
   public Object registerEnum(Object name, Object flags);
   public Object registerInterface(Object typeName);
   public Object resolveInheritance();
}

All methods added to the prototype will be “inherited” by any other function defined in the context of any library-powered application.

 

Other Top-Level Types

The Microsoft AJAX library contains code that defines new objects and extends existing JavaScript objects with additional functionality. Table 2-1 lists the main global objects defined in the library.

By simply adding a ScriptManager server control to an ASP.NET page, you gain the right to use any additional methods on native objects that are defined in the Microsoft AJAX library. For example, the following code will work just fine if you add such a control:

var s = "Dino";
alert(s.startsWith('D'));

The native JavaScript String object doesn’t feature either a startsWith or an endsWith method. However, the following code in Microsoft Client library does the trick:

String.prototype.endsWith = function String$endsWith(suffix) 
{
    var e = Function._validateParams(...);
    if (e) throw e;

    return (this.substr(this.length - suffix.length) === suffix);
}
String.prototype.startsWith = function String$startsWith(prefix)
{
    var e = Function._validateParams(...);
    if (e) throw e;

    return (this.substr(0, prefix.length) === prefix);
}

Type.registerNamespace("IntroAjax");

// Constructor
IntroAjax.Person = function IntroAjax$Person(firstName, lastName)
{
    IntroAjax.Person.initializeBase(this);
    this._firstName = firstName;
    this._lastName = lastName;
}

// Add a FirstName property to the class prototype
IntroAjax.Person.prototype.get_FirstName =
    function IntroAjax$Person$get_FirstName() {
        // Raise an error if the number of arguments doesn't match
        if (arguments.length !== 0)
           throw Error.parameterCount ();
        return this._firstName;
    }
IntroAjax.Person.prototype.set_FirstName =
    function IntroAjax$Person$set_FirstName(value) {
        // Automatic arguments validation
        var e = Function._validateParams(arguments,
                   [{name: "value", type: String}]);
        if (e)
           throw e;
        this._firstName = value;
    }

// Add a LastName property to the class prototype
IntroAjax.Person.prototype.get_LastName =
    function IntroAjax$Person$get_LastName() {
        if (arguments.length !== 0)
         throw Error.parameterCount();
        return this._lastName;
    }
IntroAjax.Person.prototype.set_LastName =
    function IntroAjax$Person$set_LastName(value) {
        var e = Function._validateParams(arguments,
                    [{name: "value", type: String}]);
        if (e)
           throw e;
        this._lastName = value;
    }

IntroAjax.Person.registerClass('IntroAjax.Person');

var p = new Person("Dino", "Esposito");
alert(Object.getTypeName(p));

Object.getTypeName = function Object$getTypeName(instance)
{
    var e = Function._validateParams( ... );
    if (e) throw e;

    return Object.getType(instance).getName();
}
Object.getType = function Object$getType(instance)
{
    var e = Function._validateParams( ... );
    if (e) throw e;

    var ctor = instance.constructor;
    if (!ctor || (typeof(ctor) !== "function") ||
        !ctor.__typeName || (ctor.__typeName === 'Object'))
    {
        return Object;
    }
    return ctor;
}

Type.prototype.getName = function Type$getName()
{
    if (arguments.length !== 0)
        throw Error.parameterCount();
    return (typeof(this.__typeName) === "undefined")
            ? "" : this.__typeName;
}

Object._typeName = 'Object';

var x = 1;
var y = "1";

alert(TextBox1.value);

alert(document.getElementById("TextBox1").value);

alert($get("TextBox1").value);

var $get = Sys.UI.DomElement.getElementById = function
           Sys$UI$DomElement$getElementById(id, element)
{
    var e = Function._validateParams( ... );
    if (e) throw e;

    if (!element)
        return document.getElementById(id);
    if (element.getElementById)
        return element.getElementById(id);

    var nodeQueue = [];
    var childNodes = element.childNodes;
    for (var i = 0; i < childNodes.length; i++)
    {
        var node = childNodes[i];
        if (node.nodeType == 1)
            nodeQueue[nodeQueue.length] = node;
    }

    while (nodeQueue.length) {
        node = nodeQueue.shift();
        if (node.id == id) {
            return node;
        }
        
       childNodes = node.childNodes;
       for (i = 0; i < childNodes.length; i++) {
           node = childNodes[i];
           if (node.nodeType == 1) {
               nodeQueue[nodeQueue.length] = node;
           }
       }
   }

   return null;
}

registerNamespace("IntroAjax");

// Closure: Constructor and members
IntroAjax.Person = function()
{
    var _firstName;
    var _lastName;
    this.get_FirstName = function() { return this._firstName; }
    this.get_LastName = function() { return this._lastName; }
}
IntroAjax.Person.registerClass('IntroAjax.Person');

registerNamespace("IntroAjax");

// Prototype: Constructor
IntroAjax.Person = function()
{
    // Ctor creates private fields
    this._firstName = "";
    this._lastName = "";
}
// Prototype: Members
IntroAjax.Person.prototype.get_FirstName = function() {
    return this._firstName;
}
IntroAjax.Person.prototype.get_LastName = function() {
    return this._lastName;
}

IntroAjax.Person.registerClass("IntroAjax.Person");

Type.registerNamespace("IntroAjax");
IntroAjax.Person = function IntroAjax$Person(firstName, lastName)
{
    this._firstName = firstName;
    this._lastName = lastName;
}

// Define the body of members
function IntroAjax$Person$ToString() {
   return this._lastName + ", " + this._firstName;
}
...

// Define the prototype of the class
IntroAjax.Person.prototype = {
    ToString: IntroAjax$Person$ToString,
    get_FirstName: IntroAjax$Person$get_FirstName,
    set_FirstName: IntroAjax$Person$set_FirstName,
    get_LastName: IntroAjax$Person$get_LastName,
    set_LastName: IntroAjax$Person$set_LastName
}

// Register the class
IntroAjax.Person.registerClass("IntroAjax.Person");

// Declare the class
IntroAjax.Citizen = function IntroAjax$Citizen(firstName, lastName, id)
{
   ...
}

// Define the prototype of the class
IntroAjax.Citizen.prototype = {
   ...
}

// Register the class
IntroAjax.Citizen.registerClass("IntroAjax.Citizen", IntroAjax.Person);

IntroAjax.Citizen = function IntroAjax$Citizen(firstName, lastName, id)
{
    IntroAjax.Citizen.initializeBase(this, [firstName, lastName]);
    this._id = id;
    this._address = "";
}

IntroAjax.Citizen.prototype =
{
    ToString:    IntroAjax$Citizen$ToString,
    get_ID:      IntroAjax$Citizen$get_ID,
    get_Address: IntroAjax$Citizen$get_Address,
    set_Address: IntroAjax$Citizen$set_Address
}

function IntroAjax$Citizen$ToString()
{
    var temp = IntroAjax.Citizen.callBaseMethod(this, 'ToString');
    temp += " [" + this._id + "]";
    return temp;
}

Type.registerNamespace("Sys"); 

Sys.IDisposable = function Sys$IDisposable()
{
    throw Error.notImplemented();
}

function Sys$IDisposable$dispose()
{
    throw Error.notImplemented();
}

Sys.IDisposable.prototype =
{
    dispose: Sys$IDisposable$dispose
}

Sys.IDisposable.registerInterface('Sys.IDisposable');

IntroAjax.Citizen.registerClass('IntroAjax.Citizen',
           IntroAjax.Person, Sys.IDisposable);

function IntroAjax$Citizen$dispose
{
   this._id = "";
   this._address = "";
}

IntroAjax.Citizen.prototype =
{
   dispose: IntroAjax$Citizen$dispose
   ...
}

Sys.Component.registerClass('Sys.Component', null,
Sys.IDisposable,
Sys.INotifyPropertyChange,
Sys.INotifyDisposing);

Core Components

The AJAX client library is made up of three main logical layers: JavaScript extensions, core framework classes, and user-interface (UI) framework classes. (See Figure 2-1.)

As mentioned in the previous sections, JavaScript extensions add new methods and capabilities to native JavaScript objects and enable registration methods to simulate object-oriented constructs such as classes, namespaces, inheritance, and interfaces. The UI framework includes base components to define client behaviors, controls, DOM elements, and input devices such as keyboard and mouse buttons. The UI framework also incorporates as private elements classes that provide the client object model for a couple of ASP.NET AJAX server controls, namely Timer and UpdateProgress. We’ll cover these controls in Chapter 4, “Partial Page Rendering.”

The core framework classes form a sort of base library that incorporates a set of commonly used classes for event handling, string manipulation, Web services, debugging, and network operations. As you saw earlier, the Microsoft AJAX library supports namespaces, so classes in the client library belong to a particular namespace. Most classes in the base framework layer of the library belong to the Sys namespace.

In the remainder of this chapter, we’ll take a look at the main functionality implemented in the Microsoft AJAX library, starting with the Application object.

Sys.Application = new Sys._Application();

The application object serves two main purposes: providing access to page components, and loading external script files registered with the page script manager. Note that each external script file registered with the script manager needs to place a notifyScriptLoaded call at the bottom of its source to notify the application of success.

Sys._Application.findComponent(id);
Sys._Application.findComponent(id, parent);

var $find = Sys.Application.findComponent;

When an ASP.NET AJAX page first loads up, the load event is fired for the client code to perform any required initialization. Note that the event refers to the page lifetime, not the application lifetime. So whenever a classic postback occurs, you receive a new load event. You don’t receive events for any AJAX-style postback. Likewise, the unload event is fired when the page is unloaded.

The load event occurs after an ASP.NET AJAX page has been loaded and initialized completely. For such a page, the load event is preferable to the browser’s onload for initialization purposes. Only when you get the Microsoft AJAX library load event, therefore, can you be sure that the page is ready for user interaction.

The unload event occurs just before the Microsoft AJAX library runtime releases the page and all of its resources. For the sake of the application’s stability, you should use this event instead of the browser’s onunload event for clean-up tasks.

The following code shows how to add handlers to the load and unload events via script:

Sys.Application.add_load(_pageLoadHandler);
Sys.Application.add_unload(_pageUnloadHandler);

You add this code to a ...