Building Client-Side ASP.NET AJAX Controls

Registering a Control Namespace

When creating custom client-side controls, you’ll want to define a namespace for each control to resolve any possible naming conflicts that may arise in an application. The AlbumViewer control is placed in a Wrox.ASPAJAX.Samples namespace and registered by using the Type class’s registerNamespace() function. Namespaces can contain other nested namespaces, classes, interfaces, enumerations, and even delegates and should be defined at the beginning of a control’s code:

Type.registerNamespace("Wrox.ASPAJAX.Samples");

Note that no End Namespace keywords (as in VB.NET) or start and end brackets (as in C#) are used to define where an ASP.NET AJAX client-side namespace starts and ends. Instead, the namespace is referenced directly by a given control, as shown next.

Creating a Control Constructor

Once the namespace for a control is registered using the Type class, the control itself can be defined using the JavaScript "function" keyword. This is done by prefixing the control’s name with the names-pace that it should be placed in and defining an anonymous JavaScript function as shown in Listing 11-1.

Listing 11-1

Type.registerNamespace("Wrox.ASPJAX.Samples");

Wrox.ASPAJAX.Samples.AlbumViewer = function(element) {
    // Initialize base class
    Wrox.ASPAJAX.Samples.AlbumViewer.initializeBase(this,[element]);
    this._AlbumDivOverCssClass = null;
    this._AlbumDivOutCssClass = null;
    this._AlbumTitleCssClass = null;
    this._AlbumArtistCssClass = null;
    this._SongTitleCssClass = null;
    this._Albums = [];
    this._ServicePath = null;
    this._ServiceMethod = null;
    this._StatusLabel = null;
    this._ShowSearchBox = false;
    this._albumContainer = null;

    //Delegate definitions
    this._overHandler = null;
    this._outHandler = null;
    this._clickHandler = null;
    this._btnClickHandler = null;
    this._propertyChanged = null;
}   

The code in Listing 11-1 associates the namespace of Wrox.ASPAJAX.Samples with the AlbumViewer control and creates a constructor for the control by defining a new anonymous JavaScript function. Like VB.NET and C# constructors, JavaScript constructors can accept initialization parameters. The AlbumViewer constructor shown in Listing 11-1 accepts a DOM element object representing the parent container that the control will use. The AlbumViewer control uses a div DOM element as its parent container.

The first line of code inside of the AlbumViewer control’s constructor makes a call to the Type class’s initializeBase() method (recall that all controls are considered types and have access to the Type class’s methods) to initialize the control’s base class. Because the AlbumViewer control is a visual control that adds content to a div element, it inherits from the Sys.UI.Control base class provided by the ASP.NET AJAX script library. The call to initializeBase() instantiates the Sys.UI.Control class. You’ll learn more about how the AlbumViewer class inherits from Sys.UI.Control later in the chapter.

The initializeBase() method accepts two parameters. The first parameter represents the object instance to initialize the base class for (the AlbumViewer control, in this case). You’ll normally use the JavaScript this keyword for the parameter value. The second parameter accepts an array, which is why the [ and ] characters are used, that can be passed to the base constructor as it initializes. Listing 11-1 passes the container element of the AlbumViewer control as the parameter value. Because the control uses a div element as its container, the div is passed directly to the base class’s constructor.

Once the base class has been initialized, fields used by the AlbumViewer control are defined. Each field is prefixed with the this keyword, which represents the current class (the this keyword is much like the Me keyword VB.NET developers use and analogous to the this keyword in C#). Because the fields shown in Listing 11-1 are private, their names are prefixed by the underscore character. This character isn’t required and has no actual significance; it is a standard naming convention used in the ASP.NET AJAX script library for private members of a class. As a general rule, all object and array fields used by a control should be defined in the control’s constructor so that the field instances are unique to all control instances and not shared across instances.

The AlbumViewer class defines several fields in its constructor such as this._AlbumTitleCssClass and this._AlbumArtistCssClass that are used to store the CSS class applied to various child elements within the control. It also defines an array named this._Albums using the shortcut []JSON notation. this._Albums is used to store album information used by the control. Other fields such as this._ServicePath and this._ServiceMethod are used to store information about the web service that provides album, artist, and song information to the control. The handler fields shown (this._overHandler, this._outHandler, and so on) represent delegates used by the control that route data from events to event handlers.

Using the Prototype Design Pattern with JSON

JavaScript has long supported the ability to extend objects by using the prototype property. By using it, JavaScript objects can inherit from base types and add additional properties and methods. The ASP.NET AJAX Library uses the prototype property and a pattern referred to as the “prototype design pattern” to extend existing objects and create new ones. Listing 11-2 shows how the prototype property can be used to define a Person object and expose two property getters and setters, as well as a method.

Listing 11-2

function Person() {
    this._FirstName = null;
    this._LastName = null;
}

Person.prototype.get_FirstName = function() {
      return this._FirstName;
}

Person.prototype.set_FirstName = function(value) {
      this._FirstName = value;
}

Person.prototype.get_LastName = function() {
      return this._LastName;
}

Person.prototype.set_LastName = function(value) {
      this._LastName = value;
}
Person.prototype.getFullName = function() {
      return this._FirstName + " " + this._LastName;
}

Usually, there is a one-to-one relationship between a prototype property and a function definition, as shown in Listing 11-2. If four methods need to be added to a custom control, the prototype property is used four times. An exception to this rule would be for objects that define their properties and methods directly in the constructor, which is not a practice followed by the ASP.NET AJAX script library. Properties and methods added directly into the constructor get duplicated each time a new object instance is created. However, by using the prototype property, properties and methods are shared across multiple object instances resulting in less bloat.

Although the code shown in Listing 11-2 is fairly standard, ASP.NET AJAX client-side controls use the prototype design pattern with JSON notation to define properties and methods rather than using the prototype property for each property or method. Listing 11-3 shows how the Person class shown in Listing 11-2 can be refactored using the prototype design pattern with JSON. As you look through the code, notice that all properties and methods are wrapped within a single prototype statement. Property and method names are following by a colon that separates the name from the actual functionality. Each property and method is then separated by a comma.

Listing 11-3

function Person() {
    this._FirstName = null;
    this._LastName = null;
}

Person.prototype = {
    get_FirstName: function() {
       return this._FirstName;
    },

    set_FirstName: function(value) {
       this._FirstName = value;
    },

    get_LastName: function() {
       return this._LastName;
    },

    set_LastName: function(value) {
       this._LastName = value;
    },

    getFullName: function() {
       return this._FirstName + " " + this._LastName;
    }
}

The functionality for a property or method can also be defined in a separate location rather than inline, as shown in Listing 11-4. The ASP.NET AJAX script library uses this technique quite frequently to define client-side classes.

Listing 11-4

function Person() {
    this._FirstName = null;
    this._LastName = null;
}

Person.prototype = {
    get_FirstName: Person$get_FirstName,

    set_FirstName: Person$set_FirstName,

    get_LastName: Person$get_LastName,

    set_LastName: Person$set_LastName,

    getFullName: Person$getFullName
}

function Person$get_FirstName() {
    return this._FirstName;
}

function Person$set_FirstName(value) {
    this._FirstName = value;
}

function Person$get_LastName() {
    return this._LastName;
}

function Person$set_LastName(value) {
    this._LastName = value;
}

function Person$getFullName() {
    return this._FirstName + " " + this._LastName;
}

Now that you’ve seen the fundamentals of building constructors and using the prototype design pattern, let’s take a look at some of the properties defined in the AlbumViewer control.

Initializing a Control and Handling Events

The Sys.Component class mentioned earlier defines an initialize() method that’s useful when a control is first initialized. When initialize() is called, a property named isInitialized is set to true by Sys.Component through a call to set_isInitialized(). This property is referenced by other classes in the ASP.NET AJAX script library such as Sys.UI.Behavior to determine if a control has been initialized or not.

Custom controls such as the AlbumViewer control can override the initialize() method and use it to initialize a base class, initialize properties or field values, define delegates, and hook events to event han-dlers. The AlbumViewer control defines the initialize() method within the prototype section of the code shown in Listing 11-6.

Listing 11-6

Wrox.ASPAJAX.Samples.AlbumViewer.prototype = {

    //Property definitions go here

    initialize : function() {
        var e = this.get_element();
        e.style.className = this.get_AlbumDivOutCssClass();

        //Initialize Delegates
        this._overHandler = Function.createDelegate(this, this._onMouseOver);
        this._outHandler = Function.createDelegate(this, this._onMouseOut);
        this._clickHandler = Function.createDelegate(this, this._onClick);   
        this._btnClickHandler = Function.createDelegate(this,this._onButtonClick); 
        this._propertyChanged = 
          Function.createDelegate(this,this._onPropertyChanged);
        this.add_propertyChanged(this._propertyChanged);

        //Create search text box
        if (this._ShowSearchBox) {
            var lblText = document.createElement("SPAN");
            lblText.style.cssText = "font-family:arial;font-weight:bold;" +
              "font-size:8pt;";
            lblText.innerHTML = "Album Name: ";

            var txtAlbum = document.createElement("INPUT");
            txtAlbum.setAttribute("type","text");
            txtAlbum.setAttribute("id",e.id + "_txtAlbumSearch");
            txtAlbum.style.cssText = "width:150px;";

            var btnAlbumSearch = document.createElement("INPUT");
            btnAlbumSearch.setAttribute("type","button");
            btnAlbumSearch.id = e.id + "_btnAlbumSearch";
            btnAlbumSearch.value = "Search";
            $addHandler(btnAlbumSearch,"click",this._btnClickHandler);

            e.appendChild(lblText);
            e.appendChild(txtAlbum);
            e.appendChild(btnAlbumSearch);
            e.appendChild(document.createElement("P"));        
        }

        //Create div that will hold albums
        this._albumContainer = document.createElement("DIV");
        this._albumContainer.id = e.id + "_AlbumContainer";      
        e.appendChild(this._albumContainer); 

        Wrox.ASPAJAX.Samples.AlbumViewer.callBaseMethod(this, 'initialize'); 

        //Bind data if albums have been assigned
        if (this._ServicePath && this._ServiceMethod) {                    
            // Call the web service
            this._invokeWebService(null);
        } else if (this._Albums != null) {
            this.set_data(this._Albums);
        }
    },

    //Additional methods go here
}

When the AlbumViewer control’s initialize() method is called, several tasks are performed. First, a reference to the DOM element used by the control is made by calling get_element(). The element property is inherited from Sys.UI.Control and is referenced any time the AlbumViewer control needs to access the DOM element container. Once the DOM element is accessed, the CSS class to apply to the element is assigned by reading from the AlbumDivOutCssClass property. This class defines the overall style applied to the control’s parent container.

Next, several delegates are created that point to various event handler methods. Delegates in ASP.NET AJAX client-side controls perform the same overall function as delegates used in VB.NET or C#: They pass data raised by an event to an event handler. Client-side delegates are created by calling the Function class’s createDelegate() method and passing the object context that the delegate applies to, as well as the name of the event handler method that the delegate should direct data to. The delegates created in the AlbumViewer control are used to route data when mouseover, mouseout, click, and propertychanged events are raised.

The delegate instances returned from calling Function.createDelegate() are assigned to private fields defined in the control’s constructor because several of them are reused throughout the control and need to be globally accessible. For example, the following code creates a delegate that is responsible for routing mouseover event data to an event handler named _onMouseOver. A reference to the delegate is stored in the this._overHandler field.

this._overHandler = Function.createDelegate(this, this._onMouseOver);

Property changed events raised by the AlbumViewer control are routed to an event handler by calling the add_propertyChanged() method. This method routes data raised when the raisePropertyChanged() method discussed earlier is called to an event handler so that the change can be handled by the control. It accepts the name of the event handler method to call or a delegate instance that points to the method.

Once a delegate is created, it can be used to hook an event directly to an event handler using the ASP.NET AJAX $addHandler method. VB.NET developers will be quite comfortable using the $addHandler() method, as it’s similar in functionality to the VB.NET AddHandler keyword. $addHandler() is a shortcut to the Sys.UI.DomEvent class’s addHandler() method. It accepts several parameters, including the object that raises the event, the name of the event that will be raised, and the delegate that should be used to route event data to an event handler. Listing 11-6 contains an example of using the $addHandler method to hook up a button control’s click event to a delegate named this._btnClickHandler:

//Define Delegate
this._btnClickHandler = 
    Function.createDelegate(this,this._onButtonClick);

//Hook button's click event
$addHandler(btnAlbumSearch,"click",this._btnClickHandler);

In addition to $addHandler(), the ASP.NET AJAX script library provides an $addHandlers() method that allows multiple event handlers to be defined for a DOM element with a single statement. For example, if you need to attach the mouseover, mouseout, and click events of a DOM element named albumDiv to event handlers, you could use $addHandlers() in the following way:

$addHandlers(albumDiv, 
   {"mouseover" : this._overHandler,
    "mouseout" : this._outHandler,
    "click" : this._clickHandler },
  this);

The second parameter passed to $addHandlers is a JSON object containing the different event names and related delegates that should be attached to the DOM element.

The initialize() method shown in Listing 11-6 is also used to add several controls into the AlbumViewer control’s parent container element. Because album data is being displayed, an end user may want to search for one or more albums based upon title. Searching is controlled by data stored in the this._ShowTextBox field of the control. When the field value is true, a span tag, textbox, and but-ton are added to the AlbumViewer control’s div container. End users can then use the controls to perform a search. Adding controls is accomplished by calling document.createElement() and passing in the name of the element object that should be created. Once element objects are created, they’re added to the appropriate parent container by calling its appendChild() method.

The final two tasks performed by the AlbumViewer control’s initialize() method are calling the base Sys.UI.Control class’s initialize() method and binding album data to the control. The Type class’s callBaseMethod() method calls the initialize() method of the base class. This method accepts the current object instance as well as the name of the method to call on the base class. Although not used by the AlbumViewer control, callBaseMethod() returns a reference to the base class’s ini tialize() method.

Now that you’ve been exposed to the initialize() method, let’s move on to a few other methods used by the AlbumViewer control to bind data, call web services, and perform additional functionality.