Creating Custom ASP.NET AJAX Client Controls—Client control Prototype

CSharp-Online.NET:Articles

ASP.NET Articles

Creating Custom ASP.NET AJAX Client Controls Prerequisites Extend existing controls Extend Image web control Creating ImageEx custom web control Registering the client control Implementing the IScriptControl Interface GetScriptDescriptors method GetScriptReferences method Building the client control Client control Prototype Registering the client control References What's Next

edit

Contents 1 Defining Client control Class Prototype 1.1 Defining properties using get and set accessors 1.2 Defining the event handlers for the client control DOM element 1.3 Implementing the Initialize and Dispose Methods

Defining Client control Class Prototype

As part of building client control, you'll need to define the prototype for the client control class. The prototype includes get and set accessors for properties as well as event handlers. It also includes an initialize method that is called when an instance of the client control is created, and a dispose method that performs cleanup when the client control is no longer required by the page.

Defining properties using get and set accessors

Each property identified in the ScriptDescriptor instance of the server control's GetScriptDescriptors method must have corresponding client accessors. The client property accessors are defined as get_<property name> and set_<property name> methods of the client class prototype. The following code shows one property implementation, you can explore rest of properties in the attached sample code.

get_hoverImageUrl : function() {
  return this._hoverImageUrl;
},
set_hoverImageUrl : function(value) {
if (this._hoverImageUrl !== value) {
    this._hoverImageUrl = value;
    this.raisePropertyChanged('hoverImageUrl');
  }
},

It is important to note that JavaScript is case-sensitive, the get and set accessor names must exactly match the property names identified in the ScriptDescriptor instance of the GetScriptDescriptors method in the Web server control.

Defining the event handlers for the client control DOM element

Event handlers for a client class are defined as methods of the class prototype. The handlers are associated with event delegates and with events of the browser DOM by using the addHandlers method, which is discussed later in this section with the initialize method.

// Event delegates
_onMouseOver : function(e) {
  if (this.get_element() && !this.get_element().disabled) {
      this.get_element().src = this._hoverImageUrl;          
  }
},
_onMouseOut : function(e) {
  if (this.get_element() && !this.get_element().disabled) {
      this.get_element().src = this._normalImageUrl;          
  }
},

Implementing the Initialize and Dispose Methods

The initialize method is called when an instance of the control is created. Typically implement this method to set default property values, to create function delegates, and to add delegates as event handlers.

The initialize method of the SCS.WebControls.ImageEx class does the following:

• Calls the initialize method of the Sys.UI.Control base class
• Calls the $addHandlers method to add event delegates as handlers for the onmouseover, onmouseout, onmousedown and onmouseup events of the associated HTML element <img ...>. You’ll Notice that the "on" part of the event name (for example, onmouseover) is not specified.
• Initialize the associated HTML element <img ...> with default image. If the image is disabled, the src attribute be setted with disabledImageUrl property.

The dispose method is called when an instance of the control is no longer used on the page and is removed. Implement this method to free any resources that are no longer required for the control, such as DOM event handlers.

The dispose method of the SCS.WebControls.ImageEx class does the following:

• Calls the $clearHandlers method to clear the event delegates as handlers for the onmouseover, onmouseout, onmousedown and onmouseup events of the associated DOM element.
• Calls the dispose method of the Sys.UI.Control base class.

initialize : function(){
        SCS.WebControls.ImageEx.callBaseMethod(this, 'initialize');
        
        this._onmouseoverHandler = Function.createDelegate(this, this._onMouseOver);
        this._onmouseoutHandler = Function.createDelegate(this, this._onMouseOut);
        this._ommousedownHandler = Function.createDelegate(this, this._onMouseDown);
        this._onmouseupdHandler = Function.createDelegate(this, this._onMouseUp);
        
        //Registering event handlers
        //note that "on" is removed from event name 
        $addHandlers(this.get_element(), 
                     { 'mouseover' : this._onMouseOver,
                       'mouseout' : this._onMouseOut ,
                       'mousedown' : this._onMouseDown,
                       'mouseup' : this._onMouseUp },
                     this);
        //Initialize client control DOM element
        if(!this.get_element().disabled)
            this.get_element().src = this._normalImageUrl;
        else
            this.get_element().src = this._disabledImageUrl;
    },
    
    //Dispose Method
    dispose : function() 
    {
        $clearHandlers(this.get_element());        
        SCS.WebControls.ImageEx.callBaseMethod(this, 'dispose');
    },