ASP.NET AJAX Programmer’s Reference - Chapter 6 pps

DOM Extensions Document Object Model (DOM) programming is one of the most common client-side programming tasks in the world of Web development. The ASP.NET AJAX DOM extensions extend traditional DOM programming to add support for .NET-like methods and properties. This chapter provides in-depth coverage of these extensions. As you’ll see in subsequent chapters, this convenient set of classes and enumerations are used extensively in the ASP.NET AJAX client-side framework. DomElement As Listing 6-1 shows, the ASP.NET AJAX DOM extensions define a new JavaScript class named DomElement . As you’ll see in the following sections, this class exposes static methods and proper- ties that introduce .NET-like programming convenience into your client-side DOM scripting. Because all these methods and properties are static, you must call them directly on the DomElement class itself. Note that the DomElement class belongs to the Sys.UI namespace. Also note that you should not directly instantiate an instance of this class because all members of the class are static. Listing 6-1: The DomElement Class Sys.UI.DomElement = function Sys$UI$DomElement() { } Sys.UI.DomElement.registerClass(‘Sys.UI.DomElement’); get ElementById This static method of the DomElement class takes up to two parameters. The first parameter contains the value of the id HTML attribute of a DOM element. The second parameter, which is optional, references the parent DOM element of the DOM element whose id HTML attribute’s value is given by the first parameter. The main responsibility of the getElementById method is to return a reference to the JavaScript object that represents the DOM element whose id HTML attribute is given by the first parameter. To see how the getElementById method returns this reference, let’s take a look at the internal implementation of this method as shown in Listing 6-2 . c06.indd 161c06.indd 161 8/20/07 7:58:09 PM8/20/07 7:58:09 PM Chapter 6: DOM Extensions 162 Listing 6-2: The Internal Implementation of the get ElementById Method of the DomElement Class var $get = Sys.UI.DomElement.getElementById = function(f, e) { if(!e) return document.getElementById(f); if(e.getElementById) return e.getElementById(f); var c = [], d = e.childNodes; for(var b = 0; b < d.length; b ++ ) { var a = d[b]; if(a.nodeType == 1) c[c.length] = a; } while(c.length) { a = c.shift(); if(a.id == f) return a; d = a.childNodes; for(b = 0; b < d.length; b ++ ) { a = d[b]; if(a.nodeType == 1) c[c.length] = a; } } return null; } The getElementById method first checks whether its second parameter has been specified. If not, it simply delegates to the getElementById method of the current document JavaScript object. In other words, by default, the getElementById method uses the current document object as the parent of the DOM element with the id HTML attribute given by the first parameter: if(!e) return document.getElementById(f); If the second argument of the method has indeed been specified, the method checks whether the parent DOM element that the second argument references supports a method named getElementById . If so, it simply delegates to the getElementById method of the parent element. For example, if your page uses a frameset consisting of two frames, and you want to access a child element of one of these frames from the other frame, you can pass the document DOM object of the other frame as the second argument of the getElementById method: if(e.getElementById) return e.getElementById(f); c06.indd 162c06.indd 162 8/20/07 7:58:09 PM8/20/07 7:58:09 PM Chapter 6: DOM Extensions 163 This tells the getElementById method to call the getElementById method of the document element of the other frame as opposed to the document element of the current frame. You’ll see an example of this scenario shortly. If the second argument of the getElementById method of the DomElement class has indeed been specified but it does not support the getElementById method, the getElementById method of the DomElement class simply searches through the descendants of the parent element for the element with the specified id attribute value: var c = [], d = e.childNodes; for(var b = 0; b < d.length; b ++ ) { var a = d[b]; if(a.nodeType == 1) c[c.length] = a } while(c.length) { a = c.shift(); if(a.id == f) return a; d = a.childNodes; for(b = 0; b < d.length; b ++ ) { a = d[b]; if(a.nodeType == 1) c[c.length] = a } } return null This is great for situations where you want to limit the search to the descendant of a particular DOM element. You’ll see an example of this scenario shortly. As the internal implementation of the getElementById method of the DomElement class shows, this method handles the following three scenarios: ❑ The default scenario where the search for the DOM element with the specified id HTML attri- bute is limited to the descendant DOM elements of the current document object ❑ The scenario where the search for the DOM element with the specified id HTML attribute is limited to the descendant DOM elements of the specified document object, which may or may not be the current document object ❑ The scenario where the search for the DOM element with the specified id HTML attribute is limited to the descendant DOM elements of the specified DOM element The following code presents an example of the first scenario. As the boldfaced portion of this code shows, the getElementById method of the DomElement class is called without specifying the second argument. This instructs the getElementById method to search through the descendant DOM elements of the current document. c06.indd 163c06.indd 163 8/20/07 7:58:10 PM8/20/07 7:58:10 PM Chapter 6: DOM Extensions 164 <%@ Page Language=”C#” %> <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”> <html xmlns=”http://www.w3.org/1999/xhtml”> <head runat=”server”> <title>Untitled Page</title> <script language=”javascript” type=”text/javascript”> function frame1ClickCallback() { var frame1TextBox = Sys.UI.DomElement.getElementById(“frame1TextBox”); alert(frame1TextBox.value); } </script> </head> <body> <form id=”form1” runat=”server”> <asp:ScriptManager runat=”server” ID=”ScriptManager1” /> <input type=”text” id=”frame1TextBox” />&nbsp; <input type=”button” onclick=”frame1ClickCallback()” value=”Send” /> </form> </body> </html> Now, let’s take look at the example of the second scenario shown in the following code. The boldfaced portion of this code passes the document.form1 element as the second argument of the getElementById method. As you can see, document.form1 is the parent of the frame1TextBox element. This limits the search to the child elements of the document.form1 element. <%@ Page Language=”C#” %> <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”> <html xmlns=”http://www.w3.org/1999/xhtml”> <head runat=”server”> <title>Untitled Page</title> <script language=”javascript” type=”text/javascript”> function frame1ClickCallback() { var frame1TextBox = Sys.UI.DomElement.getElementById(“frame1TextBox”, document.form1); alert(frame1TextBox.value); } </script> </head> <body> <form id=”form1” runat=”server”> <asp:ScriptManager runat=”server” ID=”ScriptManager1” /> <input type=”text” id=”frame1TextBox” />&nbsp; <input type=”button” onclick=”frame1ClickCallback()” value=”Send” /> </form> </body> </html> c06.indd 164c06.indd 164 8/20/07 7:58:10 PM8/20/07 7:58:10 PM Chapter 6: DOM Extensions 165 Now, let’s take a look at an example of the third scenario. This example consists of three ASP.NET pages. The first page uses a frameset as shown in Listing 6-3 . The frameset consists of two frames named frame1 and frame2 that respectively display the contents of the frame1.aspx and frame2.aspx pages. Listing 6-3: The page that uses the frameset <%@ Page Language=”C#” %> <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”> <html xmlns=”http://www.w3.org/1999/xhtml”> <head runat=”server”> <title>Untitled Page</title> </head> <frameset cols=”60%,40%”> <frame src=”frame1.aspx” name=”frame1”/> <frame src=”frame2.aspx” name=”frame2”/> </frameset> </html> Listing 6-4 presents the frame2.aspx page. As you can see, this page is very simple. It consists of a single text box element. Listing 6-4: The frame2.aspx Page <%@ Page Language=”C#” %> <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”> <html xmlns=”http://www.w3.org/1999/xhtml”> <head runat=”server”> <title>Untitled Page</title> </head> <body> <form id=”form1” runat=”server”> <input type=”text” id=”frame2TextBox” /> </form> </body> </html> Listing 6-5 presents the frame1.aspx page. Listing 6-5: The frame1.aspx Page <%@ Page Language=”C#” %> <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”> <html xmlns=”http://www.w3.org/1999/xhtml”> <head runat=”server”> <title>Untitled Page</title> <script language=”javascript” type=”text/javascript”> (continued) c06.indd 165c06.indd 165 8/20/07 7:58:10 PM8/20/07 7:58:10 PM Chapter 6: DOM Extensions 166 Listing 6-5 (continued) function frame1ClickCallback() { var frame1TextBox = Sys.UI.DomElement.getElementById(“frame1TextBox”); var frame2TextBox = Sys.UI.DomElement.getElementById(“frame2TextBox”, parent.frame2.document); frame2TextBox.value = frame1TextBox.value; } </script> </head> <body> <form id=”form1” runat=”server”> <asp:ScriptManager runat=”server” ID=”ScriptManager1” /> <input type=”text” id=”frame1TextBox” />&nbsp; <input type=”button” onclick=”frame1ClickCallback()” value=”Send” /> </form> </body> </html> This page consists of a text box and a button. When you enter a value into the text box and click the button, the frame1ClickCallback JavaScript function is called. As the boldfaced portion of Listing 6-5 shows, this JavaScript function takes the following actions: 1. It calls the getElementById method of the DomElement class to return a reference to the text box displayed in the frame1.aspx — that is, the current document. var frame1TextBox = Sys.UI.DomElement.getElementById(“frame1TextBox”); 2. It calls the getElementById method of the DomElement class to return a reference to the text box displayed in the other frame — that is, frame2.aspx . Note that the frame1ClickCallback method passes the document object of the other frame as the second argument to the getElementById method to instruct this method to search through the child DOM elements of the other frame for the specified text box. var frame2TextBox = Sys.UI.DomElement.getElementById(“frame2TextBox”, parent.frame2.document); 3. It assigns the value of the text box of frame1.aspx to the text box of frame2.aspx . frame2TextBox.value = frame1TextBox.value; add CssClass The addCssClass static method of the DomElement class adds a new CSS class name to the specified DOM element, if it hasn’t been already added. Listing 6-6 presents the internal implementation of this method. Note that this method first calls the containsCssClass static method of the DomElement class to check whether the DOM object already contains the specified CSS class name. If not, it simply appends the new CSS class name to the className property of the DOM object. c06.indd 166c06.indd 166 8/20/07 7:58:11 PM8/20/07 7:58:11 PM Chapter 6: DOM Extensions 167 Listing 6-6: The Internal Implementation of the add CssClass Method Sys.UI.DomElement.addCssClass = function(a, b) { if(!Sys.UI.DomElement.containsCssClass(a, b)) { if(a.className === “”) a.className = b; else a.className += “ “ + b; } } contains CssClass The containsCssClass static method of the DomElement class returns a Boolean value that specifies whether a specified DOM object contains the specified CSS class name. Listing 6-7 presents the internal implementation of this method. Note that this method simply delegates to the contains static method of the Array class. The ASP.NET AJAX client-side script framework extends the Array class to add support for the contains static method, as discussed in chapter 2 . Listing 6-7: The Internal Implementation of the contains CssClass Method Sys.UI.DomElement.containsCssClass = function(b, a) { return Array.contains(b.className.split(“ “), a) } remove CssClass The removeCssClass static method of the DomElement class removes a specified CSS class name from the specified DOM object. Listing 6-8 contains the code for the internal implementation of this method. As you can see, this method uses a simple string manipulation to remove the specified CSS class name. Listing 6-8: The Internal Implementation of the remove CssClass Method Sys.UI.DomElement.removeCssClass = function(d, c) { var a =” “ + d.className + “ “, b = a.indexOf(“ “ + c + “ “); if(b >= 0) d.className = (a.substring(0, b) + “ “ + a.substring(b + c.length + 1, a.length)).trim(); } Take a look at the example in Listing 6-9 , which uses the addCssClass and removeCssClass methods of the DomElement class. c06.indd 167c06.indd 167 8/20/07 7:58:11 PM8/20/07 7:58:11 PM Chapter 6: DOM Extensions 168 Listing 6-9: A page that uses the add CssClass and remove CssClass Methods <%@ Page Language=”C#” %> <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”> <html xmlns=”http://www.w3.org/1999/xhtml”> <head runat=”server”> <title>Untitled Page</title> <style type=”text/css”> .CssClass1 { background-color: Blue; color: Yellow; font-weight: bold; } .CssClass2 { background-color: Yellow; color: Blue; font-weight: bold; } </style> <script language=”javascript” type=”text/javascript”> var myLinkDomElementObj; var myList; function addCallback() { var myCssClass = myList.options[myList.selectedIndex].value; Sys.UI.DomElement.addCssClass(myLinkDomElementObj, myCssClass); } function removeCallback() { var myCssClass = myList.options[myList.selectedIndex].value; Sys.UI.DomElement.removeCssClass(myLinkDomElementObj, myCssClass); } function pageLoad() { myLinkDomElementObj = Sys.UI.DomElement.getElementById(“myLink”); myList = document.getElementById(“myList”); } </script> </head> <body> <form id=”form1” runat=”server”> <asp:ScriptManager runat=”server” ID=”ScriptManager1” /> <a href=”http://www.wrox.com” id=”myLink”> Wrox Web Site</a>&nbsp;&nbsp; <select id=”myList”> <option value=”CssClass1”>CSS Class 1</option> <option value=”CssClass2”>CSS Class 2</option> </select>&nbsp;&nbsp; c06.indd 168c06.indd 168 8/20/07 7:58:11 PM8/20/07 7:58:11 PM Chapter 6: DOM Extensions 169 <input type=”button” value=”Add” onclick=”addCallback()” />&nbsp; <input type=”button” value=”Remove” onclick=”removeCallback()” /> </form> </body> </html> Figure 6-1 shows what you’ll see when you access this page. Run the program, select a CSS class name from the list, and click the Add button. You should see the effects of the selected CSS class. Now click the Remove button. The link should go back to its default format. Figure 6-1 toggle CssClass The toggleCssClass static method of the DomElement class toggles a specified CSS class name on or off on a specified DOM object. The best way to understand what this method does is to use it in an example. Listing 6-10 presents a page that uses this method. Listing 6-10: A page that uses the toggle CssClass Method <%@ Page Language=”C#” %> <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”> <html xmlns=”http://www.w3.org/1999/xhtml”> <head runat=”server”> <title>Untitled Page</title> <style type=”text/css”> .CssClass1 { background-color: Blue; color: Yellow; font-size: 40px; } </style> <script language=”javascript” type=”text/javascript”> function toggleCssClass(myLink) { Sys.UI.DomElement.toggleCssClass(myLink, “CssClass1”); } </script> (continued) c06.indd 169c06.indd 169 8/20/07 7:58:12 PM8/20/07 7:58:12 PM Chapter 6: DOM Extensions 170 Listing 6-10 (continued) </head> <body> <form id=”form1” runat=”server”> <asp:ScriptManager runat=”server” ID=”ScriptManager1” /> <a href=”http://www.wrox.com” onmouseover=”toggleCssClass(this)” onmouseout=”toggleCssClass(this)”>Wrox Web Site</a> </form> </body> </html> If you run this code, you’ll see the result shown in Figure 6-2 , which is a very simple page that contains a single hyperlink. Now if you move the mouse over the link, you’ll get the result shown in Figure 6-3 . If you move the mouse away from the link, you’ll get the result shown in Figure 6-2 again. Therefore, moving the mouse over and out of the link switches the style of the class between what you see in the two figures. Figure 6-2 Figure 6-3 Listing 6-11 shows the internal implementation of the toggleCssClass method. This method first calls the containsCssClass method to check whether the specified DOM object already contains the speci- fied CSS class name. If so, it calls the removeCssClass method to remove the CSS class name. If not, it calls the addCssClass method to add the CSS class name. c06.indd 170c06.indd 170 8/20/07 7:58:12 PM8/20/07 7:58:12 PM [...]... element.offsetHeight || 0); } The ASP.NET page shown in Listing 6- 1 8 uses the getBounds method to access the width of the span DOM element called myspan 175 c 06. indd 175 8/20/07 7:58:14 PM Chapter 6: DOM Extensions Listing 6- 1 8: An ASP.NET page that uses the getBounds Method ... values of the DomEvent object that represents the click event, as shown in Figure 6- 4 As you can see, the ASP.NET AJAX DOM extensions automatically instantiate a DomEvent object under the hood and pass it into the clickcb event handler 190 c 06. indd 190 8/20/07 7:58:18 PM Chapter 6: DOM Extensions Figure 6- 4 Listing 6- 2 7: The addHandler Method var $addHandler = Sys.UI.DomEvent.addHandler = function... that features one enumeration value for each key, as shown in Listing 6- 2 0 1 76 c 06. indd 1 76 8/20/07 7:58:14 PM Chapter 6: DOM Extensions Listing 6- 2 0: The Key Enumeration Sys.UI.Key = function Sys$UI$Key() { } Sys.UI.Key.prototype = { backspace: 8, tab: 9, enter: 13, esc: 27, space: 32, pageUp: 33, pageDown: 34, end: 35, home: 36, left: 37, up: 38, right: 39, down: 40, del: 127 } Sys.UI.Key.registerEnum(“Sys.UI.Key”);... first parameter references the DOM element that raised the event The second parameter is a string that contains the name of the event, excluding the on prefix The third parameter references the event handler being added Listing 6- 2 6 contains an example the uses the addHandler method Listing 6- 2 6: An example that uses the addHandler method Notice that Listings 6- 2 2 and 6- 2 3 use a element to register the Delegate.js JavaScript file This file contains the entire application logic The ScriptReference class is discussed later in this book For... 172 c 06. indd 172 8/20/07 7:58:13 PM Chapter 6: DOM Extensions Listing 6- 1 5 shows an example of how the getLocation and setLocation methods are used Listing 6- 1 5: An ASP.NET page that uses the getLocation and setLocation Methods ... Listing 6- 2 3: A page that uses different movable content Untitled Page 180 c 06. indd 180 8/20/07 7:58:15 PM Chapter 6: DOM... different types of event models As such, programmers spend most of their time adding custom code to make up for the differences between these event models The ASP.NET AJAX client-side framework comes with a 185 c 06. indd 185 8/20/07 7:58: 16 PM Chapter 6: DOM Extensions class named DomEvent that encapsulates all the logic that deals with event modeling differences among browsers, and provides you with a convenient . the className property of the DOM object. c 06. indd 166 c 06. indd 166 8/20/07 7:58:11 PM8/20/07 7:58:11 PM Chapter 6: DOM Extensions 167 Listing 6- 6 : The Internal Implementation of the add CssClass. 6- 9 , which uses the addCssClass and removeCssClass methods of the DomElement class. c 06. indd 167 c 06. indd 167 8/20/07 7:58:11 PM8/20/07 7:58:11 PM Chapter 6: DOM Extensions 168 Listing 6- 9 :. language=”javascript” type=”text/javascript”> (continued) c 06. indd 165 c 06. indd 165 8/20/07 7:58:10 PM8/20/07 7:58:10 PM Chapter 6: DOM Extensions 166 Listing 6- 5 (continued) function frame1ClickCallback()