ASP.NET AJAX Programmer’s Reference - Chapter 8 potx

Developing Client Controls As discussed in the previous chapter, the Component class is the base class for all ASP.NET AJAX components. The ASP.NET AJAX client-side framework includes two important subclasses of the Component base class: Sys.UI.Control and Sys.UI.Behavior . Therefore, when it comes to choosing a base class from which to derive your component class, you have three options: Component , Control , and Behavior . The previous chapter showed you how to implement an ASP.NET AJAX component that derives from the Component base class. This chapter first provides you with in-depth coverage of the Control class and its methods, properties, and events. Then it provides you with a recipe for developing ASP.NET AJAX components that derive from the Control class. Finally, it uses this recipe to implement a custom control class. Control This section discusses the methods and properties of the Control base class. Because your custom controls must override the members of the Control class, you need to have a good understanding of what each member does and how you should override them to provide your own implementa- tion for these members. Definition Listing 8-1 presents the definition of the Control class. Note that this code listing registers the Control class as the subclass of the Component base class: Sys.UI.Control.registerClass(‘Sys.UI.Control’, Sys.Component); The Control class exposes several methods and properties, which are discussed in the following sections. This section discusses the constructor of the class. c08.indd 281c08.indd 281 8/20/07 6:05:04 PM8/20/07 6:05:04 PM Chapter 8: Developing Client Controls 282 Listing 8-1: The Definition of the Control Class Sys.UI.Control = function Sys$UI$Control(element) { if (typeof(element.control) != ‘undefined’) throw Error.invalidOperation(Sys.Res.controlAlreadyDefined); Sys.UI.Control.initializeBase(this); this._element = element; element.control = this; this._oldDisplayMode = this._element.style.display; if (!this._oldDisplayMode || (this._oldDisplayMode == ‘none’)) this._oldDisplayMode=’’; } Sys.UI.Control.prototype={ _ parent: null, _visibilityMode: Sys.UI.VisibilityMode.hide, get_element: Sys$UI$Control$get_element, get_id: Sys$UI$Control$get_id, set_id: Sys$UI$Control$set_id, get_parent: Sys$UI$Control$get_parent, set_parent: Sys$UI$Control$set_parent, get_visibilityMode: Sys$UI$Control$get_visibilityMode, set_visibilityMode: Sys$UI$Control$set_visibilityMode, get_visible: Sys$UI$Control$get_visible, set_visible: Sys$UI$Control$set_visible, addCssClass: Sys$UI$Control$addCssClass, dispose: Sys$UI$Control$dispose, initialize: Sys$UI$Control$initialize, onBubbleEvent: Sys$UI$Control$onBubbleEvent, raiseBubbleEvent: Sys$UI$Control$raiseBubbleEvent, removeCssClass: Sys$UI$Control$removeCssClass, toggleCssClass: Sys$UI$Control$toggleCssClass } Sys.UI.Control.registerClass(‘Sys.UI.Control’, Sys.Component); As you can see, the constructor of the Control class takes a single argument that references the DOM element that the Control instance being instantiated will represent. You can think of the Control instance as the ASP.NET AJAX representation of the DOM element. Consequently, the DOM element that the Control instance is supposed to represent must already exist in the document where the Control instance is instantiated. Notice that the constructor assigns the newly instantiated Control instance to the control property of the DOM element, signifying that the DOM element knows which ASP.NET AJAX Control object repre- sents it: element.control = this; c08.indd 282c08.indd 282 8/20/07 6:05:05 PM8/20/07 6:05:05 PM Chapter 8: Developing Client Controls 283 As a result, every DOM element can be represented by only one Control object. To enforce this requirement, the constructor first checks whether the control property of the specified DOM element already references an object. If so, the constructor raises an exception: if (typeof(element.control) != ‘undefined’) throw Error.invalidOperation(Sys.Res.controlAlreadyDefined); Note that the constructor calls the initializeBase method, passing in the reference to the Control instance being instantiated to invoke the constructor of its base class, which is the Component base class: Sys.UI.Control.initializeBase(this); The constructor stores the DOM element passed into it in a field named _element : this._element = element; The constructor then stores the value of the display property of the style property of the DOM element in another field named _oldDisplayMode : this._oldDisplayMode = this._element.style.display; if (!this._oldDisplayMode || (this._oldDisplayMode == ‘none’)) this._oldDisplayMode=’’; get_element The get_element method of the Control class returns a reference to the DOM element that the Control represents, as shown in Listing 8-2 . Listing 8-2: The get_element Method of the Control Class function Sys$UI$Control$get_element() { return this._element; } get_id As discussed in the previous chapter, the Component base class exposes a property named id whose value uniquely identifies a component among other components stored in the Application object’s _components collection. Because the Control class derives from the Component base class, every Control object is also a Component object and consequently is added to the _components collection of the Application object. This means that every Control object must have a unique id value. Because a Control object is an ASP.NET AJAX representation of a DOM element in an ASP.NET AJAX application, it makes lot of sense to use the value of the DOM element’s id HTML attribute as the id of the Control object that represents the DOM element. Therefore, the Control class overrides the get_id method that it inherits from its base class (the Component class) to return the value of the id attribute of the DOM element that the Control represents, as shown in Listing 8-3 . c08.indd 283c08.indd 283 8/20/07 6:05:05 PM8/20/07 6:05:05 PM Chapter 8: Developing Client Controls 284 Listing 8-3: The get_id Method of the Control Class function Sys$UI$Control$get_id() { if (!this._element) return ‘’; return this._element.id; } set_id Because the value of a Control object’s id property is the same as the value of the id HTML attribute of the DOM element that the Control object represents, the id property of the Control object cannot be set. Therefore, the Control class overrides the set_id method that it inherits from the Component base class to raise an InvalidOperation exception. This exception informs the client of a Control object that calls this method that setting the value of the id property of the Control object is an invalid opera- tion, as shown in Listing 8-4 . Listing 8-4: The set_id Method of the Control Class function Sys$UI$Control$set_id(value) { throw Error.invalidOperation(Sys.Res.cantSetId); } set_parent The Control class exposes a property named parent that references the parent Control object of a Control object. The Control class features a method named set_parent that allows you to specify another Control object as the parent of the Control object on which this method is invoked, as shown in Listing 8-5 . Listing 8-5: The set_parent Method of the Control Class function Sys$UI$Control$set_parent(value) { var parents = [this]; var current = value; while (current) { if (Array.contains(parents, current)) throw Error.invalidOperation(Sys.Res.circularParentChain); parents[parents.length] = current; current = current.get_parent(); } this._parent = value; } c08.indd 284c08.indd 284 8/20/07 6:05:06 PM8/20/07 6:05:06 PM Chapter 8: Developing Client Controls 285 get_parent The Control class exposes a method named get_parent that returns the parent Control object of a Control object on which this method is invoked, as shown in Listing 8-6 . Listing 8-6: The get_parent Method of the Control Class function Sys$UI$Control$get_parent() { if (this._parent) return this._parent; else { var parentElement = this._element.parentNode; while (parentElement) { if (parentElement.control) return parentElement.control; parentElement = parentElement.parentNode; } return null; } } As you can see in this listing, the get_parent method returns the value of the _parent property of the Control object on which the method is invoked if the value of this property has been set: if (this._ parent) return this._ parent; However, if the value of the _ parent property of the Control object has not been specified, the get_parent method searches upward through the containment hierarchy of the DOM element that the Control object represents for the first DOM element whose control property has been specified and returns the value of this control property as the parent Control object. As previously shown in Listing 8-2 , the value of a control property of a DOM element references the Control object that represents the DOM element. Therefore, if the value of the parent property of the Control object that represents a DOM element is not explicitly specified, the Control object that represents the first parent DOM element in the contain- ment hierarchy of the DOM element will be used as the parent Control object of the DOM element. As Listing 8-6 shows, if the parent property of the Control object that represents a DOM element is not specified, and no parent DOM element in the containment hierarchy of the DOM element is repre- sented by a Control object, the get_parent method returns null . This means that it is possible to have a Control object without a parent. c08.indd 285c08.indd 285 8/20/07 6:05:06 PM8/20/07 6:05:06 PM Chapter 8: Developing Client Controls 286 get_visibilityMode The Control class exposes a property of type VisibilityMode named visibilityMode . Listing 8-7 presents the definition of the VisibilityMode type. As you can see, the VisibilityMode is an enu- meration with two possible values: hide and collapse . Listing 8-7: The VisibilityMode Type Sys.UI.VisibilityMode = function Sys$UI$VisibilityMode() { throw Error.notImplemented(); } Sys.UI.VisibilityMode.prototype = { hide: 0, collapse: 1 } Sys.UI.VisibilityMode.registerEnum(“Sys.UI.VisibilityMode”); The get_visibilityMode method of the Control class returns the value of the visibilityMode property of the Control , as shown in Listing 8-8 . Listing 8-8: The get_visibilityMode Method of the Control Class function Sys$UI$Control$get_visibilityMode() { return this._visibilityMode; } get_visible The Control class contains a method named get_visible that returns the visibility status of the DOM element that the current Control object represents, as shown in Listing 8-9 . In other words, the visibility status of a Control object is same as the visibility status of the DOM element that the Control object represents. Listing 8-9: The get_visible Method of the Control Class function Sys$UI$Control$get_visible() { return (this._element.style.visibility != ‘hidden’); } set_visibilityMode The set_visibilityMode method of the Control class enables you to set the value of the visibili- tyMode property of the Control object on which this method is invoked, as shown in Listing 8-10 . Due to the fact that a Control object is an ASP.NET AJAX representation of a DOM element, setting its prop- erties affects the DOM element that it represents. In this case, setting the visibilityMode property of a c08.indd 286c08.indd 286 8/20/07 6:05:06 PM8/20/07 6:05:06 PM Chapter 8: Developing Client Controls 287 Control object changes the value of the display property of the DOM element’s style property if the DOM element is invisible. More specifically, if the visibilityMode property is set to the enumeration value VisibilityMode.hide , the display property reverts to its original value. The constructor of the Control class stores the original value of the display property of the DOM element’s style property in a field named _oldDisplayMode . If the visibilityMode property is set to the enumeration value VisibilityMode.collapse , the display property of the DOM element’s style property is set to none . Listing 8-10: The set_visibilityMode Method of the Control Class function Sys$UI$Control$set_visibilityMode(value) { if (this._visibilityMode !== value) { this._visibilityMode = value; if (this.get_visible() === false) { if (this._visibilityMode === Sys.UI.VisibilityMode.hide) this._element.style.display = this._oldDisplayMode; else this._element.style.display = ’none’; } } this._visibilityMode = value; } set_visible Listing 8-11 presents the internal implementation of the set_visible method of the Control class. As you can see, the visible property of a Control object basically reflects the visibility property of the style property of the DOM element that the Control object represents. In other words, the visible property of a Control object allows you to treat the visibility of the underlying DOM element as a Bool- ean value as opposed to a string value such as visible or hidden . Listing 8-11: The set_visible Method of the Control Class function Sys$UI$Control$set_visible(value) { if (value != this.get_visible()) { this._element.style.visibility = value ? ‘visible’ : ‘hidden’; if (value || (this._visibilityMode === Sys.UI.VisibilityMode.hide)) this._element.style.display = this._oldDisplayMode; else this._element.style.display=’none’; } } c08.indd 287c08.indd 287 8/20/07 6:05:07 PM8/20/07 6:05:07 PM Chapter 8: Developing Client Controls 288 add CssClass When this method is invoked on a Control object, it calls the addCssClass static method on the DomElement class to add the specified CSS class to the DOM element that the Control object represents, as shown in Listing 8-12 . Listing 8-12: The add CssClass Method of the Control Class function Sys$UI$Control$addCssClass(className) { Sys.UI.DomElement.addCssClass(this._element, className); } remove CssClass When this method is invoked on a Control object, it calls the removeCssClass static method on the DomElement class to remove the specified CSS class from the DOM element that the Control object represents, as shown in Listing 8-13 . Listing 8-13: The remove CssClass Method of the Control Class function Sys$UI$Control$removeCssClass(className) { Sys.UI.DomElement.removeCssClass(this._element, className); } toggle CssClass When this method is called on a Control object, it calls the toggleCssClass static method on the DomElement class to toggle the specified CSS class of the DOM element that the Control object repre- sents, as shown in Listing 8-14 . What this means is that if the DOM element already contains the speci- fied CSS class, the toggleCssClass method removes the CSS class. Otherwise, the method adds the CSS class to the DOM element. Listing 8-14: The toggle CssClass Method of the Control Class function Sys$UI$Control$toggleCssClass(className) { Sys.UI.DomElement.toggleCssClass(this._element, className); } dispose The Control class overrides the dispose method that it inherits from the Component base class, as shown in Listing 8-15 . This method calls the delete method on the element property that references the DOM element that the current Control object represents. c08.indd 288c08.indd 288 8/20/07 6:05:07 PM8/20/07 6:05:07 PM Chapter 8: Developing Client Controls 289 Listing 8-15: The dispose Method of the Control Class function Sys$UI$Control$dispose() { Sys.UI.Control.callBaseMethod(this, ‘dispose’); if (this._element) { this._element.control = undefined; delete this._element; } } on BubbleEvent The Control base class in the ASP.NET Framework exposes a method named OnBubbleEvent that its subclasses can override to catch the events that their child controls bubble up. For example, the GridViewRow class overrides the OnBubbleEvent method to catch the Command events that its child Image, Button, or Link controls bubble up. The ASP.NET AJAX Control base class exposes a method named onBubbleEvent that emulates the OnBubbleEvent method of the ASP.NET Control base class. This means that your custom client control can override this method to catch the events that its child Control objects bubble up, as shown in Listing 8-16 . Listing 8-16: The on BubbleEvent Method of the Control Class function Sys$UI$Control$onBubbleEvent(source, args) { return false; } As the listing shows, the onBubbleEvent method takes two arguments and returns a Boolean value. The first argument references the child Control object that bubbled up the event. The second argument is of type EventArgs . As mentioned, the OnBubbleEvent method allows your custom client control to catch the events that its child controls bubble up. What your custom client control does with the events that it catches is up to your custom control. Normally, your custom client control is only interested in certain types of events. It’s the responsibility of your custom client control’s implementation of the onBubbleEvent method to use the second argument of the method to determine the type of the event. If the event is not of the type that your custom control is interested in, your custom control’s implemen- tation of the method must return false to allow the event to bubble further up in the containment hier- archy of your control. However, if the event is indeed of the type that your custom control is interested in, your custom control must return true to stop the event from bubbling further up the containment hierarchy (as shown later in this chapter). In Listing 8-16 , the onBubbleEvent method of the Control base class returns false to allow the event to bubble further up in the containment hierarchy. c08.indd 289c08.indd 289 8/20/07 6:05:07 PM8/20/07 6:05:07 PM Chapter 8: Developing Client Controls 290 raise BubbleEvent The ASP.NET Control base class exposes a method named RaiseBubbleEvent that its subclasses can invoke to bubble up their events. For example, the GridViewRow control calls this method to bubble its events up to the containing GridView control, where the GridView control catches these events in its OnBubbleEvent method. The ASP.NET AJAX Control base class exposes a method named raiseBubbleEvent that emulates the RaiseBubbleEvent method of the ASP.NET Control base class. Your custom client control can call this method to bubble its events up to its containing controls. You’ll see an example of this later in this chapter. Now let’s take a look at the internal implementation of the Control base class’s raiseBubbleEvent method, which is shown in Listing 8-17 . Listing 8-17: The raise BubbleEvent Method of the Control Class function Sys$UI$Control$raiseBubbleEvent(source, args) { var currentTarget = this.get_ parent(); while (currentTarget) { if (currentTarget.onBubbleEvent(source, args)) return; currentTarget = currentTarget.get_ parent(); } } As you can see, this method marches upward through the containment hierarchy of the control that invokes the raiseBubbleEvent and keeps calling the onBubbleEvent method on each node of the hierarchy until it reaches the node whose onBubbleEvent method returns true . The onBubbleEvent method of a client control returns true when it catches an event that it can handle. Developing Custom Client Controls An ASP.NET AJAX client control is an ASP.NET AJAX client component that directly or indirectly derives from the Control base class. You can think of an ASP.NET AJAX client control as an ASP.NET AJAX representation of a specific DOM element on a page. The ASP.NET AJAX client controls essentially emulate their corresponding ASP.NET server controls. Most basic ASP.NET server controls, such as Label and Image , are ASP.NET representations of DOM elements. These representations enable you to program against the underlying DOM elements using the ASP.NET/.NET Framework. In other words, these representations enable you to treat DOM elements as .NET objects. The ASP.NET AJAX client controls play a similar role in the client-side programming. These controls are the ASP.NET AJAX representations of DOM elements, allowing you to program against these elements using the ASP.NET AJAX Framework. In other words, these representations enable you to treat DOM elements as ASP.NET AJAX objects. c08.indd 290c08.indd 290 8/20/07 6:05:08 PM8/20/07 6:05:08 PM [...]... consequently the element displays these tags as if they were normal non-HTML characters Figure 8- 2 296 c 08. indd 296 8/ 20/07 6:05:10 PM Chapter 8: Developing Client Controls Note that the page shown in Listing 8- 2 4 contains the following reference: This script references a JavaScript file named PreviewScripts.js that contains... Figure 8- 2 presents a different scenario from what’s shown in Figure 8- 1 The text “ASP.NET AJAX” is entered in both cases, containing the opening and closing tags of the HTML element In Figure 8- 1 , however, the HTML encoding is off In this case, the opening and closing tags of the HTML element are not HTML-encoded and consequently the HTML element shows the text in bold In Figure 8- 2 ,... control counterpart to make client-side programming feel more like server-side ASP.NET programming 2 98 c 08. indd 2 98 8/20/07 6:05:10 PM Chapter 8: Developing Client Controls imageURl The Image client control exposes two methods named get_imageURL and set_imageURL that allow you to get and set the value of the src property of the underling DOM element, as shown in Listing 8- 2 7 As you can see from this code... ‘text’, type: String } ] } 294 c 08. indd 294 8/ 20/07 6:05:09 PM Chapter 8: Developing Client Controls Using Label Client Control Listing 8- 2 4 presents a page that uses the Label client control Listing 8- 2 4: A Page that Uses the Label Client Control ... Control—passing in the reference to the DOM element that the Label control represents htmlEncode The Label client control exposes a getter method named get_htmlEncode and a setter method named set_htmlEncode that respectively get and set the value of the htmlEncode Boolean property of the control, as shown in Listing 8- 1 9 291 c 08. indd 291 8/ 20/07 6:05: 08 PM Chapter 8: Developing Client Controls Listing 8- 1 9: The... fashion: this.get_element().filters[“revealTrans”].play(); 3 08 c 08. indd 3 08 8/20/07 6:05:14 PM Chapter 8: Developing Client Controls mouseOutCallback When the end user moves the mouse pointer out of the image DOM element that the Image2 client control represents, the mouseOutCallback method shown in Listing 8- 3 9 is automatically invoked Listing 8- 3 9: The mouseOutCallback Method function CustomComponents$Image2$mouseOutCallback... value of the innerHTML property of the DOM element that the Label control represents: else return element.innerHTML; Listing 8- 2 1 presents the implementation of the set_text method of the Label control 292 c 08. indd 292 8/ 20/07 6:05: 08 PM Chapter 8: Developing Client Controls Listing 8- 2 1: The set_text Method of the Label Control function Sys$Preview$UI$Label$set_text(value) { if (!value) value=””; var element... this.get_element().height; (continued) 299 c 08. indd 299 8/ 20/07 6:05:11 PM Chapter 8: Developing Client Controls Listing 8- 2 9 (continued) } function Sys$Preview$UI$Image$set_height(value) { this.get_element().height = value; } alternateText The get_alternateText and set_alternateText methods allow you to get and set the value of the alt property of the image DOM element using the ASP.NET AJAX client-side framework in the... object The ASP.NET AJAX Image client control plays the same role in the ASP.NET AJAX client-side framework It is the ASP.NET AJAX representation of an image DOM element As such, it exposes the DOM width, height, src, and alt properties of this DOM element as the width, height, imageURL, and 297 c 08. indd 297 8/ 20/07 6:05:10 PM Chapter 8: Developing Client Controls alterateText properties on the Image client... alternateText : “Wrox Programmer’s Reference Series”, width : 155, height : 58, 312 c 08. indd 312 8/ 20/07 6:05:15 PM Chapter 8: Developing Client Controls mouseOverImageURL : “wroxProfessionalSmall.jpg”, duration : 0.4, transition : CustomComponents.Transition.circleIn}; var events = null; var references = null; var element = $get(“myImage”); $create(type, properties, events, references, element); } . knows which ASP. NET AJAX Control object repre- sents it: element.control = this; c 08. indd 282 c 08. indd 282 8/ 20/07 6:05:05 PM8/20/07 6:05:05 PM Chapter 8: Developing Client Controls 283 As a result,. Control represents, as shown in Listing 8- 3 . c 08. indd 283 c 08. indd 283 8/ 20/07 6:05:05 PM8/20/07 6:05:05 PM Chapter 8: Developing Client Controls 284 Listing 8- 3 : The get_id Method of the Control. the ASP. NET AJAX Framework. In other words, these representations enable you to treat DOM elements as ASP. NET AJAX objects. c 08. indd 290c 08. indd 290 8/ 20/07 6:05: 08 PM8/20/07 6:05: 08 PM Chapter