This content was uploaded by our users and we assume good faith they have the permission to share this book. If you own the copyright to this book and it is wrongfully on our website, we offer a simple DMCA procedure to remove your content from our site. Start by pressing the button below!
Trademarks: Wiley, the Wiley logo, Wrox, the Wrox logo, Wrox Programmer to Programmer, and related trade dress are trademarks or registered trademarks of John Wiley & Sons, Inc. and/or its affiliates, in the United States and other countries, and may not be used without written permission. All other trademarks are the property of their respective owners. Wiley Publishing, Inc., is not associated with any product or vendor mentioned in this book. Wiley also publishes its books in a variety of electronic formats. Some content that appears in print may not be available in electronic books.
ffirs.indd vi
8/25/07 2:41:01 AM
About the Author Shahram Khosravi, Ph.D., is a senior software engineer, consultant, author, and instructor specializing in ASP.NET, Windows Communications Foundation (WCF), ASP.NET AJAX, Windows Workflow Foundation (WF), IIS7 and ASP.NET Integrated Programming, ADO.NET, Web services, .NET, and XML technologies such as XSD, XSLT, XPath, SOAP, and WSDL. He also has years of experience in object-oriented analysis, design, and programming, architectural and design patterns, service-oriented analysis, design, and programming, 3D computer graphics programming, user interface design, and usability. Shahram is the author of the following four books: Professional ASP.NET 3.5 and .NET 3.5 Programming (ASP.NET Internals plus ASP.NET AJAX, IIS 7.0, Enterprise Library Application Blocks, Windows Workflow Foundation, and Windows Communication Foundation), ASP.NET AJAX Programmer’s Reference with ASP. NET 2.0 or ASP.NET 3.5, Professional IIS7 and ASP.NET Integrated Programming, and Professional ASP.NET Server Control and Component Development. He has written articles on the ASP.NET, ADO.NET, .NET, and XML technologies for the industry’s leading magazines, such as Dr. Dobb’s Journal, asp.netPRO magazine, and Microsoft MSDN Online.
ffirs.indd vii
8/25/07 2:41:01 AM
ffirs.indd viii
8/25/07 2:41:02 AM
Credits Senior Acquisitions Editor
Production Manager
Jim Minatel
Tim Tate
Development Editor
Vice President and Executive Group Publisher
Brian MacDonald
Richard Swadley
Technical Editors
Vice President and Executive Publisher
Alexei Gorkov Darren J. Kindberg Sam Judson Dan Maharry Cody Reichenau
Joseph B. Wikert
Project Coordinator, Cover Adrienne Martinez
Proofreader Production Editor
Ian Golder
Eric Charbonneau
Indexer Copy Editors
Jack Lewis
Kathryn Duggan S. B. Kleinman
Anniversary Logo Design Richard Pacifico
Editorial Manager Mary Beth Wakefield
ffirs.indd ix
8/25/07 2:41:02 AM
ffirs.indd x
8/25/07 2:41:02 AM
Acknowledgments First and foremost, I would like to greatly thank Jim Minatel, the senior acquisitions editor on the book, for giving me the opportunity to work on this exciting project and for all his support and guidance throughout the process. Huge thanks go to Brian MacDonald, the book’s development editor. I greatly appreciate all your input, comments, and advice. Thanks, Brian, for everything! Special thanks go to the book’s technical editors; Alexei Gorkov, Darren J. Kindberg, Sam Judson, Dan Maharry and Cody Reichenau. Thank you gentlemen, for all your input and comments. Additional thanks go to Eric Charbonneau, the book’s production editor. Thanks also go to Kathi Duggan and S.B. Kleinman, the copy editors; as well as Ian Golder, the proofreader.
ffirs.indd xi
8/25/07 2:41:02 AM
ffirs.indd xii
8/25/07 2:41:02 AM
Contents Acknowledgments Introduction
Chapter 1: AJAX Technologies Google Suggest XMLHttpRequest XML JSON object array string number null, true, and false
ASP.NET AJAX Installing the ASP.NET AJAX Extensions and ASP.NET Futures Summary
Chapter 2: JavaScript Base Type Extensions ASP.NET AJAX Array Type Extensions add addRange clear clone contains enqueue and dequeue forEach indexOf insert parse remove removeAt
ASP.NET AJAX Boolean Type Extensions ASP.NET AJAX Date Type Extensions ASP.NET AJAX Object Type Extensions
ftoc.indd xiii
xi xxix
1 1 4 16 20 20 20 20 21 21
24 25 25
27 28 28 29 29 30 30 31 33 34 35 36 36 37
37 38 38
8/20/07 8:54:40 PM
Contents ASP.NET AJAX String Type Extensions endsWith startsWith trim Formatting
ASP.NET AJAX Error Type Extensions create popStackFrame Under the Hood of popStackFrame
Summary
Chapter 3: Built-In and Custom Exception Types ASP.NET AJAX Built-In Exception Types ArgumentException ArgumentNullException ArgumentOutOfRangeException ArgumentTypeException ArgumentUndefinedException InvalidOperationException NotImplementedException ParameterCountException
Implementing Custom Exception Types Recipe for Implementing Custom Exception Types Using the Recipe
Summary
Chapter 4: JavaScript Object-Oriented Programming and Type Reflection Extensions JavaScript Functions JavaScript Classes Type registerClass getName isClass registerNamespace isNamespace registerInterface getInterfaces isInterface Inheritance
Using WebRequest, WebRequestManager, and XMLHttpExecutor Summary
Chapter 13: Consuming Web Services Via Soap Messages Building the Web Service WSDL Documents Argument Names, Types, and Order Return Value Types and Order Describing the Method Describing the Communication Protocol for Accessing the Method Specifying the Site for Method Access Specifying the Method Class
SOAP Messages Summary
Chapter 14: Consuming Web Services Via JSON Messages WebServiceProxy Timeout Default Succeeded Callback Default Failed Callback Path Invoking a Web Method
Using WebServiceProxy WebServiceError Using WebServiceError Calling Page Methods Calling Custom Methods Under the Hood ScriptHandlerFactory RestHandlerFactory
479 479 479 480 482 483 484 484 484 485 486
487 510
511 511 512 514 515 515 516 517 518
518 533
535 535 535 536 536 537 537
549 553 557 561 564 570 571 574
xxi
ftoc.indd xxi
8/20/07 8:54:42 PM
Contents RestHandler HandlerWrapper Page Methods Demystified Web Services Bridges Demystified Using the Replicas
Summary
577 582 583 590 593
595
Chapter 15: Proxy Classes
597
What’s a Proxy, Anyway? Proxy Class
597 599
Proxy Classes Associated with Web Services Proxy Classes Associated with Page Methods Proxy Classes Associated with Custom Classes
Automatic Proxy Class Generation Declarative Approach Imperative Approach Parent/Child Pages
Under the Hood ScriptManager ServiceReference ClientProxyGenerator RestClientProxyHandler
Using the Replicas Summary
Chapter 16: Behaviors What is a Behavior, Anyway? The Behavior Class Properties Instance Methods Static Methods
ClickBehavior descriptor The click Event initialize Using the ClickBehavior
The ASP.NET AJAX Control Toolkit BehaviorBase The TextBoxWatermarkBehavior
Summary
600 605 608
608 608 618 621
623 624 627 630 648
650 658
659 659 661 668 672 674
675 676 677 677 678
680 681 687
706
xxii
ftoc.indd xxii
8/20/07 8:54:42 PM
Contents Chapter 17: Script and Extender Server Controls
707
Why You Need Script and Extender Server Controls Extender Server Controls
ResolveScriptReference Event Putting it All Together Developing a Custom Extender Server Control WatermarkText WatermarkCssClass ClientState ClientStateFieldID CreateClientStateField BehaviorID GetScriptReferences GetScriptDescriptors OnInit Page_PreLoad OnLoad
Contents OnPreRender Render Using the Extender Server Control
Developing a Script Control PreRender Render Using the Script Server Control
761 763 763
764 768 769 769
Script Server Controls versus Extender Server Controls Summary
770 771
Chapter 18: Web Services Bridges and Transformers
773
Amazon Web Services ItemSearch
Developing Web Services Bridge-Enabled Script Server Controls AspNetAjaxAmazonSearch AmazonSearchScriptControl HtmlGenerator HtmlGeneratorScriptControl Using the Components
Transformers Using Transformers XmlBridgeTransformer XsltBridgeTransformer
Children as Triggers Inclusion of One UpdatePanel in another UpdatePanel Using Triggers Imperative Update
Developing Partial-Rendering Enabled Custom Composite Server Controls BaseMasterDetailControl BaseMasterDetailControl2
Summary
863 864 877 878
881 882 906
910
xxiv
ftoc.indd xxiv
8/20/07 8:54:43 PM
Contents Chapter 20: Using UpdatePanel in User Controls and Custom Controls MasterDetailControl CreateBaseDataBoundControlMaster RegisterMasterEventHandlers Properties
Using MasterDetailControl in a Web Page MasterDetailControl2 CreateBaseDataBoundControlMaster RegisterMasterEventHandlers Master_SelectedIndexChanged Master_DataBound Properties
Using MasterDetailControl2 MasterDetailControl3 Using MasterDetailControl3 MasterDetailControl4 Developing Partial-Rendering-Enabled Data Control Fields Extending BoundField Overriding InitializeDataCell Handling the DataBound Event Extracting Values from Cells Appearance Properties Using MasterDetailField
Developing Partial-Rendering-Enabled User Controls Displaying all Messages Displaying the Details of a Message Deleting a Message Updating a Message Replying to a Message Starting a New Thread
Summary
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Processing a Request The Page Life Cycle The First Visit to a Partial-Page-Rendering-Enabled Web Page InitRecursive The OnInit Method of ScriptManager The OnInit Method of UpdatePanel Templated Controls
911 911 913 914 916
916 921 923 923 923 923 924
924 927 928 930 931 932 937 938 939 939 940
945 957 958 959 960 961 963
964
965 966 969 971 971 972 980 987
xxv
ftoc.indd xxv
8/20/07 8:54:43 PM
Contents LoadRecursive The Initialize Method of the UpdatePanel
Rendering The Render Method of ScriptManager The Render Method of the UpdatePanel
Summary
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager
995 998
1019 1020 1028
1029
1033
Instantiating and Initializing the Client-Side PageRequestManager
1034
The getInstance Method of the Client-Side PageRequestManager The Constructor of the Client-Side PageRequestManager Class The _initializeInternal Method of the Client-Side PageRequestManager
1036 1037 1040
_updateControls The _pageLoadedInitialLoad Method of the Client-Side PageRequestManager The _pageLoaded Method of the Client-Side PageRequestManager
The pageLoaded Event Using the pageLoaded Event
Making an Asynchronous Page Postback Helper Methods _doPostBack _onFormSubmit
The initializeRequest Event Using the initializeRequest Event
The beginRequest Event Using the beginRequest Event
Summary
Chapter 23: Asynchronous Partial Page Rendering: Server Side Processing RetrievePostData LoadScrollPosition InitRecursive The IsAsyncPostBackRequest Method of the PageRequestManager The OnInit Method of PageRequestManager
1046 1050 1050
1052 1055
1071 1071 1077 1081
1090 1092
1099 1101
1104
1105 1105 1109 1111 1111 1112
Load Post Data
1113
UpdatePanel
1117
ScriptManager The LoadPostData Method of PageRequestManager The Raise Post Data Changed Event
1117 1118 1120
xxvi
ftoc.indd xxvi
8/20/07 8:54:43 PM
Contents PreRender The OnPreRender Method of PageRequestManager
Rendering The Encode Method of PageRequestManager The RenderPageCallback Method of PageRequestManager
Server Response Summary
Chapter 24: Asynchronous Partial Page Rendering: Client-Side Processing Arrival of the Server Response Text The _updatePanel Method of PageRequestManager The registerDisposeScript Method of PageRequestManager _destroyTree _ScriptLoader readLoadedScripts getInstance queueScriptBlock queueCustomScriptTag isScriptLoaded _getLoadedScript queueScriptReference loadScripts _loadScriptsInternal _createScriptElement The Constructor of the _ScriptLoader Class _scriptLoaderHandler
_ScriptLoaderTask The Constructor of the_ScriptLoaderTask Class execute _scriptLoadHandler
Introduction Welcome to ASP.NET AJAX Programmer’s Reference with ASP.NET 2.0 or ASP.NET 3.5. The ASP.NET AJAX framework consists of two frameworks: the ASP.NET AJAX client-side framework and the ASP.NET AJAX server-side framework. It’s a well-known fact that client-side programming is very different from server-side programming. The main difference lies in the fact that client-side programming lacks a feature-rich programming framework like the ASP.NET/.NET framework. Wouldn’t be great if you could write your client-side code in a framework with programming styles and capabilities like those of the ASP.NET/.NET framework? Enter the ASP.NET AJAX client-side framework. It simulates the rich programming features of the ASP.NET/ .NET framework on the client side as much as possible. The capabilities of these simulations are only limited by the fundamental limitations of client-side technologies such as JavaScript. The ASP.NET AJAX server-side framework extends the ASP.NET Framework to provide server-side support for Ajax-enabled Web applications. The ASP.NET AJAX client-side and server-side frameworks work hand in hand to meet both the client-side and server-side needs of your Ajax-enabled applications. That said, the ASP.NET AJAX client-side framework can also work alongside server technologies other than the ASP.NET Framework. This book uses a unique approach characterized by the following attributes to provide you with an in-depth coverage of both the ASP.NET AJAX client-side and server-side frameworks:
❑
Practical real-world examples: The discussions in this book are presented in the context of numerous practical real-world examples that you can use in your own ASP.NET AJAX applications.
❑
Under-the-hood looks: This book takes you under the hood of both ASP.NET AJAX client-side and server-side frameworks, where you can see for yourself how they work from the inside out and how you can extend them to meet your application requirements.
❑
Code walkthroughs: I’ll use numerous code walkthroughs to help you gain the skills, experience, and knowledge you need to implement similar features in your own ASP.NET AJAX applications.
Who This Book Is For This book is aimed at the ASP.NET developer who wants to learn ASP.NET AJAX for the first time. No knowledge of ASP.NET AJAX is assumed.
flast.indd xxix
8/25/07 2:41:53 AM
Introduction
What This Book Covers This book is divided into 24 chapters and six appendices, as follows:
❑
Chapter 1, “Ajax Technologies,” provides an overview of the main technologies used in Ajaxenabled Web applications, such as XMLHttpRequest, XML, and JSON, in the context of examples.
❑
Chapter 2, “JavaScript Base Type Extensions,” explains the JavaScript base type extensions. You’ll learn how these extensions enhance the JavaScript base types such as Array, Boolean, Date, Error, Object, and String to enable you to experience these types — as much as possible — as you would their .NET counterparts.
❑
Chapter 3, “Built-In and Custom Exception Types,” first covers the ASP.NET AJAX built-in exception types, including ArgumentException, ArgumentNullException, ArgumentOutOfRangeException, ArgumentTypeException, ArgumentUndefinedException, InvalidOperationException, NotImplementedException, and ParameterCountException, in depth. Then it provides you with a recipe for developing custom exception types, uses this recipe to implement a custom exception type named DuplicateItemException, and implements a page that uses this custom exception type.
❑
Chapter 4, “JavaScript Object-Oriented Programming and Type Reflection Extensions,” first examines those JavaScript technologies that the ASP.NET AJAX object-oriented programming (OOP) and type reflection extensions use under the hood to extend JavaScript to add OOP and type reflection support. Then it provides a comprehensive coverage of the Type and its methods, where you’ll learn through numerous examples how to define namespaces, interfaces, classes, and enumeration types, how to implement classes that implement one or more interfaces, and how to implement classes that derives from other classes.
❑
Chapter 5, “Event Programming Extensions,” provides you with a detailed step-by-step recipe for implementing and adding events to your custom ASP.NET AJAX client classes to enable the clients of your classes to extend their functionality to execute application-specific logic. It then presents and discusses a practical example that uses this recipe. This chapter also describes the EventArgs, CancelEventArgs, and EventHandlerList classes and their methods and properties in detail.
❑
Chapter 6, “DOM Extensions,” shows you how the ASP.NET AJAX DOM extensions extend traditional DOM programming to add support for .NET-like methods and properties, and how to use these extensions in your own DOM programming. It covers the ASP.NET AJAX delegates and the DomElement and DomEvent client classes and their methods and properties.
❑
Chapter 7, “Component Development Infrastructure,” covers the ASP.NET AJAX component development infrastructure and its main constituent interfaces, including IDisposable, INotifyDisposing, INotifyPropertyChanged, and IContainer and its main constituent classes, including Component and Application. You’ll also learn through numerous examples how to implement these interfaces and how to implement a custom component that derives from the Component base class. This chapter also covers the application and component life cycles and application level events in detail.
❑
Chapter 8, “Developing Client Controls,” describes the Control, Label, Image, and HyperLink client controls and their methods and properties, and presents examples that use these client controls. This chapter also presents and discusses the implementation of a custom Image client control that extends the functionality of the ASP.NET AJAX Image client control.
xxx
flast.indd xxx
8/25/07 2:41:53 AM
Introduction ❑
Chapter 9, “Event Bubbling and Button Client Control,” first covers the CommandEventArgs event data class and the Button client control. Then it discusses ASP.NET AJAX event bubbling and shows you how to implement custom controls that bubble their events up to their parents, and how to implement custom controls that capture events bubbled up by their children. This chapter implements a client control named GridView, which uses ASP.NET AJAX event bubbling.
❑
Chapter 10, “Type Description Extensions,” provides comprehensive coverage of the TypeDescriptor class and ICustomTypeDescriptor interface, from which you’ll learn how to take advantage of the ASP.NET type description capabilities in your own applications in order to isolate your client code from the specifics of the types of the objects that your client code deals with. This will allow your code to interact with different types of objects without code change. This chapter implements three Web pages that you can use to generically inspect the properties, events, and methods of any ASP.NET AJAX type. This chapter also implements a custom client control named CustomTable that uses the ASP.NET AJAX type description capabilities to display any type of data records. Finally, this chapter shows you how to dynamically inject metadata information.
❑
Chapter 11, “Data Classes,” first discusses the IData interface and then dives into the ASP.NET AJAX DataColumn, DataRow, and DataTable data classes. It also implements a custom client control that can display data from any data source, such as DataTable, and that implements the IData interface.
❑
Chapter 12, “Client-Server Communications,” covers the client-server communications layer of the ASP.NET AJAX framework and its constituent classes, including detailed discussions of WebRequest, WebRequestExecutor, WebRequestManager, NetworkRequestEventArgs, and XMLHttpExecutor, and presents several examples that show you how to use these classes in your own ASP.NET AJAX applications.
❑
Chapter 13, “Consuming Web Services Via SOAP Messages,” first discusses WSDL documents and SOAP messages in detail and then presents an example that uses the classes in the clientserver communications layer of the ASP.NET AJAX framework to exchange SOAP messages with a Web service.
❑
Chapter 14, “Consuming Web Services Via JSON Messages,” provides in-depth coverage of the WebServiceProxy and WebServiceError classes and teaches you three different ways to invoke server-side methods from your client code: calling page methods, Web service methods, and Web services bridges. It also covers .asbx files in detail. This chapter then presents and implements fully functional replicas of the main components of the ASP.NET AJAX REST method call-request-processing infrastructure, including the ScriptHandlerFactory, RestHandlerFactory, RestHandler, HandlerWrapper, and ScriptModule classes, and implements an example in which these replicas are used. This chapter also uses these replicas to demystify page method calls and Web services bridges.
❑
Chapter 15, “Proxy Classes,” first covers proxy classes associated with page methods, Web services bridges, and Web services methods in detail. Next, it discusses ScriptManager and ScriptManagerProxy server controls and the role of ScriptManagerProxy server controls in parent/child page scenarios. This chapter then implements fully functional replicas of the main components of the ASP.NET AJAX automatic proxy-class-generation infrastructure, such as ScriptManager, ServiceReferenceCollection, ServiceReference, ClientProxyGenerator, and RestClientProxyHandler, and you’ll see for yourself how this infrastructure generates the proxy classes associated with page methods, Web services bridges, and Web services methods. This chapter then implements an example that uses these replicas.
xxxi
flast.indd xxxi
8/25/07 2:41:54 AM
Introduction ❑
Chapter 16, “Behaviors,” begins by providing in-depth coverage of the Behavior base class and its methods and properties, and shows you how to derive from this base class to implement your own custom behaviors. It then discusses the ASP.NET AJAX control toolkit behavior base class named BehaviorBase, and shows you how to derive from the BehaviorBase class to implement your own custom toolkit behavior.
❑
Chapter 17, “Script and Extender Server Controls,” implements fully functional replicas of those components of the ASP.NET AJAX server-side framework that are deeply involved in the internal functioning of two important types of server controls, known as script controls and extender controls, to help you gain a solid understanding of these server controls, how they interact with their associated client-side components, how they differ from one another, and how to implement your own custom script controls and extender controls. The components of the ASP.NET AJAX server-side framework whose replicas these chapter implements include IExtenderControl, ExtenderControl, IScriptControl, ScriptControl, ScriptDescriptor, ScriptComponentDescriptor, ScriptBehaviorDescriptor, ScriptControlDescriptor, ScriptReference, ResolveScriptReference, ScriptReferenceCollection, and ScriptManager. This chapter then implements custom script and extender server controls, and you’ll gain the skills you need to develop your own custom script and extender server controls.
❑
Chapter 18, “Web Services Bridges and Transformers,” first walks you through the implementation of a Web services bridge–enabled script server control that uses the Amazon Web services. Then it discusses ASP.NET AJAX transformers in detail, including XmlBridgeTransformer and XsltBridgeTransformer, and uses them to enhance the Web services bridge–enabled script server control. This chapter also shows you how to implement your own custom transformers.
❑
Chapter 19, “UpdatePanel and ScriptManager,” uses numerous examples in which you learn how to enable asynchronous partial page rendering, how to use triggers, and several different ways to conditionally update an UpdatePanel server control, including by setting its ChildrenAsTrigger property, by directly adding it to another UpdatePanel server control, by indirectly adding it to another UpdatePanel server control via a user control, by indirectly adding it to another UpdatePanel server control via a content page, and by explicitly calling its Update method from your code. This chapter then implements two base custom partial-page-rendering-enabled server controls named BaseMasterDetailControl and BaseMasterDetailControl2.
❑
Chapter 20, “Using UpdatePanel in User Controls and Custom Controls,” implements three custom partial-page-rendering-enabled server controls named MasterDetailControl, MasterDetailControl2, and MasterDetailControl3, a custom partial-page-renderingenabled data control field named MasterDetailField, and a partial-page-rendering-enabled threaded discussion forum user control. This chapter also implements pages that use these partial-page-rendering-enabled custom server controls, data control field, and user control.
❑
Chapter 21, “Page Life Cycle and Asynchronous Partial Page Rendering,” follows the Page object through its life cycle phases to process the first request to a partial-page-renderingenabled Web page to help you gain a solid understanding of the ASP.NET AJAX asynchronous partial-page-rendering infrastructure and its main components, such as the ScriptManager and server-side PageRequestManager, UpdatePanel, UpdatePanelTrigger, UpdatePanelControlTrigger, and AsyncPostBackTrigger classes. This chapter also implements a custom UpdatePanel server control named CustomUpdatePanel and a custom trigger named AsyncMultiPostBackTrigger.
xxxii
flast.indd xxxii
8/25/07 2:41:54 AM
Introduction ❑
Chapter 22, “ASP.NET AJAX Client-Side PageRequestManager,” first provides a comprehensive coverage of the instantiation and initialization process of the current client-side PageRequestManager instance, where you also learn about this instance’s pageLoaded event and its associated PageLoadedEventArgs event data class. It also shows an example in which this event is used. This chapter then dives into the process through which the current client-side PageRequestManager instance makes an asynchronous page postback request to the server, and you also learn about this instance’s initializeRequest and beginRequest events. It also shows examples in which you’ll learn how to use these events in your own ASP.NET AJAX applications.
❑
Chapter 23, “Asynchronous Partial Page Rendering: Server-Side Processing,” follows the Page object through its life cycle phases to process an asynchronous page postback request where you’ll learn about the role of the server-side PageRequestManager, RetrievePostData, ScriptManager, UpdatePanel, ScriptRegisterationManager, and triggers in generating the final response text. This chapter also implements a page that enables you to inspect the server response text.
❑
Chapter 24, “Asynchronous Partial Page Rendering: Client-Side Processing,” follows the client-side PageRequestManager instance through its life cycle phases to process the server response to an asynchronous page postback request where you’ll see for yourself how the current client-side PageRequestManager manages to parse the server response text, download the required scripts, and update the required UpdatePanel server controls on the client side. You’ll also learn about the pageLoading and endRequest events of the current client-side PageRequestManager instance and their associated PageLoadingEventArgs and EndRequestEventArgs event data classes. This chapter shows examples in which these events and their associated event data classes are used. It also covers the PageRequestManagerTimeoutException, PageRequestManagerServerErrorException, PageRequestManagerParserErrorException, and InvalidOperationException exceptions that the current client-side PageRequestManager instance raises. Finally, it implements a custom error handler and a page that uses this error handler.
❑
Appendix A, “XML Script,” provides comprehensive coverage of the ASP.NET AJAX xmlscript, which enables you to program declaratively with little or no imperative or procedural JavaScript code. This appendix covers the main components of the ASP.NET AJAX xml-script parsing infrastructure, such as MarkupContext and MarkupParser, and you’ll learn through numerous examples how to enable the clients of your client classes to declaratively instantiate and initialize instances of your classes in xml-script without writing any procedural JavaScript code. You’ll also learn how to extend the ASP.NET AJAX xml-script parsing infrastructure to add support for custom parsing of your own client classes.
❑
Appendix B, “Binding,” covers ASP.NET AJAX binding in detail. The BindingBase client class, built-in and custom transformers, and the Binding client class are discussed in depth.
❑
Appendix C, “Actions,” discusses the ASP.NET AJAX actions including the IAction client interface, the Action base class, actions in xml-script, and built-in actions such as InvokeMethodAction, SetPropertyAction, and PostBackAction in detail.
❑
Appendix D, “Data Control,” first provides a comprehensive coverage of the ASP.NET AJAX DataControl base class and its methods, properties, and events. Then it implements a custom data control named CustomTable that derives from the DataControl base class, and uses the ASP.NET AJAX type description capabilities to display any type of data records.
xxxiii
flast.indd xxxiii
8/25/07 2:41:55 AM
Introduction ❑
Appendix E, “Templated Controls,” first covers the ITemplate client interface, TemplateInstance client class, and Template client class in detail. Then it develops a custom template named TemplateField that derives from the Template class and supports its own parseFromMarkup static method, which tells the ASP.NET AJAX xml-script parsing infrastructure how to parse an instance of the TemplateField class declared in xml-script. Finally, it develops a custom templated data control that enables its clients to use TemplateField instances in xml-script to specify different types of HTML markup texts for rendering different types of database fields.
❑
Appendix F, “ListView,” begins by providing an overview of the ASP.NET AJAX ListView client control and its methods, properties, and events, and goes on to present examples in which this client control is used to display data records downloaded from a backend Web service. Then it dives into the internals of the ListView client control and its methods, properties, events, and surrounding classes and interfaces such as ITask, _TaskManager, and ListViewRenderTask. You’ll learn the skills you need to develop a custom templated data control as complex as the ListView client control.
What You Need To Use This Book You’ll need the following items to run the code samples in this book:
❑
ASP.NET AJAX Extensions 1.0
❑
ASP.NET Futures
❑
Windows Server 2003, Windows 2000, Windows XP, or Windows Vista
❑
Visual Studio 2005, Visual Studio 2005 Express Edition, Visual Studio 2008, or Visual Studio 2008 Express Edition
❑
SQL Server 2005 or SQL Server 2005 Express Edition
You can download free copies of Visual Studio 2005 Express Edition or Visual Studio 2008 Express Edition and SQL Server 2005 Express Edition from http://msdn.microsoft.com/vstudio/express/ and ASP.NET AJAX Extensions 1.0 and ASP.NET Futures from http://ajax.asp.net/downloads/.
Conventions To help you get the most from the text and keep track of what’s happening, we’ve used a number of conventions throughout the book.
Boxes like this one hold important, not-to-be forgotten information that is directly relevant to the surrounding text.
Tips, hints, tricks, and asides to the current discussion are offset and placed in italics like this.
xxxiv
flast.indd xxxiv
8/25/07 2:41:55 AM
Introduction As for styles in the text:
❑
We highlight new terms and important words when we introduce them.
❑
We show keyboard strokes like this: Ctrl+A.
❑
We show file names, URLs, and code within the text like so: persistence.properties.
❑
We present code in two different ways:
In code examples we highlight new and important code with a gray background. The gray highlighting is not used for code that’s less important in the present context, or that has been shown before.
Source Code As you work through the examples in this book, you may choose either to type in all the code manually or to use the source code files that accompany the book. All the source code used in this book is available for download at http://www.wrox.com. Once at the site, simply locate the book’s title (either by using the Search box or by using one of the title lists) and click the Download Code link on the book’s detail page to obtain all the source code for the book. Because many books have similar titles, you may find it easiest to search by ISBN; this book’s ISBN is 978-0-470-10998-4. Once you download the code, just decompress it with your favorite compression tool. Alternately, you can go to the main Wrox code download page at http://www.wrox.com/dynamic/books/download .aspx to see the code available for this book and all other Wrox books.
Errata We make every effort to ensure that there are no errors in the text or in the code. However, no one is perfect, and mistakes do occur. If you find an error in one of our books, like a spelling mistake or faulty piece of code, we would be very grateful for your feedback. By sending in errata you may save another reader hours of frustration and at the same time you will be helping us provide even higher-quality information. To find the errata page for this book, go to http://www.wrox.com and locate the title using the Search box or one of the title lists. Then, on the book details page, click the Book Errata link. On this page you can view all errata that have been submitted for this book and posted by Wrox editors. A complete book list including links to each’s book’s errata is also available at www.wrox.com/misc-pages/booklist.shtml. If you don’t spot “your” error on the Book Errata page, go to www.wrox.com/contact/techsupport .shtml and complete the form there to send us the error you have found. We’ll check the information and, if appropriate, post a message to the book’s errata page and fix the problem in subsequent editions of the book.
xxxv
flast.indd xxxv
8/25/07 2:41:56 AM
Introduction
P 2 P. WROX . COM For author and peer discussion, join the P2P forums at p2p.wrox.com. The forums are a Web-based system for you to post messages relating to Wrox books and related technologies and interact with other readers and technology users. The forums offer a subscription feature to e-mail you topics of interest of your choosing when new posts are made to the forums. Wrox authors, editors, other industry experts, and your fellow readers are present on these forums. At http://p2p.wrox.com you will find a number of different forums that will help you not only as you read this book, but also as you develop your own applications. To join the forums, just follow these steps:
1. 2. 3.
Go to p2p.wrox.com and click the Register link.
4.
You will receive an e-mail with information describing how to verify your account and complete the joining process.
Read the terms of use and click Agree. Complete the required information to join, as well as any optional information you wish to provide, and click Submit.
You can read messages in the forums without joining P2P, but in order to post your own messages you must join. Once you join, you can post new messages and respond to messages other users post. You can read messages at any time on the Web. If you would like to have new messages from a particular forum e-mailed to you, click the Subscribe to this Forum icon by the forum name in the forum listing. For more information about how to use the Wrox P2P, be sure to read the P2P FAQs for answers to questions about how the forum software works as well as many common questions specific to P2P and Wrox books. To read the FAQs, click the FAQ link on any P2P page.
xxxvi
flast.indd xxxvi
8/25/07 2:41:56 AM
AJAX Technologies Traditional Web pages use server-side technologies and resources to operate and deliver their features and services to end users. These Web pages require end users to perform full-page postbacks to the server, where these pages can run the required server-side code to deliver the requested service or feature. In other words, these Web pages use the click-and-wait, userunfriendly interaction pattern, which is characterized by waiting periods that disrupt user workflow and degrade the user experience. This click-and-wait user interaction pattern is what makes the traditional Web applications act and feel very different from their desktop counterparts. Asynchronous JavaScript And XML (abbreviated AJAX) is a popular Web application development approach that uses client-side technologies such as HTML, XHTML, CSS, DOM, XML, XSLT, Javascript, and asynchronous client-callback techniques such as XMLHttp requests and hidden-frame techniques to develop more sophisticated and responsive Web applications that break free from the click-and-wait pattern and, consequently, act and feel more like a desktop application. In other words, AJAX is closing the gap between Web applications and their desktop counterparts. This chapter begins by discussing the main characteristics of AJAX-enabled Web pages in the context of an example.
Google Suggest The Google Suggest Web page (www.google.com/webhp?complete=1) contains an AJAX-enabled search box that completes your search items as you type them in, as shown in Figure 1-1. Under the hood, this AJAX-enabled search box uses AJAX techniques to asynchronously download the required data from the Web server and to display them to the end user without interrupting the user’s interaction with the page. All the client-server communications are performed in the background as the end user types into the search box. An AJAX-enabled component such as the Google Suggest search box exhibits the following four important characteristics:
❑
c01.indd 1
It uses HTML, XHTML, CSS, DOM, and JavaScript client-side technologies to implement most of its functionalities where the code runs locally on the client machine to achieve the
8/20/07 5:40:00 PM
Chapter 1: AJAX Technologies
Figure 1-1 same response time as its desktop counterpart. This allows an AJAX-enabled component to break free from the click-and-wait user-interaction pattern.
❑
It uses asynchronous client-callback techniques such as XMLHttpRequest to communicate with the server. The main goal of this asynchronous communication model is to ensure that the communication with the server doesn’t interrupt what the user is doing. This asynchronous communication model is another step that allows an AJAX-enabled component to break free from the click-and-wait pattern.
❑
AJAX-enabled components normally send data to and receive data from the server in either XML or JSON format (discussed in detail later in this chapter). This characteristic enables the clientside code to exchange data with any type of server-side code, and vice versa, because almost all platforms have built-in support for reading, writing, and manipulating XML or JSON data.
❑
The asynchronous communication between the client-side code and the server-side code are normally governed by AJAX communication patterns. These patterns enable AJAX components to take full advantage of the asynchronous nature of the communication between the client-side code and the server-side code to determine the best time for uploading the data to or downloading the data from the server so the data exchange with the server won’t interrupt the user workflow and degrade the user experience.
In a traditional Web page, the end users trigger synchronous communications with the Web server, and they then have to wait until the required data is downloaded from the server and the entire page is
2
c01.indd 2
8/20/07 5:40:02 PM
Chapter 1: AJAX Technologies rendered all over again to display the new information. AJAX changes all that. As you can see in Figure 1-2, the Ajax engine takes complete control over the client-server communications and the rendering of the new information to ensure that these communications and renderings do not interrupt the user interactions.
Internet
Ajax Engine
JSON/XML Serializer Scheduler (XMLHttpRequest)
Renderer (DHTML)
Figure 1-2 As this figure shows, the AJAX engine consists of the following three main components:
❑
Scheduler: The scheduler uses AJAX technologies such as XMLHttpRequest to send data to and receive data from the server in an asynchronous fashion. As the name suggests, the scheduler schedules and makes the client requests to the server.
❑
Renderer: The renderer component of the AJAX engine uses DHTML to dynamically update only those portions of the current page that need refreshing without re-rendering or re-loading the entire page.
❑
JSON/XML Serializer: The client and server exchange data in JSON or XML format. The JSON/ XML serializer has two main responsibilities:
❑
Serialize the client data, which are JavaScript objects, into their JSON or XML representations before these objects are sent to the server
❑
Deserialize JavaScript objects from the JSON or XML data received from the server
3
c01.indd 3
8/20/07 5:40:02 PM
Chapter 1: AJAX Technologies This chapter provides an overview of the following client-side technologies that form the foundations of the above three main AJAX engine components in the context of an example:
❑
XMLHttpRequest
❑
DHTML
❑
XML
❑
JSON
XML HttpRequest XMLHttpRequest is one of the main AJAX technologies that the scheduler component of an AJAX
engine uses to make asynchronous requests to the server. The instantiation process of the XMLHttpRequest object is browser-dependent. Listing 1-1 encapsulates the browser-dependent nature of this instantiation process in a class named XMLHttpRequest.
Listing 1-1: Instantiating XMLHttpRequest if (!window.XMLHttpRequest) { window.XMLHttpRequest = function window$XMLHttpRequest() { var progIDs = [ ‘Msxml2.XMLHTTP’, ‘Microsoft.XMLHTTP’ ]; for (var i = 0; i < progIDs.length; i++) { try { var xmlHttp = new ActiveXObject(progIDs[i]); return xmlHttp; } catch (ex) {} } return null; } }
This script first checks whether the window object already contains a definition for this class. If not, it defines the constructor of the class. The constructor contains the following array of program ids: var progIDs = [ ‘Msxml2.XMLHTTP’, ‘Microsoft.XMLHTTP’ ];
This array covers all the possible instantiation scenarios on Internet Explorer. The constructor iterates through the program ids array and takes the following steps for each enumerated program id:
1. 2. 3.
It instantiates an ActiveXObject, passing in the enumerated program id. If the instantiation succeeds, it returns this ActiveXObject instance. If the instantiation fails, the try block throws an exception, which the catch block catches and forces the loop to move to the next iteration, where the next program id is used.
4
c01.indd 4
8/20/07 5:40:03 PM
Chapter 1: AJAX Technologies The XMLHttpRequest object exposes the following methods and properties:
❑
open: This method takes up to five parameters, but only the first two parameters are required. The first required parameter is a string that contains the HTTP verb (POST or GET) being used to make the request to the server. The second required parameter is a string that contains the target URL, which is the URL of the resource for which the request is made. The third optional parameter is a Boolean value that specifies whether the request is asynchronous. If you don’t specify a value for this parameter, it defaults to true. The fourth and fifth optional parameters specify the requester’s credentials — the username and password.
❑
readyState: The XMLHttpRequest exposes an integer property named readyState with possible values of 0, 1, 2, 3, or 4. The XMLHttpRequest goes through different states during its
lifecycle, and each state is associated with one of these five possible values.
❑
onreadystatechange: You must assign a reference to a JavaScript function to this property. The XMLHttpRequest invokes this JavaScript function every time its state changes, which is every time its readyState property changes value. Every time your JavaScript function is invoked, it must check the value of the XMLHttpRequest’s readyState property to determine the state of the XMLHttpRequest. The current request is completed only when XMLHttpRequest enters the state associated with the readyState property value of 4. As a result, the typical implementation of the JavaScript function assigned to the onreadystatechange property is as follows: function readyStateChangeCallback() { if (request.readyState == 4 && request.status == 200) { // Process the server response here } }
The global variable named request in this code fragment references the XMLHttpRequest object. This JavaScript function checks whether the readyState property of the XMLHttpRequest is 4, meaning the request is completed. If so, it processes the server response. If not, it simply returns.
❑
status: This property contains the HTTP status code of the server response. The JavaScript function that you assign to the onreadystatechange property must also check whether the status property of the XMLHttpRequest is 200, as shown in the boldface portion of the following code fragment. If the status code is a not 200, this is an indication that a server-side error has occurred. function readyStateChangeCallback() { if (request.readyState == 4 && request.status == 200) { // Process the server response here } }
Strictly speaking, any status code within the 200–299 range is considered a success. However, a status code of 200 is good enough in this case.
5
c01.indd 5
8/20/07 5:40:04 PM
Chapter 1: AJAX Technologies ❑
statusText: This property contains the HTTP status text of the server response. The text describes the HTTP status code. For example, the status text for status code 200 is OK.
❑
setRequestHeader: This method sets a specified HTTP request header to a specified value. As such, this method takes two parameters: the first parameter is a string that contains the name of the HTTP request header whose value is being set, and the second parameter is a string that contains the value of this HTTP request header.
❑
send: This is the method that actually sends the request to the server. It takes a string parameter that contains the request body. If you’re making a GET HTTP request, pass null as the value of this parameter. If you’re making a POST HTTP request, generate a string that contains the body of the request and pass this string into the send method.
❑
responseText: This property contains the server response in text format.
❑
responseXML: This property contains the server response in XML format (an XML Document to be exact). This property is set only when the Content-Type response header is set to the value text/xml. If the server-side code does not set the response header to this value, the responseXML property will be null even when the actual data is in XML format. In such cases, you must load the content of the responseText property into an XML document before you can use the client-side XML API to read the XML data.
The overrideMimeType property of XMLHttpRequest in Mozilla browsers enables you to override the MIME type of the server response. However, this is a browser-specific issue that the current discussion does not need to address.
❑
getResponseHeader: This method returns the value of a response header with a specified
name. As such, it takes the name of the response header as its only argument.
❑
getAllResponseHeaders: This method returns the names and values of all response headers.
❑
abort: Use this method to abort a request.
Listing 1-2 presents an example that uses XMLHttpRequest to make an asynchronous request to the server. If you access this page, you see the result shown in Figure 1-3. This page consists of a simple user interface with two text boxes and a button. If you enter the text “username” in the top text box and the text “password” in the bottom text box and then click the button, you get the result shown in Figure 1-4.
Listing 1-2: A page that uses XMLHttpRequest void Page_Load(object sender, EventArgs e) { if (Request.Headers[“MyCustomHeader”] != null) { if (Request.Form[“passwordtbx”] == “password” && Request.Form[“usernametbx”] == “username”) { Response.Write(“Shahram|Khosravi|22223333|Some Department|”); Response.End(); } else
6
c01.indd 6
8/20/07 5:40:04 PM
Chapter 1: AJAX Technologies throw new Exception(“Wrong credentials”); } } Untitled Page var request; if (!window.XMLHttpRequest) { window.XMLHttpRequest = function window$XMLHttpRequest() { var progIDs = [ ‘Msxml2.XMLHTTP’, ‘Microsoft.XMLHTTP’ ]; for (var i = 0; i < progIDs.length; i++) { try { var xmlHttp = new ActiveXObject(progIDs[i]); return xmlHttp; } catch (ex) {} } return null; } } window.employee = function window$employee(firstname, lastname, employeeid, departmentname) { this.firstname = firstname; this.lastname = lastname; this.employeeid = employeeid; this.departmentname = departmentname } function deserialize() { var delimiter=”|”; var responseIndex = 0; var delimiterIndex; var response = request.responseText; delimiterIndex = response.indexOf(delimiter, responseIndex); var firstname = response.substring(responseIndex, delimiterIndex); responseIndex = delimiterIndex + 1; delimiterIndex = response.indexOf(delimiter, responseIndex); var lastname = response.substring(responseIndex, delimiterIndex); responseIndex = delimiterIndex + 1; delimiterIndex = response.indexOf(delimiter, responseIndex);
(continued)
7
c01.indd 7
8/20/07 5:40:05 PM
Chapter 1: AJAX Technologies Listing 1-2 (continued) var employeeid = response.substring(responseIndex, delimiterIndex); responseIndex = delimiterIndex + 1; delimiterIndex = response.indexOf(delimiter, responseIndex); var departmentname = response.substring(responseIndex, delimiterIndex); return new employee(firstname, lastname, employeeid, departmentname); } function readyStateChangeCallback() { if (request.readyState == 4 && request.status == 200) { var credentials = document.getElementById(“credentials”); credentials.style.display=”none”; var employeeinfotable = document.getElementById(“employeeinfo”); employeeinfotable.style.display=”block”; var employee = deserialize(); var firstnamespan = document.getElementById(“firstname”); firstnamespan.innerText = employee.firstname; var lastnamespan = document.getElementById(“lastname”); lastnamespan.innerText = employee.lastname; var employeeidspan = document.getElementById(“employeeid”); employeeidspan.innerText = employee.employeeid; var departmentnamespan = document.getElementById(“departmentname”); departmentnamespan.innerText = employee.departmentname; } } window.credentials = function window$credentials(username, password) { this.username = username; this.password = password; } function serialize(credentials) { var requestBody=””; requestBody += “usernametbx”; requestBody += “=”; requestBody += encodeURIComponent(credentials.username); requestBody += “&”; requestBody += “passwordtbx”; requestBody += “=”; requestBody += encodeURIComponent(credentials.password); return requestBody; } function submitCallback()
8
c01.indd 8
8/20/07 5:40:05 PM
Chapter 1: AJAX Technologies { var var var var
usernametbx = document.getElementById(“usernametbx”); passwordtbx = document.getElementById(“passwordtbx”); credentials1= new credentials(usernametbx.value, passwordtbx.value); body = serialize(credentials1);
Note that Listing 1-2 registers a JavaScript function named submitCallback as an event handler for the click event of the button. This function encapsulates the logic that schedules and makes the asynchronous request to the server. This logic is what is referred to as the Scheduler in Figure 1-2.
10
c01.indd 10
8/20/07 5:40:06 PM
Chapter 1: AJAX Technologies Now let’s walk through the submitCallback function in the listing. First, submitCallback calls the getElementbyId method on the document object to return a reference to the username text box DOM element: var usernametbx = document.getElementById(“usernametbx”);
Next, it calls the getElementById method again to return a reference to the password text box DOM element: var passwordtbx = document.getElementById(“passwordtbx”);
Next, it creates an instance of a class named credentials: var credentials1 = new credentials(usernametbx.value, passwordtbx.value);
Listing 1-2 defines the credentials class as follows: window.credentials = function window$credentials(username, password) { this.username = username; this.password = password; }
The next order of business is to serialize this credentials object into a format that the server-side code understands. This is exactly what the following JavaScript function named serialize does: var body = serialize(credentials1);
This function basically contains the logic referred to as the Serializer in Figure 1-2. The serialize function is discussed in more detail shortly, but for now it suffices to say that this function serializes the specified credentials object into a string with a specific format. Next, the submitCallback function creates an instance of the XMLHttpRequest class previously defined in Listing 1-1: request = new XMLHttpRequest();
As previously discussed, this class encapsulates the browser-dependent logic that instantiates the appropriate object. Then, the submitCallback function invokes the open method on this XMLHttpRequest object, passing in two parameters. The first parameter is the string “POST” because the function is making a POST HTTP request to the server. The second parameter is the value of the action property of the form element. The action property contains the URL of the current page. The page is basically posting back to itself in asynchronous fashion. request.open(“POST”, document.form1.action);
11
c01.indd 11
8/20/07 5:40:07 PM
Chapter 1: AJAX Technologies Next, submitCallback assigns a reference, which references a JavaScript function named readyStateChangeCallback, to the onreadystatechange property of the XMLHttpRequest object: request.onreadystatechange = readyStateChangeCallback;
Then, it invokes the setRequestHeader method on the XMLHttpRequest object to add a custom header named MyCustomHeader with the value true: request.setRequestHeader(“MyCustomHeader”, “true”);
As you’ll see later, when the page finally posts back to itself, the server-side code uses this header to distinguish between ansynchronous and normal synchronous postback requests. Next, the submitCallback function invokes the setRequestHeader method again, this time to set the value of the Content-Type header request to application/x-www-form-urlencoded: request.setRequestHeader(‘Content-Type’, ‘application/x-www-form-urlencoded’);
As you’ll see later, this will allow you to use the Request object to access the posted data. Finally, submitCallback invokes the send method on the XMLHttpRequest object, passing in the string that contains the post data to make an HTTP POST request to the server: request.send(body);
As previously discussed, this string is the return value of the serialize method. Now let’s walk through the implementation of the serialize function: function serialize(credentials) { var requestBody=””; requestBody += “usernametbx”; requestBody += “=”; requestBody += encodeURIComponent(credentials.username); requestBody += “&”; requestBody += “passwordtbx”; requestBody += “=”; requestBody += encodeURIComponent(credentials.password); return requestBody; }
The serialize function generates a string that consists of two substrings separated by the & character. The first substring itself consists of two substrings separated by the equal sign (=), where the first substring contains the name HTML attribute value of the username text box DOM element and the second substring contains the value that the end user has entered into this text box: var requestBody = ””; requestBody += “usernametbx”; requestBody += “=”; requestBody += usernametbx.value;
12
c01.indd 12
8/20/07 5:40:07 PM
Chapter 1: AJAX Technologies The second substring itself consists of two substrings separated by the equal sign (=), where the first substring contains the name HTML attribute value of the password text box DOM element and the second substring contains the value that the end user has entered into this text box: requestBody += “passwordtbx”; requestBody += “=”; requestBody += passwordtbx.value;
When this HTTP POST request arrives at the server, ASP.NET automatically loads the body of the request into the Request object’s Form collection property because the Content-Type request header is set to the value application/x-www-form-urlencoded. When the Page_Load method shown in Listing 1-2 is finally invoked, it first checks whether the current request contains an HTTP header named MyCustomHeader: if (Request.Headers[“MyCustomHeader”] != null)
If so, this is an indication that the current page postback is an asynchronous page postback and, consequently, the Page_Load method first validates the user’s credentials. To keep the current discussion focused, this method hardcodes the valid credentials as shown here: if (Request.Form[“passwordtbx”] == “password” && Request.Form[“usernametbx”] == “username”)
If the validation succeeds, Page_Load generates a string that contains the server data (which is again hardcoded to keep this discussion focused), invokes the Write method on the Response object to write this string into the response output stream, and invokes the End method on the Response object to end the current response and, consequently, to send the server response to the client: Response.Write(“Shahram|Khosravi|22223333|Some Department|”); Response.End();
Ending the current response ensures that the current page will not go through its normal rendering routine where it renders the entire page all over again. That is the reason behind adding the custom HTTP request header “MyCustomHeader”. The arrival of the server response changes the state of the XMLHttpRequest object to the completed state, which in turn changes the value of the readyState property of the object to 4. This change in value automatically invokes the readyStateChangeCallback JavaScript function assigned to the onreadystatechange property of the object. The readyStateChangeCallback JavaScript function encapsulates the logic that uses DHTML to dynamically update those portions of the page that need refereshing without re-rendering and reloading the entire page all over again. This logic is what is referred to as the Renderer in Figure 1-2. The readyStateChangeCallback JavaScript function first checks whether the readyState and status properties of the XMLHttpRequest object are set to 4 and 200, respectively. If so, it invokes the getElementById method on the document object to return a reference to the table DOM element that
13
c01.indd 13
8/20/07 5:40:08 PM
Chapter 1: AJAX Technologies displays the login dialog box, and sets the display property of this DOM element’s style property to none to hide the dialog box: var credentials = document.getElementById(“credentials”); credentials.style.display=”none”;
Next, readyStateChangeCallback invokes the getElementById method again, this time to return a reference to the table DOM element that displays the server data, and sets the display property of this DOM element’s style property to block to show this DOM element: var employeeinfotable = document.getElementById(“employeeinfo”); employeeinfotable.style.display=”block”;
Then, it invokes the responseText property on the XMLHttpRequest object to return a string that contains the server data: var response = request.responseText;
Keep in mind that the server data is in the following format: Shahram|Khosravi|22223333|Some Department|
The next order of business is to deserialize an employee object from the server data. The following excerpt from Listing 1-2 defines the employee class: window.employee = function window$employee(firstname, lastname, employeeid, departmentname) { this.firstname = firstname; this.lastname = lastname; this.employeeid = employeeid; this.departmentname = departmentname }
As you can see in the following excerpt from Listing 1-2, the readyStateChangeCallback function invokes a JavaScript function named deserialize: var employee = deserialize();
This deserialize JavaScript function encapsulates the logic that deserializes an employee object from the server data (described in more detail later). This logic is what is referred to as the Serializer in Figure 1-2. Next, the readyStateChangeCallback function uses DHTML to update the relevant parts of the page with employee information in the employee object. First, it calls the getElementyById method on the document object to return a reference to the DOM element with the id HTML attribute of
14
c01.indd 14
8/20/07 5:40:08 PM
Chapter 1: AJAX Technologies firstname, and assigns the firstname property of the employee object to the innerText property of this DOM element to display the first name of the employee: var firstnamespan = document.getElementById(“firstname”); firstnamespan.innerText = employee.firstname;
Next, it calls the getElementyById method again, this time to return a reference to the DOM element with the id HTML attribute of lastname, and assigns the lastname property of the employee object to the innerText property of this DOM element to display the last name of the employee: var lastnamespan = document.getElementById(“lastname”); lastnamespan.innerText = employee.lastname;
It then repeats the same process to display the employee’s id and department name: var employeeidspan = document.getElementById(“employeeid”); employeeidspan.innerText = employee.employeeid; var departmentnamespan = document.getElementById(“departmentname”); departmentnamespan.innerText = employee.departmentname;
As mentioned, the deserialize JavaScript function deserializes an employee object from the server data: function deserialize(response) { var delimiter=”|”; var responseIndex = 0; var delimiterIndex; delimiterIndex = response.indexOf(delimiter, responseIndex); var firstname = response.substring(responseIndex, delimiterIndex); responseIndex = delimiterIndex + 1; delimiterIndex = response.indexOf(delimiter, responseIndex); var lastname = response.substring(responseIndex, delimiterIndex); responseIndex = delimiterIndex + 1; delimiterIndex = response.indexOf(delimiter, responseIndex); var employeeid = response.substring(responseIndex, delimiterIndex); responseIndex = delimiterIndex + 1; delimiterIndex = response.indexOf(delimiter, responseIndex); var departmentname = response.substring(responseIndex, delimiterIndex); return new employee(firstname, lastname, employeeid, departmentname); }
The deserialize function basically contains the logic that knows how to parse a string with the following format into an employee object: Shahram|Khosravi|22223333|Some Department|
15
c01.indd 15
8/20/07 5:40:08 PM
Chapter 1: AJAX Technologies
XML As you saw earlier, Listing 1-2 contains a JavaScript function named serialize that serializes a given credentials object into a string with the following format before this object is sent over the wire to the server: usernametbx=username&passwordtbx=password
Listing 1-2 also contains a JavaScript function named deserialize that deserializes an employee object from a string with the following format: Shahram|Khosravi|22223333|Some Department|
The serialize and deserialize methods encapsulate the logic that was referred to as the Serializer in Figure 1-2. The great thing about the XML format is that the server- and client-side technologies provide built-in support for serializing objects into XML and deserializing objects from XML. Listing 1-3 presents a new version of Listing 1-2 where the Page_Load server-side method serializes the server data into XML, which is then sent over the wire to the client, where the deserialize JavaScript function deserializes an employee object from the XML.
Listing 1-3: A version of Listing 1-2 that uses XML format void Page_Load(object sender, EventArgs e) { if (Request.Headers[“MyCustomHeader”] != null) { if (Request.Form[“passwordtbx”] == “password” && Request.Form[“usernametbx”] == “username”) { string xml=””; using (StringWriter sw = new StringWriter()) { XmlWriterSettings settings = new XmlWriterSettings(); settings.Indent = true; settings.OmitXmlDeclaration = true; using (XmlWriter xw = XmlWriter.Create(sw, settings)) { xw.WriteStartDocument(); xw.WriteStartElement(“employeeInfo”); xw.WriteElementString(“firstName”, “Shahram”); xw.WriteElementString(“lastName”, “Khosravi”); xw.WriteElementString(“employeeId”, “22223333”); xw.WriteElementString(“departmentName”, “Some Department”); xw.WriteEndElement();
16
c01.indd 16
8/20/07 5:40:09 PM
Chapter 1: AJAX Technologies xw.WriteEndDocument(); } xml = sw.ToString(); } Response.ContentType = ”text/xml”; Response.Write(xml); Response.End(); } else throw new Exception(“Wrong credentials”); } } Untitled Page var request; if (!window.XMLHttpRequest) { // Same as Listing 2 } window.employee = function window$employee(firstname, lastname, employeeid, departmentname) { // Same as Listing 2 } function deserialize() { var response = request.responseXML; var employeeInfo = response.documentElement; var firstNameElement = employeeInfo.childNodes[0]; var firstname = firstNameElement.firstChild.nodeValue; var lastNameElement = employeeInfo.childNodes[1]; var lastname = lastNameElement.firstChild.nodeValue; var employeeIdElement = employeeInfo.childNodes[2]; var employeeid = employeeIdElement.firstChild.nodeValue; var departmentNameElement = employeeInfo.childNodes[3]; var departmentname = departmentNameElement.firstChild.nodeValue; return new employee(firstname, lastname, employeeid, departmentname); } function readyStateChangeCallback() { // Same as Listing 2 } window.credentials = function window$credentials(username, password)
(continued)
17
c01.indd 17
8/20/07 5:40:09 PM
Chapter 1: AJAX Technologies Listing 1-3 (continued) { // Same as Listing 2 } function serialize(credentials) { // Same as Listing 2 } function submitCallback() { // Same as Listing 2 }
Now let’s walk through the implementations of the Page_Load server-side method and the deserialize JavaScript function in this listing, starting with the Page_Load method. The Page_Load method begins by instantiating a StringWriter into which the XML data will be written: string xml = ””; using (StringWriter sw = new StringWriter())
Then it instantiates an XmlWriterSettings object that specifies the settings for the XML document. In this case, the XML document will be indented and it will not contain the XML declaration: XmlWriterSettings settings = new XmlWriterSettings(); settings.Indent = true; settings.OmitXmlDeclaration = true;
Next, it instantiates an XmlWriter object with the specified settings and wraps the StringWriter. In other words, this XmlWriter will write the XML into the StringWriter: using (XmlWriter xw = XmlWriter.Create(sw, settings))
Then, it invokes the WriteStartDocument method on the XmlWriter to mark the beginning of the XML document: xw.WriteStartDocument();
18
c01.indd 18
8/20/07 5:40:10 PM
Chapter 1: AJAX Technologies Next, it invokes the WriteStartElement method on the XmlWriter to write a new element named employeeInfo into the XmlWriter, which in turn writes this element into the StringWriter: xw.WriteStartElement(“employeeInfo”);
This element will act as the document element of the XML document. Every XML document must have a single element known as the document element that encapsulates the rest of the XML document. Page_Load then invokes the WriteElementString method four times to write three elements named firstName, lastName, employeeId, and departmentName with the specified values into the XmlWriter, which in turn writes these elements into the StringWriter: xw.WriteElementString(“firstName”, “Shahram”); xw.WriteElementString(“lastName”, “Khosravi”); xw.WriteElementString(“employeeId”, “22223333”); xw.WriteElementString(“departmentName”, “Some Department”);
Next, Page_Load invokes the ToString method on the StringWriter to return a string that contains the entire XML document: xml = sw.ToString();
Then, it sets the Content-Type HTTP response header to the value text/xml to signal the client code that the server response contains XML data: Response.ContentType=”text/xml”;
Next, it writes the string that contains the XML data into the server response output stream: Response.Write(xml);
Finally, it invokes the End method on the Response object to end the response right away and, consequently, to send the XML document to the client, bypassing the normal rendering routine of the current page: Response.End();
Now let’s walk through the implementation of the deserialize JavaScript function in Listing 1-3. This function invokes the responseXML property on the XMLHttpRequest object to return the XML document: var response = request.responseXML; var employeeInfo = response.documentElement;
Then, it uses the XML API to extract the employee’s firstname, lastname, employeeid, and departmentname from the XML document:
19
c01.indd 19
8/20/07 5:40:10 PM
Chapter 1: AJAX Technologies var firstNameElement = employeeInfo.childNodes[0]; var firstname = firstNameElement.firstChild.nodeValue; var lastNameElement = employeeInfo.childNodes[1]; var lastname = lastNameElement.firstChild.nodeValue; var employeeIdElement = employeeInfo.childNodes[2]; var employeeid = employeeIdElement.firstChild.nodeValue; var departmentNameElement = employeeInfo.childNodes[3]; var departmentname = departmentNameElement.firstChild.nodeValue;
Finally, it instantiates and returns an employee object with the returned firstname, lastname, employeeid, and departmentname: return new employee(firstname, lastname, employeeid, departmentname);
JSON One of the main tasks in an AJAX-enabled application is to serialize client/server-side objects into the appropriate format before data is sent over the wire and to deserialize client/server-side objects from an appropriate format after data is received over the wire. In general there are two common data-interchange formats: XML and JSON. XML format was discussed in the previous section. Now let’s move on to the second common data-interchange format: JSON. JavaScript Object Notation (JSON) is a data-interchange format based on a subset of the JavaScript language. The following sections present the fundamental JSON concepts and terms.
object A JSON object is an unordered, comma-separated list of name/value pairs enclosed within a pair of braces. The name and value parts of each name/value pair are separated by a colon (:). The name part of each name/value pair is a string; and the value part is an array, another object, a string, a number, true, false, or null.
array A JSON array is an ordered, comma-separated list of values enclosed within a pair of square brackets ([ ]). Each value is an array, another object, a string, a number, true, false, or null.
string A JSON string is a collection of zero or more Unicode characters enclosed within double quotes (“ “). You must use a JSON string to represent a single character, and the character must be in double quotes. You must use the backslash character (\) to escape the following characters:
❑
Quotation mark (\")
❑
Solidus (\/)
20
c01.indd 20
8/20/07 5:40:11 PM
Chapter 1: AJAX Technologies ❑
Reverse solidus (\\)
❑
Backspace (\b)
❑
Formfeed (\f)
❑
Newline (\n)
❑
Carriage return (\r)
❑
Horizontal tab (\t)
number A JSON number is very similar to a C# number with one major exception: JSON does not support octal and hexadecimal formats.
null, true, and false JSON supports null, true, and false as valid values. JSON is a simple-yet-powerful, data-interchange format. It has the same hierarchical nature as XML, without the extra angle brackets, as shown in the following example: { “departments”:[ {“departmentName”:”department1”, “departementManager”:{“name”:”someName1”, “employeeID”:1, “managesMultipleDepts”:true }, “sections”:[ {“sectionName”:”section1”, “sectionManager”:{“name”:”someName2”, “employeeID”:2 }, “employees”:[ {“name”:”someName3”, “employeeID”:3 }, {“name”:”someName4”, “employeeID”:4 } ] }, {“sectionName”:”section2”, “sectionManager”:{“name”:”someName5”, “employeeID”:5 }, “employees”:[ {“name”:”someName6”, “employeeID”:6 },
One of the great things about JSON is that JavaScript provides easy, built-in support for parsing a JSON representation, as shown in Listing 1-4. This example is a version of Listing 1-2 that uses JSON.
Listing 1-4: A version of Listing 1-2 that uses JSON void Page_Load(object sender, EventArgs e) { if (Request.Headers[“MyCustomHeader”] != null) { if (Request.Form[“passwordtbx”] == “password” && Request.Form[“usernametbx”] == “username”) { string json=”{\”firstname\”: \”Shahram\”,”; json += “\”lastname\”: \”Khosravi\”,”; json += “\”employeeid\”: 22223333,”; json += “\”departmentname\”: \”Some Department\”}”; Response.Write(json); Response.End(); } else throw new Exception(“Wrong credentials”); } } Untitled Page var request; if (!window.XMLHttpRequest) { // Same as Listing 2 } function readyStateChangeCallback() { if (request.readyState == 4 && request.status == 200) {
22
c01.indd 22
8/20/07 5:40:11 PM
Chapter 1: AJAX Technologies var credentials = document.getElementById(“credentials”); credentials.style.display=”none”; var employeeinfotable = document.getElementById(“employeeinfo”); employeeinfotable.style.display=”block”; var response = request.responseText; eval(“var employee = ” + response + “;”); var firstnamespan = document.getElementById(“firstname”); firstnamespan.innerText = employee.firstname; var lastnamespan = document.getElementById(“lastname”); lastnamespan.innerText = employee.lastname; var employeeidspan = document.getElementById(“employeeid”); employeeidspan.innerText = employee.employeeid; var departmentnamespan = document.getElementById(“departmentname”); departmentnamespan.innerText = employee.departmentname; } } window.credentials = function window$credentials(username, password) { // Same as Listing 2 } function serialize(credentials) { // Same as Listing 2 } function submitCallback() { // Same as Listing 2 } // Same as Listing 2
In this listing, the Page_Load method generates a string that contains the JSON representation of the employee object. This method writes the JSON representation into the response output stream and ends the response as usual: string json=”{\”firstname\”: \”Shahram\”,”; json += “\”lastname\”: \”Khosravi\”,”; json += “\”employeeid\”: 22223333,”; json += “\”departmentname\”: \”Some Department\”}”; Response.Write(json); Response.End();
23
c01.indd 23
8/20/07 5:40:12 PM
Chapter 1: AJAX Technologies Things are pretty simple on the client side, as you can see in the following code fragment from Listing 1-4: var response = request.responseText; eval(“var employee=” + response + “;”);
This simply calls the eval JavaScript function to deserialize an employee object in the JSON string received from the server. As you can see, the messy XML deserialization code presented in Listing 1-3 is all gone and replaced with a simple call into the eval JavaScript function. However, this simplicity comes with a price. Because the eval JavaScript function basically trusts the scripts that it runs, it introduces serious security issues. This is not a problem in this example because the JSON representation is coming from a trusted server. However, in general, you must be very careful about what gets passed into eval.
ASP.NET AJAX The ASP.NET AJAX framework brings to the world of AJAX-enabled Web application development what ASP.NET and the .NET Framework brought to the world of server-side Web application development over the past few years. The biggest advantage of ASP.NET over the earlier server-side Web development technologies such as the classic ASP is that you get to program in the .NET Framework, which provides the following benefits among many others:
❑
The .NET Framework is a full-fledged, object-oriented framework that enables you to take full advantage of all the well-known benefits of object-oriented programming such as classes, interfaces, namespaces, polymorphism, inheritance, and the like.
❑
The .NET Framework comes with a large set of managed classes with convenient methods, properties, and events that save you from having to write lots of infrastructure and generic code that have nothing to do with the specifics of your application.
❑
The .NET Framework includes a full-fledged typing and type-reflection system that enables you to perform runtime type inspections, discoveries, instantiations, invocations, and the like.
❑
The .NET Framework provides you with groundbreaking facilities and capabilities such as the following:
❑
Application lifecycle and its events: The HttpApplication object that represents an ASP.NET application goes through a set of steps or phases collectively known as the application lifecycle. This object raises events before and/or after each lifecycle phase to allow you to customize the application lifecycle.
❑
Page lifecycle and its events: Every ASP.NET page goes through a set of steps or phases collectively known as the page lifecycle. The Page object that represents the ASP.NET page raises events before and/or after each lifecycle phase to allow you to customize the page lifecycle.
❑
Server controls: Server controls enable you to program against the underlying markup using the .NET Framework and its rich, object-oriented class library. This gives you the same programming experience as these server controls desktop counterparts provide.
24
c01.indd 24
8/20/07 5:40:12 PM
Chapter 1: AJAX Technologies ❑
Control architecture: Every server control goes through a set of steps or phases collectively known as the control lifecycle, and raises events before and/or after each lifecycle phase to allow you to customize the control lifecycle.
❑
Declarative programming: The ASP.NET declarative programming enables you to program declaratively without writing a single line of imperative code. The ASP.NET runtime automatically parses the declarative code, dynamically generates the associated imperative code, dynamically compiles the imperative code, caches the compiled imperative code for future use, and instantiates and initializes the associated compiled .NET types.
Thanks to ASP.NET and the .NET Framework, the server-side Web application development world can take full advantage of these important programming benefits to enormously boost productivity and to write more reliable and architecturally sound programs. As you’ll see throughout this book, the ASP.NET AJAX framework provides similar programming benefits to developers of AJAX-enabled Web applications. The ASP.NET AJAX Framework consists of two frameworks: the ASP.NET AJAX client-side framework and the ASP.NET AJAX server-side framework. The ASP.NET AJAX server-side framework is an extension of the ASP.NET Framework, which provides all the server-side support that an AJAX-enabled Web application needs.
Installing the ASP.NET AJAX Extensions and ASP.NET Futures Make sure both the ASP.NET AJAX Extensions and ASP.NET Futures are installed on your computer. You can download free copies of the ASP.NET AJAX Extensions and ASP.NET Futures from the official Microsoft ASP.NET AJAX site at
Summar y This chapter first discussed the main AJAX technologies. Then it provided a brief description of the ASP. NET AJAX framework. As mentioned, the ASP.NET AJAX framework consists of two main frameworks: the ASP.NET AJAX client-side framework and ASP.NET AJAX server-side framework. The next chapter begins your journey of the ASP.NET AJAX client-side framework, where you’ll learn a great deal about the ASP.NET AJAX JavaScript base type extensions.
25
c01.indd 25
8/20/07 5:40:12 PM
c01.indd 26
8/20/07 5:40:13 PM
JavaScript Base Type Extensions The main goal of the ASP.NET AJAX client-side framework is to emulate the ASP.NET and .NET Framework as much as possible to bring similar .NET-style programming to your client-side scripting. The ASP.NET AJAX JavaScript base type extensions are the first step toward achieving this goal. These extensions extend the functionality of the JavaScript base types such as Array, Boolean, Date, Error, Number, Object, and String to add support for .NET-like methods and properties. As such, the ASP.NET AJAX JavaScript base type extensions make client-side programming against these JavaScript base types more like server-side programming against their .NET counterparts as much as possible. The code samples presented in this chapter use a new JavaScript function named pageLoad and a new server control named ScriptManager as shown in the boldfaced portion of Listing 2-1.
Listing 2-1: The ASP.NET Page Used by the Examples Untitled Page function pageLoad() { . . . }
c02.indd 27
8/20/07 5:42:26 PM
Chapter 2: JavaScript Base Type Extensions I’ll discuss the pageLoad JavaScript function and ScriptManager server control in detail in future chapters. For now, here are two key concepts:
❑
One of the responsibilities of the ScriptManager server control is to download the ASP.NET AJAX client-side framework to the requesting browser to make it available to the browser’s JavaScript engine.
❑
The ASP.NET AJAX client-side framework automatically calls the pageLoad JavaScript function after the page and the related client-side scripts are completely loaded.
ASP. NET AJAX Array Type Extensions The .NET Array type features methods such as Clone, Add, Clear, Contains, IndexOf, Insert, Remove, and RemoveAt. The ASP.NET AJAX client-side framework extends the JavaScript Array type to add support for similar methods. These extensions allow the JavaScript Array type to emulate its .NET counterpart as much as possible to make you feel like you’re programming against the .NET Array type. Keep in mind that these new methods are static methods, which means that you must call these methods directly on the Array class itself.
add The add method takes two arguments of type Array and Object, respectively and adds the Object to the end of the Array as shown in the following code. Because the second argument is of type Object, you can add any type of object to the specified array. Untitled Page function pageLoad() { var a = [‘m1’,’m2’]; Array.add(a, ‘m3’); for (var i = 0; i ----> ----> ----> ----> ----> ---->
} function pageLoad() { var mybtn = $get(“mybtn”); $addHandler (mybtn, “click”, clickcb); } Click Here
This example renders a simple HTML element. As this example shows, adding an event handler for an event involves the following steps:
1.
Access a reference to the DOM element that will raise the event: var mybtn = $get(“mybtn”);
2.
Call the addHandler method, passing in the reference to the DOM element, the name of the event, and the reference to the event handler: $addHandler (mybtn, “click”, clickcb);
The clickcb event handler simply pops up an alert that displays the property 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
c06.indd 190
8/20/07 7:58:18 PM
Chapter 6: DOM Extensions
Figure 6-4
Listing 6-27: The addHandler Method var $addHandler = Sys.UI.DomEvent.addHandler = function Sys$UI$DomEvent$addHandler(element, eventName, handler) { if (!element._events) element._events = {}; var eventCache = element._events[eventName]; if (!eventCache) element._events[eventName] = eventCache = []; var browserHandler; if (element.addEventListener) { browserHandler = function(e) { return handler.call(element, new Sys.UI.DomEvent(e)); } element.addEventListener(eventName, browserHandler, false); } else if (element.attachEvent) { browserHandler = function() { return handler.call(element, new Sys.UI.DomEvent(window.event)); } element.attachEvent(‘on’ + eventName, browserHandler); } eventCache[eventCache.length] = {handler: handler, browserHandler: browserHandler}; }
191
c06.indd 191
8/20/07 7:58:18 PM
Chapter 6: DOM Extensions Now, let’s walk through the implementation of the addHandler method shown in Listing 6-27. This method first checks whether the DOM element that will raise the event contains an object named _events. If not, it instantiates and adds this object to the DOM element: if (!element._events) element._events = {};
Next, addHandler uses the event name as an index into the _events to access the subarray associated with the specified event name. If _events does not contain a subarray for the specified event name, addHandlers instantiates and adds this subarray to _events: var eventCache = element._events[eventName]; if (!eventCache) element._events[eventName] = eventCache = [];
Then, addHandler checks whether the DOM element that will raise the event supports a method named addEventListener. The DOM elements of browsers such as Mozilla support this method. If the DOM element supports this method, addHandler takes the following steps:
1.
It defines a JavaScript function that contains two statements. The first statement instantiates a DomEvent, passing in the event object to represent the event. The second statement invokes the call method on the event handler being registered, passing in the reference to the DOM element that will raise the event and the DomEvent object that represents the event. JavaScript sets the value of the JavaScript keyword within the scope of the event handler being registered to reference the DOM element passed into the call method. This means that you can use the JavaScript keyword within the body of this event handler to access the DOM element that raised the event.
2.
It invokes the addEventListener method on the DOM element that will raise the event, passing in the event name and the JavaScript function defined previously to register the JavaScript function as the event handler for the event with the specified name.
In other words, addHandler wraps the call into the event handler being added in a new event handler and registers this new event handler for the event. Therefore, when the specified DOM element finally raises the event, it calls the new event handler, which in turn instantiates the DomEvent object and calls the event handler being added, passing in the DomEvent object: var browserHandler; if (element.addEventListener) { browserHandler = function(e) { var domEvent = new Sys.UI.DomEvent(e); return handler.call(element, domEvent); } element.addEventListener(eventName, browserHandler, false); }
If the DOM element that will raise the event does not support the addEventListener method, addHandler checks whether it supports the attachEvent method. The DOM elements of IE browsers support this method. If the DOM element supports this method, addHandler first defines a JavaScript function that consists of two statements. The first statement instantiates a DomEvent object that encapsulates the window.event event object. The second statement invokes the call method on the event handler being added, passing in the reference to the DOM element and the DomEvent object. Next,
192
c06.indd 192
8/20/07 7:58:18 PM
Chapter 6: DOM Extensions addHandler calls the attachEvent method on the DOM element, passing in the on-prefixed name of the event and the JavaScript function just defined: else if (element.attachEvent) { browserHandler = function() { var domEvent = new Sys.UI.DomEvent(window.event); return handler.call(element, domEvent); } element.attachEvent(‘on’ + eventName, browserHandler); }
Finally, addHandler stores an object with two properties in the subarray associated with the event. The first property, handler, references the event handler being added; and the second property, browserHandler, references the JavaScript function defined previously: eventCache[eventCache.length] = {handler: handler, browserHandler: browserHandler};
removeHandler The DomEvent class exposes a method named removeHandler that removes a specified event handler. As Listing 6-28 shows, the removeHandler is defined on the DomEvent class itself. As such, it is a static method that must be called on the class itself. As you can see, the removeHandler method takes three parameters. The first parameter references the DOM element that exposes the event with the specified name. The second parameter is a string that contains the name of the event. The third parameter references the event handler method being removed.
Listing 6-28: The removeHandler Method of the DomEvent Class var $removeHandler = Sys.UI.DomEvent.removeHandler = function Sys$UI$DomEvent$removeHandler(element, eventName, handler) { var cache = element._events[eventName]; var browserHandler = null; for (var i = 0, l = cache.length; i < l; i++) { if (cache[i].handler === handler) { browserHandler = cache[i].browserHandler; break; } } if (element.removeEventListener) element.removeEventListener(eventName, browserHandler, false); else if (element.detachEvent) element.detachEvent(‘on’ + eventName, browserHandler); cache.splice(i, 1); }
193
c06.indd 193
8/20/07 7:58:19 PM
Chapter 6: DOM Extensions Now, let’s walk through the implementation of the removeHandler method. This method first uses the event name as an index into the _events object of the DOM element that exposes the event with the specified name, and returns a reference to the array that contains all the event handlers for the event with the specified name: var cache = element._events[eventName];
Next, it iterates through the event handlers of the array to locate the event handler to be removed: for (var i = 0, l = cache.length; i < l; i++) { if (cache[i].handler === handler) { browserHandler = cache[i].browserHandler; break; } }
Then, it checks whether the DOM element that exposes the event supports the removeEventListener method. The DOM elements of browsers such as Mozilla support this method. If the DOM element supports the method, removeHandler simply calls the removeEventListener method on the DOM element to remove the specified event handler: element.removeEventListener(eventName, browserHandler, false);
If the DOM element does not support the removeEventListener method, removeHandler checks whether it supports the detachEvent method. The DOM elements of browsers such as IE support this method. If the DOM element supports the method, removeHandler calls the method to remove the specified event handler: element.detachEvent(‘on’ + eventName, browserHandler);
Finally, removeHandler removes the event handler from the array: cache.splice(i, 1);
As you can see, thanks to the removeHandler method of the DomEvent class, you don’t have to worry about the discrepancies among the browsers. It’s all taken care of under the hood. The DomEvent class also takes care of the bookkeeping logic required to store and remove event handlers — storing and removing event handlers from the associated arrays of _events. Later in this chapter, you’ll see an example where you need to call the removeHandler method to remove a specified event handler.
addHandlers The DomEvent class exposes a method named addHandlers that allows you to register event handlers for different events of a specified DOM element. As Listing 6-29 shows, this method takes three arguments. The first argument references the DOM element that will raise the specified events. The second argument is a collection that contains the event names and the handlers being registered for these events. The third argument references the object that is the context for the delegates that the addHandlers method creates internally to represent the event handlers (discussed in detail later in this chapter).
194
c06.indd 194
8/20/07 7:58:19 PM
Chapter 6: DOM Extensions Listing 6-29: The Internal Implementation of the addHandlers Method var $addHandlers = Sys.UI.DomEvent.addHandlers = function Sys$UI$DomEvent$addHandlers(element, events, handlerOwner) { for (var name in events) { var handler = events[name]; if (handlerOwner) handler = Function.createDelegate(handlerOwner, handler); $addHandler(element, name, handler); } }
Now let’s walk through this listing. Here’s what’s going on:
1.
The addHandlers method is defined on the DomEvent class itself instead of its prototype property. This means that this method is a static method and must be invoked on the class itself.
2.
The ASP.NET AJAX DOM extensions define a shortcut method named $addHandlers that allows you to use the following short syntax to invoke the addHandler method:
$addHandlers(element, events, handlerOwner); addHandlers iterates through the event handlers that the events dictionary contains and takes the
following actions for each enumerated event handler:
❑
It uses the event name as an index into the events dictionary to access the enumerated event handler:
var handler = events[name];
❑
It checks whether the caller has passed a value for the third argument. If so, addHandlers invokes the createDelegate method on the Function type, passing in the third argument and the event handler itself: if (handlerOwner) handler = Function.createDelegate(handlerOwner, handler);
As discussed earlier in this chapter, the createDelegate method creates a delegate that encapsulates and represents the event handler associated with the specified object.
❑
It calls the addHandler method of the DomEvent class, passing in three arguments. The first argument references the DOM element that will raise the event; the second argument is a string value that contains the event name; and the third argument references the event handler being added: $addHandler(element, name, handler);
Listing 6-30 shows an example that uses the addHandlers method.
195
c06.indd 195
8/20/07 7:58:19 PM
Chapter 6: DOM Extensions Listing 6-30: An example that uses the addHandlers method Untitled Page function blurcb(domEvent) { alert(“blurcb was invoked!”); } function mousedowncb(domEvent) { alert(“mousedowncb was invoked!”); } function pageLoad() { var mybtn = $get(“mybtn”); var events = {blur:blurcb, mousedown:mousedowncb}; $addHandlers(mybtn, events); } Click Here
As you can see, the pageLoad method first creates a JavaScript object literal that contains two name/ value pairs where the name part of each pair contains the event name and the value part contains the event handler. Then it calls the addHandlers method of the DomEvent class, passing in the reference to the HTML element and this JavaScript object literal. In this case, you could also call the addHandler method twice to achieve the same effect, as shown in the boldfaced portion of Listing 6-31. If you don’t specify the third argument of the addHandlers method, the method is equivalent to multiple calls into the addHandler method. However, as you’ll see later in this chapter, if you do specify the third argument of the addHandlers method, the method does more than just make multiple calls into the addHandler methods.
196
c06.indd 196
8/20/07 7:58:20 PM
Chapter 6: DOM Extensions Listing 6-31: A version of Listing 6-30 that uses the addHandler method Untitled Page function blurcb(domEvent) { alert(“blurcb was invoked!”); } function mousedowncb(domEvent) { alert(“mousedowncb was invoked!”); } function pageLoad() { var mybtn = $get(“mybtn”); $addHandler (mybtn, “blur”, blurcb); $addHandler (mybtn, “mousedown”, mousedowncb); } Click Here
clearHandlers The DomEvent class exposes a method named clearHandlers that allows you to clear all event handlers registered for all the events of a specified DOM element. In Listing 6-32, the DomEvent class does the following:
1.
It defines the clearHandlers method on the DomEvent class itself. As such, this method is a static method that must be directly called on the class itself.
2.
It defines a shortcut method named $clearHandlers that allows you to use the following notation to invoke the clearHandlers method:
$clearHandlers(element);
197
c06.indd 197
8/20/07 7:58:20 PM
Chapter 6: DOM Extensions Listing 6-32: The clearHandlers Method of the DomEvent Class var $clearHandlers = Sys.UI.DomEvent.clearHandlers = function Sys$UI$DomEvent$clearHandlers(element) { if (element._events) { var cache = element._events; for (var name in cache) { var handlers = cache[name]; for (var i = handlers.length - 1; i >= 0; i--) $removeHandler(element, name, handlers[i].handler); } element._events = null; } }
In its internal implementation, the clearHandlers method simply iterates through the event handlers in the _events dictionary of the specified DOM element and takes the following steps for each enumerated event type:
1.
It uses the event name as an index into the _events dictionary to access the array that contains the event handlers for the event with the specified name:
var handlers = cache[name];
2.
It iterates through the event handlers in the array and calls the removeHandler method once for each enumerated event handler to remove the handler:
for (var i = handlers.length - 1; i >= 0; i--) $removeHandler(element, name, handlers[i].handler);
Again thanks to the DomEvent class, you can remove all the event handlers registered for all the events of a specified DOM element by one simple call into the clearHandler method. All the associated bookkeeping work is managed under the hood for you.
Instance Methods As mentioned previously, the DomEvent class exposes two sets of methods: static and instance. The static methods were discussed in the previous section. This section discusses the instance methods of the DomEvent class. The instance methods are defined directly on the prototype property of the DomEvent class. As such, they must be invoked on an instance of the class. They cannot be invoked on the class itself. These instance methods are preventDefault and stopPropagation.
preventDefault As discussed earlier, when an event occurs, the browser instantiates an event object and populates its properties with specific information about the event. Each event normally has a default behavior. For example, the click event of posts the form data back to the server. Most
198
c06.indd 198
8/20/07 7:58:20 PM
Chapter 6: DOM Extensions applications nowadays need to validate the form data on the client-side and cancel the postback operation altogether if the validation fails. Obviously the cancellation must be performed inside the event handler method that handles the click event. The event object associated with the event exposes a member that allows these applications to cancel the default action of the event. The event object created by browsers such as Mozilla exposes a method named preventDefault that can be invoked on the event object to cancel the default action. The event object created by some other browsers such as IE, on the other hand, exposes a Boolean property named returnValue that can be set to cancel the default action. The DomEvent class exposes an instance method named preventDefault that encapsulates this browser-dependent event cancellation logic, enabling you to cancel the event with a single method call that works on all types of browsers. Listing 6-33 presents the internal implementation of the preventDefault method.
Listing 6-33: The preventDefault Instance Method of the DomEvent Class function Sys$UI$DomEvent$preventDefault() { if (this.rawEvent.preventDefault) this.rawEvent.preventDefault(); else if (window.event) window.event.returnValue = false; }
Listing 6-34 contains a page the uses the preventDefault instance method of the DomEvent class.
Listing 6-34: A page that uses the preventDefault method void Page_Load(object sender, EventArgs e) { if (IsPostBack) info.Text=”You entered: “ + date.Value; } Untitled Page function validateInput(input) { if (arguments.length != arguments.callee.length) { var err3=Error.parameterCount(“Invalid argument count!”); throw err3; }
(continued)
199
c06.indd 199
8/20/07 7:58:20 PM
Chapter 6: DOM Extensions Listing 6-34 (continued) if (input == null || input.trim() == “”) { var er = Error.argumentNull(“input”, “Date cannot be null!”); throw er; } var reg = new RegExp(“(\\d\\d)[-](\\d\\d)[-](\\d\\d\\d\\d)”); var date = reg.exec(input); if (date == null) { var err = Error.argumentUndefined(“input”, “Undefined value!”); throw err; } var ar = input.split(“-”); if (ar[2] < 1900 || ar[2] > 2008) { var err2=Error.argumentOutOfRange(“input”, input); throw err2; } } function clickCallback(domEvent) { var date = $get(“date”); var info = $get(“info”); info.innerHTML=””; try { validateInput(date.value); } catch (e) { alert(e.message); date.value=””; domEvent.preventDefault(); } } function pageLoad() { var submitbtn = $get(“submitbtn”); $addHandler(submitbtn, “click”, clickCallback); }
200
c06.indd 200
8/20/07 7:58:21 PM
Chapter 6: DOM Extensions Enter date: Submit
This page covers a very common scenario in Web applications: the validation of the data that the end user enters into a text box before submitting the form to the server. As you can see, this page contains a text box and a Submit button that submits the value of the text box to the server. The pageLoad JavaScript function uses the addHandler method of the DomEvent class to register the clickCallback JavaScript function as the event handler for the click event of the Submit button: function pageLoad() { var submitbtn = $get(“submitbtn”); $addHandler(submitbtn, “click”, clickCallback); }
The clickCallback event handler first calls the validateInput JavaScript function to validate the date that the end user entered in the text box. The validateInput JavaScript function performs the validations discussed in Chapter 3, and raises an exception if the validation fails. The catch block of the clickCallback event handler catches this exception and calls the preventDefault method of the DomEvent object to cancel the form submission to the server.
stopPropagation Event propagation is one of the important aspects of client-side event programming. To understand event propagation, first you need to understand the concept of containment hierarchy. The containment hierarchy of a specified DOM element such as the Submit button in Listing 6-34 is a tree, or hierarchy, of DOM elements that contains all the ancestor DOM elements of the specified DOM element in addition to the DOM element itself. The root DOM element of a containment hierarchy is the window object. For example, the containment hierarchy of the Submit button in Listing 6-34 contains these DOM elements: window, document, HTML, body, form, and button. Prior to modern browsers, when the end user clicked the Submit button, the button would raise the click event, which had to be handled at the Submit button level. In other words, you had to register an event handler for the click event of the Submit button to handle the event. If there were no event handlers registered for the click event of the Submit button, the event would be lost forever. You had to handle the event at the event target itself. That’s all in the past. Modern browsers propagate the event that a DOM element raises all the way through the containment hierarchy of the element. For example, in the case of the Submit button in Listing 6-34, when the end user clicks the button and raises the click event, the event object associated
201
c06.indd 201
8/20/07 7:58:21 PM
Chapter 6: DOM Extensions with this event is passed to the ancestor DOM elements (document, HTML, and so on) for the Submit button. This has two important benefits:
❑
You can now register an event handler with a higher-level DOM element, such as the document element, to handle the event that a lower-level DOM element, such as the Submit button, raises.
❑
You can handle the same event multiple times at multiple hierarchy levels. For example, you can handle the event that the Submit button raises at the document and body levels in addition to the Submit-button level.
In general, there are three event propagation models:
❑
Netscape Navigator 4–only event propagation model: Netscape Navigator 4 is the only browser that supports this event propagation model. As more people are moving from Netscape Navigator 4 to more modern browsers, this event propagation model is used less often. In this event propagation model, when a DOM element such as the Submit button in Listing 6-34 raises an event, the event propagates from the top of the DOM element’s containment hierarchy (the window object) all the way down to the event target (the DOM element itself). The Netscape Navigator 4 event propagation model is also known as event capture. By default, Netscape Navigator 4 event propagation is turned off.
❑
Internet Explorer 4 and higher event propagation model: In this event propagation model, when a DOM element such as the Submit button in Listing 6-34 raises an event, the event propagates from the bottom of the DOM element’s containment hierarchy (the DOM element itself) all the way up to the top of the containment hierarchy (the window object). In other words, the Internet Explorer 4 and higher propagation model is the opposite of the Netscape Navigator 4 event propagation model. The Internet Explorer 4 and higher propagation model is known as event bubbling. Internet Explorer 4 and higher event bubbling is very similar to the ASP.NET Framework’s event bubbling. By default, Internet Explorer 4 and higher event propagation is turned on.
❑
W3C event propagation model: In this event propagation model, when a DOM element such as the Submit button in Listing 6-34 raises an event, the event propagates from the top of the DOM element’s containment hierarchy (the window object) all the way down to the event target and then bubbles from there all the way back up to the top of the containment hierarchy. The W3C event propagation model accommodates both Netscape Navigator 4 and Internet Explorer 4 and higher event propagation models. Unfortunately, because the other two propagation models are still in use, the W3C event propagation model had to introduce a new syntax to avoid conflicts. By default, only the event bubbling portion of the W3C event propagation is turned on.
By default, event capture is turned off no matter which event propagation model is used. There are times when an application needs to stop the default behavior of event bubbling at a particular level of a containment hierarchy. For example, in the case of Listing 6-34, you may not want the click event to propagate to the document level because it would interfere with some other events that your application handles at that level. Both the Internet Explorer 4 and higher and W3C propagation models allow you to stop the event bubbling at a desired level of a containment hierarchy. However, these models require you to invoke different members of the event object to achieve this. In the case of the W3C event propagation model, you must call the stopPropagation method on the event object to stop the event bubbling at a specified hierarchy level. In the case of the Internet Explorer 4 and higher event propagation model, you must set the cancelBubble property of the event object to true to stop the event bubbling at a specified hierarchy level.
202
c06.indd 202
8/20/07 7:58:21 PM
Chapter 6: DOM Extensions The DomEvent class exposes an instance method named stopPropagation that encapsulates this browser-dependent code, allowing you to stop the event bubbling at a desired level by making a single method call that works with all types of browsers. Listing 6-35 presents the internal implementation of the stopPropagation method of the DomEvent class.
Listing 6-35: The stopPropagation Instance Method of the DomEvent Class function Sys$UI$DomEvent$stopPropagation() { if (this.rawEvent.stopPropagation) this.rawEvent.stopPropagation(); else if (window.event) window.event.cancelBubble = true; }
As you can see in this listing, the stopPropagation method first checks whether the event object supports a method named stopPropagation. If so, this indicates that the browser is using the W3C event propagation model, and the stopPropagation method of the event object is called to stop the event bubbling. The constructor of the DomEvent class assigns the event object to the rawEvent property of the DomEvent object: this.rawEvent.stopPropagation();
If the event object does not support the stopPropagation method, Listing 6-35 checks whether the window object supports a property named event. If so, this indicates that the browser is using the Internet Explorer 4 and higher event propagation model, and the cancelBubble property of the event object is set to true to stop the event bubbling.
Using the DomEvent Class Listing 6-36 presents an example that uses the methods of the DomEvent class. This example is a new version of the example discussed earlier in the chapter (see Listing 6-22 through 6-24). Recall that the previous version did the following:
❑
It loaded and displayed a single movable object such as text.
❑
It instantiated a single mover that enables the end user to move the movable object.
As you can see, the previous version of the example supports loading, displaying, and moving a single movable object. The new version of the example supports loading, displaying, and moving multiple movable objects simultaneously. The new version allows you to attach a separate mover object to each movable object so you can move them independently. The new version also adds support for a new type of movable object that displays a table of data. As Listing 6-36 shows, this page displays three movable objects simultaneously, allowing you to move them independently. These movable objects are text, an image, and a table of data as shown in Figure 6-5.
203
c06.indd 203
8/20/07 7:58:22 PM
Chapter 6: DOM Extensions Listing 6-36: A page that uses the DomEvent Class Untitled Page .myTable { background-color: LightGoldenrodYellow; border-color:Tan; border-width:1px; color:Black; } .myTable th, .myTable td { padding: 2px 5px; } .header { background-color:Tan; font-weight:bold } .odd { background-color:PaleGoldenrod; } function pageLoad() { var imageMover = new Delegates.Mover(“container1”); var imageProvider = new Delegates.ImageProvider(“images.jpg”); var addImageDelegate = Function.createDelegate(imageProvider, imageProvider.addImage); imageMover.addContent(addImageDelegate); var textMover = new Delegates.Mover(“container2”); var textProvider = new Delegates.TextProvider(“Wrox Web Site”); var addTextDelegate = Function.createDelegate(textProvider, textProvider.addText); textMover.addContent(addTextDelegate); var headers = [“Product”, “Distributor”, “Producer”]; var rows = [];
204
c06.indd 204
8/20/07 7:58:22 PM
Chapter 6: DOM Extensions for (var i=0; i
Here is what happens in this phase:
1.
An internal flag named _initializing is set to true to mark the beginning of the initialization phase of the application.
2.
The _doInitialize method is queued for execution.
3.
Beginning of the Component Creation phase: This is the phase where the beginCreateComponents method of the Application object is invoked. As discussed earlier, this method simply sets an internal flag named _creatingComponents to true to mark the beginning of the Component Creation lifecycle phase.
4.
Raising the Init Event: This phase occurs immediately after the application enters the Component Creation phase. This is the phase where the application raises the init event and consequently invokes all the event handlers registered for this event. Because the application
257
c07.indd 257
8/20/07 8:09:14 PM
Chapter 7: Component Development Infrastructure has just entered the component creation phase, the cross references among the components of the application have not been resolved yet. As such, the event handlers that you register for the init event of the Application object must not access other components of the application.
5.
End of the Component Creation Phase: This phase occurs right after all the event handlers for the init event of the Application have been invoked. This is the phase where the endCreateComponents method of the Application object is invoked to resolve the cross references among the constituent components of an ASP.NET AJAX application.
6.
Load Phase: This phase occurs after all the cross references among the constituent components of an ASP.NET AJAX application have been resolved. This is the phase where the raiseLoad method of the Application object is invoked. Here is what happens in this phase:
1.
The application raises the load event and consequently invokes all the event handlers registered for the load event. The Application object passes an ApplicationLoadEventArgs object into each event handler. This object contains the contents of the Application object’s _createdComponents array. The create static method of the Component base class adds the newly created Component object to this array, which means that you can access the newly created Component objects from within your load event handler to customize them. This is very similar to the ItemCreated event of the GridView, which allows you to customize the GridViewRow objects right after they’re created. Because the load event is raised after all the cross references among the constituent components of an application are resolved, you can safely access any component of the application from within your load event handler.
2.
If a page contains the pageLoad method, this method is invoked right after the load event is raised.
3.
The _createdComponents array is reset.
Application Level Events The Application object that represents an ASP.NET AJAX application exposes three important events, as discussed in the following sections.
init The Application object features a method named add_init that allows you to register a specified event handler for the init event of the Application object as shown in Listing 7-29.
Listing 7-29: The add_init Method of the Application Object function Sys$_Application$add_init(handler) { if (this._initialized) handler(this, Sys.EventArgs.Empty); else this.get_events().addHandler(“init”, handler); }
258
c07.indd 258
8/20/07 8:09:14 PM
Chapter 7: Component Development Infrastructure As you can see in this code listing, the add_init method first checks whether the Application object has already raised the init event. The init event is raised only once in the lifetime of an ASP.NET AJAX application, as discussed earlier. If the init event has already been raised, the add_init method does not add the event handler being registered to the internal EventHandlerList. This is because when an event handler is added to the EventHandlerList, it will not be invoked until the associated event is raised. In this case, because the init event has already been raised, the event handler will remain in the EventHandlerList forever without ever being invoked. That is why the add_init method invokes the event handler being registered synchronously: if (this._initialized) handler(this, Sys.EventArgs.Empty);
However, if the event handler is added before the Application raises the init event, the add_init method first calls the get_events method to return a reference to the internal EventHandlerList and then calls the addHandler method on the EventHandlerList to register the event handler for the init event of the Application object: else this.get_events().addHandler(“init”, handler);
The Application object also exposes a method named remove_init, shown in Listing 7-30, that allows you to remove a specified event handler from the list of event handlers registered for the Application object’s init event.
Listing 7-30: The remove_init Method of the Application Object function Sys$_Application$remove_init(handler) { this.get_events().removeHandler(“init”, handler); }
load You can use the add_load and remove_load methods of the Application object to add a specified event handler to and remove a specified event handler from the list of event handlers registered for the Application object’s load event, as shown in Listing 7-31.
Listing 7-31: The add_load and remove_load Methods of the Application Object function Sys$_Application$add_load(handler) { this.get_events().addHandler(“load”, handler); } function Sys$_Application$remove_load(handler) { this.get_events().removeHandler(“load”, handler); }
259
c07.indd 259
8/20/07 8:09:14 PM
Chapter 7: Component Development Infrastructure
unload The Application object’s add_unload and remove_unload methods allow you to add a specified event handler to and remove a specified event handler from the list of event handlers registered for the Application object’s unload event of, as shown in Listing 7-32.
Listing 7-32: The add_unload and remove_unload Methods of the Application Object function Sys$_Application$add_unload(handler) { this.get_events().addHandler(“unload”, handler); } function Sys$_Application$remove_unload(handler) { this.get_events().removeHandler(“unload”, handler); }
Disposable Objects As shown in the following code snippet from Listing 7-18, the constructor of the _Application class defines and instantiates an array named _disposableObjects: this._disposableObjects = [];
A disposable object is an instance of a class that implements the IDisposable interface. Recall that the IDisposable interface exposes a single method named dispose that must be implemented by classes that derive from this interface. A class’s implementation of the dispose method must release the resources that the instance of the class is holding before the instance is disposed of. The Application object that represents an ASP.NET AJAX application guarantees to call the dispose method of your disposable objects before these objects are disposed of if you call the registerDisposableObject method on the Application object to register your disposable object. As you can see in Listing 7-33, the registerDisposableObject method adds the disposable object to the internal _disposableObjects array.
Listing 7-33: The registerDisposableObject Method of the Application Object function Sys$_Application$registerDisposableObject(object) { if (!this._disposing) this._disposableObjects[this._disposableObjects.length] = object; }
As shown in the following code snippet from Listing 7-18, the constructor of the _Application class calls the createDelegate method on the Function class to create a delegate that represents the Application object’s _unloadHandler method and registers this delegate as the event handler for the window object’s unload event: this._unloadHandlerDelegate = Function.createDelegate(this, this._unloadHandler); Sys.UI.DomEvent.addHandler(window, “unload”, this._unloadHandlerDelegate);
260
c07.indd 260
8/20/07 8:09:15 PM
Chapter 7: Component Development Infrastructure When the window object finally raises the unload event, it automatically calls the _unloadHandlerDelegate delegate, which in turn calls the Application object’s _unloadHandler method. Listing 7-34 presents the implementation of the _unloadHandler method.
Listing 7-34: The _unloadHandler Method of the Application Object function Sys$_Application$_unloadHandler(event) { this.dispose(); }
As you can see, the _unloadHandler method calls the dispose method on the Application object to dispose of the object. Listing 7-35 presents the implementation of the Application object’s dispose method.
Listing 7-35: The dispose Method of the Application Object function Sys$_Application$dispose() { if (!this._disposing) { this._disposing = true; if (window.pageUnload) window.pageUnload(this, Sys.EventArgs.Empty); var unloadHandler = this.get_events().getHandler(“unload”); if (unloadHandler) unloadHandler(this, Sys.EventArgs.Empty); var disposableObjects = Array.clone(this._disposableObjects); for (var i = 0, l = disposableObjects.length; i < l; i++) disposableObjects[i].dispose(); Array.clear(this._disposableObjects); Sys.UI.DomEvent.removeHandler(window, “unload”, this._unloadHandlerDelegate); if(this._loadHandlerDelegate) { Sys.UI.DomEvent.removeHandler(window, “load”, this._loadHandlerDelegate); this._loadHandlerDelegate = null; } var sl = Sys._ScriptLoader.getInstance(); if(sl) sl.dispose(); Sys._Application.callBaseMethod(this, ‘dispose’); } }
261
c07.indd 261
8/20/07 8:09:15 PM
Chapter 7: Component Development Infrastructure The dispose method first sets an internal flag named _disposing to true to ensure that the dispose method is not called more than once during the lifetime of the current ASP.NET AJAX application: this._disposing = true;
Next, it checks whether the window object contains a method named pageUnload. If so, it invokes this method: if (window.pageUnload) window.pageUnload(this, Sys.EventArgs.Empty);
Next, it calls the get_events method on the Application object to return a reference to the internal EventHandlerList that contains all the event handlers registered for the events of the Application object. It then calls the getHandler method on the EventHandlerList object, passing in the string “unload” to return a reference to the JavaScript function whose invocation automatically invokes all the event handlers registered for the unload event of the Application object: var unloadHandler = this.get_events().getHandler(“unload”);
Next, it invokes this JavaScript function to invoke the associated event handlers: if (unloadHandler) unloadHandler(this, Sys.EventArgs.Empty);
As you can see, you have two options when it comes to handling the unload event of the Application object. One option is to implement a JavaScript function named pageUnload. When the dispose method of the Application object invokes the pageUnload method, it passes a reference to the Application object raising the event, which means that you can use this reference to access the methods and properties of the Application object that represents the current ASP.NET AJAX application. Another option is to call the add_unload method on the Application object to register an event handler for the unload event. As the following code snippet from Listing 7-35 shows, the dispose method then iterates through the disposable objects in the _disposableObjects collection and invokes the dispose method on each enumerated disposable object. The dispose method of a disposable object must perform final cleanup and release all the resources the object is holding. var disposableObjects = Array.clone(this._disposableObjects); for (var i = 0, l = disposableObjects.length; i < l; i++) disposableObjects[i].dispose();
Next, it calls the clear static method on the Array class to clear the _disposableObjects collection and consequently dispose these objects: Array.clear(this._disposableObjects);
As you can see, the Application object disposes the disposable objects only after it invokes their dispose method — that is, only after these objects get the chance to perform their final cleanup and to release the resources they’re holding.
262
c07.indd 262
8/20/07 8:09:15 PM
Chapter 7: Component Development Infrastructure The dispose method then performs its final cleanup and releases the resources that the application is holding. In this case, it unregisters the _unloadHandlerDelegate and _loadHandlerDelgate event handlers (which the constructor of the _Application class previously registered for the unload and load events of the window object): Sys.UI.DomEvent.removeHandler(window, “unload”, this._unloadHandlerDelegate); if(this._loadHandlerDelegate) { Sys.UI.DomEvent.removeHandler(window, “load”, this._loadHandlerDelegate); this._loadHandlerDelegate = null; }
Next, the dispose method of Application calls the dispose method of the _ScriptLoader object to allow this object to release the resources it is holding: var sl = Sys._ScriptLoader.getInstance(); if(sl) sl.dispose();
Finally, the dispose method of Application invokes the dispose method of its base class, which in this case is the Component class. Your custom class’s implementation of the dispose method must always invoke the dispose method of its base class before it returns to allow the base class to perform its final cleanup and to release the resources it is holding. You must call the following method at the end of the dispose method of your class — that is, after your class releases the resources it is holding: Sys._Application.callBaseMethod(this, ‘dispose’);
There are times when you may decide to unregister your disposable object. This is where the Application object’s unregisterDisposableObject method comes into play, as shown in Listing 7-36.
Listing 7-36: The unregisterDisposableObject Method of the Application Object function Sys$_Application$unregisterDisposableObject(object) { if (!this._disposing) Array.remove(this._disposableObjects, object); }
Using the Application Object and Component Base Class The previous sections of this chapter provided you with in-depth coverage of the important methods and events of the Application object and Component base class. This section shows you how to use the Application object and Component base class and their methods and events in your own ASP.NET AJAX applications. The example presented in this section is a new version of the Monitor class discussed earlier in this chapter. The following sections go over the old version of this class to point out the differences between the old and new versions and the logic behind these differences.
263
c07.indd 263
8/20/07 8:09:16 PM
Chapter 7: Component Development Infrastructure
dispose Listing 7-26 took extra steps to emulate a disposing event, as shown in the highlighted portions of the following code: Untitled Page var monitor; function disposingcb() { alert(“The Disposing event was raised!”); } . . . function pageLoad() { monitor = new Disposables.Monitor(); monitor.add_disposing(disposingcb); var disposebtn = $get(“disposebtn”); var disposeDelegate = Function.createDelegate(monitor, monitor.dispose); $addHandler(disposebtn, “click”, disposeDelegate); . . . } . . . Enter new Monitor id: Change Property Dispose Monitor
264
c07.indd 264
8/20/07 8:09:16 PM
Chapter 7: Component Development Infrastructure The highlighted portions of code do the following:
❑
Add a button named Dispose Monitor: Dispose Monitor
❑
Call the createDelegate method on the Function class to create a delegate that represents the dispose method of the Monitor class:
var disposeDelegate = Function.createDelegate(monitor, monitor.dispose);
❑
Call the addHandler method on the DomEvent class to register this delegate as an event handler for the click event of the Dispose Monitor button: $addHandler(disposebtn, “click”, disposeDelegate);
When the end user clicks this button, the delegate is automatically called, which in turn calls the dispose method of the Monitor class. As mentioned before, this was done for educational purposes. In a real-life project, the Monitor object must be registered as a disposable object with the Application object to have the Application object automatically call its dispose method before it is disposed of. As the following code shows, the constructor of the Component base class automatically registers the component as a disposable object with the Application object: Sys.Component = function Sys$Component() { if (Sys.Application) Sys.Application.registerDisposableObject(this); }
Therefore, if you inherit the Monitor class from the Component base class and have the constructor of the Monitor class invoke the constructor of the base class as shown in the boldfaced portion of the following code, every Monitor object is guaranteed to be registered as a disposable object with the Application object: Type.registerNamespace(“CustomComponents”); CustomComponents.Monitor = function() { CustomComponents.Monitor.initializeBase(this); . . . } CustomComponents.Monitor.registerClass(“CustomComponents.Monitor”, Sys.Component);
Because the Monitor class is now an ASP.NET AJAX component (meaning it derives from the Component base class), it makes more sense to define a more appropriate namespace such as CustomComponents.
265
c07.indd 265
8/20/07 8:09:16 PM
Chapter 7: Component Development Infrastructure As the highlighted portion of the following code snippet from Listing 7-8 shows, the dispose method of the Monitor class implements the logic that raises disposing event and consequently invokes the event handlers registered for this event: dispose : function() { if (this.events) { var handler = this.events.getHandler(“disposing”); if (handler) handler(this, Sys.EventArgs.Empty); } delete this.events; $removeHandler(document, “mousemove”, this.delegate); },
As you can see in the following code snippet from Listing 7-11, the dispose method of the Component base class includes the highlighted code from the previous code fragment: function Sys$Component$dispose() { if (this._events) { var handler = this._events.getHandler(“disposing”); if (handler) handler(this, Sys.EventArgs.Empty); } delete this._events; . . . }
Therefore, you can simplify the implementation of the dispose method of the Monitor class if you inherit the Monitor class from the Component base class and invoke the callBaseMethod method from the dispose method of the Monitor class, as shown in the following code fragment: dispose : function() { $removeHandler(document, “mousemove”, this.delegate); CustomComponents.Monitor.callBaseMethod(this, “dispose”); },
The callBaseMethod method invokes the dispose method of the Component base class. If you derive a custom component from the Component base class and if your custom component needs to override the dispose method, your custom component’s implementation of this method must use the callBaseMethod method to invoke the dispose method of the Component base class. Otherwise, the disposing event of your custom component will not be raised and, consequently, the event handlers registered for this event will not be invoked.
266
c07.indd 266
8/20/07 8:09:17 PM
Chapter 7: Component Development Infrastructure
initialize The create static method of the Component base class invokes the endUpdate method when it is done with updating the newly instantiated component, as shown in the highlighted portions of the following code snippet from Listing 7-5: var $create = Sys.Component.create = function Sys$Component$create(type, properties, events, references, element) { var component = (element ? new type(element): new type()); component.beginUpdate(); . . . if (Sys.Application.get_isCreatingComponents()) { if (references) Sys.Application._addComponentToSecondPass(component, references); else component.endUpdate(); } else { if (references) Sys$Component$_setReferences(component, references); component.endUpdate(); } return component; }
The endUpdate method invokes the initialize method if this method has not been already explicitly invoked, as shown in the highlighted portion of the following code snippet from Listing 7-8. The Component base class guarantees that the initialize method will be automatically invoked if it is not explicitly invoked. function Sys$Component$endUpdate() { this._updating = false; if (!this._initialized) this.initialize(); this.updated(); }
267
c07.indd 267
8/20/07 8:09:17 PM
Chapter 7: Component Development Infrastructure As you can see in the following code fragment, the initialize method of the Component base class doesn’t do much. It simply sets the _initialized flag to true to ensure that the initialize method is not twice: function Sys$Component$initialize() { this._initialized = true; }
Because the Component base class guarantees the one-time automatic invocation of the initialize method, this method is the best place for your custom component to initialize itself. The Monitor class initializes itself partly inside its constructor and partly inside the registerMonitor method, as shown in the highlighted portions of the following code snippet from Listing 7-8: CustomComponents.Monitor = function() { CustomComponents.Monitor.initializeBase(this); this.id = ”Monitor1”; this.div = document.createElement(“div”); document.body.insertBefore(this.div,document.forms[0]); this.registerMonitor(); } CustomComponents.Monitor.prototype = { registerMonitor : function() { this.delegate = Function.createDelegate(this, this.print); $addHandler(document, “mousemove”, this.delegate); }, . . . }
The new version of the Monitor class overrides the initialize method that it inherits from the Component base class and moves all its initialization logic from its constructor and the registerMonitor method into the initialize method, as shown in the following code fragment: CustomComponents.Monitor.prototype = { initialize : function() { CustomComponents.Monitor.callBaseMethod(this, “initialize”); this.printFormat = ”Monitor id: {0} X-Coordinate: {1}” + “Y-Coordinate: {2}”; this.div = document.createElement(“div”); document.body.insertBefore(this.div,document.forms[0]); this.delegate = Function.createDelegate(this, this.print); $addHandler(document, “mousemove”, this.delegate); } }
268
c07.indd 268
8/20/07 8:09:17 PM
Chapter 7: Component Development Infrastructure Note that the Monitor class’s implementation of the initialize method uses the callBaseMethod method to invoke the initialize method of its Component base class. When you inherit a custom component from the Component base class, your custom component’s implementation of the initialize method must use the callBaseMethod method to invoke the Component base class’s initialize method. This enables the base class to set the _initialized internal flag, which ensures that your custom component is not initialized twice.
id The Monitor class implements a getter named get_id and a setter named set_id to allow its clients to get and to set the id of a Monitor object, as shown in the following code snippet from Listing 7-8: get_id : function() { return this.id; }, set_id : function(value) { this.id = value; this.raisePropertyChanged(“id”); },
Because the new version of the Monitor class derives from the Component base class, it automatically inherits the get_id and set_id methods from its base class and, consequently, there is no need to implement these two methods. The following code fragment shows the set_id method of the Component base class: function Sys$Component$set_id(value) { if (this._idSet) throw Error.invalidOperation(Sys.Res.componentCantSetIdTwice); this._idSet = true; var oldId = this.get_id(); if (oldId && Sys.Application.findComponent(oldId)) throw Error.invalidOperation(Sys.Res.componentCantSetIdAfterAddedToApp); this._id = value; }
As this code shows, the set_id method performs the following two tasks before it sets the id of the component:
1.
It raises an exception if the set_id method has already been invoked to ensure that the id of a component is not set twice:
if (this._idSet) throw Error.invalidOperation(Sys.Res.componentCantSetIdTwice);
269
c07.indd 269
8/20/07 8:09:17 PM
Chapter 7: Component Development Infrastructure 2.
It invokes the findComponent method on the current Application object to determine whether the current application already contains a component with the specified id, and if so, it raises an exception to ensure that the id of the component is not set after the component is added to the application:
if (oldId && Sys.Application.findComponent(oldId)) throw Error.invalidOperation(Sys.Res.componentCantSetIdAfterAddedToApp);
These two checks are necessary because the id of the component uniquely identifies the component among other components in the current ASP.NET AJAX application. If you implement a custom component that derives from the Component base class, and your custom component needs to override the set_id method to run some custom code, your custom component’s implementation of this method must use the callBaseMethod method to invoke the set_id method of its base class. Otherwise, the two checks will not be performed.
raisePropertyChanged The Monitor class implements a method named raisePropertyChanged that raises the propertyChanged event and, consequently, invokes the event handlers registered for this event, as shown in the following code fragment from Listing 7-8: raisePropertyChanged : function (propertyName) { if (!this.events) return; var handler = this.events.getHandler(“propertyChanged”); if (handler) handler(this, new Sys.PropertyChangedEventArgs(propertyName)); },
As you can see in the following code listing, the Component base class exposes the same method, which contains the same logic: function Sys$Component$raisePropertyChanged(propertyName) { if (!this._events) return; var handler = this._events.getHandler(“propertyChanged”); if (handler) handler(this, new Sys.PropertyChangedEventArgs(propertyName)); }
Because the new implementation of the Monitor class inherits the Component base class, it automatically inherits the raisePropertyChanged method from its base class and, therefore, there is no need to implement this method.
270
c07.indd 270
8/20/07 8:09:18 PM
Chapter 7: Component Development Infrastructure If you implement a custom component that derives from the Component base class, and your custom component needs to override the raisePropertyChanged method to run some custom code, your custom component’s implementation of the raisePropertyChanged method must use the callBaseMethod method to invoke the raisePropertyChanged method of the base class. Otherwise the propertyChanged event of your custom component will be not raised and, consequently, the event handlers registered for this event will not be invoked.
get_events Classes such as Monitor that expose events must perform the following tasks:
1.
Support a method such as get_events that returns a reference to the EventHandlerList object where the class stores all the event handlers registered for the events of the class. The following code presents a typical implementation of this method: get_events : function() { if (!this.events) this.events = new Sys.EventHandlerList(); return this.events; },
2.
Support a method named add_EventName where the EventName is the placeholder for the name of the event. This method normally takes a single argument that references a JavaScript function and registers this function as the event handler for the specified event. The following code fragment presents a typical implementation of this method. As you can see, this method first invokes the method in step 1 to return a reference to the EventHandlerList object and then invokes the addHandler method on this object to register the specified handler for the event with the specified name.
add_EventName : function (handler) { var eventHandlerList = this.get_events(); eventHandlerList.addHandler(“EventName”, handler); }
3.
Support a method named remove_EventName where the EventName is the place holder for the name of the event. This method normally takes a single argument that references a JavaScript function and registers this function as the event handler for the specified event. The following code fragment presents a typical implementation of this method. As you can see, this method first invokes the method in step 1 to return a reference to the EventHandlerList object and then invokes the removeHandler method on this object to remove the specified handler from the list of event handlers registered for the event with the specified name.
remove_EventName : function (handler) { var eventHandlerList = this.get_events(); eventHandlerList.removeHandler(“EventName”, handler); }
271
c07.indd 271
8/20/07 8:09:18 PM
Chapter 7: Component Development Infrastructure Because the Component base class implements the get_events method, any class that derives from the Component base class automatically inherits this method and, consequently, does not need to re-implement this method. The class only needs to implement the add_EventName and remove_EventName methods. Therefore, the new version of the Monitor class does not need to implement the get_events method.
INotifyPropertyChange As discussed earlier and shown in the following code fragment, the Component base class implements the INotifyPropertyChange interface and its add_propertyChanged and remove_propertyChanged methods: function Sys$Component$add_propertyChanged(handler) { this.get_events().addHandler(“propertyChanged”, handler); } function Sys$Component$remove_propertyChanged(handler) { this.get_events().removeHandler(“propertyChanged”, handler); }
Because the new version of the Monitor class derives from the Component base class, it automatically inherits these two methods from the base class and, consequently, does not need to implement these two methods. If you derive a custom component from the Component base class, and if your custom component needs to override the add_ propertyChanged or remove_ propertyChanged method to run some custom code, your custom component’s implementation of these two methods must use the callBaseMethod method to invoke the add_ propertyChanged or remove_ propertyChanged method of the Component base class. Otherwise, the clients of your custom component will not be able to register or unregister event handlers for the propertyChanged event of your component.
INotifyDisposing As discussed earlier and shown in the following code fragment, the Component base class implements the INotifyDisposing interface and its add_disposing and remove_disposing methods: function Sys$Component$add_disposing(handler) { this.get_events().addHandler(“disposing”, handler); } function Sys$Component$remove_disposing(handler) { this.get_events().removeHandler(“disposing”, handler); }
272
c07.indd 272
8/20/07 8:09:18 PM
Chapter 7: Component Development Infrastructure Because the new version of the Monitor class derives from the Component base class, it automatically inherits these two methods from the base class and, consequently, does not need to implement these two methods. If you derive a custom component from the Component base class, and if your custom component needs to override the add_disposing or remove_disposing method to run some custom code, your custom component’s implementation of these two methods must use the callBaseMethod method to invoke the add_disposing or remove_disposing method of the Component base class. Otherwise, the clients of your custom component will not be able to register or un-register event handlers for the disposing event of your component. Listing 7-37 presents the content of the Monitor.js JavaScript file that contains the implementation of the new version of the Monitor class.
Listing 7-37: The Content of the Monitor.js JavaScript File that Contains the New Version of the Monitor Class Type.registerNamespace(“CustomComponents”); CustomComponents.Monitor = function() { CustomComponents.Monitor.initializeBase(this); } CustomComponents.Monitor.prototype = { print : function(domEvent) { this.div.innerHTML = String.format(this.printFormat, this.get_id(), domEvent.clientX, domEvent.clientY) }, dispose : function() { $removeHandler(document, “mousemove”, this.delegate); CustomComponents.Monitor.callBaseMethod(this, “dispose”); }, set_fontSize : function(value) { if (value != this.fontSize) { this.raisePropertyChanged(“fontSize”); this.fontSize = value; this.div.style.fontSize = this.fontSize + “px”; } }, get_fontSize : function() { return this.fontSize; },
As this listing shows, the Monitor class exposes two new methods named get_fontSize and set_fontSize that allow you to change the font size for the text that displays the current x and y coordinates of the mouse pointer: set_fontSize : function(value) { if (value != this.fontSize) { this.raisePropertyChanged(“fontSize”); this.fontSize = value; this.div.style.fontSize = this.fontSize + “px”; } }, get_fontSize : function() { return this.fontSize; },
Note that the set_fontSize method calls the raisePropertyChanged method of the Component base class, passing in the name of the property — that is, the string value “fontSize“ — to raise the propertyChanged event. Next, the print method is modified to use the font size: print : function(domEvent) { this.div.innerHTML = String.format(this.printFormat, this.get_id(), domEvent.clientX, domEvent.clientY) },
Finally, the end of the JavaScript file shown in Listing 7-37 contains the following script: if(typeof(Sys)!==’undefined’) Sys.Application.notifyScriptLoaded();
274
c07.indd 274
8/20/07 8:09:19 PM
Chapter 7: Component Development Infrastructure You must always include this script at the end of JavaScript files that contain the required scripts for your ASP.NET AJAX application. As you can see, this script invokes the notifyScriptLoaded method on the current Application object to notify the object that the loading of the current JavaScript file is completed. Listing 7-38 presents a page that uses the new version of the Monitor class.
Listing 7-38: A Page that Uses the New Version of the Monitor Class Untitled Page var monitor; function disposingcb() { alert(“The Disposing event was raised!”); } function propertyChangedcb(sender,e) { alert(e.get_propertyName() + “ property changed!”); } function changeFontSize(domEvent) { var fontSizetxt = $get(“fontSizetxt”); monitor.set_fontSize(fontSizetxt.value); } function changeId(domEvent) { var id = $get(“id”); try { monitor.set_id(id.value); } catch (ex) { alert(ex.message); } }
(continued)
275
c07.indd 275
8/20/07 8:09:19 PM
Chapter 7: Component Development Infrastructure Listing 7-38 (continued) function pageLoad() { var type = CustomComponents.Monitor; var properties = {id : “Monitor1”}; var events = {disposing : disposingcb, propertyChanged : propertyChangedcb}; var references = null; var element = null; monitor = $create(type, properties, events, references, element); var changeIdbtn = $get(“changeIdbtn”); $addHandler(changeIdbtn, “click”, changeId); var changeFontSizebtn = $get(“changeFontSizebtn”); $addHandler(changeFontSizebtn, “click”, changeFontSize); } Enter new Monitor id: Change Id Enter new font size: Change Font Size
As you can see, this pageLoad method invokes the create static method on the Component base class (recall that $create is shortcut for the create static method), passing in the following five parameters to instantiate and initialize a Monitor object and to add this object to the current ASP.NET AJAX application:
❑
type: This parameter references the constructor of the Monitor class — CustomComponents .Monitor. The type information must also contain the complete namespace containment
hierarchy of the class being instantiated. var type = CustomComponents.Monitor;
The create static method invokes the new operator on this constructor to instantiate the component.
❑
properties: This parameter is an object whose property values are used to initialize the properties of the component that have the same names as the properties of the object. Typically, this
276
c07.indd 276
8/20/07 8:09:19 PM
Chapter 7: Component Development Infrastructure object is a JavaScript object literal that contains one name/value pair for each property being initialized: var properties = {id : “Monitor1”};
In this case, you’re only initializing the id property of the Monitor class. The Monitor class inherits this property from the Component base class.
❑
events: This parameter is an object whose property values are registered as event handlers for the events of the component that have the same names as the properties of the object. Typically, this object is a JavaScript object literal that contains one name/value pair for each event of interest: var events = {disposing : disposingcb, propertyChanged : propertyChangedcb};
In this case, the object literal consists of two name/value pairs:
❑
❑
The name part of the first name/value pair contains the word disposing, which is the name of the Monitor class’s disposing event, and the value part of this pair references the disposingcb JavaScript function. This instructs the create static method to register the disposingcb function as the event handler for the disposing event.
❑
The name part of the second name/value pair contains the word propertyChanged, which is the name of the Monitor class’s propertyChanged event, and the value part of this pair references the propertyChangedcb JavaScript function. This instructs the create static method to register the propertyChangedcb function as the event handler for the propertyChanged event of the newly instantiated Monitor object.
references: This parameter is an object whose property values are used to initialize the properties of the component that have the same names as the properties of the object and reference other components in the current application. Typically, this object is a JavaScript object literal that contains one name/value pair for each property being initialized. In this case, the Monitor class does not expose any properties that reference other components in the current application. Therefore, you pass null as the value of this parameter: var references = null;
❑
element: This parameter references the DOM element associated with the component being initialized. In this case, the Monitor class is not associated with any DOM elements on the current page, so you pass null as the value of this parameter: var element = null;
As you can see, the pageLoad method invokes the create static method and passes the five parameters into it. The create method instantiates and initializes a Monitor object, adds the object to the current application, and returns a reference to this object. The pageLoad method stores this reference in a variable named monitor for future reference: monitor = $create(type, properties, events, references, element);
277
c07.indd 277
8/20/07 8:09:20 PM
Chapter 7: Component Development Infrastructure The pageLoad method then registers the changeId JavaScript function as the event handler for the click event of the changeIdbtn HTML button: var changeIdbtn = $get(“changeIdbtn”); $addHandler(changeIdbtn, “click”, changeId);
Finally, the pageLoad method registers the changeFontSizebtn JavaScript function as the event handler for the click event of the changeFontSizebtn HTML button: var changeFontSizebtn = $get(“changeFontSizebtn”); $addHandler(changeFontSizebtn, “click”, changeFontSize);
If you run this page, you should see the result shown in Figure 7-4. As you can see, the page consists of two text boxes and their associated buttons.
Figure 7-4 Enter a new value for the font size and click the Change Font Size button. You should see the pop-up message shown in Figure 7-5.
Figure 7-5
278
c07.indd 278
8/20/07 8:09:20 PM
Chapter 7: Component Development Infrastructure Next, enter a new URL in the address bar of your browser and press Enter to load the new page. The browser displays the pop-up message shown in Figure 7-6 before it loads the new page. This message indicates that the Application object automatically invoked the dispose method on the Monitor object before disposing of the object.
Figure 7-6 The changeId JavaScript function wraps the call into the set_id method of the Monitor object in a try block and catches the associated exception in the catch block, as shown in the following code excerpt from Listing 7-38: function changeId(domEvent) { var id = $get(“id”); try { monitor.set_id(id.value); } catch (ex) { alert(ex.message); } }
As discussed earlier and shown again in highlighted portion of the following code fragment, the set_id method raises an exception if the value of the id is being set twice: function Sys$Component$set_id(value) { if (this._idSet) throw Error.invalidOperation(Sys.Res.componentCantSetIdTwice); this._idSet = true; var oldId = this.get_id(); if (oldId && Sys.Application.findComponent(oldId)) throw Error.invalidOperation(Sys.Res.componentCantSetIdAfterAddedToApp); this._id = value; }
279
c07.indd 279
8/20/07 8:09:20 PM
Chapter 7: Component Development Infrastructure The create static method of the Component base class sets the specified properties of the component to the specified values (previously shown in Listing 7-5). Because Listing 7-39 invokes the set_id method after the call into the create method — that is, after id property value is set — the set_id method invoked within the changeId JavaScript function shown in Listing 7-39 is bound to raise an exception. To see this in action, run the application again. Enter a new id for the Monitor and click the Change Monitor Id button. This should pop up the alert shown in Figure 7-7.
Figure 7-7
Summar y This chapter presented some of the important classes and interfaces that make up the ASP.NET AJAX component-development framework. This chapter also provided in-depth coverage of the two main classes of the ASP.NET AJAX component-development infrastructure: the _Application and Component classes. The next chapter presents a breed of components named client controls.
280
c07.indd 280
8/20/07 8:09:21 PM
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 implementation 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.
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 represents it: element.control = this;
282
c08.indd 282
8/20/07 6:05:05 PM
Chapter 8: Developing Client Controls 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.
283
c08.indd 283
8/20/07 6:05:05 PM
Chapter 8: Developing Client Controls 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 operation, 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; }
284
c08.indd 284
8/20/07 6:05:06 PM
Chapter 8: Developing Client Controls
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 containment 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 represented by a Control object, the get_parent method returns null. This means that it is possible to have a Control object without a parent.
285
c08.indd 285
8/20/07 6:05:06 PM
Chapter 8: Developing Client Controls
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 enumeration 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 visibilityMode 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 properties affects the DOM element that it represents. In this case, setting the visibilityMode property of a
286
c08.indd 286
8/20/07 6:05:06 PM
Chapter 8: Developing Client Controls 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 Boolean 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’; } }
287
c08.indd 287
8/20/07 6:05:07 PM
Chapter 8: Developing Client Controls
addCssClass 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 addCssClass Method of the Control Class function Sys$UI$Control$addCssClass(className) { Sys.UI.DomElement.addCssClass(this._element, className); }
removeCssClass 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 removeCssClass Method of the Control Class function Sys$UI$Control$removeCssClass(className) { Sys.UI.DomElement.removeCssClass(this._element, className); }
toggleCssClass 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 represents, as shown in Listing 8-14. What this means is that if the DOM element already contains the specified CSS class, the toggleCssClass method removes the CSS class. Otherwise, the method adds the CSS class to the DOM element.
Listing 8-14: The toggleCssClass 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.
288
c08.indd 288
8/20/07 6:05:07 PM
Chapter 8: Developing Client Controls 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; } }
onBubbleEvent 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 onBubbleEvent 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 implementation of the method must return false to allow the event to bubble further up in the containment hierarchy 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.
289
c08.indd 289
8/20/07 6:05:07 PM
Chapter 8: Developing Client Controls
raiseBubbleEvent 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 raiseBubbleEvent 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.
290
c08.indd 290
8/20/07 6:05:08 PM
Chapter 8: Developing Client Controls Every ASP.NET AJAX client control emulates its corresponding ASP.NET server control as much as possible. As such, they expose similar methods and properties as their server counterparts. The ASP.NET AJAX client-side framework includes with a Sys.Preview namespace defined as follows: Type.registerNamespace(‘Sys.Preview’);
The Sys.Preview namespace contains a UI namespace defined as follows: Type.registerNamespace(‘Sys.Preview.UI’);
The Sys.Preview.UI namespace contains several client controls that directly or indirectly derive from the ASP.NET AJAX Control base class. The following sections walk you through the code for these client controls to help you gain the skills you need to develop your own custom client controls. You’ll also take a look at the code for Web pages that use these client controls.
Label Client Control The ASP.NET AJAX Label client control is the ASP.NET AJAX representation of the HTML element. The Label client control derives from the Control base class and extends its functionality to add support for two new properties named htmlEncode and text. The following sections discuss the members of the Label client control.
Constructor Listing 8-18 presents the implementation of the constructor of the Label client control. Note that this constructor takes a single argument, which references the DOM span element that the Label control represents.
Listing 8-18: The Constructor of the Label Client Control Sys.Preview.UI.Label = function Sys$Preview$UI$Label(associatedElement) { Sys.Preview.UI.Label.initializeBase(this, [associatedElement]); } Sys.Preview.UI.Label.registerClass(‘Sys.Preview.UI.Label’,Sys.UI.Control);
This constructor calls the initializeBase method to invoke the constructor of its base class— 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-19.
291
c08.indd 291
8/20/07 6:05:08 PM
Chapter 8: Developing Client Controls Listing 8-19: The Getter and Setter Methods of the htmlEncode Property function Sys$Preview$UI$Label$get_htmlEncode() { return this._htmlEncode; } function Sys$Preview$UI$Label$set_htmlEncode(value) { this._htmlEncode = value; }
text Listing 8-20 presents the implementation of the Label control’s get_text getter method, which returns the value of the text property of the control.
Listing 8-20: The get_text Getter Method of the Label Control function Sys$Preview$UI$Label$get_text() { var element = this.get_element(); if (this._htmlEncode) return element.innerText; else return element.innerHTML; }
This method first calls the get_element method to return a reference to the DOM element that the Label control represents: var element = this.get_element();
The Label control inherits the get_element method from its base class—Control. Next, the get_text method checks whether the value of the htmlEncode property is set to true. If so, it returns the value of the innerText property of the DOM element that the Label control represents: if (this._htmlEncode) return element.innerText;
If not, it returns the value of the innerHTML property of the DOM element that the Label control represents: else return element.innerHTML;
Listing 8-21 presents the implementation of the set_text method of the Label control.
292
c08.indd 292
8/20/07 6:05:08 PM
Chapter 8: Developing Client Controls Listing 8-21: The set_text Method of the Label Control function Sys$Preview$UI$Label$set_text(value) { if (!value) value=””; var element = this.get_element(); if (this._htmlEncode) { if (element.innerText !== value) { element.innerText = value; this.raisePropertyChanged(‘text’); } } else { if (element.innerHTML !== value) { element.innerHTML = value; this.raisePropertyChanged(‘text’); } } }
This method first calls the get_element method of its base class to return a reference to the DOM element that the Label control represents: var element = this.get_element();
Next, it checks whether the value of the Label control’s htmlEncode property has been set to true. If so, it assigns the new value to the innerText property of the DOM element and calls the raisePropertyChanged method to raise the propertyChanged event: element.innerText = value; this.raisePropertyChanged(‘text’);
The Label control inherits the raisePropertyChanged method from the Component base class. If the htmlEncode property has been set to false, get_text assigns the new value to the innerHTML property of the DOM element and calls the raisePropertyChanged method to raise the propertyChanged event. The get_text and set_text methods of the Label control constitute convenient wrappers around the innerText and innerHTML properties of the DOM element that the control represents. If you’re wondering how the get_text and set_text methods work in a browser such as Firefox that does not support the innerText property, the answer lies in the Mozilla compatibility layer of the ASP. NET AJAX client-side framework, which includes the logic that adds the support for this property. Refer to the PreviewScripts.js JavaScript file for more information on the Mozilla compatibility layer.
293
c08.indd 293
8/20/07 6:05:09 PM
Chapter 8: Developing Client Controls
prototype As Listing 8-22 shows, the get_htmlEncode, set_htmlEncode, get_text, and set_text methods of the Label client control are directly defined on the prototype property of the control. This means that these methods are instance methods and must be invoked on the instances of the Label control class, not the class itself.
Listing 8-22: The prototype Property of the Label Control Sys.Preview.UI.Label.prototype = { _htmlEncode: false, get_htmlEncode: Sys$Preview$UI$Label$get_htmlEncode, set_htmlEncode: Sys$Preview$UI$Label$set_htmlEncode, get_text: Sys$Preview$UI$Label$get_text, set_text: Sys$Preview$UI$Label$set_text }
descriptor Every component, including the Label control, must expose a property named descriptor that references an object literal describing the members of the component. The ASP.NET AJAX client-side framework includes a class named TypeDescriptor that uses the descriptor property of a component to discover its members. In other words, the descriptor property of a component contains metadata about the type of the component and its members. As such, the descriptor property of a component must always be defined directly on the component class itself. The descriptor property of a component references an object literal that contains one or more name/ value pairs, where each name/value pair describes a specific group of members. The name part of the name/value pair that describes the properties of a component contains the word properties, and the value part is an array of object literals where each object literal describes a particular property. In the case of the Label control, this array contains two object literals, where the first object literal describes the htmlEncode property and the second object literal describes the text property (see Listing 8-23). Each object literal contains two name/value pairs. The name part of the first name/value pair is the word name, and the value part is the string that contains the name of the property being described. The name part of the second name/value pair is the word type, and the value part references the constructor of the type of the property being described.
Listing 8-23: The descriptor Property of the Label Control Sys.Preview.UI.Label.descriptor = { properties: [ { name: ‘htmlEncode’, type: Boolean }, { name: ‘text’, type: String } ] }
294
c08.indd 294
8/20/07 6:05:09 PM
Chapter 8: Developing Client Controls
Using Label Client Control Listing 8-24 presents a page that uses the Label client control.
Listing 8-24: A Page that Uses the Label Client Control Untitled Page var label; function clickcb(domEvent) { var chkbx = $get(“chkbx”); label.set_htmlEncode($get(“chkbx”).checked); var txtbx = $get(“txtbx”); label.set_text(txtbx.value); } function pageLoad() { var btn = $get(“btn”); $addHandler(btn, “click”, clickcb); label = $create(Sys.Preview.UI.Label, null, null, null, $get(“myspan”)); } Enable HTML encoding Enter text: Submit
295
c08.indd 295
8/20/07 6:05:09 PM
Chapter 8: Developing Client Controls Figure 8-1 shows what you’ll see in your browser when you access this page:
❑
A check box that allows you to toggle HTML encoding on or off
❑
A text box where you can enter text
❑
A Submit button
❑
A HTML element
Figure 8-1 When you enter a text into the text box and click the Submit button, the callback for the button retrieves the text and displays it inside the HTML element. 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, on the other hand, the HTML encoding is on. In this case, the opening and closing tags of the element are HTML encoded and consequently the element displays these tags as if they were normal non-HTML characters.
Figure 8-2
296
c08.indd 296
8/20/07 6:05:10 PM
Chapter 8: Developing Client Controls Note that the page shown in Listing 8-24 contains the following reference:
This script references a JavaScript file named PreviewScripts.js that contains the definition of the Label client control. This JavaScript file is embedded in the Microsoft.Web.Preview.dll assembly. You need to add this assembly to the bin directory of your application. When you install the Microsoft ASP.NET Futures, it automatically adds the necessary template to the Visual Studio. Therefore, if you use this template when you’re creating a new Web site, the Microsoft.Web.Preview.dll assembly will be automatically added to the bin directory of your Web site. As Listing 8-24 shows, pageLoad calls the addHandler static method on the DomEvent class to register the clickcb JavaScript function as the event handler for the click event of the Submit button: var btn = $get(“btn”); $addHandler(btn, “click”, clickcb);
Then pageLoad instantiates an instance of the Label client control to represent the HTML element: label = $create(Sys.Preview.UI.Label, null, null, null, $get(“myspan”));
Now let’s walk through the code for the clickcb JavaScript function. This function first uses the $get global JavaScript function to return a reference to the check box element: var chkbx = $get(“chkbx”);
It then passes the check box status into the set_htmlEncode method of the Label client control: label.set_htmlEncode($get(“chkbx”).checked);
Finally, it calls the set_text method on the Label client control that represents the element to display the value entered into the text box: var txtbx = $get(“txtbx”); label.set_text(txtbx.value);
Image Client Control The ASP.NET Image server control is the ASP.NET representation of an image DOM element. As such, it exposes the width, height, src, and alt properties of this DOM element as the Width, Height, ImageURL, and AlternateText properties on the Image server control itself. This allows you to treat these DOM properties as properties on the Image server-control.NET 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
c08.indd 297
8/20/07 6:05:10 PM
Chapter 8: Developing Client Controls alterateText properties on the Image client control itself. This allows you to treat these DOM properties as properties on an ASP.NET AJAX Image client control object. The following sections discuss the implementation of the Image client control members.
Constructor As Listing 8-25 shows, the constructor of the Image client control takes a single argument, which references the HTML element the Image client control will represent. This constructor simply calls the initializeBase method to invoke the constructor of its Control base class, passing in the reference to the element. The registerClass method is then called to register the Image class as the subclass of the Control base class.
Listing 8-25: The Constructor of the Image Client Control Sys.Preview.UI.Image = function Sys$Preview$UI$Image(associatedElement) { Sys.Preview.UI.Image.initializeBase(this, [associatedElement]); } Sys.Preview.UI.Image.registerClass(‘Sys.Preview.UI.Image’, Sys.UI.Control);
prototype Listing 8-26 presents the implementation of the prototype property of the Image client control. In this implementation, an object literal describing all the instance methods of the control has been assigned to the prototype property. As discussed in the previous chapter, an instance method of a class is a method that is directly defined on the prototype property of the class, as opposed to the class itself. An instance method must always be invoked on an instance of a class, not the class itself.
Listing 8-26: The prototype Property of the Image Client Control Sys.Preview.UI.Image.prototype = { get_alternateText: Sys$Preview$UI$Image$get_alternateText, set_alternateText: Sys$Preview$UI$Image$set_alternateText, get_height: Sys$Preview$UI$Image$get_height, set_height: Sys$Preview$UI$Image$set_height, get_imageURL: Sys$Preview$UI$Image$get_imageURL, set_imageURL: Sys$Preview$UI$Image$set_imageURL, get_width: Sys$Preview$UI$Image$get_width, set_width: Sys$Preview$UI$Image$set_width }
As you can see in this listing, the Image client control exposes four pairs of instance methods. Each pair allows you to set and get the value of a particular property of the Image class. For example, the set_height and get_height instance methods allow you to set and get the value of the height property of the Image client control. The four properties that the Image client control exposes — width, height, imageURL, and alternateText — are given the same names as the corresponding properties of its Image server control counterpart to make client-side programming feel more like server-side ASP.NET programming.
298
c08.indd 298
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-27. As you can see from this code listing, both methods first call the get_element method to return a reference to the element that the Image client control represents. The Image client control inherits this method from its Control base class.
Listing 8-27: The set_imageURL and get_imageURL Methods of the Image Client Control function Sys$Preview$UI$Image$get_imageURL() { return this.get_element().src; } function Sys$Preview$UI$Image$set_imageURL(value) { this.get_element().src = value; }
width The Image client control exposes two methods named get_width and set_width that allow you to get and set the value of the width property of the image DOM element that the control represents. As you can see in Listing 8-28, these methods are just wrappers around the width property of the DOM element, which means you can treat this the same way as a property on an ASP.NET AJAX object.
Listing 8-28: The set_width and get_width Methods of the Image Client Control function Sys$Preview$UI$Image$get_width() { return this.get_element().width; } function Sys$Preview$UI$Image$set_width(value) { this.get_element().width = value; }
height As you can see in Listing 8-29, the set_height and get_height methods act as wrappers around the height property of the underlying image DOM element. This enables you to treat this as a property on an ASP.NET AJAX object, which is the Image client control in this case.
Listing 8-29: The set_height and get_height Methods of the Image Client Control function Sys$Preview$UI$Image$get_height() { return this.get_element().height;
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 same way as you would to get and set the value of this property using the ASP.NET Framework (see Listing 8-30).
Listing 8-30: The set_alternateText and get_alternateText Methods of the Image Client Control function Sys$Preview$UI$Image$get_alternateText() { return this.get_element().alt; } function Sys$Preview$UI$Image$set_alternateText(value) { this.get_element().alt = value; }
Using the Image Client Control Listing 8-31 presents a page that uses the Image client control. Previously, we implemented a similar page that showed how to use the Label client control where the page used the following script reference to reference the PreviewScript.js JavaScript file embedded in the Microsoft.Web.PreviewScript.dll assembly:
As you can see, Listing 8-31 uses the same script reference because the same JavaScript file also contains the definition of the Image client control.
Listing 8-31: A Page that uses the Image client control Untitled Page
300
c08.indd 300
8/20/07 6:05:11 PM
Chapter 8: Developing Client Controls function pageLoad() { var type = Sys.Preview.UI.Image; var properties = { imageURL: “wroxProgrammerSmall.jpg”, alternateText : “Wrox Programmer’s Reference Series”, width: 155, height: 58 }; var events = null; var references = null; var element = $get(“myImage”); $create(type, properties, events, references, element); }
The pageLoad method uses the $create shortcut method (the shortcut for the create static method of the Component base class) to instantiate and initialize an Image client control and to add the control to the _components collection of the Application object that represents the current ASP.NET AJAX application. pageLoad passes the following parameters into the create method:
❑
type: This parameter references the constructor of the component being created, which is the Sys.Preview.UI.Image constructor in this case.
❑
properties: This parameter references an object (normally an object literal) that contains the names and values of the properties of the component being created that you want to initialize. The create method internally assigns these values to the properties with the specified names. In this case, the object literal contains four name/value pairs where the name and value parts of each pair respectively contain the name and value of a particular property of the Image client control being created: var properties = { imageURL: “wroxProgrammerSmall.jpg”, alternateText : “Wrox Programmer’s Reference Series”, width: 155, height: 58 };
❑
events: This parameter references an object (normally an object literal) that specifies the event handlers that you want to register for events with the specified names. In this case, the events object is null so any event handlers will be registered.
❑
references: This parameter references an object (normally an object literal) that specifies the values of the properties of the component being created that reference other components in the _components collection of the current Application object. In this case, this object is null
301
c08.indd 301
8/20/07 6:05:11 PM
Chapter 8: Developing Client Controls because the Image client control does not expose any properties that reference other components of the application.
❑
element: This parameter references the DOM element on the current page that the newly created Image client control will represent. In this case, this parameter references the HTML element with id HTML attribute value of “myimage“: var element = $get(“myImage”);
The pageLoad method then invokes the create method, passing in the five parameters to create the Image client control: $create(type, properties, events, references, element);
Extending Image Client Control In this section, we’ll implement a client control named Image2 that extends the functionality of the Image client control to add support for a DHTML feature known as transition. The Image2 client control will use the transition feature to provide an animated effect when the user moves the mouse pointer over and out of the DOM image element that the control represents. Because this feature is only supported on Internet Explorer version 4 (IE4) or higher, we need a way to ensure that the Image2 client control is used in only IE4 or higher. The ASP.NET AJAX client-side framework defines an object named browser, as presented in Listing 8-32, which emulates the HttpBrowserCapabilities class in the ASP.NET Framework.
As you can see in this listing, the ASP.NET AJAX client-side framework automatically populates the browser object with the information about the current browser when the ASP.NET AJAX scripts are downloaded. The browser object exposes two important properties named agent and version that specify the type and version of the current browser. The possible values of the agent property are Sys.Browser.InternetExplorer, Sys.Browser.Firefox, Sys.Browser.Safari, and Sys.Browser .Opera. Now back to the original goal, which is implementing the Image2 client control that supports the transition DHTML feature. Listing 8-33 presents the Image2.js JavaScript file that defines the Image2 client control. The following sections discuss all the members of this control.
Listing 8-33: The Content of the Image2.js File Type.registerNamespace(“CustomComponents”); CustomComponents.Image2 = function CustomComponents$Image2(associatedElement) { if (Sys.Browser.agent != Sys.Browser.InternetExplorer || Sys.Browser.version < 4) throw Error.invalidOperation; CustomComponents.Image2.initializeBase(this, [associatedElement]); associatedElement.style.filter = ”revealTrans(duration=0.4, transition=1)”; } function CustomComponents$Image2$set_imageURL(value) { this.mouseOutImageURL = value; CustomComponents.Image2.callBaseMethod(this, “set_imageURL”, [value]); } function CustomComponents$Image2$get_mouseOverImageURL() { return this.mouseOverImageURL; }
Constructor Listing 8-34 presents the implementation of the Image2 client control’s constructor.
Listing 8-34: The Constructor of the Image2 Client Control CustomComponents.Image2 = function CustomComponents$Image2(associatedElement) { if (Sys.Browser.agent != Sys.Browser.InternetExplorer || Sys.Browser.version < 4) throw Error.invalidOperation; CustomComponents.Image2.initializeBase(this, [associatedElement]); associatedElement.style.filter = “revealTrans(duration=0.4, transition=1)”; } CustomComponents.Image2.registerClass(‘CustomComponents.Image2’, Sys.Preview.UI.Image);
The constructor takes a single argument that references the image DOM element that the Image2 client control represents. The constructor first uses the values of the agent and version properties of the Sys.Browser object to determine whether the current browser is IE4 or higher. If not, it raises an exception, which ensures that the Image2 client control is used only on IE4 or later browsers: if (Sys.Browser.agent != Sys.Browser.InternetExplorer || Sys.Browser.version < 4) throw Error.invalidOperation;
Next, the constructor calls the initializeBase method to invoke the constructor of its base class — that is, the Image client control: CustomComponents.Image2.initializeBase(this, [associatedElement]);
306
c08.indd 306
8/20/07 6:05:13 PM
Chapter 8: Developing Client Controls The constructor then adds the revealTrans filter to the image DOM element that the Image2 client control represents: associatedElement.style.filter = “revealTrans(duration=0.4, transition=1)”;
Note that Listing 8-33 registers the Image2 class as the subclass of the Image class: CustomComponents.Image2.registerClass(‘Sys.Preview.UI.Image2’, Sys.Preview.UI.Image);
prototype Listing 8-35 presents the code for the prototype property of the Image2 client control. This code listing assigns an object literal to the prototype property. Each name/value pair of this object literal describes a method of the Image2 client control. These methods are discussed in the following sections.
imageURL The Image2 client control overrides the set_imageURL method that it inherits from the Image client control and stores the value assigned to the src property of the underlying DOM element in a new field named mouseOutImageURL, as shown in Listing 8-36.
Listing 8-36: The set_imageURL Method of the Image2 Client Control function CustomComponents$Image2$set_imageURL(value) { this.mouseOutImageURL = value; CustomComponents.Image2.callBaseMethod(this, “set_imageURL”, [value]); }
Note that this code calls the callBaseMethod to invoke the set_imageURL method of the base class — the Image client control. As discussed in the previous sections, the set_imageURL method of the base class simply assigns the specified value to the src property of the underlying DOM element.
307
c08.indd 307
8/20/07 6:05:13 PM
Chapter 8: Developing Client Controls As the name implies, the image whose path is given by the mouseOutImageURL field will be displayed when the mouse moves out of the image DOM element.
mouseOverImageURL As Listing 8-37 shows, the Image2 client control exposes a property named mouseOverImageURL and two methods named get_mouseOverImageURL and set_mouseOverImageURL to get and set the value of this property. The value of this property must be set to the URL of the image that the Image2 client control will display when the end user moves the mouse pointer over the image DOM element that the control represents.
Listing 8-37: The set_mouseOverImageURL and get_mouseOverImageURL Methods function CustomComponents$Image2$get_mouseOverImageURL() { return this.mouseOverImageURL; } function CustomComponents$Image2$set_mouseOverImageURL(value) { this.mouseOverImageURL = value; }
mouseOverCallback When the end user moves the mouse pointer over the image DOM element that the Image2 client control represents, the mouseOverCallback method shown in Listing 8-38 is automatically invoked.
Listing 8-38: The mouseOverCallback Method function CustomComponents$Image2$mouseOverCallback () { this.get_element().filters[“revealTrans”].apply(); this.get_element().src = this.mouseOverImageURL; this.get_element().filters[“revealTrans”].play(); }
This method first calls the apply method on the revealTrans filter of the image DOM element to capture the snapshot of the element: this.get_element().filters[“revealTrans”].apply();
It then assigns the value of the mouseOverImageURL property to the src property of the DOM element: this.get_element().src = this.mouseOverImageURL;
Finally, it calls the play method on the revealTrans filter of the DOM element to display the image whose URL is given by the mouseOverImageURL property in animated fashion: this.get_element().filters[“revealTrans”].play();
308
c08.indd 308
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-39 is automatically invoked.
Listing 8-39: The mouseOutCallback Method function CustomComponents$Image2$mouseOutCallback () { this.get_element().filters[“revealTrans”].apply(); this.get_element().src = this.mouseOutImageURL; this.get_element().filters[“revealTrans”].play(); }
This method first calls the apply method on the revealTrans filter of the image DOM element to capture the snapshot of the element: this.get_element().filters[“revealTrans”].apply();
It then assigns the value of the mouseOutImageURL property to the src property of the DOM element: this.get_element().src = this.mouseOutImageURL;
Finally, it calls the play method on the revealTrans filter of the DOM element to display the image whose URL is given by the mouseOutImageURL property in animated fashion: this.get_element().filters[“revealTrans”].play();
Duration The revealTrans filter exposes a property named duration. As the name implies, the duration property is a float value that determines the duration of the animation. As you can see in Listing 8-40, the Image2 client control exposes two methods named get_duration and set_duration that get and set the value of the duration property of the revealTrans filter. Note that after setting the value of the property, the set_duration method calls the apply method on the revealTrans filter to take a new snapshot.
Listing 8-40: The get_duration and set_duration Methods function CustomComponents$Image2$get_duration() { return this.get_element().filters[“revealTrans”].duration; } function CustomComponents$Image2$set_duration(value) { this.get_element().filters[“revealTrans”].duration = value; this.get_element().filters[“revealTrans”].apply(); }
309
c08.indd 309
8/20/07 6:05:14 PM
Chapter 8: Developing Client Controls
transition The revealTrans filter exposes a property named transition that determines the animation flavor. The Image2 client control features two methods named get_transition and set_transition that allow you to get and set the value of the transition property of the revealTrans filter, as shown in Listing 8-41.
Listing 8-41: The get_transition and set_transition Methods function CustomComponents$Image2$get_transition() { return this.get_element().filters[“revealTrans”].transition; } function CustomComponents$Image2$set_transition(value) { this.get_element().filters[“revealTrans”].transition = value; this.get_element().filters[“revealTrans”].apply(); }
Transition Enumeration The transition property of the revealTrans filter takes one of the predefined possible values. As such, it makes lot of sense to define an enumeration type named Transition as shown in Listing 8-42. This ensures that only valid values are used for the transition property.
This method begins by invoking the initialize method of its base class: CustomComponents.Image2.callBaseMethod(this, “initialize”);
Next, it creates a delegate that represents the mouseOverCallback method of the Image2 control and stores this delegate in a private field named mouseOverDelegate for future reference: this.mouseOverDelegate = Function.createDelegate(this, this.mouseOverCallback);
Then, it creates another delegate to represent the mouseOutCallback method of the Image2 control and stores this delegate in a private field named mouseOutDelegate for future reference: this.mouseOutDelegate = Function.createDelegate(this, this.mouseOutCallback);
Next, it registers the mouseOverDelegate delegate as the event handler for the mouseover event of the Image2 control’s associated element. This means that when the end user moves the mouse over this element, the element will automatically invoke the mouseOverDelegate delegate, which in turn will invoke the mouseOverCallback method: $addHandler(this.get_element(), “mouseover”, this.mouseOverDelegate);
Finally, it registers the mouseOutDelegate delegate as the event handler for the mouseout event of the Image2 control’s associated element. This means that when the end user moves the mouse out of this
311
c08.indd 311
8/20/07 6:05:15 PM
Chapter 8: Developing Client Controls element, the element will automatically invoke the mouseOutDelegate delegate, which in turn will invoke the mouseOutCallback method: $addHandler(this.get_element(), “mouseout”, this.mouseOutDelegate);
dispose The Image2 control overrides the dispose method that it inherits from its base class, as shown in Listing 8-44. The current Application object automatically calls this method to allow the Image2 control to perform its final cleanup before the control is disposed of.
Listing 8-44: The dispose Method function CustomComponents$Image2$dispose() { $removeHandler(this.get_element(), “mouseover”, this.mouseoverDelegate); $removeHandler(this.get_element(), “mouseout”, this.mouseOutDelegate); CustomComponents.Image2.callBaseMethod(this, “dispose”); }
As you saw previously in Listing 8-43, the initialize method registered the mouseOverDelegate and mouseOutDelegate delegates as event handlers for the mouseover and mouseout events of the associated elements of the Image2 control. The dispose method simply removes these two delegates from the list of event handlers registered for the mouseover and mouseout events. Note that the method finally uses the callBaseMethod method to invoke the dispose method of its base class. Your custom component’s implementation of the dispose method must always invoke the dispose method of its base class to allow the base class to perform its final cleanup, raise the disposing event, and invoke the event handlers registered for this event.
Using Image2 Client Control Listing 8-45 shows a page where the Image2 client control is used.
Listing 8-45: A Page that Uses the Image2 Client Control Untitled Page function pageLoad() { var type = CustomComponents.Image2; var properties = {imageURL : “wroxProgrammerSmall.jpg”, alternateText : “Wrox Programmer’s Reference Series”, width : 155, height : 58,
312
c08.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); }
The page shown in this listing uses the to register the PreviewScript.js and Image2.js JavaScript files:
The pageLoad method passes the following five parameters into the create static method of the Component base class, using $create as a shortcut for this method:
❑
type: This parameter references the constructor of the Image2 client control, with the create method internally applying the new operator on this constructor to instantiate the client control: var type = CustomComponents.Image2;
❑
properties. This parameter is an object literal that contains one name/value pair for each property of the Image2 control to be initialized — which in this case are the property values of imageURL, alternateText, width, height, mouseOverImageURL, duration, and transition. The create method internally iterates through these name/value pairs and assigns the value part of each name/value pair to the property of the Image2 control with the same name as the name part of the pair.
events: Because no event handlers are being registered in this case, this parameter is null: var events = null;
❑
references: Because no property that references other components in the current application is being initialized in this case, this parameter is null: var references = null;
❑
element: This parameter references the DOM element that the Image2 control will represent: var element = $get(“myImage”);
The pageLoad method invokes the create method and passes the five parameters into it: $create(type, properties, events, references, element);
HyperLink Client Control The ASP.NET AJAX HyperLink client control derives from the Label client control and extends its functionality to enable you to program against the hyperlink DOM element () using an ASP.NET-like programming style.
Constructor Listing 8-46 presents the constructor of the HyperLink client control. At the end of this listing, the registerClass method is called to register the HyperLink class as the subclass of the Label class.
Listing 8-46: The Definition of the HyperLink Client Control Sys.Preview.UI.HyperLink = function Sys$Preview$UI$HyperLink(associatedElement) { Sys.Preview.UI.HyperLink.initializeBase(this, [associatedElement]); } Sys.Preview.UI.HyperLink.registerClass(‘Sys.Preview.UI.HyperLink’, Sys.Preview.UI.Label);
314
c08.indd 314
8/20/07 6:05:16 PM
Chapter 8: Developing Client Controls
prototype As you can see in Listing 8-47, an object literal has been assigned to the prototype property of the HyperLink client control. Note that each name/value pair of this object describes a member of the HyperLink class.
Listing 8-47: The prototype Property of the HyperLink Client Control Sys.Preview.UI.HyperLink.prototype = { _clickHandler: null, get_navigateURL: Sys$Preview$UI$HyperLink$get_navigateURL, set_navigateURL: Sys$Preview$UI$HyperLink$set_navigateURL, initialize: Sys$Preview$UI$HyperLink$initialize, dispose: Sys$Preview$UI$HyperLink$dispose, add_click: Sys$Preview$UI$HyperLink$add_click, remove_click: Sys$Preview$UI$HyperLink$remove_click, _onClick: Sys$Preview$UI$HyperLink$_onClick }
navigateURL The ASP.NET AJAX HyperLink client control is just like its server counterpart — that is, the ASP.NET HyperLink server control exposes a property named navigateURL. As Listing 8-48 shows, the setter and getter of this property — set_navigateURL and get_navigateURL — simply delegate to the href property of the DOM element that the HyperLink client control represents. These two .NET-like methods enable you to program against the href property using a .NET-like programming style.
Listing 8-48: The set_navigateURL and get_navigateURL Methods of the HyperLink Client Control function Sys$Preview$UI$HyperLink$get_navigateURL() { return this.get_element().href; } function Sys$Preview$UI$HyperLink$set_navigateURL(value) { this.get_element().href = value ? value : “”; }
initialize As you can see in Listing 8-49, the HyperLink client control overrides the initialize method that it inherits from its Label base class.
315
c08.indd 315
8/20/07 6:05:16 PM
Chapter 8: Developing Client Controls Listing 8-49: The initialize Method of the HyperLink Client Control function Sys$Preview$UI$HyperLink$initialize() { Sys.Preview.UI.HyperLink.callBaseMethod(this, ‘initialize’); this._clickHandler = Function.createDelegate(this, this._onClick); $addHandler(this.get_element(), “click”, this._clickHandler); }
First, the HyperLink client control calls the callBaseMethod method to invoke the initialize method of its base class: Sys.Preview.UI.HyperLink.callBaseMethod(this, ‘initialize’);
In general, every time you override the initialize method, you must use the callBaseMethod method from within your implementation of the initialize method to call the base class’s initialize method to allow the base class to initialize itself. The initialize method then calls the createDelegate method on the Function class to create a delegate that represents the _onClick method of the HyperLink client control. This delegate is stored in a field named _clickHandler for future reference: this._clickHandler = Function.createDelegate(this, this._onClick);
The initialize method then calls the addHandler static method on the DomEvent class to register the delegate as the event handler for the click event of the DOM element that the HyperLink client control represents: $addHandler(this.get_element(), “click”, this._clickHandler);
Therefore, when the DOM element is clicked, it automatically invokes the _clickHandler delegate, which in turn invokes the _onClick method on the HyperLink client control that represents the DOM element.
add_click Listing 8-50 presents the implementation of the add_click method of the HyperLink client control.
Listing 8-50: The add_click Method of the HyperLink Client Control function Sys$Preview$UI$HyperLink$add_click(handler) { this.get_events().addHandler(“click”, handler); }
This method enables you to register an event hander for the click event of the HyperLink client control — not the click event of the DOM element that the HyperLink client control represents. Keep in mind that the HyperLink client control is a wrapper around the DOM element. What the users actually interacts with is the DOM element, not the HyperLink client control. In other words, when the user clicks the DOM element, it is the DOM element that raises the click event, not the HyperLink client control.
316
c08.indd 316
8/20/07 6:05:16 PM
Chapter 8: Developing Client Controls You may be wondering what the connection is between the click event of the HyperLink client control and the click event of the DOM element that the control represents. You’ll learn the answer to this question shortly. For now, keep in mind that the add_click method of the HyperLink client control enables you to register an event handler for the click event of the HyperLink client control itself.
remove_click As you can see in Listing 8-51, the remove_click method of the HyperLink client control is the opposite of the add_click method. It removes a specified event handler from the list of event handlers registered for the click event of the HyperLink client control.
Listing 8-51: The remove_click Method of the HyperLink Client Control function Sys$Preview$UI$HyperLink$remove_click(handler) { this.get_events().removeHandler(“click”, handler); }
_onClick Listing 8-52 shows the code for the _onClick method of the HyperLink client control.
Listing 8-52: The_onClick Method of the HyperLink Client Control function Sys$Preview$UI$HyperLink$_onClick() { var handler = this.get_events().getHandler(“click”); if (handler) handler(this, Sys.EventArgs.Empty); }
This method first calls the get_events method to return a reference to the EventHandlerList that contains all the event handlers for the HyperLink client control events. The HyperLink client control inherits the get_events method from the Component base class. The _onClick method then invokes the getHandler method on the EventHandlerList to return a reference to the JavaScript function whose invocation automatically invokes all the event handlers registered for the HyperLink client control’s click event: var handler = this.get_events().getHandler(“click”);
Finally, the _onClick method invokes the JavaScript function, which in turn invokes all the event handlers registered for the HyperLink control’s click event. Now let’s put it altogether :
❑
The initialize method of the HyperLink client control registers the _onClick method as the event handler for the click event of the DOM element that the control represents (shown in Listing 8-49). This means that when the end user clicks the DOM element, the _onClick method of the HyperLink client control is automatically invoked.
317
c08.indd 317
8/20/07 6:05:17 PM
Chapter 8: Developing Client Controls ❑
The add_click method of the HyperLink client control adds a specified handler as the event handler for the click event of the HyperLink client control (shown in Listing 8-50).
❑
The _onClick method of the HyperLink client control calls all the event handlers registered for the click event of the HyperLink control (shown in Listing 8-52).
dispose The HyperLink client control overrides the dispose method that it inherits from its base class, as shown in Listing 8-53.
Listing 8-53: The dispose Method of the HyperLink Client Control function Sys$Preview$UI$HyperLink$dispose() { if (this._clickHandler) $removeHandler(this.get_element(), “click”, this._clickHandler); Sys.Preview.UI.HyperLink.callBaseMethod(this, ‘dispose’); }
The dispose method calls the removeHandler static method on the DomEvent class using $removeHandler as a shortcut) to remove the _clickHandler delegate from the list of event handlers registered for the HyperLink client control’s click event. As previously shown in Listing 8-49, the _clickHandler delegate represents the _onClick method of the HyperLink client control.
descriptor The HyperLink client control, like any other client component, exposes a property named descriptor, as shown in Listing 8-54.
Listing 8-54: The descriptor Property of the HyperLink Client Control Sys.Preview.UI.HyperLink.descriptor ={ properties: [ { name: ‘navigateURL’, type: String } ], events: [ { name: ‘click’ } ] }
This code listing assigns an object literal to the descriptor property. This object contains two name/ value pairs. The first name/value pair describes the name and types of the properties of the HyperLink client control. As discussed, this control exposes a single property of type string named navigateURL: properties: [ { name: ‘navigateURL’, type: String } ],
The second name/value pair describes the events that the control exposes. As discussed, the HyperLink client control exposes a single event named click: events: [ { name: ‘click’ } ]
318
c08.indd 318
8/20/07 6:05:17 PM
Chapter 8: Developing Client Controls
Using the HyperLink Client Control Listing 8-55 shows a page where the HyperLink client control is used.
Listing 8-55: A Page that Uses the HyperLink Client Control Untitled Page function pageLoad() { var type = Sys.Preview.UI.HyperLink; var properties = { navigateURL: “http://www.wrox.com”, text: “Wrox Web Site”, htmlEncode: false }; var events = null; var references = null; var element = $get(“myHyperLink”); $create(type, properties, events, references, element); }
The pageLoad JavaScript function invokes the create static method on the Component base class to instantiate and initialize an instance of the HyperLink client control to represent the specified HTML element. pageLoad passes the following object literal into the create method to initialize the navigateURL, text, and htmlEncode properties of the HyperLink client control being created. var properties = { navigateURL: “http://www.wrox.com”, text: “Wrox Web Site”, htmlEncode: false };
As discussed earlier, the HyperLink client control inherits the text and htmlEncode methods from the Label client control. Listing 8-56 shows an example that uses the click event of the HyperLink control.
319
c08.indd 319
8/20/07 6:05:17 PM
Chapter 8: Developing Client Controls Listing 8-56: A Page that Uses the Click Event of the HyperLink Client Control Untitled Page function clickCallback(domEvent) { alert(“Click event was raised!”); } function pageLoad() { var type = Sys.Preview.UI.HyperLink; var properties = { text: “Click here!”, htmlEncode: false }; var events = { click: clickCallback }; var references = null; var element = $get(“myHyperLink”); $create(type, properties, events, references, element); }
The pageLoad method in this code listing invokes the create static method on the Component base class to instantiate and initialize an instance of the HyperLink control. It passes the following parameters into the create method:
❑
type: This parameter references the constructor of the HyperLink client control. Keep in mind that the value of this parameter must contain the complete namespace containment hierarchy of the client component being instantiated. var type = Sys.Preview.UI.HyperLink;
❑
properties. This parameter is an object literal that specifies the values of the text and htmlEncode properties of the HyperLink client control being instantiated. var properties = { text: “Click here!”, htmlEncode: false };
320
c08.indd 320
8/20/07 6:05:18 PM
Chapter 8: Developing Client Controls ❑
events: This parameter is an object literal that specifies the clickCallback JavaScript function as the function to be registered as event handler for the click event of the HyperLink client con-
trol being instantiated. var events = { click: clickCallback };
❑
references. This parameter is null because no properties are being initialized that reference
other components of the current application. var references = null;
❑
element: This parameter references the DOM element with the id HTML attribute value of “myHyperLink”. var element = $get(“myHyperLink”);
Summar y This chapter first dove into the Control base class and its members. Then it provided you with in-depth coverage of several standard ASP.NET AJAX client controls. Finally, it showed you how to develop your own custom client controls. The next chapter moves on to the Button client control and event bubbling.
321
c08.indd 321
8/20/07 6:05:18 PM
c08.indd 322
8/20/07 6:05:18 PM
Event Bubbling and Button Client Control This chapter discusses the implementation of the ASP.NET AJAX Button client control and Web pages that use this control. You’ll also learn how to implement custom client controls that bubble their events up to their parent client controls, and how to implement custom client controls that catch the events that their child controls bubble up.
CommandEventArgs As you’ll see later in this chapter, the Button client control raises an event named command when the user clicks the button. The ASP.NET AJAX CommandEventArgs class is the event data class for the command event, as defined in Listing 9-1.
Listing 9-1: The CommandEventArgs Class Sys.Preview.UI.CommandEventArgs = function Sys$Preview$UI$CommandEventArgs(commandName, argument) { Sys.Preview.UI.CommandEventArgs.initializeBase(this); this._commandName = commandName; this._argument = argument; } function Sys$Preview$UI$CommandEventArgs$get_argument() { return this._argument; } function Sys$Preview$UI$CommandEventArgs$get_commandName() { return this._commandName; }
The CommandEventArgs class exposes two read-only properties of type string named commandName and argument. The constructor of this class takes two string parameters and assigns them to these two properties: Sys.Preview.UI.CommandEventArgs = function Sys$Preview$UI$CommandEventArgs(commandName, argument) { Sys.Preview.UI.CommandEventArgs.initializeBase(this); this._commandName = commandName; this._argument = argument; }
The constructor of this class is the only way to set the values of the commandName and argument properties. The CommandEventArgs class comes with two methods named get_commandName and get_argument that respectively return the values of the commandName and argument properties of the CommandEventArgs. The get_commandName and get_argument methods are defined on the prototype property of the CommandEventArgs class. As such, they are considered instance methods and must be invoked on a class instance. The CommandEventArgs class, like any other ASP.NET AJAX class, exposes a property named descriptor that describes the members of the class. An object literal with a single name/value pair is assigned to the prototype property. This name/value pair describes the commandName and argument properties of the CommandEventArgs class. Every ASP.NET AJAX event data class must directly or indirectly inherit from the EventArgs base class. The CommandEventArgs class is no exception: Sys.Preview.UI.CommandEventArgs.registerClass(‘Sys.Preview.UI.CommandEventArgs’, Sys.EventArgs);
324
c09.indd 324
8/21/07 1:02:54 AM
Chapter 9: Event Bubbling and Button Client Control
Button Client Control The ASP.NET Button server control exposes the following important features:
❑
An event named Command: When the end user clicks a Button server control, the control raises two events, Click and Command. The event data class associated with the Command event is an ASP.NET class named CommandEventArgs. When the Button server control invokes an event handler registered for its Command event, it passes an instance of the CommandEventArgs event data class into it.
❑
A property named CommandName: The Button server control assigns the value of its CommandName property to the CommandName property of the CommandEventArgs object that it passes into the event handlers registered for its Command event.
❑
A property named CommandArgument: The Button server control optionally assigns the value of its CommandArgument property to the CommandArgument property of the CommandEventArgs object that it passes into the event handlers registered for its Command event.
The ASP.NET AJAX Button client control emulates the ASP.NET Button server control to offer these three features on the client side, as discussed in the following sections.
Constructor As you can see in Listing 9-2, the constructor of the Button client control takes a single argument that references the DOM element that the control represents. The constructor calls the initializeBase method to invoke the constructor of its base class, passing in the reference to the DOM element. The Button client control is then registered as the subclass of the Control base class.
Listing 9-2: The Constructor of the Button Client Control Sys.Preview.UI.Button = function Sys$Preview$UI$Button(associatedElement) { Sys.Preview.UI.Button.initializeBase(this, [associatedElement]); } Sys.Preview.UI.Button.registerClass(‘Sys.Preview.UI.Button’, Sys.UI.Control)
prototype As Listing 9-3 shows, the Button client control exposes nine instance methods. They are instance methods because they’re directly defined on the prototype property of the class. As such, you must invoke these methods on a class instance.
325
c09.indd 325
8/21/07 1:02:55 AM
Chapter 9: Event Bubbling and Button Client Control Listing 9-3: The prototype Property of the Button Client Control Sys.Preview.UI.Button.prototype = { _command: null, _arg: null, _clickHandler: null, get_argument: Sys$Preview$UI$Button$get_argument, set_argument: Sys$Preview$UI$Button$set_argument, get_command: Sys$Preview$UI$Button$get_command, set_command: Sys$Preview$UI$Button$set_command, initialize: Sys$Preview$UI$Button$initialize, dispose: Sys$Preview$UI$Button$dispose, add_click: Sys$Preview$UI$Button$add_click, remove_click: Sys$Preview$UI$Button$remove_click, _onClick: Sys$Preview$UI$Button$_onClick }
argument The Button client control exposes a property named argument, which emulates the CommandArgument property of the Button server control. As Listing 9-4 shows, the get_argument and set_argument methods of the Button client control emulate the getter and setter of the Button server control’s CommandArgument property. Note that the set_argument method calls the raisePropertyChanged method to raise the propertyChanged event. The Button client control inherits this method from its base class.
Listing 9-4: The get_argument and set_argument Methods of the Button Client Control function Sys$Preview$UI$Button$get_argument() { return this._arg; } function Sys$Preview$UI$Button$set_argument(value) { if (this._arg !== value) { this._arg = value; this.raisePropertyChanged(‘argument’); } }
command As Listing 9-5 shows, the Button client control exposes a property named command and two methods named get_command and set_command that emulate the CommandName property of the Button server control and its associated getter and setter methods. Again, note that the set_command method invokes
326
c09.indd 326
8/21/07 1:02:55 AM
Chapter 9: Event Bubbling and Button Client Control the raisePropertyChanged method to raise the propertyChanged event and, consequently, to invoke all the event handlers registered for this event.
Listing 9-5: The get_command and set_command Methods of the Button Client Control function Sys$Preview$UI$Button$get_command() { return this._command; } function Sys$Preview$UI$Button$set_command(value) { if (this._command !== value) { this._command = value; this.raisePropertyChanged(‘command’); } }
initialize The Button client control overrides the initialize method that it inherits from its base class, as shown in Listing 9-6.
Listing 9-6: The initialize Method of the Button Client Control function Sys$Preview$UI$Button$initialize() { Sys.Preview.UI.Button.callBaseMethod(this, ‘initialize’); this._clickHandler = Function.createDelegate(this, this._onClick); $addHandler(this.get_element(), “click”, this._clickHandler); }
The Button client control’s implementation of this method follows the same implementation pattern as the initialize method of the HyperLink client control discussed in the previous chapter. First, it calls the callBaseMethod method to invoke the initialize method of its base class. Every time you implement a client component that overrides the initialize method, your component’s implementation must always call the callBaseMethod method to invoke the initialize method of its base class to allow the base class to initialize itself: Sys.Preview.UI.Button.callBaseMethod(this, ‘initialize’);
Next, the initialize method of the Button client control calls the createDelegate method on the Function class to create a delegate that represents the _onClick method of the Button control: this._clickHandler = Function.createDelegate(this, this._onClick);
Finally, it calls the addHandler static method on the DomEvent class to register this delegate as an event handler for the click event of the DOM element that the Button client control represents. This means that when the end user clicks the DOM element and raises its click event, it automatically invokes this delegate, which in turn invokes the method that it represents — the _onClick method.
327
c09.indd 327
8/21/07 1:02:55 AM
Chapter 9: Event Bubbling and Button Client Control
add_click Following the same implementation pattern as the HyperLink client control, the Button client control exposes two methods named add_click and remove_click that allow you to add a specified handler to and remove a specified handler from the list of handlers registered for the click event of the Button client control, as shown in Listing 9-7.
Listing 9-7: The add_click Method of the Button Client Control function Sys$Preview$UI$Button$add_click(handler) { this.get_events().addHandler(“click”, handler); } function Sys$Preview$UI$Button$remove_click(handler) { this.get_events().removeHandler(“click”, handler); }
_onClick One of the great things about the ASP.NET Button server control is that it bubbles its Command event up to its parent server controls. This plays a significant role in composite controls such as GridView and DetailsView. Thanks to event bubbling, these composite controls can catch the events raised by their child controls, such as a Button server control, and expose them as top-level events. This allows these composite controls to hide their child controls from their clients and consequently act as a single entity. The _onClick method of the Button client control emulates the same feature in client-side programming, as shown in Listing 9-8.
Listing 9-8: The _onClick Method of the Button Client Control function Sys$Preview$UI$Button$_onClick() { var handler = this.get_events().getHandler(“click”); if (handler) handler(this, Sys.EventArgs.Empty); if (this._command) { var e = new Sys.Preview.UI.CommandEventArgs(this._command, this._arg); this.raiseBubbleEvent(this, e); } }
This method first calls the get_events method to return a reference to the EventHandlerList that contains all the event handlers registered for the events that the Button client control exposes. The Button client control inherits the get_events method from its base class. Next, the _onClick method calls the getHandler method on the EventHandlerList to return a JavaScript function whose invocation automatically invokes all the event handlers registered for the click event of the Button control:
328
c09.indd 328
8/21/07 1:02:56 AM
Chapter 9: Event Bubbling and Button Client Control var handler = this.get_events().getHandler(“click”);
Next, the _onClick method calls this JavaScript function to invoke all the event handlers registered for the click event: handler(this, Sys.EventArgs.Empty);
So far, there was nothing special about the _onClick method. What makes the _onClick method of the Button client control very different from the _onClick method of client controls such as the HyperLink control is that the _onClick method creates an instance of the CommandEventArgs event data class (discussed in the previous section), passing in the values of the command and argument properties of the Button client control: var e = new Sys.Preview.UI.CommandEventArgs(this._command, this._arg);
Finally, the _onClick method calls the raiseBubbleEvent method, passing in the CommandEventArgs event data object to bubble the Button control’s command event up to its parent client control: this.raiseBubbleEvent(this, e);
Keep in mind that every client control inherits the raiseBubbleEvent method from the Control class. This method provides you with a very nice mechanism to bubble the events of your custom controls to their parent controls to allow the event handlers of the parent controls to handle these events. This enables the parent of a child control to catch the events raised by its child controls and expose them as its own events. This way, the clients of the parent control do not have to deal with the child controls. Instead, they register their event handlers for the events that the parent control exposes. You’ll see an example of this later.
dispose As you can see in Listing 9-9, the Button client control overrides the dispose method of its base class to remove all the event handlers registered for its click event. Note that the Button control’s implementation of this method calls the callBaseMethod method to invoke the dispose method of its base class to allow its base class to do its final cleanup before it is disposed of. Your custom client control’s implementation of the dispose method must always invoke the dispose method of its base class.
Listing 9-9: The dispose Method of the Button Client Control function Sys$Preview$UI$Button$dispose() { if (this._clickHandler) $removeHandler(this.get_element(), “click”, this._clickHandler); Sys.Preview.UI.Button.callBaseMethod(this, ‘dispose’); }
329
c09.indd 329
8/21/07 1:02:56 AM
Chapter 9: Event Bubbling and Button Client Control
descriptor The Button client control, like any ASP.NET AJAX client class, exposes a property named descriptor that describes the members of the Button control. The value of this property is always an object literal. As Listing 9-10 shows, this object contains two name/value pairs, where the first name/value pair describes the properties of the Button control, and the second name/value pair describes the events that the control exposes. The Button control exposes the command and argument properties and the click event.
Listing 9-10: The descriptor Property of the Button Client Control Sys.Preview.UI.Button.descriptor = { properties: [ { name: ‘command’, type: String }, { name: ‘argument’, type: String } ], events: [ { name: ‘click’ } ] }
Using Button Client Control This section uses a couple of examples to show you the significance of the Button client control’s event-bubbling capability. Event bubbling involves two important methods of the Control base class: onBubbleEvent and raiseBubbleEvent. It is the responsibility of a child client control to invoke the raiseBubbleEvent method to bubble its events to its parent client controls. It is the responsibility of the parent client control to override the onBubbleEvent method to catch and to optionally handle the event bubbled up by its child client control.
Catching a Bubbled Event The _onClick method of the Button client control calls the raiseBubbleEvent method to bubble its command event up to its parent client controls. The first example shows you a parent client control named GridView that overrides the onBubbleEvent method to catch the command event that its child Button client controls bubble up. Listing 9-11 presents the GridView.js JavaScript file that contains the implementation of the GridView client control.
Listing 9-11: The GridView.js JavaScript File Containing the GridView Client Control Implementation Type.registerNamespace(“CustomComponents”); CustomComponents.GridView = function CustomComponents$GridView(associatedElement) { CustomComponents.GridView.initializeBase(this, [associatedElement]); } function CustomComponents$GridView$onBubbleEvent(source, args) {
330
c09.indd 330
8/21/07 1:02:56 AM
Chapter 9: Event Bubbling and Button Client Control var handled = false; if (args instanceof Sys.Preview.UI.CommandEventArgs) { switch (args.get_commandName()) { case “Select”: alert(args.get_argument() + “ is selected!”); handled = true; break; case “Delete”: alert(args.get_argument() + “ is deleted!”); handled = true; break; } } return handled; } CustomComponents.GridView.prototype = { onBubbleEvent : CustomComponents$GridView$onBubbleEvent } CustomComponents.GridView.registerClass(“CustomComponents.GridView”, Sys.UI.Control); if(typeof(Sys)!==’undefined’) Sys.Application.notifyScriptLoaded();
As you can see, the GridView client control exposes a constructor and a method named onBubbleEvent that override the onBubbleEvent method of the Control base class.
Constructor Listing 9-12 shows the constructor of the GridView client control.
Listing 9-12: The Constructor of the GridView Client Control CustomComponents.GridView = function CustomComponents$GridView(associatedElement) { CustomComponents.GridView.initializeBase(this, [associatedElement]); } CustomComponents.GridView.registerClass(“CustomComponents.GridView”, Sys.UI.Control);
As with any other ASP.NET AJAX client control, this constructor takes an argument that references the DOM element that the control represents. It then calls the initializeBase method to invoke the constructor of its base class, passing in the reference to the DOM element. At the end of this listing, the GridView client control is registered as the subclass of the Control base class: CustomComponents.GridView.registerClass(“CustomComponents.GridView”, Sys.UI.Control);
331
c09.indd 331
8/21/07 1:02:57 AM
Chapter 9: Event Bubbling and Button Client Control onBubbleEvent The GridView client control overrides the onBubbleEvent method of its Control base class, as shown in Listing 9-13. Pay close attention to the implementation pattern used to implement the onBubbleEvent method, because the same pattern is used to implement the onBubbleEvent method of all parent client controls that need to catch the events raised by their child client controls.
Listing 9-13: The onBubbleEvent Method of the GridView Client Control function CustomComponents$GridView$onBubbleEvent(source, args) { var handled = false; if (args instanceof Sys.Preview.UI.CommandEventArgs) { switch (args.get_commandName()) { case “Select”: alert(args.get_argument() + “ is selected!”); handled = true; break; case “Delete”: alert(args.get_argument() + “ is deleted!”); handled = true; break; } } return handled; }
As shown in this listing, you take the following steps to implement the onBubbleEvent method of a parent client control:
1.
Declare a local variable named handled and initialize its value to false: var handled = false;
2.
Use the instanceof operator to determine whether the event is of the type that the parent client control handles. In this case, the GridView client control handles only command events: if (args instanceof Sys.Preview.UI.CommandEventArgs)
3.
Call the get_commandName method on the second parameter passed into the onBubbleEvent method to access the command name: var commandName = args.get_commandName();
4.
Use a switch statement that contains one branch for each command name that the parent client control handles. In this case the GridView client control handles only the Select and Delete commands.
5.
Handle the event within each branch and set the value of the handled variable to true. The logic that handles the event can call the get_argument method on the second parameter passed into the onBubbleEvent method to access the command argument. In this case, the
332
c09.indd 332
8/21/07 1:02:57 AM
Chapter 9: Event Bubbling and Button Client Control GridView client control’s handling of the Select and Delete events is pretty simple — the control simply calls the alert method to display a message that contains the value returned from the get_argument method.
6.
Return the value of the handled variable to the caller of the onBubbleEvent.
The caller of the onBubbleEvent method of a parent client control is the raiseBubbleEvent method of the child client control as shown in the following code snippet from Listing 8-17. The child client control calls the raiseBubbleEvent method to bubble its event up to its parent. function Sys$UI$Control$raiseBubbleEvent(source, args) { var currentTarget = this.get_parent(); while (currentTarget) { if (currentTarget.onBubbleEvent(source, args)) return; currentTarget = currentTarget.get_parent(); } }
The raiseBubbleEvent 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. In this case, the onBubbleEvent method of the GridView client control returns true after handling the Select and Delete events. Listing 9-14 contains a Web page that demonstrates the GridView and Button client controls’ eventbubbling capabilities. Figure 9-1 shows what you’ll see when you access this page.
Listing 9-14: A Page Showing the GridView and Button Client Controls’ Event-Bubbling Capabilities Untitled Page function pageLoad() { $create(CustomComponents.GridView, null, null, null, $get(“products”)); $create(Sys.Preview.UI.Button, { command: “Select”, argument: “Product1” }, null, { parent: “products”}, $get(“product1Selectbtn1”));
Chapter 9: Event Bubbling and Button Client Control
Figure 9-1
This page renders a table with the id HTML attribute value of “products” that contains two table rows. Each table row contains two table cells, and each table cell contains a HTML element. Therefore, altogether you’re looking at four HTML elements with id HTML attribute values of product1Selectbtn1, product1Deletebtn1, product2Selectbtn1, and product2Deletebtn1. Notice that each HTML element displays either the Select or the Delete text. As you can see, we’ve basically hard-coded a table of rows where each row displays one product and two buttons. One button allows you to select the row and the other button allows you to delete the row. To keep this discussion focused, the onBubbleEvent method of the GridView client control does not contain the logic that actually selects or deletes a row. Instead, this method simply calls the alert method to inform the user that a specified product is selected or deleted (see Listing 9-13).
Product Name
Unit Price
Product1
$100
Select
Delete
Product2
$200
Select
Delete
335
c09.indd 335
8/21/07 1:02:58 AM
Chapter 9: Event Bubbling and Button Client Control Now, lets walk though the implementation of the pageLoad method shown in Listing 9-14. This method first instantiates an instance of the GridView client control to represent the table DOM element with id HTML attribute value of “products”: $create(Sys.Preview.UI.GridView, null, null, null, $get(“products”));
Then, the method instantiates a Button client control to represent the button DOM element with the id HTML attribute value of product1Selectbtn1. This button DOM element allows the user to select the first row: $create(Sys.Preview.UI.Button, { command: “Select”, argument: “Product1” }, null, { parent: “products”}, $get(“product1Selectbtn1”));
The following object literal is passed as the third argument into the create static method: { parent: “products”}
The third argument of the create method specifies the values of the properties of the component that reference other components in the current application. As discussed in Chapter 8, the Control base class exposes a property name parent that references the parent client control of the current control. In this case, the {parent: “products”} object literal is passed as the third parameter of the create method that creates the product1Selectbtn1 client control to tell the create method that the client control with an id property value of “products” is the parent control of the product1Selectbtn1 client control. The create method internally locates this parent control in the _components collection of the current Application object and assigns it to the parent property of the product1Selectbtn1 client control. The pageLoad method passes the {command: “Select”, argument: “Product1”} object literal as the second parameter of the create method that creates the product1Selectbtn1 client control. As you can see, this object literal specifies the string “Product1” as the value of the argument property of this client control. As you saw previously in Listing 9-13, this allows the onBubbleEvent method of the GridView client control to use the get_argument method to access the argument value and consequently the name of the product being selected: The pageLoad method follows similar steps to instantiate and initialize the Button client controls that represent the HTML elements with id HTML attribute values of product1Deletebtn1, product2Selectbtn1, and product2Deletebtn1. Finally, this page registers the PreviewScript.js and GridView.js JavaScript files with the ScriptManager:
336
c09.indd 336
8/21/07 1:03:01 AM
Chapter 9: Event Bubbling and Button Client Control Run the page and click the Delete button that deletes the second row. This should pop up the message shown in Figure 9-2. This message contains the name of the product being deleted.
Figure 9-2
Bubbling an Event The next example shows you how to use the raiseBubbleEvent method in your own custom client control to bubble the events that your control exposes. This example involves three ASP.NET AJAX classes: a new version of the GridView client control, a new client control named GridViewRow, and a new event data class named GridViewCommandEventArgs.
GridViewRow Listing 9-15 presents a JavaScript file named GridViewRow.js. This file contains the implementation of a new client control named GridViewRow that represents a table row in the GridView client control.
Listing 9-15: The GridViewRow.js JavaScript file Containing the GridViewRow Client Control Implementation Type.registerNamespace(“CustomComponents”); CustomComponents.GridViewRow = function CustomComponents$GridViewRow(associatedElement) { CustomComponents.GridViewRow.initializeBase(this, [associatedElement]); }
(continued)
337
c09.indd 337
8/21/07 1:03:01 AM
Chapter 9: Event Bubbling and Button Client Control Listing 9-15 (continued) function CustomComponents$GridViewRow$set_rowIndex(value) { if (this._rowIndexSet) throw Error.invalidOperation(“rowIndex property cannot be set twice!”); this._rowIndexSet = true; this._rowIndex = value; } function CustomComponents$GridViewRow$get_rowIndex() { return this._rowIndex; } function CustomComponents$GridViewRow$onBubbleEvent(source, args) { var handled = false; if (args instanceof Sys.Preview.UI.CommandEventArgs) { var args2=new CustomComponents.GridViewCommandEventArgs(this, source, args); this.raiseBubbleEvent(this, args2); handled = true; } return handled; } CustomComponents.GridViewRow.prototype = { get_rowIndex : CustomComponents$GridViewRow$get_rowIndex, set_rowIndex : CustomComponents$GridViewRow$set_rowIndex, onBubbleEvent : CustomComponents$GridViewRow$onBubbleEvent } CustomComponents.GridViewRow.descriptor = { properties : [{name : ‘rowIndex’, type : Number}] }; CustomComponents.GridViewRow.registerClass( “CustomComponents.GridViewRow”, Sys.UI.Control); if(typeof(Sys)!==’undefined’) Sys.Application.notifyScriptLoaded();
The following sections discuss the implementation of the members of the GridViewRow client control.
338
c09.indd 338
8/21/07 1:03:01 AM
Chapter 9: Event Bubbling and Button Client Control Constructor Listing 9-16 shows the constructor of the GridViewRow client control. This constructor takes an argument that references the table row DOM element the control represents. At the end of the listing, the GridViewRow class is registered as the subclass of the Control base class.
Listing 9-16: The Constructor of the GridViewRow Client Control CustomComponents.GridViewRow = function CustomComponents$GridViewRow(associatedElement) { CustomComponents.GridViewRow.initializeBase(this, [associatedElement]); } CustomComponents.GridViewRow.registerClass(“CustomComponents.GridViewRow”, Sys.UI.Control);
rowIndex The GridViewRow client control exposes a property of type integer named rowIndex that specifies the index of the table row DOM element that the control represents. The get_rowIndex method of the control, shown in Listing 9-17, returns the value of the rowIndex property. As you’ll see later, you use the set_rowIndex method to set the value of this property when you create the GridViewRow client control. This property value can be set only once, which ensures that the value cannot be overridden.
Listing 9-17: The get_rowIndex and set_rowIndex Methods of the GridViewRow Client Control function CustomComponents$GridViewRow$set_rowIndex(value) { if (this._rowIndexSet) throw Error.invalidOperation(“rowIndex property cannot be set twice!”); this._rowIndexSet = true; this._rowIndex = value; } function CustomComponents$GridViewRow$get_rowIndex() { return this._rowIndex; }
onBubbleEvent As you can see in Listing 9-18, the GridViewRow client control overrides the onBubbleEvent method of its base class to catch the events that its child client controls fire. In this case, the table row DOM element that the GridViewRow client control represents contains two Button client controls that allow the end user to select and delete the table row. Therefore, the onBubbleEvent method of the GridViewRow control catches the command events that these Button client controls raise. As such, the first parameter of the onBubbleEvent method references the Button client control that raised the command event, and the second parameter of the method references the CommandEventArgs event data object that the _onClick
339
c09.indd 339
8/21/07 1:03:02 AM
Chapter 9: Event Bubbling and Button Client Control method of the Button client control passed into the raiseBubbleEvent method (shown previously in Listing 9-8).
Listing 9-18: The onBubbleEvent Method of the GridViewRow Client Control function CustomComponents$GridViewRow$onBubbleEvent(source, args) { var handled = false; if (args instanceof Sys.Preview.UI.CommandEventArgs) { var args2=new CustomComponents.GridViewCommandEventArgs(this,source, args); this.raiseBubbleEvent(this, args2); handled = true; } return handled; }
This method first checks whether the event that it just caught is a command event. The easiest way to do this is to check whether the event data object passed into the onBubbleEvent method as its second argument is of type CommandEventArgs: if (args instanceof Sys.Preview.UI.CommandEventArgs)
As previously shown in Listing 9-8, only command events use this type as their event data class. Next, the onBubbleEvent method creates an instance of the GridViewCommandEventArgs class. As you’ll see in the next section, this class is the event data class associated with an event named GridViewCommand. The constructor of this event data class takes three arguments. The first argument references the GridViewRow client control; the second argument references the Button client control that raised the Command event; and the third argument references the CommandEventArgs object passed into the onBubbleEvent: var args2=new CustomComponents.GridViewCommandEventArgs(this, source, args);
Next, the onBubbleEvent method calls the raiseBubbleEvent method, passing in two parameters. The first parameter references the GridViewRow client control; and the second parameter references the GridViewCommandEventArgs object: this.raiseBubbleEvent(this, args2);
Therefore, the onBubbleEvent method catches the command event that its Button child controls raise and raises a GridViewCommand event instead. In this case, it returns true to stop its Button child control’s command event from bubbling to the parent of the GridViewRow control, which is the GridView client control. In other words, the GridView client control never gets to handle the original command event raised by the Button child control. Instead, it receives and handles the GridViewCommand event that the GridViewRow client control raises.
340
c09.indd 340
8/21/07 1:03:02 AM
Chapter 9: Event Bubbling and Button Client Control descriptor The GridViewRow client control, like any other ASP.NET AJAX class, implements a property named descriptor. You must always define the descriptor property of your ASP.NET AJAX class on the class itself, not on the prototype property of your class. In other words, the descriptor property must be a static property. This is because the descriptor property describes the members of the class using metadata that is shared by all instances of the class. Listing 9-19 assigns an object literal to the descriptor property. In this case, the object contains a single name/value pair that describes the properties of the GridViewRow client control. Because this control contains a single property named rowIndex, the value portion of this name/value pair is an array that contains a single object literal. This object consists of three name/value pairs. The first name/value pair specifies the name of the property: rowIndex. The second name/value pair specifies the type of the property: Number.
Listing 9-19: The descriptor Property of the GridViewRow Client Control CustomComponents.GridViewRow.descriptor = { properties : [{name : ‘rowIndex’, type : Number}] };
GridViewCommandEventArgs As discussed in the previous section, the GridViewRow client control raises an event named GridViewCommand that uses a new event data class named GridViewCommandEventArgs. Listing 9-20 presents a JavaScript file named GridViewCommandEventArgs.js that contains the implementation of the GridViewCommandEventArgs class.
Listing 9-20: The GridViewCommandEventArgs.js File Containing GridViewCommandEventArgs Event Data Class Implementation Type.registerNamespace(“CustomComponents”); CustomComponents.GridViewCommandEventArgs = function CustomComponents$GridViewCommandEventArgs (row, source, args) { CustomComponents.GridViewCommandEventArgs.initializeBase(this, [args.get_commandName(), args.get_argument()]); this._commandSource = source; this._row = row; } function CustomComponents$GridViewCommandEventArgs$get_commandSource() { return this._commandSource; }
The following sections walk you through the implementation of the GridViewCommandEventArgs event data class.
Constructor Listing 9-21 shows the constructor of the GridViewCommandEventArgs event data class. This constructor takes three parameters. The first parameter references the GridViewRow client control that bubbles the event up to the GridView control (shown previously in Listing 9-18). The second parameter references the Button child client control that raised the original command event (shown previously in Listing 9-8). The third parameter references the CommandEventArgs event data object that the Button child client’s _onClick method instantiated (shown previously in Listing 9-8).
Listing 9-21: The Constructor of the GridViewCommandEventArgs Event Data Class CustomComponents.GridViewCommandEventArgs = function CustomComponents$GridViewCommandEventArgs (row, source, args) { CustomComponents.GridViewCommandEventArgs.initializeBase(this, [args.get_commandName(), args.get_argument()]); this._commandSource = source; this._row = row; } CustomComponents.GridViewCommandEventArgs.registerClass( “CustomComponents.GridViewCommandEventArgs”, Sys.Preview.UI.CommandEventArgs);
342
c09.indd 342
8/21/07 1:03:03 AM
Chapter 9: Event Bubbling and Button Client Control The constructor first calls the initializeBase method to invoke the constructor of its CommandEventArgs base class. An array of two items is passed to the constructor of the CommandEventArgs class. These items contain the command name and argument, respectively. The GridViewCommandEventArgs constructor stores the references to the GridViewRow and Button client controls in internal fields named _commandSource and _row. Listing 9-21 registers the GridViewCommandEventArgs class as the subclass of the CommandEventArgs class: CustomComponents.GridViewCommandEventArgs.registerClass( “CustomComponents.GridViewCommandEventArgs”, Sys.Preview.UI.CommandEventArgs);
get_commandSource As you can see in Listing 9-22, the get_commandSource method returns a reference to the Button child control that raised the original command event.
Listing 9-22: The get_commandSource Method of the GridViewCommandEventArgs Class function CustomComponents$GridViewCommandEventArgs$get_commandSource() { return this._commandSource; }
get_row As you can see in Listing 9-23, the get_row method returns a reference to the GridViewRow client control that raised the GridViewCommand event.
Listing 9-23: The get_row Method of the GridViewCommandEventArgs Class function CustomComponents$GridViewCommandEventArgs$get_row() { return this._row; }
descriptor The GridViewCommandEventArgs class defines a property named descriptor that returns an object literal describing the members of the class, as shown in Listing 9-24. In this case, the object contains a single name/value pair that describes the properties of the class. The value part of the name/value pair contains an array of two object literals that describe the commandSource and row properties of the class. Each object literal contains three name/value pairs. The first two pairs describe the name and type of the property. The last pair specifies that the property is read-only.
343
c09.indd 343
8/21/07 1:03:03 AM
Chapter 9: Event Bubbling and Button Client Control Listing 9-24: The descriptor Property of the GridViewCommandEventArgs Class CustomComponents.GridViewCommandEventArgs.descriptor = { properties: [{name:’commandSource’, type:Sys.Preview.UI.Control, readOnly:true}, {name : ‘row’, type : CustomComponents.GridViewRow, readOnly: true}] }
GridView Listing 9-25 presents a new version of the GridView.js JavaScript file that contains the implementation of a new version of the GridView client control.
Listing 9-25: The Content of a New Version of the GridView.js File that Contains the Implementation of a New Version of the GridView Client Control Type.registerNamespace(“CustomComponents”); CustomComponents.GridView = function Sys$Preview$UI$GridView(associatedElement) { CustomComponents.GridView.initializeBase(this, [associatedElement]); } function CustomComponents$GridView$onBubbleEvent(source, args) { var handled = false; if (args instanceof CustomComponents.GridViewCommandEventArgs) { switch (args.get_commandName()) { case “Select”: alert(args.get_argument() + “ from row number “ + args.get_row().get_rowIndex() + “ is selected!”); handled = true; break; case “Delete”: alert(args.get_argument() + “ from row number “ + args.get_row().get_rowIndex() + “ is deleted!”); handled = true; break; } } return handled; } CustomComponents.GridView.prototype = { onBubbleEvent : CustomComponents$GridView$onBubbleEvent }
344
c09.indd 344
8/21/07 1:03:03 AM
Chapter 9: Event Bubbling and Button Client Control CustomComponents.GridView.registerClass(“CustomComponents.GridView”, Sys.UI.Control); if(typeof(Sys)!==’undefined’) Sys.Application.notifyScriptLoaded();
This GridView client control overrides the onBubbleEvent method of its base class to catch the events that its GridViewRow child client controls raise. As previously shown in Listing 9-18, the GridViewRow client control raises and bubbles up the GridViewCommand event. Because the GridView client control handles only GridViewCommand events, onBubbleEvent first checks whether the event just caught is of type GridViewCommand. The standard way to do this is to check the type of the second parameter passed into the onBubbleEvent. This parameter references an event data object. As you can see from the following code snippet, if this parameter is of type GridViewCommandEventArgs, you can rest assured that the event just caught is of type GridViewCommand because only this type of event uses the GridViewCommandEventArgs class as its event data class. if (args instanceof CustomComponents.GridViewCommandEventArgs)
Next, the onBubbleEvent method does what the earlier version of the GridView client control did. The main difference here is that the messages that the alert methods pop up now contain the index of the table row that raised the GridViewCommand event (see Figure 9-3).
Figure 9-3
345
c09.indd 345
8/21/07 1:03:04 AM
Chapter 9: Event Bubbling and Button Client Control Listing 9-26 shows a page that uses the new version of the GridView client control.
Chapter 9: Event Bubbling and Button Client Control
Product Name
Unit Price
Product1
$100
Select
Delete
Product2
$200
Select
Delete
Let’s walk through the implementation of the pageLoad method shown in the listing. This method first instantiates an instance of the GridView client control to represent the table with an id HTML attribute value of products: $create(CustomComponents.GridView, null, null, null, $get(“products”));
Then, the method instantiates an instance of the GridViewRow client control to represent the first row of the table: $create(CustomComponents.GridViewRow, {rowIndex: 1}, null, {parent: “products”}, $get(“row1”));
As this code fragment shows, the pageLoad method passes the {parent: “products”} object literal as the third argument into the create method to specify the GridView client control with id property value of “products” as the parent of the GridViewRow client control being instantiated. As you saw previously in Listing 9-18, the GridViewRow client control’s onBubbleEvent method calls the raiseBubbleEvent method to bubble the GridViewCommand event to its parent client control. Therefore, you must specify the GridView client control as the parent control of the GridViewRow control if you want the onBubbleEvent method of the GridView client control to catch the GridViewCommand event. Also note that the pageLoad method passes the {rowIndex: 1} object literal as the second argument into the create method to initialize the rowIndex property of the GridViewRow client control being instantiated to 1.
347
c09.indd 347
8/21/07 1:03:05 AM
Chapter 9: Event Bubbling and Button Client Control Then, the pageLoad method takes the same steps that the pageLoad method previously shown in Listing 9-14 took. The main difference is that Listing 9-26 specifies the GridViewRow client control as the parent control of the Button client controls as opposed to the GridView control itself, as shown in the boldfaced portions of the following code: $create(Sys.Preview.UI.Button, { command: “Select”, argument: “Product1” }, null, { parent: “row1”}, $get(“product1Selectbtn1”)); $create(Sys.Preview.UI.Button, { command: “Delete”, argument: “Product1” }, null, { parent: “row1”}, $get(“product1Deletebtn1”));
The pageLoad method then repeats the previous steps to create the second GridViewRow client control and its two Button child client controls. At the end of Listing 9-26, two new JavaScript files named GridViewCommandEventArgs.js and GridViewRow.js are registered with the ScriptManager:
The GridViewCommandEventArgs.js file contains the code that defines and registers the GridViewCommandEventArgs class (shown previously in Listing 9-20). The GridViewRow.js file contains the code that defines and registers the GridViewRow client control (shown previously in Listing 9-25).
Summar y This chapter showed you how to implement client controls that bubble their events up to their parent client controls and how to implement client controls that catch the events that their child controls bubble up. The next chapter moves on to another important topic in the ASP.NET AJAX client-side framework: the type description extensions.
348
c09.indd 348
8/21/07 1:03:05 AM
Type Description Extensions The ASP.NET Framework provides you with two ways to inspect the metadata associated with a given type: reflection and TypeDescriptor. Metadata inspection plays a central role in the ASP.NET Framework. For example, metadata inspection is an integral part of the ASP.NET server controls such as GridView, where data records come from many different data sources. It is a well-known fact that different types of data stores expose different types of data records. For example, data records stored into or retrieved from a relational database via the ADO.NET layer normally are of type DataRow or DataRowView. Data records stored into or retrieved from an XML document via the .NET XML layer are of type XmlNode. If an ASP.NET server control such as GridView were to know about the actual type of the data records being retrieved or stored, it would be tied to a particular type of data record, and, consequently, a particular type of data store. For example, if an ASP.NET server control were to directly interact with the DataRow or DataRowView objects returned from the ADO.NET layer, it would not be able to interact with XmlNode objects returned from the .NET XML layer. In other words, the server control would only be able to retrieve data from and store data into a relational database via the ADO.NET layer and would not be able to retrieve data from and store data into an XML document via the .NET XML layer. The metadata inspection capabilities of the .NET Framework allows a server control such as GridView to interact with the data records in generic fashion without knowing their actual types. This allows the same server control to retrieve and store any type of data records. The ASP.NET AJAX client-side framework introduces two metadata inspection facilities that emulate their .NET counterparts, reflection and TypeDescriptor. Previous chapters covered the reflection capabilities of the ASP.NET AJAX client-side framework. This chapter discusses the ASP.NET AJAX type description capabilities, which emulate the .NET type description capabilities. As you’ll see later, the ASP.NET AJAX type descriptions provide the client controls with the same capabilities as their server counterparts. These capabilities enable the client controls to deal with data records in a generic fashion without having to know their actual types. The ASP.NET AJAX type description infrastructure consists of the following main components:
c10.indd 349
❑
TypeDescriptor
❑
ICustomTypeDescriptor
8/20/07 6:08:12 PM
Chapter 10: Type Description Extensions
TypeDescriptor The ASP.NET AJAX client-side framework includes a client class named TypeDescriptor that emulates the ASP.NET server-side TypeDescriptor class. The following sections discuss the members of this client class.
Constructor Listing 10-1 presents the implementation of the TypeDescriptor client class’s constructor. As the name suggests, a TypeDescriptor object describes a type. A type exposes up to three different kinds of members: properties, methods, and events. Every type can also be annotated with zero or more metadata attributes that provide more information about the type. A type also inherits the properties, methods, events, and attributes of its base types. Therefore, a complete description of a type must include the type’s and its ancestor type’s properties, methods, events, and attributes. That is why the TypeDescriptor client class in Listing 10-1 exposes four properties named properties, methods, events, and attributes. As the listing shows, the TypeDescriptor class also exposes four getter methods named _get _ properties, _get_methods, _get_events, and _get_attributes that provide access to these four properties. The following sections discuss these properties.
Listing 10-1: The Constructor of the TypeDescriptor Client Class Sys.Preview.TypeDescriptor = function Sys$Preview$TypeDescriptor() { var _properties = { }; var _events = { }; var _methods = { }; var _attributes = { }; this._getAttributes = function this$_getAttributes() { return _attributes; } this._getEvents = function this$_getEvents() { return _events; } this._getMethods = function this$_getMethods() { return _methods; } this._getProperties = function this$_getProperties() { return _properties; } } Sys.Preview.TypeDescriptor.registerClass(‘Sys.Preview.TypeDescriptor’);
350
c10.indd 350
8/20/07 6:08:12 PM
Chapter 10: Type Description Extensions _properties This property references a JavaScript object literal that contains one name/value pair for each property of the type (or its base type) that the TypeDescriptor object describes. The name part of each name/ value contains the name of the property associated with the pair. The value part of each name/value pair is a JavaScript object literal that describes the property associated with the pair. This JavaScript object literal contains up to five name/value pairs, where each pair provides a piece of metadata information about the property that the object literal describes, as follows:
❑
The first name/value pair specifies the name of the property. The name part of this name/value pair is name, and the value part is a string that contains the name of the property.
❑
The second name/value pair describes the type of the property. The name part of this name/ value pair is type, and the value part references the constructor of the property type.
❑
The third name/value pair specifies whether the property is read-only. The name part of this name/value pair is readOnly, and the value part is a Boolean value.
❑
The fourth name/value pair describes the metadata attributes that annotate the type of the property. The name part of this name/value pair is attributes, and the value part is an object that contains the attributes.
❑
The fifth name/value pair specifies whether the property references a DOM element. The name part of this name/value pair is isDomElement, and the value part is a Boolean value.
For example, the Component base class exposes the properties shown in the following table.
Property Name
Property Type
Read Only
dataContext
Object
False
id
String
False
isInitialized
Boolean
True
isUpdating
Boolean
True
Based on this table, the _properties property of the TypeDescriptor object that describes the Component base class references the JavaScript object literal shown in Listing 10-2.
Listing 10-2: The JavaScript Object Literal Referenced by the _properties of the TypeDescriptor Object that Describes the Component Base Class { ‘dataContext’: {name: ‘dataContext’, type: Object, readOnly: false}, ‘id’: {name: ‘id’, type: String, readOnly: false}, ‘isInitialized’: {name: ‘isInitialized’, type: Boolean, readOnly: true}, ‘isUpdating’: {name: ‘isUpdating’, type: Boolean, readOnly: true} }
This object literal contains five name/value pairs. The name part of each of these name/value pairs contains the name of a property — dataContext, id, isInitialized, and isUpdating. The value part of each of these name/value pairs contains the JavaScript object literal that describes the corresponding
351
c10.indd 351
8/20/07 6:08:13 PM
Chapter 10: Type Description Extensions property of the Component base class:
Now, let’s take a look at the content of the TypeDescriptor object’s _ properties property. Because the Control class derives from the Component base class, it inherits all the properties of its base class. The following table presents all the properties of the Control base class, including those that it inherits from its base class.
Property Name
Property Type
Read Only
dataContext
Object
false
Id
String
false
isInitialized
Boolean
true
isUpdating
Boolean
true
Element
Object
true
Role
String
true
Parent
Object
false
Visible
Boolean
false
visibilityMode
Sys.UI.VisibilityMode
false
Based on this table, the _properties property of the TypeDescriptor object that describes the Control base class references the JavaScript object literal shown in Listing 10-3.
Listing 10-3: The JavaScript Object Literal Referenced by the _properties of the TypeDescriptor Object that Describes the Control Base Class { ‘dataContext’: {name: ‘dataContext’, type: Object, readOnly: false}, ‘id’: {name: ‘id’, type: String, readOnly: false}, ‘isInitialized’: {name: ‘isInitialized’, type: Boolean, readOnly: true}, ‘isUpdating’: {name: ‘isUpdating’, type: Boolean, readOnly: true}, ‘element’: {name: ‘element’, type: Object, readOnly: true}, ‘role’: {name: ‘role’, type: String, readOnly: true}, ‘parent’: {name: ‘parent’, type: Object, readOnly: false}, ‘visible’: {name: ‘visible’, type: Boolean}, ‘visibilityMode’: {name:’visibilityMode’, type: Sys.UI.VisibilityMode, readOnly:false} }
Listing 10-4 shows a page that enables you to display the _properties property of the TypeDescriptor object associated with any ASP.NET AJAX client class, including your own custom classes.
352
c10.indd 352
8/20/07 6:08:13 PM
Chapter 10: Type Description Extensions Listing 10-4: A Page that Displays the _properties of the TypeDescriptor Object Associated with an ASP.NET AJAX Client Class Untitled Page .properties { background-color: LightGoldenrodYellow; color: black; border-collapse: collapse; } .properties td, .properties th { border: 1px solid Tan; padding: 5px; } .header { background-color: Tan; } .odd { background-color: PaleGoldenrod; } function displayProperties(instance) { var td = Sys.Preview.TypeDescriptor.getTypeDescriptor(instance); var properties = td._getProperties(); var columns = [“Property Name”, “Property Type”, “ReadOnly”, “Property Attributes (Name/Value)”]; var table = document.createElement(“table”); Sys.UI.DomElement.addCssClass(table, “properties”); var headerRow = table.insertRow(0); Sys.UI.DomElement.addCssClass(headerRow, “header”); var headerCell = null; for (var i=0, length = columns.length; i= 0; c--) { var column = this._columns[c]; if (column.get_columnName() === name) {
raiseRowChanged The setProperty method of a DataRow object calls the raiseRowChanged method on the DataTable object that owns the DataRow object, passing in the updated row object (as previously shown in Listing 11-7). Listing 11-30 shows the raiseRowChanged method. This method adds the updated row object to the _updatedRows array of the DataTable object and calls the _onPropertyChanged method to raise the propertyChanged event for the isDirty property.
Listing 11-30: The raiseRowChanged Method function Sys$Preview$Data$DataTable$raiseRowChanged(changedItem) { if ((Array.indexOf(this._updatedRows, changedItem) === -1) && (Array.indexOf(this._newRows, changedItem) === -1)) { var oldIsDirty = this.get_isDirty(); Array.add(this._updatedRows, changedItem); if (!oldIsDirty) this._onPropertyChanged(“isDirty”); } }
parseFromJson The DataTable class exposes a static method named parseFromJson that creates a DataTable object from a JavaScript object, which is normally an object literal. This object must contain the following two name/value pairs:
❑
The first name/value pair must describe the columns of the data table. The name part of the pair must be the keyword columns, and the value part must be an array of object literals where each object literal describes a column. In turn, each object literal must expose the following five name/value pairs:
❑
The first name/value pair must describe the column name. The name part must be name, and the value part must be a string that contains the column name.
❑
The second name/value pair must describe the data type of the column. The name part must be dataType, and the value part must reference the actual data type.
❑
The third name/value pair must describe the default value. The name part must be defaultValue, and the value part must reference the actual default value.
443
c11.indd 443
8/20/07 8:14:25 PM
Chapter 11: Data Classes ❑
The fourth name/value pair must describe whether the column is a primary key column. The name part of the pair must be isKey, and the value part must be a Boolean value.
❑
The fifth name/value pair must describe whether the column is editable. The name part must be readOnly, and the value part must be a Boolean value.
For example, the following three object literals describe the ProductId, ProductName, and UnitPrice columns of the Products data table: {name: ‘ProductId’, dataType: Number, defaultValue: 1, isKey: true, readOnly: true} {name: ‘ProductName’, dataType: String, defaultValue: ‘Unknown’, isKey: false, readOnly: true} {name: ‘UnitPrice’, dataType: Number, defaultValue: 50, isKey: false, readOnly: false}
Note that the value part of the fourth name/value pair of the object literal that describes the ProductId column has been set to true to signal that this column is a primary key column. If the primary key of a data table consists of multiple columns, you must set the value of the fourth name/value pair of all the object literals that describe the constituent columns of the primary key to true.
❑
The second name/value pair must describe the data rows of the data table. The name part of the pair must be rows, and the value part must be an array of object literals where each object literal describes a data row. In turn, each object literal must contain one name/value pair for each data field of the data row. The name part of each pair must be a string that contains the name of the data field, and the value part must reference the actual value of the data field. For example, the following three object literals describe three data rows of the Products data table:
This object literal describes the Products data table with three columns named ProductId, ProductName, and UnitPrice and three data rows, as shown in the following table. Listing 11-31 shows the parseFromJson method.
Listing 11-31: The parseFromJson Method Sys.Preview.Data.DataTable.parseFromJson = function Sys$Preview$Data$DataTable$parseFromJson(json) { var columnArray = null; if(json.columns) { columnArray = []; for(var i=0; i < json.columns.length; i++) Array.add(columnArray, Sys.Preview.Data.DataColumn.parseFromJson(json.columns[i])); } return new Sys.Preview.Data.DataTable(columnArray, json.rows); }
As discussed earlier, the object literal passed into the parseFromJson method contains two name/value pairs whose name parts are columns and rows. The method uses columns to access its associated value part, which is an array of object literals where each object literal describes a column of the data table. The method iterates through these object literals and passes each enumerated object literal into the parseFromJson static method of the DataColumn class: for(var i=0; i < json.columns.length; i++) Array.add(columnArray, Sys.Preview.Data.DataColumn.parseFromJson(json.columns[i]));
The parseFromJson static method of the DataColumn class creates a DataColumn object from the specified object literal representation. Note that Listing 11-31 stores all these DataColumn objects into a local array. The parseFromJson method of the DataTable class then uses the rows on the object literal to access its associated value part, which is an array of object literals where each object literal describes a data row. The method then passes this array and the local array that contains the DataColumn objects into the DataTable constructor to instantiate the DataTable object.
445
c11.indd 445
8/20/07 8:14:26 PM
Chapter 11: Data Classes
Using DataColumn, DataRow, and DataTable This section provides an example of how you can use the DataColumn, DataRow, and DataTable client classes in your own client-side code. In Chapter 10, we implemented a custom client control named CustomTable that uses the ASP.NET AJAX type inspection capabilities to display data records of any type. This custom client control exposes a method named dataBind that iterates through the data records to display them, as shown in Listing 11-32.
Listing 11-32: The dataBind Method of the CustomTable Client Control function CustomComponents$CustomTable$dataBind() { var sb = new Sys.StringBuilder(‘
’); var propertyNames = []; for (var i=0; i . . . --> . . .
Now if you run the PageMethods.aspx, Math.aspx, and Math2.aspx pages, you should be able to see the same results you saw when you ran these pages with the standard ASP.NET ScriptHandlerFactory and ScriptModule. Feel free to play with the code to get a better understanding of the processing infrastructure of the ASP.NET AJAX REST method call request.
Summar y This chapter provided you with in-depth coverage of the ASP.NET AJAX REST method call request’s processing infrastructure. It introduced Web services bridges, which are covered in more detail in Chapter 19, where you’ll learn how to develop a custom script server control that uses a bridge to enable the client code to interact with Amazon Web services. The next chapter builds on what you learned in this chapter to show you how this infrastructure manages to hide its complexity behind proxy classes.
595
c14.indd 595
8/20/07 6:14:05 PM
c14.indd 596
8/20/07 6:14:05 PM
Proxy Classes The previous chapter provided you with in-depth coverage of the ASP.NET AJAX REST method call request processing infrastructure. This chapter shows you how this infrastructure hides its complexity behind proxy classes to enable you to program against a remote object as you would against a local object.
What’s a Proxy, Anyway? Let’s revisit the add JavaScript function shown in Listing 14-14 of Chapter 14, and shown again here in Listing 15-1. This JavaScript function was registered as the event handler for the Add button’s click event of in Listing 14-14.
Listing 15-1: The add Method function add() { var servicePath = “ http://localhost/AJAXEnabledFuturesWebSite2/Math.asmx”; var methodName = “Add”; var useGet = false; var xValue = $get(“firstNumber”).value; var yValue = $get(“secondNumber”).value; var params = {x : xValue, y : yValue}; var userContext = $get(“result”); var webServiceProxy = new Sys.Net.WebServiceProxy(); webServiceProxy.set_timeout(0); request = webServiceProxy._invoke(servicePath, methodName, useGet, params, onSuccess, onFailure, userContext); }
Now here is a question for you: How would you code this add method if the Math class (see Listing 14-15) were a local class in your client-side code, such as the local class shown in Listing 15-2?
c15.indd 597
8/20/07 9:08:00 PM
Chapter 15: Proxy Classes Listing 15-2: A Local Class with the Same Name and Methods as the Remote Web Service Type.registerNamespace(“MyNamespace”); MyNamespace.Math = function () { } MyNamespace.Math.prototype = { Add : function (x, y) { return x + y; } } MyNamespace.Math.registerClass(“MyNamespace.Math”);
Wouldn’t your implementation of the add method be something like the one shown in Listing 15-3?
Listing 15-3: Implementation of add Method if the Web Service Class Were a Local Class function add() { var math = new MyNamespace.Math(); var xValue = $get(“firstNumber”).value; var yValue = $get(“secondNumber”).value; var z = math.Add(Number.parseInvariant(xValue), Number.parseInvariant(yValue)); $get(“result”).innerText = z; }
As you can see in this listing, if the Math object were a local object, you would directly invoke the Add method on the object and directly pass the x and y values into the Add method itself. However, when the Math object becomes a Web service, it is a remote object, so you cannot directly invoke the Add method on it, nor can you directly pass the x and y values into it. When you’re calling the Add method on the remote Math object:
❑
You have to worry about the service path where the remote Math object is located: var servicePath = “http://localhost/AJAXEnabledFuturesWebSite2/Math.asmx”;
You don’t have to worry about the location of a local Math object, because it always resides in the same address space as the rest of your program and, consequently, you have direct access to the object.
❑
You have to pass the name of the method as a string into the _invoke method of the WebServiceProxy object:
Chapter 15: Proxy Classes This is obviously very different from a local method invocation where you directly invoke the method on the object instead of passing a string around.
❑
You have to pass the names and values of the parameters of the method as a dictionary into the _invoke method of the WebServiceProxy object.
var params = {x : xValue, y : yValue}; request = webServiceProxy._invoke(servicePath, methodName, useGet, params, onSuccess, onFailure, userContext);
This is obviously very different from a local method invocation where you directly pass these parameters into the method itself instead of passing a dictionary around.
❑
You’re trying to call a method named Add, which takes two parameters of type double and returns a value of type double, on an object of type Math, but you have to call a method with a different name (_invoke), with completely different parameters (servicePath, methodName, useGet, params, onSucess, onFailure, and userContext), and with a completely different return type (WebRequest), on a completely different object (the WebServiceProxy object): request = webServiceProxy._invoke(servicePath, methodName, useGet, params, onSuccess, onFailure, userContext);
This is obviously very different from a local method invocation where you directly invoke the Add method on the Math object. As you can see, invoking the Add method on the remote Math object doesn’t look anything like invoking the Add method on a local Math object.
Proxy Class The ASP.NET AJAX framework provides you with a local object that has the following characteristics:
❑
It has the same name as the remote object. For example, in the case of the Math Web service, the AJAX framework provides you with a local object named Math.
❑
It exposes methods with the same names as the methods of the remote object. For example, the local Math object associated with the remote Math Web service object exposes a method named Add.
❑
Its methods take parameters with the same names as the associated methods of the remote object. For example, the Add method of the local Math object associated with the remote Math Web service object also takes two parameters with the same names as the parameters of the Add method of the remote Math Web service object: x and y.
❑
Its methods take parameters of the same types as the associated methods of the remote object. For example, the Add method of the local Math object associated with the remote Math Web service object also takes two parameters of the same types as the parameters of the Add method of the remote Math Web service object: double.
❑
Its methods return values of the same types as the associated methods of the remote object. For example, the Add method of the local Math object associated with the remote Math Web service object returns a value of the same type as the return value of the Add method of the remote Math Web service object: double.
599
c15.indd 599
8/20/07 9:08:01 PM
Chapter 15: Proxy Classes This enables you to program against the local object, instead of the WebServiceProxy object as you did in the last chapter, and consequently, makes programming against remote objects more like programming against local objects. Because this local object makes it feel like you’re directly interacting with the remote object, it is known as a proxy object. In other words, this local object acts as a proxy for the remote object. Let’s begin by discussing the implementation of the proxy class and object that the ASP.NET AJAX framework automatically generates for you. (The mechanism that actually generates this proxy class and object is discussed later in the chapter.) As you learned in the previous chapter, there are three types of remote method invocations:
❑
Invoking a Web method that is part of a Web service
❑
Invoking a page method that is part of an ASP.NET page
❑
Invoking a method that is part of a custom class
Therefore, there are three types of proxy classes:
❑
Proxy classes associated with Web services
❑
Proxy classes associated with page methods
❑
Proxy classes associated with custom classes
Proxy Classes Associated with Web Services Listing 15-4 presents the implementation of the local Math proxy class associated with the remote Math Web service class.
Listing 15-4: The Local Math Proxy Class Associated with the Remote Math Web Service Class Type.registerNamespace(‘MyNamespace’); MyNamespace.Math = function() { MyNamespace.Math.initializeBase(this); this._timeout = 0; this._userContext = null; this._succeeded = null; this._failed = null; } MyNamespace.Math.prototype = { Add : function(x, y, succeededCallback, failedCallback, userContext) { var servicePath = MyNamespace.Math.get_path(); var methodName = ‘Add’; var useGet = false; var params = {x : x, y : y}; var onSuccess = succeededCallback;
This code listing defines a namespace with the same name as the namespace of the remote Math Web service class: Type.registerNamespace(‘MyNamespace’);
The local Math proxy class derives from the WebServiceProxy class: MyNamespace.Math.registerClass(‘MyNamespace.Math’, Sys.Net.WebServiceProxy);
All ASP.NET AJAX proxy classes directly or indirectly derive from the Sys.Net.WebServiceProxy class. As you can see from in the following excerpt from Listing 15-4, this local Math proxy class exposes a method with the same name as the remote Web service class — Add. This method takes parameters with the same names and types as the remote Web service class’s Add method parameters, and returns a value of the same type as the remote Web service class’s Add method return value: MyNamespace.Math.prototype = { Add : function(x, y, succeededCallback, failedCallback, userContext) { var servicePath = MyNamespace.Math.get_path(); var methodName = ‘Add’; var useGet = false; var params = {x : x, y : y}; var onSuccess = succeededCallback; var onFailure = failedCallback; return this._invoke(servicePath, methodName, useGet, params, onSuccess,onFailure, userContext); } }
The Add method of this local Math proxy class encapsulates the code that you would otherwise have to write to interact with the WebServiceProxy object as you did in the previous chapter. Note that Listing 15-4 instantiates an instance of this local Math proxy class and assigns the instance to a private static field on this class named _staticInstance: MyNamespace.Math._staticInstance = new MyNamespace.Math();
602
c15.indd 602
8/20/07 9:08:02 PM
Chapter 15: Proxy Classes The code then defines static getters and setters that delegate to the associated getters and setters of this static Math proxy instance. Also note that the code exposes a static method named Add on this local Math proxy class, which delegates to the Add method of the static Math proxy instance: MyNamespace.Math.Add = function(x, y, onSuccess, onFailed, userContext) { MyNamespace.Math._staticInstance.Add(x, y, onSuccess, onFailed, userContext); }
Finally, the code invokes the set_path static method on this local Math proxy class to set the service path for the static Math proxy instance: MyNamespace.Math.set_path(“/AJAXFuturesEnabledWebSite2/Math.asmx”);
Listing 15-5 presents a page that uses the Math proxy class. As you’ll see later in this chapter, the ASP.NET AJAX framework automatically generates the code for the proxy class such as the Math proxy class shown in this listing. For now, assume that you generated this code yourself and treat it like any other client code. As such, the content of Listing 15-4 is stored in a JavaScript file named MathWebServiceProxy.js, and Listing 15-5 adds a reference to this JavaScript file. Now let’s walk through the implementation of the add JavaScript function shown in the following excerpt from Listing 15-5: function add() { var userContext = $get(“result”); var xValue = $get(“firstNumber”).value; var yValue = $get(“secondNumber”).value; MyNamespace.Math.Add(xValue, yValue, onSuccess, onFailure, userContext); }
Thanks to the Math proxy class, you get to directly invoke the Add method and directly pass the x and y values into this method. Note that there is no sign of the WebServiceProxy and its weird-looking _invoke method. The Math proxy class enables you to program against the remote Math Web service object as if you were programming against a local Math object. In other words, the Math proxy class gives your client code the illusion that it is making a local method call.
Listing 15-5: A Page that Uses the Local Static Math Proxy Instance Untitled Page var request; function onSuccess(result, userContext, methodName) {
(continued)
603
c15.indd 603
8/20/07 9:08:02 PM
Chapter 15: Proxy Classes Listing 15-5 (continued) userContext.innerHTML = “” + result + “”; } function onFailure(result, userContext, methodName) { var builder = new Sys.StringBuilder(); builder.append(“timedOut: “); builder.append(result.get_timedOut()); builder.appendLine(); builder.appendLine(); builder.append(“message: “); builder.append(result.get_message()); builder.appendLine(); builder.appendLine(); builder.append(“stackTrace: “); builder.appendLine(); builder.append(result.get_stackTrace()); builder.appendLine(); builder.appendLine(); builder.append(“exceptionType: “); builder.append(result.get_exceptionType()); builder.appendLine(); builder.appendLine(); builder.append(“statusCode: “); builder.append(result.get_statusCode()); builder.appendLine(); builder.appendLine(); builder.append(“methodName: “); builder.append(methodName); alert(builder.toString()); } function add() { var userContext = $get(“result”); var xValue = $get(“firstNumber”).value; var yValue = $get(“secondNumber”).value; MyNamespace.Math.Add(xValue, yValue, onSuccess, onFailure, userContext); }
604
c15.indd 604
8/20/07 9:08:02 PM
Chapter 15: Proxy Classes First Number:
Second Number:
Add
Result:
Proxy Classes Associated with Page Methods The following code presents a proxy class associated with a page method named Add, which belongs to the PageMethods.aspx page: PageMethods = function() { PageMethods.initializeBase(this); this._timeout = 0; this._userContext = null; this._succeeded = null; this._failed = null; } PageMethods.prototype = { Add : function(x, y, succeededCallback, failedCallback, userContext) { return this._invoke(PageMethods.get_path(), ‘Add’, false, {x:x, y:y}, succeededCallback, failedCallback, userContext); } } PageMethods.registerClass(‘PageMethods’, Sys.Net.WebServiceProxy);
Chapter 15: Proxy Classes Comparing this code with Listing 15-4 clearly shows that a proxy class associated with page methods has a fixed named — PageMethods — and does not belong to any namespace. All methods annotated with WebMethod metadata attribute on a given page are associated with the same proxy class named PageMethods on the client side. As the boldface portion of the code shows, the set_path method is invoked on the PageMethods proxy object to specify the URL of the PageMethods.aspx page as the target URL for the proxy class. The following code presents a page that uses the PageMethods proxy class. As you’ll see later in this chapter, the ASP.NET AJAX framework automatically generates the code for the PageMethods proxy class and adds this code to the current page. For now, assume that you generated this code yourself and treat it like any other client script. As such, this code is stored in a JavaScript file named MathPageMethodsProxy.js, and the following code adds a reference to this file. Note that the following code is the same as Listing 15-5, except for the boldface portion where the PageMethods proxy is used to communicate with the underlying page method. Untitled Page var request; function onSuccess(result, userContext, methodName) { userContext.innerHTML = “” + result + “”; } function onFailure(result, userContext, methodName) { //Same as Listing 15-5 } function add() { var userContext = $get(“result”); var xValue = $get(“firstNumber”).value; var yValue = $get(“secondNumber”).value; PageMethods.Add(xValue, yValue, onSuccess, onFailure, userContext); }
607
c15.indd 607
8/20/07 9:08:03 PM
Chapter 15: Proxy Classes
Proxy Classes Associated with Custom Classes The proxy classes associated with custom classes are very similar to the proxy classes associated with Web services. The main difference is that the target URL of the proxy class associated with a custom class is set to the URL of the .asbx file that describes the custom class.
Automatic Proxy Class Generation This illusion will work only if someone implements the Math proxy class for you. Otherwise, if you were to implement this class yourself, it would not be much of an illusion. The main challenge with implementing a proxy class is that one proxy class will not work with all types of remote classes. For example, you cannot use the Math proxy class to talk to the Products Web service class because the Products Web service class is a completely different Web service class than the Math Web service class. For one thing, the Products Web service class exposes methods such as GetProducts as opposed to Add. This means that you have to use separate proxy classes to talk to different remote classes. This is where the ASP.NET AJAX server-side framework comes to the rescue. This framework contains the logic that automatically generates the code for the proxy class for each remote class that your client code needs to interact with. All you have to do is add a ServiceReference object to the Services collection of the current ScriptManager server control to specify which remote class you need to talk to. You can do this either imperatively or declaratively.
Declarative Approach Listing 15-6 presents a page that that uses the declarative approach to add a ServiceReference object to the Services collection of the current ScriptManager server control.
Listing 15-6: A Page that Uses the Declarative Approach to Add a ScriptReference Object Untitled Page var request; function onSuccess(result, userContext, methodName) { userContext.innerHTML = “” + result + “”; } function onFailure(result, userContext, methodName) { var builder = new Sys.StringBuilder(); builder.append(“timedOut: “); builder.append(result.get_timedOut()); builder.appendLine();
As you can see in the boldface portion of this code listing, the page adds an element to the child element of the tag that represents the current ScriptManager server control on the .aspx page. Note that this page sets the Path attribute on this tag to the service path of the Math Web service. Also note that the page sets the InlineScript attribute on this tag to true to tell the ASP.NET AJAX server-side framework to add the definition of the Math proxy class to the markup sent to the requesting browser. As a matter of fact, if you run Listing 15-6 and view the source from your browser, you’ll see Listing 15-7.
Listing 15-7: The Source for the Page Shown in Listing 15-6 Untitled Page var request; function onSuccess(result, userContext, methodName) { userContext.innerHTML = “” + result + “”; } function onFailure(result, userContext, methodName) { var builder = new Sys.StringBuilder(); builder.append(“timedOut: “); builder.append(result.get_timedOut()); builder.appendLine();
As you can see, the boldface portion of this listing is just the inline definition of the Math proxy class. This inline solution has the following drawbacks:
❑
Like any other inline solution, it does not allow the browser to cache the same script used in different pages to improve performance. For example, if you have multiple pages in your application that use the Math proxy class, every single page will include the boldface portion of Listing 15-7. However, if the script that defines the Math proxy class were in a separate file (as shown in the following code snippet), the browser could download and cache this file once.
❑
It increases the size of the page because the definition of the Math proxy class is directly added to the page. As you can see in Listing 15-7, your pages could get quite large, and the bigger a page is, the longer it takes to download. However, if the boldface portion of Listing 15-7 were in a separate file (as shown in the following code snippet), the browser would download this script once and use it across all pages in your application that use the Math proxy class.
If you set the InlineScript attribute on the to false, run the same page, and view the source from your browser, you’ll get Listing 15-8.
614
c15.indd 614
8/20/07 9:08:05 PM
Chapter 15: Proxy Classes Listing 15-8: The Source of the Page Shown in Listing 15-6 with a ScriptMode Value of Debug Untitled Page var request; function onSuccess(result, userContext, methodName) { userContext.innerHTML = “” + result + “”; } function onFailure(result, userContext, methodName) { var builder = new Sys.StringBuilder(); builder.append(“timedOut: “); builder.append(result.get_timedOut()); builder.appendLine(); builder.appendLine(); builder.append(“message: “); builder.append(result.get_message()); builder.appendLine(); builder.appendLine(); builder.append(“stackTrace: “); builder.appendLine(); builder.append(result.get_stackTrace()); builder.appendLine(); builder.appendLine(); builder.append(“exceptionType: “); builder.append(result.get_exceptionType()); builder.appendLine(); builder.appendLine(); builder.append(“statusCode: “); builder.append(result.get_statusCode()); builder.appendLine(); builder.appendLine(); builder.append(“methodName: “); builder.append(methodName); alert(builder.toString()); } function add() { var userContext = $get(“result”); var xValue = $get(“firstNumber”).value;
Notice that the boldface portion of Listing 15-7 is replaced by the boldface portion of Listing 15-8:
617
c15.indd 617
8/20/07 9:08:06 PM
Chapter 15: Proxy Classes This script block sets the src to the value /AJAXFuturesEnabledWebSite2/Math.asmx/jsdebug. Note that this value consists of two parts: the first part is the URL of the Math Web service, and the second part is jsdebug. The path trailer jsdebug tells the ASP.NET AJAX server-side framework that the client code wants to download the debug version of the script. If you enter this URL in the address bar of your browser, you’ll get the JavaScript file that contains the definition of the Math proxy class (the boldfacportion of Listing 15-7). The ScriptManager server control exposes an enumerator property of type ScriptMode and named ScriptMode. This property determines which version of the script to download. The following code presents the definition of the ScriptMode enumerator: public enum ScriptMode { Auto = 0, Inherit = 1, Debug = 2, Release = 3, }
For example, if you set the ScriptMode attribute on the child element previously shown in Listing 15-6 to Release, run the listing page, and view the page source from your browser, you’ll see that the source contains the following script block. As the boldface portion shows, the path trailer is now js instead of jsdebug, which means that this time around, the release version of the script will be downloaded:
Imperative Approach Listing 15-9 presents a page that uses the imperative approach to add a ServiceReference object to the Services collection of the current ScriptManager server control.
Listing 15-9: A Page that Uses the Imperative Approach to Add a ServiceReference void Page_Load(object sender, EventArgs e) { if (!IsPostBack) { ServiceReference serviceRef = new ServiceReference(); serviceRef.InlineScript = false; serviceRef.Path = “/AJAXCTPEnabledWebSite2/Math.asmx”; ScriptManager1.Services.Add(serviceRef); } }
618
c15.indd 618
8/20/07 9:08:06 PM
Chapter 15: Proxy Classes Untitled Page var request; function onSuccess(result, userContext, methodName) { userContext.innerHTML = “” + result + “”; } function onFailure(result, userContext, methodName) { var builder = new Sys.StringBuilder(); builder.append(“timedOut: “); builder.append(result.get_timedOut()); builder.appendLine(); builder.appendLine(); builder.append(“message: “); builder.append(result.get_message()); builder.appendLine(); builder.appendLine(); builder.append(“stackTrace: “); builder.appendLine(); builder.append(result.get_stackTrace()); builder.appendLine(); builder.appendLine(); builder.append(“exceptionType: “); builder.append(result.get_exceptionType()); builder.appendLine(); builder.appendLine(); builder.append(“statusCode: “); builder.append(result.get_statusCode()); builder.appendLine(); builder.appendLine(); builder.append(“methodName: “); builder.append(methodName); alert(builder.toString()); } function add() { var userContext = $get(“result”); var xValue = $get(“firstNumber”).value; var yValue = $get(“secondNumber”).value; MyNamespace.Math.Add(xValue, yValue, onSuccess, onFailure, userContext); }
As the boldface portion of this code listing shows, the Page_Load method first instantiates a ServiceReference instance: ServiceReference serviceRef = new ServiceReference();
Next, it sets the InlineScript and Path properties of this instance: serviceRef.InlineScript = false; serviceRef.Path = “/AJAXFuturesEnabledWebSite2/Math.asmx”;
Finally, it adds the instance to the Services collection of the current ScriptManager server control: ScriptManager1.Services.Add(serviceRef);
620
c15.indd 620
8/20/07 9:08:07 PM
Chapter 15: Proxy Classes
Parent/Child Pages As previously discussed, to take advantage of the ASP.NET AJAX server-side framework automatic proxy-code generation, you must imperatively or declaratively add a ServiceReference object to the Services collection of the ScriptManager server control. To do so, you need to have access to this server control. This causes problems in situations involving parent and child pages. Two common scenarios are master/content and host/user control scenarios. In the master/content page scenario, the parent page is the master page and the child page is the content page. In the host/user control scenario, the child page is the user control and the parent page is the page that hosts the user control. The problem in these parent/child page scenarios is that the parent and child are finally merged and form a single page, which means that you cannot include a separate instance of the ScriptManager server control on the parent and child pages. As previously discussed, every page can contain only a single instance of the ScriptManager server control. If you put the ScriptManager server control on the parent page, the child page would not be able to add its ServiceReference objects to the Services collection of the ScriptManager server control. If you put the ScriptManager server control on the child page, the parent page would not be able to add its ServiceReference objects to the Services collection of the ScriptManager server control. You would have the same problem with ScriptReferences. If you put the ScriptManager server control on the parent page, the child page would not be able to add its ScriptReference objects to the Scripts collection of the ScriptManager server control. If you put the ScriptManager server control on the child page, the parent page would not be able to add its ScriptReference objects to the Scripts collection of the ScriptManager server control. To tackle these situations, the ASP.NET AJAX framework includes a new server control named ScriptManagerProxy. A child page whose parent page contains an instance of the ScriptManager server control, or a parent page whose child page contains an instance of the ScriptManager server control, can add its ServiceReference and ScriptReference objects to the Services and Scripts collections of the ScriptManagerProxy server control and rest assured that the ASP.NET AJAX framework will automatically add these ServiceReference and ScriptReference objects to the ScriptManager server control. Because the ServiceReference and ScriptReference objects added to the Services and Scripts collections of the ScriptManagerProxy server control are added to the Services and Scripts collections of the current ScriptManager server control, the ScriptManagerProxy server control acts as a proxy for the current ScriptManager server control.
Listing 15-10 contains a user control that employs the ScriptManagerProxy server control.
Listing 15-10: A User Control that Employs the ScriptManagerProxy Server Control var request; function onSuccess(result, userContext, methodName) { userContext.innerHTML = “” + result + “”; }
(continued)
621
c15.indd 621
8/20/07 9:08:07 PM
Chapter 15: Proxy Classes Listing 15-10 (continued) function onFailure(result, userContext, methodName) { var builder = new Sys.StringBuilder(); builder.append(“timedOut: “); builder.append(result.get_timedOut()); builder.appendLine(); builder.appendLine(); builder.append(“message: “); builder.append(result.get_message()); builder.appendLine(); builder.appendLine(); builder.append(“stackTrace: “); builder.appendLine(); builder.append(result.get_stackTrace()); builder.appendLine(); builder.appendLine(); builder.append(“exceptionType: “); builder.append(result.get_exceptionType()); builder.appendLine(); builder.appendLine(); builder.append(“statusCode: “); builder.append(result.get_statusCode()); builder.appendLine(); builder.appendLine(); builder.append(“methodName: “); builder.append(methodName); alert(builder.toString()); } function add() { var userContext = $get(“result”); var xValue = $get(“firstNumber”).value; var yValue = $get(“secondNumber”).value; MyNamespace.Math.Add(xValue, yValue, onSuccess, onFailure, userContext); }
First Number:
622
c15.indd 622
8/20/07 9:08:08 PM
Chapter 15: Proxy Classes
Second Number:
Add
Result:
Listing 15-11 presents a page that hosts the user control shown in Listing 15-10. As you can see, the host page contains the ScriptManager server control, and the child user control contains the ScriptManagerProxy server control.
Listing 15-11: A Page that Hosts the User Control shown in Listing 15-10 Untitled Page
Under the Hood Adding a ServiceReference object to the Services collection of the current ScriptManager server control is all it takes to instruct the ASP.NET AJAX server-side framework to automatically generate a client script that defines, instantiates, and initializes the proxy class. To help you understand how the ASP.NET AJAX server-side framework manages to do this, this section implements fully functional
623
c15.indd 623
8/20/07 9:08:08 PM
Chapter 15: Proxy Classes (as far as the discussions in this section are concerned) replicas of the components of the framework that are responsible for generating a client script that defines, instantiates, and initializes the proxy class.
ScriptManager Listing 15-12 presents the implementation of the replica ScriptManager server control.
Listing 15-12: The Replica ScriptManager Server Control using using using using using using using using using using using using using using using using
namespace CustomComponents { [ParseChildren(true), DefaultProperty(“Scripts”), NonVisualControl, PersistChildren(false)] public class ScriptManager : Control { private ServiceReferenceCollection _services; [PersistenceMode(PersistenceMode.InnerProperty), Editor(“System.Web.UI.Design.CollectionEditorBase, System.Web.Extensions.Design, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35”, typeof(System.Drawing.Design.UITypeEditor)), DefaultValue((string)null), MergableProperty(false), Category(“Behavior”)] public ServiceReferenceCollection Services { get { if (this._services == null) this._services = new ServiceReferenceCollection(); return this._services; } }
624
c15.indd 624
8/20/07 9:08:08 PM
Chapter 15: Proxy Classes protected override void OnInit(EventArgs e) { base.OnInit(e); this.Page.PreRenderComplete += new EventHandler(Page_PreRenderComplete); } void Page_PreRenderComplete(object sender, EventArgs e) { if (this._services != null) { foreach (ServiceReference reference in this._services) { reference.Register(this); } } if (this.EnablePageMethods) { ClientProxyGenerator generator2 = new ClientProxyGenerator(); string script = generator2.GetClientProxyScript(this.Page.Request.FilePath, true); this.Page.ClientScript.RegisterClientScriptBlock(typeof(Page), script, script, true); } } public bool EnablePageMethods { get { return ViewState[“EnablePageMethods”] != null ? (bool)ViewState[“EnablePageMethods”] : false; } set { ViewState[“EnablePageMethods”] = value; } } } }
Services The replica ScriptManager exposes a collection property of type ServiceReferenceCollection named Services, as defined in the following excerpt from Listing 15-12. Note that this property is annotated with the PersistenceMode(PersistenceMode.InnerProperty) metadata attribute, which enables page developers to declare the property as the child element of the tag that represents the ScriptManager on the .aspx page. private ServiceReferenceCollection _services; [PersistenceMode(PersistenceMode.InnerProperty), Editor(“System.Web.UI.Design.CollectionEditorBase,
(continued)
625
c15.indd 625
8/20/07 9:08:08 PM
Chapter 15: Proxy Classes (continued) System.Web.Extensions.Design, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35”, typeof(System.Drawing.Design.UITypeEditor)), DefaultValue((string)null), MergableProperty(false), Category(“Behavior”)] public ServiceReferenceCollection Services { get { if (this._services == null) this._services = new ServiceReferenceCollection(); return this._services; } }
Listing 15-13 presents the implementation of the replica ServiceReferenceCollection class. Thanks to the .NET 2.0 generics, implementing a new type-safe collection class is just a matter of deriving from a generic collection class such as Collection.
Listing 15-13: The ServiceReferenceCollection Class using System.Collections; using System.Collections.Generic; using System.Collections.ObjectModel; namespace CustomComponents { public class ServiceReferenceCollection : Collection { } }
EnablePageMethods The replica ScriptManager server control also exposes a Boolean property named EnablePageMethods, as shown in the following excerpt from Listing 15-12. Page developers can set this property to have the control generate a client script that defines, instantiates, and initializes the PageMethods client class. public bool EnablePageMethods { get { return ViewState[“EnablePageMethods”] != null ? (bool)ViewState[“EnablePageMethods”] : false; } set { ViewState[“EnablePageMethods”] = value; } }
626
c15.indd 626
8/20/07 9:08:09 PM
Chapter 15: Proxy Classes OnInit As you can see in the following excerpt from Listing 15-12, the replica ScriptManager server control overrides the OnInit method that it inherits from the Control base class to register a method named Page_RenderComplete as the event handler for the Page object’s PreRenderComplete event: protected override void OnInit(EventArgs e) { base.OnInit(e); this.Page.PreRenderComplete += new EventHandler(Page_PreRenderComplete); }
Page_PreRenderComplete When the page finally enters its PreRenderComplete lifecycle phase, it automatically calls the Page_PreRenderComplete method, which in turn performs the following tasks:
1.
It iterates through the ServiceReference objects in the Services collections and invokes their Register methods:
reference.Register(this);
2.
It checks whether the EnablePageMethods property is set to true. If so, it instantiates an instance of a class named ClientProxyGenerator: ClientProxyGenerator generator2 = new ClientProxyGenerator();
3.
It invokes the GetClientProxyScript method on this ClientProxyGenerator object to generate the client script that defines, instantiates, and initializes the PageMethods client class: string script = generator2.GetClientProxyScript(this.Page.Request.FilePath, true);
4.
It invokes the RegisterClientScriptBlock method on the ClientScript property of the containing page to register this script for rendering: this.Page.ClientScript.RegisterClientScriptBlock(typeof(Page), script, script, true);
As a result, when the containing page enters its rendering phase, it will automatically render all registered scripts, including the script that defines, instantiates, and initializes the PageMethods client class:
ServiceReference Listing 15-14 presents the implementation of the replica ServiceReference class.
627
c15.indd 627
8/20/07 9:08:09 PM
Chapter 15: Proxy Classes Listing 15-14: The ServiceReference Class using using using using using using using using using using using using using using using using using using
The Register method in this listing takes the following steps if the page developer has set the InlineScript Boolean property to true:
1.
It instantiates a ClientProxyGenerator object: ClientProxyGenerator generator = new ClientProxyGenerator();
2.
It invokes the GetClientProxyScript method on this ClientProxyGenerator object to generate the client script that defines, instantiates, and initializes the proxy class: inlineScript = generator.GetClientProxyScript(this.Path, false);
3.
It invokes the RegisterClientScriptBlock method on the Page object’s ClientScript property of to register the client script for rendering: control.Page.ClientScript.RegisterClientScriptBlock(typeof(Page), inlineScript, inlineScript, true);
As a result, when the page enters its rendering phase, it automatically renders all registered client scripts, including the client script that defines, instantiates, and initializes the proxy class. Conversely, if the page developer has not set the InlineScript Boolean property to true, the Register method simply calls the RegisterClientScriptInclude method on the ClientScript property of the Page object to register a script block whose src attribute is set to the service path plus the path trailer /js: else { string url = this.Path + “/js”; control.Page.ClientScript.RegisterClientScriptInclude(typeof(Page), url, url); }
For the purposes of the current discussion, you can ignore the /jsdebug option.
629
c15.indd 629
8/20/07 9:08:09 PM
Chapter 15: Proxy Classes
ClientProxyGenerator Listing 15-15 presents the implementation of the replica ClientProxyGenerator class. The following sections discuss the methods and properties of this class.
Listing 15-15: The ClientProxyGenerator Class using using using using using using using using using using using using using using using using using using
GetClientProxyScript Listing 15-16 shows the GetClientProxyScript method of the replica ClientProxyGenerator class. The main responsibility of this method is to generate the client script that defines, instantiates, and initializes the proxy class.
The GetClientProxyScript method takes two arguments. The first argument is a string that contains the service path, and the second argument is a Boolean that specifies whether the first parameter of the server method contains the path to an .aspx page, which means it is being invoked as a page method. This method performs the following tasks:
1.
It invokes the DetermineServiceType method to determine the Type object that represents the type of the server class that represents the file with the specified service path: this.DetermineServiceType();
635
c15.indd 635
8/20/07 9:08:11 PM
Chapter 15: Proxy Classes 2.
It invokes the DetermineServiceFullName method to determine the full name of the server class: this.DetermineServiceFullName();
3.
It invokes the PopulateMethodInfos method to populate an internal collection named _methodInfos with MethodInfo objects that represent the server class methods: this.PopulateMethodInfos();
4.
It invokes the PopulateParameterInfos method to populate an internal collection named _parameterInfos with ParameterInfo objects that represent the parameters of the server class methods: this.PopulateParameterInfos();
5.
It invokes the GenerateNamespace method to generate the client script that defines the namespace of the proxy class if the method being invoked is not a page method: if (!this._isPageMethod) this.GenerateNamespace();
As previously discussed, the proxy class in this example is named PageMethods and does not belong to any namespace:
6.
It invokes the GenerateConstructor method to generate the client script that defines the constructor of the proxy class: this.GenerateConstructor();
7.
It invokes the GeneratePrototype method to generate the client script that defines the prototype property of the proxy class: this.GeneratePrototype();
8.
It invokes the GenerateRegisterClass method to generate the client script that registers the proxy class with the ASP.NET AJAX client-side framework: this.GenerateRegisterClass();
9.
It invokes the GenerateStaticInstance method to generate the client script that defines the _staticInstance property of the proxy class: this.GenerateStaticInstance();
10.
It invokes the GenerateStaticMethods method to generate the client script that defines the static method of the proxy class: this.GenerateStaticMethods();
636
c15.indd 636
8/20/07 9:08:12 PM
Chapter 15: Proxy Classes As you can see, the GetClientProxyScript method basically generates a client script such as the one previously shown in Listing 15-4. Keep that listing in mind as the following sections walk you through the implementation of the methods that the GetClientProxyScript method invokes.
DetermineServiceType As you can see in the following excerpt from Listing 15-15, the DetermineServiceType method invokes the GetCompiledType static method on the BuildManager class. The GetCompiledType method takes a string parameter that contains the virtual path of a file, uses this virtual path to locate the file on the server, parses the file, uses the content of the file to dynamically generate the code for a .NET class that represents the file, compiles this dynamically generated class into an assembly, loads the assembly into the current application domain, and returns a reference to the Type object that represents the compiled class. Note that the DetermineServiceType method stores this reference in a private field named _serviceType. private void DetermineServiceType() { _serviceType = BuildManager.GetCompiledType(this._servicePath); if (_serviceType == null) _serviceType = BuildManager.CreateInstanceFromVirtualPath(_servicePath, typeof(Page)).GetType(); }
DetermineServiceFullName As you can see in the following excerpt from Listing 15-15, the DetermineServiceFullName method first checks whether _isPageMethod field of the ScriptManager server control is set to true. If so, it simply uses PageMethod as the service’s full name. If not, it uses the FullName property value of the Type object that represents the service as the service’s full name. The FullName property returns a string that contains the fully qualified name of the service type, including its complete containment namespace hierarchy. private void DetermineServiceFullName() { if (this._isPageMethod) _serviceFullName = “PageMethods”; else _serviceFullName = _serviceType.FullName; }
PopulateMethodInfos The PopulateMethodInfos method takes the following steps to populate an internal collection named _methodInfos:
1.
It invokes the GetMethods method on the Type object that represents the type of the service to return an array of MethodInfo objects, where each object represents a method of the service: MethodInfo[] infoArray = _serviceType.GetMethods();
637
c15.indd 637
8/20/07 9:08:12 PM
Chapter 15: Proxy Classes 2.
It searches through the objects in this array for MethodInfo objects annotated with the WebMethodAttribute metadata attribute and adds them to the _methodInfos collection: foreach (MethodInfo info in infoArray) { object[] objArray = info.GetCustomAttributes(typeof(WebMethodAttribute), true); if (objArray.Length != 0) _methodInfos.Add(info); } }
PopulateParameterInfos The PopulateParameterInfos method iterates through the MethodInfo objects in the _methodInfos collection and takes the following steps for each object:
1.
It invokes the GetParameters method on the MethodInfo object to return an array of ParameterInfo objects, where each object represents a parameter of the method that the MethodInfo object represents: list = info.GetParameters();
2.
It uses the MethodInfo object as an index into the _parameterInfos collection to add the ParameterInfo objects to the collection: list2 = new ArrayList(); list2.AddRange(list); _parameterInfos.Add(info, list2); } }
The _parameterInfos collection is a collection of collections, where each collection contains the ParameterInfo objects of a particular MethodInfo object.
GenerateNamespace As you can see in the following excerpt from Listing 15-15, the GenerateNamespace method generates the client script that defines the namespace of the proxy class. Note that this method uses the namespace of the service as the namespace of the proxy class. private void GenerateNamespace() { this._builder.Append(“\r\nType.registerNamespace(‘”); this._builder.Append(_serviceType.Namespace); this._builder.Append(“’);\r\n\r\n”); }
This method basically generates the following portion of the Listing 15-4 script: Type.registerNamespace(‘MyNamespace’);
638
c15.indd 638
8/20/07 9:08:12 PM
Chapter 15: Proxy Classes GenerateConstructor As you can see in the following excerpt from Listing 15-15, the GenerateConstructor method generates the script that defines the constructor of the proxy class. Note that this method uses the fully qualified name of the service as the name of the proxy class. private void GenerateConstructor() { _builder.Append(_serviceFullName); _builder.Append(“ = “); _builder.Append(“function()\r\n{\r\n\t”); _builder.Append(_serviceFullName); _builder.Append(“.initializeBase(this);\r\n”); _builder.Append(“\tthis._timeout = 0;\r\n”); _builder.Append(“\tthis._userContext = null;\r\n”); _builder.Append(“\tthis._succeeded = null;\r\n”); _builder.Append(“\tthis._failed = null;\r\n”); _builder.Append(“}\r\n\r\n”); }
This method basically generates the following portion of the Listing 15-4 script: MyNamespace.Math = function() { MyNamespace.Math.initializeBase(this); this._timeout = 0; this._userContext = null; this._succeeded = null; this._failed = null; }
GeneratePrototype The GeneratePrototype method generates the portion of the script that defines the prototype property of the proxy class. As you can see in the following excerpt from Listing 15-15, this method iterates through the MethodInfo objects in the _methodInfos collection and invokes the GenerateWebMethodProxy method to generate the script that defines the associated method of the proxy class: private void GeneratePrototype() { this._builder.Append(_serviceFullName); this._builder.Append(“.prototype”); this._builder.Append(“ = “); this._builder.Append(“\r\n{“); bool flag1 = true; foreach (MethodInfo methodInfo in _methodInfos) { if (!flag1) _builder.Append(“,\r\n”); flag1 = false; this.GenerateWebMethodProxy(methodInfo); } _builder.Append(“}\r\n\r\n”); }
639
c15.indd 639
8/20/07 9:08:12 PM
Chapter 15: Proxy Classes This method basically generates the following portion of the Listing 15-4 script: MyNamespace.Math.prototype = { Add : function(x, y, succeededCallback, failedCallback, userContext) { return this._invoke(MyNamespace.Math.get_path(),’Add’, false, {x : x, y : y}, succeededCallback, failedCallback, userContext); } }
GenerateWebMethodProxy The GenerateWebMethodProxy method takes a MethodInfo object as its argument and generates the script that defines the method of the proxy class associated with this MethodInfo object, as shown in Listing 15-17 (which is the GenerateWebProxy method portion of Listing 15-15).
Listing 15-17: The GenerateWebMethodProxy Method private void GenerateWebMethodProxy(MethodInfo methodInfo) { ArrayList parameterList = _parameterInfos[methodInfo]; _builder.Append(methodInfo.Name); _builder.Append(“ : “); _builder.Append(“function(“); foreach (ParameterInfo pinfo in parameterList) { _builder.Append(pinfo.Name); _builder.Append(“, “); } _builder.Append(“succeededCallback, failedCallback, userContext)”); _builder.Append(“\r\n{\r\n”); _builder.Append(“\treturn this._invoke(“); _builder.Append(_serviceFullName); _builder.Append(“.get_path(), “); _builder.Append(“’”); _builder.Append(methodInfo.Name); _builder.Append(“’, false, “); _builder.Append(‘{‘); int i = 0; foreach (ParameterInfo pinfo in parameterList) { _builder.Append(pinfo.Name); _builder.Append(“:”); _builder.Append(pinfo.Name); if (i != (parameterList.Count - 1)) _builder.Append(“, “); i++; }
For example, this listing generates the local Math proxy class associated with the remote Math Web service class, as previously shown in Listing 15-4 and again in Listing 15-18.
Listing 15-18: An Example of the Script that Listing 15-17 Generates Add : function(x, y, succeededCallback, failedCallback, userContext) { return this._invoke(MyNamespace.Math.get_path(),’Add’, false, {x : x, y : y}, succeededCallback, failedCallback, userContext); }
Keeping this listing in mind, let’s walk through the implementation of the GenerateWebMethodProxy method shown in Listing 15-17. The GenerateWebMethodProxy method uses the name of the server method as the name of the associated proxy method: _builder.Append(methodInfo.Name);
This code basically generates the following portion of the Listing 15-18 script: Add
The following lines of code from Listing 15-17: _builder.Append(“ : “); _builder.Append(“function(“);
generate the following portion of the Listing 15-18 script: Add : function(
Listing 15-17 uses the names of the parameters of the server method as the names of the parameters of the associated proxy method: foreach (ParameterInfo pinfo in parameterList) { _builder.Append(pinfo.Name); _builder.Append(“, “); }
This code basically generates the following boldface portion of the Listing 15-18 script: Add : function(x, y,
641
c15.indd 641
8/20/07 9:08:13 PM
Chapter 15: Proxy Classes The next lines of code in Listing 15-17: _builder.Append(“succeededCallback, failedCallback, userContext)”); _builder.Append(“\r\n{\r\n”); _builder.Append(“\treturn this._invoke(“);
generate the following boldface portion of the Listing 15-18 script: Add : function(x, y, succeededCallback, failedCallback, userContext) { this._invoke(
The next lines of code in Listing 15-17: _builder.Append(_serviceFullName); _builder.Append(“.get_path(), “);
generate the following boldface portion of the Listing 15-18 script: Add : function(x, y, succeededCallback, failedCallback, userContext) { this._invoke(MyNamespace.Math.get_path(),
The next lines of code in Listing 15-17: _builder.Append(“’”); _builder.Append(methodInfo.Name); _builder.Append(“’, false, “);
generate the following boldface portion of the Listing 15-18 script, which specifies the name of the service method and the value false to indicate that you want to make the POST HTTP request: Add : function(x, y, succeededCallback, failedCallback, userContext) { this._invoke(MyNamespace.Math.get_path(),’Add’, false,
Listing 15-17 then iterates through the parameters of the service method as follows: _builder.Append(‘{‘); int i = 0; foreach (ParameterInfo pinfo in parameterList) { _builder.Append(pinfo.Name); _builder.Append(“:”); _builder.Append(pinfo.Name); if (i != (parameterList.Count - 1)) _builder.Append(“, “); i++; } _builder.Append(“}”);
642
c15.indd 642
8/20/07 9:08:13 PM
Chapter 15: Proxy Classes to generate the following boldface portion of the Listing 15-18 script: Add : function(x, y, succeededCallback, failedCallback, userContext) { this._invoke(MyNamespace.Math.get_path(),’Add’, false, {x:x, y:y}
The last lines of the code in Listing 15-17: _builder.Append(“, succeededCallback, failedCallback, userContext);” + “\r\n}\r\n”);
wrap the rendering of the specified method of the proxy class, as shown in the following boldface portion of the Listing 15-18 script: Add : function(x, y, succeededCallback, failedCallback, userContext) { this._invoke(MyNamespace.Math.get_path(),’Add’, false, {x:x, y:y}, succeededCallback, failedCallback, userContext); }
GenerateRegisterClass As you can see in the following excerpt from Listing 15-15, the GenerateRegisterClass method generates the script that registers the proxy class with the ASP.NET AJAX client-side framework. protected void GenerateRegisterClass() { this._builder.Append(this._serviceFullName); this._builder.Append(“.registerClass(‘”); this._builder.Append(this._serviceFullName); this._builder.Append(“’, Sys.Net.WebServiceProxy);\r\n”); }
This method basically generates the following portion of the Listing 15-4 script: MyNamespace.Math.registerClass(‘MyNamespace.Math’, Sys.Net.WebServiceProxy);
GenerateStaticInstance This method generates the script that defines, instantiates, and initializes the _staticInstance property of the proxy class, as shown in the following excerpt from Listing 15-15: protected void GenerateStaticInstance() { this._builder.Append(this._serviceFullName); this._builder.Append(“._staticInstance = new “); this._builder.Append(this._serviceFullName); this._builder.Append(“();\r\n”); this._builder.Append(this._serviceFullName); this._builder.Append(“.set_path = function(value) { “); this._builder.Append(this._serviceFullName); this._builder.Append(“._staticInstance._path = value; }\r\n”);
This method basically generates the following portion of the Listing 15-4 script: MyNamespace.Math._staticInstance = new MyNamespace.Math(); MyNamespace.Math.set_path = function(value) { MyNamespace.Math._staticInstance._path = value; } MyNamespace.Math.get_path = function() {
GenerateStaticMethods This method generates the script that defines the static methods of the proxy class as shown in Listing 15-19 (which is the GenerateStaticMethods portion of Listing 15-15).
Listing 15-20 presents an example of the script that Listing 15-19 generates.
Listing 15-20: An Example of the Script that Listing 15-19 Generates MyNamespace.Math.Add = function(x, y, onSuccess, onFailed, userContext) { MyNamespace.Math._staticInstance.Add(x, y, onSuccess, onFailed, userContext); }
Using this listing as an example, let’s walk through the GenerateStaticMethods method in Listing 15-19. This method iterates through the MethodInfo objects in the _methodInfos collection and takes the following steps to generate the script that defines the static method associated with each enumerated MethodInfo object:
1.
It uses the name of the server method that the MethodInfo object represents as the name of the static method of the proxy class, prefixed by the full name of the service:
This generates a script such as the following portion of Listing 15-20: MyNamespace.Math.Add = function(
2.
It uses the names of the parameters of this server method as the names of the parameters of the associated static method of the proxy class: foreach (ParameterInfo pinfo in parameterList) { _builder.Append(pinfo.Name); _builder.Append(‘,’); }
This generates a script such as the following boldface portion of Listing 15-20: MyNamespace.Math.Add = function(x, y,
3.
It uses the following line of code: _builder.Append(“onSuccess, onFailed, userContext) \r\n{\r\n\t”);
to generate the following boldface portion of the Listing 15-20 script: MyNamespace.Math.Add = function(x, y, onSuccess, onFailed, userContext) {
4.
It uses the following lines of code: this._builder.Append(this._serviceFullName); this._builder.Append(“._staticInstance.”); this._builder.Append(methodInfo.Name); this._builder.Append(“(“);
to generate the following boldface portion of the Listing 15-20 script: MyNamespace.Math.Add = function(x, y, onSuccess, onFailed, userContext) { MyNamespace.Math._staticInstance.Add(
5.
It then iterates through the parameters of the enumerated method: foreach (ParameterInfo pinfo in parameterList) { _builder.Append(pinfo.Name); _builder.Append(‘,’); }
647
c15.indd 647
8/20/07 9:08:15 PM
Chapter 15: Proxy Classes to generate the following boldface portion of the Listing 15-20 script: MyNamespace.Math.Add = function(x, y, onSuccess, onFailed, userContext) { MyNamespace.Math._staticInstance.Add(x, y,
6.
It uses the following line of code: _builder.Append(“onSuccess, onFailed, userContext); \r\n};\r\n”);
to complete the Listing 15-20 script generation: MyNamespace.Math.Add = function(x, y, onSuccess, onFailed, userContext) { MyNamespace.Math._staticInstance.Add(x, y, onSuccess, onFailed, userContext); };
RestClientProxyHandler The previous chapter left out the discussion of the RestClientProxyHandler class used in the GetHandler method of the RestHandlerFactory class. As a matter of fact, the boldface portion of the following code was commented out in all the examples in that chapter: namespace CustomComponents { internal class RestHandlerFactory : IHttpHandlerFactory { public virtual IHttpHandler GetHandler(HttpContext context, string requestType, string url, string pathTranslated) { if (IsClientProxyRequest(context.Request.PathInfo)) return new RestClientProxyHandler(); return RestHandler.CreateHandler(context); } . . . } }
This boldfaced portion first invokes the IsClientProxyRequest method discussed in the previous chapter to determine whether the current request is a client proxy request. A client proxy request is a request that the client code makes to the server to download the release or debug version of the script that defines, instantiates, and initializes the proxy class. When and why would the client code make such a request? The answer depends on the value of the InlineScript property of the ServiceReference object that registers a service with the current ScriptManager server control. If you set this property to true, the ScriptManager server control will ask the current ASP.NET Page object to render the script that defines, instantiates, and initializes the proxy class directly into the page itself. In other words, when the requesting browser is downloading the current page for the first time, this script gets downloaded with the page because it is part of the page.
648
c15.indd 648
8/20/07 9:08:15 PM
Chapter 15: Proxy Classes If you set the InlineScript property to false, the ScriptManager server control will ask the current ASP.NET Page object to render a script block such as the following into the current page:
Note that the src attribute of this script element is set to a URL with path information trailer js or jsdebug. This triggers the requesting browser to make another request for the resource with the URL specified in the src attribute. When this request arrives in RestHandlerFactory and triggers the call into the GetHandler method as discussed in the previous chapter, the GetHandler method invokes the IsClientProxyRequest method, passing in the URL. As discussed in the previous chapter, this method searches the path information for the js or jsdebug trailer. If IsClientProxyRequest finds the trailer, it returns true and, consequently, triggers the GetHandler method to instantiate and return an instance of an ASP.NET class named RestClientProxyHandler. This class is responsible for generating the script that defines, instantiates, and initializes the proxy class, and returning this script to the requesting browser. Listing 15-21 presents the implementation of this replica RestClientProxyHandler class.
Listing 15-21: The RestClientProxyHandler Class using System; using System.Web; namespace CustomComponents { internal class RestClientProxyHandler : IHttpHandler { public void ProcessRequest(HttpContext context) { ClientProxyGenerator generator = new ClientProxyGenerator(); string script = generator.GetClientProxyScript(context.Request.FilePath, false); context.Response.ContentType = “application/x-javascript”; context.Response.Write(script); } public bool IsReusable { get { return false; } } } }
Like any other ASP.NET HTTP handler, the RestClientProxyHandler implements the IHttpHandler interface. RestClientProxyHandler implements this interface’s ProcessRequest method as follows:
1.
It instantiates a ClientProxyGenerator instance: ClientProxyGenerator generator = new ClientProxyGenerator();
649
c15.indd 649
8/20/07 9:08:15 PM
Chapter 15: Proxy Classes 2.
It invokes the GetClientProxyScript method on this instance to generate the script that defines, instantiates, and initializes the proxy class: string script = generator.GetClientProxyScript(context.Request.FilePath, false);
3.
It sets the Content-Type HTTP header to application/x-javascript to tell the requesting browser that the response contains JavaScript code:
It writes the script that defines, instantiates, and initializes the proxy class into the server output stream:
context.Response.Write(script);
Using the Replicas Follow these steps to see the replicas in action:
1. 2. 3.
Create an AJAX-enabled Web site in Visual Studio.
4.
Add a new source file named RestHandlerFactory.cs to the App_Code directory, and add the code shown in Listing 14-26 (located in the previous chapter) to this source file.
5.
Add a new source file named RestHandler.cs to the App_Code directory, and add the code shown in Listing 14-27 (located in the previous chapter) to this source file.
6.
Add a new source file named HandlerWrapper.cs to the App_Code directory, and add the code shown in Listing 14-28 (located in the previous chapter) to this source file.
7.
Add a new source file named ScriptModule.cs to the App_Code directory, and add the code shown in Listing 14-31 (located in the previous chapter) to this source file.
8.
Add a new source file named ScriptManager.cs to the App_Code directory, and add the code shown in Listing 15-12 (earlier in this chapter) to this source file.
9.
Add a new source file named ServiceReferenceCollection.cs to the App_Code directory, and add the code shown in Listing 15-13 (earlier in this chapter) to this source file.
10.
Add a new source file named ServiceReference.cs to the App_Code directory, and add the code shown in Listing 15-14 (earlier in this chapter) to this source file.
11.
Add a new source file named ClientProxyGenerator.cs to the App_Code directory, and add the code shown in Listing 15-15 (earlier in this chapter) to this source file.
12.
Add a new source file named RestClientProxyHandler.cs to the App_Code directory, and add the code shown in Listing 15-21 (located after this procedure) to this source file.
13.
Add a new Web form (.aspx file) named PageMethods.aspx, and add the code shown in Listing 15-22 (located after this procedure) to this .aspx file.
Add an App_Code directory to this Web site. Add a new source file named ScriptHandlerFactory.cs to the App_Code directory, and add the code shown in Listing 14-24 (located in the previous chapter) to this source file.
650
c15.indd 650
8/20/07 9:08:15 PM
Chapter 15: Proxy Classes 14.
Add a new Web form (.aspx file) named Math.aspx to the root directory of this Web site, and add the code shown in Listing 15-23 (located after this procedure) to this .aspx file.
15.
Add a new XML file named Math.asbx to the root directory of this Web site, and add the XML document shown in Listing 14-21 (located in the previous chapter).
16.
Add a new source file named Math.cs to the App_Code directory, and add the code shown in Listing 14-21 (located in the previous chapter) to this source file.
17.
Add a new Web form (.aspx file) named Math2.aspx to the root directory of this Web site, and add the code shown in Listing 15-24 (located after this procedure) to this .aspx file.
18.
Add a new Web service (.asmx) named Math.asmx to the root directory of this Web site, and add the code shown in Listing 14-19 (located in the previous chapter) to this .asmx file.
19.
In the web.config file, comment out the italicized lines shown in the following code, and add the boldface portion of the code (which is basically replacing the standard ASP.NET ScriptHandlerFactory and ScriptModule with the replica ScriptHandlerFactory and ScriptModule):
--> . . . --> . . .
651
c15.indd 651
8/20/07 9:08:16 PM
Chapter 15: Proxy Classes 20.
Run PageMethods.aspx, Math.aspx, and Math2.aspx, and you should see the same results you saw when you ran these pages with the standard ASP.NET ScriptHandlerFactory and ScriptModule. Feel free to play with the code to get a better understanding of the processing infrastructure of the ASP.NET AJAX REST method call request.
Listing 15-22: The PageMethods.aspx Page [WebMethod] public static double Divide(double x, double y) { if (y == 0) throw new DivideByZeroException(); return x / y; } Untitled Page var request; function onSuccess(result, userContext, methodName) { userContext.innerHTML = “” + result + “”; } function onFailure(result, userContext, methodName) { var builder = new Sys.StringBuilder(); builder.append(“timedOut: “); builder.append(result.get_timedOut()); builder.appendLine(); builder.appendLine(); builder.append(“message: “); builder.append(result.get_message()); builder.appendLine(); builder.appendLine(); builder.append(“stackTrace: “); builder.appendLine(); builder.append(result.get_stackTrace()); builder.appendLine(); builder.appendLine();
652
c15.indd 652
8/20/07 9:08:16 PM
Chapter 15: Proxy Classes builder.append(“exceptionType: “); builder.append(result.get_exceptionType()); builder.appendLine(); builder.appendLine(); builder.append(“statusCode: “); builder.append(result.get_statusCode()); builder.appendLine(); builder.appendLine(); builder.append(“methodName: “); builder.append(methodName); alert(builder.toString()); } function divide() { var xValue = $get(“firstNumber”).value; var yValue = $get(“secondNumber”).value; var userContext = $get(“result”); PageMethods.Divide(xValue, yValue, onSuccess, onFailure, userContext); }
Listing 15-24: The Math2.aspx Page Untitled Page var request; function onSuccess(result, userContext, methodName) { userContext.innerHTML = “ 0) { this.get_element().maxLength = this._maxLength; this._maxLength = null; } }
clearText As the name suggests, the clearText method clears the text from the associated text box DOM element of the TextBoxWatermarkBehavior. As you can see from Listing 16-30, this method takes a single Boolean argument that specifies whether the associated text box DOM element is grabbing the focus. As this code listing shows, the clearText method first invokes the get_element method to return a reference to the associated text box DOM element, and then sets its value property to an empty string to clear the text box: this.get_element().value = “”;
Next, the clearText method checks whether the associated text box DOM element is grabbing the focus. If so, it first calls the setAttribute method on the associated text box DOM element to turn off its autocomplete feature, to avoid a Firefox-specific NS_ERROR_XPC_JS_THREW_STRING error, and then
692
c16.indd 692
8/20/07 6:16:02 PM
Chapter 16: Behaviors calls the select method on the associated text box DOM element to ensure that the blinking cursor is displayed inside the text box on IE browsers: if(focusing) { // Avoid NS_ERROR_XPC_JS_THREW_STRING error in Firefox this.get_element().setAttribute(“autocomplete”,”off”); // This fix displays the blinking cursor in a focused, empty text box in IE this.get_element().select(); }
Listing 16-30: The clearText Method function AjaxControlToolkit$TextBoxWatermarkBehavior$clearText(focusing) { /// /// Clear the text from the target /// /// /// Whether or not we are focusing on the textbox /// this.get_element().value = “”; if(focusing) { // Avoid NS_ERROR_XPC_JS_THREW_STRING error in Firefox this.get_element().setAttribute(“autocomplete”,”off”); // This fix displays the blinking cursor in a focused, empty text box in IE this.get_element().select(); } }
_onBlur Recall from Listing 16-28 that the initialize method registers the _onBlur method as an event handler for the blur event of the associated text box DOM element of the TextBoxWatermarkBehavior. This DOM element fires this event and consequently invokes the _onBlur method when it loses focus. As you can see from Listing 16-31, this method first checks whether at least one of the following conditions is met:
❑
The value property of the associated text box DOM element is set to an empty string, which means that the text box is empty.
❑
The _watermarked flag of the TextBoxWatermarkBehavior is set to true to specify that the associated text box DOM element must be watermarked.
If either of these conditions is met, the _onBlur method takes the following actions. First, it checks whether the watermark text is longer than the maximum number of characters the associated text box DOM element can display. If so, it first stores the value of the maxLength property of the text box DOM
693
c16.indd 693
8/20/07 6:16:02 PM
Chapter 16: Behaviors element in a private field named _maxLength, and then assigns the length of the watermark text as the new value of this property. This ensures that the text box will display the entire watermark text: if (this.get_element().maxLength > 0 && this._watermarkText.length > this.get_element().maxLength) { this._maxLength = this.get_element().maxLength; this.get_element().maxLength = this._watermarkText.length; }
Finally, the _onBlur method invokes the _applyWatermark method on the TextBoxWatermarkBehavior to apply the watermark to the text box: this._applyWatermark();
Listing 16-31: the _onBlur Method function AjaxControlToolkit$TextBoxWatermarkBehavior$_onBlur() { /// /// Handle the textbox’s blur event /// if((“” == this.get_element().value) || this._watermarked) { // Enlarge the TextBox’s MaxLength if it’s not big enough // to accomodate the watermark if (this.get_element().maxLength > 0 && this._watermarkText.length > this.get_element().maxLength) { this._maxLength = this.get_element().maxLength; this.get_element().maxLength = this._watermarkText.length; } this._applyWatermark(); } }
_applyWatermark The main responsibility of the _applyWatermark method is to display the watermark. As Listing 16-32 shows, this method first assigns the watermark text to the value property of the associated text box DOM element to display the watermark text in the text box: this.get_element().value = this._watermarkText;
Next, it assigns the watermark CSS class name to the className property of the associated text box DOM element to apply the watermarked style to the text box: if(this._watermarkCssClass) this.get_element().className = this._watermarkCssClass;
694
c16.indd 694
8/20/07 6:16:02 PM
Chapter 16: Behaviors Finally, it sets the _watermarked flag to true to specify that the associated text box DOM element is watermarked: this._watermarked = true;
Listing 16-32: The _applyWatermark Method function AjaxControlToolkit$TextBoxWatermarkBehavior$_applyWatermark() { /// /// Apply the watermark to the textbox /// this.get_element().value = this._watermarkText; if(this._watermarkCssClass) this.get_element().className = this._watermarkCssClass; this._watermarked = true; }
_onKeyPress Recall from Listing 16-28 that the initialize method registers the _onKeyPress method as an event handler for the keypress event of the associated text box DOM element of the TextBoxWatermarkBehavior. This DOM element fires the keypress event when the user presses the key inside the text box. As you can see from Listing 16-33, this method simply sets the _watermarked flag to false to signal that the text box is no longer watermarked. Note that the text box automatically raises the focus event right after the keypress, consequently invoking the _onFocus method, which undisplays the watermark text and reverts the text box back to its unwatermarked style.
Listing 16-33 The _onKeyPress Method function AjaxControlToolkit$TextBoxWatermarkBehavior$_onKeyPress() { /// /// Handle the textbox’s keypress event /// this._watermarked = false; }
registerPropertyChanged Recall from Listing 16-28 that the initialize method invokes the registerPropertyChanged method. As you can see from Listing 16-34, this method first invokes the get_element method to return a reference to the associated text box DOM element of the TextBoxWatermarkBehavior: var e = this.get_element();
Next, it checks whether both of the following two conditions are met:
❑
The associated text box DOM element supports a property named control. This happens when the text box is associated with a Sys.Preview.UI.TextBox client control.
❑
The _propertyChangedHandler field is null.
695
c16.indd 695
8/20/07 6:16:02 PM
Chapter 16: Behaviors If both of these conditions are met, the registerPropertyChanged method first creates a delegate that represents the _onPropertyChanged method of the TextBoxWatermarkBehavior: this._propertyChangedHandler = Function.createDelegate(this, this._onPropertyChanged);
Next, it invokes the add_propertyChanged method on the Sys.Preview.UI.TextBox client control associated with the text box DOM element, to register the delegate as event handler for the propertyChanged event of the client control: e.control.add_propertyChanged(this._propertyChangedHandler);
Listing 16-34: The registerPropertyChanged Method function AjaxControlToolkit$TextBoxWatermarkBehavior$registerPropertyChanged() { /// /// Method called to hook up to Sys.Preview.UI.TextBox if present /// Note: This method must be called manually if the Sys.Preview.UI.TextBox /// is added after the TextBoxWatermarkBehavior is initialized. /// var e = this.get_element(); if(e.control && !this._propertyChangedHandler) { this._propertyChangedHandler = Function.createDelegate(this, this._onPropertyChanged); e.control.add_propertyChanged(this._propertyChangedHandler); } }
_onPropertyChanged When the Sys.Preview.UI.TextBox client control associated with the associated text box DOM element of the TextBoxWatermarkBehavior raises its propertyChanged event, it automatically invokes the _onPropertyChanged method on the TextBoxWatermarkBehavior, passing in two parameters. The first parameter references the Sys.Preview.UI.TextBox client control that raises the propertyChanged event, and the second parameter references the propertyChangedEventArgs object that contains the event data for the propertyChanged event. As you can see from Listing 16-35, the _onPropertyChanged method invokes the get_propertyName method of the propertyChangedEventArgs object to return the name of the property of the Sys.Preview.UI.TextBox client control whose value has changed, and then determines whether this property is the Text property. If so, it invokes the set_Text method on the TextBoxWatermarkBehavior to set the value of its Text property to the value of the value property of its associated text box DOM element. As you can see, the Text property of the TextBoxWatermarkBehavior maps to the value property of its associated text box DOM element: if(“text” == propertyChangedEventArgs.get_propertyName()) this.set_Text(this.get_element().value);
696
c16.indd 696
8/20/07 6:16:03 PM
Chapter 16: Behaviors Listing 16-35: The _onPropertyChanged Method function AjaxControlToolkit$TextBoxWatermarkBehavior$_onPropertyChanged(sender, propertyChangedEventArgs) { /// /// Handler called automatically when a property change event is fired /// /// /// Sender /// /// /// Event arguments /// if(“text” == propertyChangedEventArgs.get_propertyName()) this.set_Text(this.get_element().value); }
set_Text As mentioned earlier, the TextBoxWatermarkBehavior class features a property named Text that maps into the value property of its associated text box DOM element. Because of this, the class also exposes a setter named set_Text (see Listing 16-36) and a getter named get_Text (see Listing 16-37) that you can use in your client code to set and get the value of the Text property. As you can see from Listing 16-36, the set_Text method first checks whether the new value of the Text property is an empty string. If so, it performs the following tasks:
❑
Assigns the empty string as the value of the value property of the associated text box DOM element, which means that the text box now displays nothing: this.get_element().value = “”;
❑
Invokes the blur method on the associated text box DOM element to cause the text box to lose focus: this.get_element().blur();
❑
Invokes the _onBlur method on the TextBoxWatermarkBehavior. This is necessary because calling the blur method on the associated text box DOM element does not cause the text box to fire its blur event, and therefore does not cause the _onBlur method to be automatically invoked: this._onBlur();
If the new value of the Text property is not an empty string, the set_Text method performs the following tasks:
❑
Invokes the _onFocus method on the TextBoxWatermarkBehavior:
this._onFocus();
// onFocus sets “”
697
c16.indd 697
8/20/07 6:16:03 PM
Chapter 16: Behaviors ❑
Assigns the new value to the value property of the associated text box DOM element: this.get_element().value = value;
Listing 16-36: The set_Text Method function AjaxControlToolkit$TextBoxWatermarkBehavior$set_Text(value) { if (“” == value) { this.get_element().value = “”; this.get_element().blur(); this._onBlur(); // onBlur needs to see “” } else { this._onFocus(); // onFocus sets “” this.get_element().value = value; } }
Here is the reason the TextBoxWatermarkBehavior wraps the value property of its associated text box DOM element in its Text property. As Listing 16-37 shows, the get_Text getter method returns an empty string if the text box element, rather than the actual value of the element, is watermarked. Recall that when the text box is watermarked, its value property contains the watermark text. This ensures that the clients of the TextBoxWatermarkBehavior always receive the value that the end user enters into the text box, rather than the watermark text.
Listing 16-37: The get_Text Method function AjaxControlToolkit$TextBoxWatermarkBehavior$get_Text() { /// /// Wrapper for the textbox’s text that will ignore or create the /// watermark as appropriate /// return (this._watermarked ? “” : this.get_element().value); }
_partialUpdateEndRequest Recall from Listing 16-28 that the initialize method of the TextBoxWatermarkBehavior invokes the registerPartialUpdateEvents method that it inherits from the BehaviorBase base class. Also recall that the registerPartialUpdateEvents method registers the _partialUpdateEndRequest method as an event handler for the endRequest event of the current client-side PageRequestManager instance. As you can see, if a subclass of the BehaviorBase base class needs to run custom code when the current PageRequestManager instance raises its beginRequest and endRequest events, the subclass must takes two actions. First, it must invoke the registerPartialUpdateEvents method from its initialize method. Second, it must override the _partialUpdateBeginRequest and/or _partialUpdateEndRequest methods to encapsulate the custom code.
698
c16.indd 698
8/20/07 6:16:03 PM
Chapter 16: Behaviors Since the TextBoxWatermarkBehavior is interested only in the endRequest event of the current client-side PageRequestManager instance, it overrides only the _partialUpdateEndRequest method that it inherits from the BehaviorBase base class, leaving the _partialUpdateBeginRequest method intact. Listing 16-38 contains the TextBoxWatermarkBehavior class’s implementation of the _ partialUpdateEndRequest method. When the current client-side PageRequestManager instance finally fires its endRequest event and consequently invokes the _partialUpdateEndRequest method, it passes two parameters into this method. The first references the current client-side PageRequestManager instance, and the second references the EndRequestEventArgs object that contains the event data for the current endRequest event. As you can see from Listing 16-38, the _partialUpdateEndRequest method first invokes the partialUpdateEndRequest method of its base class, passing the aforementioned two parameters: AjaxControlToolkit.TextBoxWatermarkBehavior.callBaseMethod(this, ‘_partialUpdateEndRequest’, [sender, endRequestEventArgs]);
In general, every time your ASP.NET AJAX class overrides the methods it inherits from its base class, its implementation of these methods must invoke the respective methods of the base class unless you have a good reason to stop the base method from running. Next, the _partialUpdateEndRequest method checks whether an internal flag named _clearedForSubmit has been set. As you’ll see in next section, the _onSubmit method of the TextBoxWatermarkBehavior sets this flag to signal the occurrence of a form submission. Since the _partialUpdateEndRequest method is invoked in response to the endRequest event of the current client-side PageRequestManager instance, and since this event is raised after an asynchronous form submission occurs and the server response arrives, it makes lot of sense to apply the watermark to the text box. To do this, the _partialUpdateEndRequest method first invokes the blur method on text box element, to cause the element to lose focus: this.get_element().blur();
Then it invokes the _onBlur method on the TextBoxWatermarkBehavior. This is necessary because the blur method does not raise the blur event and consequently does not automatically invoke the _onBlur method: this._onBlur();
Listing 16-38: The _partialUpdateEndRequest Method function AjaxControlToolkit$TextBoxWatermarkBehavior$_partialUpdateEndRequest( sender, endRequestEventArgs) { /// /// Handler Called automatically when a partial postback ends /// /// /// Sender ///
(continued)
699
c16.indd 699
8/20/07 6:16:04 PM
Chapter 16: Behaviors Listing 16-38 (continued) /// /// Event arguments /// AjaxControlToolkit.TextBoxWatermarkBehavior.callBaseMethod(this, ‘_partialUpdateEndRequest’, [sender, endRequestEventArgs]); if (this.get_element() && this._clearedForSubmit) { // Restore the cleared watermark (useful when the submit was // wrapped in an UpdatePanel) this.get_element().blur(); this._onBlur(); this._clearedForSubmit = false; } }
_onSubmit The TextBoxWatermarkBehavior does not invoke its _onSubmit method. It is the responsibility of the client code that uses the TextBoxWatermarkBehavior to ensure that the _onSubmit method is invoked before the form is submitted. As you can see from Listing 16-39, this method checks whether the associated text box DOM element of the TextBoxWatermarkBehavior is watermarked. If so, it invokes the clearText method to clear the text box before the form is submitted. This ensures that the watermark text is not submitted to the server.
Listing 16-39: The _onSubmit Method function AjaxControlToolkit$TextBoxWatermarkBehavior$_onSubmit() { /// /// Handler Called automatically when a submit happens to clear the /// watermark before posting back /// if(this._watermarked) { // Clear watermark text before page is submitted this.clearText(false); this._clearedForSubmit = true; } }
dispose The TextBoxWatermarkBehavior, like any other ASP.NET AJAX component, inherits the dispose method from the Component base class and overrides it to perform its final cleanup before the Application object representing the current ASP.NET AJAX application disposes of it. As you can see from Listing 16-40, the dispose method first invokes the get_element method to return a reference to the DOM element to which the TextBoxWatermarkBehavior is attached. As discussed earlier, this DOM element is a text box. The TextBoxWatermarkBehavior, like any other behavior, inherits the get_element method from the Behavior base class: var e = this.get_element();
700
c16.indd 700
8/20/07 6:16:04 PM
Chapter 16: Behaviors Next, the dispose method checks whether the following two conditions hold:
❑
The associated text box DOM element exposes a property named control. This is true if the associated text box DOM element is itself associated with an instance of a Sys.Preview.UI.TextBox control. Recall that the Control base class under the hood creates a custom property named control on the DOM element associated with a client control, and assigns a reference to the client control (in this case the Sys.Preview.UI.TextBox control) to this custom control property.
❑
The _propertyChangedHandler delegate has been defined.
If both of these conditions are met, the dispose method invokes the remove_propertyChangedHandler method on the custom control property of the associated text box DOM element, to remove the _propertyChangedHandler delegate from the list of event handlers registered for the propertyChanged event of the Sys.Preview.UI.TextBox client control associated with the text box DOM element. if(e.control && this._propertyChangedHandler) { e.control.remove_propertyChanged(this._propertyChangedHandler); this._propertyChangedHandler = null; }
Next, it uses the $removeHandler global JavaScript function to remove the _focusHandler, _blurHandler, and _keyPressHandler delegates from the list of event handlers registered for focus, blur, and keypress events of the associated text box DOM element. Then it invokes the clearText method on the TextBoxWatermarkBehavior to clear the watermark: if(this._watermarked) this.clearText(false);
Listing 16-40: The dispose Method of the TextBoxWatermarkBehavior function AjaxControlToolkit$TextBoxWatermarkBehavior$dispose() { /// /// Dispose the behavior /// var e = this.get_element(); // Unhook from Sys.Preview.UI.TextBox if present if(e.control && this._propertyChangedHandler) { e.control.remove_propertyChanged(this._propertyChangedHandler); this._propertyChangedHandler = null; } // Detach events if (this._focusHandler) { $removeHandler(e, ‘focus’, this._focusHandler); this._focusHandler = null; }
(continued)
701
c16.indd 701
8/20/07 6:16:04 PM
Chapter 16: Behaviors Listing 16-40 (continued) if (this._blurHandler) { $removeHandler(e, ‘blur’, this._blurHandler); this._blurHandler = null; } if (this._keyPressHandler) { $removeHandler(e, ‘keypress’, this._keyPressHandler); this._keyPressHandler = null; } // Clear watermark text to avoid confusion during Refresh/Back/Forward if(this._watermarked) this.clearText(false); AjaxControlToolkit.TextBoxWatermarkBehavior.callBaseMethod(this, ‘dispose’); }
WatermarkText The TextBoxWatermarkBehavior exposes a getter named get_WatermarkText and a setter named set_WatermarkText that you can use in your client code to get and set the watermark text, as shown in Listing 16-41.
Listing 16-41: The WatermarkText Property function AjaxControlToolkit$TextBoxWatermarkBehavior$get_WatermarkText() { /// /// The text to show when the control has no value /// return this._watermarkText; } function AjaxControlToolkit$TextBoxWatermarkBehavior$set_WatermarkText(value) { if (this._watermarkText != value) { this._watermarkText = value; if (this._watermarked) this._applyWatermark(); this.raisePropertyChanged(‘WatermarkText’); } }
WatermarkCssClass The TextBoxWatermarkBehavior exposes a getter named get_WatermarkCssClass and a setter named set_WatermarkCssClass that you can use in your client code to get and set the watermark style, as shown in Listing 16-42.
702
c16.indd 702
8/20/07 6:16:05 PM
Chapter 16: Behaviors Listing 16-42: The WatermarkCssClass Property function AjaxControlToolkit$TextBoxWatermarkBehavior$get_WatermarkCssClass() { /// /// The CSS class to apply to the TextBox when it has no value (e.g. the /// watermark text is shown). /// return this._watermarkCssClass; } function AjaxControlToolkit$TextBoxWatermarkBehavior$set_WatermarkCssClass(value) { if (this._watermarkCssClass != value) { this._watermarkCssClass = value; if (this._watermarked) this._applyWatermark(); this.raisePropertyChanged(‘WatermarkCssClass’); } }
Using the TextBoxWatermarkBehavior Listing 16-43 contains a page that uses the TextBoxWatermarkBehavior. Takes these steps to run this page:
1. 2.
Create an Ajax-enable website in Visual Studio Add a JavaScript file named BehaviorBase.js to this website and add the code shown in Listings 16-19 through 16-26 to this JavaScript file.
3.
Add a JavaScript file named TextBoxWatermarkBehavior.js to this website and add the code shown in Listings 16-27 through 16-43 to this JavaScript file
4.
Add the following line at the beginning of both JavaScript files: Type.registerNamespace(‘AjaxControlToolkit’);
5.
Add the following line at the end of both JavaScript files: if (typeof(Sys) !== ‘undefined’) Sys.Application.notifyScriptLoaded();
6.
Add a Web Form named Default.aspx to this website and add the code shown in Listing 16-44 to the Default.aspx file
If you access the Default.aspx page for your browser, you should see that the associated text box DOM element of the TextBoxWatermarkBehavior is watermarked — that is, that it displays the watermark text and is styled with the watermarked style. If you click this text box, it will revert to its unwatermarked style when it grabs the focus, enabling you to enter new text. If you click the Submit button to submit the form, the watermark text disappears from the text box. This ensures that the watermark text is not submitted to the server.
703
c16.indd 703
8/20/07 6:16:05 PM
Chapter 16: Behaviors Listing 16-43: A Page that Uses the TextBoxWatermarkBehavior void ClickCallback(object sender, EventArgs e) { Info.Text = TextBox1.Text; } Untitled Page .WatermarkCssClass { background-color: #dddddd } var textBoxWatermarkBehavior; function submitCallback() { textBoxWatermarkBehavior._onSubmit(); } function pageLoad() { var properties = {name : “MyTextBoxWatermarkBehaviorName”, id : “MyTextBoxWatermarkBehaviorID”, WatermarkText : “Enter text here”, WatermarkCssClass : “WatermarkCssClass”}; var textBox1 = $get(“TextBox1”); textBoxWatermarkBehavior = $create(AjaxControlToolkit.TextBoxWatermarkBehavior, properties, null, null, textBox1); }
704
c16.indd 704
8/20/07 6:16:05 PM
Chapter 16: Behaviors
I’ll walk you through the code shown in Listing 16-43. First, notice that this page contains a CSS class named WatermarkCssClass, which defines the watermarked style: .WatermarkCssClass { background-color: #dddddd }
Also note that this page registers references to two JavaScript files named BehaviorBase.js and TextBoxWatermarkBehavior.js:
These two JavaScript files contain the implementation of the BehaviorBase and TextBoxWatermarkBehavior client classes, respectively. (You can find the complete code for these two classes in the sections of this chapter where we discussed their implementation.) Don’t forget to include the following definition at the beginning these two files: Type.registerNamespace(“AjaxControlToolkit”);
Also don’t forget to include the following script at the event of these two files: if(typeof(Sys)!==’undefined’) Sys.Application.notifyScriptLoaded();
As Listing 16-43 shows, the pageLoad method performs the following tasks. First, it instantiates a dictionary named properties and populates it with the names and values of the properties of the TextBoxWatermarkBehavior: var properties = []; properties[“name”] = “MyTextBoxWatermarkBehaviorName”; properties[“id”] = “MyTextBoxWatermarkBehaviorID”; properties[“WatermarkText”] = “Enter text here”; properties[“WatermarkCssClass”] = “WatermarkCssClass”;
Next, it uses the $get global JavaScript function to return a reference to the text box DOM element to which we want to attach the TextBoxWatermarkBehavior we’re about to create: var textBox1 = $get(“TextBox1”);
705
c16.indd 705
8/20/07 6:16:05 PM
Chapter 16: Behaviors Finally, it invokes the $create global JavaScript function, passing in five parameters. The first parameter references the constructor of the TextBoxWatermarkBehavior, the second references the dictionary that contains the names and values of the properties of the TextBoxWatermarkBehavior object being instantiated, the third and forth are null, and the last references the text box DOM element to which the TextBoxWatermarkBehavior being instantiated attaches. The $create method instantiates the TextBoxWatermarkBehavior, initializes its properties with the values specified in the properties dictionary, invokes its initialize method, and finally adds it to the current ASP.NET AJAX application. textBoxWatermarkBehavior = $create(AjaxControlToolkit.TextBoxWatermarkBehavior, properties, null, null, textBox1);
As Listing 16-43 shows, the page also registers an event handler named submitCallback for the submit event of the form. As you can see, this event handler invokes the _onSubmit method on the TextBoxWatermarkBehavior to remove the watermark text from the text box before the form is submitted to the server: function submitCallback() { textBoxWatermarkBehavior._onSubmit(); }
Summar y This chapter provided you with in-depth coverage of the ASP.NET AJAX behaviors and helped you gain the experience you need to develop your own custom behaviors. The next chapter will show you how to develop ASP.NET server controls that take full advantage of the ASP.NET AJAX behaviors.
706
c16.indd 706
8/20/07 6:16:05 PM
Script and Extender Ser ver Controls In this chapter, I’ll implement fully functional replicas of those components of the ASP.NET AJAX server-side Framework that are deeply involved in the internal functioning of two important types of server controls, known as script controls and extender controls, to help you gain a solid understanding of these server controls, how they interact with their associated client-side components, how they differ from one another, and how to implement your own custom script controls and extender controls. These components of the ASP.NET AJAX server side Framework include:
❑
IExtenderControl
❑
ExtenderControl
❑
IScriptControl
❑
ScriptControl
❑
ScriptDescriptor
❑
ScriptComponentDescriptor
❑
ScriptBehaviorDescriptor
❑
ScriptControlDescriptor
❑
ScriptReference
❑
ScriptReferenceCollection
❑
ScriptManager
Why You Need Script and Extender Ser ver Controls Let us revisit Listing 16-64. Recall that this code listing contains a page that uses the TextBoxWatermarkBehavior. As this code listing demonstrates, page developers must write quite a bit of JavaScript code to use the TextBoxWatermarkBehavior in their applications.
c17.indd 707
8/20/07 6:29:52 PM
Chapter 17: Script and Extender Server Controls If you could encapsulate the TextBoxWatermarkBehavior and the JavaScript code that instantiates and initializes this behavior, attaches this behavior to its associated DOM element, and adds this behavior to the current ASP.NET AJAX application in a server control, you would provide the clients of your server control with the following important benefits:
❑
This server control could be used declaratively without writing a single line of imperative code such as C#, VB.NET, or JavaScript.
❑
It could be added to the Toolbox of the Visual Studio to allow page developers to drag and drop it on the designer surface.
❑
It could be programmed against by means of the ASP.NET Framework. This would allow page developers to take full advantage of the well-known benefits of programming in the .NET environment.
❑
The C#/VB.NET/JavaScript code encapsulated in this server control could be changed to fix a bug, to optimize the code, or to add a new enhancement without breaking the applications that use this server control — as long as these changes do not affect the API through which these applications interact with this server control.
❑
Since the entire logic that defines, instantiates, and initializes the TextBoxWatermarkBehavior, attaches it to its associated DOM element, and adds it to the current ASP.NET AJAX application is encapsulated in a single component (that is, the server control), you could perform any required bug fixes, code optimizations, and enhancements in a single component and rest assured that these changes will be automatically picked up by all applications that use this server control.
The ASP.NET AJAX Framework provides you with two different approaches to encapsulating the logic that performs the following tasks in a server control:
❑
Defines an ASP.NET AJAX component such as TextBoxWatermarkBehavior.
❑
Instantiates this component.
❑
Initializes this component. (This initialization involves initializing the properties of the component and registering event handlers for its events.)
❑
Attaches this component to a DOM element.
❑
Adds this component to the current ASP.NET AJAX application.
These two approaches are as follows:
❑
Script Controls: This approach encapsulates the logic I just mentioned in a server control that represents the associated DOM element of the ASP.NET AJAX component. For example, in the case of Listing 16-64, the associated DOM element of the TextBoxWatermarkBehavior is a text box. As you’ll see later in this chapter, you’ll develop a custom TextBox server control named TextBoxWatermarkScriptControl that derives from the ASP.NET TextBox server control to encapsulate the preceding logic. As you can see, this script server control represents the associated DOM text box element of the TextBoxWatermarkBehavior.
❑
Extender Controls: This approach encapsulates the logic I just mentioned in a server control that attaches to the server control that represents the associated DOM element of the ASP.NET AJAX component. For example, in the case of Listing 16-64, the associated DOM element of the
708
c17.indd 708
8/20/07 6:29:53 PM
Chapter 17: Script and Extender Server Controls TextBoxWatermarkBehavior is a text box. Later in this chapter we’ll develop an extender server control named TextBoxWatermarkExtenderControl to encapsulate this logic. As you can see, this extender server control does not represent the associated DOM text box element of the TextBoxWatermarkBehavior. Instead it attaches to the server control that represents this associated element — that is, the ASP.NET TextBox server control.
In other words, while the TextBoxWatermarkScriptControl derives from the ASP.NET TextBox server control, the TextBoxWatermarkExtenderControl attaches to the ASP.NET TextBox server control instead of deriving from it. This will all be made clear later in this chapter.
Extender Ser ver Controls An extender server control is an ASP.NET server control that allows you to extend the client-side functionality of an existing ASP.NET server control without touching its code! The ASP.NET server control whose client-side functionality is being extended is completely oblivious to the presence of the extender control. This is a great way to enhance the client-side behavior of an existing ASP.NET server control.
IExtenderControl Every ASP.NET extender server control implements an interface named IExtenderControl, defined in Listing 17-1.
Listing 17-1: The IExtenderControl Interface using System; using System.Web.UI; using System.Collections.Generic; namespace CustomComponents3 { public interface IExtenderControl { IEnumerable GetScriptDescriptors(Control targetControl); IEnumerable GetScriptReferences(); } }
As you can see, the IExtenderControl interface exposes the following two methods:
❑
GetScriptDescriptors: This method takes a parameter of type Control that references the
ASP.NET server control whose client-side functionality the current extender server control extends. The main responsibility of this method is to instantiate, initialize, and return an IEnumerable collection of the ScriptDescriptor objects, where each ScriptDescriptor object generates the client script that instantiates and initializes an ASP.NET AJAX component such as the TextBoxWatermarkBehavior, attaches it to its associated DOM element, and adds it to the current ASP.NET AJAX application.
709
c17.indd 709
8/20/07 6:29:53 PM
Chapter 17: Script and Extender Server Controls ❑
GetScriptReferences: The main responsibility of this method is to instantiate, initialize, and return an IEnumerable collection of the ScriptReference objects where each ScriptReference object references a JavaScript file that normally defines an ASP.NET AJAX component such as the TextBoxWatermarkBehavior or any other required JavaScript code.
ExtenderControl The ASP.NET AJAX Framework comes with an implementation of the IExtenderControl interface named ExtenderControl. Listing 17-2 presents the implementation of the replica ExtenderControl. This base class contains the base functionality that every extender server control must support. Deriving your extender server controls from the ExtenderControl base class will save you from having to implement this base functionality every time you develop a custom extender server control.
Listing 17-2: The ExtenderControl Base Class namespace CustomComponents3 { using System; using System.Web.UI; using System.ComponentModel; using System.Collections.Generic; [DefaultProperty(“TargetControlID”), ParseChildren(true), NonVisualControl, PersistChildren(false)] public abstract class ExtenderControl : Control, IExtenderControl { private ScriptManager _scriptManager; private string _targetControlID; protected abstract IEnumerable GetScriptDescriptors( Control targetControl); protected abstract IEnumerable GetScriptReferences(); protected override void OnPreRender(EventArgs e) { base.OnPreRender(e); Control control = this.FindControl(this.TargetControlID); ScriptManager scriptManager = ScriptManager.GetCurrent(Page); scriptManager.RegisterExtenderControl(this, control); } protected override void Render(HtmlTextWriter writer) { base.Render(writer); if (!base.DesignMode) { ScriptManager mgr = ScriptManager.GetCurrent(Page); mgr.RegisterScriptDescriptors(this); } }
710
c17.indd 710
8/20/07 6:29:53 PM
Chapter 17: Script and Extender Server Controls IEnumerable IExtenderControl.GetScriptDescriptors( Control targetControl) { return this.GetScriptDescriptors(targetControl); } IEnumerable IExtenderControl.GetScriptReferences() { return this.GetScriptReferences(); } [DefaultValue(“”), IDReferenceProperty, Category(“Behavior”)] public string TargetControlID { get { if (this._targetControlID != null) return this._targetControlID; return string.Empty; } set { this._targetControlID = value; } } [Browsable(false), DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden), EditorBrowsable(EditorBrowsableState.Never)] public override bool Visible { get { return base.Visible; } set { throw new NotImplementedException(); } } } }
As Listing 17-2 shows, the ExtenderControl implements the GetScriptDescriptors and GetScriptReferences methods of the IExtenderControl interface. The implementations of these two methods simply delegate to two virtual methods with the same names. This is a typical C# interface implementation pattern, where a class’s explicit implementation of the methods, properties, and events of an interface simply delegates to protected virtual methods, properties, and events with the same names as the methods, properties, and events of the interface. This provides two important benefits. First, it saves the subclasses of the class from explicitly implementing the interface. Second, it allows these subclasses to override these protected virtual methods, properties, and events to provide their own implementations. This is a great interface implementation pattern that you should use in your own custom classes. Note that the protected virtual GetScriptDescriptors and GetScriptReferences methods of the ExtenderControl base class are marked as abstract. This means that all subclasses of this base class must implement these two methods.
711
c17.indd 711
8/20/07 6:29:54 PM
Chapter 17: Script and Extender Server Controls As Listing 17-2 shows, the ExtenderControl base class exposes a read/write string property named TargetControlID that specifies the ID property value of the server control whose client-side functionality the extender control extends. This server control is known as the target control of the extender control. For example, in the case of the TextBoxWatermarkExtenderControl extender control, which will be implemented later in this chapter, the target server control is the ASP.NET TextBox server control whose functionality this extender control extends. [DefaultValue(“”), IDReferenceProperty, Category(“Behavior”)] public string TargetControlID { get { if (this._targetControlID != null) return this._targetControlID; return string.Empty; } set { this._targetControlID = value; } }
As you can see from Listing 17-2, the ExtenderControl base class derives from the ASP.NET Control base class and overrides the OnPreRender and Render methods that it inherits from the Control class. Next, I’ll walk you through the ExtenderControl base class’s implementation of these two methods. The OnPreRender method begins by invoking the OnPreRender method of its base class — that is, the Control base class. The OnPreRender method of the Control base class raises the PreRender event and consequently invokes all the event handlers registered for this event. base.OnPreRender(e);
If you need to run some code when an extender server control such as TextBoxWatermarkExtenderControl enters its PreRender lifecycle phase, you must encapsulate this code in a method and register the method as an event handler for the PreRender event of the extender server control. Next, the OnPreRender method of the ExtenderControl base class invokes the FindControl method, passing in the ID property value of the target server control (recall that the target server control of an extender control is the server control whose client-side functionality the extender control is extending) to return a reference to this server control. Control control = this.FindControl(this.TargetControlID);
Then, the OnPreRender method of the ExtenderControl base class invokes the GetCurrent static method on the replica ScriptManager to return a reference to the current replica ScriptManager server control: ScriptManager scriptManager = ScriptManager.GetCurrent(Page);
Next, the method invokes the RegisterExtenderControl method on the current ScriptManager server control to register the current extender control as the extender control for the specified target
712
c17.indd 712
8/20/07 6:29:54 PM
Chapter 17: Script and Extender Server Controls control. As you’ll see later, the RegisterExtenderControl method adds the specified extender server control to an internal collection. scriptManager.RegisterExtenderControl(this, control);
Next, I’ll walk you through the ExtenderControl base class’s implementation of the Render method that it inherits from the Control base class. This method begins by calling the Render method of the base class. The Render method of the Control base class iterates through the child controls of the extender control and invokes their RenderControl method to allow them to render themselves. base.Render(writer);
The Render method of the ExtenderControl base class then calls the GetCurrent static method on the replica ScriptManager class to return a reference to the current replica ScriptManager server control: ScriptManager mgr = ScriptManager.GetCurrent(Page);
Next, the method calls the RegisterScriptDescriptors method on the current replica ScriptManager server control to allow the extender control to register all the required client scripts for rendering. mgr.RegisterScriptDescriptors(this);
Script Ser ver Controls As the name suggests, an extender server control such as TextBoxWatermarkExtenderControl extends the client-side functionality of an existing ASP.NET server control such as TextBox. A script server control, such as TextBoxWatermarkScriptControl, on the other hand, extends the client-side functionality of an exiting ASP.NET server control such as TextBox if it derives from that server control. Otherwise a script server control can be a brand-new server control on its own.
IScriptControl All ASP.NET AJAX script server controls implement an interface named IScriptControl, defined in Listing 17-3. As you can see, the IScriptControl interface exposes two methods:
❑
GetScriptDescriptors: The GetScriptDescriptors method of the IScriptControl interface plays the same role in a script server control that the GetScriptDescriptors method of the IExtenderControl plays in an extender server control. Recall that the GetScriptDescriptors method of the IExtenderControl interface takes a parameter of type Control that references the target server control of the extender server control. The target
server control is the server control whose client-side functionality the specified extender server control extends. However, as Listing 17-3 shows, the GetScriptDescriptors method of the IScriptControl interface does not take this parameter. This is because the script server control that extends the client-side functionality of an existing ASP.NET server control directly derives from that server control; consequently there is no need for this parameter because it references the script server control itself. To put it differently, a script server control is its own target server control.
713
c17.indd 713
8/20/07 6:29:54 PM
Chapter 17: Script and Extender Server Controls ❑
GetScriptReferences: The GetScriptReferences method of the IScriptControl interface plays the same role in a script server control that the GetScriptReferences method of the IExtenderControl plays in an extender server control. In other words, the GetScriptReferences method returns an IEnumerable collection of ScriptReference objects in which each ScriptReference object references a JavaScript file that contains the
JavaScript code that supports the client-side functionality of the script server control, such as the definition of an ASP.NET AJAX component associated with the script server control.
Listing 17-3: The IScriptControl using System.Collections.Generic; namespace CustomComponents3 { public interface IScriptControl { IEnumerable GetScriptDescriptors(); IEnumerable GetScriptReferences(); } }
ScriptControl As you saw in the previous section, the ASP.NET AJAX Framework comes with an implementation of the IExtenderControl interface named ExtenderControl. As I mentioned, the ExtenderControl base class contains the base functionality that every extender server control must implement. Because of this, you should derive your custom extender server controls from the ExtenderControl base class to save yourself from having to implement this base functionality every time you develop an extender server control. Similarly, the ASP.NET AJAX Framework comes with an implementation of the IScriptControl interface, named ScriptControl, which contains the base functionality that every script server control must implement. Therefore, deriving your custom script server controls from the ScriptControl base class saves you from having to implement this base functionality every time you develop a script server control. That said, there are times when you cannot derive your script server control from the ScriptControl base class, and consequently you have to re-implement this base functionality. This happens when you’re implementing a custom script server control that is required to derive from an existing ASP.NET server control. For example, as you’ll see later, the TextBoxWatermarkScriptControl script server control derives from the ASP.NET TextBox server control and extends its client-side functionality. In these situations, you cannot derive from the ScriptControl server control because the object-oriented programming languages such as C# and VB.NET do not allow multiple inheritances. Therefore, your custom script control has no choice but to explicitly implement the IScriptControl interface, where it must basically do the same thing that the ScriptControl base class does. Listing 17-4 presents the implementation of our replica ScriptControl base class. Note that this base class follows the typical C# interface implementation pattern to implement the GetScriptDescriptors and GetScriptReferences methods of the IScriptControl base class, where it exposes two protected virtual methods with the same names as the methods of the interface. Note also that the ScriptControl base class marks these two protected virtual methods as abstract, to require its subclasses to implement these two methods.
714
c17.indd 714
8/20/07 6:29:54 PM
Chapter 17: Script and Extender Server Controls Listing 17-4: The ScriptControl Base Class namespace CustomComponents3 { using System; using System.Web.UI; using System.Collections.Generic; using System.Web.UI.WebControls; public abstract class ScriptControl : WebControl, IScriptControl { protected abstract IEnumerable GetScriptDescriptors(); protected abstract IEnumerable GetScriptReferences(); protected override void OnPreRender(EventArgs e) { base.OnPreRender(e); ScriptManager scriptManager = ScriptManager.GetCurrent(Page); scriptManager.RegisterScriptControl(this); } protected override void Render(HtmlTextWriter writer) { base.Render(writer); if (!base.DesignMode) { ScriptManager scriptManager = ScriptManager.GetCurrent(Page); scriptManager.RegisterScriptDescriptors(this); } } IEnumerable IScriptControl.GetScriptDescriptors() { return this.GetScriptDescriptors(); } IEnumerable IScriptControl.GetScriptReferences() { return this.GetScriptReferences(); } } }
As Listing 17-4 shows, the ScriptControl base class derives from the WebControl base class and overrides its OnPreRender and Render methods. Next, I’ll walk you through the ScriptControl base class’s implementation of the OnPreRender method. As you can see, this method begins by invoking the OnPreRender method of its base class to raise the PreRender event and consequently to invoke the event handlers registered for this event: base.OnPreRender(e);
715
c17.indd 715
8/20/07 6:29:55 PM
Chapter 17: Script and Extender Server Controls If you need to run some custom code when a script server control such as TextBoxWatermarkScriptControl enters its PreRender life-cycle phase, you must encapsulate this code in a method and register the method as event handler for the PreRender event of the script server control. Next, it calls the GetCurrent static method on our replica ScriptManager class to return a reference to the current replica ScriptManager server control: ScriptManager scriptManager = ScriptManager.GetCurrent(Page);
Finally, it calls the RegisterScriptControl method on the current replica ScriptManager server control to register the script server control. scriptManager.RegisterScriptControl(this);
Next, I’ll walk you through the implementation of the Render method. As you can see from Listing 17-4, this method first invokes the Render method of its base class, which in turn invokes the RenderControl method of the child controls of the script server control. base.Render(writer);
Next, it calls the GetCurrent static method on our replica ScriptManager class to return a reference to the current replica ScriptManager server control: ScriptManager scriptManager = ScriptManager.GetCurrent(Page);
Finally, it calls the RegisterScriptDescriptors method on the current replica ScriptManager server control to allow the script server control to register its scripts: scriptManager.RegisterScriptDescriptors(this);
As you can see from Listing 17-4, the ScriptControl base class derives from the WebControl base class instead of the Control base class. Therefore, if you decide to derive your custom script server control from the ScriptControl base class instead of explicitly implementing the IScriptControl interface, you must make sure that you override the WebControl base class’s overridable methods as opposed to the Control base class. You’ll see an example of this later in this chapter.
ScriptDescriptor Recall from Listings 17-1 and 17-3 that the GetScriptDescriptors method of the IExtenderControl and IScriptControl interfaces return an IEnumerable collection of the ScriptDescriptor objects. Listing 17-5 presents the implementation of the replica ScriptDescriptor abstract base class. As you can see, this class exposes two methods:
❑
GetScript: The subclasses of the ScriptDescriptor abstract base class must implement the GetScript abstract method to return a string that contains the client script that supports the client functionality of a script server control or extender server control. This client script normally performs these tasks:
❑
Instantiates the ASP.NET AJAX component associated with the script server control or extender server control
716
c17.indd 716
8/20/07 6:29:55 PM
Chapter 17: Script and Extender Server Controls
❑
❑
Initializes the properties of this ASP.NET AJAX component and registers event handlers for the events of this ASP.NET AJAX component
❑
Adds this ASP.NET AJAX component to the current ASP.NET AJAX application
RegisterDisposeForDescriptor: The subclasses of the ScriptDescriptor base class can override the RegisterDisposeForDescriptor method to generate the client script that registers the dispose script for the ASP.NET AJAX component associated with the script server control or extender server control. Such a dispose script normally performs final cleanup before the ASP.NET AJAX component is disposed of. As you can see, the ScriptDescriptor base class does not mark the RegisterDisposeForDescriptor method as abstract. Therefore the implementation of this method is optional.
Listing 17-5: The ScriptDescriptor Base Class namespace CustomComponents3 { using System.Web.UI; public abstract class ScriptDescriptor { protected internal abstract string GetScript(); internal virtual void RegisterDisposeForDescriptor(ScriptManager scriptManager, Control owner) { } } }
The ASP.NET AJAX Framework comes with a class named ScriptComponentDescriptor that derives from the ScriptDescriptor abstract base class, implements its GetScript method, and extends its functionality to add support for new methods and properties. We’ll discuss all this in the next section.
ScriptComponentDescriptor Listing 17-6 presents the implementation of the replica ScriptComponentDescriptor class. I’ll discuss the implementation of the methods and properties of this class in the following sections.
Listing 17-6: The ScriptComponentDescriptor namespace CustomComponents3 { using System.Collections.Generic; using System.Web.Script.Serialization; using System.Web.UI; using System.Text; using System; public class ScriptComponentDescriptor : ScriptDescriptor { // Fields private string _elementIDInternal;
(continued)
717
c17.indd 717
8/20/07 6:29:55 PM
Chapter 17: Script and Extender Server Controls Listing 17-6 (continued) private private private private private private private
// Methods public ScriptComponentDescriptor(string type) { this._registerDispose = true; this._type = type; } internal ScriptComponentDescriptor(string type, string elementID) : this(type) { this._elementIDInternal = elementID; } public void AddComponentProperty(string name, string componentID) { string value = “\””; value += HelperMethods.QuoteString(componentID); value += “\””; References[name] = value; } public void AddElementProperty(string name, string elementID) { string value = “$get(\””; value += HelperMethods.QuoteString(elementID); value += “\”)”; Properties[name] = value; } public void AddEvent(string name, string handler) { this.Events[name] = handler; } public void AddProperty(string name, object val) { string value = this.Serializer.Serialize(val); Properties[name] = value; } public void AddScriptProperty(string name, string script) { Properties[name] = script; }
718
c17.indd 718
8/20/07 6:29:56 PM
Chapter 17: Script and Extender Server Controls private void AppendScript(SortedList list, StringBuilder builder) { bool flag = true; if ((list != null) && (list.Count > 0)) { foreach (KeyValuePair pair in list) { if (flag) { builder.Append(“{“); flag = false; } else builder.Append(“,”); builder.Append(‘”’); builder.Append(HelperMethods.QuoteString(pair.Key)); builder.Append(‘”’); builder.Append(‘:’); builder.Append(pair.Value); } } if (flag) builder.Append(“null”); else builder.Append(“}”); } protected internal override string GetScript() { if (!string.IsNullOrEmpty(this.ID)) this.AddProperty(“id”, this.ID); StringBuilder builder = new StringBuilder(); builder.Append(“$create(“); builder.Append(this.Type); builder.Append(“, “); this.AppendScript(this._properties, builder); builder.Append(“, “); this.AppendScript(this._events, builder); builder.Append(“, “); this.AppendScript(this._references, builder); if (this.ElementIDInternal != null) { builder.Append(“, “); builder.Append(“$get(\””); builder.Append(HelperMethods.QuoteString(this.ElementIDInternal)); builder.Append(“\”)”); }
(continued)
719
c17.indd 719
8/20/07 6:29:56 PM
Chapter 17: Script and Extender Server Controls Listing 17-6 (continued) builder.Append(“);”); return builder.ToString(); } public virtual string ClientID { get { return this.ID; } } internal string ElementIDInternal { get { return this._elementIDInternal; } } private SortedList Events { get { if (this._events == null) this._events = new SortedList(StringComparer.Ordinal); return this._events; } } public virtual string ID { get { return (this._id ?? string.Empty); } set { this._id = value; } } private SortedList Properties { get { if (this._properties == null) this._properties = new SortedList(StringComparer.Ordinal); return this._properties; } } private SortedList References { get { if (this._references == null) this._references = new SortedList(StringComparer.Ordinal); return this._references; } }
720
c17.indd 720
8/20/07 6:29:56 PM
Chapter 17: Script and Extender Server Controls internal bool RegisterDispose { get { return this._registerDispose; } set { this._registerDispose = value; } } private JavaScriptSerializer Serializer { get { if (this._serializer == null) this._serializer = new JavaScriptSerializer(); return this._serializer; } } public string Type { get { return this._type; } set { this._type = value; } } } }
GetScript The ScriptComponentDescriptor overrides the GetScript abstract method that it inherits from the ScriptDescriptor abstract base class, as shown in Listing 17-6. The main responsibility of the GetScript method of the ScriptComponentDescriptor class is to generate the client script that performs the following tasks:
❑
Instantiates the ASP.NET AJAX component associated with the script or extender server control
❑
Initializes the properties of this ASP.NET AJAX component
❑
Registers event handlers for the events of this ASP.NET AJAX component
❑
Attaches this ASP.NET AJAX component to its associated script or extender server control
❑
Adds this ASP.NET AJAX component to the current ASP.NET AJAX application
As the following excerpt from Listing 16-64 shows, all of this is achieved through a call into the $create global JavaScript function: var properties = {name : “MyTextBoxWatermarkBehaviorName”, id : “MyTextBoxWatermarkBehaviorID”, WatermarkText : “Enter text here”, WatermarkCssClass : “WatermarkCssClass”}; var textBox1 = $get(“TextBox1”); textBoxWatermarkBehavior = $create(AjaxControlToolkit.TextBoxWatermarkBehavior, properties, null, null, textBox1);
721
c17.indd 721
8/20/07 6:29:57 PM
Chapter 17: Script and Extender Server Controls This example does not register any event handlers. However, in general, the $create function takes five parameters:
❑
The first parameter references the constructor of the ASP.NET AJAX component being created. The current example passes the reference to the constructor of the TextBoxWatermarkBehavior because this behavior is the ASP.NET AJAX component being created in this case:
The second parameter references the dictionary that contains the names and initial values of the properties of the ASP.NET AJAX component being created:
The third parameter references the dictionary that contains the names of the events of the ASP.NET AJAX component being created, and the event handlers being registered for these events. This example passes null for this parameter because the page shown in Listing 16-64 does not register any event handlers:
The fourth parameter is a dictionary that contains the names and values of those properties of the ASP.NET AJAX component that reference other ASP.NET AJAX components in the current ASP.NET AJAX application:
As you can see from Listing 17-6, the GetScript method takes these steps to generate the client script that calls into the $create global JavaScript function, passing in the preceding five parameters. As you’ll see later, the ScriptComponentDescriptor exposes a method named AddProperty that takes two parameters, the first parameter containing the name of the property being added and the second containing the value of this property. The AddProperty method under the hood adds the specified property name and value to an internal dictionary. As Listing 17-6 shows, the GetScript method calls the AddProperty method to add the id property and its value to this internal dictionary: if (!string.IsNullOrEmpty(this.ID)) this.AddProperty(“id”, this.ID);
722
c17.indd 722
8/20/07 6:29:57 PM
Chapter 17: Script and Extender Server Controls As the following code fragment shows, the ScriptComponentDescriptor exposes a read-only property named ClientID, which returns the value of another property named ID. The ID property is a read/write property that specifies the id of the ASP.NET AJAX component being created. Recall that the id of an ASP.NET AJAX component uniquely identifies that component among other components in the current ASP.NET AJAX application: public virtual string ClientID { get { return this.ID; } } public virtual string ID { get { return (this._id ?? string.Empty); } set { this._id = value; } }
Now back to the implementation of the GetScript method. Next, GetScript instantiates a StringBuilder and populates it with the script that invokes the $create function: StringBuilder builder = new StringBuilder();
Then, GetScript appends the string “$create(“ to the StringBuilder: builder.Append(“$create(“);
Next, it passes the value of the Type property of the ScriptComponentDescriptor as the first parameter of the $create function. Recall that the first parameter references the constructor of the ASP.NET AJAX component being created: builder.Append(this.Type);
As you can see from the following code fragment, the constructor of the ScriptComponentDescriptor takes a string parameter that contains the fully qualified name of the type of the ASP.NET AJAX component being initialized. Note that this constructor assigns this string parameter to a private field named _type, which can be then accessed via the read/write Type property of the ScriptComponentDescriptor: public ScriptComponentDescriptor(string type) { this._registerDispose = true; this._type = type; } public string Type { get { return this._type; } set { this._type = value; } }
723
c17.indd 723
8/20/07 6:29:57 PM
Chapter 17: Script and Extender Server Controls Now back to the implementation of the GetScript method. Next, this method invokes another method, AppendScript, and passes two parameters into it. The first parameter references an internal collection named _properties, and the second parameter references the StringBuilder. As you’ll see later, the _ properties collection is a SortedList of KeyValuePair objects for which each object represents a property of the ASP.NET AJAX component being created. The Key and Value properties of each object contain the name and value of the associated property, respectively. As you’ll see later, the AppendScript method serializes the _ properties collection into an object literal whose name/value pairs are the object literal representations of the KeyValuePair objects in the collection. The AppendScript method then passes this object literal into the $create method as its second argument. Recall that the second argument of the $create method is a dictionary that contains one name/value pair for each property being initialized, the name part of the pair containing the name of the property and the value part containing the value: this.AppendScript(this._properties, builder);
Next, the GetScript method invokes the AppendScript method once again and passes two parameters into it. The first parameter references an internal collection named _events and the second parameter references the StringBuilder. As you’ll see later, the _events collection is another SortedList of KeyValuePair objects. The Key and Value properties contain an event name of the ASP.NET AJAX component being initialized and the event handler being registered for this event, respectively. As you’ll see later, the AppendScript method serializes the _events collection into an object literal whose name/value pairs are the object literal representations of KeyValuePair objects in the collection. The AppendScript method then passes this object literal into the $create method as its third argument. Recall that the third argument of the $create method is an object literal whose name/value pairs represent event names and the event handlers being registered for these events. this.AppendScript(this._events, builder);
Next, the GetScript method invokes the AppendScript method once more and passes two parameters into it. The first parameter references an internal collection named _references and the second parameter references the StringBuilder. As you’ll see later, the _references collection is another SortedList of KeyValuePair objects for which the Key and Value properties contain the name of a property of the ASP.NET AJAX component being initialized and the id of another ASP.NET AJAX component that the property references, respectively. As you’ll see later, the AppendScript method serializes the _references collection into an object literal whose name/value pairs are the object literal representation of KeyValuePair objects in the collection. The AppendScript method then passes this object literal into the $create method as its fourth argument. this.AppendScript(this._references, builder);
Next, GetScript generates the script that invokes the $get global JavaScript function to return a reference to the associated DOM element of the ASP.NET AJAX component being created. Note that GetScript passes the value of the ElementIDInternal property of the ScriptComponentDescriptor into the
724
c17.indd 724
8/20/07 6:29:57 PM
Chapter 17: Script and Extender Server Controls $get function. The value returned from the $get function is then passed into the $create global
JavaScript function as its last parameter. Recall that the last parameter of this function references the associated DOM element of the ASP.NET AJAX component being created. builder.Append(“$get(\””); builder.Append(HelperMethods.QuoteString(this.ElementIDInternal));
The ScriptComponentDescriptor comes with an internal constructor that takes two parameters. The first parameter is a string that contains the fully qualified name of the type of the ASP.NET AJAX component being instantiated, including its complete namespace containment hierarchy (for example, this parameter is the string AjaxControlToolkit.TextBoxWatermarkBehavior in the case of the TextBoxWatermarkBehavior). The second parameter is a string that contains the id HTML attribute value of the associated DOM element of the component. As you can see, this constructor stores its second parameter in a private field named _elementIDInternal, whose value is returned by an internal property named ElementIDInternal: internal ScriptComponentDescriptor(string type, string elementID) : this(type) { this._elementIDInternal = elementID; } internal string ElementIDInternal { get { return this._elementIDInternal; } }
HelperMethods As Listing 17-6 shows, the GetScript method calls the QuoteString static method on a class named HelperMethods and passes the value of the ElementIDInternal property of the ScriptComponentDescriptor into it: builder.Append(HelperMethods.QuoteString(this.ElementIDInternal));
To understand what the QuoteString static method does, you need to understand the definition of a string in the JSON jargon. According to the JSON specification, a string is a collection of zero or more Unicode characters wrapped in double quotes and using backlash escapes. As you can see from Listing 17-7, the QuoteString method ensures that the string passed into it as its argument meets these JSON requirements. Note that the QuoteString static method makes use of another static method of the HelperMethods class, AppendCharAsUnicode, to ensure that all the characters in the specified string are Unicode characters.
Listing 17-7: The HelperMethods Class using using using using using using using using
Chapter 17: Script and Extender Server Controls Listing 17-7 (continued) using System.Web.UI.HtmlControls; using System.Text; namespace CustomComponents3 { public class HelperMethods { public static string QuoteString(string value) { if (string.IsNullOrEmpty(value)) return string.Empty; StringBuilder builder = null; int startIndex = 0; int count = 0; for (int i = 0; i < value.Length; i++) { char c = value[i]; if ((((c == ‘\r’) || (c == ‘\t’)) || ((c == ‘”’) || (c == ‘\’’))) || ((((c == ‘’)) || ((c == ‘\\’) || (c == ‘\n’))) || (((c == ‘\b’) || (c == ‘\f’)) || (c < ‘ ‘)))) { if (builder == null) builder = new StringBuilder(value.Length + 5); if (count > 0) builder.Append(value, startIndex, count); startIndex = i + 1; count = 0; } switch (c) { case ‘’: case ‘\’’: HelperMethods.AppendCharAsUnicode(builder, c); continue; case ‘\\’: builder.Append(@”\\”); continue; case ‘\b’: builder.Append(@”\b”); continue; case ‘\t’: builder.Append(@”\t”); continue; case ‘\n’: builder.Append(@”\n”); continue;
726
c17.indd 726
8/20/07 6:29:58 PM
Chapter 17: Script and Extender Server Controls case ‘\f’: builder.Append(@”\f”); continue; case ‘\r’: builder.Append(@”\r”); continue; case ‘”’: builder.Append(“\\\””); continue; } if (c < ‘ ‘) HelperMethods.AppendCharAsUnicode(builder, c); else count++; } if (builder == null) return value; if (count > 0) builder.Append(value, startIndex, count); return builder.ToString(); } public static void AppendCharAsUnicode(StringBuilder builder, char c) { builder.Append(@”\u”); builder.AppendFormat(“{0:x4}”, new object[] { (int)c }); } } }
Public Methods The ScriptComponentDescriptor class exposes five important public methods that you can call from your managed code. I’ll present and discuss the implementation of these public methods in the following sections.
AddComponentProperty Use the AddComponentProperty method to initialize those properties of an ASP.NET AJAX component that reference other ASP.NET AJAX components in the current ASP.NET AJAX application. These properties are known as component properties. The AddComponentProperty method takes two parameters, the first being a string that contains the name of the property being initialized and the second being a string that contains the id property value of the ASP.NET AJAX component that this property references. Recall that the id property value of an ASP.NET AJAX component uniquely identifies the component among other components in the current ASP.NET AJAX application.
727
c17.indd 727
8/20/07 6:29:58 PM
Chapter 17: Script and Extender Server Controls Keep in mind that an ASP.NET AJAX component is any ASP.NET AJAX class that directly or indirectly inherits from the ASP.NET AJAX Component base class. Since all ASP.NET AJAX controls and behaviors inherit from this base class, they are all ASP.NET AJAX components. Listing 17-6 presents the implementation of the AddComponentProperty method. As you can see, this method takes the following two steps to ensure that the id property value passed into the method as its second argument is a valid JSON string. (Keep in mind that this id property is the id property value of the component referenced by the property being initialized.) Recall that a valid JSON string is a collection of zero or more Unicode characters wrapped in double quotes and using backslash escapes:
❑
First, the AddComponentProperty method calls the QuoteString static method, passing in the component id. Recall from Listing 17-7 that the QuoteString method ensures that the specified string, which is the component id in this case, is a collection of Unicode characters using backslash escapes.
❑
Second, it wraps the component id in double quotes.
The AddComponentProperty method then stores the property name and its associated value, which is the id property value of the component that the property references, in an internal collection named References. As you can see from Listing 17-6, the References collection is a SortedList of KeyValuePair objects for which each object represents a component property. The Key and Value properties of each object in the References collection respectively contain the name of the associated property and its value, which is nothing but the id property value of the component that the property references.
AddElementProperty Use the AddElementProperty method to initialize those properties of an ASP.NET AJAX component that reference DOM elements on the current page. These properties are known as element properties. As you can see from Listing 17-6, the AddElementProperty method takes two arguments: a string that contains the name of the property whose value is being initialized, and a string that contains the id HTML attribute value of a DOM element on the current page. As Listing 17-6 shows, the AddElementProperty method begins by evaluating the value of the property, which is a reference to the DOM element with the specified id HTML attribute value. As such, this method generates the script that contains a call into the $get global JavaScript function. The method takes the following steps to ensure that this script is a valid JSON string:
❑
Calls the QuoteString static method, passing in the element id. Recall from Listing 17-7 that the QuoteString method ensures that the specified string, which is the element id in this case, is a collection of Unicode characters using backslash escapes.
❑
Wraps the element id in double quotes.
Finally, the AddElementProperty method adds the name of the property and its value, which is the above script, to an internal collection named Properties. Notice that the Properties collection is again a SortedList of KeyValuePair objects where each object represents an element property. The Key and Value properties of each in the Properties collection respectively contain the name of the associated property and its value, which is nothing but the script that returns a reference to the DOM element with the specified element id.
728
c17.indd 728
8/20/07 6:29:59 PM
Chapter 17: Script and Extender Server Controls AddEvent The AddEvent method takes two parameters: a string that contains an event name, and a string that contains an event handler. In other words, this method enables you to register an event handler for the specified event of an ASP.NET AJAX component. As Listing 17-6 shows, this method adds the specified event name and its associated event handler to an internal dictionary named Events. Notice that the Events collection is a SortedList of KeyValuePair objects. The Key and Value properties of each object in the Events collection contain an event name and its associated event handler, respectively.
AddProperty The AddProperty public method takes the name of the property being initialized as its first argument and the value of the property as its second argument. The value could be any .NET object that the JavaScriptSerializer can serialize into a valid JSON string. As you can see from Listing 17-6, this method first invokes the Serialize method on the JavaScriptSerializer, passing in the property value, which is a .NET object. The Serialize method serializes the specified .NET object into its JSON representation and returns a string that contains this JSON representation. The AddProperty method then adds the name of this property and its value, which is the string that contains the JSON representation of the original .NET object, to the Properties collection. As you can see from Listing 17-6, our replica ScriptComponentDescriptor exposes a property of type JavaScriptSerializer named Serializer that instantiates and returns a JavaScriptSerializer object.
AddScriptProperty The AddScriptProperty method enables you to initialize those properties of an ASP.NET AJAX component whose values are client scripts. As you can see from Listing 17-6, this method takes the name of the property being initialized as its first argument and the script that constitutes the value of the property as its second argument. This method stores the name of the property and its associated value in the Properties collection.
AppendScript Recall from Listing 17-6 that the GetScript method of the ScriptComponentDescriptor instantiates a StringBuilder and populates it with the script that invokes the $create global JavaScript function to create a new ASP.NET AJAX component. As you saw, this method invokes the AppendScript method three times, as follows:
❑
The first time, it passes the Properties collection into the method to have the method to serialize this collection into its object literal representation and to append a string to the specified StringBuilder that contains this representation. Recall that this representation contains one name/value pair for each item in the Properties collection.
❑
The second time, it passes the Events collection into the method to have the method to serialize this collection into its object literal representation and to append a string to the specified StringBuilder that contains this representation. Recall that this representation contains one name/value pair for each item in the Events collection.
729
c17.indd 729
8/20/07 6:29:59 PM
Chapter 17: Script and Extender Server Controls ❑
The third time, it passes the References collection into the method to have the method to serialize this collection into its object literal representation and to append a string to the specified StringBuilder that contains this representation. Recall that this representation contains one name/value pair for each item in the References collection.
Next, I’ll walk you through the implementation of the AppendScript method, as shown in Listing 17-6. This method takes two arguments: a SortedList of KeyValuePair objects, and a StringBuilder. The main responsibility of this method is to serialize the specified SortedList into its JSON representation, which is a JSON object. This JSON object, like any other JSON object, starts with an open curly brace ({): builder.Append(“{“);
This JSON object also contains a comma-separated list of name/value pairs, for which each name/value pair is the JSON serialization of a KeyValuePair object in the SortedList. Here is how the AppendScript method serializes each KeyValuePair object in the SortedList: since the AddComponentProperty, AddElementProperty, AddEvent, AddProperty, and AddScriptProperty methods have already ensured that the value contained in the Value property of each KeyValuePair object in the References, Properties, and Events collections is a valid JSON representation, the AppendScript method must only serialize the value contained in the Key property of each KeyValuePair object. To do so, the method performs these tasks:
❑
Invokes the QuoteString static method on the HelperMethods class once for each KeyValuePair object in the SortedList, passing in the value of the Key property of the KeyValuePair object to ensure that this value is a collection of Unicode characters using backslash escapes: builder.Append(HelperMethods.QuoteString(pair.Key));
❑
Wraps the return value of the QuoteString static method in double quotes: builder.Append(‘”’); builder.Append(HelperMethods.QuoteString(pair.Key)); builder.Append(‘”’);
Finally, the AppendScript method appends a colon character followed by the value of the Value property of the KeyValuePair object as is: builder.Append(‘:’); builder.Append(pair.Value);
ScriptControlDescriptor Listing 17-8 presents the implementation of the replica ScriptControlDescriptor. As you can see, this class derives from the ScriptComponentDescriptor base class discussed in the previous sections. Note that the constructor of the ScriptControlDescriptor class makes use of the internal constructor of the ScriptComponentDescriptor base class. As discussed earlier, this internal constructor takes two parameters, the first containing the fully qualified name of the type of the ASP.NET AJAX control being
730
c17.indd 730
8/20/07 6:29:59 PM
Chapter 17: Script and Extender Server Controls instantiated and initialized, and the second containing the id HTML attribute of the associated DOM element of this ASP.NET AJAX control.
Listing 17-8: The ScriptControlDescriptor namespace CustomComponents3 { using System; public class ScriptControlDescriptor : ScriptComponentDescriptor { public ScriptControlDescriptor(string type, string elementID) : base(type, elementID) { base.RegisterDispose = false; } public override string ClientID { get { return this.ElementID; } } public string ElementID { get { return base.ElementIDInternal; } } public override string ID { get { return base.ID; } set { throw new InvalidOperationException(“ID Not Settable”); } } } }
ScriptBehaviorDescriptor Listing 17-9 presents the implementation of the replica ScriptBehaviorDescriptor. As you can see, this class, just like the ScriptControlBehavior class, derives from the ScriptComponentDescriptor base class. Note that the constructor of the ScriptBehaviorDescriptor class, just like the constructor of the ScriptControlBehavior class, makes use of the internal constructor of the ScriptComponentDescriptor base class. In this case, the first parameter passed into this internal constructor contains the fully qualified name of the type of the ASP.NET AJAX behavior being instantiated and initialized, and the second parameter contains the id HTML attribute of the associated DOM element of this ASP.NET AJAX behavior.
731
c17.indd 731
8/20/07 6:30:00 PM
Chapter 17: Script and Extender Server Controls As discussed in Chapter 16, every ASP.NET AJAX behavior exposes a property named name that contains the name of the behavior. As a result, the ScriptBehaviorDescriptor overrides the GetScript method of its base class — that is, the ScriptComponentDescriptor — to make a call to the AddProperty method to add the value of its _name field as the value of the name property of the behavior being instantiated and initialized: if (!string.IsNullOrEmpty(this._name)) base.AddProperty(“name”, this._name); return base.GetScript();
As you can see from Listing 17-9, the ScriptBehaviorDescriptor class exposes a read/write property named Name that enables you to get and to set the value of the _name field of the class. Note that the getter of this property first checks whether the value of the _name field is set — that is, whether the setter method has been called to set this value. If so, it simply returns the value of the _name field. If not, it invokes another method named GetTypeName, passing in the fully qualified name of the type of the behavior being instantiated and initialized to generate and return an appropriate value for the Name property. As Listing 17-9 shows, the GetTypeName method simply extracts the name of the type of the behavior being instantiated and initialized from its fully qualified name. Recall that the fully qualified name of the type of an ASP.NET AJAX component such as a behavior contains both the name and the complete namespace containment hierarchy of the component.
Listing 17-9: The ScriptBehaviorDescriptor namespace CustomComponents3 { public class ScriptBehaviorDescriptor : ScriptComponentDescriptor { private string _name; public ScriptBehaviorDescriptor(string type, string elementID) : base(type, elementID) { base.RegisterDispose = false; } protected internal override string GetScript() { if (!string.IsNullOrEmpty(this._name)) base.AddProperty(“name”, this._name); return base.GetScript(); } private static string GetTypeName(string type) { int num = type.LastIndexOf(‘.’); if (num == -1) return type;
732
c17.indd 732
8/20/07 6:30:00 PM
Chapter 17: Script and Extender Server Controls return type.Substring(num + 1); } public override string ClientID { get { if (string.IsNullOrEmpty(this.ID)) return (this.ElementID + “$” + this.Name); return this.ID; } } public string ElementID { get { return base.ElementIDInternal; } } public string Name { get { if (string.IsNullOrEmpty(this._name)) return GetTypeName(base.Type); return this._name; } set { this._name = value; } } } }
ScriptReference Listing 17-10 presents the implementation of the replica ScriptReference class. The main responsibility of a ScriptReference object is to specify and represent a reference to a JavaScript file. The ASP.NET AJAX ScriptReference class provides you with two approaches to specify the location of the JavaScript file. The first approach requires you to set the value of the Path property of the ScriptReference object to the URL of the JavaScript file. The second approach, which only applies to JavaScript files embedded in an assembly, requires you to assign a string that contains the assembly information to the Assembly property of the ScriptReference object and to assign a string that specifies the name of the JavaScript file to the Name property of the ScriptReference object. To keep our discussions focused, the replica ScriptReference class only supports the first approach. However, you can easily extend the replica to add support for the second approach as well.
733
c17.indd 733
8/20/07 6:30:00 PM
Chapter 17: Script and Extender Server Controls Listing 17-10: The ScriptReference Class using System; using System.Web.UI; using System.ComponentModel; namespace CustomComponents3 { public class ScriptReference { private Control _containingControl; private bool _isStaticReference; private string _path; public ScriptReference() {} public ScriptReference(string path) : this() { this.Path = path; } [DefaultValue(“”), Category(“Behavior”)] public string Path { get { if (this._path != null) return this._path; return string.Empty; } set { this._path = value; } } internal bool IsStaticReference { get { return this._isStaticReference; } set { this._isStaticReference = value; } } internal Control ContainingControl { get { return this._containingControl; } set { this._containingControl = value; } } } }
734
c17.indd 734
8/20/07 6:30:01 PM
Chapter 17: Script and Extender Server Controls
ScriptReferenceCollection Listing 17-11 presents the implementation of the replica ScriptReferenceCollection class. As the name suggests, this collection contains objects of type ScriptReference. As you’ll see in the next section, the ScriptManager exposes a property of type ScriptReferenceCollection named Scripts. Thanks to the .NET 2.0 generics, implementing a new collection class such as ScriptReferenceCollection is as easy as declaring a class that derives from one of the standard .NET generic collections.
Listing 17-11: The ScriptReferenceCollection Class using System.Collections.ObjectModel; namespace CustomComponents3 { public class ScriptReferenceCollection : Collection { } }
ScriptManager Listing 17-12 contains the implementation of the replica ScriptManager class. As you can see, this class drives from the Control base class. This derivation turns the ScriptManager into a server control and consequently allows it to participate in the typical ASP.NET page/control life-cycle phases. I’ll discuss the implementation of the methods and properties of the replica ScriptManager server control in the following sections.
Listing 17-12: The ScriptManager Class using using using using using using
namespace CustomComponents3 { [ParseChildren(true), DefaultProperty(“Scripts”), NonVisualControl, PersistChildren(false)] public class ScriptManager : Control { public event EventHandler ResolveScriptReference { add { base.Events.AddHandler(ResolveScriptReferenceEvent, value); } remove
(continued)
735
c17.indd 735
8/20/07 6:30:01 PM
Chapter 17: Script and Extender Server Controls Listing 17-12 (continued) { base.Events.RemoveHandler(ResolveScriptReferenceEvent, value); } } private ScriptReferenceCollection _scripts; [PersistenceMode(PersistenceMode.InnerProperty), Editor(“System.Web.UI.Design.CollectionEditorBase, System.Web.Extensions.Design, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35”, typeof(System.Drawing.Design.UITypeEditor)), DefaultValue((string)null), MergableProperty(false), Category(“Behavior”)] public ScriptReferenceCollection Scripts { get { if (this._scripts == null) this._scripts = new ScriptReferenceCollection(); return this._scripts; } } protected override void OnInit(EventArgs e) { base.OnInit(e); Page.Items[typeof(ScriptManager)] = this; this.Page.PreRenderComplete += new EventHandler(Page_PreRenderComplete); } public static ScriptManager GetCurrent(Page page) { return (page.Items[typeof(ScriptManager)] as ScriptManager); } private static readonly object ResolveScriptReferenceEvent = new object(); protected virtual void OnResolveScriptReference(ScriptReferenceEventArgs e) { EventHandler handler = (EventHandler) base.Events[ResolveScriptReferenceEvent]; if (handler != null) handler(this, e); } void Page_PreRenderComplete(object sender, EventArgs e) { List list1 = new List(); this.CollectScripts(list1); ScriptReferenceEventArgs args;
736
c17.indd 736
8/20/07 6:30:01 PM
Chapter 17: Script and Extender Server Controls foreach (ScriptReference reference3 in list1) { args = new ScriptReferenceEventArgs(reference3); this.OnResolveScriptReference(args); } foreach (ScriptReference reference4 in list1) { string url = reference4.Path; if (this.LoadScriptsBeforeUI) this.Page.ClientScript.RegisterClientScriptInclude(typeof(ScriptManager), url, url); else { string script = “\r\n”; this.Page.ClientScript.RegisterStartupScript(typeof(ScriptManager), url, script, false); } } } private void CollectScripts(List scripts) { if (this._scripts != null) { foreach (ScriptReference reference1 in this._scripts) { reference1.ContainingControl = this; reference1.IsStaticReference = true; scripts.Add(reference1); } } this.AddScriptReferencesForScriptControls(scripts); this.AddScriptReferencesForExtenderControls(scripts); } private void AddScriptReferencesForScriptControls( List scriptReferences) { if (this._scriptControls != null) { foreach (IScriptControl scriptControl in this._scriptControls.Keys) { IEnumerable enumerable1 = scriptControl.GetScriptReferences(); if (enumerable1 != null) { using (IEnumerator enumerator1 = enumerable1.GetEnumerator()) { while (enumerator1.MoveNext()) {
(continued)
737
c17.indd 737
8/20/07 6:30:01 PM
Chapter 17: Script and Extender Server Controls Listing 17-12 (continued) ScriptReference reference1 = enumerator1.Current; if (reference1 != null) { reference1.ContainingControl = (Control)scriptControl; reference1.IsStaticReference = false; scriptReferences.Add(reference1); } } } } } } } private void AddScriptReferencesForExtenderControls(List scriptReferences) { if (this._extenderControls != null) { foreach (IExtenderControl extenderControl in this._extenderControls.Keys) { IEnumerable enumerable1 = extenderControl.GetScriptReferences(); if (enumerable1 != null) { using (IEnumerator enumerator1 = enumerable1.GetEnumerator()) { while (enumerator1.MoveNext()) { ScriptReference reference1 = enumerator1.Current; if (reference1 != null) { reference1.IsStaticReference = false; reference1.ContainingControl = (Control)extenderControl; scriptReferences.Add(reference1); } } } } } } } public void RegisterScriptControl(TScriptControl scriptControl) where TScriptControl : Control, IScriptControl { int num; this.ScriptControls.TryGetValue(scriptControl, out num); num++; this.ScriptControls[scriptControl] = num; }
738
c17.indd 738
8/20/07 6:30:02 PM
Chapter 17: Script and Extender Server Controls private Dictionary _scriptControls; private Dictionary ScriptControls { get { if (this._scriptControls == null) this._scriptControls = new Dictionary(); return this._scriptControls; } } public void RegisterExtenderControl(TExtenderControl extenderControl, Control targetControl) where TExtenderControl : Control, IExtenderControl { List list; if (!this.ExtenderControls.TryGetValue(extenderControl, out list)) { list = new List(); this.ExtenderControls[extenderControl] = list; } list.Add(targetControl); } private Dictionary _extenderControls; private Dictionary ExtenderControls { get { if (this._extenderControls == null) this._extenderControls = new Dictionary(); return this._extenderControls; } } private bool _loadScriptsBeforeUI; [Category(“Behavior”), DefaultValue(true)] public bool LoadScriptsBeforeUI { get { return this._loadScriptsBeforeUI; } set { this._loadScriptsBeforeUI = value; } } public void RegisterScriptDescriptors(IExtenderControl extenderControl) { List list; Control control = extenderControl as Control; if (!this.ExtenderControls.TryGetValue(extenderControl, out list)) throw new ArgumentException(“Extender Control Not Registered”);
(continued)
739
c17.indd 739
8/20/07 6:30:02 PM
Chapter 17: Script and Extender Server Controls Listing 17-12 (continued) foreach (Control control2 in list) { if (control2.Visible) { IEnumerable scriptDescriptors = extenderControl.GetScriptDescriptors(control2); if (scriptDescriptors != null) { StringBuilder builder = null; foreach (ScriptDescriptor descriptor in scriptDescriptors) { if (builder == null) { builder = new StringBuilder(); builder.AppendLine(“Sys.Application.add_init(function() {“); } builder.Append(“ “); builder.AppendLine(descriptor.GetScript()); descriptor.RegisterDisposeForDescriptor(this, control); } if (builder != null) { builder.AppendLine(“});”); string key = builder.ToString(); Page.ClientScript.RegisterStartupScript(typeof(ScriptManager), key, key, true); } } } } } public void RegisterScriptDescriptors(IScriptControl scriptControl) { int num; Control control = scriptControl as Control; if (!this.ScriptControls.TryGetValue(scriptControl, out num)) throw new ArgumentException(“Script Control Not Registered”); for (int i = 0; i < num; i++) { IEnumerable scriptDescriptors = scriptControl.GetScriptDescriptors(); if (scriptDescriptors != null) { StringBuilder builder = null; foreach (ScriptDescriptor descriptor in scriptDescriptors) { if (builder == null) {
740
c17.indd 740
8/20/07 6:30:02 PM
Chapter 17: Script and Extender Server Controls builder = new StringBuilder(); builder.AppendLine(“Sys.Application.add_init(function() {“); } builder.Append(“ “); builder.AppendLine(descriptor.GetScript()); descriptor.RegisterDisposeForDescriptor(this, control); } if (builder != null) { builder.AppendLine(“});”); string key = builder.ToString(); Page.ClientScript.RegisterStartupScript(typeof(ScriptManager), key, key, true); } } } } } }
Scripts As you can see from Listing 17-12, the ScriptManager server control exposes a collection property of the type ScriptReferenceCollection named Scripts that contains the ScriptReference objects that reference JavaScript files. Note that this property is marked with the PersistenceMode(PersistenceMode.InnerProperty) metadata attribute to enable you to add ScriptReference objects to this collection in a purely declarative fashion, without writing a single line of imperative code.
LoadScriptsBeforeUI As Listing 17-12 shows, the ScriptManager server control exposes a Boolean property named LoadScriptsBeforeUI that specifies whether the script files referenced by the ScriptReference objects in the Scripts collection must be loaded before the HTML markup text. The default is true. The decision as to whether to load the scripts before or after UI depends on whether the scripts contain any references to the UI elements. If they do, they must be loaded after UI to ensure that the UI elements that the scripts reference are already loaded. You’ll see an example of this property later in this chapter.
ScriptControls The replica ScriptManager server control maintains the list of all script server controls on the current page in an internal collection named ScriptControls (see Listing 17-12).
RegisterScriptControl The RegisterScriptControl method of the ScriptManager server control adds the specified script server control to the ScriptControls collection discussed in the previous section (see Listing 17-12).
741
c17.indd 741
8/20/07 6:30:03 PM
Chapter 17: Script and Extender Server Controls
ExtenderControls The replica ScriptManager server control also maintains the list of all extender server controls on the current page in an internal collection named ExtenderControls (see Listing 17-12).
RegisterExtenderControl As you saw in the previous section, the ExtenderControls collection is a dictionary of items, each of which contains a list of server controls associated with a particular extender server control. The RegisterExtenderControl method takes two parameters, the first referencing the extender server control being registered and the second the server control whose client-side functionality the specified extender server control extends. Recall that this server control is known as the target server control of the extender server control. The RegisterExtenderControl simply accesses the item associated with the specified extender server control and adds the specified target server control to the associated server control list of this item. Recall also that each item in the ExtenderControls dictionary contains a list of server controls associated with a particular extender server control.
GetCurrent As Listing 17-12 shows, the GetCurrent static method of the ScriptManager server control returns a reference to the current ScriptManager server control. Recall that the ScriptManager server control maintains this reference in the Items collection of the current Page object. This ensures that the same ScriptManager server control is used throughout the current request.
OnInit As Listing 17-12 shows, the ScriptManager server control overrides the OnInit method that inherits from the Control base class. This method performs three tasks. First, it invokes the OnInit method of its base class to raise the Init event and consequently to invoke all the event handlers registered for the Init event of the current ScriptManager server control: base.OnInit(e);
Next, it stores the reference to the current ScriptManager server control in the Items collection of the current Page object. As discussed earlier, the GetCurrent static method returns this reference to its caller to ensure that the same instance of the ScriptManager server control is used during processing of the current request. Page.Items[typeof(ScriptManager)] = this;
Finally, the OnInit method registers a method named Page_PreRenderComplete as an event handler for the PreRenderComplete event of the current Page object: this.Page.PreRenderComplete += new EventHandler(Page_PreRenderComplete);
742
c17.indd 742
8/20/07 6:30:03 PM
Chapter 17: Script and Extender Server Controls
Page_PreRenderComplete When the current Page enters its PreRenderComplete phase, it automatically invokes the Page_PreRenderComplete method of the current ScriptManager server control shown in Listing 17-12. As you can see, this method first instantiates a List collection: List list1 = new List();
Next, it invokes another method named CollectScripts, passing in the List collection to have this method to populate this collection with the list of ScriptReference objects that reference JavaScript files: this.CollectScripts(list1);
Then it iterates through the ScriptReference objects in the List collection and performs these two tasks for each enumerated ScriptReference object. First, it instantiates a ScriptReferenceEventArgs instance, passing in a reference to the enumerated ScriptReference object. As you’ll see later, the ScriptReferenceEventArgs is the event data class associated with an event named ResolveScriptReference. Next, it invokes a method named OnResolveScriptReference, passing in the ScriptReferenceEventArgs object to raise the ResolveScriptReference event. As you’ll see later, this enables the page developer to register an event handler for this event whereby he or she can use custom code to resolve the reference to the JavaScript file specified by the enumerated ScriptReference object. foreach (ScriptReference reference3 in list1) { args = new ScriptReferenceEventArgs(reference3); this.OnResolveScriptReference(args); }
Next, the Page_PreRenderComplete method iterates through the ScriptReference objects in the List collection once more and takes these steps for each enumerated ScriptReference object. It checks whether the LoadScriptsBeforeUI property is set to true. If so, this indicates that the page developer has requested the referenced JavaScript files to be loaded before the UI is loaded. As a result, the Page_PreRenderComplete method invokes the RegisterClientScriptInclude method on the ClientScript property of the current Page object to have the current page render the script block associated with the enumerated ScriptReference at the beginning of the current page. Note that the src attribute of this script block is set to the value of the Path property of the enumerated ScriptReference object because this property contains the URL of the JavaScript file that the object references. foreach (ScriptReference reference4 in list1) { string url = reference4.Path; if (this.LoadScriptsBeforeUI) this.Page.ClientScript.RegisterClientScriptInclude(typeof(ScriptManager), url, url);
743
c17.indd 743
8/20/07 6:30:03 PM
Chapter 17: Script and Extender Server Controls If the LoadScriptBeforeUI property is set to false, this indicates that the page developer wants the JavaScript file referenced by the enumerated ScriptReference object to be loaded after the UI. As a result, the Page_PreRenderComplete method first generates a string that contains a script include block whose src attribute is set to the value of the Path property of the enumerated ScriptReference object. Then it invokes the RegisterStartupScript method to have the current page render this string right before the closing tag of the form HTML element: else { string script = “\r\n”; this.Page.ClientScript.RegisterStartupScript(typeof(ScriptManager), url, script, false); } }
CollectScripts As you saw in the previous section, the Page_PreRenderComplete method invokes the CollectScripts method of the current ScriptManager server control, passing in a List collection to that method to populate this collection with the list of all ScriptReference objects. In general, there are three groups of ScriptReference objects that the CollectScripts method needs to collect. The first group contains the ScriptReference objects that the page developers declaratively or imperatively add to the Scripts collection of the current ScriptManager server control. As a result, the CollectScripts method iterates through the ScriptReference objects in the Scripts collection and performs these tasks for each ScriptReference object. First it assigns the reference to the current ScriptManager server control as the ContainingControl property of the ScriptReference object: reference1.ContainingControl = this;
Next, it sets the IsStaticReference property of the ScriptReference object to true to signal that this ScriptReference object was defined statically by the page developer: reference1.IsStaticReference = true;
Finally, it adds the ScriptReference object to the List collection passed into the CollectScripts method: scripts.Add(reference1);
The second group of ScriptReference objects includes the ScriptReference objects of the script server controls on the current page. Next, the CollectScripts method invokes another method named AddScriptReferencesForScriptControls, passing in the List collection to have this method add the ScriptReference objects in the second group to this collection: this.AddScriptReferencesForScriptControls(scripts);
744
c17.indd 744
8/20/07 6:30:04 PM
Chapter 17: Script and Extender Server Controls The third group of ScriptReference objects includes the ScriptReference objects of the extender server controls on the current page. Next, the CollectScripts method invokes another method named AddScriptReferencesForExtenderControls, passing in the List collection to have this method add the ScriptReference objects in the third group to this collection: this.AddScriptReferencesForExtenderControls(scripts);
As you can see, when the CollectScripts method finally returns, the List collection passed into it is populated with ScriptReference objects defined for the current page.
AddScriptReferencesForScriptControls As you saw earlier, the CollectScripts method invokes the AddScriptReferencesForScriptControls method, passing in a List collection to have this method to add the ScriptReference objects of all the script server controls on the current page to this collection. Recall that the current ScriptManager server control maintains references of all script server controls on the current page in an internal collection of type Dictionary named ScriptControls. This dictionary exposes a collection property named Keys that contains the actual references to all the script server controls on the current page. Keep in mind that all script server controls implement the IScriptControl interface. As you can see from Listing 17-12, this method iterates through the script server controls in the Keys collection of this collection and takes these steps for each script server control to collect its ScriptReference objects. First, it invokes the GetScriptReferences method on the script server control to return an IEnumerable collection that contains all the ScriptReference objects associated with the script server control. IEnumerable enumerable1 = scriptControl.GetScriptReferences();
Next, it calls the GetEnumerator method on this IEnumerable collection to return a reference to the IEnumerator object that knows how to iterate through the items of this collection in a generic fashion: IEnumerator enumerator1 = enumerable1.GetEnumerator()
Next, it uses this IEnumerator object to iterate through the ScriptReference objects in this collection and performs these steps for each enumerated ScriptReference object. First, it assigns a reference to the script server control to the ContainingControl property of the enumerated ScriptReference object: reference1.ContainingControl = (Control)scriptControl;
Next, it sets the IsStaticReference property of the ScriptReference object to false to indicate that the enumerated ScriptReference object is not one of those ScriptReference objects that the page developer has statically added to the Scripts collection of the ScriptManager server control: reference1.IsStaticReference = false;
745
c17.indd 745
8/20/07 6:30:04 PM
Chapter 17: Script and Extender Server Controls Finally, it adds the enumerated ScriptReference object to the List collection passed into the method: scriptReferences.Add(reference1);
As you can see, by the time the AddScriptReferencesForScriptControls method returns, all the ScriptReference objects of all the script server controls on the current page have been added to the List collection passed into the method.
RegisterScriptDescriptors For Extender Controls The ScriptManager exposes a public method named RegisterScriptDescriptors that you can use from your server-side code to add ScriptDescriptor objects for your extender server control. As Listing 17-12 shows, this method begins by checking whether the ExtenderControls collection of the current ScriptManager server control contains the specified extender server control. Recall from previous sections that you must invoke the RegisterExtenderControl method on the current ScriptManager server control to add your extender server control to the ExtenderControls collection. Note that if the ExtenderControls collection does not contain the specified extender server control, the RegisterScriptDescriptors method raises an exception and does not allow you to add ScriptDescriptors for your extender server control: if (!this.ExtenderControls.TryGetValue(extenderControl, out list)) throw new ArgumentException(“Extender Control Not Registered”);
You must invoke the RegisterExtenderControl method on the current ScriptManager server control to register your extender server control with the current ScriptManager server control before you can register any ScriptDescriptor objects for your extender server control. You do not have to worry about this issue if you’re deriving your extender server control from the ExtenderControl base class. As Listing 17-2 shows, the ExtenderControl base class invokes the RegisterExtenderControl method when it enters its PreRender life-cycle phase and the RegisterScriptDescriptors method when it enters its Render life-cycle phase. Since the PreRender life-cycle phase always occurs before the Render life-cycle phase, the RegisterExtenderControl method is always invoked before the RegisterScriptDescriptors method. The RegisterScriptDescriptors method then calls the GetScriptDescriptors method on the specified extender server control, passing in the reference to the target server control to return an IEnumerable collection that contains all the ScriptDescriptor objects associated with this extender server control: IEnumerable scriptDescriptors = extenderControl.GetScriptDescriptors(control2);
Next, it instantiates a StringBuilder and adds the following string to it. As you can see, this string contains a client script that invokes the add_init method on the Application object that represents the current ASP.NET AJAX application, in order to register the JavaScript function being defined as an event handler for the init event of the Application object. As you’ll see shortly, the rest of the RegisterScriptDescriptors method will define the rest of this JavaScript function. In other words,
746
c17.indd 746
8/20/07 6:30:04 PM
Chapter 17: Script and Extender Server Controls this method is generating the script code that both defines this JavaScript function and registers it as an event handler for the init event. “Sys.Application.add_init(function() {“
Next, the RegisterScriptDescriptors method iterates through the ScriptDescriptor objects in the previously mentioned IEnumerable collection and takes these two steps for each enumerated ScriptDescriptor object. First, it calls the GetScript method on the enumerated ScriptDescriptor object to return a string that contains the client script being registered and adds this string to the StringBuilder: builder.AppendLine(descriptor.GetScript());
When the RegisterScriptDescriptors method gets out of the loop, it invokes the RegisterStartupScript method to have the current page to render the content of the StringBuilder right before the closing tag of the form element. Recall that the content of the StringBuilder is a string that defines and registers a JavaScript function as event handler for the init event of the client-side Application object. if (builder != null) { builder.AppendLine(“});”); string key = builder.ToString(); Page.ClientScript.RegisterStartupScript(typeof(ScriptManager), key, key, true); }
As you can see, by the time the RegisterScriptDescriptors method returns, all the ScriptDescriptor objects associated with the specified extender server control are registered.
ResolveScriptReference Event Recall from Listing 17-12 that the current ScriptManager server control registers its Page_PreRenderComplete method as an event handler for the PreRenderComplete event of the current page. When the current page enters its PreRenderComplete phase, it automatically invokes the Page_PreRenderComplete method. As you saw earlier (and will also see in the following code fragment), this method first invokes the CollectScripts method to collect all ScriptReference objects in a List collection. Next, it iterates through the ScriptReference objects in this collection and takes the following two steps for each enumerated ScriptReference object. First, it instantiates a ScriptReferenceEventArgs object, passing in the enumerated ScriptReference object. Then it invokes the OnResolveScriptReference method, passing in this ScriptReferenceEventArgs object to raise the ResolveScriptReference event for the enumerated ScriptReference object. As you can see, the current ScriptManager server control raises its ResolveScriptReference event once for each ScriptReference object. The page developer can register an event handler for this event in order to be notified when this event is raised. As you can see from the highlighted portions of the following code listing, the current ScriptManager server control raises its ResolveScriptReference event before it invokes the RegisterClientScriptInclude or RegisterStartupScript method to have the current page render the associated script block. This allows the event handlers registered for this event to make any required updates to each ScriptReference object before their associated script blocks are rendered to the current page.
747
c17.indd 747
8/20/07 6:30:05 PM
Chapter 17: Script and Extender Server Controls void Page_PreRenderComplete(object sender, EventArgs e) { List list1 = new List(); this.CollectScripts(list1); ScriptReferenceEventArgs args; foreach (ScriptReference reference3 in list1) { args = new ScriptReferenceEventArgs(reference3); this.OnResolveScriptReference(args); } foreach (ScriptReference reference4 in list1) { string url = reference4.Path; if (this.LoadScriptsBeforeUI) this.Page.ClientScript.RegisterClientScriptInclude(typeof(ScriptManager), url, url); else { string script = “\r\n”; this.Page.ClientScript.RegisterStartupScript(typeof(ScriptManager), url, script, false); } } }
The ScriptManager server control follows the typical .NET event implementation pattern to implement its ResolveScriptReference event:
❑
It defines an event data class named ScriptReferenceEventArgs to hold the event data for this event. Listing 17-13 presents the implementation of this event data class. As you can see from this code listing, the constructor of this event data class takes a single argument of type ScriptReference and stores it in a private field named _script. Note that the class exposes a single read-only property named Script that returns the value of this private field.
❑
It defines an event property as follows: public event EventHandler ResolveScriptReference { add { base.Events.AddHandler(ResolveScriptReferenceEvent, value); } remove { base.Events.RemoveHandler(ResolveScriptReferenceEvent, value); } }
748
c17.indd 748
8/20/07 6:30:05 PM
Chapter 17: Script and Extender Server Controls ❑
It defines a private static read-only object that will be used as a key to the Events collection that the ScriptManager server control inherits from the Control base class in order to add an event handler to and remove an event handler from this collection: private static readonly object ResolveScriptReferenceEvent = new object();
❑
It defines a protected virtual method named OnResolveReference that raises the following event:
Note that the OnResolveScriptReference method passes the ScriptReferenceEventArgs object into the event handlers registered for this event. Recall that this object exposes a read-only property named Script that returns a reference to the ScriptReference object for which the event was raised in the first place. This means that the event handler registered for this event can use this property to access the ScriptReference object to change the properties of this object. For example, this enables you to dynamically specify the value of the Path or Assembly property of the ScriptReference object instead of statically setting them in the .aspx page.
Listing 17-13: The ScriptReferenceEventArgs Event Data Class using System; namespace CustomComponents3 { public class ScriptReferenceEventArgs : EventArgs { private readonly ScriptReference _script; public ScriptReferenceEventArgs(ScriptReference script) { if (script == null) throw new ArgumentNullException(“script”); this._script = script; } public ScriptReference Script { get { return this._script; } } } }
749
c17.indd 749
8/20/07 6:30:05 PM
Chapter 17: Script and Extender Server Controls
Putting it All Together The next chapter will show you how to implement custom extender and script server controls and will implement pages that use these custom controls. Since we would like to put the replica components that we developed in the previous sections to the test and run our custom server controls in the context of these replicas, you need to set up a Web application that uses these replicas. Follow these steps to accomplish this task:
1. 2. 3.
Create an AJAX-enabled Web site in Visual Studio. Add an App_Code directory to this Web site. Add a new source file named IExtenderControl.cs to the App_Code directory and add the code shown in Listing 17-1 to this source file.
4.
Add a new source file named ExtenderControl.cs to the App_Code directory and add the code shown in Listing 17-2 to this source file.
5.
Add a new source file named IScriptControl.cs to the App_Code directory and add the code shown in Listing 17-3 to this source file.
6.
Add a new source file named ScriptControl.cs to the App_Code directory and add the code shown in Listing 17-4 to this source file.
7.
Add a new source file named ScriptDescriptor.cs to the App_Code directory and add the code shown in Listing 17-5 to this source file.
8.
Add a new source file named ScriptComponentDescriptor.cs to the App_Code directory and add the code shown in Listing 17-6 to this source file.
9.
Add a new source file named HelperMethods.cs to the App_Code directory and add the code shown in Listing 17-7 to this source file.
10.
Add a new source file named ScriptControlDescriptor.cs to the App_Code directory and add the code shown in Listing 17-8 to this source file.
11.
Add a new source file named ScriptBehaviorDescriptor.cs to the App_Code directory and add the code shown in Listing 17-9 to this source file.
12.
Add a new source file named ScriptReference.cs to the App_Code directory and add the code shown in Listing 17-10 to this source file.
13.
Add a new source file named ScriptReferenceCollection.cs to the App_Code directory and add the code shown in Listing 17-11 to this source file.
14.
Add a new source file named ScriptManager.cs to the App_Code directory and add the code shown in Listing 17-12 to this source file.
15.
Add a new source file named ScriptReferenceEventArgs.cs to the App_Code directory and add the code shown in Listing 17-13 to this source file.
750
c17.indd 750
8/20/07 6:30:06 PM
Chapter 17: Script and Extender Server Controls
Developing a Custom Extender Ser ver Control In this section, I’ll implement a custom extender server control named TextBoxWatermarkExtenderControl to help you gain the skills that you need to develop your own custom extender server controls. Listing 17-15 presents the implementation of the TextBoxWatermarkExtenderControl server control. Recall that Chapter 16 developed an ASP.NET AJAX behavior named TextBoxWatermarkBehavior. When this behavior is attached to a textbox DOM element, it extends the functionality of the DOM element to add support for watermark capability. As discussed earlier in this chaper, the page that uses the TextBoxWatermarkBehavior must take the steps shown in boldfaced portions of the following code listing:
Listing 17-14: A Page that Uses the TextBoxWatermarkBehavior . . . Untitled Page . . . var textBoxWatermarkBehavior; function submitCallback() { textBoxWatermarkBehavior._onSubmit(); } function pageLoad() { var properties = []; properties[“name”] = “MyTextBoxWatermarkBehaviorName”; properties[“id”] = “MyTextBoxWatermarkBehaviorID”; properties[“WatermarkText”] = “Enter text here”; properties[“WatermarkCssClass”] = “WatermarkCssClass”; var textBox1 = $get(“TextBox1”); textBoxWatermarkBehavior = $create(AjaxControlToolkit.TextBoxWatermarkBehavior, properties, null, null, textBox1); }
(continued)
751
c17.indd 751
8/20/07 6:30:06 PM
Chapter 17: Script and Extender Server Controls Listing 17-14 (continued) . . .
The TextBoxWatermarkExtenderControl server control encapsulates the logic that the boldfaced portions of Listing 17-14 implement and presents page developers with an object-oriented ASP.NET based API that allows them to use the same imperative and declarative ASP.NET techniques to program against the underlying TextBoxwatermark behavior. I’ll discuss the implementation of the methods and properties of the TextBoxWatermarkExtenderControl server control, shown in Listing 17-15, in the following sections.
Listing 17-15: The TextBoxWatermarkExtenderControl using using using using using using using using
Chapter 17: Script and Extender Server Controls string key; string script; key = string.Format(CultureInfo.InvariantCulture, “{0}_onSubmit”, ID); script = string.Format(CultureInfo.InvariantCulture, “var o = $find(‘{0}’); if(o) {{ o._onSubmit(); }}”, BehaviorID); System.Web.UI.ScriptManager.RegisterOnSubmitStatement(this, typeof(TextBoxWatermarkExtenderControl), key, script); ClientState = (string.Compare(Page.Form.DefaultFocus, TargetControlID, StringComparison.InvariantCultureIgnoreCase) == 0) ? “Focused” : null; } private string watermarkText; [DefaultValue(“”)] public string WatermarkText { get { return this.watermarkText; } set { this.watermarkText = value; } } private string watermarkCssClass; [DefaultValue(“”)] public string WatermarkCssClass { get { return this.watermarkCssClass; } set { this.watermarkCssClass = value; } } } }
WatermarkText The TextBoxWatermarkExtenderControl server control exposes a string property named WatermarkText that you can use to get and set the watermark text. This is the text that will be shown to the end user when the associated text box is empty and does not have the mouse focus.
WatermarkCssClass As the name suggests, you can use the WatermarkCssClass to get and to set the watermark style. This is the style that will be automatically applied to the associated text box when the text box is empty and does not have the focus.
ClientState The ClientState property of the TextBoxWatermarkExtenderControl server control gets and sets the client state of the underlying TextBoxWatermarkBehavior. Recall that the the client state of this behavior is a string that specifies whether the associated textbox DOM element has the focus.
755
c17.indd 755
8/20/07 6:30:07 PM
Chapter 17: Script and Extender Server Controls
ClientStateFieldID The ClientStateFieldID property gets and sets the ID attribute HTML value of the hidden field that stores the client state of the underlying TextBoxWatermarkBehavior. As you’ll see shortly, the server and client side code use this hidden field to communicate the client state.
CreateClientStateField The CreateClientStateField method of the TextBoxWatermarkExtenderControl creates the hidden field where the client state of the underlying TextBoxWatermarkBehavior is stored.
BehaviorID The BehaviorID property gets and sets the id of the underlying TextBoxWatermarkBehavior. Recall that the id of an ASP.NET AJAX component such as a behavior uniquely identifies the component among other components in the current ASP.NET AJAX application.
GetScriptReferences The TextBoxWatermarkExtenderServer control overrides the GetScriptReferences method that it inherits from its base class, that is, the ExtenderControl base class. First, it creates a ScriptReference object. Then, it sets the Path property of this object to the URL of the JavaScript file that contains the definition of the BehaviorBase class. Next, it creates another ScriptReference object and sets its Path property to the URL of the JavaScript file that contains the definition of the TextBoxWatermarkBehavior class. You need to copy over the BehaviorBase.js and TextBoxWatermarkBehavior.js files from Chapter 16 to include them in this Website. Finally, the GetScriptReferences method instantiates and returns an array that contains these two ScriptReference objects.
GetScriptDescriptors The TextBoxWatermarkExtenderControl overrides the GetScriptDescriptors method that it inherits from the ExtenderControl base class to instantiate and return the ScriptDescriptor object that instantiates and initializes the TextBoxWatermarkBehavior. As you can see from Listing 17-15, this method begins by creating a ScriptBehaviorDescriptor object, passing in two parameters. The first parameter is a string that contains the fully qualified name of the TextBoxWatermarkBehavior, including its namespace. The second parameter is the ClientID property value of the target server control. Recall that the target server control of an extender server control is the server control whose client side functionality the extender server control is extending, which is an ASP.NET TextBox server control in this case. ScriptBehaviorDescriptor descriptor = new ScriptBehaviorDescriptor(“AjaxControlToolkit.TextBoxWatermarkBehavior”, targetControl.ClientID);
756
c17.indd 756
8/20/07 6:30:07 PM
Chapter 17: Script and Extender Server Controls Next, I digress from our discussion of the implementation of the GetScriptDescriptors method to use the discussions of the previous sections to show you what happens to the AjaxControlToolkit .TextBoxWatermarkBehavior and targetControl.ClientID parameters passed into the ScriptBehaviorDescriptor constructor. Every server control renders its ClientID property value as the value of the id HTML attribute of its containing DOM element. In this case, the ASP.NET TextBox server control renders its ClientID property value as the value of the id HTML attribute of its containing DOM element. Recall from Listing 17-8 that the constructor of the ScriptBehaviorDescriptor passes its parameters to the internal constructor of its base class, that is, that ScriptComponentDescriptor, which means that the AjaxControlToolkit.TextBoxWatermarkBehavior and targetControl.ClientID parameters are passed into the constructor of the ScriptComponentDescriptor: public ScriptBehaviorDescriptor(string type, string elementID) : base(type, elementID) { base.RegisterDispose = false; }
Now, recall from Listing 17-6 that the constructor of the ScriptComponentDescriptor stores the AjaxControlToolkit.TextBoxWatermarkBehavior and targetControl.ClientID parameters in _type and _elementIDInternal private fields: public ScriptComponentDescriptor(string type) { this._registerDispose = true; this._type = type; } internal ScriptComponentDescriptor(string type, string elementID) : this(type) { this._elementIDInternal = elementID; }
Now, recall from Listing 17-6 (shown again in the following code listing) that the GetScript method of the ScriptComponentDescriptor generates the script that makes the call into the $create global JavaScript function to create an instance of the TextBoxWatermarkBehavior behavior. As you can see from the bold faced portions of the following code listing, the GetScript method passes the value of the Type property of the ScriptComponentDescriptor as the first parameter of the $create global function. This property simply returns the value of the _type private field, that is, the string AjaxControlToolkit.TextBoxWatermarkBehavior. As the boldfaced portion of the following code fragment shows, the GetScript method passes the value of the ElementIDInternal property into the $get JavaScript function, which is then passed into the $create function as its last argument. This property simply returns the value of the _elementIDInternal private field, that is, the value of the targetControl.ClientID property.
Now back to the implementation of the GetScriptDescriptors method. Next, this method invokes the AddProperty method on the newly-instantiated ScriptBehaviorDescriptor object to specify the value of the WatermarkText property of the TextBoxWatermarkExtenderControl as the value of the WatermarkText property of the underlying TextBoxWatermarkBehavior: descriptor.AddProperty(“WatermarkText”, this.WatermarkText);
Next, the GetScriptDescriptors method invokes the AddProperty method once again to specify the value of the WatermarkCssClass property of the TextBoxWatermarkExtenderControl as the value of the WatermarkCssClass property of the underlying TextBoxWatermarkBehavior: descriptor.AddProperty(“WatermarkCssClass”, this.WatermarkCssClass);
Then, it invokes the AddProperty method once more to specify the value of the BehaviorID property of the TextBoxWatermarkExtenderControl as the value of the id property of the underlying TextBoxWatermarkBehavior: descriptor.AddProperty(“id”, this.BehaviorID);
Finally, it instantiates and returns an array that contains the above ScriptBehaviorDescriptor object: return new ScriptDescriptor[] { descriptor };
OnInit The TextBoxWatermarkExtenderControl server control overrides the OnInit method that it inherits from the Control base class where it performs these tasks (see Listing 17-15). First, it invokes the CreateClientStateField method to create the hidden field where the client state will be stored as discussed earlier: CreateClientStateField();
758
c17.indd 758
8/20/07 6:30:08 PM
Chapter 17: Script and Extender Server Controls Next, it registers a method named Page_PreLoad as an event handler for the PreLoad event of the current page: Page.PreLoad += new EventHandler(Page_PreLoad);
Finally it invokes the OnInit method of its base class: base.OnInit(e);
Your extender server control’s implementation of the methods of any of its base classes such as ExtenderControl and Control must always invoke the associated method of its base classes unless you have a very good reason to skip the calls into these base methods.
Page_PreLoad As you saw in Listing 17-15, the OnInit method registers the Page_PreLoad method as an event handler for the PreLoad event of the containing page. When the current page enters its PreLoad lifecycle phase, it automatically invokes the Page_PreLoad method. The main responsibility of this method is to set the value of the ClientState property. As you can see from Listing 17-15, this method first invokes the FindControl method on the naming container of the TextBoxWatermarkExtenderControl server control passing in the value of the ClientStateFieldID property to return a reference to the hidden field that contains the client state. Finally, the Page_PreLoad method extracts the client state from this hidden field and assigns it to the ClientState property. Every server control including the TextBoxWatermarkExtenderControl, inherits the NamingContainer property from the Control base class. The NamingContainer property of a server control such as TextBoxWatermarkExtenderControl references the first ancestor of the server control that implements the INamingContainer interface. This interface is a marker interface and does not contain any methods, properties, and events. Implementing this interface allows a server control to act as a naming scope or container for its descendant server controls.
OnLoad As you can see from Listing 17-15, the TextBoxWatermarkExtenderControl server control overrides the OnLoad method of its base class to perform the following tasks. First, it invokes the OnLoad method of its base class to raise the Load event and consequently to invoke all the event handlers registered for the Load event of the TextBoxWatermarkExtenderControl: base.OnLoad(e);
To understand what the rest of the code in the OnLoad method does, you need to revisit Listing 17-14 as repeated in Listing 17-16. Recall that this code listing contains a page that directly uses the TextBoxWatermarkBehavior. As the boldfaced portion of this code listing shows, this page registers a JavaScript function named submitCallback as event handler for the submit event of the form DOM element. When the end user clicks the Submit button to submit this form, the form automatically invokes the submitCallback function before the actual form submission takes place. As you can see from the boldfaced portion of Listing 17-16, the submitCallback method in turn invokes the _onSubmit method on the TextBoxWatermarkBehavior.
759
c17.indd 759
8/20/07 6:30:08 PM
Chapter 17: Script and Extender Server Controls Recall from Listing 16-40 (repeated in the following code listing) that the _onSubmit method of the TextBoxWatermarkBehavior calls the clearText method to remove the watermark text from the text box before the form is submitted. This ensures that the form submission does not contain the watermark text. function AjaxControlToolkit$TextBoxWatermarkBehavior$_onSubmit() { if(this._watermarked) { this.clearText(false); this._clearedForSubmit = true; } }
Now back to the implementation of the OnLoad method of the TextBoxWatermarkExtenderControl. The main objective of this method is to render the script that registers the _onSubmit method of the underlying TextBoxWatermarkBehavior as event handler for the submit event of the form DOM element. The OnLoad method takes these steps to achieve this objective. First, it generates the script that makes a call into the $find global JavaScript function to return a reference to the underlying TextBoxWatermarkBehavior. Note that this script passes the value of the BehaviorID property of the TextBoxWatermarkExtenderControl server control as the argument of the $find function. Next, the OnLoad method generates the script that invokes the _onSubmit method on the TextBoxWatermarkBehavior. For example, if the BehaviorID property of the TextBoxWatermarkExtenderControl is set to the string value of MyTextBoxWatermarkBehavior, the OnLoad method will generate the following script: var o = $find (‘MyTextBoxWatermarkBehavior’); if (o) o._onSubmit();
Next, the OnLoad method invokes the RegisterOnSubmitStatement static method on the ScriptManager class to have the current page to render the script into the page being sent to the client: System.Web.UI.ScriptManager.RegisterOnSubmitStatement(this, typeof(TextBoxWatermarkExtenderControl), key, script);
Finally, the OnLoad method determines whether the target server control of the TextBoxWatermarkExtenderControl server control has the focus. If so, it assigns the string value Focused to the ClientState property: ClientState = (string.Compare(Page.Form.DefaultFocus, TargetControlID, StringComparison.InvariantCultureIgnoreCase) == 0) ? “Focused” : null;
As you’ll see later, the TextBoxWatermarkExtenderControl server control will store this value of the ClientState property into the client state hidden field before the response is sent back to the client. This will allow the TextBoxWatermarkBehavior to retrieve the client state from this hidden field to determine whether the target server control has the focus. If the target server control does not have the focus, the TextBoxWatermarkBehavior displays the watermark text to the end user and applies the watermark CSS class to the text box.
760
c17.indd 760
8/20/07 6:30:09 PM
Chapter 17: Script and Extender Server Controls Listing 17-16: A Page that Directly Uses the TextBoxWatermarkBehavior . . . . . . . . . function submitCallback() { textBoxWatermarkBehavior._onSubmit(); } . . . . . .
OnPreRender The TextBoxWatermarkExtenderControl server control overrides the OnPreRender method as shown in Listing 17-15. This method begins by invoking the OnPreRender method of its base class to raise the PreRender event and consequently to invoke all the event handlers registered for the PreRender event of the TextBoxWatermarkExtenderControl server control: base.OnPreRender(e);
Next, it invokes the FindControl method, passing in the value of the TargetControlID property to return a reference to the target server control of the TextBoxWatermarkExtenderControl. Recall that the target server control of an extender server control is a server control whose client-side functionality the extender server control extends, which is the ASP.NET TextBox server control in this case: Control targetControl = base.FindControl(TargetControlID);
If the FindControl method returns null, the OnPreRender method invokes the FindControl method on the naming container of the TextBoxWatermarkExtenderControl, passing in the value of the TargetControlID property to return a reference to the target server control. The OnPreRender method keeps repeating this process until it reaches the first naming container in the naming container hierarchy of the TextBoxWatermarkExtenderControl whose FindControl method returns a
761
c17.indd 761
8/20/07 6:30:09 PM
Chapter 17: Script and Extender Server Controls non-null value, that is, until it finally accesses the reference to the target server control. Repeating this process is necessary because the FindControl method only searches the server controls in the current naming container. Control targetControl = base.FindControl(TargetControlID); Control nc = NamingContainer; while ((targetControl == null) && (nc != null)) { targetControl = nc.FindControl(TargetControlID); nc = nc.NamingContainer; }
You may be wondering how the target server control of the TextBoxWatermarkExtenderControl server control (the TextBox server control) is not in the same naming container as the TextBoxWatermarkExtenderControl server control. The answer lies in the fact that the TextBox server control could be a child control of a composite server control that implements the INamingContainer interface. Since the logic discussed in the code listing repeats the call into the FindControl method until it locates the naming container that contains the target server control, you can rest assured that the target server control will eventually be located. Next, the OnPreRender method invokes the FindControl method on the naming container of the TextBoxWatermarkExtenderControl server control, passing in the value of the ClientStateFieldID property to return a reference to the hidden field where the client state must be stored: hiddenField = (HiddenField)NamingContainer.FindControl(ClientStateFieldID);
You may be wondering why this time around we’re not searching through all the ancestor naming containers of the TextBoxWatermarkExtenderControl server control. This is because the CreateClientStateField method creates and adds the hidden field in the naming container of the TextBoxWatermarkExtenderControl server control. In other words, we’re one hundred percent sure that this hidden field is in the naming container of the TextBoxWatermarkExtenderControl server control. If it is not in this naming container, it simply has not been created yet. That is why the OnPreRender method invokes the CreateClientStateField method when the current naming container does not include the specified hidden field to create the hidden field. This is one of the features of the FindControl method that you must take into account when you’re using this method in your own code to locate a server control. The FindControl method is designed to search only through the server controls in the current naming container. It does not search through the server controls in other naming containers. The FindControl method is designed this way on purpose to allow you to limit the search to the current naming container and consequently improve the performance of your application. If you know for a fact that the control that you’re looking for belongs to a specific naming container, you must invoke the FindControl method on that naming container to limit the search to that naming container. Finally, the OnPreRender method stores the value of the ClientState property in this hidden field before the response is sent back to the client: if (hiddenField != null) hiddenField.Value = ClientState;
762
c17.indd 762
8/20/07 6:30:09 PM
Chapter 17: Script and Extender Server Controls
Render As Listing 17-15 shows, the TextBoxWatermarkExtenderControl server control overrides the Render method to make a call to the VerfyRenderingInServerForm method of the current page to ensure that the TextBoxWatermarkExtenderControl server control has been declared within a form DOM element whose runat attribute is set to the string value server. A form DOM element with the runat=”server” attribute is known as server form. One of the fundamental artichitectural aspects of the ASP.NET Framework is that every page can contain only one server form, that is, only one form DOM element on the page can have the runat=”server” attribute.
Using the Extender Server Control Add a new source file named TextBoxWatermarkExtenderControl.cs to the App_Code directory of the same Web application that contains the replica components developed earlier in this chapter and add the code shown in Listing 17-15 to this source file. Next, add a new Web page named TextBoxWatermarkExtenderControl.aspx to this application and add the code shown in Listing 17-17 to this page. As you can see, this page uses the TextBoxWatermarkExtenderControl server control developed in the previous sections. Note that this page contains both the standard ASP.NET AJAX ScriptManager server control and the replica ScriptManager server control. This is because the replica does not implement every single feature of the standard ASP.NET ScriptManager server control. It just implements those features that relate to extender and script server controls. As such, this page uses the standard ASP.NET AJAX ScriptManager server control for other features such as downloading the main JavaScript files, such as MicrosoftAjax.js and so on.
Listing 17-17: A Page that Uses the TextBoxWatermarkExtenderControl Server Control void ClickCallback(object sender, EventArgs e) { Info.Text = TextBox1.Text; } Untitled Page .WatermarkCssClass { background-color: #dddddd }
(continued)
763
c17.indd 763
8/20/07 6:30:10 PM
Chapter 17: Script and Extender Server Controls Listing 17-17 (continued)
Developing a Script Control As you saw in the previous section, the TextBoxWatermarkExtenderControl server control encapsulates the logic that the boldfaced portions of Listing 17-14 implement and presents developers with an object-oriented ASP.NET based API that allows them to use the same imperative and declarative ASP.NET techniques to program against the underlying TextBoxWatermark behavior. Another approach to encapsulating the logic that the boldfaced portions of Listing 17-14 implement is to develop a script server control. In this section, I’ll implement a script server control named TextBoxWatermarkScriptControl that does what the TextBoxWatermarkExtenderControl does, that is, it encapsulates the logic that the boldfaced portions of Listing 17-14 implement and presents developers with an object-oriented ASP.NET based API that allows them to use the same imperative and declarative ASP.NET techniques to program against the underlying TextBoxwatermark behavior. Listing 17-18 presents the implementation of the TextBoxWatermarkScriptControl server control. As you can see, this control derives from the ASP.NET TextBox server control and implements the IScriptControl interface. You may be wondering why we don’t derive the TextBoxWatermarkScriptControl server control from the ScriptControl base class to save ourselves from having to implement the base functionality that the ScriptControl base class already supports. The answer lies in the fact that object-oriented languages such as C# and VB.NET do not support multiple class inheritances. In other words, the TextBoxWatermarkScriptControl server control cannot derive from both the TextBox and ScriptControl classes. We have two options here. One option is to derive the
764
c17.indd 764
8/20/07 6:30:10 PM
Chapter 17: Script and Extender Server Controls TextBoxWatermarkScriptControl server control from the ScriptControl base class and implement the functionality that the TextBox server control already supports. Another option is to derive the TextBoxWatermarkScriptControl server control from the TextBox server control and implement the functionality that the ScriptControl server control already supports. As you can see, both options require you to implement functionality that an existing ASP.NET server control already supports. Which option you choose is completely up to you and very much depends on which option requires less coding. In this case it is somewhat easier to implement the functionality that the ScriptControl server control supports than the functionality that the TextBox server control supports.
There are two ways to implement the functionality that an existing server control provides. One approach is to have the TextBoxWatermarkScriptControl server control compose the ScriptControl server control and delegate to this control. This is known as object composition in object-oriented jargon and composite controls in ASP.NET jargon. Another approach is to implement the functionality from scratch. The object composition approach is not possible in this case because the ScriptControl server control is an abstract class and cannot be instantiated. Comparision of Listings 17-18 and 17-15 shows that the TextBoxWatermarkScriptControl exposes some of the same properties and methods that the TextBoxWatermarkExtenderControl exposes. In the following sections, I’ll discuss the implementation of only those methods and properties of the TextBoxWatermarkScriptControl server control that are different from the TextBoxWatermarkExtenderControl.
Listing 17-18: The TextBoxWatermarkScriptControl using using using using using using using using
PreRender As you can see from Listing 17-18, the TextBoxWatermarkScriptControl server control overrides the OnPreRender method of its base class to perform these tasks. First, it invokes the GetCurrent static
768
c17.indd 768
8/20/07 6:30:11 PM
Chapter 17: Script and Extender Server Controls method on the ScriptManager class to return a reference to the current ScriptManager server control on the current page: ScriptManager sm = ScriptManager.GetCurrent(Page);
Next, it invokes the RegisterScriptControl method on the current ScriptManager server control to register the TextBoxWatermarkScriptControl server control with the current ScriptManager server control. As discussed earlier, this method simply adds the specified TextBoxWatermarkScriptControl server control to an internal collection named ScriptControls: sm.RegisterScriptControl(this);
Next, the OnPreRender method invokes the OnPreRender method of its base class to raise the PreRender event and consequently invokes all the event handlers registered for this event: base.OnPreRender(e);
Next, it invokes the FindControl method on the naming container of the TextBoxWatermarkScriptControl server control, passing in the value of the ClientStateFieldID property to return a reference to the hidden field that contains the client state: hiddenField = (HiddenField)NamingContainer.FindControl(ClientStateFieldID);
Finally, it stores the value of the ClientState property in this hidden field: if (hiddenField != null) hiddenField.Value = ClientState;
Render As Listing 17-18 shows, the TextBoxWatermarkScriptControl overrides the Render method of its base class, where it accesses the current ScriptManager server control: ScriptManager sm = ScriptManager.GetCurrent(Page);
Next, it invokes the RegisterScriptDescriptors method on the current ScriptManager server control to register the ScriptDescriptor object associated with the TextBoxWatermarkScriptControl server control: sm.RegisterScriptDescriptors(this);
Using the Script Server Control Add a new source file named TextBoxWatermarkScriptControl.cs to the App_Code directory of the same Web application that contains the replica components developed earlier in this chapter and add the code shown in Listing 17-18 to this source file. Next, add a new Web page named TextBoxWatermarkScriptControl.aspx to this application and add the code shown in Listing 17-19 to this page. As you can see, this page uses the TextBoxWatermarkScriptControl server control developed in the previous sections.
769
c17.indd 769
8/20/07 6:30:11 PM
Chapter 17: Script and Extender Server Controls Listing 17-19: A Page that Uses the TextBoxWatermarkScriptControl void ClickCallback(object sender, EventArgs e) { Info.Text = TextBoxWatermarkScriptControl1.Text; } Untitled Page .WatermarkCssClass { background-color: #dddddd }
Script Ser ver Controls versus Extender Ser ver Controls You may be wondering what the differences are between script and extender server controls considering the fact that both types of controls serve the same purpose, that is, they both encapsulate the logic such as the one that the boldfaced portions of Listing 17-14 implement and present the page developers with an object-oriented ASP.NET based API that allows them to use the same imperative and declarative ASP.NET techniques to program against the underlying ASP.NET AJAX component.
770
c17.indd 770
8/20/07 6:30:12 PM
Chapter 17: Script and Extender Server Controls The main difference between a script server control and an extender server control is that while the extender server control extends the client-side functionality of an existing ASP.NET server control, the script server control defines a new server control that directly includes this client-side functionality. This means that you can attach the same extender server control to different server controls to enhance their client-side functionality. However, the functionality contained in a script server control only applies to the script server control itself and cannot be attached to other server controls. Therefore, if you’re implementing a functionality that can be used by lot of other server controls, you may want to encapsulate this functionality in an extender server control that can be attached to other server controls. However, if you’re implementing a functionality that does not make sense to apply to other server controls, you may want to encapsulate this functionality in a script server control.
Summar y This chapter first implemented fully functional replicas of those components of the ASP.NET AJAX server side Framework that play important roles in the internal working of script and extender server controls. Then, it used practical examples to teach you how to implement your own custom script and extender server controls. The next chapter will implement a custom script server control that uses a Web services bridge to communicate with Amazon Web services.
771
c17.indd 771
8/20/07 6:30:12 PM
c17.indd 772
8/20/07 6:30:12 PM
Web Ser vices Bridges and Transformers This chapter will first provide an overview of the Amazon E-Commerce Web service. It will then implement a script server control that uses a Web services bridge to invoke a specified Web method of this Web service and display the results to end users. Finally, I will provide an in-depth coverage of ASP.NET AJAX transformers.
Amazon Web Ser vices At the end of Chapter 14, I promised that I’d present a more complete example of Web services bridges. In this chapter you’ll learn how to develop a custom script server control that uses a bridge to enable the client code to interact with the Amazon Web services. Before diving into the implementation of this custom script server control you need to do the following things:
❑
Visit the Amazon Web service site at www.amazon.com/gp/aws/landing.html and follow the instructions on this site to create an Amazon Web service account and get an access key. As you’ll see later, you have to include this access key with every single call that you make to the Amazon Web services. This site comes with the complete documentation and sample code for using the Amazon Web services.
❑
Acquire a good understanding of the Amazon Web services. In particular, we’re interested in the Amazon E-Commerce Web service (AWSECommerceService), a particular Web method of this Web service named ItemSearch, and a particular set of parameters of this Web method. Therefore, in this chapter we’ll focus on these items. Complete coverage of the Amazon Web services is beyond the scope of this book.
The following code listing presents the declaration of the Amazon E-Commerce Web service: public class AWSECommerceService { public ItemSearchResponse ItemSearch(ItemSearch ItemSearch1); }
c18.indd 773
8/20/07 7:56:06 PM
Chapter 18: Web Services Bridges and Transformers As you can see, the ItemSearch method takes an argument of type ItemSearch and returns an object of type ItemSearchResponse. I’ll discuss the ItemSearch and ItemSearchResponse types in the following sections.
ItemSearch The ItemSearch type or class is defined in Listing 18-1. As you can see, this class exposes two important properties, SubscriptionId and Request. As the name suggests, the SubscriptionId property is a string that contains your Amazon access key or subscription ID. The Request property references the ItemSearchRequest object that represents a request to the Amazon service.
Listing 18-1: The ItemSearch Class public class ItemSearch { public string SubscriptionId {get; set;} public ItemSearchRequest Request {get; set;} }
Listing 18-2 defines the ItemSearchRequest type or class. As you can see, this class contains four properties:
❑
ItemPage, a positive integer number. This is basically the index of the page that we want to
download from the Web service. Since there could be thousands of records for our query keyword, we need to specify which page of records we’re interested in. If you don’t specify the page index, the first page of records is returned by default.
❑
Keywords, a string that contains our query.
❑
ResponseGroup, a string that contains certain of our search criteria, as you’ll see in the
following example.
❑
SearchIndex, a string that contains the type of the query. For example, if you pass Books as the SearchIndex parameter into the ItemSearch Web method, you’re telling this method that
you’re searching for books.
Listing 18-2: The ItemSearchRequest Class public class ItemSearchRequest { public int ItemPage {get; set;} public string Keywords {get; set;} public string ResponseGroup {get; set;} public string SearchIndex {get; set;} }
Listing 18-3 defines the ItemSearchResponse class, which exposes an array property of type Items named Items.
774
c18.indd 774
8/20/07 7:56:07 PM
Chapter 18: Web Services Bridges and Transformers Listing 18-3: The ItemSearchResponse Class public class ItemSearchResponse { public Items[] Items { get; set;} }
Listing 18-4 defines the Items type, which exposes an array property of type Item named Item.
Listing 18-4: The Items Class public class Items { public Item[] Item { get; set; } }
As you can see from Listing 18-5, the Item type or class exposes four properties:
❑
DetailPageURL, a string that contains the URL of the page with more detailed information about the item. For example, if the item represents a book, this URL takes the end user to the page that provides more detailed information about the book.
❑
MediumImage, which is of type Image.
❑
ItemsAttributes and Offers, which you’ll learn about later in the chapter.
Listing 18-5: The Item Class public partial class Item { public string DetailPageURL {get; set; } public Image MediumImage {get; set;} public ItemAttributes ItemAttributes {get; set;} public Offers Offers {get; set;} }
As Listing 18-6 shows, the Image type or class exposes a string property named URL, which contains the URL of the image associated with the item. For example, if the item is a book, this is the URL of the image of the book.
Listing 18-6: The Image Class public partial class Image { public string URL {get; set;} }
As Listing 18-7 shows, the Offers type exposes an array property named Offer that contains objects of type Offer.
775
c18.indd 775
8/20/07 7:56:07 PM
Chapter 18: Web Services Bridges and Transformers Listing 18-7: The Offers Class public partial class Offers { public Offer[] Offer {get; set;} }
As you can see from Listing 18-8, the Offer type exposes an array property named OfferListing that contains an object of type OfferListing.
Listing 18-8: The Offer Class public partial class Offer { public OfferListing[] OfferListing {get; set;} }
As Listing 18-9 shows, the OfferListing type or class exposes a property of type Price named Price.
Listing 18-9: The OfferListing Class public partial class OfferListing { public Price Price {get; set;} }
As you can see from Listing 18-10, the Price type exposes a property of type string named FormattedPrice.
Listing 18-10: The Price Class public class Price { public string FormattedPrice { get; set; } }
As Listing 18-11 shows, the ItemAttributes type exposes a string property named Author, a property of type Price named ListPrice, and a string property named Title.
Listing 18-11: The ItemAttributes Class public class ItemAttributes { public string[] Author { get;set;} public Price ListPrice { get; set;} public string ProductGroup { get; set;} public string Title { get; set;} }
776
c18.indd 776
8/20/07 7:56:08 PM
Chapter 18: Web Services Bridges and Transformers Now that you have a good understanding of the AWSECommerceService Web service, its ItemSearch Web method, the names and types of parameters you need to pass into this Web method, and the type of return value you should expect to receive from it, we’re ready to use this Web service. As you learned from the WSDL document, you need to make a HTTP SOAP request to the http://soap.amazon.com/onca/soap?Service=AWSECommerceService URL to invoke the ItemSearch Web method. You could go ahead and write the SOAP message yourself, but then you would have to get involved in the dirty little details of SOAP messaging. A better approach is to generate the code for a class known as proxy that hides the underlying SOAP messaging and enables you to program against the remote Web service object as if you were programming against a local object. There are different ways to create the proxy class. If you’re working in the Visual Studio environment, you have the following options:
❑
Launch the Add Web References dialog, navigate to http://webservices.amazon.com/ AWSECommerceService/AWSECommerceService.wsdl and click the Add Reference button to add a reference to the AWSECommerceService Web service. This will automatically download the AWSECommerceService.wsdl WSDL document from the amazon.com site, create the code for the proxy class, compile the proxy class into an assembly, and add a reference to the assembly.
❑
Download the AWSECommerceService.wsdl WSDL document from http://webservices .amazon.com/AWSECommerceService/AWSECommerceService.wsdl and store the WSDL file in your favorite directory on your machine. If you’re using the built-in Web server, launch the Add Web Reference dialog and follow the same steps as in the previous item, but this time navigate to the directory where the WSDL file is located. The URL should look something like the following:
file:///d:/download/AWSECommerceService.wsdl
❑
If you’re using IIS, you have to copy the AWSECommerceService.wsdl document to the root directory of your application. The path to this directory should look something like C:\Inetpub\wwwroot\ApplicationRoot. Then launch the Add Web References dialog and follow the steps discussed in the previous item to navigate to the application root where the WSDL document is located. The URL for the WSDL document should look something like this:
If you’re using App_Code directory, copy the AWSECommerceService.wsdl document to this directory. That’s it. The Visual Studio automatically generates the code for the proxy, compiles the proxy code into an assembly, and adds a reference to the assembly.
If you’re not working in the Visual Studio environment, and you like to do things from the command line, first download the AWSECommerceService.wsdl document from http://webservices .amazon.com/AWSECommerceService/AWSECommerceService.wsdl and store the document in a file in your favorite directory. Go to this directory and use the following command to generate the code for the proxy class and to save the code to the AWSECommerceService.cs file (give it any name you wish): wsdl /out:AWSECommerceService.cs AWSECommerceService.wsdl
777
c18.indd 777
8/20/07 7:56:08 PM
Chapter 18: Web Services Bridges and Transformers The wsdl.exe tool comes with different options. For example, you can use /namespace: AWSECommerceService to specify your desired namespace for the proxy class. Then use the following command to compile the AWSECommerceService.cs into the AWSECommerceService.dll assembly and use the assembly as you would use any other: csc /t:library /out: AWSECommerceService.dll AWSECommerceService.cs
Since we want to use the ASP.NET AJAX Web services bridges to enable our client-side code to invoke the ItemSearch Web method of the AWSECommerceService Web service, first we need to create and add an .asbx file to our application. (These files were thoroughly discussed earlier in this book.) Listing 18-12 presents the content of an .asbx file named AmazonSearch.asbx that we will use in our example. This file instructs the ASP.NET AJAX framework to generate a client-side proxy class named AmazonService that belongs to a namespace named MyServices and contains a method named Search that takes two parameters, pageIndex and searchQuery. The pageIndex parameter specifies the page of records being retrieved and the searchQuery parameter specifies the search keywords.
Listing 18-12: The AmazonSearch.asbx File
As Listing 18-12 shows, this bridge is a wrapper around a .NET class named AmazonService that belongs to a namespace called CustomComponents3 and is located in the App_Code directory of the current application. Listing 18-13 presents the implementation of this class. Store this code listing in a file named AmazonService.cs and add the file to the App_Code directory.
Listing 18-13: The AmazonService Class using using using using using using using using using using using using using
namespace CustomComponents3 { public class AmazonService
778
c18.indd 778
8/20/07 7:56:08 PM
Chapter 18: Web Services Bridges and Transformers { public Items Search(int pageIndex, string searchQuery) { ItemSearchRequest itemSearchRequest = new ItemSearchRequest(); itemSearchRequest.Keywords = searchQuery; itemSearchRequest.SearchIndex = “Books”; itemSearchRequest.ResponseGroup = new string[] { “Small”, “Images”, “ItemAttributes”, “OfferFull” }; itemSearchRequest.ItemPage = pageIndex.ToString(); ItemSearch itemSearch = new ItemSearch(); itemSearch.SubscriptionId = ConfigurationManager.AppSettings[“SubscriptionID”]; itemSearch.AssociateTag = “”; itemSearch.Request = new ItemSearchRequest[1] { itemSearchRequest }; ItemSearchResponse itemSearchResponse; try { AWSECommerceService amazonService = new AWSECommerceService(); itemSearchResponse = amazonService.ItemSearch(itemSearch); } catch (Exception e) { throw e; } Items[] itemsResponse = itemSearchResponse.Items; // Check for errors in the reponse if (itemsResponse == null) throw new Exception(“Response from amazon.com contains not items!”); if (itemsResponse[0].Request.Errors != null) throw new Exception( “Response from amazon.com contains this error message: “ + itemsResponse[0].Request.Errors[0].Message); Items items = itemsResponse[0]; return items; } } }
As you can see from Listing 18-13, the AmazonService class exposes a single method named Search that performs these tasks. First, it instantiates an ItemSearchRequest object: ItemSearchRequest itemSearchRequest = new ItemSearchRequest();
Next, it assigns the search query to the Keywords property of this object. For example, the search query could be the string asp.net. itemSearchRequest.Keywords = searchQuery;
779
c18.indd 779
8/20/07 7:56:09 PM
Chapter 18: Web Services Bridges and Transformers Then, it assigns the string Books to the SearchIndex property of the ItemSearchRequest object to instruct the Amazon Web service that the end user is searching for books. For example, if the search query is the string asp.net and the search index is the string Books, the Amazon Web service will return the list of books on ASP.NET: itemSearchRequest.SearchIndex = “Books”;
Next, it assigns the specified array of strings to the ResponseGroup property of the ItemSearchRequest object: itemSearchRequest.ResponseGroup = new string[] { “Small”, “Images”, “ItemAttributes”, “OfferFull” };
Then it specifies the page of records that the Amazon Web service should return. For example, if the search query is the string asp.net, the search index is the string Books, and the page index is 4, the Amazon Web service will return the fourth page of records, where each record describes an ASP.NET book: itemSearchRequest.ItemPage = pageIndex.ToString();
Next, the Search method instantiates an ItemSearch object: ItemSearch itemSearch = new ItemSearch();
Then it assigns the access key to the SubscriptionId property of this ItemSearchObject. As discussed earlier, you need to create an Amazon Web services account and get an access key. For security reasons, you may want to store your access key in the appSettings section of the web.config file. The great thing about doing this is that the ASP.NET framework enables you to encrypt selected sections of the web.config file to protect your data. You can then use your access key through the AppSettings static collection property of the ConfigurationManager class: itemSearch.SubscriptionId = ConfigurationManager.AppSettings[“SubscriptionID”];
Next, the Search method assigns an array that contains the previously instantiated and initialized ItemSearchRequest object to the Request property of the ItemSearch object: itemSearch.Request = new ItemSearchRequest[1] { itemSearchRequest };
Then it instantiates an instance of the AWSECommerceService proxy class: AWSECommerceService amazonService = new AWSECommerceService();
Next, it invokes the ItemSearch method of the proxy class, passing in the ItemSearch object: ItemSearchResponse itemSearchResponse = amazonService.ItemSearch(itemSearch);
The ItemSearch method returns an ItemSearchResponse object that contains the server response data. As discussed earlier, this object exposes an array property named Items that contains an object of type Items: Items[] itemsResponse = itemSearchResponse.Items;
780
c18.indd 780
8/20/07 7:56:09 PM
Chapter 18: Web Services Bridges and Transformers Finally, the Search method returns the first Items object in the Items collection property: Items items = itemsResponse[0]; return items;
Developing Web Ser vices Bridge-Enabled Script Ser ver Controls Next, I’ll present and discuss the implementation of a custom ASP.NET AJAX script server control that uses the AWSECommerceService Web service to search the amazon.com site for books that meet particular search criteria. This involves implementing the following four components:
❑
AspNetAjaxAmazonSearch: An ASP.NET AJAX client control that uses the ASP.NET AJAX Web services bridges to invoke the ItemSearch Web method of the AWSECommerceService Web service
❑
AmazonSearchScriptControl: An ASP.NET script server control that encapsulates the logic,
enabling page developers to use the same imperative and declarative ASP.NET techniques to program against the underlying AspNetAjaxAmazonSearch ASP.NET AJAX client-side control
❑
HtmlGenerator: An ASP.NET AJAX client-side component that displays the results returned from the call into the ItemSearch Web method of the AWSECommerceService Web service
❑
HtmlGeneratorScriptControl: An ASP.NET script server control that encapsulates the logic,
enabling page developers to use the same imperative and declarative ASP.NET techniques to program against the underlying HtmlGenerator ASP.NET AJAX client-side component
AspNetAjaxAmazonSearch Listing 18-14 presents the implementation of the AspNetAjaxAmazonSearch client control. I’ll discuss the methods and properties of this control in the following sections.
Listing 18-14: The AspNetAjaxAmazonSearch Client-side Control Type.registerNamespace(“CustomComponents3”); CustomComponents3.AspNetAjaxAmazonSearch = function CustomComponents3$AspNetAjaxAmazonSearch(associatedElement) { CustomComponents3.AspNetAjaxAmazonSearch.initializeBase(this, [associatedElement]); } function CustomComponents3$AspNetAjaxAmazonSearch$get_searchTextBox() { return this._searchTextBox; } function CustomComponents3$AspNetAjaxAmazonSearch$set_searchTextBox(value) {
(continued)
781
c18.indd 781
8/20/07 7:56:09 PM
Chapter 18: Web Services Bridges and Transformers Listing 18-14 (continued) this._searchTextBox = value; } function CustomComponents3$AspNetAjaxAmazonSearch$get_searchButton() { return this._searchButton; } function CustomComponents3$AspNetAjaxAmazonSearch$set_searchButton(value) { this._searchButton = value; } function CustomComponents3$AspNetAjaxAmazonSearch$get_htmlGenerator() { return this._htmlGenerator; } function CustomComponents3$AspNetAjaxAmazonSearch$set_htmlGenerator(value) { this._htmlGenerator = value; } function CustomComponents3$AspNetAjaxAmazonSearch$get_searchResultAreaDiv() { return this._searchResultAreaDiv; } function CustomComponents3$AspNetAjaxAmazonSearch$set_searchResultAreaDiv(value) { this._searchResultAreaDiv = value; } function CustomComponents3$AspNetAjaxAmazonSearch$get_commandBarAreaDiv() { return this._commandBarAreaDiv; } function CustomComponents3$AspNetAjaxAmazonSearch$set_commandBarAreaDiv(value) { this._commandBarAreaDiv = value; } function CustomComponents3$AspNetAjaxAmazonSearch$get_nextButton() { return this._nextButton; } function CustomComponents3$AspNetAjaxAmazonSearch$set_nextButton(value) { this._nextButton = value; }
782
c18.indd 782
8/20/07 7:56:09 PM
Chapter 18: Web Services Bridges and Transformers function CustomComponents3$AspNetAjaxAmazonSearch$get_previousButton() { return this._previousButton; } function CustomComponents3$AspNetAjaxAmazonSearch$set_previousButton(value) { this._previousButton = value; } function CustomComponents3$AspNetAjaxAmazonSearch$get_pageIndex() { return this._pageIndex; } function CustomComponents3$AspNetAjaxAmazonSearch$set_pageIndex(value) { this._pageIndex = value; } function CustomComponents3$AspNetAjaxAmazonSearch$get_searchMethod() { return this._searchMethod; } function CustomComponents3$AspNetAjaxAmazonSearch$set_searchMethod(value) { this._searchMethod = value; } function CustomComponents3$AspNetAjaxAmazonSearch$initialize() { CustomComponents3.AspNetAjaxAmazonSearch.callBaseMethod(this, “initialize”); this._searchButtonClickHandler = Function.createDelegate(this, this._onSearchButtonClick); this._nextButtonClickHandler = Function.createDelegate(this, this._onNextButtonClick); this._previousButtonClickHandler = Function.createDelegate(this, this._onPreviousButtonClick); $addHandler(this._searchButton, “click”, this._searchButtonClickHandler); $addHandler(this._nextButton, “click”, this._nextButtonClickHandler); $addHandler(this._previousButton, “click”, this._previousButtonClickHandler); this._onSuccessHandler = Function.createDelegate(this, this._onSuccess); this._onFailureHandler = Function.createDelegate(this, this._onFailure); } function CustomComponents3$AspNetAjaxAmazonSearch$_onSearchButtonClick(evt) {
(continued)
783
c18.indd 783
8/20/07 7:56:10 PM
Chapter 18: Web Services Bridges and Transformers Listing 18-14 (continued) this._pageIndex = 1; this._searchQuery = this._searchTextBox.value; this._searchMethod( {“pageIndex”: this._pageIndex, “searchQuery”: this._searchQuery}, this._onSuccessHandler, this._onFailureHandler, null); } function CustomComponents3$AspNetAjaxAmazonSearch$_onPreviousButtonClick(evt) { this._pageIndex--; if (this._pageIndex < 0) this._pageIndex = 1; this._searchQuery = this._searchTextBox.value; this._searchMethod( {“pageIndex”: this._pageIndex, “searchQuery”: this._searchQuery}, this._onSuccessHandler, this._onFailureHandler, null); } function CustomComponents3$AspNetAjaxAmazonSearch$_onNextButtonClick(evt) { this._pageIndex++; this._searchQuery = this._searchTextBox.value; this._searchMethod( {“pageIndex”: this._pageIndex, “searchQuery”: this._searchQuery}, this._onSuccessHandler, this._onFailureHandler, null); } function CustomComponents3$AspNetAjaxAmazonSearch$_onSuccess(items, userContext, methodName) { var html = this._htmlGenerator.generateHtml(items); this._searchResultAreaDiv.innerHTML = html; this._commandBarAreaDiv.style.display = “block”; this._searchResultAreaDiv.style.display = “block”; } function CustomComponents3$AspNetAjaxAmazonSearch$_onFailure(result, userContext, methodName) { var builder = new Sys.StringBuilder(); builder.append(“timedOut: “); builder.append(result.get_timedOut()); builder.appendLine(); builder.appendLine(); builder.append(“message: “); builder.append(result.get_message()); builder.appendLine();
Chapter 18: Web Services Bridges and Transformers Listing 18-14 (continued) _onSearchButtonClick: CustomComponents3$AspNetAjaxAmazonSearch$_onSearchButtonClick, _onPreviousButtonClick: CustomComponents3$AspNetAjaxAmazonSearch$_onPreviousButtonClick, _onNextButtonClick: CustomComponents3$AspNetAjaxAmazonSearch$_onNextButtonClick, _onSuccess: CustomComponents3$AspNetAjaxAmazonSearch$_onSuccess, _onFailure: CustomComponents3$AspNetAjaxAmazonSearch$_onFailure } CustomComponents3.AspNetAjaxAmazonSearch.registerClass( “CustomComponents3.AspNetAjaxAmazonSearch”, Sys.UI.Control); if (typeof(Sys) !== ‘undefined’) Sys.Application.notifyScriptLoaded();
Properties The following table describes the getters and setters associated with the properties of the AspNetAjaxAmazonSearch client control:
Getter or Setter Method
Description
get_searchTextBox
Gets a reference to the search text box DOM element
set_searchTextBox
Sets a reference to the search text box DOM element
get_searchButton
Gets a reference to the search button DOM element
set_searchButton
Sets a reference to the search button DOM element
get_htmlGenerator
Gets a reference to the HtmlGenerator client control that displays the results returned from the call into the ItemSearch Web method of the AWSECommerceService Web service
set_htmlGenerator
Sets a reference to the HtmlGenerator client control that displays the results returned from the call into the ItemSearch Web method of the AWSECommerceService Web service
get_searchResultAreaDiv
Gets a reference to the div DOM element that displays the search result
set_searchResultAreaDiv
Sets a reference to the div DOM element that displays the search result
get_commandBarAreaDiv
Gets a reference to the div DOM element that displays the command bar
set_commandBarAreaDiv
Sets a reference to the div DOM element that displays the command bar
786
c18.indd 786
8/20/07 7:56:11 PM
Chapter 18: Web Services Bridges and Transformers Getter or Setter Method
Description
get_nextButton
Gets a reference to the next button DOM element
set_nextButton
Sets a reference to the next button DOM element
get_previousButton
Gets a reference to the previous button DOM element
set_previousButton
Sets a reference to the previous button DOM element
get_pageIndex
Gets the current page index
set_pageIndex
Sets the current page index
get_searchMethod
Gets a reference to the search method
set_searchMethod
Sets the reference to the search method
initialize As you can see from Listing 18-14, the AspNetAjaxAmazonSearch client control overrides the initialize method that it inherits from its base class, where it performs the following tasks. First, it uses the callBaseMethod method to invoke the initialize method of the base class to allow the base class to initialize itself: CustomComponents3.AspNetAjaxAmazonSearch.callBaseMethod(this, “initialize”);
Next, it creates three delegates to represents the _onSearchButtonClick, _onNextButtonClick, and _onPreviousButtonClick methods and stores these delegates in private fields named _searchButtonClickHandler, _nextButtonClickHandler, and _previousButtonClickHandler, respectively: this._searchButtonClickHandler = Function.createDelegate(this, this._onSearchButtonClick); this._nextButtonClickHandler = Function.createDelegate(this, this._onNextButtonClick); this._previousButtonClickHandler = Function.createDelegate(this, this._onPreviousButtonClick);
Then it registers the above delegates as event handlers for the click events of the search, next, and previous button DOM elements, respectively. Therefore, when the end user clicks one of these buttons, the associated delegate and consequently the method that the delegate represents is automatically invoked: $addHandler(this._searchButton, “click”, this._searchButtonClickHandler); $addHandler(this._nextButton, “click”, this._nextButtonClickHandler); $addHandler(this._previousButton, “click”, this._previousButtonClickHandler);
Finally, the AspNetAjaxAmazonSearch client control creates two more delegates to represent the _onSuccess and _onFailure methods and stores them in _onSuccessHandler and _onFailureHandler private fields, respectively: this._onSuccessHandler = Function.createDelegate(this, this._onSuccess); this._onFailureHandler = Function.createDelegate(this, this._onFailure);
787
c18.indd 787
8/20/07 7:56:11 PM
Chapter 18: Web Services Bridges and Transformers _onSearchButtonClick As Listing 18-14 shows, this method first reset the current page index to 1 because we’re about to make a new search query for which we need to download the first page of the search results: this._pageIndex = 1;
Next, it retrieves the search query from the search text box DOM element and stores it in a private field named _searchQuery: this._searchQuery = this._searchTextBox.value;
Finally, it invokes the search method, passing in four parameters. The first parameter is an object literal that describes the names and values of the parameters of the Web method being invoked. In our case, the Web method expects two parameters, pageIndex and searchQuery. The second and third parameters reference the _onSuccessHandler and _onFailureHandler delegates. Recall that these delegates respectively represent the _onSuccess and _onFailure methods. this._searchMethod( {“pageIndex”: this._pageIndex, “searchQuery”: this._searchQuery}, this._onSuccessHandler, this._onFailureHandler, null);
_onPreviousButtonClick As you can see from Listing 18-14, this method begins by decrementing the current page index because we’re moving back to the previous page: this._pageIndex--;
Next, it checks whether the new current page index is negative. If so, it resets the current page index to 1: if (this._pageIndex < 0) this._pageIndex = 1;
Then, it retrieves the search query from the search text box DOM element and stores it in the _searchQuery field: this._searchQuery = this._searchTextBox.value;
Finally, it invokes the search method, passing in the same parameters we discussed earlier: this._searchMethod( {“pageIndex”: this._pageIndex, “searchQuery”: this._searchQuery}, this._onSuccessHandler, this._onFailureHandler, null);
788
c18.indd 788
8/20/07 7:56:11 PM
Chapter 18: Web Services Bridges and Transformers _onNextButtonClick This method (see Listing 18-14) first increments the current page index because we need to download the next page of search results from the Web service: this._pageIndex++;
The next two steps are the same as in the previous example: this._searchQuery = this._searchTextBox.value; this._searchMethod( {“pageIndex”: this._pageIndex, “searchQuery”: this._searchQuery}, this._onSuccessHandler, this._onFailureHandler, null);
_onSuccess As discussed earlier, the _onSearchButtonClick, _onPreviousButtonClick, and _onNextButtonClick methods internally pass the _onSuccessHandler delegate into the _searchMethod as its second argument. This delegate represents the _onSucccess method, which means that when the search results finally arrive, the _onSuccessHandler delegate and consequently the _onSuccess method are automatically invoked. This method takes three parameters. The first parameter contains the search results, the second references the context object, and the third contains the name of the invoked method. As you can see from Listing 18-14, the _onSuccess method invokes the generateHtml instance method on the HtmlGenenrator component, passing in the search results. As you’ll see later, this method is responsible for generating and returning the HTML markup that displays the search results: var html = this._htmlGenerator.generateHtml(items);
Next, _onSuccess assigns this HTML markup to the innerHTML property of the search result area div DOM element to display the search results in this div element: this._searchResultAreaDiv.innerHTML = html;
Finally, it sets the values of the display properties of the style properties of the div elements that display the search results and command bar to “block”: this._commandBarAreaDiv.style.display = “block”; this._searchResultAreaDiv.style.display = “block”;
AmazonSearchScriptControl Listing 18-15 presents the implementation of the AmazonSearchScriptControl script server control. As I mentioned earlier, this script server control enables page developers to use familiar imperative and declarative ASP.NET techniques to program against the underlying AspNetAjaxAmazonSearch ASP.NET AJAX client-side control. I’ll discuss the methods and properties of this server control in the following sections.
789
c18.indd 789
8/20/07 7:56:11 PM
Chapter 18: Web Services Bridges and Transformers Listing 18-15: The AmazonSearchScriptControl Script Server Control using using using using using using using using using using using using using using
Chapter 18: Web Services Bridges and Transformers writer.AddAttribute(HtmlTextWriterAttribute.Id, this.ClientID + “_CommandBarArea”); writer.RenderBeginTag(HtmlTextWriterTag.Div); writer.AddAttribute(HtmlTextWriterAttribute.Type, “button”); writer.AddAttribute(HtmlTextWriterAttribute.Id, this.ClientID + “_PreviousButton”); writer.RenderBeginTag(HtmlTextWriterTag.Button); writer.Write(“>”); writer.RenderEndTag(); writer.RenderEndTag(); writer.RenderEndTag(); writer.RenderEndTag(); } protected override HtmlTextWriterTag TagKey { get { return HtmlTextWriterTag.Table; } } protected override Style CreateControlStyle() { return new TableStyle(ViewState); } public virtual int CellPadding { get { return ((TableStyle)ControlStyle).CellPadding; } set { ((TableStyle)ControlStyle).CellPadding = value; } } public virtual int CellSpacing { get { return ((TableStyle)ControlStyle).CellSpacing; } set { ((TableStyle)ControlStyle).CellSpacing = value; } } public virtual HorizontalAlign HorizontalAlign { get { return ((TableStyle)ControlStyle).HorizontalAlign; } set { ((TableStyle)ControlStyle).HorizontalAlign = value; } } public virtual string BackImageUrl {
(continued)
793
c18.indd 793
8/20/07 7:56:13 PM
Chapter 18: Web Services Bridges and Transformers Listing 18-15 (continued) get { return ((TableStyle)ControlStyle).BackImageUrl; } set { ((TableStyle)ControlStyle).BackImageUrl = value; } } public virtual GridLines GridLines { get { return ((TableStyle)ControlStyle).GridLines; } set { ((TableStyle)ControlStyle).GridLines = value; } } } }
Properties The following table describes four of the non-style properties of the AmazonSearchScriptControl script server control.
Property
Description
HtmlGeneratorID
Gets or sets the id property value of the HTML generator component, which is responsible for generating the HTML markup that displays the search results.
SearchMethod
Gets or sets the fully qualified name of the proxy method to invoke, including the name of the proxy class to which the method belongs and the complete namespace containment hierarchy to which the proxy class belongs.
Path
Gets or sets the virtual path of the JavaScript file that contains the implementation of the client control that the AmazonSearchScriptControl script server control represents.
ClientControlType
Gets or sets the fully qualified name of the client control that the AmazonSearchScriptControl script server control represents. This name must contain the complete namespace containment hierarchy of the client control.
AmazonSearchScriptControl overrides the TagKey property that it inherits from the WebControl base class to specify a table HTML element as its containing or outermost HTML element. As the name suggests, the containing HTML element of a server control is an element that contains the rest of the HTML markup that makes up the user interface of the control: protected override HtmlTextWriterTag TagKey { get { return HtmlTextWriterTag.Table; } }
Since AmazonSearchScriptControl uses a table HTML element as its containing HTML element, it also overrides the CreateControlStyle method of its base class to specify a TableStyle as a Style
794
c18.indd 794
8/20/07 7:56:13 PM
Chapter 18: Web Services Bridges and Transformers object for styling its containing HTML element. This TableStyle object enables page developers to style the containing HTML element in a strongly-typed fashion: protected override Style CreateControlStyle() { return new TableStyle(ViewState); }
Every server control that overrides the CreateControlStyle method must also expose the properties of the associated Style object as its own top-level properties. As a result, the AmazonSearchScriptControl exposes five style properties, CellPadding, CellSpacing, HorizonalAlign, BackImageUrl, and GridLines, that respectively get or set the values of the CellPadding, CellSpacing, HorizonalAlign, BackImageUrl, and GridLines properties of the underlying TableStyle object that styles the containing table HTML element of the AmazonSearchScriptControl script server control.
GetScriptDescriptors AmazonSearchScriptControl, like any other script server control, overrides the GetScriptDescriptors method of its base class, where it takes the following steps (see Listing 18-14). First, it instantiates a ScriptControlDescriptor object, passing the values of its ClientControlType and ClientID properties. Recall that the ClientControlType property contains the fully qualified name of the client control that AmazonSearchScriptControl represents: ScriptControlDescriptor descriptor = new ScriptControlDescriptor(this.ClientControlType, this.ClientID);
Next, it invokes the AddProperty method on this ScriptControlDescriptor object to specify the value of the pageIndex property of the client control that AmazonSearchScriptControl represents: descriptor.AddProperty(“pageIndex”, 1);
Then it calls the AddScriptProperty method on the ScriptControlDescriptor object to specify the value of the searchMethod property of the client control that AmazonSearchScriptControl represents. Recall that the searchMethod property references the proxy method to be invoked: descriptor.AddScriptProperty(“searchMethod”, this.SearchMethod);
Next, it calls the AddElementProperty method six times to specify the values of the searchTextBox, searchButton, searchResultAreaDiv, commandBarAreaDiv, previousButton, and nextButton properties of the client control that AmazonSearchScriptControl represents: descriptor.AddElementProperty(“searchTextBox”, this.ClientID + “_SearchTextBox”); descriptor.AddElementProperty(“searchButton”, this.ClientID + “_SearchButton”); descriptor.AddElementProperty(“searchResultAreaDiv”, this.ClientID + “_SearchResultArea”); descriptor.AddElementProperty(“commandBarAreaDiv”, this.ClientID + “_CommandBarArea”); descriptor.AddElementProperty(“previousButton”, this.ClientID + “_PreviousButton”); descriptor.AddElementProperty(“nextButton”, this.ClientID + “_NextButton”);
795
c18.indd 795
8/20/07 7:56:13 PM
Chapter 18: Web Services Bridges and Transformers Next, it calls the AddComponentProperty method on the ScriptControlDescriptor object to specify the value of the htmlGenerator property that the AmazonSearchScriptControl represents. Recall that the htmlGenerator property references the client component responsible for generating and returning the HTML markup that renders the search results: descriptor.AddComponentProperty(“htmlGenerator”, this.HtmlGeneratorID);
Finally, it instantiates and populates an array with the ScriptControlDescriptor object and returns the array to its caller: return new ScriptDescriptor[] { descriptor };
GetScriptReferences AmazonSearchScriptControl, like any other script server control, overrides the GetScriptReferences method of its base class, where it instantiates a ScriptReference object: ScriptReference reference = new ScriptReference();
Next, it assigns to the Path property of this ScriptReference object the virtual path of the JavaScript file that contains the implementation of the client control that AmazonSearchScriptControl represents: reference.Path = Path;
Finally, it instantiates and populates an array with this ScriptReference object and returns the array to its caller: return new ScriptReference[] { reference };
RenderContents AmazonSearchScriptControl, like any other WebControl subclass, overrides the RenderContents method of the WebControl base class to render its content HTML markup. The content HTML markup
of a server control is the portion of its HTML markup that goes within the opening and closing tags of its containing HTML element, which is the table HTML element in the case of AmazonSearchScriptControl. As you can see from Listing 18-14, RenderContents renders three tr HTML elements. The first tr HTML element contains the search text box and the search button: writer.RenderBeginTag(HtmlTextWriterTag.Tr); writer.RenderBeginTag(HtmlTextWriterTag.Td); writer.RenderBeginTag(HtmlTextWriterTag.Table); writer.RenderBeginTag(HtmlTextWriterTag.Tr); writer.RenderBeginTag(HtmlTextWriterTag.Td); writer.AddAttribute(HtmlTextWriterAttribute.Type, “text”); writer.AddAttribute(HtmlTextWriterAttribute.Id, ClientID + “_SearchTextBox”);
Notice that RenderContents uses the following as the value of the id HTML attributes of the text box and search button elements: ClientID + “_SearchTextBox” ClientID + “_SearchButton”
Notice also that these are the same two values that GetScriptDescriptors passes into the AddElementProperty methods that specify the values of the searchTextBox and searchButton properties of the client script that AmazonSearchScriptControl represents. Next, RenderContents renders the tr HTML element that contains the div HTML element that displays the search results: writer.RenderBeginTag(HtmlTextWriterTag.Tr); writer.AddAttribute(HtmlTextWriterAttribute.Colspan, “3”); writer.RenderBeginTag(HtmlTextWriterTag.Td); writer.AddStyleAttribute(HtmlTextWriterStyle.Display, “none”); writer.AddAttribute(HtmlTextWriterAttribute.Id, this.ClientID + “_SearchResultArea”); writer.RenderBeginTag(HtmlTextWriterTag.Div); writer.RenderEndTag(); writer.RenderEndTag(); writer.RenderEndTag();
Notice that RenderContents uses ClientID plus “_SearchResultArea” as the value of the id HTML attribute of the div HTML element that displays the search result. This value is the same one that the GetScriptDescriptors method passes into the AddElementProperty method that specifies the value of the searchResultArea property of the client control that AmazonSearchScriptControl represents. Finally, RenderContents renders the tr HTML element that contains the div HTML element that displays the command bar, which consists of the Previous and Next buttons. Again notice that the id HTML attributes of these two buttons are set to the same values that GetScriptDescriptors passes into the AddElementProperty methods that specify the values of the previousButton and nextButton properties of the client control that AmazonSearchScriptControl represents.
HtmlGenerator Listing 18-16 presents the implementation of the HtmlGenerator client component. I’ll discuss the methods and properties of this component in the following sections.
Listing 18-16: The HtmlGenerator Client Component Type.registerNamespace(“CustomComponents3”); CustomComponents3.HtmlGenerator = function CustomComponents3$HtmlGenerator() { CustomComponents3.HtmlGenerator.initializeBase(this); } function CustomComponents3$HtmlGenerator$get_tableStyle() { return this._tableStyle; } function CustomComponents3$HtmlGenerator$set_tableStyle(value) { this._tableStyle = value; } function CustomComponents3$HtmlGenerator$get_rowStyle() { return this._rowStyle; }
798
c18.indd 798
8/20/07 7:56:14 PM
Chapter 18: Web Services Bridges and Transformers function CustomComponents3$HtmlGenerator$set_rowStyle(value) { this._rowStyle = value; } function CustomComponents3$HtmlGenerator$get_alternatingRowStyle() { return this._alternatingRowStyle; } function CustomComponents3$HtmlGenerator$set_alternatingRowStyle(value) { this._alternatingRowStyle = value; } function CustomComponents3$HtmlGenerator$generateHtml(items) { var title; var author; var amazonUrl; var imageUrl; var listPrice; var price; var item; var results = items.Item; if (!results) return; var builder = new Sys.StringBuilder(); builder.append(“
”); for (var i=0; i
As the name of the setting suggests, when the UpdateMode property of an UpdatePanel server control is set to Conditional, the UpdatePanel server control updates only when one of the conditions discussed in the following sections is met.
Children as Triggers The UpdatePanel server control exposes a Boolean property named ChildrenAsTriggers, which is true by default. When this property is set to true, every asynchronous page postback originating from a server control inside the UpdatePanel server control causes the UpdatePanel server control to update. Listing 19-3 showed an example of this scenario. Listing 19-4 shows you what happens if you explicitly set the ChildrenAsTriggers property of an UpdatePanel server control to false. This code listing is a new version of Listing 19-3 in which the ChildrenAsTriggers property of the top UpdatePanel server control is set to false, as shown in the boldface portion of this code listing. If you run this code listing and click the Update button in the top UpdatePanel server control, you’ll see that this UpdatePanel server control does not update.
863
c19.indd 863
8/20/07 8:33:22 PM
Chapter 19: UpdatePanel and ScriptManager Listing 19-4: A Page that Uses ChildrenAsTriggers Property void Page_Load(object sender, EventArgs e) { // Same as Listing 19-2 }
Inclusion of One UpdatePanel in another UpdatePanel As mentioned earlier, when the UpdateMode property of an UpdatePanel server control is set to Conditional, the UpdatePanel server control updates only when one of the predefined conditions is met. I discussed one of these conditions in the preceding section. Here is the second condition. When an UpdatePanel server control updates, all its descendant UpdatePanel server controls update as well. This happens in several different scenarios, which I will discuss in the following sections.
Direct Inclusion of One UpdatePanel in another UpdatePanel In this scenario the descendant UpdatePanel server controls are directly declared inside the UpdatePanel control.
864
c19.indd 864
8/20/07 8:33:23 PM
Chapter 19: UpdatePanel and ScriptManager Listing 19-5 presents an example of the first scenario. Here UpdatePanel2 is declared directly inside UpdatePanel1. If you run this page, you should see the result shown in Figure 19-3. Now click the Update button in the parent UpdatePanel server control. Note that both parent and child UpdatePanel server controls are updated. Now click the Update button in the child UpdatePanel server control. Note that only the child UpdatePanel server control is updated.
Listing 19-5: An Example of the Scenario where One UpdatePanel Contains Another UpdatePanel void Page_Load(object sender, EventArgs e) { string text = “Refreshed at “ + DateTime.Now.ToString(); UpdatePanel1Label.Text = text; UpdatePanel2Label.Text = text; NonPartiallyUpdatableLabel.Text = text; } Untitled Page
Parent UpdatePanel Server Control (UpdatePanel1)
(continued)
865
c19.indd 865
8/20/07 8:33:23 PM
Chapter 19: UpdatePanel and ScriptManager Listing 19-5 (continued)
Child UpdatePanel Server Control(UpdatePanel2)
866
c19.indd 866
8/20/07 8:33:23 PM
Chapter 19: UpdatePanel and ScriptManager
Non Partially Updatable Portion
Figure 19-3
867
c19.indd 867
8/20/07 8:33:23 PM
Chapter 19: UpdatePanel and ScriptManager Indirect Inclusion of One UpdatePanel in Another UpdatePanel via a User Control This scenario occurs when an UpdatePanel server control is part of a user control that is added to another UpdatePanel server control. Listing 19-6 contains a user control that encapsulates an UpdatePanel server control.
Listing 19-6: A User Control that Encapsulates an UpdatePanel Server Control void Page_Load(object sender, EventArgs e) { UpdatePanel2Label.Text = “Refreshed at “ + DateTime.Now.ToString(); }
User Control
UpdatePanel Server Control
868
c19.indd 868
8/20/07 8:33:24 PM
Chapter 19: UpdatePanel and ScriptManager Listing 19-7 presents a page where this user control is added within an UpdatePanel server control that acts as the parent of this user control.
Listing 19-7: A Page that Uses the User Control from Listing 19-6 void Page_Load(object sender, EventArgs e) { string text = “Refreshed at “ + DateTime.Now.ToString(); UpdatePanel1Label.Text = text; NonPartiallyUpdatableLabel.Text = text; } Untitled Page
Parent UpdatePanel Server Control
(continued)
869
c19.indd 869
8/20/07 8:33:24 PM
Chapter 19: UpdatePanel and ScriptManager Listing 19-7 (continued)
Non Partially Updatable Portion
If you run the page in Listing 19-7, you should get the result shown in Figure 19-4. Now click the Update button in the parent UpdatePanel server control. Note that both the parent UpdatePanel server control and the UpdatePanel server control defined as part of the user control are updated.
870
c19.indd 870
8/20/07 8:33:24 PM
Chapter 19: UpdatePanel and ScriptManager
Figure 19-4
Indirect Inclusion of an UpdatePanel in Another UpdatePanel via a Content Page The third scenario occurs when the following conditions are met:
❑
A master page includes an UpdatePanel server control that contains a ContentPlaceHolder server control.
❑
A content page includes a Content server control, associated with the above ContentPlaceHolder server control, which contain one or more UpdatePanel server controls.
Listing 19-8 shows a master page that includes an UpdatePanel server control that contains a ContentPlaceHolder server control.
871
c19.indd 871
8/20/07 8:33:24 PM
Chapter 19: UpdatePanel and ScriptManager Listing 19-8: A Master Page that Includes an UpdatePanel Server Control void Page_Load(object sender, EventArgs e) { string text = “Refreshed at “ + DateTime.Now.ToString(); UpdatePanel1Label.Text = text; NonPartiallyUpdatableLabel.Text = text; }
Untitled Page
Parent UpdatePanel Server Control
872
c19.indd 872
8/20/07 8:33:25 PM
Chapter 19: UpdatePanel and ScriptManager
Non Partially Updatable Portion
Listing 19-9 shows a content page that contains a Content server control associated with the ContentPlaceHolder server control specified within the UpdatePanel server control shown in Listing 19-8. Note that this Content server control contains an UpdatePanel server control. If you run this page, you’ll get the result shown in Figure 19-5. Note that if you click the Update button in the master UpdatePanel server control, it automatically updates the UpdatePanel server control declared in the content page.
Listing 19-9: A Content Page that Uses the Master Page from Listing 19-8 void Page_Load(object sender, EventArgs e) { UpdatePanel2Label.Text = “Refreshed at “ + DateTime.Now.ToString(); }
Content Page
873
c19.indd 873
8/20/07 8:33:25 PM
Chapter 19: UpdatePanel and ScriptManager Listing 19-9 (continued)
UpdatePanel Server Control
Note also that this example declares the ScriptManager server control on the master page, which means that all content pages that use this master page will automatically inherit this ScriptManager server control. The side effect of this approach is that the partial page rendering is automatically enabled for all content pages that use this master page. If this is not what you want, do one of the following:
❑
Programmatically disable the partial page rendering for the desired content pages (see Listing 19-10).
❑
Declare a separate ScriptManager server control on each content page instead of declaring the ScriptManager server control on the master page. Keep in mind that if you choose to declare ScriptManager server controls on content pages, you mustn’t declare a ScriptManager server control on the master page. This is because when you access a content page from your browser, the ASP.NET merges the content and master pages together, which means that they form a single page. As I mentioned earlier, every page can contain only a single instance of the ScriptManager server control.
874
c19.indd 874
8/20/07 8:33:25 PM
Chapter 19: UpdatePanel and ScriptManager
Figure 19-5
The boldface portion of Listing 19-10 shows how to programmatically disable partial page rendering for a specific content page. As this portion demonstrates, you must disable partial page rendering in the Init life-cycle phase of the current page.
875
c19.indd 875
8/20/07 8:33:25 PM
Chapter 19: UpdatePanel and ScriptManager Listing 19-10: Disabling Partial Page Rendering for a Content Page void Page_Init(object sender, EventArgs e) { ScriptManager sm = ScriptManager.GetCurrent(this.Page); sm.EnablePartialRendering = false; } void Page_Load(object sender, EventArgs e) { UpdatePanel2Label.Text = “Refreshed at “ + DateTime.Now.ToString(); }
Content Page
UpdatePanel Server Control
876
c19.indd 876
8/20/07 8:33:26 PM
Chapter 19: UpdatePanel and ScriptManager
Using Triggers As I mentioned earlier, when the UpdateMode property of an UpdatePanel server control is set to Conditional, the UpdatePanel server control updates only when one of the predefined conditions is met. Here is the third condition. The UpdatePanel server control exposes Triggers, a collection property of type UpdatePanelTriggerCollection that contains objects known as triggers. As the name implies, a trigger is an object that triggers the update of the UpdatePanel server control whose Triggers collection property contains the trigger. Listing 19-11 presents a page that contains an UpdatePanel server control that uses a trigger that causes an asynchronous page postback. As you can see, an asynchronous page postback trigger is an instance of a class named AsyncPostBackTrigger, which is declaratively added to the child element of the associated tag. If you run this page, you should see the result shown in Figure 19-6. Note that the trigger in this case is an ASP.NET Button server control located in the nonpartially updatable section of the page. In other words, a trigger enables you to trigger the update of a specified UpdatePanel server control from outside the control. This approach is different from the approach discussed earlier in which you set the ChildrenAsTriggers property of the UpdatePanel server control to true to have the server controls residing inside the control trigger the update of the control.
Listing 19-11: A Page that Contains an UpdatePanel Server Control that Uses a Trigger void Page_Load(object sender, EventArgs e) { string text = “Refreshed at “ + DateTime.Now.ToString(); UpdatePanel1Label.Text = text; NonPartiallyUpdatableLabel.Text = text; } Untitled Page
Partially Updatable Portion (UpdatePanel1)
(continued)
877
c19.indd 877
8/20/07 8:33:26 PM
Chapter 19: UpdatePanel and ScriptManager Listing 19-11 (continued)
Non Partially Updatable Portion
Imperative Update The UpdatePanel server control exposes a public method named Update that you can call from within your managed code to imperatively update the control. You must set the UpdateMode property of the UpdatePanel server control to Conditional if you want to update the control imperatively. Otherwise an exception will be raised.
878
c19.indd 878
8/20/07 8:33:26 PM
Chapter 19: UpdatePanel and ScriptManager
Figure 19- 6
Listing 19-12 presents a page that updates an UpdatePanel server control imperatively. This page first adds an ASP.NET Button server control to the non-partially updatable part of the page and registers a method named AsyncPostBackButtonCallback as an event handler for the Click event of this button:
Next, it implements the AsyncPostbackButtonCallback method, where it invokes the Update method on the UpdatePanel server control to update the control. This means that every time the end user clicks the ASP.NET Button server control, the callback for the Click event of this button automatically updates the UpdatePanel server control: void AsyncPostbackButtonCallback(object sender, EventArgs e) { UpdatePanel1.Update(); }
879
c19.indd 879
8/20/07 8:33:27 PM
Chapter 19: UpdatePanel and ScriptManager We’re not done yet! If you don’t take the next step, the ASP.NET Button server control will trigger a regular synchronous page postback to the server, where not only the UpdatePanel server control but also the non-partially updatable section of the page will be updated. The next step adds the following line of code to the Page_Load method. As you can see, this line of code calls the RegisterAsyncPostBackControl method on the current ScriptManager server control to register the ASP.NET Button server control as the trigger for asynchronous page postbacks: ScriptManager1.RegisterAsyncPostBackControl(AsyncPostBackButton);
Listing 19-12: A Page that Imperatively Updates an UpdatePanel Server Control void AsyncPostbackButtonCallback(object sender, EventArgs e) { UpdatePanel1.Update(); } void Page_Load(object sender, EventArgs e) { string text = “Refreshed at “ + DateTime.Now.ToString(); UpdatePanel1Label.Text = text; NonPartiallyUpdatableLabel.Text = text; ScriptManager1.RegisterAsyncPostBackControl(AsyncPostBackButton); } Untitled Page
Partially Updatable Portion (UpdatePanel1)
880
c19.indd 880
8/20/07 8:33:27 PM
Chapter 19: UpdatePanel and ScriptManager
Non Partially Updatable Portion
Developing Par tial-Rendering Enabled Custom Composite Ser ver Controls Master/detail forms play an important role in ASP.NET applications. As the name suggests, a master/ detail form consists of two main components, the master and the detail. The master displays a set of selectable records to the end users. When an end user selects a record from the master, the detail displays detailed information about the selected record.
881
c19.indd 881
8/20/07 8:33:27 PM
Chapter 19: UpdatePanel and ScriptManager Several different ASP.NET server controls can be used as master and detail components, and a master/ detail form can be made up of any combination of these server controls. For example, you could have a master/detail form in which ASP.NET GridView and DetailsView controls are used as master and detail components, respectively. Or you could have a master/detail form in which ASP.NET DropDownList and DetailsView controls are used as master and detail components. As you can see, different types of master/detail forms can use different types of ASP.NET server controls as master and detail components. All these different types of master/detail forms have certain characteristics in common. I’ll first develop an abstract base class named BaseMasterDetailControl that captures these common characteristics. Some of the important characteristics that all master/detail forms share are their usability, responsiveness, and performance. Let’s take a look at a scenario where these common characteristics play significant roles. When the end user selects a record from the master, two things must happen:
❑
A round trip must be made to the server to retrieve the detailed information about the selected record. As you can imagine, such round trips can easily degrade the usability, responsiveness, and performance of the master/detail form if they block the user from further interaction with the page until the server response arrives. As a result, it is of paramount importance that such round trips are made asynchronously in the background, allowing the user to interact with the page while the data is being downloaded from the server.
❑
The detail component of the master/detail form must be updated with the new information. As you can imagine, such updates can easily degrade the usability, responsiveness, and performance of the master/detail form if they cause the entire page — including those parts of the page that have absolutely nothing to do with the master/detail form — to update. This is especially a problem for graphics-heavy pages. As a result, it is of paramount importance that such updates are limited to the master/detail form itself and do not propagate to the entire page.
Therefore, a master/detail form must be designed to meet these two requirements. First, all round trips to the server must be performed asynchronously in the background without interrupting the user’s interaction with the page. Second, all updates must be limited to the master/detail form without causing the entire page to reload. The ASP.NET AJAX Framework provides you with two main approaches to designing a master/detail form that meets these two requirements. One approach is to use the ASP.NET AJAX Web service consumption infrastructure to make asynchronous round trips to a Web service to retrieve the required data, and to use the ASP.NET AJAX client-side Framework to dynamically update the master/detail form with the retrieved data. Another approach is to use the ASP.NET AJAX partial page rendering infrastructure to make asynchronous page postbacks to the server and to dynamically update the master/detail form. As I discussed earlier, this infrastructure requires you to use a ScriptManager and one or more UpdatePanel server controls. In this chapter I will use the second approach.
BaseMasterDetailControl In this section I’ll implement an abstract base class named BaseMasterDetailControl that will capture the logic that all types of master/detail forms have in common, as shown in Listing 19-13. Since the BaseMasterDetailControl consists of two components — master and detail — it is an example of what is known as a composite server control.
882
c19.indd 882
8/20/07 8:33:27 PM
Chapter 19: UpdatePanel and ScriptManager The controls from which a composite server control such as BaseMasterDetailControl is assembled are known as child controls. Composite controls delegate most of their responsibilities — such as rendering content HTML and handling postback events — to their child controls. Implementing a custom composite server control such as the BaseMasterDetailControl control involves the following actions:
Deriving from CompositeControl Choosing child controls Choosing layout Implementing a custom container control Creating a container control Creating the child controls of a container control Applying style to a container control Adding a container control to the custom composite server control Rendering a container control Overriding the CreateChildControls method Overriding the TagKey property Overriding the CreateControlStyle method Exposing the ControlStyle’s properties as if they were the properties of the composite control Overriding the RenderContents method Exposing the properties of the child controls as if they were the properties of the composite control
Listing 19-13 uses the above recipe to implement the BaseMasterDetailControl composite server control as discussed in the following sections.
Listing 19-13: The BaseMasterDetailControl Server Control using using using using using using using using using using
Chapter 19: UpdatePanel and ScriptManager Listing 19-13 (continued) namespace CustomComponents { public abstract class BaseMasterDetailControl : CompositeControl { Control master; Control detail; UpdatePanel masterUpdatePanel; UpdatePanel detailUpdatePanel; MasterDetailContainer masterContainer; MasterDetailContainer detailContainer; protected protected protected protected
abstract abstract abstract abstract
Control CreateMaster(); Control CreateDetail(); void RegisterMasterEventHandlers(); void RegisterDetailEventHandlers();
public Control Master { get { EnsureChildControls(); return this.master; } } public Control Detail { get { EnsureChildControls(); return this.detail; } } public string MasterSkinID { get { EnsureChildControls(); return master.SkinID; } set { EnsureChildControls(); master.SkinID = value; } } public string DetailSkinID { get { EnsureChildControls(); return detail.SkinID; } set { EnsureChildControls(); detail.SkinID = value; } }
884
c19.indd 884
8/20/07 8:33:28 PM
Chapter 19: UpdatePanel and ScriptManager public virtual object SelectedValue { get { return ViewState[“SelectedValue”]; } set { ViewState[“SelectedValue”] = value; } } protected override Style CreateControlStyle() { return new TableStyle(ViewState); } public virtual GridLines GridLines { get { return ((TableStyle)ControlStyle).GridLines; } set { ((TableStyle)ControlStyle).GridLines = value; } } public virtual int CellSpacing { get { return ((TableStyle)ControlStyle).CellSpacing; } set { ((TableStyle)ControlStyle).CellSpacing = value; } } public virtual int CellPadding { get { return ((TableStyle)ControlStyle).CellPadding; } set { ((TableStyle)ControlStyle).CellPadding = value; } } public virtual HorizontalAlign HorizontalAlign { get { return ((TableStyle)ControlStyle).HorizontalAlign; } set { ((TableStyle)ControlStyle).HorizontalAlign = value; } } public virtual string BackImageUrl { get { return ((TableStyle)ControlStyle).BackImageUrl; } set { ((TableStyle)ControlStyle).BackImageUrl = value; } } protected virtual void CreateContainerChildControls( MasterDetailContainer container) { switch (container.ContainerType) { case ContainerType.Master: masterUpdatePanel = new UpdatePanel(); masterUpdatePanel.UpdateMode = UpdatePanelUpdateMode.Conditional; master = this.CreateMaster(); if (string.IsNullOrEmpty(master.ID)) master.ID = ”MasterServerControl”;
Chapter 19: UpdatePanel and ScriptManager Deriving from CompositeControl The ASP.NET Framework comes with a base class named CompositeControl that provides the basic features that every composite control must support. These features will be discussed later in this chapter. You must derive your custom composite control from the CompositeControl base class to save yourself from having to re-implement the features that your control can easily inherit from this base class. public class BaseMasterDetailControl: CompositeControl
Choosing the Child Controls The next order of business in developing a custom composite control is to choose the child controls that you’ll need in order to assemble your custom control. You’ll need the following server controls to assemble the BaseMasterDetailControl control (each child control is named for ease of reference):
❑
A server control to display the master data records (master)
❑
A server control to display the detailed information about the selected record of the master control (detail)
The BaseMasterDetailControl control exposes two abstract methods that its subclasses must override to create the appropriate master and detail server controls: protected abstract Control CreateMaster(); protected abstract Control CreateDetail();
Choosing the Layout Next you need to choose the desired layout for your child controls. As Figure 19-7 shows, the BaseMasterDetailControl control uses a tabular layout for its child controls, in which each table cell contains a child control. Note that the table cells in Figure 19-7 are numbered for ease of reference. Keep in mind that cell numbers 1 and 2 contain the master and detail server controls, respectively.
1
2
Figure 19- 7
890
c19.indd 890
8/20/07 8:33:29 PM
Chapter 19: UpdatePanel and ScriptManager Implementing a Custom Container Control Since the BaseMasterDetailControl control uses a tabular layout for its child controls, in which each table cell contains a child control, the appropriate container for the child controls is TableCell control. However, the TableCell control doesn’t meet the following requirements:
❑
It doesn’t implement the INamingContainer interface. I’ll discuss later why it’s important for a container control to implement this interface. You’ll also see that this is a marker interface and doesn’t have any methods or properties.
❑
It doesn’t expose a property that uniquely locates or identifies a cell among other cells. It’s important to know which cell you’re dealing with because different cells contain different types of child controls. For example, cell number 1 contains the master control while cell number 2 contains the detail control.
Therefore, I’ll implement a custom container control named MasterDetailContainer that derives from TableCell, implements the INamingContainer interface, and exposes a property named ContainerType whose value uniquely locates or identifies each cell among other cells. As Figure 19-7 shows, the number of a cell is used to identify or locate the cell among other cells. The BaseMasterDetailControl control defines an enumeration named ContainerType whose values correspond to the cell numbers shown in Figure 19-7. Listing 19-14 presents the definition of this enumerator.
Listing 19-14: The ContainerType Enumerator namespace CustomComponents { public enum ContainerType { Master = 1, Detail = 2 } }
Listing 19-15 shows the implementation of the MasterDetailContainer container control.
Listing 19-15: The MasterDetailContainer Container Control using using using using using using using
Chapter 19: UpdatePanel and ScriptManager Listing 19-15 (continued) namespace CustomComponents { public class MasterDetailContainer : TableCell, INamingContainer { private ContainerType containerType; public MasterDetailContainer(ContainerType containerType) { this.containerType = containerType; } public ContainerType ContainerType { get { return containerType; } } } }
Creating a Container Control The extensibility of a custom control is of paramount importance. As a matter of fact, the extensibility of your custom control is much more important than its feature set. You’d be better off developing an extensible custom control with fewer features than a non-extensible one with more features. An extensible control enables others to extend it to add support for missing features, but the non-extensible one is pretty much it — if it doesn’t support the features the clients of your control need, they have no choice but to dump it. That said, you can’t design a custom control that can be extended to support all possible features. This is simply not practical, for two reasons. First, you can’t see the future, which means you can’t plan for all possible extensions. Second, extensibility comes with a price in terms of both time and budget. The more extensible you want your custom control to be, the more time and effort you have to put into it. This chapter will show you a few examples of how you can make your custom controls more extensible. Listing 19-13 shows the first example, in which the protected virtual CreateContainer method encapsulates and isolates the instantiation of the container control. This will enable others to write new container controls that derive from the MasterDetailContainer control and override this method to return their own container controls.
Creating the Child Controls of a Container Control As discussed earlier, a MasterDetailContainer control is used to represent each numbered cell shown in Figure 19-7. The next order of business is to create the child controls that go into each container control. This is a tricky one because you have to do it in such a way that it doesn’t tie your custom control to a specific set of child controls. The trick is to implement a new protected virtual method (CreateContainerChildControls, shown in Listing 19-13) that encapsulates the code that does the dirty job of creating the child controls. This method must take the container control as its argument, create the child controls, and add them to the container. Therefore the only dependency between your custom control and its child controls is the container control. This dependency is weak, considering the fact that others can override the CreateContainer method to use their own custom container controls.
892
c19.indd 892
8/20/07 8:33:30 PM
Chapter 19: UpdatePanel and ScriptManager You can think of the container control as a bucket. Your custom control first calls the CreateContainer method to create the bucket. The CreateContainer method isolates your custom control from the code that does the dirty job of creating the bucket. Your custom control then passes the bucket to the CreateContainerChildControls method shown in Listing 19-13. CreateContainerChildControls creates the child controls and puts them in the bucket. Your custom control doesn’t know or care what this method puts into the bucket because your custom control deals only with the bucket, not its contents. The CreateContainerChildControls method first uses the ContainerType property of the container control to identify the table cell into which the respective child control will go. Recall that the values of the ContainerType property correspond to the cell numbers shown in Figure 19-7. The containing cell matters because it determines what types of child controls the CreateContainerChildControls method must create. For example, the child control responsible for displaying the master data records goes into the cell number 1 in Figure 19-7. The child control responsible for displaying the details of the record that the end user selects from the master, on the other hand, goes into the cell number 2. The method then creates the child control that goes into the specified cell or container control, as follows. If the container type is Master, the method first instantiates an UpdatePanel server control: masterUpdatePanel = new UpdatePanel();
This UpdatePanel server control will contain the master server control — that is, the server control that will display the master records. Placing the master server control in an UpdatePanel server control provides the following important benefit: any postback originating from the inside the master server control, such as selecting a record, will be treated as an asynchronous page postback, which means that the page will be posted back asynchronously in the background without interrupting the end user interaction with the page. As Listing 19-13 shows, the CreateContainerChildControls method sets the UpdateMode property of the master UpdatePanel server control to Conditional: masterUpdatePanel.UpdateMode = UpdatePanelUpdateMode.Conditional;
As you’ll see later, this ensures that the master server control is updated only when one of these conditions is met:
❑
The user selects a record from the master server control
❑
The user updates the record shown in the detail server control
❑
The user deletes the record shown in the detail server control
❑
The user inserts a new record in the detail server control
Next, the CreateContainerChildControls method invokes the CreateMaster method to create the master server control. As mentioned earlier, the CreateMaster method is an abstract method. It is the responsibility of the subclasses of the BaseMasterDetailControl to override this method to create the appropriate master server control. For example, one subclass may override this method to
893
c19.indd 893
8/20/07 8:33:30 PM
Chapter 19: UpdatePanel and ScriptManager create and return a GridView server control. Another subclass, on the other hand, may override this method to create and return a DropDownList server control. In other words, it is completely up to the subclass to decide what type of server control should be used to display the master records: master = this.CreateMaster();
Next, the CreateContainerChildControls method invokes the RegisterMasterEventHandlers method: this.RegisterMasterEventHandlers();
The RegisterMasterEventHandlers method is an abstract method: protected abstract void RegisterMasterEventHandlers();
As such, it is the responsibility of the subclass of the BaseMasterDetailControl to override this method to register the appropriate event handlers for those events of the master server control that require the detail server control to update. For example, if the master server control is a DropDownList control, the subclass must register an event handler for the SelectedIndexChanged event of the DropDownList control because when this event fires, the detail server control must be updated with the detailed information about the newly selected record. Next, the CreateContainerChildControls method adds the master server control to the Controls collection of the content template container server control of the master UpdatePanel server control: masterUpdatePanel.ContentTemplateContainer.Controls.Add(master);
In general, there are two ways to add content to a UpdatePanel server control: declarative and programmatic. The declarative approach requires you to add HTML or ASP.NET server controls within the opening and closing tags of the ContentTemplate child element of the tag that represents the UpdatePanel server control on an .aspx or .ascx file. Here is an example:
The imperative approach, on the other hand, requires you to add ASP.NET server controls to the Controls collection of the content template container control of the UpdatePanel server control from your C# or VB.NET code. Next, the CreateContainerChildControls method adds the master UpdatePanel server control to the Controls collection of the container server control: container.Controls.Add(masterUpdatePanel);
If the container type is Detail, the CreateContainerChildControls method first instantiates an UpdatePanel server control: detailUpdatePanel = new UpdatePanel();
894
c19.indd 894
8/20/07 8:33:30 PM
Chapter 19: UpdatePanel and ScriptManager This UpdatePanel server control will contain the detail server control — that is, the server control that will display the details of the record that the user selects from the master server control. Placing the detail server control in an UpdatePanel server control provides the following two important benefits. First, any postback originating from the inside the detail server control such as clicking an Update button to update a record will be treated as an asynchronous page postback, which means that the page will be posted back asynchronously in the background without interrupting the end-user interaction with the page. Second, when the end user selects a new record from the master records, the detail server control is the only part of the page that gets updated. That is, this update does not trigger the entire page to reload. This gives an important performance, usability, and responsiveness boost in graphics-heavy pages. As Listing 19-13 shows, the CreateContainerChildControls method sets the UpdateMode property of the detail UpdatePanel server control to Conditional: detailUpdatePanel.UpdateMode = UpdatePanelUpdateMode.Conditional;
As you’ll see later and as I mentioned earlier, this ensures that the detail server control is updated only when one of these conditions is met:
❑
The user selects a new record from the master server control
❑
The user updates the record shown in the detail server control
❑
The user deletes the record shown in the detail server control
❑
The user inserts a new record in the detail server control
Next, the CreateContainerChildControls method invokes the CreateDetail method to create the detail server control. As mentioned earlier, the CreateDetail method is an abstract method. It is the responsibility of the subclasses of the BaseMasterDetailControl to override this method to create the appropriate detail server control. For example, one subclass may override this method to create and to return a DetailsView server control. Another subclass, on the other hand, may override this method to create and to return a different type of server control. In other words, it is completely up to the subclass to decide what type of server control should be used to display the detail record: detail = this.CreateDetail();
Next, the CreateContainerChildControls method invokes the RegisterDetailEventHandlers method: this.RegisterDetailEventHandlers();
The RegisterDetailEventHandlers method is an abstract method: protected abstract void RegisterDetailEventHandlers();
Because of this, it is the responsibility of the subclass of the BaseMasterDetailControl to override this method to register the appropriate event handlers for those events of the detail server control that require the master server control to update. For example, if the detail server control is a DetailsView control, the subclass must register an event handler for the ItemDeleted event of the DetailsView control, because when this event fires, the master server control must be updated to “undisplay” the deleted record.
895
c19.indd 895
8/20/07 8:33:31 PM
Chapter 19: UpdatePanel and ScriptManager Next, the CreateContainerChildControls method adds the detail server control to the Controls collection of the content template container server control of the detail UpdatePanel server control: detailUpdatePanel.ContentTemplateContainer.Controls.Add(detail);
Finally, the CreateContainerChildControls method adds the detail UpdatePanel server control to the Controls collection of the container server control: container.Controls.Add(detailUpdatePanel);
Note that the CreateContainerChildControls method assigns unique values to the ID properties of the child controls. Also note that the CreateContainerChildControls method initializes the child controls before they are added to the Controls collection. You must initialize your child controls before you add them to the Controls collection of your custom control, because if you initialize them afterward these initialized property values will be saved to the view state. This will unnecessarily increase the size of your custom control’s view state. Recall that the containing page stores the string representation of your control’s view state in a hidden field on the page, which means that any increase in the size of your control’s view state will increase the size of the page that the requesting browser has to download from the server.
Applying Style to a Container Control Recall that container controls are of type MasterDetailContainer. As Listing 19-15 shows, the MasterDetailContainer class derives from the TableCell control, which in turn derives from WebControl. Every control that derives from WebControl exposes a property named ControlStyle. The real type of this property may vary from one control to another; the ControlStyle property of the TableCell control is of type TableItemStyle. The TableItemStyle class exposes the following 12 style properties: ForeColor, BorderColor, BackColor, BorderWidth, BorderStyle, Width, Height, Font, CssClass, HorizontalAlign, VerticalAlign, and Wrap. This means that the ControlStyle of each container control exposes these style properties. The BaseMasterDetailControl server control exposes two properties of type TableItemStyle, each of which internally maps to the ControlStyle property of its associated container control, as shown in the following table.
Style Property
Associated Container Control
masterContainerStyle
ContainerType.Master
detailContainerStyle
ContainerType.Detail
These two properties enable page developers to set the ControlStyle property of a container control as if they were setting the style properties of the BaseMasterDetailControl server control itself. In other words, the BaseMasterDetailControl server control hides the ControlStyle properties of its container controls and exposes them as its own properties.
896
c19.indd 896
8/20/07 8:33:31 PM
Chapter 19: UpdatePanel and ScriptManager As Listing 19-13 shows, the ApplyContainerStyles method iterates through the container controls in the Controls collection of the BaseMasterDetailControl server control and calls the ApplyStyle method of each enumerated container control if its associated style property isn’t null. Notice that the ApplyContainerStyles method uses the ContainerType property of each enumerated container control to determine which container control it’s dealing with.
State Management Object-oriented applications use objects to service their users. Each object normally keeps the information that it needs to function properly in memory. This information includes, but is not limited to, the property and field values of the object. This in-memory information is known as the state of the object. Invoking the methods and properties of an object normally changes its state. The state of an object is lost forever when the object is disposed of. This isn’t an issue in a desktop application, because the objects are disposed of only when they’re no longer needed. However, it causes a big problem in a Web application where each user session normally consists of more than one request. Due to the stateless nature of the HTTP protocol, the objects are disposed of at the end of each request, even though the session that the request belongs to still needs the objects. That is, the states of these objects are lost at the end of each request and new objects of the same types are recreated at the beginning of the next request. These newly created objects have no memory of the previous objects and start off with their default states. The ASP.NET view state mechanism enables you to save the states of your objects at the end of each request and load them at the beginning of the next request. The next request does the following:
❑
Creates new objects of the same types as those that were disposed of at the end of the previous request
❑
Loads the states of the old objects into the new objects
Since the newly created objects at the beginning of each request have the same types and states as the objects disposed of at the end of the previous request, it gives the illusion that objects are not disposed of at the end of each request and that the same objects are being used all along. Now you’ll see how the ASP.NET view state mechanism works. Every server control inherits three methods from the Control class: TrackViewState, SaveViewState, and LoadViewState. At the end of each request, the following sequence of events occurs:
1.
The page automatically calls the SaveViewState method of the controls in its Controls collection. Remember, the Controls collection contains all the controls that were declared in the .aspx file. Page developers can also programmatically create server controls and manually add them to the Controls collection of the page.
2.
The SaveViewState method of each control must save the state of the control and its child controls into an appropriate object and return the object.
3.
The page collects the objects returned from the SaveViewState methods of the controls in its Controls collection and forms a tree of objects known as an object graph.
897
c19.indd 897
8/20/07 8:33:31 PM
Chapter 19: UpdatePanel and ScriptManager 4.
The page framework then uses the type converter associated with each object to convert the object into a string representation, and combines these string representations into a single string that represents the entire object graph.
5.
The page framework then stores the string representation of the entire object graph in a hidden field named __VIEWSTATE, which looks something like the following:
Therefore the __VIEWSTATE hidden field is sent to the client browser as part of the containing page. When the page is posted back to the server, the following sequence of events occurs:
1.
The page framework retrieves the string representation of the object graph from the __VIEWSTATE hidden field.
2. 3.
The page framework extracts the string representation of each object.
4.
The page calls the LoadViewState method of each control in its Controls collection and passes the respective object into it. (Remember that this object contains the state of the control and its child controls at the end of the previous request.)
5.
The LoadViewState method of each control must load the contents (the state of the control at the end of the previous request) of this object into itself. Therefore the control will have the same state as in the previous request.
6. 7.
The page calls the TrackViewState method of each control in its Controls collection.
The page framework uses the type converter associated with each object to recreate the object from its string representation.
The TrackViewState of each control must set an internal Boolean field to true to specify that it’s tracking the control’s state. What this means is that from this point on, any changes in the state of the object will be marked as dirty and saved at the end of the request (as discussed before).
As I mentioned, the state of a control includes, but is not limited to, its property values. In general, there are two types of properties:
❑
Simple properties: A simple property is one whose type doesn’t expose any properties. For example, the MasterSkinID property of the BaseMasterDetailControl server control is of type string, which doesn’t expose any properties.
❑
Complex properties: A complex property is one whose type exposes properties. For example, the MasterContainerStyle and DetailContainerStyle properties of the BaseMasterDetailControl server control are of type TableItemStyle, which exposes properties such as Font, Width, Height, and so on.
Simple properties use the ViewState collection as their backing store to manage their states across page postbacks. How about the MasterContainerStyle and DetailContainerStyle complex properties of the BaseMasterDetailControl server control? How do they manage their states across page postbacks?
898
c19.indd 898
8/20/07 8:33:32 PM
Chapter 19: UpdatePanel and ScriptManager This is where the IStateManager interface comes into play. The type of MasterContainerStyle and DetailContainerStyle complex properties — that is, the TableItemStyle — implements this interface. IStateManager exposes one Boolean property, IsTrackingViewState, and three methods, TrackViewState, SaveViewState, and LoadViewState.
When the TrackViewState method of a control is called, the method calls the TrackViewState methods of its complex properties. The TrackViewState method of a complex property does exactly what the TrackViewState method of a control does — sets an internal Boolean field to true to specify that any state changes will be marked as dirty and saved at the end of the current request. When the SaveViewState method of a control is called, the method calls the SaveViewState methods of its complex properties. The SaveViewState method of a complex property does exactly what the SaveViewState method of a control does — it saves its state into an appropriate object and returns the object. It then collects the objects returned from the SaveViewState methods of its complex properties and saves them into the same object to which it saves its own state. Finally, it returns the object that contains the states of both the control and its complex properties. When the LoadViewState method of a control is called, it retrieves the objects that contain the states of its complex properties. It then calls the LoadViewState method of each complex property and passes the object that contains the saved state into it. The LoadViewState method of a complex property does exactly what the LoadViewState of a control does. As you can see from the implementation of the MasterContainerStyle and DetailContainerStyle properties shown in Listing 19-13, when these two style properties are created and BaseMasterDetailControl server control is tracking its view state, the control calls the TrackViewState method of these two properties to inform them that they must start tracking their view states.
TrackViewState BaseMasterDetailControl overrides TrackViewState to call the TrackViewState methods of its style properties, as shown in Listing 19-13. Note that TrackViewState calls the TrackViewState method of a style property if and only if the style isn’t null — that is, if the page developer has specified the style.
SaveViewState BaseMasterDetailControl overrides SaveViewState to call the SaveViewState methods of its style properties, as shown in Listing 19-13. The SaveViewState method of each style property stores its view state in an appropriate object and returns the object to the SaveViewState method of BaseMasterDetailControl, which in turn puts all these objects, and the object that contains the view state of its base class, in an array and returns the array to its caller.
Notice that SaveViewState checks whether all the objects that the array contains are null. If they are, it returns null. If at least one of the objects isn’t null, it returns the whole array.
899
c19.indd 899
8/20/07 8:33:32 PM
Chapter 19: UpdatePanel and ScriptManager LoadViewState BaseMasterDetailControl overrides LoadViewState to call the LoadViewState methods of its style properties, as shown in Listing 19-13. As you can see, the LoadViewState method of BaseMasterDetailControl retrieves the array of objects that contains the saved view state of its base class and style properties. The method then calls the LoadViewState methods of its base class and properties in the order in which the SaveViewState method of BaseMasterDetailControl called their SaveViewState methods. The LoadViewState method of each style property loads its view state
with the saved view state.
Adding a Container Control to a Composite Control The BaseMasterDetailControl server control implements a method named AddContainer, shown in Listing 19-13, that encapsulates the code that adds a container control to the Controls collection of the BaseMasterDetailControl control. Note that this method is marked as protected virtual to enable others to override it — in order, for example, to raise an event before or after the container is added to the Controls collection.
Rendering a Container Control The BaseMasterDetailControl server control exposes a method named RenderContainer, shown in Listing 19-13, which encapsulates the code that renders a container. This method is marked as protected virtual to enable others to override it.
Overriding CreateChildControls: One-Stop Shopping for All Your Child Controls The Control class exposes a method named CreateChildControls that you must override to create the child controls that you need in order to assemble your custom control. One important thing to keep in mind about child controls is that they’re created on demand. Don’t assume that they’re created at a particular stage of your custom control’s life cycle. They can be created at any time. In other words, the CreateChildControls method can be called at any stage of your custom control’s life cycle to create the child controls. This has important consequences. One of these is that you must create the child controls of your custom control in one and only one place — the CreateChildControls method. Your custom control mustn’t create any of its child controls in any other place. If you create your child controls in any other place, they cannot be created on demand because the on-demand child-control creation feature of the ASP.NET Framework is accomplished via calling the CreateChildControls method. Think of CreateChildControls as your one-stop shopping place for all your child controls. You mustn’t shop anywhere else! Next, I’ll walk you through the implementation of the CreateChildControls method shown in Listing 19-13. This method first calls the Clear method of the Controls collection to clear the collection. This ensures that multiple copies of child controls aren’t added to the Controls collection when the CreateChildControls method is called multiple times: Controls.Clear();
900
c19.indd 900
8/20/07 8:33:32 PM
Chapter 19: UpdatePanel and ScriptManager If you examine the implementation of the BaseMasterDetailControl server control, you’ll notice that this method is never called multiple times. You may be wondering, then, why you should bother with clearing the collection. You’re right as far as the implementation of the BaseMasterDetailControl server control goes, because you’re the author of this control and you can make sure your implementation of it doesn’t call the CreateChildControls method multiple times. However, you have no control over others when they’re deriving from your control to author their own custom controls. There’s nothing that would stop them from calling the CreateChildControls method multiple times. This example shows that when you’re writing a custom control you must take the subclasses of your custom control into account. Then it takes the following actions for each cell shown in Figure 19-7 to create the child control that goes into the cell:
❑
It calls the CreateContainer method to create the container control that represents the cell. For example, the following call to the CreateContainer method creates the container control that represents the cell number 2 in Figure 19-7: detailContainer = CreateContainer(ContainerType.Detail);
❑
It calls the CreateContainerChildControls method and passes the container control into it. As I mentioned earlier, the CreateContainerChildControls method creates the child controls, initializes them, and adds them to the container control. For example, the following call to the CreateContainerChildControls method creates the detail server control and adds it to the detailContainer server control:
CreateContainerChildControls(detailContainer);
❑
It calls the AddContainer method to add the container control to the BaseMasterDetailControl server control. For example, the following code adds the container control that represents the cell number 2 in Figure 19-7 to the BaseMasterDetailControl control:
AddContainer(detailContainer);
After all the child controls are created, the method then sets the ChildControlsCreated property to true: ChildControlsCreated = true;
As I mentioned, the child controls aren’t created at any particular stage of your custom control’s life cycle. They’re created on demand. This means that the CreateChildControls method can be called multiple times, though this will waste server resources because this method recreates the child controls every single time it’s called, regardless of whether or not the child controls have already been created. To address this problem, the Control class exposes a method named EnsureChildControls and a Boolean property named ChildControlsCreated. The EnsureChildControls method checks whether the ChildControlsCreated property is set to false. If it is, the method first calls the CreateChildControls method and then sets the ChildControlsCreated property to true. The EnsureChildControls method uses this property to avoid multiple invocations of the CreateChildControls method.
901
c19.indd 901
8/20/07 8:33:33 PM
Chapter 19: UpdatePanel and ScriptManager That is why your custom control’s implementation of the CreateChildControls method must set the ChildControlsCreated property to true to signal the EnsureChildControls method that child controls have been created and the CreateChildControls mustn’t be called again.
Overriding the TagKey Property Your custom control must use the TagKey property to specify the HTML element that will contain the entire contents of your custom control — that is, the containing element of your custom control. Since BaseMasterDetailControl displays its contents in a table, the control overrides the TagKey property to specify the table HTML element as its containing element (see Listing 19-13).
Overriding the CreateControlStyle Method Your custom control must override the CreateControlStyle method to specify the appropriate Style subclass. The properties of this Style subclass are rendered as CSS style attributes on the containing HTML element. Since BaseMasterDetailControl uses a table HTML element as its containing element, it overrides the CreateControlStyle method to use a TableStyle instance (see Listing 19-13). The TableStyle class exposes properties such as GridLines, CellSpacing, CellPadding, HorizontalAlign, and BackImageUrl that are rendered as CSS table style attributes.
Exposing Style Properties When you override the CreateControlStyle method, you must also define new style properties for your custom control that expose the corresponding properties of the Style subclass. This provides page developers with a convenient mechanism to set the CSS style properties of the containing HTML element. BaseMasterDetailControl exposes five properties named GridLines, CellSpacing, CellPadding, HorizonalAlign, and BackImageUrl that correspond to the properties of the TableStyle class with
the same names as shown in Listing 19-13.
Overriding the RenderContents Method The CreateChildControls method is where you create and initialize the child controls that you need in order to assemble your custom control. The RenderContents method is where you do the assembly — that is, where you assemble your custom control from the child controls. First you need to understand how the default implementation (the WebControl class’s implementation) of the RenderContents method assembles your custom control from the child controls. The WebControl class’s implementation of RenderContents calls the Render method of its base class, the Control class: protected internal virtual void RenderContents(HtmlTextWriter writer) { base.Render(writer); }
902
c19.indd 902
8/20/07 8:33:33 PM
Chapter 19: UpdatePanel and ScriptManager Render calls the RenderChildren method of the Control class: protected internal virtual void Render(HtmlTextWriter writer) { RenderChildren(writer); } RenderChildren calls the RenderControl methods of the child controls in the order in which they are added to the Controls collection: protected internal virtual void RenderChildren(HtmlTextWriter writer) { foreach (Control childControl in Controls) childControl.RenderControl(writer); }
In conclusion, the default implementation of the RenderContents method assembles the child controls in the order in which the CreateChildControls method adds them to the Controls collection. This default assembly of the BaseMasterDetailControl custom control will simply lay down the child controls on the page one after another in a linear fashion, which is not the layout you want. As Listing 19-13 shows, the BaseMasterDetailControl server control overrides the RenderContents method to compose or assemble the child controls in a tabular fashion. As Figure 19-7 shows, the BaseMasterDetailControl server control renders its contents in a table that consists of two rows. The RenderContents method in Listing 19-13 first calls the ApplyContainerStyles method to apply container styles. Then, for each table row, it calls the RenderBeginTag method of the HtmlTextWriter object passed in as its argument to render the opening tag of the tr HTML element that represents the row: writer.RenderBeginTag(HtmlTextWriterTag.Tr);
It then calls the RenderContainer method to render the masterContainer and detailContainer container controls that represent the cells numbered 1 and 2, respectively, in Figure 19-7: RenderContainer(masterContainer,writer); RenderContainer(detailContainer,writer);
Finally, it calls the RenderEndTag method of the HtmlTextWriter object to render the closing tag of the tr HTML element that represents the row: writer.RenderEndTag();
Exposing the Properties of Child Controls Your composite control must expose the properties of its child controls as if they were its own properties in order to enable page developers to treat these properties as attributes on the tag that represents your custom control on an ASP.NET page. BaseMasterDetailControl exposes the following properties of its child master and detail controls as its own properties, as shown in Listing 19-13.
903
c19.indd 903
8/20/07 8:33:33 PM
Chapter 19: UpdatePanel and ScriptManager Since the child controls of your custom composite control are created on demand, there are no guarantees that the child controls are created when the getters and setters of these properties access them. That’s why the getters and setters of these properties call EnsureChildControls before they access the respective child controls. In general, your custom control must call EnsureChildControls before it accesses any of its child controls. Exposing the properties of child controls as the top-level properties of your composite control provides page developers with the following benefits:
❑
They can set the property values of child controls as attributes on the tag that represents your composite control on an ASP.NET page.
❑
If your custom composite control doesn’t expose the properties of its child controls as its top-level properties, page developers will have no choice but to use the error-prone approach of indexing the Controls collection of the composite control to access the desired child control and set its properties.
❑
They can treat your custom control as a single entity. In other words, your composite control enables page developers to set the properties of its child controls as if they were setting its own properties.
What Your Custom Control Inherits from CompositeControl The ASP.NET CompositeControl provides the basic features that every composite control must support:
❑
Overriding the Controls collection
❑
Implementing INamingInterface
❑
Overriding the DataBind method
❑
Implementing the ICompositeControlDesignerAccessor interface. This interface exposes a single method named RecreateChildControls that enables designer developers to recreate the child controls of a composite control on the designer surface. This is useful if you want to develop a custom designer for your composite control. A designer is a component that enables page developers to work with your custom composite control in a designer such as Visual Studio. (This chapter doesn’t cover designers.)
❑
Overriding the Render method to call EnsureChildControls when the control is in design mode before the actual rendering begins. This ensures that child controls are created before they are rendered.
Overriding the Controls Collection As I discussed earlier, the child controls that you need in order to assemble your custom control aren’t created at any particular phase of your control’s life cycle. They’re created on demand. Therefore, there are no guarantees that the child controls are created when the Controls collection is accessed. That’s
904
c19.indd 904
8/20/07 8:33:34 PM
Chapter 19: UpdatePanel and ScriptManager why CompositeControl overrides the Collection property to call the EnsureChildControls method to ensure that the child controls are created before the collection is accessed: public override ControlCollection Controls { get { EnsureChildControls(); return base.Controls; } }
INamingContainer Interface As Listing 19-13 shows, the BaseMasterDetailControl server control assigns unique values to the ID properties of all of its child controls. For example, it assigns the string value MasterServerControl to the ID property of the master child control. This string value is unique in that no other child control of the BaseMasterDetailControl control has the same ID property. Now let’s examine what happens when page developers use two instances of the BaseMasterDetailControl control on the same ASP.NET Web page. Call the first instance MasterDetailControl_1 and the second instance MasterDetailControl_2. Even though the
ID properties of the child controls of each instance are unique within the scope of the instance, they aren’t unique within the page scope, because the ID property of a given child control of one instance is the same as the ID property of the corresponding child control of the other instance. For example, the ID property of the master child control of the MasterDetailControl_1 instance is the same as the ID property of the master child control of the MasterDetailControl_2 instance. So can the ID property value of a child control of a composite control be used to locate the control? It depends. Any code within the scope of the composite control can use the ID property value of a child control to locate it, because the ID property values are unique within the scope of the composite control. However, if the code isn’t within the scope of the composite control, it can’t use the ID property to locate the child control on the page if the page contains more than one instance of the composite control. Two very good examples of this circumstance are as follows:
❑
The client-side code uses the id attribute of a given HTML element to locate it on the page. This scenario is very common, because DHTML is so popular.
❑
The page needs to uniquely identify and locate a server control on the page to delegate postback and postback data events to it.
So what property of the child control should the code from outside the scope of the composite control use to locate the child control on the page? The Control class exposes two important properties named ClientID and UniqueID. The page is responsible for assigning values to these two properties that are unique on the page. The ClientID and UniqueID properties of a control are rendered as the id and
905
c19.indd 905
8/20/07 8:33:34 PM
Chapter 19: UpdatePanel and ScriptManager name HTML attributes on the HTML element that contains the control. As you know, client code uses the id attribute to locate the containing HTML element on the page while the page uses the name attribute to
locate the control on the page. The page doesn’t automatically assign unique values to the ClientID and UniqueID properties of the child controls of a composite control. The composite control must implement the INamingContainer interface to request the page to assign unique values to these two properties. The INamingContainer interface is a marker interface and doesn’t expose any methods, properties, or events. You may wonder how the page assigns unique values to the ClientID and UniqueID properties of the child controls of a composite control. A child control, like any other control, inherits the NamingContainer property from the Control class. This property refers to the first ascendant control of the child control that implements the INamingContainer interface. If your custom composite control implements this interface, it becomes the NamingContainer of its child controls. The page concatenates the ClientID of the NamingContainer of a child control to its ID with an underscore character as the separator to create a unique string value for the ClientID of the child control. The page does the same thing to create a unique string value for the UniqueID of the child control with one difference — the separator character is a dollar sign character rather than an underscore character.
BaseMasterDetailControl2 One of the best choices for a detail server control is the ASP.NET DetailsView server control, and one of the best choices for a master server control is the subclasses of BaseDataBoundControl, which include GridView, BulletedList, ListBox, CheckBoxList, RadioButtonList, and so on. I’ll implement another abstract base class named BaseMasterDetailControl2 that derives from BaseMasterDetailControl and extends its functionality to use a DetailsView server control as detail server control and a BaseDataBoundControl server control as master server control, as shown in Listing 19-16.
Listing 19-16: The BaseMasterDetailControl2 Server Control using using using using using using using using using using using using
Chapter 19: UpdatePanel and ScriptManager namespace CustomComponents { public abstract class BaseMasterDetailControl2 : BaseMasterDetailControl { protected override Control CreateMaster() { BaseDataBoundControl master = this.CreateBaseDataBoundControlMaster(); master.DataBound += new EventHandler(Master_DataBound); return master; } protected abstract void Master_DataBound(object sender, EventArgs e); protected abstract BaseDataBoundControl CreateBaseDataBoundControlMaster(); protected override Control CreateDetail() { DetailsView detail = new DetailsView(); detail.AllowPaging = false; detail.AutoGenerateDeleteButton = true; detail.AutoGenerateEditButton = true; detail.AutoGenerateInsertButton = true; detail.AutoGenerateRows = true; detail.ID=”DetailDetailsView”; return detail; } protected override void RegisterDetailEventHandlers() { ((DetailsView)Detail).ItemDeleted += new DetailsViewDeletedEventHandler(UpdateMaster); ((DetailsView)Detail).ItemInserted += new DetailsViewInsertedEventHandler(UpdateMaster); ((DetailsView)Detail).ItemUpdated += new DetailsViewUpdatedEventHandler(UpdateMaster); } public string MasterDataSourceID { get { return ((BaseDataBoundControl)Master).DataSourceID; } set { ((BaseDataBoundControl)Master).DataSourceID = value; } }
(continued)
907
c19.indd 907
8/20/07 8:33:35 PM
Chapter 19: UpdatePanel and ScriptManager Listing 19-16 (continued) public string DetailDataSourceID { get { return ((DetailsView)Detail).DataSourceID; } set { ((DetailsView)Detail).DataSourceID = value; } } } }
CreateMaster As you can see from Listing 19-16, the CreateMaster method first invokes another method named CreateBaseDataBoundControlMaster to create and return a BaseDataBoundControl server control as the master server control: BaseDataBoundControl master = this.CreateBaseDataBoundControlMaster();
Next, it registers a method named Master_DataBound as event handler for the DataBound event of the master server control: master.DataBound += new EventHandler(Master_DataBound);
As you’ll see later, the master server control is normally bound to an ASP.NET data source control such as SqlDataSource. A BaseDataBoundControl server control raises the DataBound event every time it is bound or rebound to the underlying data source control. This normally happens when the DataBind method of the control is invoked. Since rebinding the master server control causes the control to download fresh data from the underlying data store and to reload, you need to ensure that the selected record is set back to the original record if the fresh data contains the original record. That is why the BaseMasterDetailControl2 registers the Master_DataBound method as an event handler for the DataBound event of the master server control. As Listing 19-16 shows, the CreateBaseDataBoundControlMaster method is an abstract method and must be implemented by the subclasses of BaseMasterDetailControl2. This allows each subclass to use a different subclass of BaseDataBoundControl as a master server control: protected abstract BaseDataBoundControl CreateBaseDataBoundControlMaster();
As you can see from Listing 19-16, the Master_DataBound is an abstract method and must be implemented by the subclasses of BaseMasterDetailControl2. This allows each subclass to perform tasks specific to the specific type of the BaseDataBoundControl server control being used: protected abstract void Master_DataBound(object sender, EventArgs e);
908
c19.indd 908
8/20/07 8:33:35 PM
Chapter 19: UpdatePanel and ScriptManager CreateDetail As you can see from Listing 19-16, the BaseMasterDetailControl2 control implements the CreateDetail method of its base class to instantiate and initialize a DetailsView server control as the detail server control.
RegisterDetailEventHandlers The main responsibility of the RegisterDetailEventHandlers method is to register event handlers for those events of the detail server control that require the master server control to update. As you can see from Listing 19-16, in the case of the DetailsView server control, the following events are of interest:
❑
ItemDeleted: The DetailsView server control raises this event when the end user deletes the selected data record. The BaseMasterDetailControl2 registers a method named UpdateMaster as an event handler for this event to update the master server control accordingly:
((DetailsView)Detail).ItemDeleted += new DetailsViewDeletedEventHandler(UpdateMaster);
❑
ItemInserted: The DetailsView server control raises this event when the end user inserts a new data record into the underlying data store. The BaseMasterDetailControl2 registers the UpdateMaster as an event handler for this event to update the list of records that the master
server control is displaying: ((DetailsView)Detail).ItemInserted += new DetailsViewInsertedEventHandler(UpdateMaster);
❑
ItemUpdated: The DetailsView server control raises this event when the end user updates the selected data record. The BaseMasterDetailControl2 registers the UpdateMaster as an
event handler for this event to update the master server control accordingly: ((DetailsView)Detail).ItemUpdated += new DetailsViewUpdatedEventHandler(UpdateMaster);
The BaseMasterDetailControl2 inherits the UpdateMaster method from the BaseMasterDetailControl. The main responsibility of this method is to retrieve fresh data from the underlying data store and to update the master server control with this data. As Listing 19-16 shows, the UpdateMaster method first invokes the DataBind method on the master server control to rebind the control and consequently to retrieve fresh data from the underlying data store. Next, the method calls the Update method on the master UpdatePanel server control to cause this control to update. If you don’t call the Update method on the UpdatePanel server control after rebinding the master server control, the master server control will retrieve the data from the underlying data store but will not refresh itself with the retrieved data. You’ll see the logic behind this process in the following chapters.
909
c19.indd 909
8/20/07 8:33:35 PM
Chapter 19: UpdatePanel and ScriptManager Properties As you can see from Listing 19-16, the BaseMasterDetailControl2 control, like any other composite server control, exposes the properties of its child controls as its own top-level properties, as follows:
❑
MasterDataSourceID: This string property exposes the DataSourceID property of the master server control, which is a BaseDataBoundControl control, as a top-level property.
❑
DetailDataSourceID: This string property exposes the DataSourceID property of the detail server control, which is a DetailsView control, as a top-level property.
Summar y This chapter used numerous examples to provide you with an introduction to the ASP.NET AJAX partial page rendering. I then developed two base custom partial-page-enabled server controls named BaseMasterDetailControl and BaseMasterDetailControl2, which we will use in the next chapter to build partial-page-enabled server controls.
910
c19.indd 910
8/20/07 8:33:35 PM
Using UpdatePanel in User Controls and Custom Controls The previous chapter developed two partial-rendering-enabled custom controls named BaseMasterDetailControl and BaseMasterDetailControl2, which I will use in this chapter to develop partial-rendering-enabled custom server controls. I’ll then use examples to show you how to use ASP.NET AJAX partial page rendering in your own Web applications.
MasterDetailControl MasterDetailControl is a server control that inherits from BaseMasterDetailControl2 and extends its functionality to use the ASP.NET GridView as a master server control, as shown in
Listing 20-1.
Listing 20-1: The MasterDetailControl Server Control using using using using using using using using using using using using
Chapter 20: Using UpdatePanel in User Controls and Custom Controls Listing 20-1 (continued) namespace CustomComponents { public class MasterDetailControl : BaseMasterDetailControl2 { protected override BaseDataBoundControl CreateBaseDataBoundControlMaster() { GridView master = new GridView(); master.AllowPaging = true; master.AllowSorting = true; master.AutoGenerateColumns = true; master.AutoGenerateSelectButton = true; master.ID = “MasterGridView”; return master; } protected override void RegisterMasterEventHandlers() { ((GridView)Master).SelectedIndexChanged += new EventHandler(Master_SelectedIndexChanged); ((GridView)Master).PageIndexChanged += new EventHandler(Master_ResetSelectedValue); ((GridView)Master).Sorted += new EventHandler(Master_ResetSelectedValue); } public int PageSize { get { EnsureChildControls(); return ((GridView)Master).PageSize; } set { EnsureChildControls(); ((GridView)Master).PageSize = value; } } [TypeConverter(typeof(StringArrayConverter))] public string[] DataKeyNames { get { EnsureChildControls(); return ((GridView)Master).DataKeyNames; } set
912
c20.indd 912
8/20/07 8:34:11 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls { EnsureChildControls(); ((GridView)Master).DataKeyNames = value; ((DetailsView)Detail).DataKeyNames = value; } } protected override void Master_DataBound(object sender, EventArgs e) { for (int i = 0; i < ((GridView)Master).Rows.Count; i++) { if (((GridView)Master).DataKeys[i].Value == this.SelectedValue) { ((GridView)Master).SelectedIndex = i; break; } } Master_SelectedIndexChanged(null, null); } void Master_ResetSelectedValue(object sender, EventArgs e) { if (((GridView)Master).SelectedIndex != -1) { ((GridView)Master).SelectedIndex = -1; Master_SelectedIndexChanged(null, null); } } protected virtual void Master_SelectedIndexChanged(object sender, EventArgs e) { if (((GridView)Master).SelectedIndex == -1) this.Detail.Visible = false; else this.Detail.Visible = true; this.SelectedValue = ((GridView)Master).SelectedValue; UpdateDetail(sender, e); } } }
I’ll discuss the methods and properties of the MasterDetailControl server control in the following sections.
CreateBaseDataBoundControlMaster As Listing 20-1 shows, the MasterDetailControl server control overrides the CreateBaseDataBoundControlMaster method of its base class to create and return a GridView server control as the master server control. As you can see, this method instantiates a GridView server control and sets its AllowPaging, AllowSorting, AutoGenerateColumns, and AutoGenerateSelectButton properties.
913
c20.indd 913
8/20/07 8:34:11 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls
RegisterMasterEventHandlers The main responsibility of the RegisterMasterEventHandlers method is to register event handlers for those events of the master server control that require the detail server control to update. The GridView server control exposes the following three important events that meet that description, as shown in Listing 20-1:
❑
SelectedIndexChanged: The GridView server control raises this event when the end user selects a new record from the records that the control is displaying. Since the detail server control displays the details of the selected record, every time a new record is selected — that is, every time the SelectedIndexChanged event is raised — the detail server control must be updated with the details of the newly selected record. Because of this, the MasterDetailControl registers a method named Master_SelectedIndexChanged as an event handler for the SelectedIndexChanged event of the GridView server control: ((GridView)Master).SelectedIndexChanged += new EventHandler(Master_SelectedIndexChanged);
❑
PageIndexChanged: The GridView server control raises this event when the end user clicks an element in the pager user interface to display a new page of records. Since the new page of records may not include the selected record, you need to hide the detail server control until the end user makes a new selection. That is why the MasterDetailControl registers a method named Master_ResetSelectedValue as an event handler for the PageIndexChanged event of the GridView server control: ((GridView)Master).PageIndexChanged += new EventHandler(Master_ResetSelectedValue);
❑
Sorted: The GridView server control raises this event when the end user clicks the header
text of a column to sort the displayed records. Again, the newly sorted records may not include the selected record, so you need to hide the detail server control. That is why the MasterDetailControl registers the Master_ResetSelectedValue method as an event handler for the Sorted event of the GridView server control: ((GridView)Master).Sorted += new EventHandler(Master_ResetSelectedValue);
Master_SelectedIndexChanged As you can see from Listing 20-1, this method hides the detail server control if the SelectedIndex property of the master server control is set to -1 — that is, if no record is selected. There is no point in rendering the detail server control if there is no selected record to display: if (((GridView)Master).SelectedIndex == -1) this.Detail.Visible = false; else this.Detail.Visible = true
Next, the method stores the value of the SelectedValue of the GridView server control in the SelectedValue property of the MasterDetailControl: this.SelectedValue = ((GridView)Master).SelectedValue;
914
c20.indd 914
8/20/07 8:34:11 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls The MasterDetailControl inherits the SelectedValue property from the BaseMasterDetailControl. As Listing 20-1 shows, this property stores its value in the view state for future reference. It is necessary to store the selected record in the view state because the following requests may end up rebinding the GridView server control and consequently resetting the SelectedValue property of the control. In such situations, you can retrieve the selected value from the view state and assign it to the SelectedValue property of the GridView server control after rebinding the control if the control still contains the selected record. As Listing 20-1 shows, the Master_SelectedIndexChanged method finally calls the UpdateDetail method to update the detail server control. This is necessary because a new record has been selected. MasterDetailControl inherits the UpdateDetail method from its base class — that is, from the BaseMasterDetailControl. As you can see from Listing 20-1, this method first calls the DataBind
method on the detail server control to rebind the control and consequently to retrieve fresh data from the underlying data store: detail.DataBind();
Next, the method calls the Update method on the detail UpdatePanel server control to force this control to update.
Master_ResetSelectedValue As you can see from Listing 20-1, this method simply sets the SelectedIndex property of the GridView server control to -1 to signal that no record is selected, and then invokes the Master_SelectedIndexChanged method discussed in the previous section.
Master_DataBound As you can see from Listing 20-1, this method first searches through the GridViewRow server controls in the Rows collection of the GridView server control for a GridViewRow server control with the same primary key field value as the one stored in the SelectedValue property. If the search succeeds, the method assigns the index of the GridViewRow server control to the SelectedIndex property of the GridView server control to specify this GridViewRow server control as the selected row: for (int i = 0; i < ((GridView)Master).Rows.Count; i++) { if (((GridView)Master).DataKeys[i].Value == this.SelectedValue) { ((GridView)Master).SelectedIndex = i; break; } }
The GridView server control uses an instance of a server control named GridViewRow to display each of its data records. The Rows collection property of the GridView server control contains all the GridViewRow server controls that display the data records of the server control. The GridView server control exposes a collection property named DataKeys, which contains one DataKey object for each displayed data record in which the names and values of the primary key datafields of the record are stored. In other words, each DataKey object in the DataKeys collection corresponds to a GridViewRow server control in the Rows collection.
915
c20.indd 915
8/20/07 8:34:12 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls Next, the method invokes the Master_SelectedIndexChanged method discussed earlier: Master_SelectedIndexChanged(null, null);
Properties As you can see from Listing 20-1, the MasterDetailControl, like any other composite server control, exposes the properties of its child controls as its own top-level properties, as follows:
❑
PageSize: This string property exposes the PageSize property of the GridView server control as top-level property. Recall that the PageSize property of a GridView server control specifies the total number of records to display.
❑
DataKeyNames: This array property exposes the DataKeyNames property of the GridView server control as top-level property. Recall that the DataKeyNames property of a GridView server control contains the list of primary key datafield names.
Note that the DataKeyNames property is annotated with the TypeConverter(typeof(StringArray Converter)) metadata attribute to instruct the page parser that it must use the StringArrayConverter to convert the declarative value of the DataKeyNames to the array. This declarative value is the value that the page developer declaratively assigns to the DataKeyNames attribute on the tag that represents the MasterDetailControl server control on an .aspx or .ascx file. This declarative value is a string of comma-separated list of substrings in which each substring contains the name of a primary key datafield name. As the name suggests, the StringArrayConverter converts this string into an array, which the page parser then automatically assigns to the DataKeyNames property of the MasterDetailControl server control. Note that the getters and setters of these properties of the MasterDetailControl invoke the EnsureChildControls method before they attempt to access the associated child server controls, as I mentioned earlier.
Using MasterDetailControl in a Web Page Add the following files to the App_Code directory of the application that contains the page that uses the MasterDetailControl control:
❑
BaseMasterDetailControl.cs: Listing 19-12 presents the content of this file.
❑
ContainerType.cs: Listing 19-13 presents the content of this file.
❑
MasterDetailContainer.cs: Listing 19-14 presents the content of this file.
❑
BaseMasterDetailControl2.cs: Listing 19-15 presents the content of this file.
❑
MasterDetailControl.cs: Listing 20-1 presents the content of this file.
Listing 20-2 presents a page that uses the MasterDeatilControl. Note that this page uses a theme, a database with two tables named Products and Categories, and a connections string named MyConnectionString. I’ll discuss this theme, database, and connection string shortly. If you run this page, you’ll get the result shown in Figure 20-1.
916
c20.indd 916
8/20/07 8:34:12 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls Listing 20-2: A Page that Uses the MasterDetailControl Untitled Page
917
c20.indd 917
8/20/07 8:34:12 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls
Figure 20-1 As you can see, the MasterDetailControl displays only the master portion of the control. Now if you select a record from the GridView control, you’ll get the result shown in Figure 20-2: the DetailsView server control displays the detail of the selected record. Note that the DetailsView server control displays the standard Edit and Delete buttons to enable end users to edit and delete the current record from the underlying data store. The DetailsView server control also contains the New button to enable the end user to add a new record to the data store. Thanks to the ASP.NET AJAX partial page rendering infrastructure, all the user interactions with the GridView and DetailsView server controls are handled asynchronously in the background without
interrupting the user or reloading the entire page. Note that the page shown in Listing 20-2 takes advantage of ASP.NET 2.0 themes. A theme is implemented as a subfolder under the App_Themes folder. The subfolder must have the same name as the theme. A theme subfolder consists of one or more skin files and their respective image and Cascading Style Sheet files. Since ASP.NET 2.0 merges all the skin files of a theme into a single skin file, page developers can use as many skin files as necessary to organize the theme folder. Themes are assigned to the containing page, not to the the individual controls.
918
c20.indd 918
8/20/07 8:34:13 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls
Figure 20-2 The @Page directive in ASP.NET 2.0 exposes a new attribute named Theme, which is set to the name of the desired theme. Since all themes are subfolders of the App_Themes folder, the ASP.NET framework knows where to find the assigned theme. A skin file includes one or more control skins. A control skin defines the appearance properties of a class of server controls. The definition of a control skin is very similar to the declaration of an instance of the control on an ASP.NET page. This doesn’t mean that all properties of a server control can be set in its skin. In general, only the appearance properties can be included and set in a control skin. If the SkinID property of a control skin isn’t set, the control skin is treated as the default skin. A default skin is automatically applied to the control instances whose SkinID properties aren’t set. If the SkinID property of a control skin is set, it will be applied only to the control instances whose SkinID property is set to the same value.
919
c20.indd 919
8/20/07 8:34:13 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls The page shown in Listing 20-2 uses a theme named Theme1 that contains a skin file with the following content:
Also note that the page shown in Listing 20-2 connects to a database named ProductsDB that consists of two database tables named Products and Categories. The following table describes the Products database table:
Column Name
Data Type
ProductID
int
ProductName
varchar (50)
CategoryID
int
UnitPrice
decimal (18, 0)
DistributorName
varchar (50)
The following table describes the Categories database table:
Column Name
Data Type
CategoryID
int
CategoryName
varchar (50)
CategoryDescription
varchar (255)
DateCreated
datetime
920
c20.indd 920
8/20/07 8:34:13 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls Note that the data source controls in Listing 20-2 make use of a connection string named MyConnectionString. You need to add the following fragment to the web.config file of your application:
MasterDetailControl2 In this section, you’ll implement a new server control named MasterDetailControl2 that derives from BaseMasterDetailControl2 and extends its functionality to use a DropDownList server control as the master server control, as shown in Listing 20-3.
Listing 20-3: The MasterDetailControl2 Server Control using using using using using using using using using using using using
namespace CustomComponents { public class MasterDetailControl2 : BaseMasterDetailControl2 { protected override BaseDataBoundControl CreateBaseDataBoundControlMaster() { DropDownList master = new DropDownList(); master.AutoPostBack = true; master.ID = “DropDownList”; return master; } protected override void RegisterMasterEventHandlers() { ((ListControl)Master).SelectedIndexChanged += new EventHandler(Master_SelectedIndexChanged); }
(continued)
921
c20.indd 921
8/20/07 8:34:14 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls Listing 20-3 (continued) protected override void Master_DataBound(object sender, EventArgs e) { ListItem selectedItem = ((ListControl)Master).Items.FindByValue((string)SelectedValue); int selectedIndex = ((ListControl)Master).Items.IndexOf(selectedItem); ((ListControl)Master).SelectedIndex = selectedIndex; Master_SelectedIndexChanged(null, null); } protected virtual void Master_SelectedIndexChanged(object sender, EventArgs e) { if (((ListControl)Master).SelectedIndex == -1) this.Detail.Visible = false; else this.Detail.Visible = true; this.SelectedValue = ((ListControl)Master).SelectedValue; this.UpdateDetail(sender, e); } public string DataTextField { get { return ((ListControl)Master).DataTextField; } set { ((ListControl)Master).DataTextField = value; } } public string DataValueField { get { return ((ListControl)Master).DataValueField; } set { ((ListControl)Master).DataValueField = value; } } [TypeConverter(typeof(StringArrayConverter))] public string[] DataKeyNames { get { return ((DetailsView)Detail).DataKeyNames; }
922
c20.indd 922
8/20/07 8:34:14 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls set { ((DetailsView)Detail).DataKeyNames = value; } } } }
CreateBaseDataBoundControlMaster As you can see from Listing 20-3, the MasterDetailControl2’s implementation of this method instantiates and initializes a DropDownList server control as the master server control.
RegisterMasterEventHandlers As Listing 20-3 shows, this method registers a method named Master_SelectedIndexChanged as an event handler for the SelectedIndexChanged event of the master server control. Note that this method treats the master server control as a ListControl object rather than a DropDownList. This is possible because the ASP.NET DropDownList server control derives from the ListControl base class. As you’ll see in the next section, treating the master server control as a ListControl enables you to use the same implementation of the RegisterMasterEventHandlers method for all types of ListControl controls, such as DropDownList and ListBox.
Master_SelectedIndexChanged When the ListControl control raises the SelectedIndexChanged event, the Master_SelectedIndexChanged method shown in Listing 20-3 is automatically invoked. This method first checks whether any item has been selected from the ListControl control. If not, it hides the detail server control, as I mentioned earlier: if (((ListControl)Master).SelectedIndex == -1) this.Detail.Visible = false; else this.Detail.Visible = true;
Next, it assigns the value of the SelectedValue property of the ListControl control to the SelectedValue property of the MasterDetailControl2 control: this.SelectedValue = ((ListControl)Master).SelectedValue;
Finally, it invokes the UpdateDetail method to update the detail server control. As discussed earlier, the detail server control picks up the new value of the SelectedValue property of the MasterDetailControl2 and displays the detail information about the selected item: this.UpdateDetail(sender, e);
Master_DataBound Recall that the Master_DataBound method is automatically invoked when the DataBound event of the master server control is fired. As you can see from Listing 20-3, this method first accesses the ListItem
923
c20.indd 923
8/20/07 8:34:14 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls object whose value is given by the SelectedValue property of the MasterDetailControl2. Recall that this property contains the value associated with the selected item: ListItem selectedItem = ((ListControl)Master).Items.FindByValue((string)SelectedValue);
Next, it accesses the index of the selected item: int selectedIndex = ((ListControl)Master).Items.IndexOf(selectedItem);
Then it assigns this index to the SelectedIndex property of the ListControl master: ((ListControl)Master).SelectedIndex = selectedIndex;
Finally, it invokes the SelectedIndexChanged method discussed earlier: Master_SelectedIndexChanged(null, null);
Properties MasterDetailControl2, like any other composite control, exposes the properties of its child controls as its own top-level properties, as shown in Listing 20-3. Note that the DataKeyNames property is annotated with the [TypeConverter(typeof(StringArrayConverter))] metadata attribute to instruct the page parser that it must use the StringArrayConverter to convert the declarative value of this
property to its imperative value. The declarative value is the string containing a list of comma-separated substrings that the page developer assigns to the DataKeyNames attribute on the tag that represents the MasterDetailControl2 control on the .aspx page. The imperative value is the value that the DataKeyNames property expects — that is, an array of strings. The StringArrayConverter knows how to convert the string containing a list of comma-separated substrings to a .NET array that contains these substrings.
Using MasterDetailControl2 Listing 20-4 presents a page that uses the MasterDetailControl2. Figure 20-3 shows what you’ll see on your browser when you access this page. Note that this page uses a theme named Theme1 that contains a skin file with the following content:
924
c20.indd 924
8/20/07 8:34:14 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls
This page assumes that the following files are added to the App_Code directory of the application that contains the page:
❑
BaseMasterDetailControl.cs: Listing 19-12 presents the content of this file.
❑
ContainerType.cs: Listing 19-13 presents the content of this file.
❑
MasterDetailContainer.cs: Listing 19-14 presents the content of this file.
❑
BaseMasterDetailControl2.cs: Listing 19-15 presents the content of this file.
❑
MasterDetailControl.cs: Listing 20-1 presents the content of this file.
❑
MasterDetailControl2.cs: Listing 20-3 presents the content of this file.
Also note that this page uses the same database (ProductsDB) and connection string discussed in the previous section. Again, thanks to the ASP.NET AJAX partial page infrastructure, every time the end user selects a new item from the DropDownList master control, or deletes, inserts, or updates a record in the DetailsView detail control, the following things happen:
❑
The current page is posted back to the server asynchronously in the background, without interrupting the user interaction with the current page.
❑
When the server response finally arrives, only the MasterDetailControl2 is updated, without causing the entire page to reload.
Listing 20-4: A Page that Uses MasterDetailControl2 Untitled Page
(continued)
925
c20.indd 925
8/20/07 8:34:15 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls Listing 20-4 (continued)
926
c20.indd 926
8/20/07 8:34:15 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls
Figure 20-3
MasterDetailControl3 In this section, you’ll implement a new server control named MasterDetailControl3 that derives from MasterDetailControl2 and extends its functionality to use a ListBox server control rather than the DropDownList server control as master server control, as shown in Listing 20-5. As you can see, MasterDetailControl3 simply overrides the CreateBaseDataBoundControlMaster method that it inherits from MasterDetailControl2 and replaces the DropDownList server control with a ListBox server control.
Listing 20-5: The MasterDetailControl3 Control using System; using System.Data; using System.Configuration;
(continued)
927
c20.indd 927
8/20/07 8:34:15 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls Listing 20-5 (continued) using using using using using using using
namespace CustomComponents { public class MasterDetailControl3 : MasterDetailControl2 { protected override BaseDataBoundControl CreateBaseDataBoundControlMaster() { ListBox master = new ListBox(); master.AutoPostBack = true; master.ID = “ListBox”; return master; } } }
Using MasterDetailControl3 Listing 20-6 contains a page that uses MasterDetailControl3. Note that this page uses a theme named Theme1, which contains a skin file with the following content:
Note also that this page assumes that the following files are added to the App_Code directory of the application that contains this page:
❑
BaseMasterDetailControl.cs: Listing 19-12 presents the content of this file.
❑
ContainerType.cs: Listing 19-13 presents the content of this file.
❑
MasterDetailContainer.cs: Listing 19-14 presents the content of this file.
❑
BaseMasterDetailControl2.cs: Listing 19-15 presents the content of this file.
928
c20.indd 928
8/20/07 8:34:16 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls ❑
MasterDetailControl.cs: Listing 20-1 presents the content of this file.
❑
MasterDetailControl2.cs: Listing 20-3 presents the content of this file.
❑
MasterDetailControl3.cs: Listing 20-5 presents the content of this file.
Also note that this page uses the same database (ProductsDB) and connection string as the pages in the previous sections. Figure 20-4 shows what you’ll get when you access this page. As you can see, the master server control is now a ListBox server control. Again, thanks to the ASP.NET AJAX partial page infrastructure, every time the end user selects a new item from the ListBox master control or deletes, inserts, or updates a record in the DetailsView detail control, the following things happen:
❑
The current page is posted back to the server asynchronously in the background, without interrupting the user interaction with the current page.
❑
When the server response finally arrives, only the MasterDetailControl3 is updated, without causing the entire page to reload.
Listing 20-6: A Page that Uses the MasterDetailControl3 Control Untitled Page
(continued)
929
c20.indd 929
8/20/07 8:34:16 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls Listing 20-6 (continued)
MasterDetailControl4 In this section I’ll implement a server control named MasterDetailControl4 that derives from the MasterDetailControl2 and overrides its SelectedValue property. Recall that the MasterDetailControl2 inherits this property from the BaseMasterDetailControl. MasterDetailControl4 overrides this property to use the ASP.NET Session object as the backing store. Recall that the BaseMasterDetailControl’s implementation of this property uses the ViewState as the backing store. In the next section we’ll implement a custom data control field that will demonstrate the significance of using the ASP.NET Session object as the backing store. Listing 20-7 presents the implementation of MasterDetailControl4.
Listing 20-7: The MasterDetailControls4 Server Control namespace CustomComponents { public class MasterDetailControl4 : MasterDetailControl2 { public override object SelectedValue { get { return this.Page.Session[“SelectedValue”]; } set { this.Page.Session[“SelectedValue”] = value; } } } }
930
c20.indd 930
8/20/07 8:34:16 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls
Figure 20-4
Developing Par tial-Rendering-Enabled Data Control Fields The foreign and primary key pairs establish relationships among database tables. The value of a foreign key field in a given record is one of the existing values of its corresponding primary key field. Most database tables automatically generate the primary key value of a record when the record is added to the table. Therefore the actual foreign key value is an auto-generated integer that doesn’t mean anything to end users. However, the table that contains the primary key field normally contains other field values that are more meaningful to them. For instance, consider a database that contains tables named Products and Categories. The Products table has a foreign key field named CategoryID. The Categories table contains the corresponding primary key field, CategoryID. The Categories table also exposes fields such as CategoryName and
931
c20.indd 931
8/20/07 8:34:16 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls CategoryDescription, which provide more meaningful information to end users. Wouldn’t it be great if you could provide end users the appropriate user interface with which to view more meaningful information about the available categories, so they can make more intelligent decisions as to which category to choose for a given record? This is exactly what you’re going to do in this section. You’ll implement a custom data control field named MasterDetailField that will present the end users with a user interface that consists of a DropDownList master server control and a DetailsView detail server control, so users can view more detailed information about a given foreign key field. The MasterDetailField will take advantage of the ASP.NET AJAX partial rendering infrastructure to retrieve the required data from the server asynchronously and to update only the necessary part of the page — that is, the detail server control — without forcing a complete page reload.
As you’ll see, the MasterDetailField data control field not only displays detailed information about a selected foreign key field value but also enables the end user to update this information. In other words, the end user gets to update the records of both the table that contains the primay key field values and the table that contains the associated foreign key field values, simultaneously.
Extending BoundField Most standard data control fields internally use server controls to display the values of their respective database fields. For example, the ImageField and CheckBoxField data control fields internally use Image and CheckBox server controls, respectively, to display their field values. The data type of the field and the state of its containing row determine the type of server control used to display the value of the field. For instance, an ImageField data control field uses an Image server control to display its field value when its containing row is in the normal state, and a TextBox server control when its containing row is in the Edit or Insert state. The MasterDetailField custom data control field will use a MasterDetailControl4 server control to display all the legal values of its field when its containing row is in the Edit or Insert state. The MasterDetailField data control field will display the current value of its field as simple text when its containing row isn’t in the Edit or Insert state. The MasterDetailField data control field derives from the BoundField data control field because BoundField provides all the necessary base functionality when the containing row isn’t in the Edit or Insert state, such as:
❑
Extracting the current value of the field whose name is the value of the DataField property. The MasterDetailField overrides this property and defines a new property named DataTextField to replace it because DataTextField is a more appropriate name than DataField.
❑
Displaying the current value as simple text if the current value isn’t null.
❑
Displaying the value of the NullDisplayText property if the current value is null.
❑
Displaying the value of the HeaderText property as simple text if sorting is disabled and as a hyperlink if sorting is enabled.
❑
Raising the sort event when sorting is enabled and the header hyperlink is clicked.
The main shortcoming of the BoundField data control field is that it displays the current value of the field in a TextBox control when the containing row is in the Edit or Insert state. The TextBox control is not the appropriate server control for editing foreign key fields because it enables users to enter any value instead of restricting values to the legal ones. The MasterDetailField data control field overrides the InitializeDataCell, OnDataBindField, and ExtractValuesFromCell methods of the
932
c20.indd 932
8/20/07 8:34:17 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls BoundField data control field to add the support needed when the containing row is in the Edit or Insert state. Listing 20-8 shows all the properties and methods of the MasterDetailField data control field. In the following sections I’ll walk you through the implementation of these properties and methods.
Listing 20-8: The MasterDetailField Data Control Field namespace CustomComponents { using System; using System.Web; using System.Web.UI; using System.Web.UI.WebControls; using System.ComponentModel; using System.Collections.Specialized; using System.Collections; using System.Data; public class MasterDetailField : BoundField { public override string DataField { get { return base.DataField; } set { throw new global::System.NotImplementedException(); } } public virtual string DataTextField { get { return base.DataField; } set { base.DataField = value; } } public virtual string MasterSkinID { get { return (ViewState[“MasterSkinID”] != null) ? (string)ViewState[“MasterSkinID”] : String.Empty; }
(continued)
933
c20.indd 933
8/20/07 8:34:17 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls Listing 20-8 (continued) set { ViewState[“MasterSkinID”] = value; } } public virtual string DetailSkinID { get { return (ViewState[“DetailSkinID”] != null) ? (string)ViewState[“DetailSkinID”] : String.Empty; } set { ViewState[“DetailSkinID”] = value; } } [TypeConverter(typeof(StringArrayConverter))] public virtual string[] DataKeyNames { get { return (ViewState[“DataKeyNames”] != null) ? (string[])ViewState[“DataKeyNames”] : null; } set { ViewState[“DataKeyNames”] = value; } } public virtual bool EnableTheming { get { return (ViewState[“EnableTheming”] != null) ? (bool)ViewState[“EnableTheming”] : true; } set { ViewState[“EnableTheming”] = value; } } public virtual string DataValueField { get { return (ViewState[“DataValueField”] != null) ? (string)ViewState[“DataValueField”] : String.Empty; }
934
c20.indd 934
8/20/07 8:34:17 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls set { ViewState[“DataValueField”] = value; } } public virtual string MasterDataSourceID { get { return (ViewState[“MasterDataSourceID”] != null) ? (string)ViewState[“MasterDataSourceID”] : String.Empty; } set { ViewState[“MasterDataSourceID”] = value; } } public virtual string DetailDataSourceID { get { return (ViewState[“DetailDataSourceID”] != null) ? (string)ViewState[“DetailDataSourceID”] : String.Empty; } set { ViewState[“DetailDataSourceID”] = value; } } protected override void OnDataBindField(Object sender, EventArgs e) { DropDownList ddl = sender as DropDownList; if (ddl == null) { base.OnDataBindField(sender, e); return; } Control parent = ddl.Parent; DataControlFieldCell cell = null; while (parent != null) { cell = parent as DataControlFieldCell; if (cell != null) break; parent = parent.Parent; }
(continued)
935
c20.indd 935
8/20/07 8:34:18 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls Listing 20-8 (continued) IDataItemContainer container = (IDataItemContainer)cell.Parent; object dataItem = container.DataItem; if (dataItem == null || String.IsNullOrEmpty(DataValueField)) return; object dataValueField = DataBinder.Eval(dataItem, DataValueField); if (dataValueField.Equals(DBNull.Value)) ddl.SelectedIndex = 0; else ddl.SelectedIndex = ddl.Items.IndexOf(ddl.Items.FindByValue(dataValueField.ToString())); } protected override void InitializeDataCell(DataControlFieldCell cell, DataControlRowState rowState) { if ((rowState & DataControlRowState.Edit) != 0 || (rowState & DataControlRowState.Insert) != 0) { MasterDetailControl4 mdc = new MasterDetailControl4(); mdc.MasterSkinID = MasterSkinID; mdc.DetailSkinID = DetailSkinID; mdc.EnableTheming = EnableTheming; mdc.MasterDataSourceID = this.MasterDataSourceID; mdc.DetailDataSourceID = this.DetailDataSourceID; mdc.DataKeyNames = DataKeyNames; ((DropDownList)mdc.Master).DataTextField = DataTextField; ((DropDownList)mdc.Master).DataValueField = DataValueField; if (DataTextField.Length != 0 && DataValueField.Length != 0) ((DropDownList)mdc.Master).DataBound += new EventHandler(OnDataBindField); cell.Controls.Add(mdc); } else base.InitializeDataCell(cell, rowState); } public override void ExtractValuesFromCell(IOrderedDictionary dictionary, DataControlFieldCell cell, DataControlRowState rowState, bool includeReadOnly) { if (cell.Controls.Count > 0) { MasterDetailControl4 mdc = cell.Controls[0] as MasterDetailControl4; if (mdc == null) throw new InvalidOperationException( “MasterDetailField could not extract control.”); string dataValueField = ((DropDownList)mdc.Master).SelectedValue;
936
c20.indd 936
8/20/07 8:34:18 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls if (dictionary.Contains(DataValueField)) dictionary[DataValueField] = int.Parse(dataValueField); else dictionary.Add(DataValueField, int.Parse(dataValueField)); } } } }
Overriding InitializeDataCell The BoundField data control field exposes a method named InitializeDataCell that contains the code that generates the appropriate HTML markup text for the data cell. The InitializeDataCell method takes two arguments. The first argument is the DataControlFieldCell cell being initialized. The second argument is the state of the containing row. What HTML markup text the BoundField class’s implementation of the InitializeDataCell method emits depends on the state of its containing row. If the containing row is not in the Edit or Insert state, the method simply registers the OnDataBindField method as the callback for the DataBinding event of the respective DataControlFieldCell instance. When the DataBinding event of the cell is raised, the OnDataBindField method extracts the current value of the respective field (the name of the field is the value of the DataField property). If the current value is null, the value of the NullDisplayText property is displayed. Otherwise the current value is displayed as simple text. The BoundField class’s implementation of the InitializeDataCell method in normal state is exactly what you need. However, the BoundField class’s implementation of the method when the containing row is in the Edit or Insert state is not acceptable, because the method instantiates an instance of the TextBox control. You need an implementation that instantiates an instance of the MasterDetailControl4 control. That is why the MasterDetailField data control field overrides the InitializeDataCell method. The MasterDetailField data control field calls the base version of the InitializeDataCell method when the containing row is in the normal state, because the behavior of the base version is exactly what you need. However, the MasterDetailField data control field provides its own implementation when the containing row is in the Edit or Insert state. As Listing 20-8 shows, the MasterDetailField data control field’s implementation of the InitializeDataCell method instantiates an instance of the MasterDetailControl4 control and sets its MasterDataSourceID and DetailDataSourceID properties to the values of the MasterDataSourceID and DetailDataSourceID properties of the MasterDetailField data control field, respectively. It is the responsibility of page developers to set the MasterDataSourceID and DetailDataSourceID properties of the MasterDetailField data control field to the values of the ID properties of the appropriate data source controls in the containing page. Page developers must also set the DataTextField and DataValueField properties of the MasterDetailField data control field to the names of the appropriate database fields. This allows the MasterDetailField data control field to automatically populate its MasterDetailControl4 control with the valid values of the foreign key field. Note that InitializeDataCell method also sets the DataKeyNames property of the MasterDetailControl4 control to the value of the DataKeyNames property of the
937
c20.indd 937
8/20/07 8:34:18 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls MasterDetailField. Again, it’s the responsibility of page developers to assign the comma-separated list of primary key field names to the DataKeyNames property of the MasterDetailField: MasterDetailControl4 mdc = new MasterDetailControl4(); mdc.MasterSkinID = MasterSkinID; mdc.DetailSkinID = DetailSkinID; mdc.EnableTheming = EnableTheming; mdc.MasterDataSourceID = this.MasterDataSourceID; mdc.DetailDataSourceID = this.DetailDataSourceID; mdc.DataKeyNames = DataKeyNames; ((DropDownList)mdc.Master).DataTextField = DataTextField; ((DropDownList)mdc.Master).DataValueField = DataValueField;
One of the requirements for the MasterDetailField data control field is that it has to set the selected value of the MasterDetailControl4 control to the current value of the respective foreign key field. This is done in a callback registered for the DataBound event of the DropDownList master server control of the MasterDetailControl4 control. The DropDownList control inherits the DataBound event from the BaseDataBoundControl class. There is a difference between the DataBound event that the BaseDataBoundControl class exposes and the DataBinding event that the Control class exposes: the DataBinding event is raised before the data is actually bound, while the DataBound event is raised after the data binding process finishes. Since the selected value of the MasterDetailControl4 control must be set after the control is bound to its data source, it is set within the callback for the DataBound event. The InitializeDataCell method registers the OnDataBindField method as the callback for the DataBound event of the DropDownList master server control: if (DataTextField.Length != 0 && DataValueField.Length != 0) ((DropDownList)mdc.Master).DataBound += new EventHandler(OnDataBindField);
Handling the DataBound Event When the DataBinding event of the cell is raised, the OnDataBindField method is called to display the current value in display mode — that is, as a simple text. When the DataBound event of the DropDownList master server control of the MasterDetailControl4 control is raised, the OnDataBindField method is called to display the current value in edit mode — that is, as the selected item of the MasterDetailControl4 control. Before the OnDataBindField method can display the current value in the edit or insert mode, it has to extract the value. The OnDataBindField method uses the parent control of the cell to access the value: Control parent = ddl.Parent; DataControlFieldCell cell = null; while (parent != null) { cell = parent as DataControlFieldCell; if (cell != null) break; parent = parent.Parent; }
938
c20.indd 938
8/20/07 8:34:18 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls IDataItemContainer container = (IDataItemContainer)cell.Parent; object dataItem = container.DataItem;
The parent of the cell is a row of type GridViewRow in GridView controls and of type DetailsViewRow in DetailsView controls. Both these types implement the IDataItemContainer interface. IDataItemContainer exposes a property named DataItem of type Object. The DataItem object represents the record of the database that the row is bound to. After you access the dataItem object, you can use the DataBinder class to extract the current value of the field whose name is the value of the DataValueField property: object dataValueField = DataBinder.Eval(dataItem, DataValueField);
The value of the DataValueField property is the name of the foreign key field. The OnDataBindField method then sets the SelectedIndex of the DropDownList master server control of the MasterDetailControl4 control to the index of dataValueField if dataValueField is not equal to DBNull. Otherwise it configures this DropDownList server control to display the newly added item as its selected item: if (dataValueField.Equals(DBNull.Value)) ddl.SelectedIndex = 0; else ddl.SelectedIndex = ddl.Items.IndexOf(ddl.Items.FindByValue(dataValueField.ToString()));
Extracting Values from Cells Data-bound controls such as GridView and DetailsView enable users to edit database fields. Users click on the Update button after they make the desired changes. GridView and DetailsView controls are equipped with internal handlers to handle the Update event. These handlers call the ExtractRowValues method of the GridView or DetailsView control, which in turn calls the ExtractValuesFromCell methods of its cells. The ExtractRowValues method provides each ExtractValuesFromCell method with a container of type IOrderedDictionary. Each ExtractValuesFromCell method extracts the value of its cell and inserts the value into the container. The internal handler for the Update event then uses these values in its internal data access code to update the underlying database fields. The ExtractValuesFromCell method of the MasterDetailField data control field extracts the selected value of the MasterDetailControl4 control and inserts it into the IOrderedDictionary container passed in as its first input argument.
Appearance Properties The DataControlField class exposes a property of type Style named ControlStyle. The DataControlField class internally uses the value of the ControlStyle property to set the style properties of the server control that the DataControlField instance renders. In the case of the MasterDetailField data control field, the ControlStyle property is applied to the MasterDetailControl4 control that the class contains.
939
c20.indd 939
8/20/07 8:34:19 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls The ControlStyle property is not the only styling option available. Another styling option is the ASP.NET 2.0 themes. The MasterDetailField class exposes two new properties named MasterSkinID and DetailSkinID. It’s the responsibility of page developers to set these two properties to the values of the SkinID properties of the desired DropDownList and DetailsView control skins, respectively. The InitializeDataCell method sets the MasterSkinID and DetailSkinID properties of the MasterDetailControl4 control to the values of the MasterSkinID and DetailSkinID properties of the MasterDetailField object. Themes give page developers full control over the appearance properties of the MasterDetailControl4 control that the MasterDetailField object renders.
Using MasterDetailField Page developers can use the MasterDetailField data control field declaratively. Listing 20-9 shows a page that uses an instance of the MasterDetailField declaratively. Note that this page uses a theme that contains the following skin file:
As Listing 20-9 shows, the SkinID property values of the preceding two control skins are assigned to the MasterSkinID and DetailSkinID properties, respectively, of the MasterDetailField data control field. Note that this page assumes that the following files are added to the App_Code directory of the application that contains this page:
❑
BaseMasterDetailControl.cs: Listing 19-12 presents the content of this file.
❑
ContainterType.cs: Listing 19-13 presents the content of this file.
❑
MasterDetailContainer.cs: Listing 19-14 presents the content of this file.
❑
BaseMasterDetailControl2.cs: Listing 19-15 presents the content of this file.
❑
MasterDetailControl.cs: Listing 20-1 presents the content of this file.
❑
MasterDetailControl2.cs: Listing 20-3 presents the content of this file.
❑
MasterDetailControl4.cs: Listing 20-7 presents the content of this file.
940
c20.indd 940
8/20/07 8:34:19 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls ❑
MasterDetailField.cs: Listing 20-8 presents the content of this file.
❑
Product.cs: The following code listing presents the content of this file. (Notice that the ObjectDataSource control shown in Listing 20-9 uses the Product class defined in this file.)
public class Product { public static IEnumerable Select(string sortExpression) { string connectionString = ConfigurationManager.ConnectionStrings[“MyConnectionString”].ConnectionString; string commandText = “Select CategoryName, ProductName, ProductID,” + “Products.CategoryID As CategoryID From Products, Categories “ + “Where Products.CategoryID = Categories.CategoryID”; if (!string.IsNullOrEmpty(sortExpression)) commandText += “ Order By “ + sortExpression; SqlConnection con = new SqlConnection(connectionString); SqlCommand com = new SqlCommand(commandText, con); con.Open(); return com.ExecuteReader(CommandBehavior.CloseConnection); } public static void Update(int ProductID, string ProductName, int CategoryID) { string connectionString = ConfigurationManager.ConnectionStrings[“MyConnectionString”].ConnectionString; string commandText = “Update Products Set ProductName=@ProductName,” + “CategoryID=@CategoryID Where ProductID=@ProductID”; SqlConnection con = new SqlConnection(connectionString); SqlCommand com = new SqlCommand(commandText, con); com.Parameters.AddWithValue(“@ProductName”, ProductName); com.Parameters.AddWithValue(“@CategoryID”, CategoryID); com.Parameters.AddWithValue(“@ProductID”, ProductID); con.Open(); com.ExecuteNonQuery(); con.Close(); } }
941
c20.indd 941
8/20/07 8:34:19 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls Also note that the page shown in Listing 20-9 uses the same database (ProductsDB) and connection string as the pages in the previous sections.
Listing 20-9: Using the MasterDetailField Data Control Field Declaratively Untitled Page
942
c20.indd 942
8/20/07 8:34:20 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls
If you run this page, you’ll get the result shown in Figure 20-5. Now, if you click the Edit link on the fifth row, you’ll get the result shown in Figure 20-6. As you can see, the Category cell now contains the MasterDetailControl4 server control, which consists of a DropDownList master server control and a DetailsView detail server control.
Figure 20-5
943
c20.indd 943
8/20/07 8:34:20 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls
Figure 20-6 Note that the DetailsView detail server control contains the standard Edit, Delete, and New buttons to enable the end user to edit an existing category, delete a category, and add a new category. If you click the Edit button, you’ll get the result shown in Figure 20-7.
Figure 20- 7
944
c20.indd 944
8/20/07 8:34:20 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls The great thing about the MasterDetailField is that it takes full advantage of the ASP.NET AJAX partial page rendering infrastructure where all these operations are performed asynchronously in the background without interrupting the user interaction with the current page and without causing the entire page to reload.
Developing Par tial-Rendering-Enabled User Controls The previous section showed you how to develop custom server controls that take full advantage of the ASP.NET AJAX partial page rendering infrastructure to:
❑
Perform page postbacks to the server asynchronously, without interrupting the user interaction
❑
Update themselves without causing the entire page to reload
This section will show you how to develop user controls that achieve similar goals. To make our discussions more concrete, I’ll develop a partial-rendering-enabled threaded discussion forum user control that you can use in your own Web applications. Before diving into the details of the implementation of this user control, let’s see what it looks like in action. Figure 20-8 shows this user control.
Figure 20- 8 As you can see, this user control consists of two main parts: the top part is a TreeView server control that displays the subjects of all the messages of the threaded discussion forum. When the end user clicks a given subject, the DetailsView control at the bottom of the user control displays detailed information about the message, including its body. Note that this DetailsView control contains the standard Reply, Edit, and Delete buttons to enable the end user to reply to, edit, or delete a message. For example, when the end user clicks the Reply button, the page shown in Figure 20-9 is displayed, which includes the user interface that enables the user to enter the reply to the specified message.
945
c20.indd 945
8/20/07 8:34:21 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls
Figure 20- 9 Listing 20-10 presents the implementation of the partial-rendering-enabled threaded discussion forum user control. As you can see from this code listing, this user control consists of two UpdatePanel server controls with ID property values of MasterUpdatePanel and DetailUpdatePanel. Note that the UpdateMode properties of both UpdatePanel server controls are set to Conditional to ensure that they get updated only when the required conditions are met. Notice that the top and bottom UpdatePanel server controls respectively contain the TreeView and DetailsView server controls discussed earlier. Since the TreeView and DetailsView server controls are the children of these UpdatePanel server controls and since these UpdatePanel server controls update conditionally, the partial-rendering-enabled threaded discussion forum user control takes full advantage of the ASP.NET AJAX partial rendering infrastructure to ensure that all the communications with the backend server are done asynchronously in the background without interrupting the end user’s interactions with the page that contains the user control, and to ensure that all the page updates are limited to the associated UpdatePanel server controls without reloading the entire page all over again.
946
c20.indd 946
8/20/07 8:34:21 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls Listing 20-10: The Partial-Rendering-Enabled Threaded Discussion Forum User Control
public string DataFile { get { return MySource.DataFile; } set { MySource.DataFile = value; MySource2.DataFile = value; } } void DataBound(Object sender, TreeNodeEventArgs e) { if (((XmlNode)e.Node.DataItem).LocalName == “Message”) e.Node.Text = XPathBinder.Eval(e.Node.DataItem, “Subject”).ToString() + “, by “ + XPathBinder.Eval(e.Node.DataItem, “@UserName”).ToString() + “ “ + XPathBinder.Eval(e.Node.DataItem, “@AddedDate”).ToString(); } void SelectedNodeChanged(object sender, EventArgs e) { MySource2.XPath = TreeView1.SelectedNode.DataPath; if (DetailsView1.CurrentMode != DetailsViewMode.ReadOnly) DetailsView1.ChangeMode(DetailsViewMode.ReadOnly); DetailUpdatePanel.Update(); } void DetailsView_ItemCommand(object sender, DetailsViewCommandEventArgs e) { switch (e.CommandName) { case “SubmitUpdate”: Update(); break; case “SubmitInsert”: Insert(); break; case “SubmitDelete”: Delete(); break; }
Chapter 20: Using UpdatePanel in User Controls and Custom Controls void Delete() { XmlDocument doc = MySource2.GetXmlDocument(); XmlNode message = doc.SelectSingleNode(TreeView1.SelectedNode.DataPath); message.ParentNode.RemoveChild(message); MySource2.XPath = “”; Save(); } void Save() { MySource2.Save(); if (DetailsView1.CurrentMode != DetailsViewMode.ReadOnly) DetailsView1.ChangeMode(DetailsViewMode.ReadOnly); Cache.Remove(“MyKey”); TreeView1.DataBind(); } void NewThreadClick(object sender, EventArgs e) { DetailsView1.ChangeMode(DetailsViewMode.Insert); ViewState[“NewThread”] = “NewThread”; } New Thread
(continued)
949
c20.indd 949
8/20/07 8:34:22 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls Listing 20-10 (continued)
,
Reply Edit Delete
950
c20.indd 950
8/20/07 8:34:22 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls
<strong>Reply
<strong>Subject:
<strong>Body:
<strong>Edit
(continued)
951
c20.indd 951
8/20/07 8:34:23 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls Listing 20-10 (continued)
<strong>Subject:
<strong>Body:
952
c20.indd 952
8/20/07 8:34:23 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls The partial-rendering-enabled threaded discussion forum uses an XML document as its underlying data store. Listing 20-11 shows part of the XML document.
Listing 20-11: Part of the XML Document that Stores the Messages Looking for a good book on ASP.NET I’m looking for a book with lot of examples. Are you looking for a book for beginners? What kind of book are you looking for? Books for beginers with lot of examples I’m looking for a book with lot of examples What sort of examples? Could you be more specific? Examples with practical applications Code examples that I could use in my work New ASP.NET books are coming out You may want to checkout amazon.com for new books on ASP.NET Thanks, I will I will check out amazon.com. I may get lucky there. Any one has code examples for data source controls I need code examples that show how to use data source controls in big applications What type of data source controls? There are all kinds of data source controls. Which ones are you planning on using?
953
c20.indd 953
8/20/07 8:34:23 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls Root Messages Message Subject
Body
text()
text()
AddedDate
UserName
Subject
Body
text()
text()
Message Message
AddedDate
Message
UserName
Message
Message
Message
Subject
Body
text()
text()
Message
AddedDate
UserName
Figure 20- 10 A element represents a posted message in which the and child elements contain the subject and body, respectively. The AddedDate and UserName attributes of a given element represent the date on which the message was added and the user name of the author, respectively. As Listing 20-10 shows, the partial-rendering-enabled threaded discussion forum user control uses an XmlDataSource server control to interact with the underlying XML document. The XmlDataSource control must first load the document into memory. The XmlDataSource control uses the W3C DOM model to load the entire contents of the messages.xml file into an instance of the XmlDocument class and generates the in-memory tree representation of the document, as shown in Figure 20-10. Let us compare the XmlDataSource and SqlDataSource loading models. The SqlDataSource control loads the underlying database tables into an instance of the DataSet class, and generates the in-memory tabular representation of the underlying tables. The in-memory tabular representation consists of interconnected rows, each of which is an instance of the DataRow class. Now compare that with the in-memory tree representation such as the one shown in Figure 20-10, which consists of interconnected nodes, each of which is an instance of the XmlNode class. The XmlNode class is an abstract class that represents any type of node. Each of its subclasses represents a particular type of node. For instance, the XmlElement subclass represents element nodes, such as , , and , while the XmlAttribute subclass represents attribute nodes, such as AddedDate and UserName. When you select, delete, insert, or update a row in a DataSet object, you do not directly select, delete, insert, or update the corresponding row in the underlying database table because the DataSet object is not connected to the database. In other words, you select, delete, insert, or update the row in the in-memory tabular representation of the database table, not the database table itself. That is why the changes made to the in-memory tabular representation must be explicitly committed to the underlying database tables. The same logic applies to the XmlDocument object that has been loaded with the data from the underlying messages.xml file. When you select, delete, insert, or update a node in the XmlDocument object, you do not directly select, delete, insert, or update the corresponding node in the underlying XML document, because the XmlDocument object is not connected to the underlying XML file itself. You are really manipulating the node in the in-memory tree representation of the XML document, not the file itself.
954
c20.indd 954
8/20/07 8:34:23 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls Again, that is why the changes to made the in-memory tree representation must be explicitly committed to the underlying XML file. In order to select, delete, insert, or update a row or node, you have to first select, delete, insert, or update the row or node in the corresponding tabular or tree representation and then commit the changes to the underlying data store. Since a tabular or tree representation is a collection of rows or nodes, you cannot select, delete, insert, or update a row or node in the collection unless you have a way to locate and identify that row or node. Page developers use the primary key of a row to uniquely locate and identify the row in the underlying tabular representation. The primary key of a row plays a crucial role in data operations because without it there is no way to know which row is being selected, deleted, updated, or inserted. The XPath data model uses a concept known as hierarchical or location path to uniquely locate or identify a node in the tree hierarchy. The hierarchical or location paths play the same role in a tree hierarchy that primary keys play in a tabular representation. Without it there is no way to know which node is being selected, deleted, updated, or inserted. As Figure 20-10 shows, every node in the tree is the root node of yet another tree, unless the node is a leaf node. This means the tree is a hierarchy of trees of which each tree is built out of smaller trees. Since you have to locate the root node of a subtree in order to locate the subtree itself, the location of the root node of a subtree uniquely identifies the subtree in the hierarchy of trees. This means that the hierarchical path of a node in a tree hierarchy uniquely identifies and locates not only the node itself but also the subtree associated with the node. The primary key of a row is normally an autogenerated integer number with a unique value. The hierarchical or location path of a node, on the other hand, is built out of the location steps of its ancestor nodes all the way up to the root node of the entire tree hierarchy. The hierarchical path of a node is based on an imaginary journey from the root node of the tree all the way down to the node itself. The journey consists of several location steps. Each location step takes you from your current node to the next. Let us consider an example. Suppose you want to locate the gray node in Figure 20-10. The journey begins at the root node of the entire tree hierarchy. The XPath data model uses the notation / to represent the root node. The first location step, Messages[position()=1], takes you from the root node to the Messages node. So far the location path is /Messages[position()=1]. The second location step, Message[position()=1], takes you from the Messages node to the first Message node. The location path so far is /Messages[position()=1]/Message[position()=1]. The third location step, Message[position()=3], takes you from the current Message node to the next Message node. The location path is now /Messages[position()=1]/Message[position()=1]/ Message[position()=3]. The final location step, Message[position()=3], takes you to the destination, the gray node. Therefore the location path of the gray node is as follows: /Messages[position()=1]/Message[position()=1]/Message[position()=3]/ Message[position()=3]
As the example shows, the loation path of a node, such as the gray node, uniquely identifies and locates the node and its associated subtree in the tree hierarchy. The XmlDataSource control provides hierarchical data-bound controls such as TreeView and Menu with the hierarchical views of the underlying XML document. A hierarchical view represents a particular subtree in the in-memory tree representation of the document. Therefore the hierarchical path of the root
955
c20.indd 955
8/20/07 8:34:24 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls node of a subtree uniquely identifies the hierarchical view that represents the subtree. That is why the hierarchical path of the root node of a subtree is also referred to as a view path. Every hierarchical view has a unique view path. As we discussed earlier, the user interface of the partial-rendering-enabled threaded discussion forum user control consists of a TreeView and a DetailsView control. The TreeView control displays the subject, added date, and user name of all the message nodes of the tree hierarchy. The TreeView and DetailsView controls create a master/detail form in which the user selects a message from the TreeView control to see its details in the DetailsView control. The DetailsView control also enables users to edit, delete, or reply to the selected message, or to start a new thread of discussion. The DetailsView control therefore does not display, edit, delete, or reply to all the message nodes of the tree. It only displays, edits, deletes, or replies to the message node that the user has selected from the TreeView control. This means that the DetailsView control must first locate the selected message node in the underlying tree representation. The only way to locate a node in a tree is to find out its hierarchical or location path. Let us see how the DetailsView control accesses the hierarchical path of the selected message. The TreeView control creates an instance of the TreeNode class for each message node it displays and sets its DataPath property to the hierarchical or location path of the message node. When the user selects a message from the TreeView control, the SelectedNode property of the control is set to the TreeNode object that represents the selected message node. Therefore the DetailsView control can easily use the DataPath property of the SelectedNode object of the TreeView control to access the hierarchical path of the selected message node, TreeView1.SelectedNode.DataPath. One of the responsibilities of the DetailsView control is to use the hierarchical path of the selected message node to locate the node in the underlying tree representation, extract its details, and display them to users. Thanks to the new ASP.NET 2.0 data source and data-bound model this is all done automatically. All you need to do is to set the XPath property of the XmlDataSource associated with the DetailsView control to the hierarchical path of the selected message node. You an do this easily in the callback for the SelectedNodeChanged event of the TreeView control: void SelectedNodeChanged(object sender, EventArgs e) { MySource2.XPath = TreeView1.SelectedNode.DataPath; if (dv.CurrentMode != DetailsViewMode.ReadOnly) dv.ChangeMode(DetailsViewMode.ReadOnly); }
Setting the XPath property of the XmlDataSource control associated with the DetailsView control (MySource2) to the hierarchical path of the selected message node is all it takes to have the DetailsView control extract the details of the selected message node from the tree and display them. Let us see what makes this possible. The DetailsView control internally registers a callback for the DataSourceChanged event of its associated XmlDataSource control, i.e. MySource2. The XmlDataSource control raises the event when one of the following conditions is met:
❑
One or more of its properties change value.
❑
The underlying data store changes because of a delete, update, or insert operation.
956
c20.indd 956
8/20/07 8:34:24 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls Therefore, setting the XPath property of the XmlDataSource control raises the DataSourceChanged event and calls the internal callback function by which the DetailsView control uses the XmlDataSource control to automatically extract the details of the selected message node from the underlying tree and displays them to users. The great thing about the DetailsView control is that it allows all operations (display, edit, delete, reply, and add a new thread) to be handled within the same server control, the DetailsView control. You switch from one operation to another by switching the mode of the DetailsView control. The DetailsView control can be in one of the three possible modes: DetailsViewMode.ReadOnly, DetailsViewMode.Edit, and DetailsViewMode.Insert. When the user selects a message from the TreeView control, the DetailsView control is switched to the DetailsViewMode.ReadOnly mode, in which the details of the selected message are displayed. When the user clicks the Edit button of the DetailsView control, the DetailsView control is switched to the DetailsViewMode.Edit mode, in which the user can edit the selected message. When the user clicks the Reply button of the DetailsView control, the DetailsView control is switched to the DetailsViewMode.Insert mode, in which the user can reply to the selected message. When the user clicks the New Thread button, the DetailsView control is switched to the DetailsViewMode.Insert mode, in which the user can start a new thread.
Displaying all Messages The TreeView control uses the following XmlDataSource control to extract all the message nodes from the tree:
The XPath property operates like the SelectCommand attribute of the SqlDataSource control — that is, it specifies which message nodes will be selected. In this case it is set to the value “/Messages/ Message” to extract all the message nodes. Accessing the underlying data store is one of the most time-consuming operations in data-driven Web applications. Page developers normally cache data query results in the Cache object to improve performance. The XmlDataSource control enables you to cache data without writing a single line of code. All you have to do is to set the EnableCaching, CacheDuration, and CacheExpirationPolicy properties of the XmlDataSource control. The possible values of CacheExpirationPolicy are Sliding and Absolute. Automatic caching is possible because the XmlDataSource control uses W3C DOM APIs to load the entire XML document into memory. The streaming load model, on the other hand, does not allow caching because only the current node is kept in memory. The downside of every caching is the problem of stale data. The problem occurs when the underlying data store changes but the application still displays out-of-date information. The XmlDataSource control, like any other ASP.NET component, internally uses the Insert method of the Cache object to cache the XML document if its caching feature is enabled. The Insert method takes an argument that specifies a cache key. This cache key is an arbitrary key under which some arbitrary information is
957
c20.indd 957
8/20/07 8:34:24 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls cached in the Cache object. The Insert method internally establishes a dependency between the cache key under which the XML document is cached and the cache key passed into the method. This means that if you invalidate the cache key passed into the Insert method as its argument, you’ll automatically invalidate the cache key under which the XML document is cached, because of the dependency between these two cache keys. The XmlDataSource control exposes a public property named CacheKeyDependency, which you must set to the cache key that you want the control to pass into the Insert method of the Cache object when it is caching the XML document. You will see later that the callbacks for the Delete, Update, and Edit operations in the DetailsView control call the Remove method of the Cache object to invalidate the data cached under the key specified in the CacheKeyDependency property, and consequently to invalidate the cached XML document. The next time the page is accessed, the XmlDataSource control will extract fresh data from the underlying XML document. This automatically resolves the problem of stale data. The application also registers the DataBound method as the callback for the TreeNodeDataBound event of the TreeView control, in which it specifies what information to display for each message: void DataBound(Object sender, TreeNodeEventArgs e) { if (((XmlNode)e.Node.DataItem).LocalName == “Message”) e.Node.Text = XPathBinder.Eval(e.Node.DataItem, “Subject”).ToString() + “, by “ + XPathBinder.Eval(e.Node.DataItem, “@UserName”).ToString() + “ “ + XPathBinder.Eval(e.Node.DataItem, “@AddedDate”).ToString(); }
The Eval method of the XPathBinder takes two arguments. The first argument is the object against which a given XPath expression is evaluated. The second argument is the XPath expression being evaluated. The first argument accepts only objects whose classes implement the IXPathNavigable interface. This is because the Eval method simply calls the CreateNavigator method of the object to access its XPathNavigator object. The Eval method then calls the Select method of the XPathNavigator object and passes the XPath expression as its argument. Let us take a look at the XPath expressions used as the second arguments of the Eval method calls Subject, @UserName, and @AddedDate. These expressions refer to the child element and the UserName and AddedDate attributes of the selected message node. As Figure 20-10 shows, the child element and UserName and AddedDate attributes are themselves nodes of the tree hierarchy. Therefore the XPath expressions are nothing but the location steps that take you from the selected message node to the Subject, UserName, and AddedDate nodes. The Select method of the XPathNavigator object uses these location steps to locate these nodes and return references to them.
Displaying the Details of a Message Since the DetailsView control is bound to an XmlDataSource control in which every data item implements the IXPathNavigable interface, it uses XPathBinder in its data-binding expressions. XPath is
958
c20.indd 958
8/20/07 8:34:25 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls the short version of XPathBinder.Eval(Container.DataItem, xpathexpression, format). The DetailsView control uses four XPath data-binding expressions:
1.
XPath(“Subject/text()”) returns the subject of the selected message node. The text() function returns the text within the opening and closing tags of the element in the XML document. As Figure 20-10 shows, the text itself is a node in the tree hierarchy. The XPath expression Subject/text() is therefore a location path that takes us from the selected message node to the text node.
2. 3.
XPath(“Body/text()”) returns the body of the selected message node.
4.
XPath(“@AddedDate”) returns the value of the AddedDate attribute of the selected element. As Figure 20-10 shows, the attribute itself is a node. XPath(“@UserName”) returns the value of the UserName attribute of the selected
element. The DetailsView control and its associated XmlDataSource control work together to automatically display the details of the message node that the user selects from the TreeView control. In other words, the select operation is done automatically. However, XmlDataSource does not provide automatic support for delete, update, and insert operations. The application must explicitly handle these operations.
Deleting a Message The ItemTemplate section of the DetailsView control contains the Delete button. The DetailsView control provides built-in support for deleting items. Page developers need only add a new Delete button to the ItemTemplate section and set its CommandName property to Delete. When the user clicks the Delete button, the DetailsView control checks the value of the CanDelete property of its associated view object. If it is true, the control calls the Delete method of the view object; otherwise it throws an exception. The CanDelete property value is true only when the view object implements the Delete method. However, the XmlDataSourceView class does not implement the Delete method. Therefore the application must not set the CommandName property of the Delete button to the value “Delete,” or an exception will be thrown when the button is clicked. The application sets the CommandName property of the Delete button to the value “SubmitDelete” instead, and registers the DetailsView_ItemCommand method as the callback for the ItemCommand event of the DetailsView control to handle the delete event. Later you will see that the DetailsView_ItemCommand method will also be used to handle the update and insert events. The method calls the Delete method to handle the delete event. As discussed before, the XmlDataSource control uses the W3C DOM APIs to load the entire messages.xml file into memory and creates an in-memory tree representation of the XML document. The great thing about the W3C DOM model is that it enables page developers to add, update, and delete nodes from the in-memory tree. The XmlDataSource control exposes a method named GetXmlDocument that returns a reference to the underlying XmlDocument object.
959
c20.indd 959
8/20/07 8:34:25 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls As you can see from the implementation of the Delete method shown in Listing 20-10, deleting a node from the tree hierarchy involves the following four steps:
1.
Find out the hierarchical path of the node to be deleted. Since the message node being deleted is the node that the user selected from the TreeView control, the value of the DataPath property of the SelectedNode of the TreeView control is the hierarchical path of the node being deleted.
2.
Call the SelectSingleNode method of the XmlDocument object and pass the hierarchical path of the node as its argument. The method uses the hierarchical path to locate the message node in the tree:
Call the RemoveChild method of the parent node to delete the node from the tree:
parent.RemoveChild(message);
The Delete method then calls the Save method. As you can see from Listing 20-10, the Save method takes care of the following issues:
❑
Removing the selected message node from the in-memory tree hierarchy does not automatically remove the message from the underlying data store — that is, the XML document. The Save method calls the Save method of the associated XmlDataSource control to propagate the changes to the XML document.
❑
Recall that the XmlDataSource control associated with the TreeView control caches the XML document in the Cache object. Since the Delete method changes the underlying data store, it must call the Remove method of the Cache object to invalidate the cached data, otherwise the TreeView control will show out-of-date data.
❑
The DataBind method of the TreeView control must be called to update the TreeView control display. Since the cached data has already been invalidated, the DataBind method will extract fresh data from the underlying XML document.
❑
The DetailsView control must be switched back to its ReadOnly mode.
Updating a Message The ItemTemplate section of the DetailsView control contains the Edit button. Since the CommandName property of the button is set to “Edit”, when the user clicks the button the DetailsView control automatically switches to DetailsViewMode.Edit mode, in which it renders the contents of its EditItemTemplate section, including the Update and Cancel buttons. When the Cancel button is clicked, the DetailsView control automatically switches back to the DetailsViewMode.ReadOnly mode, in which it renders the contents of its ItemTemplate section. Notice that the CommandName property of the Update button is not set to “Update” for the same reason
960
c20.indd 960
8/20/07 8:34:25 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls that the CommandName property of the Delete button was not set to “Delete”. The application sets the property to “SubmitUpdate” and uses the DetailsView_ItemCommand method to handle the event. The method calls the Update method to handle the Update event. As you can see from Listing 20-10, the Update method first extracts the new values for the subject and body of the selected message. Updating a node in the tree hierarchy involves the following steps:
1.
Find out the hierarchical path of the node to be updated. Since the message node being updated is the message that the user selected from the TreeView control, the value of the DataPath property of the SelectedNode of the TreeView control is the hierarchical path of the message node. However, you want to update the child nodes (the subject and body nodes) of the message node, not the message node itself. Recall that the hierarchical path of a node takes you from the root node of the tree, node by node, all the way down to the node itself. The hierarchical path consists of location steps, each of which takes you from your current node to the next. This means that you need to add another location step to the hierarchical path of the message node to go from the message node to its child nodes, the subject and body nodes. Therefore the hierarchical paths of the subject and body nodes are as follows:
Notice that the SelectSingleNode method returns the reference to the actual node in the tree. This enables you to directly update the properties of the subject and body nodes. At the end, the Update method calls the Save method, exactly as the Delete method did.
Replying to a Message The ItemTemplate property of the DetailsView control contains the Reply button. Since the CommandName property of the button is set to “New”, when the user clicks the button the DetailsView control automatically switches to the DetailsViewMode.Insert mode, in which the control renders the contents of its InsertItemTemplate section that also includes the Insert button. Notice that the CommandName property of the Insert button is not set to “Insert” for the same reason that the CommandName properties of the Delete and Update buttons were not set to “Delete” and “Update”. The application sets the property to “SubmitInsert” and uses the DetailsView_ItemCommand method to handle the event. The method calls the Insert method to
961
c20.indd 961
8/20/07 8:34:26 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls handle the Insert event. Listing 20-10 shows the code for the Insert method. Adding a new element node to the tree hierarchy involves the following six steps:
1. 2. 3. 4.
Call the CreateElement method of the XmlDocument object to create the new element node.
5.
Call the SelectSingleNode method of the XmlDocument object and pass the hierarchical path of the parent node as its argument to access the parent node in the tree.
6.
Call the AppendChild method of the parent node to add the new element node to the tree as its child node.
Set the properties of the new element node. Call the SetAttribute method of the new element node to set its attributes. Find out the hierarchical path of the element node that will act as the parent node of the new element node.
The Insert method creates three element nodes and adds them to the tree hierarchy. The first element node represents the reply message itself. The second and third element nodes represent the subject and body of the reply message, respectively. The Insert method follows the preceding six steps for each element node that it creates and adds to the tree hierarchy. For instance, consider the six steps for the creation and addition of the element node that represents the reply message itself:
Since the message node being added is the reply to the message node that the user selected from the TreeView control, the selected message node will be the parent of the new message node. Therefore the value of the DataPath property of the SelectedNode of the TreeView control is the hierarchical path of the parent node of the new element node.
5.
Access the parent element node in the tree hierarchy:
Add the new element node to the tree hierarchy as the child node of the parent node:
parent.AppendChild(message);
At the end, the Insert method calls the Save method to commit all the changes to the disk and update the TreeView and DetailsView controls.
962
c20.indd 962
8/20/07 8:34:26 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls
Starting a New Thread The NewThreadClick method is registered as the callback for the Click event of the NewThread button, as shown in Listing 20-10. As you can see from this code listing, the method calls the ChangeMode method of the DetailsView control to change its mode to DetailsViewMode.Insert, in which the control renders the contents of its InsertItemTemplate property. The method also stores “NewThread” in ViewState under the key “NewThread”. Since replying to a message and creating a new thread both switch the DetailsView control to its Insert mode, the same discussions presented in the previous section apply here. The only difference is that the Insert method appends the newly created message node as the child node of the document element because it starts a new thread. The Insert method uses ViewState[“NewThread“] as the signal to find out whether the user is starting a new thread or replying to an existing message. Note that the partial-rendering-enabled threaded discussion forum user control registers the NewThread button as the trigger for the automatic update of the UpdatePanel server control that contains the DetailsView server control. This ensures that when the end user clicks the NewThread button to add a new thread of discussions, this UpdatePanel server control and consequently its child DetailsView server control are automatically updated.
The following code listing presents a page that uses the partial-rendering-enabled threaded discussion forum user control: Untitled Page
963
c20.indd 963
8/20/07 8:34:26 PM
Chapter 20: Using UpdatePanel in User Controls and Custom Controls This page assumes that you’ve stored Listing 20-10 in a file named DiscussionForum.ascx and Listing 20-11 in a file named messages.xml. Note that Listing 20-10 uses the value of the IsAuthenticated property of the Identity property of the User object to determine whether to display the following LinkButton server controls: Reply Edit Delete
This means that you need to use the ASP.NET Web Site Administration Tool to configure your application to use the ASP.NET 2.0 security features. You can launch this tool from the Website menu of Visual Studio 2005.
Summar y This chapter used numerous examples to show you how to use ASP.NET AJAX partial page rendering in your own Web applications. You also learned how to develop custom partial-page-rendering-enabled server controls and user controls. The next chapter will delve deeper into the ASP.NET AJAX partialpage-rendering infrastructure, and you’ll learn a great deal about the constituent components of this infrastructure.
964
c20.indd 964
8/20/07 8:34:27 PM
Page Life Cycle and Asynchronous Par tial Page Rendering The main goal of this and the next few chapters is to help you gain a solid understanding of the ASP.NET AJAX asynchronous page postback or partial-page-rendering-request-processing infrastructure. This infrastructure consists of two groups of components:
❑
Server-side components: This group includes the ScriptManager, UpdatePanel, PageRequestManager, and ScriptRegistrationManager classes.
❑
Client-side components: This group includes the PageRequestManager, WebRequest, WebRequestExecutor, WebRequestManager, XMLHttpExecutor, and Application classes, among others.
Note that both the server and client sides contain a component named PageRequestManager. Even though they have the same name, they are two different components defined in two different frameworks. One is defined in the ASP.NET AJAX server-side framework while the other is defined in the ASP.NET AJAX client-side framework. For ease of reference, I’ll refer to the one defined in the server-side framework as the server-side PageRequestManager and the other as the client-side PageRequestManager. These components are at the heart of ASP.NET AJAX partial page rendering, which, as you’ll see later, is the result of the communications between the clientside and server-side PageRequestManager components. As their names suggest, they’re the ones that are responsible for managing and processing asynchronous partial-page-rendering requests. Here is how these two components work together. The current client-side PageRequestManager instance makes an asynchronous page postback request to the server. The current server-side PageRequestManager instance picks up and processes the request and sends the reponse text back to the client. The current client-side PageRequestManager instance then picks up and processes the response text and updates the regions of the page enclosed within the specified UpdatePanel server controls.
c21.indd 965
8/20/07 8:37:01 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Your server-side code cannot directly access the current server-side PageRequestManager instance. Your code gets to interact with the current server-side PageRequestManager instance via the current ScriptManager server control, as you’ll see later in this chapter. Your client-side code, on the other hand, can directly access the current client-side PageRequestManager instance. This will all be cleared up later in this and the following chapters.
Processing a Request When an HTTP request — be it synchronous, asynchronous, partial-page-update, or normal postback — for an ASP.NET Web page arrives, the ASP.NET framework parses the requested page into a dynamically generated class that inherits the ASP.NET Page class. By default, the name of this class consists of two parts separated by an underscore character (_). The first part is the name of the file that contains the page and the second part is the string aspx. For example, if the requested page is in a file named default .aspx, ASP.NET parses the content of this file into a dynamically generated class named default_aspx that inherits the Page class. All ASP.NET dynamically generated classes, such as default_aspx, belong to a standard namespace named ASP. As a matter of fact, Visual Studio provides IntelliSense support for this namespace and its constituent dynamically generated classes. To see this, open the file that contains the code-behind file for an ASP.NET Web page (for example, the default.aspx.cs) in Visual Studio and type the first letter of the ASP namespace, that is, the letter A. You should see the popup that displays all the namespaces whose names begin with that letter, including the ASP namespace. Now, if you select ASP from this popup and type the dot character (.) you should see the name of the dynamically generated class (for example, default_aspx) associated with the current Web page. After parsing the requested page into a dynamically generated class that inherits from the ASP.NET Page class, the ASP.NET framework temporarily stores the code for this class in a source file a couple of directories below the directory named after the current Web application, in a standard directory named Temporary ASP.NET Files, under the directory on your machine where the .NET framework is installed: %windir%\Microsoft.NET\Framework\v2.0.50727\Temporary ASP.NET Files\ ajaxenabledwebsite11\de910baf\54181126
The name of this source file follows this format: App_Web_FileName.aspx.RandomHash.0.cs, where the FileName is the name of the .aspx file and the RandomHash is a randomly generated hash value that ensures the uniqueness of the source-file name. Figure 21-1 shows an example that represents this file structure for an ASP.NET application named AjaxEnabledWebSite11. This Web application is a very simple one that consists of a single page named default.aspx, as shown in the following code listing. The file named App_Web_default.aspx.cdcab7d2.a5hjdn-i.0 shown in Figure 21-1 contains the source code for the ASP.default_aspx class that represents the default.aspx file.
966
c21.indd 966
8/20/07 8:37:02 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering void SubmitCallback(object sender, EventArgs e) { Info.Text = TextBox1.Text; } Enter text:
If you’re curious to see what this dynamically generated class looks like, go to the previously mentioned directory and open the file that contains the source code for this class in your favorite editor. For example, the file associated with the preceding page contains the following source code (note that I’ve cleaned it up for presentation purposes): As I said earlier, the ASP.NET compilation system temporarily stores the source code in the previously mentioned source file. Therefore, if you want the file to remain in the directory so you can open it in your favorite editor, you must run the page in debug mode to instruct ASP.NET not to delete the file. using System; using System.Web; using System.Web.UI; using System.Web.UI.WebControls; using System.Web.UI.HtmlControls; namespace ASP { public class default_aspx : Page { protected ScriptManager ScriptManager1; protected TextBox TextBox1; protected Button Button1; protected Label Info; protected UpdatePanel UpdatePanel1; protected HtmlForm form1; . . .
Figure 21-1 The ASP.NET framework then dynamically compiles the content of the source file that contains the dynamically generated class into an assembly, stores the assembly in the same directory as the source file, and deletes the source file afterward. If you run the application in debug mode, the ASP.NET framework will not delete the source file after the compilation. As I mentioned earlier, this will enable you to open the file in your favorite editor and study its content. The name of this assembly
968
c21.indd 968
8/20/07 8:37:02 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering follows the naming convention App_Web_FileName.aspx.RandomHash.0.dll, where FileName is the name of the .aspx file and RandomHash is a randomly generated hash value that ensures the uniqueness of the DLL file name. For example, in the case of Figure 21-1, the DLL’s name is App_Web_default.aspx.cdcab7d2.a5hjdn-i.dll. The ASP.NET Framework then loads this assembly — keep in mind that it contains the dynamically generated class — into the application domain where the current application is running, dynamically instantiates an instance of this compiled class, and calls the ProcessRequest method on this instance. For ease of reference, I’ll refer to this instance as the Page object or the Page, because this is an instance of a class that inherits the ASP.NET Page class. You can think of this instance (the Page object) as the ASP.NET representation of the requested Web page. It inherits the ProcessRequest method from the ASP.NET Page class. As the name suggests, this method processes the current request. The call into this method causes the Page object to start its life cycle, which consists of different phases. The best way to understand the ASP.NET AJAX asynchronous page postback or partial-rendering-request-processing infrastructure and its constituent components is to follow the Page object as it goes through its life cycle phases.
The Page Life Cycle Listing 21-1 presents the internal implementation of the ProcessRequest method of the ASP.NET Page class. As you can see, this method consists of a bunch of method calls, each of which defines a particular phase of the Page object’s life cycle, as discussed in the following sections. Figure 21-2 presents the flowchart associated with the ProcessRequest method. Keep this flowchart in mind as you’re reading through this chapter.
Listing 21-1: The ProcessRequest Method of the Page Class public void ProcessRequest(HttpContext context) { this._context = context; this.RetrievePostedData(); if (this.MaintainScrollPositionOnPostBack) this.LoadScrollPosition(); this.PerformPreInit(); this.InitRecursive(null); this.OnInitComplete(EventArgs.Empty); if (this.IsPostBack) { this.LoadAllState(); this.ProcessPostData(this._requestValueCollection, true); } this.OnPreLoad(EventArgs.Empty); this.LoadRecursive();
(continued)
969
c21.indd 969
8/20/07 8:37:03 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Listing 21-1 (continued) if (this.IsPostBack) { this.ProcessPostData(this._leftoverPostData, false); this.RaiseChangedEvents(); this.RaisePostBackEvent(this._requestValueCollection); } this.OnLoadComplete(EventArgs.Empty); this.PreRenderRecursive(); this.PerformPreRenderComplete(); this.SaveAllState(); this.OnSaveStateComplete(EventArgs.Empty); this.RenderControl(this.CreateHtmlTextWriter(this.Response.Output)); }
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Keep in mind that our goal in this chapter is to follow the Page object through its life cycle phases in order to understand the ASP.NET AJAX asynchronous page postback or partial-page-rendering-requestprocessing infrastructure and its constituent server-side and client-side components. As discussed in the previous chapter, an ASP.NET Web page enabled for partial page rendering contains a single instance of the ScriptManager server control and one or more instances of the UpdatePanel server controls. I’ll begin with the first request that the requesting browser makes to the server to visit an ASP.NET Web page enabled for partial page rendering. This first request is an HTTP GET request that downloads the Web page for the first time. Obviously this first request is not a postback or asynchronous postback request. I’ll first follow the Page object through its life cycle phases to process this very first request, even though it is not an asynchronous postback request because the first request instantiates and initializes many of the components that come into play in the subsequent asynchronous page postback requests to the same Web page.
The First Visit to a Par tial-Page-RenderingEnabled Web Page As just discussed, to visit for the first time an ASP.NET Web page enabled for partial page rendering, the browser must send an HTTP GET request to the server. In this section I’ll follow the Page object through its life cycle phases to process this HTTP GET request. As Figure 21-2 shows, the current Page skips some of its life cycle phases when it is processing a non-postback request such as the first HTTP GET request.
InitRecursive I’ll begin when the page enters its InitRecursive (or Init) life cycle phase, where the ProcessRequest method invokes the InitRecursive method on the current Page (see Listing 21-1 and Figure 21-2). All server controls, including the Page, ScriptManager, and UpdatePanel, inherit the InitRecursive method from the Control base class. The InitRecursive method of a server control such as Page and UpdatePanel recursively invokes the InitRecursive methods of its child server controls. The InitRecursive method of a server control takes these actions:
❑
Sets the NamingContainer, ID (if it hasn’t already been set), and Page properties of its child server controls. This step does not apply to the ScriptManager because it does not contain any child server controls. However, it does apply to the UpdatePanel server controls on the current page because they do contain other server controls.
❑
Calls the ApplySkin to apply its associated skins if theming is enabled. This step does not apply to the ScriptManager because it does not render visual HTML, but it does apply to the UpdatePanel server controls because they may contain child server controls that use skins.
❑
Calls the OnInit method to raise its Init event and consequently invoke all the event handlers registered for this event.
971
c21.indd 971
8/20/07 8:37:04 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering ❑
Calls the TrackViewState method to start tracking its view state. After the call into the TrackViewState method goes through, any changes made to the state of a server control, such as to its property values, will be marked as dirty and stored in the view state at the end of the current request and consequently sent to the client as part of the current page. As you can see, the bigger the view state the bigger the current page.
The Init life cycle phase of the Page object is very complex in that it involves a lot of method calls on the Page, ScriptManager, PageRequestManager, and UpdatePanel classes. Because of this, it’s really easy to lose track of these method calls and their surrounding discussions. To make things a little easier on you, I’ll present these method calls in a diagram. At the end of each section I’ll update this diagram with the method calls discussed in the section. Therefore, by the time I’m done with our discussions of the Init life cycle phase of the Page object, you’ll have a single diagram that contains all the method calls in the order in which they’re made. I’ll do the same for other complex life cycle phases of the Page object. This way, for each complex life cycle phase you’ll have one diagram that contains all the method calls made in that phase in the order in which they’re made. Keep in mind that the vertical line in each diagram represents the timeline. The method calls positioned higher on these vertical lines occur earlier. Figure 21-3 presents the diagram that contains the method calls I’ve discussed so far. As you can see, when the Page enters its Init phase, it first invokes its own InitRecursive method. Since the Page calls this method on itself, the diagram uses an arrow that starts and ends with the vertical timeline associated with the page. The InitRecursive method then calls the InitRecusive methods of the ScriptManager and UpdatePanel before calling its own ApplySkin, OnInit, and TrackViewState methods. The InitRecursive methods of the ScriptManager and UpdatePanel, like the InitRecusive method of any other server control, call their own ApplySkin, OnInit, and TrackViewState methods. Now the question is: what happens when the OnInit methods of the ScriptManager and UpdatePanel server controls are invoked? In other words, what sequence of method calls do the calls into the OnInit methods of the ScriptManager and UpdatePanel server controls trigger? The dashed lines in Figure 21-3 are the placeholders for these missing method calls, which will be discussed in the following sections.
The OnInit Method of ScriptManager Listing 21-2 presents the ScriptManager class’s internal implementation of the OnInit method, which it inherits from the Control base class. This implementation takes these steps. First, it calls the GetCurrent static method on the ScriptManager class to determine whether the current page already contains an instance of the ScriptManager server control. If so, it raises an exception because every page can contain only one instance of the ScriptManager server control. Next, the OnInit method adds the current instance of the ScriptManager server control to the Items collection of the current Page object. The next calls into the GetCurrent static method will return the instance stored in the Items collection of the current page. This ensures that the same instance will always be used for the entire lifespan of the current request. this.Page.Items[typeof(ScriptManager)] = this;
972
c21.indd 972
8/20/07 8:37:04 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering InitRecursive Page
Figure 21-3 This behavior of the Items collection has significant consequences when you’re enabling partial page rendering for a user control or a content page. Since a user control or a content page merges into its parent page and consequently forms a single page with its parent, you have to make sure that you do not declare separate instances of the ScriptManager server control in the parent page and the child page — be they user controls or content pages. You have two choices in these situations. You can declare the ScriptManager server control either in the parent or the child page (that is, user control or content page). Each option has its own pluses and minuses. If you declare the ScriptManager server control in the parent page, this automatically enables partial page rendering for all child pages — that is, for all user controls and content pages — which may not be the effect you’re looking for. Doing this also means that if you need to access the current ScriptManager server control from within your user control or content page, you must call the GetCurrent static method on the ScriptManager class to return a reference to the ScriptManager server control declared in the parent page. If you declare the ScriptManager in the child page you can directly access the current ScriptManager server control from the child page without using the GetCurrent static method. However, this also means that partial page rendering is only enabled for those user controls or content pages that directly contain the ScriptManager server control, which may not be the effect you’re looking for. Another side effect of this approach is that you cannot directly access the current
973
c21.indd 973
8/20/07 8:37:04 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering ScriptManager server control from your parent page because the parent page does not directly contain this server control. Instead you must use the GetCurrent static method to return a reference to this server control. Using this approach also means that if your parent page contains a partial-pagerendering-related functionality you must add code to check whether the child control does indeed contain an instance of the ScriptManager server control. If not, you must disable this functionality for this child control. OnInit then registers the OnPagePreRenderComplete method as an event handler for the PreRenderComplete event of the current Page object: this.Page.PreRenderComplete += new EventHandler(this.OnPagePreRenderComplete);
Next, OnInit checks whether the page has been posted back to the server. If so, it calls the IsAsyncPostBackRequest static method on the current server-side PageRequestManager instance, passing in the request header collection to determine whether the page has been posted back asynchronously. (You’ll learn more about the server-side PageRequestManager class later.) As you’ll see, the ScriptManager server control delegates some of its responsibilities to this class, especially those responsibilities that handle asynchronous page postback or partial-rendering requests. The IsAsyncPostBackRequest static method will be thoroughly discussed later. For now, suffice it to say that this method uses the request headers to determine whether the page is posted back asynchronously — that is, whether the current request is an asynchronous partial-page-rendering request. Note that OnInit assigns the return value of this method to the _isInAsyncPostback Boolean field: if (this.Page.IsPostBack) this._isInAsyncPostBack = PageRequestManager.IsAsyncPostBackRequest(this.Page.Request.Headers);
The ScriptManager exposes a read-only Boolean property named IsInAsyncPostBack that returns the value of the _isInAsyncPostBack field. Call this property on the current ScriptManager server control if you need to know whether the current request is an asynchronous page postback or partial-page-rendering request. Since the current Page object is processing the first HTTP GET request made to the server to visit the Web page for the first time, the IsAsyncPostBackRequest method of the current server-side PageRequestMananager instance is not invoked for this request. Next, OnInit calls the OnInit method on the current server-side PageRequestManager instance to initialize this instance. Unlike the ScriptManager, the PageRequestManager class is not a server control, which means that its OnInit method will not be automatically invoked by the containing page. That is why the OnInit method of the ScriptManager server control explicitly calls the OnInit method of the current server-side PageRequestManager instance: this.PageRequestManager.OnInit();
This is an example of a situation in which a server control such as ScriptManager has to work hand in hand with a non–server control object such as PageRequestManager throughout its life cycle. Thanks to the Page object, the server control’s life cycle methods, such as OnInit, are automatically called as the control goes through its life cycle phases. The same does not apply to the non–server control objects, such as PageRequestManager. In these cases, the server control’s life cycle methods, such as OnInit, must call the corresponding methods of the non–server control object to ensure that the
974
c21.indd 974
8/20/07 8:37:05 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering non–server control object gets to run its appropriate life cycle methods as the server control is moving through its own life cycle phases. This pattern allows a server control, such as ScriptManager, to delegate some of its responsibilities to a non–server control object, such as PageRequestManager.
Listing 21-2: The OnInit Method of the ScriptManager Class protected override void OnInit(EventArgs e) { base.OnInit(e); if (ScriptManager.GetCurrent(this.Page) != null) throw new InvalidOperationException(“OnlyOneScriptManager”); this.Page.Items[typeof(ScriptManager)] = this; this.Page.PreRenderComplete += new EventHandler(this.OnPagePreRenderComplete); if (this.Page.IsPostBack) this._isInAsyncPostBack = PageRequestManager.IsAsyncPostBackRequest(this.Page.Request.Headers); this.PageRequestManager.OnInit(); }
The OnInit Method of PageRequestManager Listing 21-3 presents the internal implementation of the OnInit method of the server-side PageRequestManager.
Listing 21-3: The OnInit Method of the PageRequestManager Class internal void OnInit() { if (this._owner.EnablePartialRendering && !this._owner._supportsPartialRenderingSetByUser) { IHttpBrowserCapabilities capabilities1 = this._owner.Page.Request.Browser; this._owner.SupportsPartialRendering = (capabilities1.W3CDomVersion >= new Version(1, 0)) && (capabilities1.EcmaScriptVersion >= new Version(1, 0)) && capabilities1.SupportsCallback; } if (this._owner.IsInAsyncPostBack) this._owner.Page.Error += new EventHandler(this.OnPageError); }
Note that the current server-side PageRequestManager instance exposes a field named _owner that references the current ScriptManager server control. Also note that the ScriptManager server control exposes the following two Boolean properties:
❑
EnablePartialRendering: Gets or sets a Boolean value that specifies whether the partial-
rendering feature is enabled. Set this property to false if you need to turn off the partial page rendering for a page. Keep in mind that if the current ScriptManager server control is declared on a parent page such as a master page, setting this property to false will disable partial page rendering for all its child pages — that is, for all its child user controls and content pages, which may not be the effect you’re looking for. In this situation, you must take the following steps to explicitly turn on partial page rendering for a particular child page. First, call the GetCurrent static method on
975
c21.indd 975
8/20/07 8:37:05 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering the ScriptManager class to return a reference to the ScriptManager server control declared on the parent page. Then set the EnablePartialRendering property of this ScriptManager server control to true. Keep in mind that this will enable partial rendering only for this specific child page, which means that you have to take these same two steps for every child page for which you need to enable partial page rendering. This may seem to suggest that you should always declare the ScriptManager server control on the child pages, which is not the case; it all depends on the specifics of your application. The downside of declaring the ScriptManager server control on child pages is that you must now disable partial page rendering for every single child page if you need to disable partial page rendering for all child pages of a given parent page.
❑
SupportsPartialRendering: Gets or sets a Boolean value that specifies whether
the browser supports partial rendering. If you explicitly set the value of this property, the ScriptManager sets an internal flag named _supportPartialRenderingSetByUser to signal to the OnInit method of the current server-side PageRequestManager instance that it does not
need to determine whether the browser indeed supports partial rendering because the user (you) has explicitly set the value of this property. The same argument presented before regarding the effects of setting the value of the EnablePartialRendering property in parent/child page scenarios also applies to the SupportsPartialRendering property.
Now let’s walk through Listing 21-3. As you can see, if partial rendering is enabled but the value of the SupportsPartialRendering property of the ScriptManager object has not been explicitly set, the OnInit method of the PageRequestManager object takes the following steps to set the value of the SupportsPartialRendering property. First, it accesses the HttpBrowserCapabilities object that
contains the complete information about the requesting browser’s capabilities: HttpBrowserCapabilities capabilities1 = this._owner.Page.Request.Browser;
The ASP.NET framework uses the browser files to determine the capabilities of the requesting browser and caches this information in an instance of the HttpBrowserCapabilities class, which is then assigned to the Browser property of the ASP.NET Request object. The browser files are files with extension .browser, which are located in the standard directory on your machine. Each browser file normally describes the capabilities of a particular type of browser. For example, ie.browser describes capabilities of the IE browser. As you can see, the information stored in the Browser property of the ASP.NET Request object comes from an offline database on your machine. The ASP.NET framework enables you to extend the existing browser files by introducing one of your own: %WinDir%\Microsoft.NET\Framework\v2.0.50727\CONFIG\Browsers
Next, OnInit checks whether the requesting browser supports version 1.0 of W3C DOM and EcmaScript and the client callbacks: this._owner.SupportsPartialRendering = (capabilities1.W3CDomVersion >= new Version(1, 0)) && (capabilities1.EcmaScriptVersion >= new Version(1, 0)) && capabilities1.SupportsCallback;
As I mentioned earlier, you can explicitly set the value of the SupportsPartialRendering property to instruct the current server-side PageRequestManager instance to bypass this check. This is a
976
c21.indd 976
8/20/07 8:37:05 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering great option when you know for a fact that the browsers that your clients use to access your application support (or do not support) partial page rendering. If the current request is an asynchronous page postback or partial rendering request, the OnInit method of the current server-side PageRequestManager instance registers its OnPageError method as an event handler for the Error event of the current Page object. This does not apply to the first request to the page because the first request is not an asynchronous page postback. if (this._owner.IsInAsyncPostBack) this._owner.Page.Error += new EventHandler(this.OnPageError);
Recall that the second dashed line from the left in Figure 21-3 represents the method calls triggered by the call into the OnInit method of the current ScriptManager server control. As you saw in this section, this call triggers a call into the OnInit method of the current server-side PageRequestManager instance. Figure 21-4 extends Figure 21-3 to add this method call. Note that Figure 21-4 still contains the first dashed line, which represents the method calls triggered by the call into the OnInit method of the UpdatePanel server control. I’ll discuss these methods in the following section. At this point, we’ll digress from our main discussions to cover two related topics in the following two subsections. InitRecursive Page
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Handling the Error Event As I mentioned earlier, errors that occur during the first request to a Web page enabled for partial page rendering are handled through normal ASP.NET error-handling practices. (Complete coverage of these practices is beyond the scope of this book.) For example, one typical practice is to define a page-level event handler such as the following: protected void Page_Error (object sender, EventArgs e) { Exception error = Server.GetLastError(); if (error is ArgumentException) Server.Transfer(“ArgumentException.aspx”); else if (error is ArgumentOutOfRangeException) Server.Transfer(“ArgumentOutOfRangeException.aspx”); //. . . Server.ClearError(); }
Such an event handler begins by invoking the GetLastError static method on the ASP.NET Server object to return a reference to the last unhandled Exception object: Exception error = Server.GetLastError();
Next, it determines the type of the Exception object and redirects the request to the Web page that displays more information about the specified type of error. Note that such redirects are normally done on the server side and does not involve a round trip to the client. Finally, the event handler invokes the ClearError static method on the Server object to remove the Exception object. Instead of writing an event handler named Page_Error, you could register an event handler for the Error event of the current Page object. However, as you can see from Listing 21-3, such registration must be done in the Init life cycle phase of the current Page to ensure that your event handler does not miss any errors. Here is an example: void MyErrorHandler(object sender, EventArgs e) { Exception error = Server.GetLastError(); if (error is ArgumentException) Server.Transfer(“ArgumentException.aspx”); else if (error is ArgumentOutOfRangeException) Server.Transfer(“ArgumentOutOfRangeException.aspx”); //. . . Server.ClearError(); } protected override void OnInit(EventArgs e) { base.OnInit(e); this.Error += new EventHandler(MyErrorHandler); }
978
c21.indd 978
8/20/07 8:37:06 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Untitled Page . . .
As you can see from Listing 21-3, the OnInit method of the current server-side PageRequestManager instance registers a method named OnPageError as an event handler for the Error event of the current Page when an asynchronous page postback request is made to a Web page enabled for partial page rendering. I’ll discuss the OnPageError method later because the first request to a partial-page-renderingenabled Web page is not an asynchronous page postback.
Handling the Init Event As you saw in Listing 21-2, the current ScriptManager server control invokes the OnInit method of its base class to raise the Init event and consequently invoke the event handlers registered for this event. If you need to run some custom code when the current ScriptManger server control raises its Init event, you have two options. If your custom code is something that you think a lot of your clients might be interested in, and is not specific to a particular application, you can write a custom server control that derives from the ScriptManager server control and overrides its OnInit method to include this custom code. Here is an example: public class MyScriptManager : ScriptManager { protected override void OnInit(EventArgs e) { base.OnInit(e); // Your custom code should go here } }
It’s very important that your custom server control’s implementation of the OnInit method invoke the OnInit method of its base class — that is, the ScriptManager server control. Otherwise none of the following code will run and consequently the ASP.NET AJAX partial rendering will not work: this.Page.Items[typeof(ScriptManager)] = this; this.Page.PreRenderComplete += new EventHandler(this.OnPagePreRenderComplete); if (this.Page.IsPostBack) this._isInAsyncPostBack = PageRequestManager.IsAsyncPostBackRequest(this.Page.Request.Headers); this.PageRequestManager.OnInit();
979
c21.indd 979
8/20/07 8:37:06 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering If your custom code is specific to a particular application, you need to wrap the code in a method and register the method as the event handler for the Init method of the current ScriptManager server control instead of writing a custom server control. Here is an example: void MethodContainingYourCustomCode(object sender, EventArgs e) { // Your custom code should go here } Untitled Page . . .
The OnInit Method of UpdatePanel Keep in mind that we’re following the Page object as it goes through its life cycle phases to process the first request made to a Web page enabled for partial page rendering. As you follow the Page object, keep in mind where you are at every moment of the journey. Currently we’re at the Init life cycle phase where the OnInit methods of the ScriptManager and UpdatePanel server controls are invoked. (I covered the OnInit method of the ScriptManager server control in the previous section.) In this section I’ll discuss the OnInit method of the UpdatePanel server control. Listing 21-4 presents the internal implementation of this method.
Listing 21-4: The OnInit Method of the UpdatePanel Control protected override void OnInit(EventArgs e) { base.OnInit(e); this.RegisterPanel(); this.CreateContents(base.DesignMode); }
As you can see, the OnInit method calls the RegisterPanel and CreateContents methods of the UpdatePanel server control. I’ll discuss these methods in the following sections. Recall that the dashed line in Figure 21-4 represents the method calls triggered by the call into the OnInit method of the UpdatePanel server control. As you saw in this section, these triggered method calls are the calls into the RegisterPanel and CreateContents methods of the UpdatePanel server
980
c21.indd 980
8/20/07 8:37:07 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering control. Figure 21-5 extends Figure 21-4 to add these two method calls. Note that Figure 21-5 now contains two dashed lines, which represent the method calls triggered by the calls into the RegisterPanel and CreateContents methods. I’ll discuss these two methods in the following sections. I’ll wrap up the this section with the following note on handling the Init event of UpdatePanel server controls. InitRecursive Page
Figure 21-5 As you saw in Listing 21-4, the UpdatePanel server control invokes the OnInit method of its base class to raise the Init event and consequently invoke the event handlers registered for this event. If you need to run some custom code when a specific UpdatePanel server control on the current page raises its Init event, you have two options. If your custom code is something that you think a lot of your clients might be interested in and is not specific to a particular application, you can write a custom server control that
981
c21.indd 981
8/20/07 8:37:07 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering derives from the UpdatePanel server control and overrides its OnInit method to include this custom code. Here is an example: public class MyUpdatePanel : UpdatePanel { protected override void OnInit(EventArgs e) { base.OnInit(e); // Your custom code should go here } }
It’s very important that your custom server control’s implementation of the OnInit method invoke the OnInit method of its base class — that is, the UpdatePanel server control. Otherwise none of the following code will run and consequently the ASP.NET AJAX partial rendering will not work: base.OnInit(e); this.RegisterPanel(); this.CreateContents(base.DesignMode);
If your custom code is specific to a particular application, you need to wrap the code in a method and register the method as the event handler for the Init method of the desired UpdatePanel server control instead of writing a custom server control. Here is an example: void MethodContainingYourCustomCode(object sender, EventArgs e) { // Your custom code should go here } Untitled Page . . . . . . . . .
The RegisterPanel Method of the UpdatePanel Listing 21-5 contains the code for the RegisterPanel method, which calls the RegisterUpdatePanel method on the current ScriptManager server control to register the UpdatePanel control with the current ScriptManager control. Note that the RegisterPanel method first determines whether the UpdatePanel control is contained in another UpdatePanel control. If so, it calls the RegisterPanel
982
c21.indd 982
8/20/07 8:37:07 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering method of the container UpdatePanel control before calling the RegisterUpdatePanel method to register the current UpdatePanel. This has two consequences:
❑
The container UpdatePanel control of an UpdatePanel control is registered before the UpdatePanel control itself. You’ll see shortly what this registration entails.
❑
When the RegisterPanel method of an UpdatePanel control returns, you can rest assured that its container UpdatePanel control, the container UpdatePanel control of its container UpdatePanel control, the container UpdatePanel control of the container UpdatePanel control of its container UpdatePanel control, and so on are all registered with the current ScriptManager server control.
Note that the RegisterPanel method finally sets the _panelRegistered Boolean field to true to mark the completion of the registration process: this._panelRegistered = true;
Listing 21-5: The RegisterPanel Method private void RegisterPanel() { if (!this._panelRegistered) { for (Control control1 = this.Parent; control1 != null; control1 = control1.Parent) { UpdatePanel panel1 = control1 as UpdatePanel; if (panel1 != null) { panel1.RegisterPanel(); break; } } this.ScriptManager.RegisterUpdatePanel(this); this._panelRegistered = true; } }
The RegisterUpdatePanel Method of the ScriptManager Next, I’ll show you the implementation of the RegisterUpdatePanel method of the ScriptManager class. As you can see from Listing 21-6, this method delegates the responsibility of registering the specified UpdatePanel control to the RegisterUpdatePanel method of the current server-side PageRequestManager instance.
Listing 21-6: The RegisterUpdatePanel Method of ScriptManager void IScriptManagerInternal.RegisterUpdatePanel(UpdatePanel updatePanel) { this.PageRequestManager.RegisterUpdatePanel(updatePanel); }
983
c21.indd 983
8/20/07 8:37:08 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering The RegisterUpdatePanel Method of the PageRequestManager The current server-side PageRequestManager instance maintains all UpdatePanel server controls on the current page in an internal collection named _allUpdatePanels. As Listing 21-7 shows, the RegisterUpdatePanel method of the PageRequestManager simply adds the specified UpdatePanel control to this collection.
Listing 21-7: The RegisterUpdatePanel Method of the PageRequestManager internal void RegisterUpdatePanel(UpdatePanel updatePanel) { if (this._allUpdatePanels == null) this._allUpdatePanels = new List(); this._allUpdatePanels.Add(updatePanel); }
Now let’s update Figure 21-5 with the latest method calls. Recall that the top dashed line in Figure 21-5 represents the method calls triggered by the call into the RegisterPanel method of the UpdatePanel server control. As we discussed earlier, the RegisterPanel method triggers the call into the RegisterUpdatePanel method of the current ScriptManager server control, which in turn triggers the call into the RegisterUpdatePanel method of the current server-side PageRequestManager instance, which in turn triggers the call into the Add method of the _allUpdatePanels collection to add the UpdatePanel server control to this collection. Figure 21-6 extends Figure 21-5 to add the latest triggered method calls. Note that Figure 21-6 inherits the bottom dashed line from Figure 21-5, and remember that this dashed line represents the method calls triggered by the call into the CreateContents method of the UpdatePanel server control. These method calls will also be discussed in the following section.
The CreateContents Method of the UpdatePanel Recall from Listing 21-4 that the OnInit method of the UpdatePanel calls the CreateContents method, and Listing 21-8 presents its internal implementation. This method takes a Boolean parameter that specifies whether the contents of the UpdatePanel must be recreated from scratch. If so, the method first clears the Controls collection of the content template container server control: this.ContentTemplateContainer.Controls.Clear();
As Listing 21-8 shows, the CreateControl method first checks whether it is asked to recreate the content of the UpdatePanel from scratch. If so, it takes the following steps. First, it clears the Controls collection of the template container server control. This collection contains the server controls that represent the markup text enclosed within the opening and closing tags of the child element that represents the ContentTemplate property on the .aspx page. this.ContentTemplateContainer.Controls.Clear();
As I mentioned in the previous chapter, you can access the ContentTemplateContainer property of an UpdatePanel server control from within your C# or VB.NET code and imperatively add server controls to the Controls collection of the content template container server control from right within your code.
984
c21.indd 984
8/20/07 8:37:08 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering InitRecursive Page
Figure 21-6 Next, the CreateContents method calls the CreateContentTemplateContainer method to create the template container server control that will act as the container for the server controls that represent the markup text enclosed within the opening and closing tags of the child element: this._contentTemplateContainer = this.CreateContentTemplateContainer();
Then the CreateContents method calls the InstantiateIn method on the ContentTemplate property, passing in the template container server control. Keep in mind that ASP.NET has already parsed the markup text enclosed within the opening and closing tags of the child element into a class, compiled this class, and assigned an instance of it to the ContentTemplate property. This means that when the CreateContents method calls the InstantiateIn method on the ContentTemplate property, it actually calls the InstantiateIn method of this class instance. As discussed earlier, this method adds the server controls that represent the markup text enclosed within the opening and closing tags of the child element to the Controls collection of the template container server control: this._contentTemplate.InstantiateIn(this._contentTemplateContainer);
985
c21.indd 985
8/20/07 8:37:08 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Next, the CreateContents method calls the AddContentTemplateContainer method to add the template container server control to the Controls collection of the UpdatePanel control: this.AddContentTemplateContainer();
Listing 21-8: The CreateContents Method of the UpdatePanel private void CreateContents(bool recreate) { if (recreate) { this.ContentTemplateContainer.Controls.Clear(); this._contentTemplateContainer = null; this.ChildControls.ClearInternal(); } if (this._contentTemplateContainer == null) { this._contentTemplateContainer = this.CreateContentTemplateContainer(); this._contentTemplate.InstantiateIn(this._contentTemplateContainer); this.AddContentTemplateContainer(); } }
The following code listing contains the implementation of the CreateContentTemplateContainer method of the UpdatePanel control. As you can see, the UpdatePanel uses an instance of the Control base class as the template container server control. protected virtual Control CreateContentTemplateContainer() { return new Control(); }
Now let’s update Figure 21-6 with the latest method calls. Recall that the dashed line in Figure 21-6 represents the method calls triggered by the call into the CreateContents method of the UpdatePanel, and that this method triggers the call into the CreateContentTemplateContainer and AddContentTemplateContainer methods of the UpdatePanel, as well as the InstantiateIn method of the ITemplate interface. Figure 21-7 extends Figure 21-6 to add these three latest triggered method calls. This wraps up our discussions of the Init life cycle phase of the current Page. At this point, we digress from our main discussions to cover the related topic of templated controls in the following subsection.
986
c21.indd 986
8/20/07 8:37:09 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering InitRecursive UpdatePanel
Templated Controls The UpdatePanel is a templated control that exposes a template property named ContentTemplate. The ContentTemplate property, just like any other template property, is of type ITemplate, and as such it exposes a method named InstantiateIn. This method takes a server control known as a template container as its argument. The great thing about a template property is that you can specify its value declaratively on an .ascx or .aspx page without writing a single line of imperative code such as C# or VB.NET. This declarative value is the markup, including HTML and server controls, that you place within the opening and closing tags of the element that represents the template property on an .ascx or .aspx page. In the case of the UpdatePanel, this declarative value is the markup that you place between the opening and closing tags of the child element of the UpdatePanel, because this child element represents the ContentTemplate property on the .ascx or .aspx page.
987
c21.indd 987
8/20/07 8:37:09 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering ASP.NET automatically parses the markup enclosed within the opening and closing tags of the child element and dynamically generates an instance of a class named CompiledTemplateBuilder that implements the ITemplate interface, which means that this class implements the InstantiateIn method of the interface. This class’s implementation of this method adds the server controls that represent the markup enclosed within the opening and closing tags of the child element to the Controls collection of the server control passed into the InstantiateIn method. As mentioned earlier, this server control is known as the template container. As you can see, the template container server control acts as a container for the server controls that represent the markup enclosed within the opening and closing tags of the child element. ASP.NET then assigns this CompiledTemplateBuilder instance to the ContentTemplate property of the UpdatePanel. As discussed earlier, ASP.NET dynamically generates a class that inherits from the Page class to represent the current page, and stores the source file for this class a couple of directories underneath the directory associated with your Web application under the following standard directory on your machine: %windir%\Microsoft.NET\Framework\v2.0.50727\Temporary ASP.NET Files
If you’re curious to see the these principles in action, create a Web application that contains a page named default.aspx, as shown in the following code listing. In my case this application is named AjaxEnabledWebSite11.: void SubmitCallback(object sender, EventArgs e) { Info.Text = TextBox1.Text; } Enter text:
If you go to a couple of directories (these two directories have weird-looking names because the ASP.NET framework uses auto-generated hash values to create these names) underneath the directory named ajaxenabledwebsite11 (which is nothing but the name of the application) underneath the standard directory Temporary ASP.NET Files, and open the file that contains the source code for the dynamically generated class that represents the preceding page, as discussed earlier in this chapter,
988
c21.indd 988
8/20/07 8:37:09 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering you’ll see the following code. The boldface portion of this code listing shows how ASP.NET manages to initialize the value of the ContentTemplate property of the UpdatePanel server control. namespace ASP { public class default_aspx : Page { protected ScriptManager ScriptManager1; protected TextBox TextBox1; protected Button Button1; protected Label Info; protected UpdatePanel UpdatePanel1; protected HtmlForm form1; . . . private UpdatePanel @__BuildControlUpdatePanel1() { UpdatePanel @__ctrl = new UpdatePanel(); this.UpdatePanel1 = @__ctrl; BuildTemplateMethod templateMethod = new BuildTemplateMethod(this.@__BuildControl__control4); @__ctrl.ContentTemplate = new CompiledTemplateBuilder(templateMethod); @__ctrl.ID = “UpdatePanel1”; return @__ctrl; } . . . } }
Interestingly enough, the CompiledTemplateBuilder class is a public class, which means that you can use it within your own C# or VB.NET code. As we discussed in the previous chapter, if you need to imperatively add server controls to an UpdatePanel server control, you must add these server controls to the Controls collection of the ContentTemplateContainer property of the UpdatePanel server control. You can use the CompiledTemplateBuilder class to enhance the functionality of the ASP.NET UpdatePanel server control to add support for default templates. The following code listing shows the implementation of such a custom UpdatePanel server control. To understand the implementation of this custom server control, you first need to understand how the CompiledTemplateBuilder class works. The constructor of this class takes an instance of a .NET delegate named BuildTemplateMethod, which represents a method that takes a single argument of type Control and returns no value. It is the responsibility of this method to populate the Controls collection of the Control passed into it with the appropriate server controls. As you’ll see shortly, these server controls will constitute the content of the custom UpdatePanel server control. Now back to the implementation of the CustomUpdatePanel server control. As you can see from the following code listing, the CustomUpdatePanel server control exposes two public properties named BuildTemplateMethodProviderType and BuildTemplateMethodProviderMethod. The BuildTemplateMethodProviderType property specifies the assembly-qualified name of a .NET type. The assembly-qualified name of a .NET type consists of five parts, which includes the fully qualified name of the type (including its complete namespace containment hierarchy) and the name, version, culture, and public key token of the assembly where the type resides. The
989
c21.indd 989
8/20/07 8:37:10 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering BuildTemplateMethodProviderMethod property specifies the name of the method of this .NET type that takes no arguments and returns an instance of the BuildTemplateMethod delegate.
Next, I’ll walk you through the implementation of the OnInit method of the CustomUpdatePanel server control, where all the action is. This method begins by checking whether the values of the BuildTemplateMethodProviderType and BuildTemplateMethodProviderMethod properties are set. If not, the method simply invokes the OnInit method on its base class — that is, the UpdatePanel server control. If so, it performs the following tasks. First, it extracts the fully qualified name of the specified .NET type, excluding the assembly information, from the BuildTemplateMethodProviderType property: string typeName = BuildTemplateMethodProviderType.Trim().Split( new char[] { ‘,’ })[0];
Next, it extracts the assembly information for the BuildTemplateMethodProviderType property: string assemblyName = BuildTemplateMethodProviderType.Trim().Remove( BuildTemplateMethodProviderType.IndexOf(typeName), typeName.Length);
Then, if the BuildTemplateMethodProviderType property does not contain the assembly information, the CustomUpdatePanel server control assumes that the specified .NET type resides in the executing assembly, and consequently invokes the GetExecutingAssembly static method on the Assembly class to return a reference to the Assembly object that represents the executing assembly: Assembly assembly; if (string.IsNullOrEmpty(assemblyName)) assembly = Assembly.GetExecutingAssembly();
If the BuildTemplateMethodProviderType property does contain the assembly information, it invokes the Load static method on the Assembly class to load the specified assembly into the current application domain and to return a reference to the Assembly object that represents this assembly: else { assemblyName = assemblyName.Trim().Remove(0, 1); assembly = Assembly.Load(assemblyName); }
Next, the OnInit method invokes the CreateInstance method on the Assembly object, passing in the fully qualified name of the specified .NET type to instantiate an instance of this .NET type: object provider = assembly.CreateInstance(typeName);
Then it invokes the GetType method on the newly-created instance to return a reference to the Type object that represents the type of this instance: Type type = provider.GetType();
990
c21.indd 990
8/20/07 8:37:10 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Next, it invokes the GetMethod on this Type object, passing in the value of the BuildTemplateMethodProviderMethod property to return a reference to the MethodInfo object that represents the specified method of the specified .NET type. Recall that this is the method that returns the BuildTemplateMethod delegate that you must pass into the CompiledTemplateBuilder constructor: MethodInfo methodInfo = type.GetMethod(BuildTemplateMethodProviderMethod);
Then it calls the Invoke method on the MethodInfo object to dynamically invoke the specified method on the newly created instance and consequently to return the BuildTemplateMethod delegate that you need: BuildTemplateMethod method = (BuildTemplateMethod)methodInfo.Invoke(provider, null);
Next, the OnInit method passes the BuildTemplateMethod instance into the CompiledTemplateBuilder constructor to instantiate a CompiledTemplateBuilder object, which is subsequently assigned to the ContentTemplate property that the CustomUpdatePanel server control inherits from the UpdatePanel server control: ContentTemplate = new CompiledTemplateBuilder(method);
Finally, it invokes the OnInit method of its base class — that is, the UpdatePanel server control. This step is very important because, as thoroughly discussed earlier, the OnInit method of the UpdatePanel server control is the method that actually calls the InstantiateIn method on the ContentTemplate property to create the content of the UpdatePanel control. Nothing will take effect if this last step is not taken.
Listing 21-9: The CustomUpdatePanel Server Control using System; using System.Web; using System.Web.UI; using System.Web.UI.WebControls; using System.Reflection; namespace CustomComponents5 { public class CustomUpdatePanel : UpdatePanel { public string BuildTemplateMethodProviderType { get { return ViewState[“BuildTemplateMethodProviderType”] != null ? (string)ViewState[“BuildTemplateMethodProviderType”] : string.Empty; } set { ViewState[“BuildTemplateMethodProviderType”] = value; } }
(continued)
991
c21.indd 991
8/20/07 8:37:10 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Listing 21-9 (continued) public string BuildTemplateMethodProviderMethod { get { return ViewState[“BuildTemplateMethodProviderMethod”] != null ? (string)ViewState[“BuildTemplateMethodProviderMethod”] : string.Empty; } set { ViewState[“BuildTemplateMethodProviderMethod”] = value; } } protected override void OnInit(EventArgs e) { if (!string.IsNullOrEmpty(BuildTemplateMethodProviderType) && !string.IsNullOrEmpty(BuildTemplateMethodProviderMethod)) { string typeName = BuildTemplateMethodProviderType.Trim().Split( new char[] { ‘,’ })[0]; string assemblyName = BuildTemplateMethodProviderType.Trim().Remove( BuildTemplateMethodProviderType.IndexOf(typeName), typeName.Length); Assembly assembly; if (string.IsNullOrEmpty(assemblyName)) assembly = Assembly.GetExecutingAssembly(); else { assemblyName = assemblyName.Trim().Remove(0, 1); assembly = Assembly.Load(assemblyName); } object provider = assembly.CreateInstance(typeName); Type type = provider.GetType(); MethodInfo methodInfo = type.GetMethod(BuildTemplateMethodProviderMethod); BuildTemplateMethod method = (BuildTemplateMethod)methodInfo.Invoke(provider, null); ContentTemplate = new CompiledTemplateBuilder(method); } base.OnInit(e); } } }
Listing 21-10 contains an example of a .NET type that supports a method that returns a BuildTemplateMethod delegate. This code listing shows a class named BuildTemplateMethodProvider that exposes a method named GetBuildTemplateMethod that instantiates and returns an instance of the BuildTemplateMethod delegate. Note that this method passes another method named BuildTemplate as an argument into the constructor of the BuildTemplateMethod delegate. When the CompiledTemplateBuilder invokes the BuildTemplateMethod delegate, this delegate in turn invokes the method passed into its constructor, which is the BuildTemplate method in this case. Note that the method passed into this constructor must take a single argument of type Control and return no value.
992
c21.indd 992
8/20/07 8:37:11 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering The BuildTemplate method is where the BuildTemplateMethodProvider class builds the server controls that go into the UpdatePanel server control. The method can be as complex as you want it to be and can build any type of server controls that you want to put in. In this simple example, the BuildTemplate method first creates a Label control, sets its Text property value to the current date and time, and adds the Label control to the Controls collection of the Control passed into it. Since the CompiledTemplateBuilder passes the ContentTemplateContainer of the UpdatePanel server control as the argument of the BuildTemplate method, any server control you add to the Controls collection of this control goes right into the UpdatePanel server control. label1 = new Label(); label1.Text = DateTime.Now.ToString(); c.Controls.Add(label1);
The BuildTemplate method then creates a Button control, registers a method named Button1_Click as an event handler for its Click event, and adds the Button to the Controls collection of the Control passed into it: Button button1 = new Button(); button1.Text = “Update”; button1.Click += new EventHandler(Button1_Click); c.Controls.Add(button1);
The Button1_Click method doesn’t do much in this case. It simply displays the current date and time in the Label control.
21-10: An Example of a .NET Type that Supports a Method that Returns a BuildTemplateMethod Delegate using System; using System.Web; using System.Web.UI; using System.Web.UI.WebControls; using System.Reflection; namespace CustomComponents5 { public class BuildTemplateMethodProvider { Label label1; public void BuildTemplate(Control c) { label1 = new Label(); label1.Text = DateTime.Now.ToString(); c.Controls.Add(label1); Button button1 = new Button(); button1.Text = “Update”; button1.Click += new EventHandler(Button1_Click); c.Controls.Add(button1); }
(continued)
993
c21.indd 993
8/20/07 8:37:11 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering 21-10 (continued) void Button1_Click(object sender, EventArgs e) { label1.Text = DateTime.Now.ToString(); } public BuildTemplateMethod GetBuildTemplateMethod() { return new BuildTemplateMethod(BuildTemplate); } } }
The following code listing contains a page that uses the CustomUpdatePanel server control: void Page_Load(object sender, EventArgs e) { Info.Text = DateTime.Now.ToString(); } Untitled Page
The official ASP.NET 2.0 documentation from Microsoft makes the following statement about the CompiledTemplateBuilder class: This class supports the .NET Framework infrastructure and is not intended to be used directly from your code. That said, there is nothing technically wrong with directly using this class from your code. Another important point is that as you’ve seen in the preceding examples, this class makes a great educational tool for learning about the UpdatePanel server control, which is one of our main goals in this chapter.
994
c21.indd 994
8/20/07 8:37:11 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering
LoadRecursive Keep in mind, again, that you’re following the current Page object as it goes through its life cycle phases to process the first HTTP GET request made to a Web page enabled for partial page rendering. Since the first request is not a postback, the current Page skips all the postback-related life cycle phases and enters directly into its LoadRecusive (or Load) life cycle phase, in which the ProcessRequest method of the current Page (see Listing 21-1) invokes the LoadRecursive method on the current Page. The following code listing presents the internal implementation of the LoadRecursive method. All server controls, including the Page, ScriptManager, and UpdatePanel, inherit the LoadRecursive method from the Control base class. As the following code listing shows, the LoadRecursive method of a server control such as Page or UpdatePanel first calls its own OnLoad method and then calls the LoadRecursive methods of its child server controls. internal virtual void LoadRecursive() { this.OnLoad(EventArgs.Empty); foreach (Control control in this.Controls) { control.LoadRecursive(); } }
Therefore, the following sequence of method calls occurs when the current Page enters its LoadRecusive phase:
1. 2. 3. 4. 5. 6.
The call into the LoadRecusive method of the current Page The call into the OnLoad method of the current Page The call into the LoadRecusive method of the ScriptManager The call into the OnLoad method of the ScriptManager The call into the LoadRecusive method of the UpdatePanel The call into the OnLoad method of the UpdatePanel
The OnLoad methods of the current Page and the current ScriptManager server control simply raise the Load event. If you need to execute some application-specific logic when the current ScriptManager server control or a particular UpdatePanel server control enters its Load life cycle phase, you must encapsulate this logic in a method and register this method as an event handler for the Load event of the current ScriptManager server control or the specified UpdatePanel server control. If you want the ScriptManager server control to do more work than just raising the Load event, you can write your own custom ScriptManager server control that inherits from the ScriptManager server control and overrides its OnLoad method to do whatever else you need the control to do when it enters its Load life cycle phase. Make sure your custom ScriptManager server control’s implementation of the OnLoad method calls the OnLoad method of its base class. Otherwise your custom ScriptManager server control will not raise the Load event when it enters its Load life cycle phase.
995
c21.indd 995
8/20/07 8:37:12 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Listing 21-11 presents the internal implementation of the OnLoad method of the UpdatePanel server control. As you can see, this method checks whether the current request is an asynchronous page postback. If not, it calls the Initialize method of the UpdatePanel to initialize it. Keep in mind that the current Page is processing the first request to a Web page enabled for partial page rendering. Since the first request is not a postback, the OnLoad method of the UpdatePanel server control calls its Initialize method, which will be discussed in the following section. Implement a custom UpdatePanel server control that overrides the OnLoad method if you want the UpdatePanel server control to do more work than just raising the Load event and invoking the Initialize method.
Listing 21-11: The OnLoad Method of the UpdatePanel protected override void OnLoad(EventArgs e) { base.OnLoad(e); if (!this.ScriptManager.IsInAsyncPostBack) this.Initialize(); }
Figure 21-8 presents a diagram that contains the method calls that occur when the current Page enters the LoadRecusive life cycle phase: LoadRecursive Page
UpdatePanel
ScriptManager
LoadRecursive ( ) OnLoad ( )
LoadRecursive ( ) OnLoad ( )
LoadRecursive ( ) OnLoad ( ) Initialize ( )
Figure 21-8
996
c21.indd 996
8/20/07 8:37:12 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering As mentioned earlier, the current ScriptManager server control’s OnLoad method simply raises the Load event and consequently invokes the event handlers registered for this event. If you need to run some custom code when the current ScriptManger server control raises its Load event, you have two options. If your custom code is something that you think a lot of your clients might be interested in and is not specific to a particular application, you can write a custom server control that derives from the ScriptManager server control and overrides its OnLoad method to include this custom code. Here is an example: public class MyScriptManager : ScriptManager { protected override void OnLoad(EventArgs e) { base.OnInit(e); // Your custom code should go here } }
It’s very important that your custom server control’s implementation of the OnLoad method invoke the OnLoad method of its base class — that is, the ScriptManager server control. Otherwise the Load event of your custom server control will not be raised and consequently the event handlers registered for this event will not be invoked. If your custom code is specific to a particular application, you need to wrap the code in a method and register the method as the event handler for the Load method of the current ScriptManager server control instead of writing a custom server control. Here is an example: void MethodContainingYourCustomCode(object sender, EventArgs e) { // Your custom code should go here } Untitled Page . . .
As you saw in Listing 21-11, the UpdatePanel server control invokes the OnLoad method of its base class to raise the Load event and consequently invoke the event handlers registered for this event. If you need to run some custom code when a specific UpdatePanel server control on the current page raises its Load event, you have the same two options that you have with the ScriptManager, as just discussed.
997
c21.indd 997
8/20/07 8:37:12 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering
The Initialize Method of the UpdatePanel The UpdatePanel server control maintains an internal collection of type UpdatePanelTriggerCollection named _triggers that contains objects of type UpdatePanelTrigger. As the name suggests, an UpdatePanelTrigger object triggers automatic updates of its associated UpdatePanel server control. Note that an UpdatePanelTrigger object is an instance of a class, which itself is not a server control. This raises the following question: what causes an UpdatePanelTrigger object to trigger the automatic updates of its associated UpdatePanel server control? The answer is “it depends.” Different types of triggers use different types of mechanisms. The UpdatePanelTrigger class is an abstract base class whose methods and properties define an API that all triggers must implement in order to act as triggers for automatic updates of their associated UpdatePanel server controls. The UpdatePanel exposes a property of type UpdatePanelTriggerCollection named Triggers that returns a reference to the _triggers collection, as shown in Listing 21-12.
Listing 21-12: The Triggers Collection Property of the UpdatePanel [DefaultValue((string)null), PersistenceMode(PersistenceMode.InnerProperty)] public UpdatePanelTriggerCollection Triggers { get { if (this._triggers == null) this._triggers = new UpdatePanelTriggerCollection(this); return this._triggers; } }
As Listing 21-13 shows, the Initialize method of the UpdatePanel first checks whether the _triggers collection contains any UpdatePanelTrigger objects and whether the partial rendering is supported. If both of these conditions are met, it calls the Initialize method on the _triggers collection to initialize the collection.
Listing 21-13: The Initialize Method of the UpdatePanel protected internal virtual void Initialize() { if ((this._triggers != null) && this.ScriptManager.SupportsPartialRendering) this._triggers.Initialize(); }
The Initialize Method of the UpdatePanelTriggerCollection As Listing 21-14 shows, the Initialize method of the UpdatePanelTriggerCollection iterates through its constituent UpdatePanelTrigger objects and calls their Initialize methods to initialize them. Note that the Initialize method sets an internal flag named _initialized to true to mark the end of the initialization phase.
998
c21.indd 998
8/20/07 8:37:13 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Listing 21-14: The Initialize Method of the UpdatePanelTriggerCollection internal void Initialize() { using (IEnumerator enumerator1 = base.GetEnumerator()) { while (enumerator1.MoveNext()) { enumerator1.Current.Initialize(); } } this._initialized = true; }
Before diving into the implementation of the Initialize method of the UpdatePanelTrigger class, let’s update Figure 21-8 with the latest method calls. Recall that the dashed line in Figure 21-8 represents the method calls triggered by the call into the Initialize method of the UpdatePanel server control. As mentioned earlier, the Initialize method triggers the call into the Initialize method of the UpdatePanelTriggersCollection, which in turn triggers the call into the Initialize method of the UpdatePanelTrigger. Figure 21-9 extends Figure 21-8 to add these two latest triggered method calls. Note that Figure 21-9 contains a dashed line, which represents the method calls triggered by the call into the Initialize method of the UpdatePanelTrigger, which will be discussed in the following sections. I’ll wrap up the discussions of this subsection with the following note on the Initialize method of the UpdatePanel server control. As you can see from Listing 21-11, when the UpdatePanel server control enters its Load life cycle phase it automatically invokes its Initialize method if the current request is not an asynchronous partial-page-rendering request: protected override void OnLoad(EventArgs e) { base.OnLoad(e); if (!this.ScriptManager.IsInAsyncPostBack) this.Initialize(); }
As Listing 21-13 shows, the Initialize method of the UpdatePanel server control is marked as protected virtual. This means that you can write a custom server control that derives from the UpdatePanel server control and overrides its Initialize method to extend its functionality. Keep in mind that any custom code you include in the Initialize method will not be executed when the current request is an asynchronous partial page rendering. Also make sure that your custom control’s implementation of the Initialize method invokes the Initialize method of its base class — that is, the UpdatePanel server control. Otherwise, none of the triggers registered with your custom controls will be initialized.
999
c21.indd 999
8/20/07 8:37:13 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering LoadRecursive Page
UpdatePanel
ScriptManager
UpdatePanelTrigger
LoadRecursive ( ) OnLoad ( )
LoadRecursive ( ) OnLoad ( )
LoadRecursive ( ) OnLoad ( ) Initialize ( )
UpdatePanelTriggerCollection Initialize ( )
Initialize ( )
Figure 21-9
The Initialize Method of the UpdatePanelTrigger As you can see from Listing 21-15, the UpdatePanelTrigger is an abstract class whose Initialize method does not do anything. However, the subclasses of this abstract class override this method to perform subclass-specific initialization. At this point, we digress from our main discussion to study the UpdatePanelTrigger and its subclasses.
Listing 21-15: The Initialize Method of the UpdatePanelTrigger public abstract class UpdatePanelTrigger { protected internal abstract bool HasTriggered(); protected internal virtual void Initialize() { } internal void SetOwner(UpdatePanel owner) { this._owner = owner; } private UpdatePanel _owner; }
1000
c21.indd 1000
8/20/07 8:37:13 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering UpdatePanelTrigger and its Subclasses The methods of the UpdatePanelTrigger base class define the API that every UpdatePanelTrigger subclass must implement in order to trigger updates of its owner UpdatePanel server control. Keep in mind that the owner of an UpdatePanelTrigger object is the UpdatePanel server control whose Triggers collection contains the object. As Listing 21-15 shows, this API consists of two methods:
❑
Initialize: A subclass of the UpdatePanelTrigger base class can override this optional
method to perform any subclass-specific initialization task. You’ll see an example of this later in this section.
❑
HasTriggered: A subclass of the UpdatePanelTrigger base class must override this mandatory method, where the subclass’s implementation of this method must use subclass-specific logic to determine when the trigger has been triggered. You’ll see an example of this later in this section.
Note that the UpdatePanelTrigger exposes a method named SetOwner that specifies an UpdatePanel control as the owner of the trigger. This method is marked as internal, which means that you can never set the owner UpdatePanel server control of a given UpdatePanelTrigger from your code. You may be wondering who calls this method. The answer is the Add method of the UpdatePanelTriggerCollection. Recall from Listing 21-12 that when the Triggers property of the UpdatePanel instantiates the UpdatePanelTriggerCollection, it passes a reference to the UpdatePanel control into the constructor of the UpdatePanelTriggerCollection, as shown in the highlighted portion of the following code listing: [DefaultValue((string)null), PersistenceMode(PersistenceMode.InnerProperty)] public UpdatePanelTriggerCollection Triggers { get { if (this._triggers == null) this._triggers = new UpdatePanelTriggerCollection(this); return this._triggers; } }
Listing 21-16 presents the internal implementation of the constructor of the UpdatePanelTriggerCollection. As you can see, this constructor stores the reference to the owner UpdatePanel server control in a field named _owner for future reference.
Listing 21-16: The Constructor of the UpdatePanelTriggerCollection public UpdatePanelTriggerCollection(UpdatePanel owner) { if (owner == null) throw new ArgumentNullException(“owner”); this._owner = owner; }
1001
c21.indd 1001
8/20/07 8:37:13 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering As a matter of fact, the UpdatePanelTriggerCollection exposes a public read-only property named Owner that returns the value of the _owner field, as shown in Listing 21-17.
Listing 21-17: The Owner Property of the UpdatePanelTriggerCollection public UpdatePanel Owner { get {return this._owner;} }
The UpdatePanelTriggerCollection exposes a method named InsertItem, as shown in Listing 21-18. When you call the Add method on the Triggers collection of an UpdatePanel server control to add a new UpdatePanelTrigger object to the collection, the Add method internally calls the InsertItem method. As you can see from Listing 21-18, the InsertItem method takes these steps. First, it calls the SetOwner method on the UpdatePanelTrigger object being inserted, to set its owner UpdatePanel server control: item.SetOwner(this.Owner);
Therefore, when the Add method is invoked on the Triggers collection of an UpdatePanel server control to add a new UpdatePanelTrigger object to the collection, under the hood the Add method automatically sets the owner of the newly added UpdatePanelTrigger object. In general, there are two ways to add a new UpdatePanelTrigger object to the Triggers collection of an UpdatePanel server. The first approach, which is the most common, is to do it declaratively. Here is an example: . . .
When you do this declaratively, the page parser automatically calls the Add method under the hood to add the specified trigger to the Triggers collection. The second approach is to do it imperatively from your code: UpdatePanel up; AsyncPostBackTrigger trigger = new AsyncPostBackTrigger(); trigger.ControlID = “Button1”; trigger.EventName = “Click”; up.Triggers.Add(trigger);
As you can see, the imperative approach requires you to explicitly invoke the Add method on the Triggers collection.
1002
c21.indd 1002
8/20/07 8:37:14 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Back to the implementation of the InsertItem method. Next, this method checks whether its _intialized field has been set. If so, it initializes the object by calling the Initialize method on the UpdatePanelTrigger object being inserted: if (this._initialized) item.Initialize();
Recall from Listing 21-14 that the Initialize method of the UpdatePanelTriggerCollection is the one that sets the value of the _initialized field. Therefore, you can add new UpdatePanelTrigger objects to the Triggers collection of a given UpdatePanel server control, even after the Init life cycle phase and rest assured that the Initialize method of your newly added UpdatePanelTrigger object will be automatically invoked. A good place for imperative addition of new UpdatePanelTrigger objects to the Triggers collection of an UpdatePanel server control is within the Page_Load method of the current page — that is, where the current Page enters its Load life cycle phase.
Listing 21-18: The Add Method of the UpdatePanelTriggerCollection protected override void InsertItem(int index, UpdatePanelTrigger item) { item.SetOwner(this.Owner); if (this._initialized) item.Initialize(); base.InsertItem(index, item); }
Note that the UpdatePanelTrigger API does not contain any reference to any server control (see Listing 21-15). This means that this API does not put a restriction on how a particular subclass of UpdatePanelTrigger is triggered. In other words, you could implement a subclass of the UpdatePanelTrigger base class that is triggered by a mechanism other than a server control. The immediate subclass of the UpdatePanelTrigger abstract class is another abstract class named UpdatePanelControlTrigger (see Listing 21-19), which exposes a property named ControlID and a method named FindTargetControl. Every UpdatePanelControlTrigger trigger is associated with a server control. The user interaction with the associated server control of an UpdatePanelControlTrigger trigger triggers the UpdatePanelControlTrigger, which in turn triggers the update of its owner UpdatePanel server control. The ControlID property of the UpdatePanelControlTrigger contains the UniqueID property value of the trigger’s associated server control. As the name suggests, the FindTargetControl method finds and returns a reference to the associated server control of the UpdatePanelControlTrigger trigger. As Listing 21-19 shows, the FindTargetControl method first checks whether it is asked to limit the search for the associated server control to the child controls of the UpdatePanel control that owns the UpdatePanelControlTrigger trigger. If so, the method simply calls the FindControl method on the owner UpdatePanel control to search for the associated server control. Otherwise, the method searches through all the naming containers of the UpdatePanel control and its ancestor controls for the associated server control.
1003
c21.indd 1003
8/20/07 8:37:14 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Note that the FindTargetControl method is marked as protected. This means that only subclasses of this base class can access this method. Therefore, when you’re writing your own custom subclass of the UpdatePanelControlTrigger class, you can call this method from within your subclass scope to return a reference to the associated server control of your subclass. Also note that the FindTargetControl method cannot be overridden because it is not marked as virtual. Your custom subclass must use this method as is.
Listing 21-19: The UpdatePanelControlTrigger Class public abstract class UpdatePanelControlTrigger : UpdatePanelTrigger { protected Control FindTargetControl(bool searchNamingContainers) { if (searchNamingContainers) { Control control2 = base.Owner; Control control1 = null; while ((control1 == null) && (control2 != base.Owner.Page)) { control2 = control2.NamingContainer; if (control2 == null) return control1; control1 = control2.FindControl(this.ControlID); } return control1; } return base.Owner.FindControl(this.ControlID); } [DefaultValue(“”)] public string ControlID { get { return (this._controlID ?? string.Empty); } set { this._controlID = value; } } private string _controlID; }
The ASP.NET AJAX framework comes with two subclasses of the UpdatePanelControlTrigger abstract base class: PostBackTrigger and AsyncPostBackTrigger. As the names suggest, these two triggers are associated with server controls that trigger synchronous and asynchronous page postbacks, respectively.
Back to the Initialize Method of UpdatePanelTrigger Recall that we digressed from our discussions of the Initialize method of the UpdatePanelTrigger class to study this class and its subclasses in more detail. As you may recall from Listing 21-14, the Initialize method of the UpdatePanelTriggerCollection invokes the Initialize method of its constituent UpdatePanelTrigger objects. As Listing 21-15 shows, the Initialize method of the UpdatePanelTrigger abstract base class doesn’t do anything. However, the AsyncPostBackTrigger subclass of this base class overrides this method, providing the implementations shown in Listing 21-20.
1004
c21.indd 1004
8/20/07 8:37:14 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Before diving into the AsyncPostBackTrigger’s implementation of the Initialize method, we need to get some facts straight about an AsyncPostBackTrigger and how it works. An AsyncPostBackTrigger, like any other subclass of the UpdatePanelControlTrigger base class, is triggered when its associated server control raises a specified type of event. That is why, as you can see from Listing 21-20, the AsyncPostBackTrigger exposes two read/write properties named ControlID and EventName. You must set the ControlID property to the value of the ID property of its associated server control. Even though it’s mandatory that you set the value of the ControlID property, it is not mandatory to set the EventName property. However, if you decide to set this property, you must set it to the name of a specified event of the associated server control. public string ControlID { get { return base.ControlID; } set { base.ControlID = value; } } [DefaultValue(“”)] public string EventName { get { if (this._eventName == null) return string.Empty; return this._eventName; } set { this._eventName = value; } }
Here is an example: . . .
As you can see, this code listing sets the ControlID property of the AsyncPostBackTrigger to the value of the ID property of the specified ASP.NET Button server control, and the EventName property to the string ”Click” to specify that the AsyncPostBackTrigger must be triggered when the Click event of the specified Button server control is raised. Now let’s walk through the Initialize method of the AsyncPostBackTrigger. The whole idea behind the Initialize method is to register a method named OnEvent as an event handler for the specified event — that is, the event whose name is given by the EventName property — of the associated server control so that when the server control raises this event, the OnEvent method of the AsyncPostBackTrigger
1005
c21.indd 1005
8/20/07 8:37:15 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering is automatically invoked, allowing the AsyncPostBackTrigger to mark itself as triggered. As Listing 21-21 shows, the OnEvent method simply sets an internal flag to mark the current AsyncPostBackTrigger as triggered: public void OnEvent(object sender, EventArgs e) { this._eventHandled = true; }
As Listing 21-20 shows, the AsyncPostBackTrigger class’ implementation of the Initialize method is complex. This makes you wonder what is so difficult about registering the OnEvent method as the event handler for the specified event of the associated server control. The difficulty arises from the fact that the only information you’re providing to the AsyncPostBackTrigger is the value of the ID property of its associated server control and the name of the event of the associated server control that you want the AsyncPostBackTrigger to respond to: . . .
To register a method as an event handler for an event of a server control:
❑
You need a reference to the server control.
❑
You need to know the actual delegate type of the event so you can instantiate an instance of this delegate to represent your method.
For example, to register the OnEvent method as an event handler for the Click event of the ASP.NET Button server control shown in the previous example:
❑
You need a reference to the ASP.NET Button server control with the ID property value of Button1. Let’s assume that some variable named myButton references this server control.
❑
You need to know that the Click event of the ASP.NET Button server control is a delegate of type EventHandler so you can instantiate an instance of the EventHandler delegate to represent the OnEvent method, and add this delegate to the Click event delegate:
myButton.Click += new EventHandler(OnEvent);
1006
c21.indd 1006
8/20/07 8:37:15 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering The AsyncPostBackTrigger only knows the following things:
❑
The value of the ID property of the server control instead of the actual reference to the control itself
❑
The name of the event instead of the actual type of the event delegate
That is why the Initialize method must take extra steps to use the value of the ID property of the server control to somehow access a reference to the control itself, and to use the name of the event to somehow access the actual type of the event delegate. Now let’s walk through the implementation of the Initialize method of the AsyncPostBackTrigger shown in Listing 21-20 to see how this method manages to register the OnEvent method as an event handler for the specified event of the server control with the specified ID property value.
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Listing 21-20 (continued) public override string ToString() { if (string.IsNullOrEmpty(this.ControlID)) return “AsyncPostBack”; return (“AsyncPostBack: “ + this.ControlID + (string.IsNullOrEmpty(this.EventName) ? string.Empty : (“.” + this.EventName))); } public string ControlID { get { return base.ControlID; } set { base.ControlID = value; } } private static MethodInfo EventHandler { get { if (AsyncPostBackTrigger._eventHandler == null) AsyncPostBackTrigger._eventHandler = typeof(AsyncPostBackTrigger).GetMethod(“OnEvent”); return AsyncPostBackTrigger._eventHandler; } } [DefaultValue(“”)] public string EventName { get { if (this._eventName == null) return string.Empty; return this._eventName; } set { this._eventName = value; } } internal IScriptManagerInternal ScriptManager { get { if (this._scriptManager == null) { this._scriptManager = ScriptManager.GetCurrent(base.Owner.Page); if (this._scriptManager == null) throw new InvalidOperationException(“ScriptManagerRequired”); } return this._scriptManager; } } private Control _associatedControl; private bool _eventHandled; private static MethodInfo _eventHandler; private string _eventName; private IScriptManagerInternal _scriptManager; }
1008
c21.indd 1008
8/20/07 8:37:16 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering This method first calls the FindTargetControl method that it inherits from its base class to return a reference to its associated server control. Recall from Listing 21-19 that the FindTargetControl method searches through the child controls of all the naming containers of the owner UpdatePanel server control and the owner ancestor server controls for the server control with the specified ID property value. In the case of the previous example, this method will return a reference to the Button server control with the ID property value of Button1. Therefore, the call into the FindTargetControl method provides the AsyncPostBackTrigger with a reference to the server control for whose event the OnEvent method is being registered as an event handler: this._associatedControl = base.FindTargetControl(true);
The method then calls the RegisterAsyncPostBackControl method on the current ScriptManager instance, passing in the reference to its associated server control to register this control as the trigger for asynchronous page postbacks. As you’ll see later, the server-side PageRequestManager instance passes the list of the UniqueID property values of the controls registered as triggers for asynchronous page post backs to the client-side PageRequestManager instance, where they’re stored in an internal client-side collection for future reference. When the end user clicks a control to post the form back to the server, the client-side PageRequestManager intercepts the postback before the actual postback request is made to the server, and determines whether the end user has clicked a control whose UniqueID property value belongs to the internal collection. If so, it treats the postback as asynchronous and makes an asynchronous page postback request to the server, bypassing the normal browser’s form submission. This will all be made clear in the next few chapters. this.ScriptManager.RegisterAsyncPostBackControl(this._associatedControl);
The RegisterAsyncPostBackControl method of the ScriptManager class is a public method that you can use in your own C# or VB.NET code. In other words, the application of this method is not limited to the AsyncPostBackTrigger class. The rest of the code in the Initialize method is there to access the actual type of the event delegate in a generic fashion. As you can see, the method first calls the GetType method on its associated server control to return a reference to the Type object that represents the type of the control: Type associatedControlType = this._associatedControl.GetType();
Next, it calls the GetEvent method on this Type object, passing in the event name to return a reference to the EventInfo object that represents the specified event of its associated control: EventInfo eventInfo = associatedControlType.GetEvent(this.EventName, BindingFlags.Public | BindingFlags.Instance | BindingFlags.IgnoreCase);
Then it accesses the Type object that represents the type of the event delegate: Type eventDelegateType = eventInfo.EventHandlerType;
Next, it calls GetMethod on this Type object to return a reference to the MethodInfo object that represents the Invoke method of the event delegate: MethodInfo methodInfo = eventDelegateType.GetMethod(“Invoke”);
1009
c21.indd 1009
8/20/07 8:37:16 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Then it calls the CreateDelegate static method on the Delegate class, passing in three parameters to create a Delegate object. The first parameter references the Type object that represents the type of the delegate object being created. The second parameter references the current AsyncPostBackTrigger object. (This parameter is automatically passed into the delegate object being created as its first argument when the delegate is finally invoked.) The third parameter references the MethodInfo object that represents the method that the delegate object being created encapsulates. As you’ll see shortly, the AsyncPostBackTrigger exposes a static property of type MethodInfo named EventHandler that represents the OnEvent method. Delegate delegate = Delegate.CreateDelegate(eventDelegateType, this, AsyncPostBackTrigger.EventHandler);
Finally, the method calls the AddEventHandler method on the EventInfo object that represents the event whose name is given by the EventName property, to register the newly created delegate object as event handler for this event: eventInfo.AddEventHandler(this._associatedControl, delegate);
As mentioned earlier, the AsyncPostBackTrigger class exposes a static property of type MethodInfo named EventHandler. As you can see from the following code listing, this property represents the OnEvent method of the AsyncPostBackTrigger class. Therefore, the delegate object that the CreateDelegate method creates represents the OnEvent method of the AsyncPostBackTrigger. This means that when the associated server control finally raises the event whose name is given by the EventName property of the AsyncPostBackTrigger, the OnEvent method of the AsyncPostBackTrigger is automatically invoked: private static MethodInfo EventHandler { get { if (AsyncPostBackTrigger._eventHandler == null) AsyncPostBackTrigger._eventHandler = typeof(AsyncPostBackTrigger).GetMethod(“OnEvent”); return AsyncPostBackTrigger._eventHandler; } }
As discussed earlier, the OnEvent method of the AsyncPostBackTrigger simply sets an internal flag named _eventHandler to true to mark the AsyncPostBackTrigger as triggered: public void OnEvent(object sender, EventArgs e) { this._eventHandled = true; }
As you’ll see later, at some point in the UpdatePanel server control’s life cycle the HasTriggered property is invoked on each UpdatePanelTrigger, including the AsyncPostBackTrigger in the Triggers collection of the UpdatePanel server control, to determine whether it has been triggered. As the following code listing shows, the HasTriggered method of the AsyncPostBackTrigger takes the following steps. If the EventName property of the AsyncPostBackTrigger has been set, it simply returns the value of the _eventHandled flag. Otherwise it compares the value of the AsyncPostBackSourceElementID property of the ScriptManager with the value of the UniqueID property of its associated server control.
1010
c21.indd 1010
8/20/07 8:37:16 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering If they are the same, or if the value of the AsyncPostBackSourceElementID property begins with the value of the UniqueID property of its associated server control plus the dollar sign, the HasTriggered method returns true to signal to its caller that the current AsyncPostBackTrigger has indeed been triggered: protected internal override bool HasTriggered() { if (!string.IsNullOrEmpty(this.EventName)) return this._eventHandled; string text1 = this.ScriptManager.AsyncPostBackSourceElementID; if (text1 != this._associatedControl.UniqueID) return text1.StartsWith(this._associatedControl.UniqueID + “$”, StringComparison.Ordinal); return true; }
As mentioned earlier, the HasTriggered method returns true if the value of the AsyncPostBackSourceElementID property begins with the value of the UniqueID property of its associated server control plus the dollar sign. This happens when the associated server control of the AsyncPostBackTrigger is a composite control that contains a child control that triggers the asynchronous postbacks. This means that the associated server control of an AsyncPostBackTrigger does not have to be a simple server control. Before diving into the implementation of the RegisterAsyncPostBackControl method of the ScriptManager class, let’s update Figure 21-9 with the latest method calls. Recall that the dashed line in Figure 21-9 represents the method calls triggered by the call into the Initialize method of the UpdatePanelTrigger. In this case the trigger is the AsyncPostBackTrigger subclass of the UpdatePanelTrigger. Because of this, we need to replace the UpdatePanelTrigger class shown in Figure 21-9 with AsyncPostBackTrigger. Again, the Initialize method of the AsyncPostBackTrigger triggers the call into the FindTargetControl method of the AsyncPostBackTrigger and the RegisterAsyncPostBackControl method of the ScriptManager. Figure 21-10 extends Figure 21-9 to add these two latest triggered method calls. Note that Figure 21-10 contains a dashed line that represents the method calls triggered by the call into RegisterAsyncPostBackControl method of the ScriptManager, which will be discussed in the
following sections.
The RegisterAsyncPostBackControl Method of the ScriptManager As you saw earlier, the Initialize method of the AsyncPostBackTrigger calls the RegisterAsyncPostBackControl method on the ScriptManager to register its associated server control as a trigger for asynchronous page postbacks. Listing 21-21 presents the internal implementation of the RegisterAsyncPostBackControl method of the ScriptManager. As you can see, this method delegates the responsibility of registering the specified server control to the RegisterAsyncPostBackControl method of the current server-side PageRequestManager instance.
Listing 21-21: The RegisterAsyncPostBackControl Method of the ScriptManager public void RegisterAsyncPostBackControl(Control control) { this.PageRequestManager.RegisterAsyncPostBackControl(control); }
1011
c21.indd 1011
8/20/07 8:37:17 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering LoadRecursive Page
The RegisterAsyncPostBackControl Method of PageRequestManager Listing 21-22 contains the code for the RegisterAsyncPostBackControl method of the PageRequestManager. As you can see, this method takes the following steps. First, it raises an exception if the control being registered is the Page object: if (control is Page) throw new ArgumentException(“CannotRegisterPage”);
The Page cannot be registered as a trigger for asynchronous page postbacks. Next, it raises an exception if the control being registered implements none of the INamingContainer, IPostBackDataHandler, and IPostBackEventHandler interfaces: if ((!(control is INamingContainer) && !(control is IPostBackDataHandler)) && !(control is IPostBackEventHandler)) throw new ArgumentException(“InvalidControlRegistration”);
1012
c21.indd 1012
8/20/07 8:37:17 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Only server controls that implement at least one of the INamingContainer, IPostBackDataHandler, and IPostBackEventHandler interfaces can be registered as triggers for asynchronous page postbacks. For example, the ASP.NET Button server control can be registered as a trigger for asynchronous page postbacks because it implements the IPostBackEventHandler interface. Note that the current server-side PageRequestManager instance maintains two internal collections named _ postBackControls and _asyncPostBackControls, where it stores the server controls registered as triggers for synchronous and asynchronous page postbacks, respectively. As you can see from Listing 21-22, the RegisterAsyncPostBackControl method raises an exception if the server control being registered has already been added to the _postBackControls collections: if ((this._postBackControls != null) && this._ postBackControls.Contains(control)) throw new ArgumentException(“CannotRegisterBothPostBacks”);
The same server control cannot be registered as a trigger for both synchronous and asynchronous page postbacks. Finally, the RegisterAsyncPostBack method adds the server control being registered to the _asyncPostBackControls collection if the collection does not already contain the server control: if (!this._asyncPostBackControls.Contains(control)) this._asyncPostBackControls.Add(control);
The same server control can be registered multiple times as a trigger for asynchronous page postbacks, because the RegisterAsyncPostBack method ensures that the same server control is not added multiple times to the _asyncPostBackControls collection.
Listing 21-22: The RegisterAsyncPostBackControl Method of the PageRequestManager public void RegisterAsyncPostBackControl(Control control) { if (control == null) throw new ArgumentNullException(“control”); if (control is Page) throw new ArgumentException(“CannotRegisterPage”); if (!(control is INamingContainer) && !(control is IPostBackDataHandler) && !(control is IPostBackEventHandler)) throw new ArgumentException(“InvalidControlRegistration”); if ((this._ postBackControls != null) && this._postBackControls.Contains(control)) throw new ArgumentException(“CannotRegisterBothPostBacks”); if (this._asyncPostBackControls == null) this._asyncPostBackControls = new List(); if (!this._asyncPostBackControls.Contains(control)) this._asyncPostBackControls.Add(control); }
1013
c21.indd 1013
8/20/07 8:37:17 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Now let’s update Figure 21-10 with the latest method calls. Recall that the dashed line in Figure 21-10 represents the method calls triggered by the call into the RegisterAsyncPostBackControl method of the ScriptManager. As I mentioned earlier, this method triggers the call into the RegisterAsyncPostBackControl method of the PageRequestManager, which in turn triggers the call into the Add method of the _asyncPostBackControls field, which is a collection of type List. Figure 21-11 extends Figure 21-10 to add these two latest triggered method calls. This wraps up the LoadRecursive life cycle phase. LoadRecursive Page
Figure 21-11 Before diving into the next life cycle phase, that of PreRenderRecursive, let’s take a look at an example that shows you how to develop your own custom UpdatePanelTrigger triggers.
Developing a Custom UpdatePanelTrigger In this section, I’ll develop a custom UpdatePanelTrigger named AsyncMultiPostBackTrigger that is associated with a list of server controls. Listing 21-23 presents the implementation of this trigger. As you can see, it inherits from the UpdatePanelTrigger base class and overrides its HasTriggered and Initialize methods. As you can also see, AsyncMultiPostBackTrigger exposes two collection properties named ControlIDs and EventNames. It is the responsibility of the page developer to assign a commaseparated list of UniqueID property values and event names, respectively, to these two properties. Each
1014
c21.indd 1014
8/20/07 8:37:18 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering value in the former list must be the UniqueID property value of a server control on the current page. There must be a one-to-one correspondence between the UniqueID property value and event names. Note that the AsyncMultiPostBackTrigger exposes a method named FindTargetControls, which repeats the logic used in the FindTargetControl method shown in Listing 21-19 once for each UniqueID property value in the ControlIDs collection. In other words, the FindTargetControls method returns an array that contains references to the associated server controls of the AsyncMultiPostBackTrigger. Also note that the AsyncMultiPostBackTrigger’s implementation of the HasTriggered and Initialize methods repeats the logic used in the HasTriggered and Initialize methods shown in Listing 21-20 once for each server control in the list of associated server controls. As the boldface portion of Listing 21-23 shows, the AsyncMultiPostBackTrigger is considered triggered when the first server control in the list of its associated server control triggers.
Listing 21-23: The AsyncMultiPostBackTrigger Class using System; using System.Configuration; using System.Web; using System.Web.UI; using System.Web.UI.WebControls; using System.Web.UI.HtmlControls; using System.Reflection; using System.ComponentModel; using System.Collections; namespace CustomComponents { public class AsyncMultiPostBackTrigger : UpdatePanelTrigger { protected Control[] FindTargetControls(bool searchNamingContainers) { ArrayList list = new ArrayList(); if (searchNamingContainers) { Control control2 = null; Control control1 = null; foreach (string controlID in this._controlIDs) { control2 = base.Owner; control1 = null; while ((control1 == null) && (control2 != base.Owner.Page)) { control2 = control2.NamingContainer; if (control2 == null) break; control1 = control2.FindControl(controlID); } list.Add(control1); } }
(continued)
1015
c21.indd 1015
8/20/07 8:37:18 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Listing 21-23 (continued) else { foreach (string controlID in this._controlIDs) { list.Add(base.Owner.FindControl(controlID)); } } Control[] controls = new Control[list.Count]; list.CopyTo(controls); return controls; } protected override bool HasTriggered() { if (this.EventNames != null && this.EventNames.Length > 0 && !String.IsNullOrEmpty(this.EventNames[0])) return this._eventHandled; ScriptManager sm = ScriptManager.GetCurrent(this.Owner.Page); foreach (Control associatedControl in this._associatedControls) { if (sm.AsyncPostBackSourceElementID != associatedControl.UniqueID) return sm.AsyncPostBackSourceElementID.StartsWith( associatedControl.UniqueID + “$”, StringComparison.Ordinal); } return true; } protected override void Initialize() { base.Initialize(); this._associatedControls = this.FindTargetControls(true); ScriptManager sm = ScriptManager.GetCurrent(this.Owner.Page); Control associatedControl = null; string eventName = “”; Type associatedControlType; EventInfo eventInfo; Type eventDelegateType; MethodInfo methodInfo; Delegate delegate1; for (int i = 0; i < this._associatedControls.Length; i++) { associatedControl = this._associatedControls[i]; eventName = this.EventNames[i]; sm.RegisterAsyncPostBackControl(associatedControl); associatedControlType = associatedControl.GetType(); eventInfo = associatedControlType.GetEvent(eventName, BindingFlags.Public | BindingFlags.Instance | BindingFlags.IgnoreCase); eventDelegateType = eventInfo.EventHandlerType; methodInfo = eventDelegateType.GetMethod(“Invoke”); delegate1 = Delegate.CreateDelegate(eventDelegateType, this, AsyncMultiPostBackTrigger.EventHandler); eventInfo.AddEventHandler(associatedControl, delegate1); } }
1016
c21.indd 1016
8/20/07 8:37:18 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering public void OnEvent(object sender, EventArgs e) { this._eventHandled = true; } [TypeConverter(typeof(StringArrayConverter))] public string[] ControlIDs { get { return this._controlIDs; } set { this._controlIDs = value; } } private static MethodInfo EventHandler { get { if (AsyncMultiPostBackTrigger._eventHandler == null) AsyncMultiPostBackTrigger._eventHandler = typeof(AsyncMultiPostBackTrigger).GetMethod(“OnEvent”); return AsyncMultiPostBackTrigger._eventHandler; } } [TypeConverter(typeof(StringArrayConverter))] public string[] EventNames { get { return this._eventNames; } set { this._eventNames = value; } } private bool _eventHandled; private Control[] _associatedControls; private static MethodInfo _eventHandler; private string[] _eventNames; private string[] _controlIDs; } }
The following code listing presents a page that uses the AsyncMultiPostBackTrigger. As the boldface portion of this code listing shows, the AsyncMultiPostBackTrigger has two associated server controls, which have the UniqueID property values AsyncPostBackButton1 and AsyncPostBackButton2. void Page_Load(object sender, EventArgs e) { string text = “Refreshed at “ + DateTime.Now.ToString(); UpdatePanel1Label.Text = text; NonPartiallyUpdatableLabel.Text = text; }
(continued)
1017
c21.indd 1017
8/20/07 8:37:19 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering (continued) Untitled Page
Partially Updatable Portion (UpdatePanel1)
Non Partially Updatable Portion
1018
c21.indd 1018
8/20/07 8:37:19 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering
Rendering Once again, keep in mind that we’re following the current Page object as it goes through its life cycle phases to process the first HTTP GET request made to a Web page enabled for partial page rendering. In the previous sections, you saw what happens when the Page enters its PreInit, InitRecursive, LoadRecursive, and PreRenderRecursive life cycle phases. In this section, you’ll see what happens when the Page enters its rendering life cycle phase, where the ProcessRequest method (see Listing 21-1) calls the RenderControl method on the current Page. The current Page inherits the RenderControl from the ASP.NET Control base class. The RenderControl method internally calls the Render method, which in turn calls the RenderChildren method. Listing 21-24 presents the internal implementation of the RenderChildren method of the Control base class. As you can see, the RenderChildren method first calls the GetRenderMethod to return a reference to the RenderMethod delegate registered with the server control, if any. Since this part of the implementation of the RenderChildren method does not apply to the first request, I’ll postpone the discussion of this part of the code to later when we’re discussing asynchronous page postback requests. In other words, only the boldface portion of the RenderChildren method is executed for the first request. As you can see, this portion iterates through the child controls in the Controls collection of the current Page and invokes the RenderControl method on each enumerated child control. Synchronous page postbacks and the first requests always end up rendering all visible server controls on the current page. As you’ll see, asynchronous page postbacks, on the other hand, end up rendering only specified UpdatePanel server controls on the current page.
1019
c21.indd 1019
8/20/07 8:37:19 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Listing 21-24: The RenderChildren Method of the Control Base Class protected internal virtual void RenderChildren(HtmlTextWriter writer) { RenderMethod renderMethod = this.GetRenderMethod(); if (renderMethod != null) { writer.BeginRender(); renderMethod(writer, this); writer.EndRender(); } else if (this.Controls != null) { foreach (Control control in this.Controls) { control.RenderControl(writer); } } }
Therefore, the RenderControl method of the ScriptManager and UpdatePanel server controls is automatically invoked when the current Page enters its rendering life cycle phase. As just discussed, the RenderControl method calls the Render method. Figure 21-12 depicts the method calls that we’ve covered so far. Note that this figure contains two dashed lines. These dashed lines represent the method calls that the Render methods of the ScriptManager and UpdatePanel server controls trigger, as discussed in the following sections.
The Render Method of ScriptManager The Render method of the current ScriptManager server control internally calls the RenderPageRequestManagerScript method on the current server-side PageRequestManager instance. Listing 21-25 presents the implementation of the RenderPageRequestManagerScript method. This method renders the script that instantiates and initializes the client-side PageRequestManager class. The instantiation and initialization of the current client-side PageRequestManager instance involves two steps. First, the _initialize static method must be called on the client-side PageRequestManager class. Second, the _updateControls instance method must be called on the current client-side PageRequestManager instance. As Listing 21-25 shows, the RenderPageRequestManagerScript method takes these steps to render the script that instantiates and initializes the current client-side PageRequestManager instance.
1020
c21.indd 1020
8/20/07 8:37:19 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Rendering Lifecycle Phase Page
Listing 21-25: The RenderPageRequestManagerScript Method of PageRequestManager internal void RenderPageRequestManagerScript(HtmlTextWriter writer) { writer.Write(“\r\n”); writer.Write(“//\r\n\r\n”); }
1021
c21.indd 1021
8/20/07 8:37:20 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering The method begins by rendering the opening tag of the script HTML element that will contain the entire instantiation/initialization script: writer.Write(“\r\n”);
Next, the method renders the part of the script that invokes the _initialize static method on the client-side PageRequestManager class: writer.Write(“// element): writer.Write(“’, document.getElementById(‘”); writer.Write(this._owner.IPage.Form.ClientID); writer.Write(“’));\r\n”);
Next, the RenderPageRequestManagerScript method renders the portion of the script that invokes the _updateControls method on the current client-side PageRequestManager instance. It begins by rendering the method invocation: writer.Write(“Sys.WebForms.PageRequestManager.getInstance()._updateControls([“);
Next, it renders the parameters passed into the _updateControls method. This method takes three parameters. The first is an array that contains the values of the UniqueID properties of all the UpdatePanel server controls on the current page. The RenderPageRequestManagerScript method calls the RenderUpdatePanelIDsFromList static method to return an array that contains these UniqueID property values: PageRequestManager.RenderUpdatePanelIDsFromList(writer, this._allUpdatePanels); writer.Write(“], [“);
The second parameter of the _updateControls method is an array that contains the values of the UniqueID properties of all the server controls that cause asynchronous page postbacks. The RenderPageRequestManagerScript method calls the GetAsyncPostBackControlIDs method to return an array that contains these UniqueID property values: writer.Write(this.GetAsyncPostBackControlIDs(true)); writer.Write(“], [“);
1022
c21.indd 1022
8/20/07 8:37:20 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering The third parameter of the _updateControls method is an array that contains the values of the UniqueID properties of all the server controls that cause synchronous page postbacks. The RenderPageRequestManagerScript method calls the GetPostBackControlIDs method to return an array that contains these UniqueID property values: writer.Write(this.GetPostBackControlIDs(true)); writer.Write(“], “);
The fourth parameter of the _updateControls method is a string that contains the asynchronous postback timeout. Recall that the server-side PageRequestManager class exposes a field named _owner that references the current ScriptManager server control. Also recall that the ScriptManager server control exposes an integer property named AsyncPostBackTimeout that returns the asynchronous postback request timeout: writer.Write(this._owner.AsyncPostBackTimeout.ToString()); writer.WriteLine(“);”); writer.Write(“//]]>\r\n\r\n”);
Here is an example. Suppose the current page contains a ScriptManager server control with UniqueID value of ”ScriptManager1” enclosed in a form element with the id HTML attribute value of ”Form1”, three UpdatePanel server controls with UniqueID values of ”UpdatePanel1”, ”UpdatePanel2”, and ”UpdatePanel3”, two Button server controls that cause synchronous page postbacks, with UniqueID values of ”SyncButton1” and ”SyncButton2”, and finally three Button server controls that cause asynchronous page postbacks, with UniqueID values of ”AsyncButton1”, ”AsyncButton2”, and ”AsyncButton3”. The following code fragment shows the script that the RenderPageRequestManagerScript method will render: //
Before diving into the implementations of the RenderUpdatePanelIDsFromList, GetAsyncPostBackConrolIDs, and GetPostBackControlIDs of the server-side PageRequestManager, let’s update Figure 21-12 with the latest method calls. Figure 21-13 extends Figure 21-12 to add the new method calls. Note that this figure contains three dashed lines. The figure inherits the left dashed line from Figure 21-12. Recall that this dashed line represents the method calls triggered by the call into the Render method of the UpdatePanel. The remaining two dashed lines represent the method calls triggered by the calls into the GetAsynchPostBackControlIDs and GetPostBackControlIDs, which will be discussed in the next sections.
1023
c21.indd 1023
8/20/07 8:37:20 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Rendering Lifecycle Phase Page
The RenderUpdatePanelIDsFromList Method of the Server-Side PageRequestManager Listing 21-26 presents the implementation of the RenderUpdatePanelIDsFromList method of PageRequestManager. This method takes two parameters. The first references an HtmlTextWriter object. The second is a List collection that contains the list of all UpdatePanel server controls on the current page. The main responsibility of this method is to retrieve the values of the UniqueID and ChildrenAsTriggers properties of all UpdatePanel server controls in this collection and render them into the HtmlTextWriter object as a comma-separated list of strings, one for each UpdatePanel server control, each of which contains the following two parts:
❑
The character t if the ChildrenAsTrigger property of the associated UpdatePanel server control is true; the character f otherwise
❑
The UniqueID property value of the associated UpdatePanel server control
1024
c21.indd 1024
8/20/07 8:37:21 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Listing 21-26: The RenderUpdatePanelIDsFromList Method of PageRequestManager private static void RenderUpdatePanelIDsFromList(HtmlTextWriter writer, List list) { if ((list != null) && (list.Count > 0)) { bool flag1 = true; for (int num1 = 0; num1 < list.Count; num1++) { if (list[num1].Visible) { if (!flag1) writer.Write(“,”); flag1 = false; writer.Write(“’”); writer.Write(list[num1].ChildrenAsTriggers ? “t” : “f”); writer.Write(list[num1].UniqueID); writer.Write(“’”); } } } }
The GetAsyncPostBackControlIDs Method of the Server-Side PageRequestManager Listing 21-27 presents the implementation of the GetAsyncPostBackControlIDs method of the PageRequestManager. As you can see, this method simply delegates to the GetControlIDsFromList method, passing in the _asyncPostBackControls collection. Recall that the PageRequestManager server class features a private collection named _asyncPostBackControls that contains all the server controls that cause asynchronous page postbacks.
Listing 21-27: The GetAsyncPostBackControlIDs Method of the PageRequestManager private string GetAsyncPostBackControlIDs(bool includeQuotes) { return PageRequestManager.GetControlIDsFromList(this._asyncPostBackControls, includeQuotes); }
The GetControlIDsFromList Method of the Server-Side PageRequestManager Listing 21-28 contains the code for the GetControlIDsFromList method of the PageRequestManager. This method takes a List collection that contains a list of server controls. The main responsibility of this method is to return a comma-separated list of strings, each of which contains the UniqueID property value of a server control in the List collection. Note that this method takes a second Boolean argument that specifies whether these UniqueID property values must be rendered in quotes.
1025
c21.indd 1025
8/20/07 8:37:21 PM
Chapter 21: Page Life Cycle and Asynchronous Partial Page Rendering Listing 21-28: The GetControlIDsFromList Method of the PageRequestManager private static string GetControlIDsFromList(List list, bool includeQuotes) { if ((list == null) || (list.Count //
In this chapter we’ll move on to the client side, where the server response — including this script block — arrives. As you can see, this script block automatically invokes the _intialize and _updateControls methods of the client-side PageRequestManager. Figure 22-1 depicts the instantiation and initialization of the current PageRequestManager instance. As you can see, this figure diplays the two method calls I’ve discussed. Note that this figure contains two dashed lines. The top one represents the method calls triggered by the call into the _initialize method of the PageRequestManager. The bottom one represents the method calls triggered by the call into the _updateControls method. I’ll discuss these two sets of triggered method calls in the following sections, and update this figure with new method calls as we move through the chapter.
Instantiating and Initializing the Client-Side PageRequestManager Listing 22-2 presents the internal implementation of the _initialize static method of the client-side PageRequestManager.
1034
c22.indd 1034
8/20/07 8:38:08 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Listing 22-2: The _initialize Static Method of the PageRequestManager Client Class Sys.WebForms.PageRequestManager._initialize = function Sys$WebForms$PageRequestManager$_initialize(scriptManagerID, formElement) { Sys.WebForms.PageRequestManager._ensureSinglePageRequestManagerInstance(); Sys.WebForms.PageRequestManager._createPageRequestManagerInstance(); Sys.WebForms.PageRequestManager._initializePageRequestManagerInstance( scriptManagerID, formElement); }
Note that this method takes two parameters. The first is a string that contains the value of the UniqueID property of the current ScriptManager instance; the second references the form HTML element that contains the current ScriptManager instance. This method first calls the _ensureSinglePageRequestManagerInstance static method on the PageRequestManager to ensure that the current page contains a single PageRequestManager instance. As the following code listing shows, _ensureSinglePageRequestManagerInstance calls the getInstance static method on the client-side PageRequestManager to check whether the current page already contains an instance of the client-side PageRequestManager class. If so, it raises an exception, because every page can contain only one instance of this class: Sys.WebForms.PageRequestManager._ensureSinglePageRequestManagerInstance = function Sys$WebForms$PageRequestManager$_ ensureSinglePageRequestManagerInstance() { if (Sys.WebForms.PageRequestManager.getInstance()) throw Error.invalidOperation(Sys.WebForms.Res.PRM_CannotRegisterTwice); }
Next, _initialize calls the _createPageRequestManagerInstance static method on the PageRequestManager to create a new instance of the PageRequestManager. As the following code listing shows, this method instantiates an instance of the client-side PageRequestManager class and assigns it to the _instance static field of this class: Sys.WebForms.PageRequestManager._createPageRequestManagerInstance = function Sys$WebForms$PageRequestManager$_createPageRequestManagerInstance() { Sys.WebForms.PageRequestManager._instance = new Sys.WebForms.PageRequestManager(); }
Finally, the _initialize method calls the _initializePageRequestManagerInstance static method to initialize the newly created PageRequestManager instance. As the following code listing shows, this method calls the _initializeInternal private instance method on the newly instantiated client-side PageRequestManager, passing in the value of the UniqueID property of the ScriptManager server control and the reference to the form HTML element of the current page:
1035
c22.indd 1035
8/20/07 8:38:08 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Sys.WebForms.PageRequestManager._initializePageRequestManagerInstance = function Sys$WebForms$PageRequestManager$_createPageRequestManagerInstance( scriptManagerID, formElement) { Sys.WebForms.PageRequestManager.getInstance()._initializeInternal( scriptManagerID, formElement); }
Figure 22-2 updates Figure 22-1 to add the method calls triggered by the _initialize static method of the PageRequestManager. PageRequestManager Instantiation/Initialization PageRequestManager _initialize(scriptManagerUniqueID, formElement) _ensureSinglePageRequestManagerInstance ( ) getInstance ( ) _createPageRequestManagerInstance ( ) _initializePageRequestManagerInstance (scriptManagerUniqueID, formElement) _initializeInternal (scriptManagerUniqueID, formElement)
The getInstance Method of the Client-Side PageRequestManager Listing 22-3 presents the internal implementation of the getInstance static method of the client-side PageRequestManager class. As you can see, this method returns the value of the _instance static field of the PageRequestManager client class. If you need to access this instance from your client-side code, call the getInstance static method on the client-side PageRequestManager class to return a reference to the current client-side PageRequestManager instance.
1036
c22.indd 1036
8/20/07 8:38:08 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Listing 22-3: The getInstance Static Method of the PageRequestManager Client Class Sys.WebForms.PageRequestManager.getInstance = function Sys$WebForms$PageRequestManager$getInstance() { /// return Sys.WebForms.PageRequestManager._instance || null; }
The Constructor of the Client-Side PageRequestManager Class Listing 22-4 presents the implementation of the constructor of the client-side PageRequestManager class. As this code listing shows, this class contains the following private fields:
❑
_form: This field references the form DOM element associated with the HtmlForm server control. Keep in mind that an ASP.NET page may have more than one instance of the HTML element. However, only one of these HTML elements can have the runat=”server” attribute. The ASP.NET framework represents this HTML element with an instance of the HtmlForm server control. The _form field of the client-side PageRequestManager references the HTML element that contains the runat=”server” attribute.
❑
_updatePanelIDs: This field is an array that contains the values of the UniqueID properties of all UpdatePanel server controls on the current page after update.
❑
_updatePanelClientIDs: This field is an array that contains the values of the ClientID properties of all UpdatePanel server controls on the current page after update.
❑
_oldUpdatePanelIDs: This field is an array that contains the values of the UniqueID properties of all UpdatePanel server controls on the current page before update.
❑
_childUpdatePanelIDs: This field is an array that contains the values of the UniqueID properties of all child UpdatePanel server controls after update.
❑
_panelsToRefreshIDs: This field is an array that contains the values of the UniqueID properties of all parent UpdatePanel server controls that need refreshing.
❑
_updatePanelHasChildrenAsTriggers: This field is an array that contains the values of the UniqueID properties of all UpdatePanel server controls on the current page whose ChildrenAsTriggers Boolean property have been set to true.
❑
_asyncPostBackControlIDs: This field is an array that contains the values of the UniqueID properties of all server controls on the current page that cause asynchronous page postbacks.
❑
_asyncPostBackControlClientIDs: This field is an array that contains the values of the ClientID properties of all server controls on the current page that cause asynchronous page
postbacks.
❑
_postBackControlIDs: This field is an array that contains the values of the UniqueID
properties of all server controls on the current page that cause synchronous page postbacks.
❑
_postBackControlClientIDs: This field is an array that contains the values of the ClientID
properties of all server controls on the current page that cause synchronous page postbacks.
1037
c22.indd 1037
8/20/07 8:38:08 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager ❑
_scriptManagerID: This field contains the value of the UniqueID property of the current ScriptManager server control.
❑
_pageLoadedHandler: This field references the delegate registered as an event handler for the load event of the window object.
❑
_additionalInput: This field contains additional optional information.
❑
_onsubmit: This field references the original onsubmit method of the form DOM element that the _form field references. As you’ll see later, the client-side PageRequestManager instance
replaces this method with another method when it needs to make an asynchronous page postback to the server. Before replacing this method, the current client-side PageRequestMananger instance stores the function in the _onsubmit field so it can be used later when the page needs to make a synchronous page postback.
❑
_onSubmitStatements: This field is an array that contains dynamically added form submit
statements.
❑
* _originalDoPostBack: This field references the _doPostBack JavaScript function that performs a regular synchronous page postback to the server. As you’ll see later, the client-side PageRequestManager instance replaces this JavaScript function with the one that performs an asynchronous page postback to the server when PageRequestManager needs to make an asynchronous postback request. Before replacing the _doPostBack JavaScript function, the current client-side PageRequestManager instance stores the function in the _originalDoPostBack field so it can be used later when the page needs to make a synchronous page postback.
❑
_postBackSettings: This field references an object literal with three name/value pairs
that describe the postback settings for the postback request that the current client-side PageRequestManager instance is about to make to the server. The name part of the first name/ value pair is the keyword async, and the value part is a Boolean value that specifies whether
the current postback request is asynchronous. The name part of the second name/value pair is the keyword panelID, and the value part is a string that contains the value of the UniqueID property of the UpdatePanel server control whose trigger triggered the current asynchronous page postback. The name part of the third name/value pair is the keyword sourceElement, and the value part references the DOM element that triggered the asynchronous page postback.
❑
_request: This field references the WebRequest object that represents the current asynchronous
page postback request.
❑
_onFormSubmitHandler: This field references the delegate that represents the _onFormSubmit method of the current PageRequestManager instance. As you’ll see later, this instance registers this delegate as an event handler for the submit event of the form DOM element referenced by the _form field.
❑
_onFormElementClickHandler: This field references the delegate that represents the _onFormElementClick method of the current PageRequestManager instance. As you’ll see later, this instance registers this delegate as an event handler for the click event of the form DOM element referenced by the _form field.
❑
_onWindowUnloadHandler: This field references the delegate that represents the _onWindowUnload method of the current PageRequestManager instance. As you’ll see later, this instance registers this delegate as an event handler for the unload event of the form DOM element referenced by the _form field.
❑
_asyncPostBackTimeout: This field is a string that contains the asynchronous page postback
request timeout.
1038
c22.indd 1038
8/20/07 8:38:09 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager ❑
_controlIDToFocus: This field is a string that contains the value of the UniqueID property of
the server control that has the mouse focus.
❑
_scrollPosition: This field references an object literal with two name/value pairs that describe the current position of the scroll. The name part of the first name/value pair is the keyword x, and the value part is an integer that specifies the x coordinate of the scroll bar. The name part of the second name/value pair is the keyword y, and the value part is an integer that specifies the y coordinate of the scroll bar.
❑
_dataItems: This field references a dictionary of data items.
❑
_response: This field references the WebRequestExecutor object responsible for executing the current asynchronous page postback request.
❑
_processingRequest: This field is a Boolean value that specifies whether the current PageRequestManager is processing the server response.
❑
_scriptDisposes: This field references a dictionary of script disposes.
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager
The _initializeInternal Method of the Client-Side PageRequestManager Understanding the internal implementation of the _initializeInternal method of the current PageRequestManager instance requires a good understanding of the two common types of page postback. Therefore, before diving into the implementation of this method, we need to study these two different types. The first relies on the Submit button. As you know, when the user clicks the Submit button, the form DOM element raises the submit event and consequently invokes the onsubmit event handler. If the onsubmit event handler does not return false, the browser takes these steps:
1. 2.
Collects the names and values of the form elements.
3. 4. 5. 6.
Creates an HTTP POST request.
Generates a list of items separated by the & character, where each item contains the name and value of a form element. Each item consists of two parts separated by the equals sign (=), the first containing the name of the form element and the second containing the value.
Adds the list of items to the body of the request. Sets the request headers, such as Content-Type, Content-Length, Host, etc. Submits the request to the server synchronously.
The onsubmit event handler normally validates the values of the form elements and returns false to cancel the form submission if the validation fails. The main problem with the first type of page postback is its strict reliance on the Submit button for form submission. There are times when the form must be submitted via DOM elements other than the Submit button. For example, you may want the form submission to occur when the user selects an item from a certain HTML element. This is where the second type of page postback comes into play. This type relies on the __doPostBack JavaScript function. The ASP.NET server controls, such as the DropDownList, register this JavaScript function as an event handler for one of their events. For example, the DropDownList server control registers the _doPostBack JavaScript function as event handler for the onchange event of the HTML element associated with the server control if the AutoPostBack property of the server control is set to true. Listing 22-5 contains the definition of the _doPostBack JavaScript function. Since this JavaScript function is a global one, it is automatically considered as a method on the window object. As you can see, _doPostBack takes two arguments. The first is the value of the UniqueID property of the server control that caused the postback. For example, in the case of the DropDownList server control, this will be the value of the UniqueID property of the DropDownList control itself. The second argument is optional. In the case of the DropDownList server control, this will be the value of the value property of the selected element of the element associated with the server control. As you can see from Listing 22-5, the _doPostBack JavaScript function takes the following steps. First, it invokes the onsubmit event handler. Recall that this event handler normally validates the values of the form elements and returns false if the validation fails. As Listing 22-5 shows, if the onsubmit event handler does not return false, the _doPostBack JavaScript function assigns its first parameter to the value property of a hidden field named __EVENTTARGET and its second parameter to the value
1040
c22.indd 1040
8/20/07 8:38:10 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager property of a hidden field named __EVENTARGUMENT. For example, in the case of the DropDownList server control, the _doPostBack JavaScript function assigns the UniqueID property value of the server control to the value property of the __EVENTTARGET hidden field and the value of the value property of the selected option subelement of the select element associated with the server control to the value property of the __EVENTARGUMENT hidden field. theForm.__EVENTTARGET.value = eventTarget; theForm.__EVENTARGUMENT.value = eventArgument;
Finally, the _doPostBack JavaScript function invokes the submit method on the form DOM element to submit the values of the form elements to the server. When the submit method is invoked, under the hood, the browser takes these steps:
1. 2.
Collects the names and values of the form elements.
3. 4. 5. 6.
Creates an HTTP POST request.
Generates a list of items separated by the & character, where each item contains the name and value of a form element. Each item consists of two parts separated by the equals sign (=), the first containing the name of the form element and the second containing the value.
Adds to the body of the request the list of items shown in Step 2. Sets the request headers, such as Content-Type, Content-Length, Host, etc. Submits the request to the server synchronously.
Note that the preceding six steps are the same ones the browser takes for the first type of page postback — that is, the page postback via the Submit button. In other words, both the page postback via the Submit button and the page postback via the _doPostBack JavaScript function rely on the browser to take these steps.
Listing 22-5: The Standard __doPostBack JavaScript Function
Both the page postback via the Submit button and page postback via the _doPostBack JavaScript function suffer from the following fundamental shortcomings:
1041
c22.indd 1041
8/20/07 8:38:10 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager ❑
The browser submits the request to the server synchronously. A synchronous request is blocking, meaning that the end user cannot interact with the page until the server response arrives. This dramatically degrades the responsiveness, performance, and usability of a Web application that relies heavily on normal synchronous page postbacks.
❑
In both types of page postbacks, when the server response finally arrives, the entire page reloads even though only a small portion of the page requires refreshing. This also dramatically degrades the responsiveness, performance, and usability of a graphic-heavy Web page, which takes a lot of time to re-render.
As you’ll see in this chapter, the current PageRequestManager instance resolves both of these problems, as follows:
❑
Unlike page postback via the Submit button or the _doPostBack JavaScript function, it does not rely on the browser’s default synchronous form submission. Instead, the current PageRequestManager instance uses the ASP.NET AJAX client-server communication layer discussed in previous chapters to make asynchronous page postback requests to the server.
❑
Unlike page postback via the Submit button or the _doPostBack JavaScript function, it does not rely on the browser’s default rendering mechanism, which re-renders the entire page when the server response arrives. Instead, the current PageRequestManager instance uses the ASP.NET AJAX client-side framework to refresh only those parts of the page that need refreshing.
Now that you have a good understanding of the two main types of page postbacks and their shortcomings, you’re ready to dive into the internal implementation of the _initializeInternal method of the PageRequestManager, as shown in Listing 22-6.
Listing 22-6: The _initializeInternal Intance Method of the PageRequestManager Client Class function Sys$WebForms$PageRequestManager$_initializeInternal(scriptManagerID, formElement) { this._scriptManagerID = scriptManagerID; this._form = formElement; this._detachAndStoreOriginalFormOnSubmit(); this._registerHandlerForFormSubmitEvent (); this._detachAndStoreOriginalDoPostBack(); this._attachNewDoPostBack(); this._registerHandlerForWindowLoadEvent(); this._registerHandlerForFormClickEvent(); this._registerHandlerForWindowUnloadEvent(); this._storeOriginalFormAction(); }
As you can see, this method takes two arguments. The first is a string that contains the value of the UniqueID property of the ScriptManager server control. The second references the form DOM element of the current page. The method assigns the following two parameters to the _scriptManagerID and _form private fields of the current PageRequestManager instance: this._scriptManagerID = scriptManagerID; this._form = formElement;
1042
c22.indd 1042
8/20/07 8:38:10 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Next, the _initializeInternal method calls the _detachAndStoreOriginalFormOnSubmit method shown in the following code listing. As you can see, this method detaches the onsubmit method from the form DOM element and stores it in a local field named _onsubmit for future reference: function Sys$WebForms$PageRequestManager$_detachAndStoreOriginalFormOnSubmit() { this._onsubmit = this._form.onsubmit; this._form.onsubmit = null; }
Then the _initializeInternal method calls the _registerHandlerForFormSubmitEvent method shown in the following code listing. As you can see, this method first creates a delegate that represents the _onFormSubmit method of the current PageRequestManager instance, and then registers this delegate as an event handler for the submit event of the form element: function Sys$WebForms$PageRequestManager$_registerHandlerForFormSubmitEvent () { this._onFormSubmitHandler = Function.createDelegate(this, this._onFormSubmit); Sys.UI.DomEvent.addHandler(this._form, ‘submit’, this._onFormSubmitHandler); }
Recall that page postback via the Submit button causes the form DOM element to fire its submit event. Since the current PageRequestManager instance has registered the _onFormSubmitHandler delegate for this event, this delegate and consequently the _onFormSubmit method of the current PageRequestManager instance are automatically invoked. This allows the current PageRequestManager instance to take complete control over the first type of page postback mechanism before the page is actually posted back to the server. As you’ll see later, the _onFormSubmit method of the current PageRequestManager instance will first determine whether the form submission must be done asynchronously. If so, it will bypass the browser’s default synchronous form submission and use the ASP.NET AJAX client-server communication layer discussed in previous chapters to make an asynchronous page postback to the server. If the _onFormSubmit method of the current PageRequestManager instance comes to the conclusion that the form must be submitted synchronously, the method gets out of the way and allows the browser to take over the form submission and submit the form synchronously. Now back to the discussion of the implementation of the _initializeInternal method of the PageRequestManager. Next, this method calls the _detachAndStoreOriginalDoPostBack method shown in the following code listing. As you can see, this method detaches the _doPostBack JavaScript function shown in Listing 22-5 from the window object and stores it in the _originalDoPostBack field of the current PageRequestManager instance for future reference: function Sys$WebForms$PageRequestManager$_detachAndStoreOriginalDoPostBack() { this._originalDoPostBack = window.__doPostBack; window.__doPostBack = null; }
The _initializeInternal method then calls the _attachNewDoPostBack method shown in the following code listing. As you can see, this method first creates a delegate that represents the _doPostBack method of the current PageRequestManager instance and then attaches this method to the window object as its _doPostBack method:
1043
c22.indd 1043
8/20/07 8:38:11 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager function Sys$WebForms$PageRequestManager$_attachNewDoPostBack() { window.__doPostBack = Function.createDelegate(this, this._doPostBack); }
Recall that the second type of page postback invokes the _doPostBack method of the window object to submit the form to the server. Since the current PageRequestManager instance has replaced the original _doPostBack method (that is, the one shown in Listing 22-5) with the delegate that represents the _doPostBack method of the current PageRequestManager instance, when a server control such as DropDownList calls the _doPostBack method of the window object, this delegate and consequently the _doPostBack method of the current PageRequestManager instance will be called instead of the original _doPostBack method shown in Listing 22-5. This allows the current PageRequestManager instance to take complete control of the second type of page postback mechanism before the page is actually posted back to the server. As you’ll see later in this chapter, the _doPostBack method of the current PageRequestManager instance will first determine whether the form submission must be done asynchronously. If so, it will bypass the browser’s default synchronous form submission and use the ASP. NET AJAX client-server communication layer discussed in previous chapters to make an asynchronous page postback to the server. If the _doPostBack method of the current PageRequestManager instance comes to the conclusion that the form must be submitted synchronously, the method gets out of the way and allows the browser to take over the form submission and submit the form synchronously. Now back to the discussion of the implementation of the _initializeInternal method. Next, this method calls the _registerHandlerForWindowLoadEvent method shown in the following code listing. As you can see, this method first creates a delegate that represents the _pageLoadedInitialLoad method of the current PageRequestManager instance, and then registers this delegate as an event handler for the load event of the window object. Therefore, when the window raises its load event, this delegate and consequently the _pageLoadedInitialLoad method of the current PageRequestManager instance are invoked: function Sys$WebForms$PageRequestManager$_registerHandlerForWindowLoadEvent() { this._pageLoadedHandler = Function.createDelegate(this, this._pageLoadedInitialLoad); Sys.UI.DomEvent.addHandler(window, ‘load’, this._pageLoadedHandler); }
Next, the _initializeInternal method calls the _registerHandlerFormClickEvent method shown in the following code listing. As you can see, this method first creates a delegate that represents the _onFormElementClick method of the current PageRequestManager instance, and then registers this delegate as an event handler for the click event of the form element: function Sys$WebForms$PageRequestManager$_registerHandlerForFormClickEvent() { this._onFormElementClickHandler = Function.createDelegate(this, this._onFormElementClick); Sys.UI.DomEvent.addHandler(this._form, ‘click’, this._onFormElementClickHandler); }
Then the _initializeInternal method calls the _registerHandlerForWindowUnloadEvent method shown in the following code listing. As you can see, this method first creates a delegate that represents the _onWindowUnload method of the current PageRequestManager instance, and then registers this delegate as an event handler for the unload event of the window object:
1044
c22.indd 1044
8/20/07 8:38:11 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager function Sys$WebForms$PageRequestManager$_registerHandlerForWindowUnloadEvent() { this._onWindowUnloadHandler = Function.createDelegate(this, this._onWindowUnload); Sys.UI.DomEvent.addHandler(window, ‘unload’, this._onWindowUnloadHandler); }
Finally, the method calls the _storeOriginalFormAction method shown in the following code listing. As you can see, this method stores the value of the action property of the form DOM element in a custom property on the form named _initialAction for future reference. As you’ll see later, the current PageRequestManager instance uses the initial action value to determine whether a given request is a cross-page postback. function Sys$WebForms$PageRequestManager$_storeOriginalFormAction() { this._form._initialAction = this._form.action; }
Figure 22-3 updates Figure 22-2 with the method calls that the _initializeInternal method triggers. Note that Figure 22-3 inherits the bottom dashed line from Figure 22-2. Recall that this dashed line represents the method calls triggered by the call into the _updateControls method. PageRequestManager Instantiation/Initialization PageRequestManager _initialize(scriptManagerUniqueID, formElement) _ensureSinglePageRequestManagerInstance ( ) getInstance ( ) _createPageRequestManagerInstance ( ) _initializePageRequestManagerInstance (scriptManagerUniqueID, formElement) _initializeInternal (scriptManagerUniqueID, formElement) _detachAndStoreOriginalFormOnSubmit ( ) _registerHandlerForFormSubmitEvent ( ) _detachAndStoreOriginalDoPostBack ( ) _attachNewDoPostBack ( ) _registerHandlerForWindowLoadEvent ( ) _registerHandlerForFormClickEvent ( ) _registerHandlerForWindowUnloadEvent ( ) _updateControls([…], […], […], asyncPostBackTimeout)
_storeOrigianlFormAction ( )
Figure 22-3
1045
c22.indd 1045
8/20/07 8:38:11 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager
_updateControls Listing 22-7 presents the internal implementation of the _updateControls method of the PageRequestManager. This method takes the following four parameters:
❑
updatePanelIDs: This parameter is an array that contains the values of the UniqueID properties of all the UpdatePanel server controls on the current page.
❑
asyncPostBackControlIDs: This parameter is an array that contains the values of the UniqueID properties of all the server controls on the current page that cause asynchronous page
postbacks.
❑
postBackControlIDs: This parameter is an array that contains the values of the UniqueID properties of all the server controls on the current page that cause synchronous page postbacks.
❑
asyncPostBackTimeout: This parameter is a string that contains the asynchronous page post-
back request timeout.
Listing 22-7: The _updateControls Method of the PageRequestManager function Sys$WebForms$PageRequestManager$_updateControls(updatePanelIDs, asyncPostBackControlIDs, postBackControlIDs, asyncPostBackTimeout) { if (updatePanelIDs) { this._updatePanelIDs = new Array(updatePanelIDs.length); this._updatePanelClientIDs = new Array(updatePanelIDs.length); this._updatePanelHasChildrenAsTriggers = new Array(updatePanelIDs.length); for (var i = 0; i < updatePanelIDs.length; i++) { this._updatePanelHasChildrenAsTriggers[i] = (updatePanelIDs[i].charAt(0) === ‘t’); this._updatePanelIDs[i] = updatePanelIDs[i].substr(1); this._updatePanelClientIDs[i] = this._uniqueIDToClientID(updatePanelIDs[i].substr(1)); } this._asyncPostBackTimeout = asyncPostBackTimeout * 1000; } else { this._updatePanelIDs = []; this._updatePanelClientIDs = []; this._updatePanelHasChildrenAsTriggers = []; this._asyncPostBackTimeout = 0; } this._asyncPostBackControlIDs = []; this._asyncPostBackControlClientIDs = [];
1046
c22.indd 1046
8/20/07 8:38:12 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager for (var i = 0; i < asyncPostBackControlIDs.length; i++) { Array.add(this._asyncPostBackControlIDs, asyncPostBackControlIDs[i]); Array.add(this._asyncPostBackControlClientIDs, this._uniqueIDToClientID(asyncPostBackControlIDs[i])); } this._postBackControlIDs = []; this._postBackControlClientIDs = []; for (var i = 0; i < postBackControlIDs.length; i++) { Array.add(this._postBackControlIDs, postBackControlIDs [i]); Array.add(this._postBackControlClientIDs, this._uniqueIDToClientID(postBackControlIDs [i])); } }
The _updateControls method takes the following steps. First, it instantiates the _updatePanelIDs, _updatePanelClientIDs, and _updatePanelHasChildrenAsTriggers array fields of the current PageRequestManager instance: this._updatePanelIDs = new Array(updatePanelIDs.length); this._updatePanelClientIDs = new Array(updatePanelIDs.length); this._updatePanelHasChildrenAsTriggers = new Array(updatePanelIDs.length);
Next, it iterates through the UniqueID property values in the updatePanelIDs parameter and takes the following actions for each enumerated UniqueID property value. (Keep in mind that this value consists of two substrings, the first containing the character t or f, and the second containing the actual UniqueID property value):
❑
As mentioned, the current PageRequestManager instance contains a private array field named _updatePanelIDs that contains the UniqueID property values of all the UpdatePanel server controls on the current page. The _updateControls method retrieves the second substring of the enumerated value and adds it to the _updatePanelIDs array: this._updatePanelIDs[i] = updatePanelIDs[i].substr(1);
❑
The current PageRequestManager instance also contains a private array field named _updatePanelClientIDs that contains the ClientID property values of all the UpdatePanel server controls on the current page. The _updateControls method calls the _uniqueIDToClientID method to return the ClientID property value associated with the UniqueID property value and adds this ClientID property value to the _updatePanelClientIDs array:
The current PageRequestManager instance contains a private Boolean array field named _updatePanelHasChildrenAsTriggers that contains one Boolean value for each UpdatePanel server control on the page, which specifies whether its child server controls trigger partial page updates. The _updateControls method retrieves the first substring of the enumerated value. If this substring contains the character t, asynchronous updates of the server control are triggered by the child controls of the UpdatePanel server control whose UniqueID property is given by the second substring, and the _updateControls method adds the Boolean value of true to the _updatePanelHasChildrenAsTriggers collection. Otherwise it adds false.
The current PageRequestManager instance also contains an integer field named _asyncPostBackTimeout that specifies the timeout (in seconds) for all asynchronous page postback requests. The _updateControls method converts to seconds the value passed into it as its last parameter, and assigns the value to this field: this._asyncPostBackTimeout = asyncPostBackTimeout * 1000;
Next, the _updateControls method iterates through the UniqueID property values in the asyncPostBackControlIDs array and takes these actions for each value:
❑
The current PageRequestManager instance contains a private array field named _asyncPostBackControlIDs that contains the UniqueID property values of all the server controls on the current page that trigger asynchronous page postbacks. The _updateControls method adds the enumerated UniqueID property value to this array field: Array.add(this._asyncPostBackControlIDs, asyncPostBackControlIDs[i]);
❑
The current PageRequestManager instance contains a private array field named _asyncPostBackControlClientIDs that contains the ClientID property values of all the server controls on the current page that trigger asynchronous page postbacks. The _updateControls method first calls the _uniqueIDToClientID method to return the ClientID property value associated with the enumerated UniqueID property value, and then adds this return value to this array field: Array.add(this._asyncPostBackControlClientIDs, this._uniqueIDToClientID(asyncPostBackControlIDs[i]));
Next, the _updateControls method iterates through the UniqueID property values in the postBackControlIDs array and takes these actions for each value:
❑
The current PageRequestManager instance contains a private array field named _postBackControlIDs that contains the UniqueID property values of all the server controls on the current page that trigger synchronous page postbacks. The _updateControls method adds the enumerated UniqueID property value to this array field: Array.add(this._postBackControlIDs, postBackControlIDs[i]);
❑
The current PageRequestManager instance contains a private array field named _postBackControlClientIDs that contains the ClientID property values of all the server controls on the current page that trigger asynchronous page postbacks. The _updateControls method first calls the _uniqueIDToClientID method to return the ClientID property value associated with the enumerated UniqueID property value, and then adds this return value to this array field: Array.add(this._postBackControlClientIDs, this._uniqueIDToClientID(postBackControlIDs[i]));
As Listing 22-8 shows, the _uniqueIDToClientID method takes an UniqueID value as its argument and replaces all the dollar signs ($) with the underscore character (_).
1048
c22.indd 1048
8/20/07 8:38:12 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager The UniqueID and ClientID property values of an ASP.NET server control are read-only, which means that only the ASP.NET can set their values. The UniqueID property value of a server control is a string that consists of two substrings separated by the dollar sign ($), the first containing the value of the ID property of the server control and the second containing the value of the UniqueID property of the parent of the server control. The ClientID property value of a server control is a string that consists of two substrings separated by the underscore character (_), the first containing the value of the ID property of the server control and the second containing the value of the ClientID property of the parent of the server control. As you can see, the only difference between the UniqueID and the ClientID property values of a server control is the separator. That is why the _uniqueIDToClientID method replaces the dollar signs with the underscore characters to arrive at the ClientID property value.
Listing 22-8: The _uniqueIDToClientID Method of the PageRequestManager function Sys$WebForms$PageRequestManager$_uniqueIDToClientID(uniqueID) { // Convert unique IDs to client IDs by replacing all ‘$’ with ‘_’ return uniqueID.replace(/\$/g, ‘_’); }
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager
The _pageLoadedInitialLoad Method of the Client-Side PageRequestManager When the current page is finally loaded, the window object raises the load event and calls the _pageLoadedHandler delegate, which in turn calls the _pageLoadedInitialLoad instance method of the current client-side PageRequestManager instance, as shown in Listing 22-9.
Listing 22-9: The _pageLoadedInitialLoad Method of the PageRequestManager Client Class function Sys$WebForms$PageRequestManager$_pageLoadedInitialLoad(evt) { this._pageLoaded(true); }
As you can see, the _pageLoadedInitialLoad method calls the _pageLoaded method of the current client-side PageRequestManager instance, passing in true as its argument.
The _pageLoaded Method of the Client-Side PageRequestManager Listing 22-10 presents the internal implementation of the _pageLoaded method of the client-side PageRequestManager instance.
Listing 22-10: The _pageLoaded Method of the PageRequestManager Client Class function Sys$WebForms$PageRequestManager$_pageLoaded(initialLoad) { var handler = this._get_eventHandlerList().getHandler(“pageLoaded”); if (handler) handler(this, this._getPageLoadedEventArgs(initialLoad)); if (!initialLoad) { // If this isn’t the first page load (i.e. we are doing an async postback), we // need to re-raise the Application’s load event. Sys.Application.raiseLoad(); } }
This method first calls the _get_eventHandlerList method to return a reference to the EventHandlerList object that contains all the event handlers registered for the events of the current client-side PageRequestManager instance, and then calls the getHandler method on the EventHandlerList to return a reference to the JavaScript function whose invocation automatically
1050
c22.indd 1050
8/20/07 8:38:13 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager invokes all the event handlers registered for the pageLoaded event of the current client-side PageRequestManager instance. I’ll discuss this event later in the chapter. var handler = this._get_eventHandlerList().getHandler(“pageLoaded”);
Next, the _pageLoaded method calls the _getPageLoadedEventArgs method to create and return a PageLoadedEventArgs object. As you’ll see later, the PageLoadedEventArgs class is the event data class for the pageLoaded event of the client-side PageRequestManager instance. var pageLoadedEventArgs = this._getPageLoadedEventArgs(initialLoad);
Then it calls the JavaScript function, passing in a reference to the current client-side PageRequestManager instance and a reference to the PageLoadedEventArgs instance. This JavaScript function in turn calls all the event handlers registered for the pageLoaded event of the current client-side PageRequestManager instance, passing in the same two references. if (handler) handler(this, this._getPageLoadedEventArgs(initialLoad));
This enables you to perform application-specific tasks by registering an event handler for the pageLoaded event of the current PageRequestManager instance. Figure 22-5 updates Figure 22-4 with the latest method calls. This wraps up our discussion of the instantiation/initialization process of the current client-side PageRequestManager instance. Keep in mind that this process occurs only for the first request and subsequent normal synchronous page postback requests. In other words, it does not occur for subsequent asynchronous page postback requests. In summary, the previous chapter followed the first request from the time it arrived in ASP.NET to the time the server response text, including the PageRequestManager instantiation/initialization script block — such as the one shown in Listing 22-1 — was sent back to the client. The previous sections of this chapter then followed this server response text from the time it arrived on the client side to the time the instantiation and initialization of the current PageRequestManager instance were completed. Now the current PageRequestManager instance is sitting there waiting for the first or second type of page postback to occur. Recall that there are two types of page postbacks, via the Submit button and via the _doPostBack method of the window object. As we discussed earlier, as soon as the first type of page postback occurs, the _onFormSubmit method of the current PageRequestManager instance will intercept it before the page is actually posted back to the server; and as soon as the second type of page postback occurs, the _doPostBack method of the current PageRequestManager instance will intercept it before the page is actually posted back to the server. Both the _onFormSubmit and _doPostBack methods of the current PageRequestManager instance will first determine whether the page postback must be done asynchronously. If so, both methods bypass the browser’s default synchronous form submission and use the ASP.NET AJAX client-server communication layer (discussed in previous chapters) to submit the form asynchronously. If these methods determine that the page postback must be done synchronously, they simply get out of the way and let the browser’s default synchronous form submission take over and submit the form synchronously.
The page Loaded Event The previous sections followed the current client-side PageRequestManager instance through its instantiation/initialization life cycle phases. As you can see from Figure 22-5, the current client-side PageRequestManager instance fires its pageLoaded event at the end of its instantiation/initialization phase to enable you to perform application-specific tasks that must be performed right after the current client-side PageRequestManager instance is instantiated and initialized. The client-side PageRequestManager class uses the standard ASP.NET AJAX event-implementation pattern to implement its pageLoaded event as follows:
1.
The PageRequestManager class defines a collection property of type EventHandlerList to store all the event handlers registered for the events of the current client-side PageRequestManager instance.
2.
It defines a getter method that returns a reference to this EventHandlerList object:
1052
c22.indd 1052
8/20/07 8:38:13 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager function Sys$WebForms$PageRequestManager$_get_eventHandlerList() { if (!this._events) this._events = new Sys.EventHandlerList(); return this._events; }
3.
It defines a method named add_pageLoaded that enables you to register event handlers for the pageLoaded event of the current client-side PageRequestManager instance. As the following code fragment shows, this method first calls the get_eventHandlerList method on the current PageRequestManager instance to return a reference to the EventHandlerList object. Then it calls the addHandler method on this EventHandlerList object to register the specified handler as an event handler for the pageLoaded event of the current PageRequestManager instance:
function Sys$WebForms$PageRequestManager$add_pageLoaded(handler) { this._get_eventHandlerList().addHandler(“pageLoaded”, handler); }
4.
It defines a method named remove_pageLoaded that allows you to unregister an event handler registered for the pageLoaded event of the instance:
function Sys$WebForms$PageRequestManager$remove_pageLoaded(handler) { this._get_eventHandlerList().removeHandler(“pageLoaded”, handler); }
5.
It defines a method named _pageLoaded that raises the pageLoaded event and consequently invokes all the event handlers registered for this event, as shown in Listing 22-10.
The pageLoaded event, like any other, is associated with an event data class whose instance acts as a container for the associated event data. The event data class associated with the pageLoaded event is an ASP.NET AJAX client class named PageLoadedEventArgs. Listing 22-11 presents the internal implementation of the PageLoadedEventArgs class.
Listing 22-11: The Internal Implementation of the PageLoadedEventArgs Class Sys.WebForms.PageLoadedEventArgs = function Sys$WebForms$PageLoadedEventArgs(panelsUpdated, panelsCreated, dataItems) { /// /// /// Sys.WebForms.PageLoadedEventArgs.initializeBase(this); this._panelsUpdated = panelsUpdated; this._panelsCreated = panelsCreated; // Need to use “new Object()” instead of “{}”, since the latter breaks code // coverage. this._dataItems = dataItems || new Object(); }
As you can see, the constructor of the PageLoadedEventArgs class takes three parameters. The first is an array that contains the list of updated UpdatePanel server controls on the current page, the second is an array that contains the list of newly created UpdatePanel server controls, and the last is optional. The last parameter is null when the pageLoaded event is raised at the end of the instantiation/initialization of the current PageRequestManager instance. However, as you’ll see in the following chapters, the current client-side PageRequestManager instance also raises the pageLoaded event when it is processing the server response to an asynchronous page postback request where the last parameter of the constructor of the PageLoadedEventArgs class comes into play. As you can see from Listing 22-11, the constructor of the PageLoadedEventArgs class stores its parameters in private fields named _panelsUpdated, _panelsCreated, and _dataItems. Note that the PageLoadedEventArgs class exposes three getters named get_panelsUpdated, get_panelsCreated, and get_dataItems, that return these private fields. Now let’s revisit Listing 22-10, as shown again in the following code listing: function Sys$WebForms$PageRequestManager$_pageLoaded(initialLoad) { var handler = this._get_eventHandlerList().getHandler(“pageLoaded”); if (handler) { var args = this._getPageLoadedEventArgs(initialLoad)); handler(this, args); }
1054
c22.indd 1054
8/20/07 8:38:14 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager if (!initialLoad) { // If this isn’t the first page load (i.e. we are doing an async postback), we // need to re-raise the Application’s load event. Sys.Application.raiseLoad(); } }
As you can see, for the highlighted portion of the preceding code listing, this method invokes the _getPageLoadedEventArgs(initialLoad) internal method on the current PageRequestManager instance to instantiate and return an instance of the PageLoadedEventArgs class, which is then passed into the event handlers registered for the pageLoaded event of the current PageRequestManager instance. (I’ll present and discuss the internal implementation of the _getPageLoadedEventArgs method in Chapter 28.)
Using the pageLoaded Event As I mentioned earlier, the current client-side PageRequestManager instance fires its pageLoaded event at the end of its instantiation/initialization process to enable you to perform application-specific tasks that must be performed right after the current PageRequestManager instance is instantiated and initialized. Follow these steps to ensure that your required application-specific logic is executed right after the current PageRequestManager instance is instantiated and initialized:
1.
If your required application-specific logic is encapsulated in a method of an ASP.NET AJAX client class, invoke the createDelegate static method on the Function to instantiate a delegate that represents this method. If your required application-specific logic is not already encapsulated in a method of an ASP.NET AJAX client class, write a new JavaScript function that encapsulates this logic.
2.
Implement a JavaScript function that performs the following tasks:
3.
❑
Invokes the getInstance static method on the client-side PageRequestManager class to return a reference to the current client-side PageRequestManager instance
❑
Invokes the add_pageLoaded method on the current client-side PageRequestManager instance to register the delegate or the JavaScript function from Step 1 as the event handler for the pageLoaded event of the current client-side PageRequestManager instance
Register the JavaScript function from Step 3 as an event handler for the load event of the window object.
Listing 22-12 contains a page that uses this recipe. If you run this page, you should see the results shown in Figures 22-6 and 22-7. As Figure 22-6 shows, this page consists of a parent UpdatePanel server control that contains two child UpdatePanel server controls: one is added statically and the other is added dynamically — that is, via code. When you run this page, the page also displays the popup shown in Figure 22-7. As you can see, this popup contains a message that displays, right after the current client-side PageRequestManager instance is instantiated and initialized, some of the information that is available to an event handler registered for the pageLoaded event. What you do with this information is completely up to you. Your event handler can use it information to perform application-specific tasks that must be performed right after the current client-side PageRequestManager instance is instantiated and initialized.
1055
c22.indd 1055
8/20/07 8:38:14 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Listing 22-12: A Page that Uses the pageLoaded Event to Execute Application-Specific Logic void Page_Load(object sender, EventArgs e) { Label parentUpdatePanelLabel = (Label)Page.FindControl(“ParentUpdatePanelLabel”); parentUpdatePanelLabel.Text = “UpdatePanel refreshed at “ + DateTime.Now.ToString(); Label staticChildUpdatePanelLabel = (Label)Page.FindControl(“StaticChildUpdatePanelLabel”); staticChildUpdatePanelLabel.Text = “UpdatePanel refreshed at “ + DateTime.Now.ToString(); UpdatePanel dynamicChildUpdatePanel = new UpdatePanel(); dynamicChildUpdatePanel.ID = “DynamicChildUpdatePanel”; Table table = new Table(); table.BackColor = Color.FromArgb(90, 90, 90); table.ForeColor = Color.FromName(“White”); TableRow headerRow = new TableRow(); table.Rows.Add(headerRow); TableHeaderCell headerCell = new TableHeaderCell(); headerCell.Text = “Dynamic Child UpdatePanel Control”; headerRow.Cells.Add(headerCell); TableRow bodyRow = new TableRow(); table.Rows.Add(bodyRow); TableCell bodyCell = new TableCell(); bodyRow.Cells.Add(bodyCell); Label label = new Label(); label.ID = “DynamicChildUpdatePanelLabel”; label.Text = “UpdatePanel refreshed at “ + DateTime.Now.ToString() + “ ”; bodyCell.Controls.Add(label); Button button = new Button(); button.Text = “Update”; button.ID = “DynamicChildUpdatePanelButton”; button.Click += new EventHandler(ClickCallback); bodyCell.Controls.Add(button); dynamicChildUpdatePanel.ContentTemplateContainer.Controls.Add(table); PlaceHolder1.Controls.Add(dynamicChildUpdatePanel); } void ClickCallback (object sender, EventArgs e) { Label label = (Label)Page.FindControl(“DynamicChildUpdatePanelLabel”); label.Text = “UpdatePanel refreshed at “ + DateTime.Now.ToString() + “ ”; }
1056
c22.indd 1056
8/20/07 8:38:15 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Untitled Page window.onload = function () { var prm = Sys.WebForms.PageRequestManager.getInstance(); prm.remove_pageLoaded(pageLoadedHandler); prm.add_pageLoaded(pageLoadedHandler); } function pageLoadedHandler(sender, e) { var panelsUpdated = e.get_panelsUpdated(); var panelsCreated = e.get_panelsCreated(); var dataItems = e.get_dataItems(); var builder = new Sys.StringBuilder(); builder.append(“panelsUpdated: “); builder.appendLine(); for (var i in panelsUpdated) { builder.append(panelsUpdated[i].id); builder.appendLine(); } builder.appendLine(); builder.append(“panelsCreated: “); builder.appendLine(); for (var j in panelsCreated) { builder.append(panelsCreated[j].id); builder.appendLine(); } builder.appendLine(); builder.append(“_updatePanelIDs: “); builder.append(sender._updatePanelIDs); builder.appendLine(); builder.appendLine(); builder.append(“_updatePanelClientIDs: “); builder.append(sender._updatePanelClientIDs); builder.appendLine(); builder.appendLine(); builder.append(“_updatePanelHasChildrenAsTriggers: “); builder.append(sender._updatePanelHasChildrenAsTriggers); builder.appendLine(); builder.appendLine(); builder.append(“_asyncPostBackTimeout: “); builder.append(sender._asyncPostBackTimeout); builder.appendLine(); builder.appendLine(); builder.append(“_asyncPostBackControlIDs: “); builder.append(sender._asyncPostBackControlIDs); builder.appendLine(); builder.appendLine(); builder.append(“_asyncPostBackControlClientIDs: “); builder.append(sender._asyncPostBackControlClientIDs);
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager
Now let’s walk through the code shown in Listing 22-12. As you can see, this page contains a server-side and a client-side script block. The server-side script block contains the implementation of the Page_Load method. This method first calls the FindControl method twice on the current Page to return references to the ParentUpdatePanelLabel and StaticChildUpdatePanelLabel server controls, and then sets the values of their Text properties to the current time: Label parentUpdatePanelLabel = (Label)Page.FindControl(“ParentUpdatePanelLabel”); parentUpdatePanelLabel.Text = “UpdatePanel refreshed at “ + DateTime.Now.ToString(); Label staticChildUpdatePanelLabel = (Label)Page.FindControl(“StaticChildUpdatePanelLabel”); staticChildUpdatePanelLabel.Text = “UpdatePanel refreshed at “ + DateTime.Now.ToString();
1059
c22.indd 1059
8/20/07 8:38:16 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager
Figure 22-6
Next, the Page_Load method instantiates an UpdatePanel server control and sets its ID property value: UpdatePanel dynamicChildUpdatePanel = new UpdatePanel(); dynamicChildUpdatePanel.ID = “DynamicChildUpdatePanel”;
Then the method instantiates a Table server control with the specified background and foreground colors: Table table = new Table(); table.BackColor = Color.FromArgb(90, 90, 90); table.ForeColor = Color.FromName(“White”);
Next, it instantiates a TableRow server control to represent the header of the table: TableRow headerRow = new TableRow(); table.Rows.Add(headerRow); TableHeaderCell headerCell = new TableHeaderCell(); headerCell.Text = “Dynamic Child UpdatePanel Control”; headerRow.Cells.Add(headerCell);
1060
c22.indd 1060
8/20/07 8:38:16 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager
Figure 22-7 Then it creates another TableRow server control with two cells that contain a Label and a Button server control, respectively: TableRow bodyRow = new TableRow(); table.Rows.Add(bodyRow); TableCell bodyCell = new TableCell(); bodyRow.Cells.Add(bodyCell); Label label = new Label(); label.ID = “DynamicChildUpdatePanelLabel”; label.Text = “UpdatePanel refreshed at “ + DateTime.Now.ToString() + “ ”; bodyCell.Controls.Add(label); Button button = new Button(); button.Text = “Update”; button.ID = “DynamicChildUpdatePanelButton”; button.Click += new EventHandler(ClickCallback); bodyCell.Controls.Add(button);
1061
c22.indd 1061
8/20/07 8:38:16 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Note that the ClickCallback method is registered as an event handler for the Click event of the Button server control. Next, the Page_Load method adds the Table server control to the Controls collection of the ContentTemplateContainer property of the UpdatePanel server control: dynamicChildUpdatePanel.ContentTemplateContainer.Controls.Add(table);
As Listing 22-12 shows, the client-side script block consists of two parts. The first part registers the following JavaScript function as an event handler for the load event of the window object: window.onload = function () { var prm = Sys.WebForms.PageRequestManager.getInstance(); prm.add_pageLoaded(pageLoadedHandler); }
As you can see from the code fragment, this JavaScript function first calls the getInstance static method on the client-side PageRequestManager class to return a reference to the current client-side PageRequestManager instance: var prm = Sys.WebForms.PageRequestManager.getInstance();
Next, the function invokes the add_pageLoaded method on the current PageRequestManager instance to register the pageLoadedHandler JavaScript function as an event handler for the pageLoaded event of the current PageRequestManager instance: prm.add_pageLoaded(pageLoadedHandler);
Now let’s walk through the implementation of the pageLoadedHandler JavaScript function. When the current client-side PageRequestManager instance invokes this function, it passes two parameters into it. The first parameter references the current client-side PageRequestManager instance and the second references the PageLoadedEventArgs object that contains the event data for the pageLoaded event. As Listing 22-12 shows, the pageLoadedHandler method first calls the get_ panelsUpdated method on the PageLoadedEventArgs object to return a reference to the array that contains all the UpdatePanel server controls on the current page that were updated during the instantiation/ initialization phase of the current client-side PageRequestManager instance. Since this phase occurs when the current page is accessed for the first time, there are no prior UpdatePanel server controls to update and therefore the call to the get_panelsUpdated method is bound to return an empty array: var panelsUpdated = e.get_panelsUpdated();
Next, the pageLoadedHandler method calls the get_panelsCreated method on the PageLoadedEventArgs object to return a reference to the array that contains all the UpdatePanel server controls that were created and added to the current page during the instantiation/initialization phase of the current client-side PageRequestManager instance. As I mentioned earlier, because this phase occurs when the current page is accessed for the first time, all the UpdatePanel server controls on the current page are created and added to the current page, which means that the call into the get_ panelsCreated method returns an array that contains all the UpdatePanel server controls on the current page: var panelsCreated = e.get_panelsCreated();
1062
c22.indd 1062
8/20/07 8:38:17 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Next, the pageLoadedHandler method instantiates a StringBuilder: var builder = new Sys.StringBuilder();
Then it populates the StringBuilder with the UniqueID property values of all the UpdatePanel server controls in the panelsUpdated array. As I just mentioned, this array is empty: builder.append(“panelsUpdated: “); builder.appendLine(); for (var i in panelsUpdated) { builder.append(panelsUpdated[i].id); builder.appendLine(); }
Next, it populates the StringBuilder with the UniqueID property values of the all the UpdatePanel server controls in the panelsCreated array. As I just mentioned, this array contains all the UpdatePanel server controls on the current page: for (var j in panelsCreated) { builder.append(panelsCreated[j].id); builder.appendLine(); }
Then the pageLoadedHandler method adds the content of the _updatePanelIDs field of the current client-side PageRequestManager instance to the StringBuilder. Recall that the first parameter (that is, the sender parameter) of the pageLoadedHandler method references the current client-side PageRequestManager instance. Also recall that the _updatePanelIDs field of the current PageRequestManager instance contains the comma-separated list of the UniqueID property values of all the UpdatePanel server controls on the current page, both updated and created: builder.appendLine(); builder.append(“_updatePanelIDs: “); builder.append(sender._updatePanelIDs);
Next, it adds the content of the _updatePanelClientIDs field of the current client-side PageRequestManager instance to the StringBuilder. Recall that the _updatePanelClientIDs field contains the comma-separated list of the ClientID property values of all the UpdatePanel server controls on the current page, both updated and created: builder.appendLine(); builder.appendLine(); builder.append(“_updatePanelClientIDs: “); builder.append(sender._updatePanelClientIDs);
Then it adds the content of the _updatePanelHasChildrenAsTriggers field of the current client-side PageRequestManager instance to the StringBuilder. Recall that the _updatePanelHasChildrenAsTriggers field contains the comma-separated list of Boolean values, one for each UpdatePanel server control in the _updatePanelIDs:
Next, the pageLoadedHandler method adds the value of the _asyncPostBackTimeout field of the current client-side PageRequestManager instance to the StringBuilder. Recall that this field contains the asynchronous page postback request timeout: builder.appendLine(); builder.appendLine(); builder.append(“_asyncPostBackTimeout: “); builder.append(sender._asyncPostBackTimeout);
Next, it adds the content of the _asyncPostBackControlIDs field of the current client-side PageRequestManager instance to the StringBuilder. Recall that the _asyncPostBackControlIDs field contains the comma-separated list of the UniqueID property values of all the server controls on the current page that cause asynchronous page postbacks: builder.appendLine(); builder.appendLine(); builder.append(“_asyncPostBackControlIDs: “); builder.append(sender._asyncPostBackControlIDs);
Then it adds the content of the _asyncPostBackControlClientIDs field of the current client-side PageRequestManager instance to the StringBuilder. Recall that the _asyncPostBackControlClientIDs field contains the comma-separated list of the ClientID property values of all the server controls on the current page that cause asynchronous page postbacks: builder.appendLine(); builder.appendLine(); builder.append(“_asyncPostBackControlClientIDs: “); builder.append(sender._asyncPostBackControlClientIDs);
Next, it adds the content of the _postBackControlIDs field of the current client-side PageRequestManager instance to the StringBuilder. Recall that the _postBackControlIDs field contains the comma-separated list of the UniqueID property values of all the server controls on the current page that cause synchronous page postbacks: builder.appendLine(); builder.appendLine(); builder.append(“_postBackControlIDs: “); builder.append(sender._postBackControlIDs);
Then it adds the content of the _postBackControlClientIDs field of the current client-side PageRequestManager instance to the StringBuilder. Recall that the _postBackControlClientIDs field contains the comma-separated list of the ClientID property values of all the server controls on the current page that cause synchronous page postbacks: builder.appendLine(); builder.appendLine(); builder.append(“_postBackControlClientIDs: “); builder.append(sender._postBackControlClientIDs);
1064
c22.indd 1064
8/20/07 8:38:17 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Finally, the pageLoadedHandler method displays the content of the StringBuilder in a popup, shown in Figure 22-7. alert(builder.toString());
As Figure 22-7 shows:
❑
The panelsUpdated array is empty as expected.
❑
The panelsCreated array contains all the UpdatePanel server controls on the current page: ParentUpdatePanel, StaticChildUpdatePanel, and DynamicChildUpdatePanel, as expected. As we discussed, when the current page is loaded for the first time, all the UpdatePanel server controls are created and added to the current page.
❑
The _updatePanelIDs field of the current PageRequestManager instance returns the commaseparated list of the UniqueID properties of all the UpdatePanel server controls on the current page: ParentUpdatePanel, StaticChildUpdatePanel, and DynamicChildUpdatePanel. Note that the UniqueID property values in this example are the same as the ID property values because none of the UpdatePanel server controls in this example belongs to a parent server control that implements the INamingContainer interface.
❑
The _updatePanelClientIDs field of the current PageRequestManager instance returns the comma-separated list of the ClientID properties of all the UpdatePanel server controls on the current page: ParentUpdatePanel, StaticChildUpdatePanel, and DynamicChildUpdatePanel. Note that the ClientID property values in this example are the same as the ID property values because none of the UpdatePanel server controls in this example belongs to a parent server control that implements the INamingContainer interface.
❑
The _updatePanelHasChildrenAsTriggers field of the current PageRequestManger instance returns the comma-separated list of the Boolean values, one for each UpdatePanel server control. Because this example contains three UpdatePanel server controls and because the ChildrenAsTriggers properties of all three UpdatePanel server controls are set to true by default, the _updatePanelHasChildrenAsTrigger field contains a comma-separated list of three true values.
❑
The _asyncPostBackTimeout field of the current PageRequestManager instance returns the default value, which is 90000.
❑
The _asyncPostBackControlIDs field of the current PageRequestManager instance returns the comma-separated list of the UniqueID property values of all asynchronous postback server controls. This example contains two asynchronous postback Button server controls: ParentUpdatePanelTrigger and StaticChildUpdatePanelTrigger.
❑
The _asyncPostBackControlClientIDs field of the current PageRequestManager instance returns the comma-separated list of the ClientID property values of all asynchronous postback server controls. This example contains two asynchronous postback Button server controls: ParentUpdatePanelTrigger and StaticChildUpdatePanelTrigger. Again, because these two Button server controls do not belong to a server control that implements the INamingContainer interface, their UniqueID, ClientID, and ID properties have the same values.
Keep in mind that the arrays returned from the calls into the get_panelsUpdated and get_panelsCreated methods contain references to the actual updated and created UpdatePanel server controls. This gives your event handler (registered for the pageLoaded event of the current
1065
c22.indd 1065
8/20/07 8:38:18 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager PageRequestManager instance) a powerful tool with which to modify the contents of these UpdatePanel server controls or to enhance their functionality. The next example should give you an
idea of the types of things you could do within your event handler. Listing 22-13 contains a page that registers an event handler for the pageLoaded event of the current PageRequestManager instance, where it attaches a Mover object to each UpdatePanel server control. Recall from Chapter 7 that we developed an ASP.NET AJAX component named Mover. When an instance of this component is attached to a control, the end user can freely move the control. As you can see, the page shown in Listing 22-12 contains two UpdatePanel server controls. I’ve intentionally kept the contents of these UpdatePanel server controls simple so we can focus on what matters to our discussions. However, you can make these contents as complex as you want.
Listing 22-13: A Page that Attaches Movers to UpdatePanel Server Controls Untitled Page window.onload = function () { var prm = Sys.WebForms.PageRequestManager.getInstance(); prm.remove_pageLoaded(pageLoadedHandler); prm.add_pageLoaded(pageLoadedHandler); } function pageLoadedHandler(sender, e) { var updatePanelMover; var updatePanelProvider; var addUpdatePanelDelegate; var panelsCreated = e.get_panelsCreated(); for (var j in panelsCreated) { updatePanelMover = new Delegates.Mover(“container”+j); updatePanelProvider = new Delegates.UpdatePanelProvider(panelsCreated[j]); addUpdatePanelDelegate = Function.createDelegate(updatePanelProvider, updatePanelProvider.addUpdatePanel); updatePanelMover.addContent(addUpdatePanelDelegate); } }
1066
c22.indd 1066
8/20/07 8:38:18 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Wrox Web Site
Now let’s walk through the implementation of the pageLoadedHandler JavaScript function. This function invokes the get_panelsCreated method on the PageLoadedEventArgs object to return a reference to the array that contains all the newly created UpdatePanel server control on the current page: var panelsCreated = e.get_panelsCreated();
Next, the function iterates through the UpdatePanel server controls in the panelsCreated array and takes the following steps for each enumerated UpdatePanel control. First it instantiates a Mover object: updatePanelMover = new Delegates.Mover(“container”+j);
Next, it instantiates an UpdatePanelProvder object, passing in the enumerated UpdatePanel server control as its argument: updatePanelProvider = new Delegates.UpdatePanelProvider(panelsCreated[j]);
Then it calls the createDelegate static method on the Function to create a delegate that represents the addUpdatePanel method of the UpdatePanelProvider object: addUpdatePanelDelegate = Function.createDelegate(updatePanelProvider, updatePanelProvider.addUpdatePanel);
Finally, it invokes the addContent method on the Mover object, passing in the delegate. Recall from Chapter 7 that the addContent method automatically invokes this delegate and consequently the addUpdatePanel method on the UpdataPanelProvider object. updatePanelMover.addContent(addUpdatePanelDelegate);
1067
c22.indd 1067
8/20/07 8:38:18 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Listing 22-14 presents the content of the Delegates.js JavaScript file. The boldfaced portion of this code listing contains the code for a new ASP.NET AJAX client class named UpdatePanelProvider.
Listing 22-14: The Content of the Delegates.js JavaScript File Type.registerNamespace(“Delegates”); Delegates.Mover = function (containerId) { var container = $get(containerId); Delegates.Mover.incrementMoversCount(); if (!container) { container = document.createElement(“div”); this.containerId = container.id = containerId; container.style.position = “absolute”; document.body.insertBefore(container, document.forms[0]); $addHandlers(container, { mousedown: this.mousedowncb }, this); } } Delegates.Mover.prototype = { addContent : Delegates$Mover$invokeAddContentDelegate, mousedowncb : Delegates$Mover$mousedowncb, mouseupcb : Delegates$Mover$mouseupcb, mousemovecb : Delegates$Mover$mousemovecb } Delegates.Mover.incrementMoversCount = function() { if (typeof(this.moversCount) == “undefined”) this.moversCount = 0; this.moversCount++; } Delegates.Mover.get_moversCount = function() { return this.moversCount; } function Delegates$Mover$invokeAddContentDelegate(addContentDelegate) { addContentDelegate(this.containerId); } function Delegates$Mover$mousedowncb(domEvent) { var container = $get(this.containerId); this.oldClientX = domEvent.clientX; this.oldClientY = domEvent.clientY; var events = {mousemove: this.mousemovecb, mouseup: this.mouseupcb}
1068
c22.indd 1068
8/20/07 8:38:19 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager $addHandlers(document, events, this); container.style.zIndex += Delegates.Mover.get_moversCount(); domEvent.preventDefault(); } function Delegates$Mover$mouseupcb(domEvent) { var container = $get(this.containerId); $clearHandlers(document); container.style.zIndex −= Delegates.Mover.get_moversCount(); domEvent.preventDefault(); } function Delegates$Mover$mousemovecb(domEvent) { var container = $get(this.containerId); var deltaClientX = domEvent.clientX − this.oldClientX; var deltaClientY = domEvent.clientY − this.oldClientY; var containerLocation = Sys.UI.DomElement.getLocation(container); Sys.UI.DomElement.setLocation(container, containerLocation.x+deltaClientX, containerLocation.y+deltaClientY); this.oldClientX = domEvent.clientX; this.oldClientY = domEvent.clientY; domEvent.preventDefault(); } Delegates.UpdatePanelProvider = function (updatePanel) { this.updatePanel = updatePanel; } Delegates.UpdatePanelProvider.prototype = { addUpdatePanel : Delegates$UpdatePanelProvider$addUpdatePanel } function Delegates$UpdatePanelProvider$addUpdatePanel(containerId) { var container = $get(containerId); container.appendChild(this.updatePanel); } Delegates.Mover.registerClass(“Delegates.Mover”); Delegates.UpdatePanelProvider.registerClass(“Delegates.UpdatePanelProvider”); if (typeof(Sys) !== ‘undefined’) Sys.Application.notifyScriptLoaded();
1069
c22.indd 1069
8/20/07 8:38:19 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager As you can see, because the PageLoadedEventArgs event data class provides you with references to the actual updated and created UpdatePanel server controls, you can do really cool things within your event handler for the pageLoaded event. I’ll wrap up this section by drawing your attention to something important in Listings 22-12 and 22-13. Note that both code listings perform the registration of the pageLoadedHandler function for the pageLoaded event inside an event handler for the load event of the window object, as opposed to the pageLoad method. To find out why this is, we need to visit the internal implementation of the Render method of the ScriptManager server control, as shown in Listing 22-15.
Listing 22-15: The Render Method of the Current ScriptManager Server Control protected override void Render(HtmlTextWriter writer) { this.PageRequestManager.Render(writer); if (!this.IsInAsyncPostBack) this.IPage.ClientScript.RegisterStartupScript(typeof(ScriptManager), “AppInitialize”, “Sys.Application.initialize();\r\n”, true); base.Render(writer); }
As you can see from the highlighted portions of Listing 22-15, the Render method of the current ScriptManager server control calls the following two methods:
1.
First, it calls the Render method on the current server-side PageRequestManager instance. As discussed thoroughly in the previous chapter, the Render method of the current server-side PageRequestManager instance renders the following script block, which is then sent to the requesting browser:
//
As you can see, the script block shown calls the _initialize static method on the client-side PageRequestManager class to instantiate and to initialize the current client-side PageRequestManager instance. As discussed thoroughly earlier in this chapter, the _initialize static method is the one that finally raises the pageLoaded event of the current client-side PageRequestManager instance.
2.
Next, the Render method of the current ScriptManager server control calls the RegisterStartupScript method on the ClientScript property of the current page to render the following script block at the bottom of the current page:
1070
c22.indd 1070
8/20/07 8:38:19 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager //
As you can see, the script block calls the initialize method on the Application object that represents the current ASP.NET AJAX application. As discussed thoroughly in Chapter 8, the call into the initialize method finally calls the pageLoad method. As you can see, the script block that raises the pageLoaded event of the current client-side PageRequestManager instance is rendered before the script block that calls the pageLoad method. That is why, if you register a JavaScript function as an event handler for the pageLoaded event of the current client-side PageRequestManager instance inside the pageLoad method, your JavaScript function will not be invoked when the pageLoaded event is raised at the end of the instantiation/initialization phase.
Making an Asynchronous Page Postback The previous section followed the current client-side PageRequestManager instance through its instantiation and initialization life cycle phases. As discussed earlier, the current client-side pageRequestManager instance goes through these life cycle phases only once during its entire lifetime. In this section we’ll follow the current client-side PageRequestManager instance through its life cycle phases to make an asynchronous page postback request to the server. As discussed earlier, ASP.NET provides two different mechanisms for triggering a page postback: the Submit button and the _doPostBack method. Assume that a page postback via the _doPostBack method of the window object has just occurred and that consequently the _doPostBack method of the current PageRequestManager instance has just been invoked.
Helper Methods The implementation of the _doPostBack method of the PageRequestManager makes use of four other helper methods of the current PageRequestManager instance. I’ll present and discuss the implementations of these four helper methods first.
_createPostBackSettings The PageRequestManager exposes an private method named _createPostBackSettings, as shown in Listing 22-16, that takes three parameters: the first is a Boolean value that specifies whether the current page postback request is asynchronous, the second is a string that contains the value of the UniqueID property of the UpdatePanel server control whose child server control causes the current postback, and the third references the DOM element that caused the current postback. This private method creates and returns an object literal with three name/value pairs. The name part of the first name/value pair is the keyword async, and the value part contains the value of the first parameter of the method. The name part of the second name/value pair is the keyword panelID, and the value part contains the value of the second parameter of the method. The name part of the third name/value pair is the keyword sourceElement, and the value part contains the value of the third parameter of the method.
1071
c22.indd 1071
8/20/07 8:38:20 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Listing 22-16: The _createPostBackSettings Private Method of PageRequestManager function Sys$WebForms$PageRequestManager$_createPostBackSettings(async, panelID, sourceElement) { return { async: async, panelID: panelID, sourceElement: sourceElement }; }
_findNearestElement The PageRequestManager exposes a private method named _findNearestElement that takes a UniqueID property value and returns a reference to the nearest element. As Listing 22-17 shows, this method uses the fact that the UniqueID property value of an ASP.NET server control is a string that contains one or more substrings separated by the dollar sign ($), each of which contains the UniqueID property value of an ancestor of the server control. As you can see, the _findNearestElement method first calls the _uniqueIDToClientID method on the current PageRequestManager instance to return the ClientID property value associated with the specified UniqueID property value (see Listing 22-10): var clientID = this._uniqueIDToClientID(uniqueID);
Next, the method invokes the getElementById method on the document object to return a reference to the DOM element with the preceding ClientID property value: var element = document.getElementById(clientID);
If the current document does indeed contain a DOM element with the desired ClientID property value, the _findNearestElement method simply returns this reference. However, if the current document does not contain a DOM element with the specified ClientID property value, the _findNearestElement method accesses the last substring in the UniqueID property value string and repeats the previous steps: var indexOfLastDollar = uniqueID.lastIndexOf(‘$’); uniqueID = uniqueID.substring(0, indexOfLastDollar);
The _findNearestElement method keeps repeating the same steps for each substring of the UniqueID property value string until it locates the substring or UniqueID property value whose associated DOM element exists in the current document, or it returns null. (Keep in mind that each substring is itself a UniqueID property value.)
Listing 22-17: The _findNearestElement Private Method of PageRequestManager function Sys$WebForms$PageRequestManager$_findNearestElement(uniqueID) { while (uniqueID.length > 0) { var clientID = this._uniqueIDToClientID(uniqueID); var element = document.getElementById(clientID); if (element) return element;
1072
c22.indd 1072
8/20/07 8:38:20 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager var indexOfLastDollar = uniqueID.lastIndexOf(‘$’); if (indexOfLastDollar === -1) return null; uniqueID = uniqueID.substring(0, indexOfLastDollar); } return null; }
_matchesParentIDInList The current PageRequestManager instance features an internal method named _matchesParentIDInList that takes two parameters. The first is a string that contains a ClientID property value and the second is an array of ClientID property values. As you can see from Listing 22-18, this method searches the array for the ClientID property value of the parent server control of the server control whose ClientID property value is given by the first parameter. The method return true if the search succeeds and false otherwise.
Listing 22-18: The _matchesParentIDInList Method of PageRequestManager function Sys$WebForms$PageRequestManager$_matchesParentIDInList(clientID, parentClientIDList) { for (var i = 0; i < parentClientIDList.length; i++) { if (clientID.startsWith(parentClientIDList[i] + “_”)) return true; } return false; }
_getPostBackSettings The _getPostBackSettings method of the PageRequestManager takes two parameters, as shown in Listing 22-19. The second parameter is a UniqueID property value of the server control that caused the current postback. The first parameter references the server control whose UniqueID property value best matches this UniqueID property value. This method has two main responsibilities:
❑
Determine whether the current postback is asynchronous
❑
Determine whether the server control that the second parameter references resides inside an UpdatePanel server control whose ChildrenAsTriggers property is set to true
The _getPostBackSettings method walks up the DOM hierarchy of the server control that the first parameter references and takes the following steps for each server control in this DOM hierarchy:
❑
If the server control resides in an UpdatePanel server control whose ChildrenAsTriggers property is set to true, the _getPostBackSettings method creates an object literal whose:
❑
async property is set to true to specify that the current postback is asynchronous
1073
c22.indd 1073
8/20/07 8:38:20 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager When a server control that resides in an UpdatePanel server control whose ChildrenAsTriggers property is set to true causes a page postback, the current PageRequestManager instance treats the page postback as asynchronous page postback regardless of whether or not the server control has been explicitly registered as a trigger for asynchronous page postback.
❑
panelID property is set to a string that contains two substrings separated by the | character, where the first substring contains the UniqueID property value of the UpdatePanel server control and the second contains the UniqueID property value of the server control. As you’ll see later, the presence of the UniqueID property value of this UpdatePanel server control signals the server that this UpdatePanel server control must be updated.
When a server control that resides in an UpdatePanel server control whose ChildrenAsTriggers property is set to true causes a page postback, it automatically triggers the update of its parent UpdatePanel server control.
❑ ❑
sourceElement property contains a reference to the server control.
If the _asyncPostBackControlIDs collection contains the UniqueID property value of the server control or one of its ancestor server controls, but the server control does not reside in an UpdatePanel server control whose ChildrenAsTrigger property is set to true, the _getPostBackSettings method creates an object literal whose:
❑
async property is set to true to specify that the current postback is asynchronous.
When a server control whose UniqueID property value belongs to the _asyncPostBackControlIDs collection of the current PageRequestManager instance causes a page postback, the current PageRequestManager instance treats the page postback as asynchronous.
❑
❑
panelID property is set to a string that contains two substrings separated by the | character where the first substring contains the UniqueID property value of the ScriptManager server control and the second contains the UniqueID property value of the server control.
❑
sourceElement property contains a reference to the server control.
If the _postBackControlIDs collection contains the UniqueID property value of the server control or one of its ancestor server controls, the _getPostBackSettings method creates an object literal whose:
❑
async property is set to false to specify that the current postback is a regular synchronous postback. This instructs the current PageRequestManager instance that the responsi-
bility of posting the current page back to the server must be delegated to the browser to allow the browser to perform a regular page postback to the server.
❑
panelID property is set to null.
❑
sourceElement is set to null.
When a server control whose UniqueID property value belongs to the _postBackControlIDs collection of the current PageRequestManager instance causes a page postback, the current PageRequestManager instance doesn’t get involved in the form submission.
1074
c22.indd 1074
8/20/07 8:38:21 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Listing 22-19: The _getPostBackSettings Method of the PageRequestManager function Sys$WebForms$PageRequestManager$_getPostBackSettings(element, elementUniqueID) { var originalElement = element; // Keep track of whether we have an AsyncPostBackControl but still // want to see if we’re inside an UpdatePanel anyway. var proposedSettings = null; // Walk up DOM hierarchy to find out the nearest container of // the element that caused the postback. while (element) { if (element.id) { // First try an exact match for async postback, regular postback, // or UpdatePanel if (!proposedSettings && Array.contains(this._asyncPostBackControlClientIDs, element.id)) { // The element explicitly causes an async postback proposedSettings = this._createPostBackSettings(true, this._scriptManagerID + ‘|’ + elementUniqueID, originalElement); } else { if (!proposedSettings && Array.contains(this._postBackControlClientIDs, element.id)) { // The element explicitly doesn’t cause an async postback return this._createPostBackSettings(false, null, null); } else { var indexOfPanel = Array.indexOf(this._updatePanelClientIDs, element.id); if (indexOfPanel !== -1) { // The element causes an async postback because it is inside // an UpdatePanel if (this._updatePanelHasChildrenAsTriggers[indexOfPanel]) { // If it was in an UpdatePanel and the panel has // ChildrenAsTriggers=true, then // we do an async postback and refresh the given panel // Although we do the search by looking at ClientIDs, we end // up sending a UniqueID back to the server so that we can // call FindControl() with it. return this._createPostBackSettings(true, this._updatePanelIDs[indexOfPanel] + ‘|’ + elementUniqueID, originalElement); }
(continued)
1075
c22.indd 1075
8/20/07 8:38:21 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Listing 22-19 (continued) else { // The element was inside an UpdatePanel so we do an async postback, // but because it has ChildrenAsTriggers=false we don’t update // this panel. return this._createPostBackSettings(true, this._scriptManagerID + ‘|’ + elementUniqueID, originalElement); } } } } // Then try near matches if (!proposedSettings && this._matchesParentIDInList(element.id, this._asyncPostBackControlClientIDs)) { // The element explicitly causes an async postback proposedSettings = this._createPostBackSettings(true, this._scriptManagerID + ‘|’ + elementUniqueID, originalElement); } else { if (!proposedSettings && this._matchesParentIDInList(element.id, this._postBackControlClientIDs)) { // The element explicitly doesn’t cause an async postback return this._createPostBackSettings(false, null, null); } } } element = element.parentNode; } // // // // // if {
If we have proposed settings that means we found a match for an AsyncPostBackControl but were still searching for an UpdatePanel. If we got here that means we didn’t find the UpdatePanel so we just fall back to the original AsyncPostBackControl settings that we created. (!proposedSettings) // The element doesn’t cause an async postback return this._createPostBackSettings(false, null, null);
} else return proposedSettings; }
1076
c22.indd 1076
8/20/07 8:38:21 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager
_doPostBack Now back to the main topic of discussion: the implementation of the _doPostBack method of the current PageRequestManager instance. As discussed earlier, this method is invoked when a page postback occurs via the _doPostBack method of the window object. An example of such a page postback is the one that occurs when an end user selects a new item from a DropDownList server control whose AutoPostBack property has been set to true. Listing 22-20 presents the internal implementation of the _doPostBack method of the current PageRequestManager instance. This method takes the same two parameters that the original _doPostBack method takes. The first is the value of the UniqueID property of the server control that caused the page postback. For example, in the case of the DropDownList server control whose AutoPostBack property is set to true, the first parameter is the value of the UniqueID property of the DropDownList control. The second parameter is optional. For example, in the case of the DropDownList server control whose AutoPostBack property is set to true, the second parameter is the selected value of the server control.
Listing 22-20: The _doPostBack Method of the PageRequestManager function Sys$WebForms$PageRequestManager$_doPostBack(eventTarget, eventArgument) { this._additionalInput = null; var form = this._form; if (form.action !== form._initialAction) { // Allow the default form submit to take place. Since the current // form action is different from the initial one, it’s a cross-page postback. this._postBackSettings = this._createPostBackSettings(false, null, null); } else { // If it’s not a cross-page post, see if we can find the DOM element // that caused the postback var clientID = this._uniqueIDToClientID(eventTarget); var postBackElement = document.getElementById(clientID); if (!postBackElement) { // If the control has no matching DOM element we look for an exact // match from RegisterAsyncPostBackControl or RegisterPostBackControl. // If we can’t find anything about it then we do a search based on // naming containers to still try and find a match. if (Array.contains(this._asyncPostBackControlIDs, eventTarget)) { // Exact match for async postback this._postBackSettings = this._createPostBackSettings(true, this._scriptManagerID + ‘|’ + eventTarget, null); } else { if (Array.contains(this._postBackControlIDs, eventTarget))
(continued)
1077
c22.indd 1077
8/20/07 8:38:22 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Listing 22-20 (continued) { // Exact match for regular postback this._postBackSettings = this._createPostBackSettings(false, null, null); } else { // Find nearest element based on UniqueID in case the element calling // __doPostBack doesn’t have an ID. GridView does this for its Update // button and without this we can’t do async postbacks. var nearestUniqueIDMatch = this._findNearestElement(eventTarget); if (nearestUniqueIDMatch) { // We found a related parent element, so walk up the DOM to find out // what kind of postback we should do. this._postBackSettings = this._getPostBackSettings(nearestUniqueIDMatch, eventTarget); } else { // Can’t find any DOM element at all related to the eventTarget, // so we just give up and do a regular postback. this._postBackSettings = this._createPostBackSettings(false, null, null); } } } } else { // The element was found, so walk up the DOM to find out what kind // of postback we should do. this._postBackSettings = this._getPostBackSettings(postBackElement, eventTarget); } } if (!this._postBackSettings.async) { // Temporarily restore the form’s onsubmit handler expando while calling // the original ASP.NET 2.0 __doPostBack() function. form.onsubmit = this._onsubmit; this._originalDoPostBack(eventTarget, eventArgument); form.onsubmit = null; return; } form.__EVENTTARGET.value = eventTarget; form.__EVENTARGUMENT.value = eventArgument; this._onFormSubmit(); }
As Listing 22-20 shows, the _doPostBack method first checks whether the current value of the action property of the form is different from its original value. Recall from Listing 22-5 that the _initializeInternal method of the current PageRequestManager instance stores the original
1078
c22.indd 1078
8/20/07 8:38:22 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager action value in a custom property on the form named _initialAction. If the current action value is different from the original action value, this indicates that the current postback is a cross-page postback. Therefore, the _doPostBack method calls the _createPostBackSettings method on the current PageRequestManager instance to create a postback settings — an object literal with async property value of false — to indicate that the current postback is not asynchronous. (Recall from Listing 22-16 that the _createPostBackSettings method creates an object literal, known as postback settings, with three properties named async, panelID, and sourceElement.) if (form.action !== form._initialAction) this._postBackSettings = this._createPostBackSettings(false, null, null);
If the current form action value is the same as the original form action value, the _doPostBack method calls the _uniqueIDToClientID method on the current PageRequestManager instance, passing in its first parameter. Recall that the first parameter is a string that contains the UniqueID property value of the server control that caused the current page postback. Also recall from Listing 22-8 that the _uniqueIDToClientID method simply returns the ClientID property value of the server control with the specified UniqueID property value.: var clientID = this._uniqueIDToClientID(eventTarget);
The _doPostBack method then calls the getElementById method on the document object, passing in the ClientID property value to return a reference to the DOM element that caused the current page postback. var postBackElement = document.getElementById(clientID);
If the getElementById method does not return null, the _doPostBack method calls the _getPostBackSettings method discussed earlier to create the appropriate postback settings object: this._postBackSettings = this._getPostBackSettings(postBackElement, eventTarget);
If the getElementById method does return null, the _doPostBack method takes the following steps to get a reference to the DOM element that caused the current page postback:
❑
If the _asyncPostBackControlIDs collection of the current PageRequestManager instance contains the UniqueID property value of the server control that caused the current postback, the _doPostBack method creates an object literal whose:
❑
async property is set to true to specify that the current postback is asynchronous
❑
panelID property is set to a string that contains two substrings separated by the | character, where the first substring contains the UniqueID property value of the ScriptManager server control and the second contains the UniqueID property value of the server control that caused the current page postback
❑
sourceElement property is set to null: if (Array.contains(this._asyncPostBackControlIDs, eventTarget)) { // Exact match for async postback this._postBackSettings = this._createPostBackSettings(true, this._scriptManagerID + ‘|’ + eventTarget, null); }
1079
c22.indd 1079
8/20/07 8:38:22 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager ❑
If the _postBackControlIDs collection of the current PageRequestManager instance contains the UniqueID property value of the server control that caused the current postback, the _doPostBack method creates an object literal whose
❑
async property is set to false to specify that the current postback is a regular synchronous postback. This instructs the current PageRequestManager instance that the responsibility of posting the current page back to the server must be delegated to the browser to allow the browser to perform a regular page postback to the server.
❑
panelID property is set to null.
❑
sourceElement is set to null: if (Array.contains(this._postBackControlIDs, eventTarget)) { // Exact match for regular postback this._postBackSettings = this._createPostBackSettings(false, null, null); }
❑
If neither the _asyncPostBackControlIDs nor the _postBackControlIDs collections of the current PageRequestManager instance contains the UniqueID property value of the server control that caused the current postback, the _doPostBack method calls the _findNearestElement method on the current PageRequestManager instance to return a reference to the DOM element that best matches the specified UniqueID property: var nearestUniqueIDMatch = this._findNearestElement(eventTarget);
❑
If it finds such an element on the current page, it calls the _getPostBackSettings method on the current PageRequestManager instance to return the appropriate postback settings object, as discussed earlier: if (nearestUniqueIDMatch) { // We found a related parent element, so walk up the DOM to find out // what kind of postback we should do. this._postBackSettings = this._getPostBackSettings(nearestUniqueIDMatch, eventTarget); }
❑
If it doesn’t find such an element on the current page, it gives up the search for the element with the specified UniqueID and creates a postback settings object whose:
❑
async property is set to false to specify that the current postback is a regular synchronous postback. This instructs the current PageRequestManager instance that the responsibility of posting the current page back to the server must be delegated to the browser to allow the browser to perform a regular page postback to the server.
❑
panelID property is set to null.
❑
sourceElement is set to null:
1080
c22.indd 1080
8/20/07 8:38:23 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager else { // Can’t find any DOM element at all related to the eventTarget, // so we just give up and do a regular postback. this._postBackSettings = this._createPostBackSettings(false, null, null); }
Next, the _doPostBack method checks whether the async property of the postback settings object is set. If not, this is an indication that the current page postback is not asynchronous, and consequently the _doPostBack method first assigns the _onsubmit method of the current PageRequestManager instance as the onsubmit method on the form element. Recall that the _onsubmit method references the original value of the onsubmit property of the form. Next, the _doPostBack method of the current PageRequestManager instance invokes the _originalDoPostBack method of the current PageRequestManager instance. Recall that the _originalDoPostBack method references the ASP.NET 2.0 standard __doPostBack global JavaScript function, which performs normal synchronous page postbacks to the server: if (!this._postBackSettings.async) { // Temporarily restore the form’s onsubmit handler expando while calling // the original ASP.NET 2.0 __doPostBack() function. form.onsubmit = this._onsubmit; this._originalDoPostBack(eventTarget, eventArgument); form.onsubmit = null; return; }
If the async property of the postback settings object has been set, this is an indication that the current page postback is asynchronous page and consequently that the _doPostBack method of the current PageRequestManager instance first stores the UniqueID property value of the server control that caused the current postback in a hidden field named __EVENTTARGET: form.__EVENTTARGET.value = eventTarget;
Next, it stores the optional event argument parameter in a hidden field named __EVENTARGUMENT: form.__EVENTARGUMENT.value = eventArgument;
Finally, it invokes the _onFormSubmit method on the current PageRequestManager instance to submit the form to the server. As you’ll see in the next section, the _onFormSubmit method uses the ASP.NET AJAX client-server communication layer to post the page back to the server asynchronously: this._onFormSubmit();
_onFormSubmit As we discussed earlier, the ASP.NET framework provides an ASP.NET page with two types of postbacks: through the Submit button and through the ASP.NET 2.0 standard __doPostBack global JavaScript function. As you can see, both approaches end up calling the _onFormSubmit method of the current PageRequestManager instance. Listing 22-21 presents the internal implementation of the _onFormSubmit method of the PageRequestManager.
1081
c22.indd 1081
8/20/07 8:38:23 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Listing 22-21: The _onFormSubmit Method of the Client-Side PageRequestManager Instance function Sys$WebForms$PageRequestManager$_onFormSubmit(evt) { var continueSubmit = true; if (this._onsubmit) continueSubmit = this._onsubmit(); if (continueSubmit) { for (var i = 0; i < this._onSubmitStatements.length; i++) { if (!this._onSubmitStatements[i]()) { continueSubmit = false; break; } } } if (!continueSubmit) { if (evt) evt.preventDefault(); return; } var form = this._form; if (form.action !== form._initialAction) return; if (!this._postBackSettings.async) return; var formBody = new Sys.StringBuilder(); formBody.append(this._scriptManagerID + ‘=’ + this._postBackSettings.panelID + ‘&’); var count = form.elements.length; for (var i = 0; i < count; i++) { var element = form.elements[i]; var name = element.name; if (typeof(name) === “undefined” || (name === null) || (name.length === 0)) continue; var tagName = element.tagName; if (tagName === ‘INPUT’) { var type = element.type; if ((type === ‘text’) || (type === ‘password’) || (type === ‘hidden’) || (((type === ‘checkbox’) || (type === ‘radio’)) && element.checked)) { formBody.append(name); formBody.append(‘=’);
1082
c22.indd 1082
8/20/07 8:38:23 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager formBody.append(encodeURIComponent(element.value)); formBody.append(‘&’); } } else if (tagName === ‘SELECT’) { var optionCount = element.options.length; for (var j = 0; j < optionCount; j++) { var option = element.options[j]; if (option.selected) { formBody.append(name); formBody.append(‘=’); formBody.append(encodeURIComponent(option.value)); formBody.append(‘&’); } } } else if (tagName === ‘TEXTAREA’) { formBody.append(name); formBody.append(‘=’); formBody.append(encodeURIComponent(element.value)); formBody.append(‘&’); } } if (this._additionalInput) { formBody.append(this._additionalInput); this._additionalInput = null; } var request = new Sys.Net.WebRequest(); request.set_url(form.action); request.get_headers()[‘X-MicrosoftAjax’] = ‘Delta=true’; request.get_headers()[‘Cache-Control’] = ‘no-cache’; request.set_timeout(this._asyncPostBackTimeout); request.add_completed(Function.createDelegate(this, this._onFormSubmitCompleted)); request.set_body(formBody.toString()); var handler = this._get_eventHandlerList().getHandler(“initializeRequest”); if (handler) { var eventArgs = new Sys.WebForms.InitializeRequestEventArgs(request, this._postBackSettings.sourceElement); handler(this, eventArgs); continueSubmit = !eventArgs.get_cancel(); }
(continued)
1083
c22.indd 1083
8/20/07 8:38:23 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Listing 22-21 (continued) if (!continueSubmit) { if (evt) evt.preventDefault(); return; } this._scrollPosition = this._getScrollPosition(); this.abortPostBack(); handler = this._get_eventHandlerList().getHandler(“beginRequest”); if (handler) { var eventArgs = new Sys.WebForms.BeginRequestEventArgs(request, this._postBackSettings.sourceElement); handler(this, eventArgs); } this._request = request; request.invoke(); if (evt) evt.preventDefault(); }
As you can see, this method takes the following steps. First, it calls the _onsubmit method on the current PageRequestManager instance. Recall from Listing 22-5 that the _initializeInternal method assigned the original value of the onsubmit property of the window object to the _onsubmit property of the current PageRequestManager instance. The original onsubmit method is normally where the values of the form elements are validated. This method returns false if the data validation fails: if (this._onsubmit) continueSubmit = this._onsubmit();
If the call into the original onsubmit method returns true — that is, if the data validation succeeds — the _onFormSubmit method iterates through the JavaScript statements in the _onSubmitStatements array and executes each statement. As you’ll see later, the _onSubmitStatements array contains the dynamically added form onsubmit statements: for (var i = 0; i < this._onSubmitStatements.length; i++) { if (!this._onSubmitStatements[i]()) { continueSubmit = false; break; } }
If either the original onsubmit method or one of the dynamically added form onsubmit statements returns false, the _onFormSubmit method cancels the form submission by invoking the preventDefault method on the DomEvent object that represents the current event: evt.preventDefault();
1084
c22.indd 1084
8/20/07 8:38:24 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Next, the _onFormSubmit method compares the current value of the action property of the form with its original value. If these two values are different, this is an indication that the current form is being posted back to a different page and consequently that the current request is a cross-page postback. As such, the _onFormSubmit method simply returns. Recall that the _onFormSubmit method is the event handler registered for the submit event of the form. The form submission proceeds as normal if all the event handlers registered for the submit event either return true or don’t return a value. As you can see, the asynchronous page postback mechanism of the ASP.NET AJAX client-side framework does not apply to cross-page postback requests. This means that these requests proceed as usual with no intervention from the ASP.NET AJAX framework: var form = this._form; if (form.action !== form._initialAction) return;
Next, the _onFormSubmit method checks whether the current request is an asynchronous page postback. If not, it simply returns, which means that the form submission proceeds as usual: the page is synchronously posted back to the server and the entire page is re-rendered when the server response arrives: if (!this._postBackSettings.async) return;
As you can see, the ASP.NET AJAX client-side framework falls back to the normal page postback for synchronous requests. If the current request is neither a cross-page nor a normal synchronous page postback, the _onSubmitForm method takes complete control over the submission of the values of the form elements, bypassing the normal form submission mechanism and taking the following steps. First it creates a StringBuilder to accumulate the strings that will constitute the body of the asynchronous Web request being made to the server, where each string will contain the value of a form element. Therefore, each string consists of two parts separated by an equals sign (=), the first part being a string that normally contains the value of the name HTML attribute of the form element and the second part being a string that contains the value of the form element. Keep in mind that every server control renders its UniqueID property value as the value of the name HTML attribute of its associated HTML element. For example, the DropDownList server control renders its UniqueID property value as the value of the name HTML attribute of its associated HTML element: var formBody = new Sys.StringBuilder();
The first part of the first string contains the value of the UniqueID property of the current ScriptManager server control and the second part of the first string contains the value of the panelID property of the postback settings object: formBody.append(this._scriptManagerID + ‘=’ + this._postBackSettings.panelID + ‘&’);
1085
c22.indd 1085
8/20/07 8:38:24 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Next, the _onFormSubmit method iterates through the form elements and takes the following steps for each enumerated element. If the element is a text, password, hidden, checkbox, or radio input form element, the _onFormSubmit method appends a string that consists of two parts: the first contains the name of the element and the second contains its value: if (tagName === ‘INPUT’) { var type = element.type; if ((type === ‘text’) || (type === ‘password’) || (type === ‘hidden’) || (((type === ‘checkbox’) || (type === ‘radio’)) && element.checked)) { formBody.append(name); formBody.append(‘=’); formBody.append(encodeURIComponent(element.value)); formBody.append(‘&’); } }
If the enumerated form element is a select input element, the _onFormSubmit method iterates through the options collection of the element and creates one string for each selected option, the first part of the string containing the name of the select element and the second part containing the option value: else if (tagName === ‘SELECT’) { var optionCount = element.options.length; for (var j = 0; j < optionCount; j++) { var option = element.options[j]; if (option.selected) { formBody.append(name); formBody.append(‘=’); formBody.append(encodeURIComponent(option.value)); formBody.append(‘&’); } } }
If the form input element is a textarea, the _onFormSubmit method appends a string that consists of two parts, the first containing the name of the element and the second part containing its value: else if (tagName === ‘TEXTAREA’) { formBody.append(name); formBody.append(‘=’); formBody.append(encodeURIComponent(element.value)); formBody.append(‘&’); } }
If there’s additional information that needs to be sent to the server, the _onSubmitForm method appends this information as well:
1086
c22.indd 1086
8/20/07 8:38:24 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager if (this._additionalInput) { formBody.append(this._additionalInput); this._additionalInput = null; }
So far, you’ve populated the StringBuilder object with a bunch of strings, each of which contains the value of a specific input form element. Next, the _onSubmitForm method creates a WebRequest object to represent the current asynchronous Web request: var request = new Sys.Net.WebRequest();
Next, it specifies the target URL for the current request: request.set_url(form.action);
Then it adds a header named ‘X-MicrosoftAjax’ and sets its value to ‘Delta=true’ to signal the server-side PageRequestManager instance that the current request is an asynchronous page postback: request.get_headers()[‘X-MicrosoftAjax’] = ‘Delta=true’;
Next, the _onFormSubmit method adds a header named ‘Cache-Control’ and sets its value to ‘no-cache’ to signal the server that it mustn’t cache the response, because the current request is an asynchronous page postback: request.get_headers()[‘Cache-Control’] = ‘no-cache’;
Next, it specifies the request timeout. If the server response does not arrive within the specified time, the WebRequest will abort the current request: request.set_timeout(this._asyncPostBackTimeout);
Then it calls the createDelegate static method on the Function to create a delegate that represents the _onFormSubmitCompleted method of the current PageRequestManager instance and registers this delegate as an event handler for the completed event of the WebRequest object. This object will automatically call this delegate and consequently the _onFormSumitCompleted method when the server response finally arrives: request.add_completed(Function.createDelegate(this, this._onFormSubmitCompleted));
Next, the _onFormSubmit method populates the body of the current request with the content of the StringBuilder object. Recall that this object accumulated the strings that contain the values of the form elements. In other words, the values of the form elements will be sent to the server in the body of the request: request.set_body(formBody.toString());
Next, the _onFormSubmit method calls the getHandler method on the EventHandlerList object that contains all the event handlers registered for the events of the current PageRequestManager instance, in order to return a reference to a JavaScript function whose invocation automatically invokes all the event handlers registered for the initializeRequest event of the current PageRequestManager instance:
1087
c22.indd 1087
8/20/07 8:38:25 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager var handler = this._get_eventHandlerList().getHandler(“initializeRequest”);
Then the _onFormSubmit method creates an instance of an ASP.NET AJAX class named InitializeRequestEventArgs, passing in a reference to the WebRequest object that represents the current request and the DOM element that caused the postback. As you’ll see later in this chapter, InitializeRequestEventArgs is the event data class for the initializeRequest event of the current PageRequestManager instance: var eventArgs = new Sys.WebForms.InitializeRequestEventArgs(request, this._postBackSettings.sourceElement);
Then, it invokes the previously mentioned JavaScript function, passing in a reference to the current PageRequestManager and InitializeRequestEventArgs instances. Invoking this JavaScript function automatically invokes the event handlers registered for the initializeRequest event of the current PageRequestManager instance, passing in the same two references — that is, a reference to the current PageRequestManager instance and a reference to the InitializeRequestEventArgs instance: handler(this, eventArgs);
If you register an event handler for the initializeRequest event of the current PageRequestManager instance, your event handler will receive the two references previously mentioned. Your handler can then use these two references to get the complete information about the current request and use this information to determine whether the execution of the current request will violate application-specific business rules. If so, your event handler must call the set_cancel method on the InitializeRequestEventArgs object to ask the current PageRequestManager instance to cancel the current request. Next, the _onSubmitForm method checks whether any of the event handlers has requested the cancellation of the current request: continueSubmit = !eventArgs.get_cancel();
If so, the method invokes the preventDefault method on the DomEvent object that represents the current submit event to abort the form submission: if (!continueSubmit) { if (evt) evt.preventDefault(); return; }
Next, the _onFormSubmit method stores the current scroll position in a field named _scrollPosition for future use. As you’ll see later, when the server response finally arrives, the current PageRequestManager instance will compare the new scroll position with the old one to determine whether the scroll position has changed: this._scrollPosition = this._getScrollPosition();
1088
c22.indd 1088
8/20/07 8:38:25 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Then the _onFormSubmit method calls the abortPostBack method on the current PageRequestManager instance to abort any ongoing requests. This ensures two things. First, only the latest request takes effect. Second, you don’t exhaust the browser’s two-connections-per-server limit: this.abortPostBack();
Then the _onFormSubmit method calls the getHandler method on the EventHandlerList that contains all the event handlers registered for the events of the current PageRequestManager instance, in order to return a reference to the JavaScript function whose invocation automatically invokes all the event handlers registered for the beginRequest event of the current PageRequestManager instance: handler = this._get_eventHandlerList().getHandler(“beginRequest”);
Next, it creates an instance of the BeginRequestEventArgs class, passing in a reference to the WebRequest object that represents the current request and a reference to the DOM element that causes the current form submission. As you’ll see later in this chapter, BeginRequestEventArgs is the event data class for the beginRequest event of the PageRequestManager: var eventArgs = new Sys.WebForms.BeginRequestEventArgs(request, this._postBackSettings.sourceElement);
Then it invokes the previously mentioned JavaScript function, and consequently invokes the event handlers registered for the beginRequest event passing in a reference to the current PageRequestManager instance and a reference to the BeginRequestEventArgs class: handler(this, eventArgs);
If you register an event handler for the beginRequest event of the current PageRequestManager instance, your event handler will receive the two references previously mentioned. Your handler can then use these two references to get the complete information about the current request and use this information to perform application-specific request-beginning tasks. Next, for future use, the _onSubmitForm method stores the reference to the WebRequest object that represents the current request in a private field of the current PageRequestManager instance named _request: this._request = request;
Then, to submit the request to the server, the method calls the invoke method on the WebRequest object that represents the current request: request.invoke();
Finally, the method calls the preventDefault method on the DomEvent object that represents the current submit event of the form, in order to prevent the form from performing a regular synchronous page postback to the server: evt.preventDefault();
Figure 22-8 contains a diagram that shows all the method calls involved in making an asynchronous page postback request.
The initialize Request Event As you can see from Figure 22-8, the current client-side PageRequestManager instance fires its initializeRequest event right after completing the instantiation and initialization of the WebRequest object that represents the current asynchronous page postback request. This enables you to do the following:
❑
Perform application-specific tasks that must be performed right after the WebRequest object is instantiated and initialized.
❑
Run application-specific validation logic to determine whether the current form submission violates any application-specific rules. If so, you can have the current PageRequestManager instance abort the request.
1090
c22.indd 1090
8/20/07 8:38:26 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager The client-side PageRequestManager class uses the standard ASP.NET AJAX event implementation pattern to implement its initializeRequest event as follows:
1.
The class defines a method named add_initializeRequest that enables you to register event handlers for the initializeRequest event of the current client-side PageRequestManager instance. As the following code fragment shows, this method first calls the get_eventHandlerList method on the current PageRequestManager instance to return a reference to the EventHandlerList object that contains all the event handlers registered for the events of the current PageRequestManager instance. Then the add_initializeRequest method calls the addHandler method on this EventHandlerList object to register the specified handler as an event handler for the initializeRequest event of the current PageRequestManager instance:
function Sys$WebForms$PageRequestManager$add_initializeRequest(handler) { this._get_eventHandlerList().addHandler(“initializeRequest”, handler); }
2.
The class defines a method named remove_initializeRequest that enables you to unregister an event handler registered for the initializeRequest event of the instance:
function Sys$WebForms$PageRequestManager$remove_initializeRequest(handler) { this._get_eventHandlerList().removeHandler(“initializeRequest”, handler); }
The initializeRequest event, like any other, is associated with an event data class whose instance acts as a container for the associated event data. The event data class associated with the initializeRequest event is an ASP.NET AJAX client class named InitializeRequestEventArgs. Listing 22-22 presents the internal implementation of the InitializeRequestEventArgs class.
Listing 22-22: The InitializeRequestEventArgs Class Sys.WebForms.InitializeRequestEventArgs = function Sys$WebForms$InitializeRequestEventArgs(request, postBackElement) { /// /// Sys.WebForms.InitializeRequestEventArgs.initializeBase(this); this._request = request; this._postBackElement = postBackElement; } function Sys$WebForms$InitializeRequestEventArgs$get_postBackElement() { /// return this._postBackElement; }
As you can see, the constructor of the InitializeRequestEventArgs event data class takes two parameters, the first referencing the WebRequest object that represents the current asynchronous page postback request being made, and the second referencing the DOM element that caused the current asynchronous page postback. This constructor assigns these parameters to two internal fields named _request and _postBackElement: this._request = request; this._postBackElement = postBackElement;
Note that the InitializeRequestEventArgs class exposes two getters named get_request and get_postBackElement that return references to these two fields. As Listing 22-22 shows, the InitializeRequestEventArgs class derives from the CancelEventArgs base class: Sys.WebForms.InitializeRequestEventArgs.registerClass( ‘Sys.WebForms.InitializeRequestEventArgs’, Sys.CancelEventArgs);
Because of this, the InitializeRequestEventArgs class inherits the get_cancel and set_cancel methods from the CancelEventArgs base class. As you’ll see later, an event handler registered for the initializeRequest event of the current PageRequestManager instance can call the set_cancel method, passing in true as its argument to request the current PageRequestManager instance to cancel the request.
Using the initializeRequest Event Listing 22-23 contains a page that handles the initializeRequest event of the current PageRequestManager instance. If you run this page you should see the result shown in Figure 22-6. Now, if you click on the Parent UpdatePanel Trigger button shown in Figure 22-6, you should get the popup shown in Figure 22-9.
1092
c22.indd 1092
8/20/07 8:38:26 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Listing 22-23: A Page that Uses the initializeRequest Event void Page_Load(object sender, EventArgs e) { Label parentUpdatePanelLabel = (Label)Page.FindControl(“ParentUpdatePanelLabel”); parentUpdatePanelLabel.Text = “UpdatePanel refreshed at “ + DateTime.Now.ToString(); Label staticChildUpdatePanelLabel = (Label)Page.FindControl(“StaticChildUpdatePanelLabel”); staticChildUpdatePanelLabel.Text = “UpdatePanel refreshed at “ + DateTime.Now.ToString(); UpdatePanel dynamicChildUpdatePanel = new UpdatePanel(); dynamicChildUpdatePanel.ID = “DynamicChildUpdatePanel”; Table table = new Table(); table.BackColor = Color.FromArgb(90, 90, 90); table.ForeColor = Color.FromName(“White”); TableRow headerRow = new TableRow(); table.Rows.Add(headerRow); TableHeaderCell headerCell = new TableHeaderCell(); headerCell.Text = “Dynamic Child UpdatePanel Control”; headerRow.Cells.Add(headerCell); TableRow bodyRow = new TableRow(); table.Rows.Add(bodyRow); TableCell bodyCell = new TableCell(); bodyRow.Cells.Add(bodyCell); Label label = new Label(); label.ID = “DynamicChildUpdatePanelLabel”; label.Text = “UpdatePanel refreshed at “ + DateTime.Now.ToString() + “ ”; bodyCell.Controls.Add(label); Button button = new Button(); button.Text = “Update”; button.ID = “DynamicChildUpdatePanelButton”; button.Click += new EventHandler(button_Click); bodyCell.Controls.Add(button); dynamicChildUpdatePanel.ContentTemplateContainer.Controls.Add(table); PlaceHolder1.Controls.Add(dynamicChildUpdatePanel); } void button_Click(object sender, EventArgs e) { Label label = (Label)Page.FindControl(“DynamicChildUpdatePanelLabel”); label.Text = “UpdatePanel refreshed at “ + DateTime.Now.ToString() + “ ”; }
(continued)
1093
c22.indd 1093
8/20/07 8:38:26 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Listing 22-23 (continued) Untitled Page function pageLoad() { var prm = Sys.WebForms.PageRequestManager.getInstance(); prm.remove_initializeRequest(initializeRequestHandler); prm.add_initializeRequest(initializeRequestHandler); } function initializeRequestHandler(sender, e) { var request = e.get_request(); var postBackElement = e.get_postBackElement(); var builder = new Sys.StringBuilder(); builder.append(“Postback Element: “); builder.append(postBackElement.id); builder.appendLine(); builder.appendLine(); builder.append(“Request Target URL: “); builder.appendLine(); builder.append(request.get_url()); builder.appendLine(); builder.appendLine(); builder.append(“Request Headers: “); builder.appendLine(); var headers = request.get_headers(); var headerValue; for (var headerName in headers) { builder.append(headerName); builder.append(“ = ‘”); headerValue = headers[headerName]; builder.append(headerValue); builder.append(“’”); builder.appendLine(); } builder.appendLine(); builder.append(“Request Timeout: “); builder.append(request.get_timeout()); builder.appendLine(); builder.appendLine(); builder.append(“Request Body: “); builder.appendLine(); builder.append(request.get_body());
1094
c22.indd 1094
8/20/07 8:38:27 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager builder.appendLine(); alert(builder.toString()); }
Parent UpdatePanel Control
Static Child UpdatePanel Control
(continued)
1095
c22.indd 1095
8/20/07 8:38:27 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Listing 22-23 (continued)
Now let’s walk through the pageLoad method shown in Listing 22-23. function pageLoad() { var prm = Sys.WebForms.PageRequestManager.getInstance(); prm.remove_initializeRequest(initializeRequestHandler); prm.add_initializeRequest(initializeRequestHandler); }
As you can see, this method first calls the getInstance static method on the PageRequestManager class to return a reference to the current PageRequestManager instance: var prm = Sys.WebForms.PageRequestManager.getInstance();
Next, it calls the add_initializeRequest method on the current PageRequestManager instance to register the initializeRequestHandler JavaScript function as an event handler for the initializeRequest event of the current PageRequestManager instance: prm.add_initializeRequest(initializeRequestHandler);
1096
c22.indd 1096
8/20/07 8:38:27 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager
Figure 22-9
Next I’ll walk you through the implementation of the initializeRequestHandler JavaScript function. Note that this method takes two parameters, the first referencing the current PageRequestManager instance, and the second referencing the InitializeRequestEventArgs object that contains the event data for the initializeRequest event. As you can see from Listing 22-23, this initializeRequestHandler function first invokes the get_request method on the InitializeRequestEventArgs object to return a reference to the WebRequest object that represents the current asynchronous page postback request being made to the server: var request = e.get_request();
Next, it invokes the get_postBackElement method on the InitializeRequestEventArgs object to return a reference to the DOM element that caused the current page postback: var postBackElement = e.get_postBackElement();
1097
c22.indd 1097
8/20/07 8:38:28 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Then it instantiates a StringBuilder: var builder = new Sys.StringBuilder();
Next, the initializeRequestHandler function appends a string that contains the value of the id HTML attribute of the DOM element that caused the current page postback to the StringBuilder: builder.append(“Postback Element: “); builder.append(postBackElement.id); builder.appendLine(); builder.appendLine();
Then it invokes the get_url method on the WebRequest object that represents the current request to return a string that contains the target URL and appends a string that contains this target URL to the StringBuilder: builder.append(“Request Target URL: “); builder.appendLine(); builder.append(request.get_url()); builder.appendLine(); builder.appendLine();
Next, it invokes the get_headers method on the WebRequest object to return a dictionary that contains the names and values of the headers of the current request: builder.append(“Request Headers: “); builder.appendLine(); var headers = request.get_headers();
Then the initializeRequestHandler function iterates through the items in the dictionary and adds to the StringBuilder a string for each item that contains the name and value of the associated header: var headerValue; for (var headerName in headers) { builder.append(headerName); builder.append(“ = ‘”); headerValue = headers[headerName]; builder.append(headerValue); builder.append(“’”); builder.appendLine(); }
Next, it invokes the get_timeout method on the WebRequest object to return the request timeout value, and appends a string that contains this value to the StringBuilder: builder.appendLine(); builder.append(“Request Timeout: “); builder.append(request.get_timeout()); builder.appendLine(); builder.appendLine();
1098
c22.indd 1098
8/20/07 8:38:28 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Then it calls the get_body method on the WebRequest object to return a string that contains the body of the current request and appends that string to the StringBuilder: builder.append(“Request Body: “); builder.appendLine(); builder.append(request.get_body()); builder.appendLine();
Finally, it calls the alert function to display a popup that contains the content of the StringBuilder: alert(builder.toString());
One of the great things about the initializeRequest event is that it is cancelable. This enables you to register a callback for this event whereby you can run application-specific validation code to determine whether the current request should be aborted. If so, your callback can invoke the set_cancel method on the InitializeRequestEventArgs object, passing in true as its argument, to have the current PageRequestManager instance abort the current request.
The begin Request Event As you can see from Figure 22-8, the current client-side PageRequestManager instance fires its beginRequest event right before it calls the invoke method on the WebRequest object that represents the current asynchronous page postback request to begin the request, to enable you to perform application-specific tasks that must be performed right before the request is made to the server. The client-side PageRequestManager class uses the standard ASP.NET AJAX event-implementation pattern to implement its beginRequest event, as follows:
1.
PageRequestManager defines a method named add_beginRequest that enables you to register event handlers for the beginRequest event of the current client-side PageRequestManager
instance. As the following code fragment shows, this method first calls the get_eventHandlerList method on the current PageRequestManager instance to return a reference to the EventHandlerList object that contains all the event handlers registered for the events of the current PageRequestManager instance. Then it calls the addHandler method on this EventHandlerList object to register the specified handler as event handler for the beginRequest event of the current PageRequestManager instance: function Sys$WebForms$PageRequestManager$add_beginRequest(handler) { this._get_eventHandlerList().addHandler(“beginRequest”, handler); }
2.
PageRequestManager defines a method named remove_beginRequest that enables you to unregister an event handler registered for the beginRequest event of the instance:
function Sys$WebForms$PageRequestManager$remove_beginRequest(handler) { this._get_eventHandlerList().removeHandler(“beginRequest”, handler); }
1099
c22.indd 1099
8/20/07 8:38:28 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager The beginRequest event, like any other, is associated with an event data class whose instance acts as a container for the associated event data. The event data class associated with the beginRequest event is an ASP.NET AJAX client class named beginRequestEventArgs. Listing 22-24 presents the internal implementation of the beginRequestEventArgs class. As you can see, the constructor of the beginRequestEventArgs event data class takes two parameters, the first referencing the WebRequest object that represents the current asynchronous page postback request being made, and the second referencing the DOM element that caused the current asynchronous page postback. This constructor assigns these parameters to two internal fields named _request and _postBackElement: this._request = request; this._postBackElement = postBackElement;
Note that the beginRequestEventArgs class exposes two getters named get_request and get_postBackElement that return references to these two fields.
Listing 22-24: The beginRequestEventArgs Class Sys.WebForms.BeginRequestEventArgs = function Sys$WebForms$BeginRequestEventArgs(request, postBackElement) { /// /// Sys.WebForms.BeginRequestEventArgs.initializeBase(this); this._request = request; this._postBackElement = postBackElement; } function Sys$WebForms$BeginRequestEventArgs$get_postBackElement() { /// return this._postBackElement; } function Sys$WebForms$BeginRequestEventArgs$get_request() { /// return this._request; } Sys.WebForms.BeginRequestEventArgs.prototype = { get_postBackElement: Sys$WebForms$BeginRequestEventArgs$get_postBackElement, get_request: Sys$WebForms$BeginRequestEventArgs$get_request } Sys.WebForms.BeginRequestEventArgs.registerClass( ‘Sys.WebForms.BeginRequestEventArgs’, Sys.EventArgs);
1100
c22.indd 1100
8/20/07 8:38:29 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager
Using the beginRequest Event Listing 22-25 contains a page that uses the beginRequest event. If you run this page, you’ll see the result shown in Figure 22-10. If you click the Update button, you’ll see the result shown in Figure 22-11. As you can see, Figure 22-11 displays the latest two refresh times. This very simple example will teach you an important technique that you can use in your own applications to perform complex tasks.
Listing 22-25: A Page that Uses the beginRequest Event void Page_Load(object sender, EventArgs e) { if (Request.Form[“OldTime”] != null) info.Text = “UpdatePanel refreshed at “ + Request.Form[“OldTime”]; Label updatePanelLabel = (Label)Page.FindControl(“UpdatePanelLabel”); updatePanelLabel.Text = “UpdatePanel refreshed at “ + DateTime.Now.ToString(); } Untitled Page function pageLoad() { var prm = Sys.WebForms.PageRequestManager.getInstance(); prm.remove_beginRequest(beginRequestHandler); prm.add_beginRequest(beginRequestHandler); } function beginRequestHandler(sender, e) { var request = e.get_request(); var postBackElement = e.get_postBackElement(); var body = request.get_body(); var updatePanelLabel = $get(“UpdatePanelLabel”); var oldTime = updatePanelLabel.innerText.slice(25); var body2 = body.concat(“&OldTime=”+oldTime); request.set_body(body2); }
(continued)
1101
c22.indd 1101
8/20/07 8:38:29 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Listing 22-25 (continued)
Next, we’ll walk through the implementation of this page, beginning with the pageLoad function: function pageLoad() { var prm = Sys.WebForms.PageRequestManager.getInstance(); prm.remove_beginRequest(beginRequestHandler); prm.add_beginRequest(beginRequestHandler); }
Figure 22-10
1102
c22.indd 1102
8/20/07 8:38:29 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager
Figure 22-11
As you can see, this function first invokes the getInstance static method on the PageRequestManager class to return a reference to the current PageRequestManager instance: var prm = Sys.WebForms.PageRequestManager.getInstance();
Next, it calls the add_beginRequest method on the current PageRequestManager instance to register the beginRequestHandler JavaScript function as an event handler for the beginRequest event of the current PageRequestManager instance: prm.add_beginRequest(beginRequestHandler);
Now let’s walk through the implementation of the beginRequestHandler function: function beginRequestHandler(sender, e) { var request = e.get_request(); var body = request.get_body(); var updatePanelLabel = $get(“UpdatePanelLabel”); var oldTime = updatePanelLabel.innerText.slice(25); var body2 = body.concat(“&OldTime=”+oldTime); request.set_body(body2); }
This function begins by calling the get_request method on the BeginRequestEventArgs object to return a reference to the WebRequest object that represents the current request. Recall that when the current PageRequestManager instance invokes the beginRequestHandler function, it passes the BeingRequestEventArgs object containing the event data as the second parameter of this function. var request = e.get_request();
Next, the beginRequestHandler function calls the get_body method on the WebRequest object to return a string that contains the body of the current request: var body = request.get_body();
1103
c22.indd 1103
8/20/07 8:38:29 PM
Chapter 22: ASP.NET AJAX Client-Side PageRequestManager Then it calls the $get global JavaScript function to return a reference to the UpdatePanelLabel DOM element: var updatePanelLabel = $get(“UpdatePanelLabel”);
Next, it extracts the old time from the innerText property of the UpdatePanelLabel DOM element. Twenty-five is the number of characters in the string UpdatePanel refreshed at, which precedes the time: var oldTime = updatePanelLabel.innerText.slice(25);
Then it concatenates a string with the format &name=value, where the name part will be used on the server side to access the value part. As you can see, the name part contains the string OldTime (you can use any string value you wish as long as it is different from the values of the name parts of other name/value pairs in the body of request) and the value part contains the old time: var body2 = body.concat(“&OldTime=”+oldTime);
Finally, it calls the set_body method on the WebRequest object to set the body of the request to the new value: request.set_body(body2);
As you can see from Listing 22-25, when the current asynchronous page postback request arrives on the server side, the Page_Load method is invoked: void Page_Load(object sender, EventArgs e) { if (Request.Form[“OldTime”] != null) info.Text = “UpdatePanel refreshed at “ + Request.Form[“OldTime”]; Label updatePanelLabel = (Label)Page.FindControl(“UpdatePanelLabel”); updatePanelLabel.Text = “UpdatePanel refreshed at “ + DateTime.Now.ToString(); }
As you can see, this method uses the string OldTime as an index into the Form collection of the Request object to return the old time, which is then displayed in an ASP.NET Label server control.
Summar y This chapter followed the current client-side PageRequestManager instance as it made an asynchronous page postback to the server. The next chapter will move on to the server side, where we will follow this asynchronous page postback request from the time it arrives in ASP.NET to the time the server response text is finally sent back to the client.
1104
c22.indd 1104
8/20/07 8:38:30 PM
Asynchronous Par tial Page Rendering: Ser ver Side Processing The previous chapter followed the current client-side PageRequestManager instance as it made an asynchronous page postback or partial-page-rendering request to the server. This chapter will move on to the server side to follow the asynchronous page postback request from the time it arrives in ASP.NET to the time the final response text is sent back to the server. Chapter 21 followed the Page object as it went through its life cycle phases to process the first request made to a Web page enabled for partial page rendering. Since the first request wasn’t a postback, the Page object skipped the postback-related life cycle phases when it was processing the first request. This chapter, on the other hand, follows the current Page object as it goes through its life cycle phases to process an asynchronous page postback request to the same page that the first request downloaded. Since an asynchronous page postback is a postback request, the current Page will go through both postback and non-postback life cycle phases, shown in Listing 21-1 and Figure 21-2. Since the non-postback life cycle phases were discussed thoroughly in Chapter 21, I’ll discuss only the postback-related life cycle phases in this chapter.
RetrievePostData This is the life cycle phase in which the Page object populates an internal collection of type NameValueCollection named _requestValueCollection with the posted data, as shown in Listing 23-1. As such, this phase makes sense for postback requests — whether synchronous or asynchronous.
c23.indd 1105
8/20/07 8:41:21 PM
Chapter 23: Asynchronous Partial Page Rendering Listing 23-1: The RetrievePostData Method of the Page Object private void RetrievePostData() { if (this._request.HttpVerb == HttpVerb.POST && this._request.HasForm) this._requestValueCollection = this._request.Form; else if (this._request.HasQueryString) this._requestValueCollection = this._request.QueryString; }
Depending on the HTTP verb used to make a request, the clients of a page will use one of the following two approaches to submit data to the server. If the HTTP POST verb is used to make a request, the clients of the page include the data in the body of the request. The data consists of a list of data items separated by the & character, each of which consists of two parts separated by the equals sign (=). The first part of each data item helps the server determine what type of information the item contains. The second part of each data item contains the actual data or information being submitted. As an example, consider the ASP.NET page shown in Listing 23-2. As you can see, this page contains a TextBox and a DropDownList server control. Every ASP.NET server control inherits a property named UniqueID from the Control base class. The value of this property is automatically set by ASP.NET when the page containing the server control is accessed. This value is a string that contains one or more substrings separated by the dollar sign, of which the first substring contains the value of the ID property of the control and the subsequent substrings contain the values of the UniqueID properties of those parent controls of the control that implement the INamingContainer interface. In the case of Listing 23-2, none of the parent controls of the TextBox and DropDownList server controls (other than the Page itself whose UniqueID property returns an empty string) implements this interface, which means that ASP.NET sets the values of the UniqueID properties of these two server controls to the respective values of their ID properties. You may be wondering what the significance of the UniqueID property of a server control is. As the name suggests, this property uniquely identifies the server control among other server controls on the current page.
Listing 23-2: A Page that Contains a TextBox and a DropDownList Server Control Untitled Page
1106
c23.indd 1106
8/20/07 8:41:22 PM
Chapter 23: Asynchronous Partial Page Rendering
When the browser accesses this page, it receives the HTML markup text shown in Listing 23-3. Each server control renders the value of its UnqiueID property as the value of the name attribute of the HTML element that represents the control. Therefore, the TextBox and DropDownList server controls render the values of their UniqueID properties as the values of the name attributes of the input and select HTML elements, respectively, as shown in the boldface portions of the following code listing: Text1 Text2 Text3
Listing 23-3: The HTML Markup Text Sent to the Client Untitled Page Text1 Text2 Text3
Now imagine that the end user enters the string MyText into the text field, selects the Text2 option from the select element, and clicks the Submit button. The browser retrieves the following information:
❑
The value of the name HTML attribute of the text field — that is, the string “TextBox1”. Recall that this value is the value of the UniqueID property of the TextBox server control.
❑
The value of the name HTML attribute of the select HTML element — that is, the string “DropDownList1”. Recall that this value is that of the UniqueID property of the DropDownList server control.
1107
c23.indd 1107
8/20/07 8:41:22 PM
Chapter 23: Asynchronous Partial Page Rendering ❑
The string that the end user has entered into the text field — that is, the string MyText.
❑
The value of the value HTML attribute of the selected option of the select HTML element — that is, the string “Value2”.
Therefore, the data that the browser needs to send to the server consists of two data items. The first contains the string that the end user has entered into the text field, and the second contains the value of the value HTML attribute of the selected option of the select HTML element: TextBox1=MyText&DropDownList1=Value2
As you can see, each data item consists of two parts. The first part is the value of the UniqueID property of the server control and the second part is the value associated with the server control. The UniqueID property values allow ASP.NET to determine which data item is associated with which server control. So far, I’ve covered the case in which the client uses the HTTP POST verb to make its request to the server. The second scenario is when the client uses the HTTP GET verb. This scenario often involves e-commerce Web applications. For example, consider a page that displays the list of product names to the end users. When a user selects a product to see more details about it, the primary key values of the product and its distributor are passed as a query string to the server: http://www.mysite.com/Product.aspx?ProductID=2&DistributorID=3
As you can see, the query string consists of a list of data items separated by the ampersand character, each of which consists of two parts separated by the equals sign. ASP.NET represents each request with an instance of a class named HttpRequest, which exposes two collection properties of type NameValueCollection named Form and QueryString. ASP.NET automatically populates the Form collection with the posted data if the request was made using the HTTP POST verb; otherwise it populates the QueryString collection with the posted data. Keep in mind that we’re following the current Page through its life cycle phases to process the asynchronous page postback method that the current client-side PageRequestManager instance has made to the server. As we just discussed, the clients of a page have two options when it comes to submitting data to the server. Which option did the current client-side PageRequestManager instance use to submit its data to the server? The answer lies in Listing 22-22. Recall that this code listing presents the internal implementation of the _onFormSubmit method of the current client-side PageRequestManager instance. As we discussed in the previous chapter, this method is automatically invoked when a page postback occurs, allowing the current client-side PageRequestManager instance to intercept the page postback before the page is actually posted back to the server. The current client-side PageRequestManager instance then determines whether the page must be posted back asynchronously. If so, it takes over the form submission, bypassing the browser’s default synchronous form submission. As Listing 22-22 shows, the current client-side PageRequestManager instance iterates through all the input form elements on the current page, generates for each input form element one string that consists of two substrings separated by the equals sign (the first substring containing the value of the name HTML attribute of the form element and the second containing the value of the form element), and finally packs all these strings into a single string using the & character as the separator. Recall from Listing 22-22 that the current client-side PageRequestManager instance adds this string to the body of
1108
c23.indd 1108
8/20/07 8:41:22 PM
Chapter 23: Asynchronous Partial Page Rendering the request being made to the server. As you can see, the current client-side PageRequestManager instance submits its data to the server via the body of an HTTP POST request. Now back to the implementation of the RetrievePostData method of the Page object, as shown in Listing 23-1. Recall that the Page object calls this method when it enters the Retrieve Post Data life cycle phase. As this code listing shows, this method simply stores the content of the Form or QueryString collection of the HttpRequest object that represents the current request in an internal collection named _requestValueCollection. This collection contains one name/value pair for each posted data item. Recall that each posted data item consists of two parts separated by the equals sign. The name part of each name/value pair in this collection contains the first part of the data item and the value part contains the second part of the data item. This means that the first part of the data item can be used as an index into the collection to access the second part of the data item. For example, in the case of the examples discussed earlier, the following items are true:
❑
The UniqueID property value of the TextBox server control can be used as an index into the _requestValueCollection to access the text that the end user has entered into the text field:
The UniqueID property value of the DropDownList server control can be used as an index into the _requestValueCollection to access the value of the value HTML attribute of the selected option of the select HTML element associated with the server control:
Since the current Page is processing the asynchronous request shown in Listing 22-22, the _requestValueCollection of the current Page contains all the name/value pairs that Listing 22-22 stuffed into the body of the request.
LoadScrollPosition This is the life cycle phase in which the Page object retrieves the scroll x and y positions from the _requestValueCollection and assigns them to the _scrollPositionX and _scrollPositionY fields, respectively, as shown in Listing 23-4. As you’ll see later, the Page object uses these two fields to set the scroll position in the response text before submitting the response back to the client. This life cycle phase takes effect only if the MaintainScrollPositionOnPostBack property of the Page object has been set to true. As the name suggests, this property instructs the Page to maintain the scroll position on page postbacks — be they synchronous or asynchronous.
1109
c23.indd 1109
8/20/07 8:41:23 PM
Chapter 23: Asynchronous Partial Page Rendering Listing 23-4: The LoadScrollPosition Method of the Page Object Private void LoadScrollPosition() { if (this._requestValueCollection != null) { string text1 = this._requestValueCollection[“__SCROLLPOSITIONX”]; if ((text1 != null) && !int.TryParse(text1, out this._scrollPositionX)) this._scrollPositionX = 0; string text2 = this._requestValueCollection[“__SCROLLPOSITIONY”]; if ((text2 != null) && !int.TryParse(text2, out this._scrollPositionY)) this._scrollPositionY = 0; } }
Since the current Page is processing the asynchronous request made by the current client-side PageRequestManager instance, and since the _requestValueCollection contains only the name/ value pairs that the current client-side PageRequestManager instance stuffed into the body of the request, you may be wondering where the scroll x and y values come from. The answer lies in Listing 22-22 itself, which is partially repeated in the following code listing. Recall that this code listing contains the code for the _onFormSubmit method of the current client-side PageRequestManager instance. As discussed earlier, this method is automatically invoked when a postback occurs. As the highlighted portions of the following code listing show, the current client-side PageRequestManager instance iterates through all the input form elements on the page, including the hidden fields named __SCROLLPOSITIONX and __SCROLLPOSITIONY, and forms for each input form element one string that consists of two substrings, the first containing the value of the name HTML attribute of the input form element (in this case, these values are __SCROLLPOSITIONX and __SCROLLPOSITIONY) and the second containing the value of the value HTML attribute of the input form element (in this case, these values are the scroll x and y positions). As the boldface portion of the following code listing shows, the current client-side PageRequestManager instance stores the current scroll x and y positions in an internal field named _scrollPostion before it submits the request to the server. As you’ll see later, when the server response arrives, the current client-side PageRequestManager instance retrieves the new scroll x and y positions from the response and compares them with the old values stored in the _scrollPosition field to determine whether the scroll x and y positions have indeed changed. function Sys$WebForms$PageRequestManager$_onFormSubmit(evt) { . . . if (tagName === ‘INPUT’) { var type = element.type; if ((type === ‘text’) || (type === ‘password’) || (type === ‘hidden’) || (((type === ‘checkbox’) || (type === ‘radio’)) && element.checked)) { formBody.append(name); formBody.append(‘=’);
InitRecursive I covered the non-postback-related parts of the InitRecursive life cycle phase of the Page object in Chapter 21; therefore I’ll just cover the postback-related parts of this phase in this section. Recall from Chapter 21 that the OnInit method of the current ScriptManager instance is automatically invoked when the current Page enters its Init phase. Listing 23-5 presents the ScriptManager class’s internal implementation of the OnInit method, which it inherits from the Control base class. I discussed all the parts of Listing 23-6 in Chapter 21 except for the highlighted portion, which is applicable only to postback requests. As you can see, this portion calls the IsAsyncPostBackRequest static method on the server-side PageRequestManager, passing in the NameValueCollection that contains the names and values of the request headers. The main responsibility of this method is to determine whether the current request is an asynchronous page postback.
Listing 23-5: The OnInit Method of the ScriptManager Class protected override void OnInit(EventArgs e) { base.OnInit(e); if (ScriptManager.GetCurrent(this.Page) != null) throw new InvalidOperationException(“OnlyOneScriptManager”); this.IPage.Items[typeof(ScriptManager)] = this; this.IPage.PreRenderComplete += new EventHandler(this.OnPagePreRenderComplete); if (this.IPage.IsPostBack) this._isInAsyncPostBack = PageRequestManager.IsAsyncPostBackRequest(this.IPage.Request.Headers); this.PageRequestManager.OnInit(); }
The IsAsyncPostBackRequest Method of the PageRequestManager Listing 23-6 presents the internal implementation of this method. As you can see, the IsAsyncPostBackRequest method first calls the GetValues method on the NameValueCollection that contains the names and values of the request headers, in order to access all the values of the request header named “X-MicrosoftAjax”: string[] textArray1 = headers.GetValues(“X-MicrosoftAjax”);
1111
c23.indd 1111
8/20/07 8:41:23 PM
Chapter 23: Asynchronous Partial Page Rendering Then it iterates through these values searching for a value that contains the string “Delta=true”. If it finds a value that contains this string, it returns true to signal its caller that the current request is an asynchronous page postback. Listing 22-22 contains the client-side code that made the current asynchronous page postback. The following code listing repeats a portion of Listing 22-22. As the highlighted portion of the following code shows, the current client-side PageRequestManager instance added the “Delta=true” header value to a custom request header named “X-MicrosoftAjax” to signal the server-side PageRequestManager instance that the current request is an asynchronous page postback. function Sys$WebForms$PageRequestManager$_onFormSubmit(evt) { . . . var request = new Sys.Net.WebRequest(); request.set_url(form.action); request.get_headers()[‘X-MicrosoftAjax’] = ‘Delta=true’; request.get_headers()[‘Cache-Control’] = ‘no-cache’; . . . }
Listing 23-6: The IsAsyncPostBackRequest Static Method of the PageRequestManager Class internal static bool IsAsyncPostBackRequest(NameValueCollection headers) { string[] textArray1 = headers.GetValues(“X-MicrosoftAjax”); if (textArray1 != null) { for (int num1 = 0; num1 < textArray1.Length; num1++) { string[] textArray2 = textArray1[num1].Split(new char[] { ‘,’ }); for (int num2 = 0; num2 < textArray2.Length; num2++) { if (textArray2[num2].Trim() == “Delta=true”) return true; } } } return false; }
The OnInit Method of PageRequestManager Recall from Chapter 21 that the OnInit method of the current server-side PageRequestManager instance is automatically invoked when the Page object enters its Init life cycle phase. Listing 23-7 presents the internal implementation of the OnInit method of the server-side PageRequestManager. I covered all the parts of this method in Chapter 21, except for the highlighted portion, because this portion is run only when the current request is an asynchronous page postback. As you can see, this portion simply registers the OnPageError method of the current server-side PageRequestManager instance as an event handler for the Error event of the current Page object.
1112
c23.indd 1112
8/20/07 8:41:23 PM
Chapter 23: Asynchronous Partial Page Rendering Listing 23-7: The OnInit Method of the PageRequestManager Class internal void OnInit() { . . . if (this._owner.IsInAsyncPostBack) this._owner.IPage.Error += new EventHandler(this.OnPageError); }
Load Post Data Currently we’re at the Load Post Data life cycle phase, in which the ProcessRequest method (see Listing 21-1) invokes the ProcessPostData method of the current Page, passing in two parameters. The first parameter is the _requestValueCollection field of the current Page. Recall that this field is a collection of type NameValueCollection that contains one name/value pair for each posted data item, the name part containing the UniqueID property value of a server control and the value part containing the value associated with that server control. For example, the name part of the name/value pair associated with a TextBox server control contains the value of the UniqueID property of the TextBox control, and the value part contains the text that the end user has entered into the text field. As Listing 21-1 shows, the ProcessRequest method of the current Page passes true as the second argument of the ProcessPostData method to instruct this method that the Page is currently in a pre-Load life cycle phase. As you’ll see later, the same ProcessPostData method will also be called after the Load life cycle phase. The second Boolean argument allows this method to distinguish between these two calls. Listing 23-8 presents the internal implementation of the ProcessPostData method of the Page.
Listing 23-8: The ProcessPostData Method of the Page Object private void ProcessPostData(NameValueCollection postData, bool fBeforeLoad) { if (this._changedPostDataConsumers == null) this._changedPostDataConsumers = new ArrayList(); foreach (string text1 in postData) { if (!Page.IsSystemPostField(text1)) { Control control1 = this.FindControl(text1); if (control1 == null) { if (fBeforeLoad) { if (this._leftoverPostData == null) this._leftoverPostData = new NameValueCollection(); this._leftoverPostData.Add(text1, null); } } else { IPostBackDataHandler handler1 = control1 as IPostBackDataHandler;
(continued)
1113
c23.indd 1113
8/20/07 8:41:24 PM
Chapter 23: Asynchronous Partial Page Rendering Listing 23-8 (continued) if (handler1 == null) { if (control1 as IPostBackEventHandler != null) this.RegisterRequiresRaiseEvent(control1.PostBackEventHandler); } else { if (handler1.LoadPostData(text1, this._requestValueCollection)) this._changedPostDataConsumers.Add(control1); if (this._controlsRequiringPostBack != null) this._controlsRequiringPostBack.Remove(text1); } } } } ArrayList list1 = null; if (this._controlsRequiringPostBack != null) { foreach (string text2 in this._controlsRequiringPostBack) { Control control2 = this.FindControl(text2); if (control2 != null) { IPostBackDataHandler handler2 = control2 as IPostBackDataHandler; if (handler2.LoadPostData(text2, this._requestValueCollection)) this._changedPostDataConsumers.Add(control2); } else if (fBeforeLoad) { if (list1 == null) list1 = new ArrayList(); list1.Add(text2); } } this._controlsRequiringPostBack = list1; } }
This method first instantiates an ArrayList field named _changePostDataConsumers, if it hasn’t already been instantiated. You’ll see the significance of this field later. if (this._changedPostDataConsumers == null) this._changedPostDataConsumers = new ArrayList();
Next, it iterates through the name/value pairs in the NameValueCollection passed into it as its first argument, and takes the following actions for each enumerated name/value pair if the name part of the pair does not contain the name attribute value of one of the standard hidden fields such as __VIEWSTATE (the name/value pairs associated with standard hidden fields will be processed later):
❑
The ProcessPostData method calls the FindControl method on the current Page object to return a reference to the server control whose UniqueID property value is given by the name part of the enumerated name/value pair:
1114
c23.indd 1114
8/20/07 8:41:24 PM
Chapter 23: Asynchronous Partial Page Rendering Control control1 = this.FindControl(text1);
❑
If the current Page does not contain a server control with this UniqueID property value, this indicates that the server control has been dynamically added to the Page during the Page’s Load life cycle phase. For example, the page developers could add server controls to the current Page within the Page_Load method, which is invoked when the Page enters its Load life cycle phase. Since we’re currently at the Load Post Data life cycle phase, which occurs before the Load life cycle phase (see Figure 21-2), the ProcessPostData method does not process the enumerated name/value pair and instead stores the value of the name part of the pair in a collection named _leftOverPostData so that this name/value pair can be processed after the Load life cycle phase — that is, after the associated server control is added to the current Page: if (this._leftoverPostData == null) this._leftoverPostData = new NameValueCollection(); this._leftoverPostData.Add(text1, null);
❑
If the current Page contains a server control whose UniqueID property value is given by the name part of the enumerated name/value pair, the ProcessPostData method takes the following steps to process the enumerated name/value pair. First, it checks whether the server control implements the IPostBackDataEventHandler interface:
❑
If not, it checks whether the server control implements the IPostBackEventHandler interface. If so, it calls the RegisterRequiresRaiseEvent method of the current Page, passing in the server control. This method stores this server control in an internal field for future reference. As you’ll see later, when the current Page enters its RaisePostBackEvent life cycle phase, it will automatically call the RaisePostBackEvent method of this server control. In general, controls that implement the IPostBackEventHandler interface raise postback events. IPostBackDataHandler handler1 = control1 as IPostBackDataHandler; if (handler1 == null) { if (control1 as IPostBackEventHandler != null) this.RegisterRequiresRaiseEvent((IPostBackEventHandler)control1); }
❑
If so, it calls the LoadPostData method on the associated server control, passing in two parameters. The first parameter is the name part of the enumerated name/value pair, and the second parameter is the _requestValueCollection field. Recall that this field contains all the name/value pairs (or data items) that the client has posted back to the server.
❑
It is the responsibility of the LoadPostData method of the server control to use its first parameter as an index into the second parameter to retrieve the value of the value part of the associated name/value pair (or data item). For example, the LoadPostData method of an ASP.NET TextBox server control uses its UniqueID property value as an index into the _requestValueCollection to retrieve the text that the end user has entered into the text field. This method then compares this text with the value of the Text property of the TextBox control. If these two values are different, the end user has changed the original value of the text field. As a result, the LoadPostData method returns true to signal the ProcessPostData method that its value has changed and that therefore its RaisePostDataChangedEvent method must be invoked when the current Page enters its RaisePostDataChangedEvent life cycle phase (see Figure 21-2).
1115
c23.indd 1115
8/20/07 8:41:24 PM
Chapter 23: Asynchronous Partial Page Rendering ❑
Note that if the LoadPostData method returns true, the ProcessPostData method adds the server control to an internal collection named _changedPostDataConsumers. As you’ll see later, when the current Page object enters its RaisePostDataChangedEvent life cycle phase, it will iterate through the server controls in the _changedPostDataConsumers collection and invoke their RaisePostDataChangedEvent methods. if (handler1.LoadPostData(text1, this._requestValueCollection)) this._changedPostDataConsumers.Add(control1);
❑
Finally, the ProcessPostData method removes the current UniqueID property value from the _controlsRequiringPostBack collection. This collection maintains the UniqueID property values of those server controls whose RaisePostBackEvent methods must be called when the current Page enters the RaisePostBackEvent life cycle phase. this._controlsRequiringPostBack.Remove(text1);
Next, the ProcessPostData method iterates through the items in the _controlsRequiringPostBack collection. Recall that this collection contains the UniqueID property values of those server controls whose RaisePostBackEvent method must be invoked when the current Page enters the RaisePostBackEvent life cycle phase. The ProcessPostData method takes the following actions for each enumerated UniqueID property value in this collection:
❑
First, it calls the FindControl method on the current Page to return a reference to the server control with the enumerated UniqueID property value: Control control2 = this.FindControl(text2);
❑
If the current Page object contains a server control with the enumerated UniqueID property value, the ProcessPostData method calls the LoadPostData method on the server control, and if this method returns true, it adds the server control to the _changedPostDataConsumers collection: if (control2 != null) { IPostBackDataHandler handler2 = control2 as IPostBackDataHandler; if (handler2.LoadPostData(text2, this._requestValueCollection)) this._changedPostDataConsumers.Add(control2); }
❑
If the current page does not contain a server control with the enumerated UniqueID property value, the ProcessPostData method adds the server control to a local array, which is finally added to the _controlsRequiringPostBack collection: else if (fBeforeLoad) { if (list1 == null) list1 = new ArrayList(); list1.Add(text2); } } this._controlsRequiringPostBack = list1;
1116
c23.indd 1116
8/20/07 8:41:25 PM
Chapter 23: Asynchronous Partial Page Rendering
UpdatePanel As these discussions show, the Load Post Data life cycle phase of the current Page object is applicable only to those server controls that implement the IPostBackDataHandler interface. Since the current implementation of the UpdatePanel server control does not implement this interface, none of the UpdatePanel server controls on the current Page will participate in the current Page’s Load Post Data life cycle phase. However, you can write a custom UpdatePanel server control that inherits the UpdatePanel server control and implements the IPostBackDataHandler interface. If you do so, the current Page object will automatically call the LoadPostData method of your custom UpdatePanel server control, and if your implementation of this method returns true, the current Page object will also automatically call the RaisePostDataChangedEvent method of your custom control.
ScriptManager As the boldface portion of Listing 23-9 shows, the ScriptManager implements the IPostBackDataHandler interface. As I already mentioned, this interface exposes two methods named LoadPostData and RaisePostDataChangedEvent.
Listing 23-9: The Declaration of the ScriptManager Class [ParseChildren(true), DefaultProperty(“Scripts”), NonVisualControl, PersistChildren(false)] public class ScriptManager : Control, IPostBackDataHandler, IControl, IClientUrlResolver, IScriptManagerInternal { protected virtual bool LoadPostData(string postDataKey, NameValueCollection postCollection) { this.PageRequestManager.LoadPostData(postDataKey, postCollection); return false; } protected virtual void RaisePostDataChangedEvent() { } }
Since the ScriptManager server control implements the IPostBackDataHandler interface, when the current Page enters its Load Post Data life cycle phase, it automatically calls the LoadPostData method on the current ScriptManager server control, passing in two parameters. The first parameter is a string that contains the UniqueID property value of the current ScriptManager server control, and the second is the NameValueCollection that contains all the name/value pairs that the current ASP.NET AJAX client-side PageRequestManager instance has posted back to the server. As Listing 23-9 shows, the LoadPostData method of the ScriptManager delegates to the LoadPostData method of the current server-side PageRequestManager instance. Note that the LoadPostData method of the current ScriptManager instance passes the same two parameters that were passed into it into the LoadPostData method of the current server-side PageRequestManager instance.
1117
c23.indd 1117
8/20/07 8:41:25 PM
Chapter 23: Asynchronous Partial Page Rendering
The LoadPostData Method of PageRequestManager Listing 23-10 presents the internal implementation of the LoadPostData method of the server-side PageRequestManager. Recall that when the LoadPostData method of the current ScriptManager server control calls the LoadPostData method of the current server-side PageRequestManager instance, it passes two parameters into it. The first parameter is a string that contains the value of the UniqueID property of the current ScriptManager server control. The second parameter is the NameValueCollection that contains all the name/value pairs (each pair represents a posted data item) that the current client-side PageRequestManager instance has posted back to the server. Recall that Listing 22-22 presents the internal implementation of the _onFormSubmit method of the current client-side PageRequestManager instance. This method is where the current client-side PageRequestManager instance posts all its name/value pairs back to the server asynchronously. The following code listing repeats a portion of Listing 22-22: function Sys$WebForms$PageRequestManager$_onFormSubmit(evt) { . . . var formBody = new Sys.StringBuilder(); formBody.append(this._scriptManagerID + ‘=’ + this._postBackSettings.panelID + ‘&’); . . }
As the highlighted portion of this code listing shows, the current client-side PageRequestManager instance posts a name/value pair whose name part contains the UniqueID property value of the current ScriptManager server control, and whose value part contains the value of the panelID property of the postback settings JavaScript object. Recall that Listing 22-22 shows where the value of the panelID property of the postback settings JavaScript object is set. This code listing contains the implementation of the _getPostBackSettings method of the current client-side PageRequestManager instance. As discussed in Chapter 22, this method uses the following logic to set the value of the panelID property of the postback settings JavaScript object:
❑
If the server control that caused the current page postback resides in an UpdatePanel server control whose ChildrenAsTriggers property is set to true, the _getPostBackSettings method sets the value of the panelID property to a string that contains two substrings separated by the pipe character (|), of which the first substring contains the UniqueID property value of the UpdatePanel server control, and the second the UniqueID property value of the server control that caused the current page postback. As you’ll see shortly, the presence of the UniqueID property value of this UpdatePanel server control signals the current server-side PageRequestManager instance that this UpdatePanel server control must be updated.
When a page postback is caused by a server control that resides in an UpdatePanel server control whose ChildrenAsTriggers property is set to true, it automatically triggers the update of its parent UpdatePanel server control.
❑
If the _asyncPostBackControlIDs collection of the current client-side PageRequestManager instance contains the UniqueID property value of the server control that caused the current
1118
c23.indd 1118
8/20/07 8:41:25 PM
Chapter 23: Asynchronous Partial Page Rendering page postback, or one of its ancestor server controls, but the server control itself does not reside in an UpdatePanel server control whose ChildrenAsTrigger property is set to true, _getPostBackSettings sets the value of the panelID property to a string that contains two substrings separated by the | character: the first substring contains the UniqueID property value of the ScriptManager server control, and the second substring contains the UniqueID property value of the server control that caused the current page postback. Keep this logic in mind as we’re walking through the implementation of the LoadPostData method of the server-side PageReqeustManager. As you can see from Listing 23-10, this method first uses its first parameter, which is nothing but the UniqueID property value of the current ScriptManager server control, as an index into the NameValueCollection to return the associated posted string value data. string text1 = postCollection[postDataKey];
This string value consists of up to two substrings separated by the | character. As we discussed earlier, the second substring is the UniqueID property value of the server control that caused the current page postback. The LoadPostData method assigns this substring to the _asyncPostBackSourceElementID field for future reference. As we also discussed earlier, the first substring contains the value of the UniqueID property of either the ScriptManager server control or the UpdatePanel control whose content must be updated. If the substring does not contain the value of the UniqueID property of the ScriptManager server control — that is, if it contains the value of the UniqueID property of a specific UpdatePanel server control — the LoadPostData method assigns this substring to the _updatePanelRequestUpdate field: this._updatePanelRequiresUpdate = text2;
Next, the LoadPostData method iterates through all the UpdatePanel server controls on the current page and calls their Initialize methods. The server-side PageRequestManager maintains references to all the UpdatePanel server controls on the page in an internal collection named _allUpdatePanels. (The Initialize method of the UpdatePanel server control was thoroughly discussed in Chapter 21.) if ((this._allUpdatePanels != null) && (this._allUpdatePanels.Count != 0)) { List.Enumerator enumerator1 = this._allUpdatePanels.GetEnumerator(); while (enumerator1.MoveNext()) { enumerator1.Current.Initialize(); } }
Finally, the LoadPostData method sets an internal flag named _panelsInitialized to signal that all UpdatePanel controls on the page have been initialized: this._panelsInitialized = true;
1119
c23.indd 1119
8/20/07 8:41:26 PM
Chapter 23: Asynchronous Partial Page Rendering Listing 23-10: The LoadPostData Method of the PageRequestManager internal void LoadPostData(string postDataKey, NameValueCollection postCollection) { string postData = postCollection[postDataKey]; if (postData != null) { int separatorIndex = postData.IndexOf(‘|’); this._asyncPostBackSourceElementID = postData.Substring(separatorIndex + 1); string text = postData.Substring(0, separatorIndex); if (text != this._owner.UniqueID) this._updatePanelRequiresUpdate = text; } if ((this._allUpdatePanels != null) && (this._allUpdatePanels.Count != 0)) { List.Enumerator enumerator1 = this._allUpdatePanels.GetEnumerator(); while (enumerator1.MoveNext()) { enumerator1.Current.Initialize(); } } this._panelsInitialized = true; }
Figure 23-1 contains all the method calls that occur when the current Page object enters its Load Post Data life cycle phase. LoadPostData Page
The Raise Post Data Changed Event When the Page object enters its Raise Post Data Changed Event phase (see Figure 21-2), it calls the RaisePostDataChangedEvent methods of those server controls that meet the following two requirements:
❑
They implement the IPostBackDataHandler interface.
❑
Their implementation of the LoadPostData method returns true.
1120
c23.indd 1120
8/20/07 8:41:26 PM
Chapter 23: Asynchronous Partial Page Rendering The ScriptManager server control meets the first requirement. However, it does not meet the second requirement because its LoadPostData method returns false, as shown in Listing 23-9. Therefore, the RaisePostDataChangedEvent method of the ScriptManager server control is never invoked. As the following code listing shows, this method does not do anything anyway: protected virtual void RaisePostDataChangedEvent() { }
That said, you can implement a custom ScriptManager that extends the functionality of the ScriptManager server control, where its implementation of the LoadPostData method returns true, to have the Page object invoke its RaisePostDataChangedEvent. Your custom ScriptManager control’s implementation of this method can then take the appropriate actions in response.
PreRender The PreRender life cycle phase of the Page was thoroughly discussed in Chapter 21. In this section, I’ll focus only on the postback-related topics that weren’t covered in Chapter 21. As we discussed in Chapter 21, the OnPreRender method of the current ScriptManager server control is automatically invoked when the current page enters its PreRender life cycle phase. Listing 23-11 presents the internal implementation of the OnPreRender method of the ScriptManager server control. This method checks whether the current request is an asynchronous page postback. If so, it delegates to the OnPreRender method of the server-side PageRequestManager. This applies to the current request because the current request is indeed an asynchronous page postback.
Listing 23-11: The OnPreRender Method of the ScriptManager protected override void OnPreRender(EventArgs e) { base.OnPreRender(e); if (this.IsInAsyncPostBack) this.PageRequestManager.OnPreRender(); }
The OnPreRender Method of PageRequestManager Listing 23-12 presents the implementation of the OnPreRender method of the server-side PageRequestManager. The Page object, like any other server control, inherits a method named SetRenderMethodDelegate from the Control base class. This method registers a delegate of type RenderMethod that represents another method. In the case of Listing 23-12, the SetRenderMethodDelegate method registers a delegate that represents the RenderPageCallback method of the server-side PageRequestManager. As you’ll see later in this chapter, when the server control on which the SetRenderMethodDelegate method was invoked enters its rendering phase, in which its RenderChildren method is invoked, the RenderChildren method invokes the RenderMethod delegate, and consequently the method that the delegate represents, bypassing the normal rendering logic that renders the child controls of the server control.
1121
c23.indd 1121
8/20/07 8:41:26 PM
Chapter 23: Asynchronous Partial Page Rendering In the case of Listing 23-12, when the Page server control enters its rendering phase in which its RenderChildren method is called, the RenderChildren method will invoke the delegate that represents the RenderPageCallback method of the PageRequestManager, bypassing the normal rendering logic that renders the server controls in the Controls collection of the Page. This allows the server-side PageRequestManager to take complete control of the rendering of the server controls in the Controls collection of the Page object when the current request is an asynchronous page postback.
Listing 23-12: The OnPreRender Method of the PageRequestManager internal void OnPreRender() { RenderMethod renderMethod = new RenderMethod(this.RenderPageCallback); this._owner.IPage.SetRenderMethodDelegate(renderMethod); }
Rendering In this section, we’ll see what happens when the Page enters its rendering life cycle phase, in which the Render method of the Page is invoked. The Page inherits the Render method from the Control base class. Listing 23-13 presents the implementation of the Render method of the Control base class.
Listing 23-13: The Render Method of the Control Base Class protected internal override void Render(HtmlTextWriter writer) { this.RenderChildren(writer); }
As you can see, the Render method of the Control base class simply calls the RenderChildren method shown in Listing 23-14. Recall from Listing 23-12 that the OnPreRender method of the server-side PageRequestManager created a RenderMethod delegate that represents the RenderPageCallback method of the server-side PageRequestManager and invoked the SetRenderMethodDelegate method on the Page object, passing in this RenderMethod delegate. Every server control, including the Page object, inherits the RenderChildren method shown in Listing 23-14 from the Control base class. As you can see, the RenderChildren method of a server control first calls the GetRenderMethod to return a reference to the RenderMethod delegate registered with the server control, if any. In the case of the Page server control, since the current request is an asynchronous page postback, the GetRenderMethod returns a reference to the RenderMethod delegate that represents the PageRenderCallback method of the PageRequestManager. As Listing 23-14 shows, the RenderChildren method of a server control bypasses the normal rendering logic of the server control’s child controls if a RenderMethod delegate has been registered with the server control. As the boldface portion of Listing 23-14 shows, the normal rendering logic of the server control’s child controls simply iterates through the child controls in the server control’s Controls collection and invokes the RenderControl method on each enumerated child control. In the case of the Page server control, if the current request is an asynchronous page postback, the RenderChildren method invokes the registered RenderMethod delegate, which in turn invokes the
1122
c23.indd 1122
8/20/07 8:41:27 PM
Chapter 23: Asynchronous Partial Page Rendering PageRenderCallback method of the server-side PageRequestManager. The end result of all this is that the server-side PageRequestManager takes complete control over what gets rendered when the current request is an asynchronous page postback.
Listing 23-14: The RenderChildren Method of the Control Base Class protected internal virtual void RenderChildren(HtmlTextWriter writer) { RenderMethod renderMethod = this.GetRenderMethod(); if (renderMethod != null) { writer.BeginRender(); renderMethod(writer, this); writer.EndRender(); } else if (this.Controls != null) { foreach (Control control in this.Controls) { control.RenderControl(writer); } } }
The Encode Method of PageRequestManager Since the implementation of the RenderPageCallback method makes use of another method of PageRequestManager named EncodeString, I’ll discuss the implementation of this method first. Listing 23-15 presents the internal implementation of the EncodeString method of the server-side PageRequestManager. This method takes four parameters as follows, encodes the values of its second through fourth parameters into a string, and writes this encoded string into the TextWriter object referenced by its first parameter.
❑
writer: This parameter references the TextWriter instance in which the encoded string is stored. This is normally an HtmlTextWriter instance that wraps the response output stream.
❑
type: This parameter is a string that specifies the type of information that the encoded string contains. As you’ll see later, the current client-side PageRequestManager instance will use this string to determine what type of information it is dealing with. For example, if the encoded string contains the value of a hidden field, the server-side PageRequestManager instance uses the string “hiddenField” as the type to tell the current client-side PageRequestManager instance that the encoded string contains the name and value of a hidden field.
❑
id: As you’ll see later, if the encoded string contains the value associated with a server control, this optional parameter contains the value of the ClientID property of the server control.
❑
content: This parameter contains the actual value being encoded.
As Listing 23-15 shows, the EncodeString method generates a string that contains four substrings separated by the | character, where the second, third, and fourth substrings contain the second and third parameters, and the encoded form of the fourth parameter, of the EncodeString method.
The RenderPageCallback Method of PageRequestManager Now back to the implementation of the RenderPageCallback method of the server-side PageRequestManager, as shown in Listing 23-16. As you can see, this method takes two arguments. The first references the HtmlTextWriter instance that wraps the response output stream, which means that anything that this method writes into this HtmlTextWriter instance will be automatically written into the response output stream. The second argument references the Page object. The main responsibility of this method is to render the Page object and its contents to the specified HtmlTextWriter instance and consequently to the response output stream. As you can see, the RenderPageCallback method first calls the ProcessUpdatePanels method on the current server-side PageRequestManager instance. As you’ll see later in this chapter, the main
1124
c23.indd 1124
8/20/07 8:41:28 PM
Chapter 23: Asynchronous Partial Page Rendering responsibility of this method is to determine which UpdatePanel server controls on the current page must be updated. this.ProcessUpdatePanels();
The RenderPageCallback method then sets the ContentType property of the ASP.NET Response object to text/plain to inform the current client-side PageRequestManager instance that the body of the response contains plain text: IHttpResponse response1 = this._owner.IPage.Response; response1.ContentType = “text/plain”;
Next, it calls the SetNoServerCaching on the ASP.NET Cache object to turn off server-side output caching for the current response, because the current request is an asynchronous page postback, which only updates specific portions of the page — that is, the portions encapsulated in the UpdatePanel server controls. If the output caching were allowed, the next synchronous request for the page would be served from the cache and consequently the client would get HTML that contains only portions of the original page: response1.Cache.SetNoServerCaching();
Next, the RenderPageCallback method creates a delegate of type RenderMethod that represents the RenderFormCallback method of the server-side PageRequestManager: RenderMethod renderMethod = new RenderMethod(this.RenderFormCallback);
Then it calls the SetRenderMethodDelegate method on the HtmlForm server control that represents the HTML element of the current page to register the RenderMethod delegate with the HtmlForm server control. As we discussed earlier, the HtmlForm server control, like any other, inherits the SetRenderMethodDelegate method from the Control base class. When the HtmlForm server control enters its rendering phase, in which its RenderChildren method is invoked, the RenderChildren method will call the delegate and consequently the RenderFormCallback method that the delegate represents, bypassing the normal rendering logic of the HtmlForm server control’s child controls. Recall that this normal logic simply iterates through all the visible child controls of the HtmlForm server control and calls the RenderControl method on each child control to render the control, which means that the normal rendering logic renders all the visible child controls of the form. Obviously, the normal rendering logic makes sense only in a normal page postback. In an asynchronous partial page rendering, on the other hand, only the portions of the page contained within specified UpdatePanel server controls must be rendered; the rest of the page must be left alone. IHtmlForm form1 = this._owner.IPage.Form; form1.SetRenderMethodDelegate(renderMethod);
Next, for future use, the RenderPageCallback method stores a reference to the HtmlTextWriter object passed into it as its first argument, in an internal field named _updatePanelWriter. Recall that this HtmlTextWriter object wraps the response output stream. Because of this, anything written into this object will automatically be written into the response output stream and sent to the client as part of the server response. this._updatePanelWriter = writer;
1125
c23.indd 1125
8/20/07 8:41:28 PM
Chapter 23: Asynchronous Partial Page Rendering Then the method instantiates an instance of an internal StringWriter subclass named ParserStringWriter. A string writer is a stream that contains an internal string in which it accumulates the information written into the stream. PageRequestManager.ParserStringWriter writer1 = new PageRequestManager.ParserStringWriter();
Next, the RenderPageCallback method instantiates an instance of an internal HtmlTextWriter subclass named ParserHtmlTextWriter that wraps the ParserStringWriter instance. Note the difference between the ParserHtmlTextWriter instance and the HtmlTextWriter instance stored in the _updatePanelWriter field. While the former wraps the ParserStringWriter, the latter wraps the response output stream. This means that anything written into the former will be automatically written into the ParserStringWriter, which is nothing but a string writer, and anything written into the latter will be automatically written into the response output stream, which is sent back to the client. In other words, what’s written into the ParserHtmlTextWriter instance remains in the server memory for the duration of the current request, while what’s written into the HtmlTextWriter instance stored in the _updatePanelWriter field is sent to the client. PageRequestManager.ParserHtmlTextWriter writer2 = new PageRequestManager.ParserHtmlTextWriter(writer1); writer1.ParseWrites = true;
Then the RenderPageCallback method calls the RenderControl method on the HtmlForm server control to render the control and its child controls into the ParserHtmlTextWriter instance. Since the RenderControl method renders the HtmlForm server control and its child controls into an in-memory stream, as opposed to the response output stream, what gets rendered remains in memory, allowing the RenderPageCallback method to decide which part of this rendered HTML markup must be sent to the client. form1.RenderControl(writer2); writer1.ParseWrites = false;
The HtmlForm server control may contain hidden fields. When the RenderControl method of the HtmlForm server control renders these hidden fields into the ParserHtmlTextWriter instance, this instance stores these hidden fields in a collection named HiddenFields. This collection contains one KeyValuePair object for each hidden field: the name part of the pair contains the name of the hidden field and the value part contains the value. The RenderPageCallback method iterates through the KeyValuePair objects in this collection and takes the following steps for each enumerated pair. First, it checks whether the enumerated pair represents a standard hidden field. If so, it calls the EncodeString static method on the PageRequestManager class. As we discussed earlier, the EncodeString method first creates an encoded string that consists of three main substrings separated by the | character — “hiddentField”|pair1.Key.ToString()|pair1 .Value.ToString() — in which the Key and Value properties of the KeyValuePair object contain the name and value of the hidden field, respectively. Next, the EncodeString method writes this encoded string into the HtmlTextWriter object that wraps the response output stream.
1126
c23.indd 1126
8/20/07 8:41:28 PM
Chapter 23: Asynchronous Partial Page Rendering foreach (KeyValuePair pair1 in writer1.HiddenFields) { if (PageRequestManager.IsBuiltInHiddenField(pair1.Key)) PageRequestManager.EncodeString(writer, “hiddenField”, pair1.Key, pair1.Value); }
Next, the RenderPageCallback method calls the EncodeString method eight more times to write the following encoded strings to the response output stream:
❑
“asyncPostBackControlIDs”|””|this.GetAsycnPostBackControlIDs(false): The first part of this encoded string tells the current client-side PageRequestMananger instance that this string contains the list of the UniqueID property values of all server controls on the current page
that cause asynchronous page postbacks: PageRequestManager.EncodeString(writer, “asyncPostBackControlIDs”, string.Empty, this.GetAsyncPostBackControlIDs(false));
❑
“postBackControlIDs”|””|this.GetPostBackControlIDs(false): The first part of this encoded string tells the current client-side PageRequestMananger instance that this string contains the list of the UniqueID property values of all server controls on the current page that
cause synchronous page postbacks: PageRequestManager.EncodeString(writer, “postBackControlIDs”, string.Empty, this.GetPostBackControlIDs(false));
❑
“updatePanelIDs”|””|this.GetAllUpdatePanelIDs(): The first part of this encoded string tells the current client-side PageRequestMananger instance that this string contains the list of the UniqueID property values of all UpdatePanel server controls on the current page: PageRequestManager.EncodeString(writer, “updatePanelIDs”, string.Empty, this.GetAllUpdatePanelIDs());
❑
“childUpdatePanelIDs”|””|this.GetChildUpdatePanelIDs(): The first part of this encoded string tells the current client-side PageRequestMananger instance that this string contains the list of the UniqueID property values of all UpdatePanel server controls on the current page that reside inside another UpdatePanel server control: PageRequestManager.EncodeString(writer, “childUpdatePanelIDs”, string.Empty, this.GetChildUpdatePanelIDs());
❑
“panelsToRefreshIDs”|””|this.GetRefreshingUpdatePanelIDs(): The first part of this encoded string tells the current client-side PageRequestMananger instance that this string contains the list of the UniqueID property values of all UpdatePanel server controls on the current
page that need refreshing: PageRequestManager.EncodeString(writer, “panelsToRefreshIDs”, string.Empty, this.GetRefreshingUpdatePanelIDs());
1127
c23.indd 1127
8/20/07 8:41:29 PM
Chapter 23: Asynchronous Partial Page Rendering ❑
“asyncPostBackTimeout”|””|this._owner.AsyncPostBackTimeout.ToString(): The first part of this encoded string tells the current client-side PageRequestMananger instance that
this string contains the value of the asynchronous page postback timeout: PageRequestManager.EncodeString(writer, “asyncPostBackTimeout”, string.Empty, this._owner.AsyncPostBackTimeout.ToString());
❑
“formAction”|””|writer2.FormAction: The first part of this encoded string tells the current client-side PageRequestMananger instance that this string contains the value of the
form action: if (writer2.FormAction != null) PageRequestManager.EncodeString(writer, “formAction”, string.Empty, writer2.FormAction);
❑
“pageTitle”|””|this._owner.IPage.Title: The first part of this encoded string tells the current client-side PageRequestMananger instance that this string contains the value of
the page title: if (this._owner.IPage.Header != null) { string text1 = this._owner.IPage.Title; if (!string.IsNullOrEmpty(text1)) PageRequestManager.EncodeString(writer, “pageTitle”, string.Empty, text1); }
Next, the RenderPageCallback method calls the RenderDataItems method on the current server-side PageRequestManager instance to render the data items into the server output stream: this.RenderDataItems(writer);
Then the method calls the ProcessScriptRegistration method on the current server-side PageRequestManager instance to render all the required client scripts: this.ProcessScriptRegistration(writer);
Finally, the RenderPageCallback method calls the ProcessFocus method on the current server-side PageRequestManager instance to give the mouse focus to the appropriate server control. this.ProcessFocus(writer);
Listing 23-16: The RenderPageCallback Method of the PageRequestManager private void RenderPageCallback(HtmlTextWriter writer, Control pageControl) { this.ProcessUpdatePanels(); IHttpResponse response1 = this._owner.IPage.Response; response1.ContentType = “text/plain”; response1.Cache.SetNoServerCaching(); IHtmlForm form1 = this._owner.IPage.Form; form1.SetRenderMethodDelegate(new RenderMethod(this.RenderFormCallback));
The ProcessUpdatePanels Method of PageRequestManager As we discussed, the current page consists of a bunch of UpdatePanel server controls, each of which designates a particular region of the page as a partially updatable region. When an asynchronous page postback request arrives — that is, when a request for a partial page rendering arrives, how does the page know which UpdatePanel server controls need updating or refreshing? An UpdatePanel server control needs updating if it meets one or more of the following requirements:
❑
The first substring of the string that the LoadPostData method retrieves from the post collection contains the value of the UniqueID property of the UpdatePanel server control. (Recall from Listing 23-10 that the LoadPostData method assigns this substring to the _updatePanelRequestUpdate field.) As we discussed earlier in this chapter, this scenario
1129
c23.indd 1129
8/20/07 8:41:29 PM
Chapter 23: Asynchronous Partial Page Rendering occurs when the server control that caused the current asynchronous page postback resides inside an UpdatePanel server control whose ChildrenAsTriggers property is set to true.
❑
The UpdateMode property of the UpdatePanel server control is set to Always.
❑
The Update method of the UpdataPanel server control is explicitly invoked. As you can see from Listing 23-17, this method simply sets the internal Boolean _explicitUpdate field of the UpdatePanel server control on which the method is invoked to true, to specify that this UpdatePanel server control must be updated.
Use the Update method to imperatively force an UpdatePanel server control to refresh regardless of what triggered the current asynchronous page postback. If you call the Update method on an UpdatePanel server control whose UpdateMode property is set to Always, the method will raise an invalid operation exception.
❑
The second substring of the string that the LoadPostData method retrieves from the post collection contains the value of the UniqueID property of the associated server control of one of the triggers in the Triggers collection of the UpdatePanel server control. Recall from Listing 23-10 that the LoadPostData method assigns this substring to the _asyncPostBackSourceElementID field.
❑
The UpdatePanel server control is a child of an UpdatePanel server control that needs updating.
As you can see, the update of an UpdatePanel server control automatically triggers the updates of all its descendant UpdatePanel server controls. However, the update of an UpdatePanel server control does not automatically trigger the updates of its ancestor UpdatePanel server controls. If you want to force the ancestor UpdatePanel server controls to update as well, you must take one of these extra steps.
❑
Set the UpdateMode properties of the ancestor UpdatePanel server controls to Always.
❑
Add the triggers that trigger the update of a child UpdatePanel server control to the Triggers collections of the ancestor UpdatePanel server controls.
❑
Imperatively call the Update methods of the ancestor UpdatePanel server controls.
Listing 23-17: The Update Method of the UpdatePanel Server Control public void Update() { if (this.UpdateMode == UpdatePanelUpdateMode.Always) throw new InvalidOperationException(“UpdateConditional”); if (this._asyncPostBackModeInitialized) throw new InvalidOperationException(“UpdateTooLate”); this._explicitUpdate = true; }
As you saw back in Listing 23-16, the RenderPageCallback method of the current server-side PageRequestManager instance calls the ProcessUpdatePanels method on the current serverside PageRequestManager instance to determine which UpdatePanel server controls on the current page must be updated. Recall that the current server-side PageRequestManager instance maintains the list of all UpdatePanel server controls on the current page in an internal collection named _allUpdatePanels.
1130
c23.indd 1130
8/20/07 8:41:29 PM
Chapter 23: Asynchronous Partial Page Rendering As you can see from Listing 23-18, the ProcessUpdatePanels method iterates through the UpdatePanel server controls in this collection and takes the following steps for each enumerated UpdatePanel server control to determine whether the control needs refreshing. (Note that this method sets a local Boolean variable named updatePanelNeedsToUpdate to specify whether the enumerated UpdatePanel server control needs updating.)
Listing 23-18: The ProcessUpdatePanels Method of the PageRequestManager private void ProcessUpdatePanels() { if (this._allUpdatePanels != null) { this._updatePanelsToRefresh = new List(this._allUpdatePanels.Count); this._childUpdatePanelsToRefresh = new List(this._allUpdatePanels.Count); HtmlForm form1 = this._owner.Page.Form; for (int num1 = 0; num1 < this._allUpdatePanels.Count; num1++) { UpdatePanel panel1 = this._allUpdatePanels[num1]; bool updatePanelNeedsToUpdate = false; if ((this._updatePanelRequiresUpdate != null) && string.Equals(panel1.UniqueID, this._updatePanelRequiresUpdate)) updatePanelNeedsToUpdate = true; else updatePanelNeedsToUpdate = panel1.RequiresUpdate; Control control1 = panel1.Parent; while (control1 != form1) { UpdatePanel panel2 = control1 as UpdatePanel; if ((panel2 != null) && (this._updatePanelsToRefresh.Contains(panel2) || this._childUpdatePanelsToRefresh.Contains(panel2))) { updatePanelNeedsToUpdate = false; this._childUpdatePanelsToRefresh.Add(panel1); break; } control1 = control1.Parent; if (control1 == null) { updatePanelNeedsToUpdate = false; break; } } if (updatePanelNeedsToUpdate) { panel1.SetAsyncPostBackMode(true); this._updatePanelsToRefresh.Add(panel1); } else panel1.SetAsyncPostBackMode(false); } } }
1131
c23.indd 1131
8/20/07 8:41:30 PM
Chapter 23: Asynchronous Partial Page Rendering The ProcessUpdatePanels method first checks whether the _updatePanelRequiresUpdate field of the current server-side PageRequestManager instance contains the UniqueID property value of the enumerated UpdatePanel server control. Recall from Listing 23-10 that the LoadPostData method of the current server-side PageRequestManager instance retrieves from the posted data the UniqueID property value of the UpdatePanel server control that requires refreshing (if any) and stores the value in the _updatePanelRequestUpdate field of the current server-side PageRequestManager instance. if ((this._updatePanelRequiresUpdate != null) && string.Equals(panel1.UniqueID, this._updatePanelRequiresUpdate)) updatePanelNeedsToUpdate = true;
If this check fails — that is, if the _updatePanelRequiresUpdate field does not contain the UniqueID property value of the enumerated UpdatePanel server control — the ProcessUpdatePanels method sets the value of the updatePanelNeedsToUpdate Boolean variable to the value of the RequiresUpdate property of the enumerated UpdatePanel server control. else updatePanelNeedsToUpdate = panel1.RequiresUpdate;
Next, I’ll digress from our discussion of the implementation of the ProcessUpdatePanels method to discuss the implementation of the RequiresUpdate property of the UpdatePanel server control. As Listing 23-19 shows, the RequiresUpdate property returns true if:
❑
The _explicitUpdate field of the UpdatePanel server control is set to true. Recall from Listing 23-17 that the value of this field is set to true only when you explicitly invoke the Update method of the UpdatePanel server control from within your code.
❑
The UpdateMode property of the UpdatePanel server control is set to Always.
❑
The HasTriggered method of the Triggers collection of the UpdatePanel server control returns true. As Listing 23-20 shows, the HasTriggered method of this collection returns true if the HasTriggered method of at least one of its UpdatePanelTrigger objects returns true. (I discussed the HasTriggered method of the AsyncPostBackTrigger class in Chapter 21.)
Listing 23-19: The RequiresUpdate Method of the UpdatePanel Server Control protected internal virtual bool RequiresUpdate { get { if (this._explicitUpdate || (this.UpdateMode == UpdatePanelUpdateMode.Always)) return true; if ((this._triggers != null) && (this._triggers.Count != 0)) return this._triggers.HasTriggered(); return false; } }
1132
c23.indd 1132
8/20/07 8:41:30 PM
Chapter 23: Asynchronous Partial Page Rendering Listing 23-20: The HasTriggered Method of the UpdatePanelTriggerCollection Class internal bool HasTriggered() { using (IEnumerator enumerator1 = base.GetEnumerator()) { while (enumerator1.MoveNext()) { if (enumerator1.Current.HasTriggered()) return true; } } return false; }
Now back to the implementation of the ProcessUpdatePanels method shown in Listing 23-21. So far, you’ve learned that this method sets the value of the updatePanelNeedsToUpdate variable to true if the _updatePanelRequiresUpdate field contains the UniqueID property of the enumerated UpdatePanel server control, or if the RequiresUpdate property of the enumerated UpdatePanel server control returns true. As the name suggests, the updatePanelNeedsToUpdate variable specifies whether the enumerated UpdatePanel server control needs to update. Next, the ProcessUpdatePanels method walks up the control hierarchy of the enumerated UpdatePanel server control to determine whether it resides inside another UpdatePanel server control. If so, it checks whether the _updatePanelsToRefresh or _childUpdatePanelsToRefresh collection of the current server-side PageRequestManager instance already contains the container UpdatePanel server control. If so, this indicates that the container UpdatePanel server control of the enumerated UpdatePanel server control needs to update. Since updating the container UpdatePanel server control automatically updates all its content, including the enumerated UpdatePanel server control, the ProcessUpdatePanels method first sets the updatePanelNeedsToUpdate local Boolean variable to false to signal that the enumerated UpdatePanel server control mustn’t be added to the _updatePanelsToRefresh collection. This avoids duplicate updates. The ProcessUpdatePanels method then adds the enumerated UpdatePanel server control to the _childUpdatePanelsToRefresh collection. while (control1 != form1) { UpdatePanel panel2 = control1 as UpdatePanel; if ((panel2 != null) && (this._updatePanelsToRefresh.Contains(panel2) || this._childUpdatePanelsToRefresh.Contains(panel2))) { updatePanelNeedsToUpdate = false; this._childUpdatePanelsToRefresh.Add(panel1); break; } control1 = control1.Parent; if (control1 == null) { updatePanelNeedsToUpdate = false; break; } }
1133
c23.indd 1133
8/20/07 8:41:30 PM
Chapter 23: Asynchronous Partial Page Rendering Recall from Listing 21-31 that the markup text that makes up an UpdatePanel server control consists of two main parts. The first part is a div or span HTML element. The second is the rest of the markup text that makes up the UpdatePanel server control. The first part is known as the containing or outermost HTML element because it contains or encapsulates the second part. The second part is known as content because it is contained or enclosed within the opening and closing tags of the containing or outermost HTML element. As you’ll see later in this chapter, the current server-side PageRequestManager instance renders the content of an UpdatePanel server control that needs updating into a string, which is then sent back to the current client-side PageRequestManager instance for processing. As you’ll see in the next chapter, the current client-side PageRequestManager instance simply assigns the string that contains the content of the UpdatePanel server control to the innerHTML property of the containing or outermost HTML element of the UpdatePanel server control. This means that the original content of the UpdatePanel server control is completely wiped out and replaced with the new content. This has an important consequence when the UpdatePanel server control contains child UpdatePanel server controls, because updating the UpdatePanel server control deletes the current child UpdatePanel server controls and replaces them with brandnew child UpdatePanel server controls, even though the new child UpdatePanel server controls have the same UniqueID and ClientID property values as the deleted ones. Therefore, as far as the current client-side PageRequestManager instance is concerned, when an UpdatePanel server control updates, its child UpdatePanel server controls do not. Instead they are completely deleted from the current page and replaced with brand-new child UpdatePanel server controls with the same UniqueID and ClientID property values as the deleted ones. So far, we’ve assumed that the new content simply deleted the old child UpdatePanel server controls and replaced them with the brand-new child UpdatePanel server controls with the same UniqueID and ClientID property values as the deleted ones. However, it is quite possible that the new content may also include new child UpdatePanel server controls that are not replacing the old ones. It is also quite possible that some of the old child UpdatePanel server controls are indeed deleted from the new content, which means that the new content may have fewer child server controls than the old.
Finally, the ProcessUpdatePanels method checks whether the updatePanelNeedsToUpdate variable is set to true. If so, it first calls the SetAsyncPostBackMode method on the enumerated UpdatePanel server control and then adds the control to the _updatePanelsToRefresh collection of the current server-side PageRequestManager instance. As Listing 23-21 shows, the SetAsyncPostBackMode method sets an internal flag of the specified UpdatePanel server control, named _asyncPostBackMode, to true. if (updatePanelNeedsToUpdate) { panel1.SetAsyncPostBackMode(true); this._updatePanelsToRefresh.Add(panel1); }
1134
c23.indd 1134
8/20/07 8:41:31 PM
Chapter 23: Asynchronous Partial Page Rendering If the updatePanelNeedsToUpdate variable is set to false, the ProcessUpdatePanels method calls the SetAsyncPostBackMode method on the enumerated UpdatePanel server control to set its _asyncPostBackMode field to false. else panel1.SetAsyncPostBackMode(false);
As you’ll see later, when the UpdatePanel server control enters its rendering phase, it checks the value of its _asyncPostBackMode field to determine how to render its content.
Listing 23-21: The SetAsyncPostBackMode Method of the UpdatePanel internal void SetAsyncPostBackMode(bool asyncPostBackMode) { if (this._asyncPostBackModeInitialized) throw new InvalidOperationException(“SetPartialRenderingModeCalledOnce”); this._asyncPostBackMode = asyncPostBackMode; this._asyncPostBackModeInitialized = true; }
RenderControl Method of HtmlForm Recall from Listing 23-16 that the RenderPageCallback method creates a delegate of type RenderMethod that represents the RenderFormCallback method of the current server-side PageRequestManager instance and calls the SetRenderMethodDelegate method on the HtmlForm server control that represents the HTML element of the current page to register this RenderMethod delegate with the HtmlForm server control. Also recall from Listing 23-16 that the RenderPageCallback method calls the RenderControl method on the HtmlForm server control to have this server control render itself to the ParserHtmlTextWriter instance passed into the RenderControl method as its argument. Listing 23-22 presents the internal implementation of the RenderControl method of the HtmlForm server control. As you can see, this method calls the RenderControl method of the Control base class, which in turn calls the Render method of the Control base class. As Listing 23-13 shows, the Render method of the Control base class calls the RenderChildren method.
Listing 23-22: The RenderControl Method of the HtmlForm Server Control public override void RenderControl(HtmlTextWriter writer) { if (base.DesignMode) base.RenderChildren(writer); else base.RenderControl(writer); }
Listing 23-23 presents the internal implementation of the RenderChildren method of the HtmlForm server control. This method first invokes the OnFormRender method on the Page: this.Page.OnFormRender();
1135
c23.indd 1135
8/20/07 8:41:31 PM
Chapter 23: Asynchronous Partial Page Rendering Next, it calls the BeginFormRender method on the Page: this.Page.BeginFormRender(writer, this.UniqueID);
Then it calls the RenderChildren method of the Control base class: base.RenderChildren(writer);
Next, the RenderChildren method calls the EndFormRender method on the Page: this.Page.EndFormRender(writer, this.UniqueID);
Finally, it calls the OnFormPostRender method on the Page: this.Page.OnFormPostRender();
Listing 23-23: The RenderChildren Method of the HtmlForm Server Control protected internal override void RenderChildren(HtmlTextWriter writer) { if (this.Page != null) { this.Page.OnFormRender(); this.Page.BeginFormRender(writer, this.UniqueID); } base.RenderChildren(writer); if (this.Page!= null) { this.Page.EndFormRender(writer, this.UniqueID); this.Page.OnFormPostRender(); } }
The RenderChildren method of the Control base class (see Listing 23-14) calls the GetRenderMethod to return a reference to the RenderMethod delegate that represents the RenderFormCallback method and calls this delegate, and consequently the RenderFormCallback method, bypassing the normal rendering logic of the child controls of the HtmlForm server control. Recall that this normal logic simply iterates through the child controls in the Controls collection of the HtmlForm server control and calls the RenderControl method on each child control, as shown in the boldface portion of Listing 23-14.
The RenderFormCallback Method of PageRequestManager Listing 23-24 presents the internal implementation of the RenderFormCallback method of the serverside PageRequestManager. Recall that the ProcessUpdatePanels method populates an internal collection named _updatePanelsToRefresh with all the UpdatePanel server controls that need refreshing. The RenderFormCallback method iterates through the UpdatePanel server controls in this collection and calls the RenderControl method on each enumerated UpdatePanel server control to have the control render itself into the HtmlTextWriter object that the _updatePanelWriter field references. Recall from Listing 23-16 that the RenderPageCallback method of the PageRequestManager stores a reference to the HtmlTextWriter object that wraps the response output stream in the _updatePanelWriter field. Therefore, the RenderControl method of the enumerated UpdatePanel
1136
c23.indd 1136
8/20/07 8:41:32 PM
Chapter 23: Asynchronous Partial Page Rendering server control ends up rendering itself into the response output stream. The response output stream is the stream that contains the response text that is sent back to the requesting browser. As you can see, the RenderFormCallback method renders the UpdatePanels in the _updatePanelsToRefresh collection only. In other words, none of the other server controls on the current page is rendered when the current request is an asynchronous page postback. The other server controls go through all their life cycle phases as usual, except for the rendering phase. This phase is what makes an asynchronous page postback request different from a synchronous page postback request. While the HTML markup contained in the response output stream in the case of a synchronous page postback contains HTML markup text from all visible server controls on the current page, the HTML markup text contained in the response output stream in the case of an asynchronous page postback contains HTML markup text only from the visible UpdatePanel server controls in the _updatePanelsToRefresh collection.
Listing 23-24: The RenderFormCallback Method of the PageRequestManager private void RenderFormCallback(HtmlTextWriter writer, Control containerControl) { PageRequestManager.ParserStringWriter writer1 = writer.InnerWriter as PageRequestManager.ParserStringWriter; writer1.ParseWrites = false; if (this._updatePanelsToRefresh != null) { foreach (UpdatePanel panel1 in this._updatePanelsToRefresh) { if (panel1.Visible) panel1.RenderControl(this._updatePanelWriter); } } writer1.ParseWrites = true; }
The RenderControl Method of the UpdatePanel The UpdatePanel server control inherits the RenderControl method from the Control base class. The base class’s implementation of the RenderControl method calls the Render method shown in Listing 23-25. As you can see, this method calls the VerifyRenderingInServerForm method on the Page object to raise an exception if the UpdatePanel server control is not inside a element: this.IPage.VerifyRenderingInServerForm(this);
Next, it calls the Render method of its base class, which in turn calls the RenderChildren method.
Listing 23-25: The Render Method of the UpdatePanel protected override void Render(HtmlTextWriter writer) { this.IPage.VerifyRenderingInServerForm(this); base.Render(writer); }
1137
c23.indd 1137
8/20/07 8:41:32 PM
Chapter 23: Asynchronous Partial Page Rendering Listing 23-26 presents the implementation of the RenderChildren method of the UpatePanel server control. This method checks whether the UpdatePanel control is in asynchronous postback mode. Recall from Listing 23-21 that the ProcessUpdatePanels method calls the SetAsyncPostBackMode method on each UpdatePanel server control in the _allUpdatePanels collection of the current serverside PageRequestManager instance to set the value of the _asyncPostBackMode field of the UpdatePanel server control to specify whether the UpdatePanel server control must be rendered in asynchronous postback mode. As Listing 23-26 shows, the RenderChildren method of an UpdatePanel server control instantiates an HtmlTextWriter instance when the control is in asynchronous postback mode : HtmlTextWriter writer1 = new HtmlTextWriter(new StringWriter());
Next, it calls the RenderChildren method of its base class — that is, the Control base class — passing in the HtmlTextWriter instance. Recall from Listing 23-14 that the RenderChildren method of the Control base class iterates through the child controls in the Controls collection and invokes the RenderControl method on each child control to have the child control render itself into the preceding HtmlTextWriter instance. In other words, this HtmlTextWriter instance accumulates the HTML markup text generated by the server controls and HTML enclosed within the opening and closing tags of the child element of the tag. base.RenderChildren(writer1);
Finally, the RenderChildren method of the UpdatePanel control calls the EncodeString static method on the server-side PageRequestManager class, passing in four parameters: the first references the HtmlTextWriter instance that wraps the response output stream, the second is the string “updatePanel”, the third contains the value of the ClientID property of the UpdatePanel server control, and the last is a string that contains all the HTML markup of the child controls of the UpdatePanel server control. The main responsibility of the EncodeString method is to encode the last three parameters into a string and render the string into the HtmlTextWriter object that the first parameter references — that is, the HtmlTextWriter instance that wraps the response output stream.
Listing 23-26: The RenderChildren Method of the UpdatePanel protected override void RenderChildren(HtmlTextWriter writer) { if (this._asyncPostBackMode) { if (this._rendered) return; HtmlTextWriter writer1 = new HtmlTextWriter(new StringWriter()); base.RenderChildren(writer1); PageRequestManager.EncodeString(writer, “updatePanel”, this.ClientID, writer1.InnerWriter.ToString()); } else { writer.AddAttribute(HtmlTextWriterAttribute.Id, this.ClientID);
The GetAsyncPostBackControlIDs Method of the Server-Side PageRequestManager Listing 23-27 presents the implementation of the GetAsyncPostBackControlIDs method of the PageRequestManager. As you can see, this method simply delegates to the GetControlIDsFromList method, passing in the _asyncPostBackControls collection. Recall that the PageRequestManager server class features a private collection named _asyncPostBackControl that contains all the server controls that cause asynchronous page postbacks.
Listing 23-27: The GetAsyncPostBackControlIDs Method of the PageRequestManager private string GetAsyncPostBackControlIDs(bool includeQuotes) { return PageRequestManager.GetControlIDsFromList(this._asyncPostBackControls, includeQuotes); }
The GetControlIDsFromList Method of the Server-Side PageRequestManager Listing 23-28 contains the code for the GetControlIDsFromList method of the server-side PageRequestManager. This method takes a List collection that contains a list of server controls. The main responsibility of this method is to return a comma-separated list of strings, each of which contains the UniqueID property value of a server control in the List collection. Note that this method takes a second Boolean argument that specifies whether these UniqueID property values must be rendered in quotes.
Listing 23-28: The GetControlIDsFromList Method of the PageRequestManager private static string GetControlIDsFromList(List list, bool includeQuotes) { if ((list == null) || (list.Count 0) { string scriptPath = this._owner.GetScriptResourceUrl(“Focus.js”, typeof(HtmlForm).Assembly); PageRequestManager.EncodeString(writer, “scriptBlock”, “ScriptPath”, scriptPath); PageRequestManager.EncodeString(writer, “focus”, string.Empty, focusedControlID); } } }
Listing 23-52 puts together all the EncodeString method calls triggered by the call into the RenderPageCallback method of the current server-side PageRequestMananger instance.
Listing 23-52: All EncodeString Method Calls Triggered by the RenderPageCallback Method private void RenderPageCallback(HtmlTextWriter writer, Control pageControl) { IHttpResponse response1 = this._owner.IPage.Response; response1.ContentType = “text/plain”; response1.Cache.SetNoServerCaching(); foreach (UpdatePanel updatePanel in this._updatePanelsToRefresh) { . . . HtmlTextWriter writer2 = new HtmlTextWriter(new StringWriter()); base.RenderChildren(writer2); PageRequestManager.EncodeString(writer, “updatePanel”, updatePanel.ClientID, Writer2.InnerWriter.ToString()); } foreach (KeyValuePair pair1 in writer1.HiddenFields) { if (PageRequestManager.IsBuiltInHiddenField(pair1.Key)) PageRequestManager.EncodeString(writer, “hiddenField”, pair1.Key, pair1.Value); }
Just by looking at the EncodeString calls shown in the highlighted portions of Listing 23-52, and considering the fact that each EncodeString call generates a string of the format length|type|id|content, can you guess what the final server response text sent to the current client-side PageRequestManagner instance looks like? Listing 23-53 presents a page that shows you the actual server response text sent to the current client-side PageRequestManager instance. If you access this page, you should get the result shown in Figure 23-2. As you can see, this page consists of two text fields and a button. Now enter some text into the text fields and click the button. You should see the actual server response text on a popup like the one shown in Figure 23-3.
Listing 23-53: A Page that Shows What the Server Response Text Looks Like Untitled Page function requestCompleted(sender, args) { var reply = sender.get_responseData(); alert(reply); }
(continued)
1169
c23.indd 1169
8/20/07 8:41:41 PM
Chapter 23: Asynchronous Partial Page Rendering Listing 23-53 (continued) function beginRequestHandler(sender, args) { var request = args.get_request(); request.add_completed(requestCompleted); } function pageLoad() { var prm = Sys.WebForms.PageRequestManager.getInstance(); prm.add_beginRequest(beginRequestHandler); }
First Name:
Last Name:
1170
c23.indd 1170
8/20/07 8:41:41 PM
Chapter 23: Asynchronous Partial Page Rendering
Figure 23-2
Figure 23-3
1171
c23.indd 1171
8/20/07 8:41:41 PM
Chapter 23: Asynchronous Partial Page Rendering As shown in these images, the server response text is a string that consists of a bunch of substrings with the format length|type|id|content, where the length part specifies the number of characters in the content part of the substring, the type part specifies the type of information stored in the content part of the substring, the id part specifies the ClientID property value of the server control associated with the information stored in the content part of the substring, and finally the content part contains the actual information or data being sent to the current client-side PageRequestManager instance. The server response text shown in Figure 23-3 consists of 11 substrings as follows: Here is the first substring: 586|updatePanel|UpdatePanel1|
First Name:
Last Name:
|
The first substring is the one the EncodeString method call shown in Listing 23-52 generates and renders into the response output stream: PageRequestManager.EncodeString(writer, “updatePanel”, this.ClientID, writer1.InnerWriter.ToString());
As you can see, the first substring consists of the following four parts:
❑
586: This first part of the substring tells the current client-side PageRequestManager that the fourth part of the substring contains 586 characters (with spaces).
❑
updatePanel: This second part of the substring tells the current client-side PageRequestManager that the fourth part of the substring contains the HTML markup text enclosed within the UpdatePanel server control whose UniqueID property value is given by the third part of the substring.
1172
c23.indd 1172
8/20/07 8:41:41 PM
Chapter 23: Asynchronous Partial Page Rendering ❑
UpdatePanel1: The third part of the substring tells the current client-side PageRequestManager that the HTML markup text contained in the fourth part of the string belongs to the UpdatePanel server control with the UniqueID property value of UpdatePanel1.
❑
The fourth part of the substring provides the current client-side PageRequestManager instance with the HTML markup text of the UpdatePanel server control with the UniqueID property value of UpdatePanel1. Recall from Listing 23-48 that the RenderChildren method of the UpdatePanel server control generates this HTML markup text.
Here is the second substring: 52|hiddenField|__VIEWSTATE|/wEPDwULLTIxMjYzMDU2NzJkZJ0ptWJFvcbB8l53OBKz9PRMaPrd|
This is the substring that the first EncodeString method call shown in Listing 23-52 generates and renders into the response output stream: PageRequestManager.EncodeString(writer, “hiddenField”, pair1.Key, pair1.Value);
As you can see, the second substring consists of the following four parts:
❑
52: This first part of the substring tells the client-side PageRequestManager instance that the fourth part of this substring contains 52 characters (with spaces).
❑
hiddenField: This second part of the substring tells the client-side PageRequestManager instance that this substring contains the name and value of a hidden field.
❑
__VIEWSTATE: This third part of the substring tells the client-side PageRequestManager instance that the name of this hidden field is __VIEWSTATE.
❑
The fourth part of the substring tells the client-side PageRequestManager instance that the value of this hidden field is as follows:
Here is the third substring: 64|hiddenField|__EVENTVALIDATION|/wEWBAKj4cTUAgLs0bLrBgLs0fbZDAKM54rGBv6aI9H0 BYIx273PdOWCCpAOOHzF|
This is the substring that the first EncodeString method call shown in Listing 23-52 generates and renders into the response output stream: PageRequestManager.EncodeString(writer, “hiddenField”, pair1.Key, pair1.Value);
As you can see, the third substring consists of the following four parts:
❑
64: This first part of the substring tells the client-side PageRequestManager instance that the fourth part of this substring contains 64 characters (with spaces).
❑
hiddenField: This second part of the substring tells the client-side PageRequestManager instance that this substring contains the name and value of a hidden field.
1173
c23.indd 1173
8/20/07 8:41:42 PM
Chapter 23: Asynchronous Partial Page Rendering ❑
__EVENTVALIDATION: This third part of the substring tells the client-side PageRequestManager instance that the name of this hidden field is __EVENTVALIDATION.
❑
The fourth part of the substring tells the client-side PageRequestManager instance that the value of this hidden field is as follows:
Here is the fourth substring: 0|asyncPostBackControlIDs|||
This is the substring that the following EncodeString method call in Listing 23-52 generates and renders into the response output stream: PageRequestManager.EncodeString(writer, “asyncPostBackControlIDs”, string.Empty, this.GetAsyncPostBackControlIDs(false));
As you can see, the fourth substring consists of the following four parts:
❑
0: This first part of the substring tells the client-side PageRequestManager instance that the
fourth part of this substring contains zero characters.
❑
asyncPostBackControlIDs: This second part of the substring tells the client-side PageRequestManager instance that the fourth part of this substring contains the commaseparated list of the UniqueID property values of all the server controls on the current page
that cause asynchronous page postbacks. Since our example does not contain any server control causing asynchronous page postbacks, this list is empty.
❑
Since the third part of this substring does not play any role in this case, it is an empty string.
❑
Since the current example does not contain any server controls causing asynchronous page postbacks, the fourth part of this substring is an empty string.
Here is the fifth substring: 0|postBackControlIDs|||
This is the substring that the following EncodeString method call in Listing 23-52 generates and renders into the response output stream: PageRequestManager.EncodeString(writer, “postBackControlIDs”, string.Empty, this.GetPostBackControlIDs(false));
As you can see, the fifth substring consists of the following four parts:
❑
a: This first part of the substring tells the client-side PageRequestManager instance that the
fourth part of this substring contains zero characters.
❑
postBackControlIDs: This second part of the substring tells the client-side PageRequestManager instance that the fourth part of this substring contains the comma-separated list of the UniqueID property values of all the server controls on the current page that cause synchronous page
1174
c23.indd 1174
8/20/07 8:41:42 PM
Chapter 23: Asynchronous Partial Page Rendering postbacks. Since our example does not contain any server control causing synchronous page postbacks, this list is empty.
❑
Since the third part of this substring does not play any role in this case, it is an empty string,
❑
Since the current example does not contain any server controls causing synchronous page postbacks, the fourth part of the substring is an empty string.
Here is the sixth substring: 13|updatePanelIDs||tUpdatePanel1|
This is the substring that the following EncodeString method call in Listing 23-52 generates and renders into the response output stream: PageRequestManager.EncodeString(writer, “updatePanelIDs”, string.Empty, this.GetAllUpdatePanelIDs());
As you can see, the sixth substring consists of the following four parts:
❑
13: This first part of the substring tells the client-side PageRequestManager instance that the fourth part of this substring contains 13 characters.
❑
updatePanelIDs: This second part of the substring tells the client-side PageRequestManager instance that the fourth part of this substring contains the comma-separated list of the UniqueID property values of all the UpdatePanel server controls on the current page.
❑
Since the third part of this substring does not play any role in this case, it is an empty string.
❑
tUpdatePanel1: This fourth part of the substring provides the current client-side PageRequestManager instance with the comma-separated list of all the UpdatePanel server controls on the current page. Since our example includes a single UpdatePanel server control,
this list has a single member. Note that the member consists of two parts, where the first part contains the letter t, which tells the current client-side PageRequestMananger instance that the ChildrenAsTriggers property of this UpdatePanel server control has been set to true, and the second part contains the UniqueID property value of the UpdatePanel server control. Here is the seventh substring: 0|childUpdatePanelIDs|||
This is the substring that the following EncodeString method call in Listing 23-52 generates and renders into the response output stream: PageRequestManager.EncodeString(writer, “childUpdatePanelIDs”, string.Empty, this.GetChildUpdatePanelIDs());
1175
c23.indd 1175
8/20/07 8:41:42 PM
Chapter 23: Asynchronous Partial Page Rendering As you can see, the seventh substring consists of the following four parts:
❑
0: This first part of the substring tells the client-side PageRequestManager instance that the
fourth part of this substring contains zero characters.
❑
childUpdatePanelIDs: This second part of the substring tells the client-side PageRequestManager instance that the fourth part of this substring contains the commaseparated list of the UniqueID property values of all the child UpdatePanel server controls
on the current page.
❑
Since the third part of this substring does not play any role in this case, it is an empty string.
❑
Since the current example does not contain any child UpdatePanel server controls, the fourth part of the substring is an empty string.
Here is the eighth substring: 12|panelsToRefreshIDs||UpdatePanel1|
This is the substring that the following EncodeString method call in Listing 23-52 generates and renders into the response output stream: PageRequestManager.EncodeString(writer, “panelsToRefreshIDs”, string.Empty, this.GetRefreshingUpdatePanelIDs());
As you can see, the eighth substring consists of the following four parts:
❑
12: This first part of the substring tells the client-side PageRequestManager instance that the fourth part of this substring contains 12 characters.
❑
panelsToRefreshIDs: This second part of the substring tells the client-side PageRequestManager instance that the fourth part of this substring contains the comma-separated list of the UniqueID property values of all the UpdatePanel server control on the current page that need refreshing.
❑
Since the third part of the substring does not play any role in this case, it is an empty string.
❑
UpdatePanel1: This fourth part of the substring provides the current client-side PageRequestManager instance with the comma-separated list of all the UpdatePanel
server controls on the current page that need refreshing. Since our example includes a single UpdatePanel server control, this list has a single member.
Here is the ninth substring: 2|asyncPostBackTimeout||90|
This is the substring that the following EncodeString method call in Listing 23-52 generates and renders into the response output stream: PageRequestManager.EncodeString(writer, “asyncPostBackTimeout”, string.Empty, this._owner.AsyncPostBackTimeout.ToString());
1176
c23.indd 1176
8/20/07 8:41:43 PM
Chapter 23: Asynchronous Partial Page Rendering As you can see, the ninth substring consists of the following four parts:
❑
2: This first part of the substring tells the client-side PageRequestManager instance that the
fourth part of this substring contains two characters.
❑
asyncPostBackTimeout: This second part of the substring tells the client-side PageRequestManager instance that the fourth part of this substring contains the asynchro-
nous page postback timeout value.
❑
Since the third part of this substring does not play any role in this case, it is an empty string.
❑
90: This fourth part of the substring tells the current client-side PageRequestManager instance that the asynchronous page postback timeout value is 90.
Here is the tenth substring: 12|formAction||Default.aspx|
The tenth substring is the substring that the following EncodeString method call in Listing 23-52 generates and renders into the response output stream: PageRequestManager.EncodeString(writer, “formAction”, string.Empty, writer2.FormAction);
As you can see, the tenth substring consists of the following four parts:
❑
12: This first part of the substring tells the client-side PageRequestManager instance that the fourth part of this substring contains 12 characters.
❑
formAction: This second part of the substring tells the client-side PageRequestManager instance that the fourth part of this substring contains the form action.
❑
Since the third part of this substring does not play any role in this case, it is an empty string.
❑
Default.aspx: This fourth part of the substring tells the current client-side PageRequestManager instance that the form action for the current page is Default.aspx.
Here is the eleventh substring: 13|pageTitle||Untitled Page
This is the substring that the following EncodeString method call in Listing 23-52 generates and renders into the response output stream: PageRequestManager.EncodeString(writer, “pageTitle”, string.Empty, text1);
As you can see, the eleventh substring consists of the following four parts:
❑
13: This first part of the substring tells the client-side PageRequestManager instance that the fourth part of this substring contains 13 characters.
❑
pageTitle: This second part of the substring tells the client-side PageRequestManager
instance that the fourth part of this substring contains the page title.
1177
c23.indd 1177
8/20/07 8:41:43 PM
Chapter 23: Asynchronous Partial Page Rendering ❑
Since the third part of this substring does not play any role in this case, it is an empty string.
❑
Untitled Page: This fourth part of the substring tells the current client-side PageRequestManager instance that the page title is “Untitled Page.”
Summar y This chapter followed the Page through its life cycle phases to process the asynchronous page postback request made by the current client-side PageRequestMananger instance. We followed the request from the time it arrived in the ASP.NET to the time the server response text was finally sent back to the client. The next chapter will move on to the client side, where this server response text arrives, and follow the client-side PageRequestManager instance through its life cycle phases to process the server response.
1178
c23.indd 1178
8/20/07 8:41:43 PM
Asynchronous Par tial Page Rendering: Client-Side Processing The previous chapter followed the Page through its life cycle phases to process the asynchronous page postback request made by the current client-side PageRequestMananger instance. We followed the request from the time it arrived in ASP.NET to the time the server response text was finally sent back to the client. This chapter will move on to the client side, where this server response text arrives, and follow the client-side PageRequestManager instance through its life cycle phases to process the server response.
Arrival of the Ser ver Response Text Recall from Listing 22-22 that the _onFormSubmit method of the current client-side PageRequestManager instance is where the current client-side PageRequestManager instance made its asynchronous page postback to the server. Listing 24-1 presents a portion of the _onFormSubmit method. As the highlighted portion of this code listing shows, the current client-side PageRequestManager instance registers its _onFormSubmitCompleted method as an event handler for the completed event of the WebRequest object that represents the current request. request.add_completed(Function.createDelegate(this, this._onFormSubmitCompleted));
As the name suggests, the WebRequest object fires its completed event when the current request is finally completed.
c24.indd 1179
8/20/07 8:47:44 PM
Chapter 24: Asynchronous Partial Page Rendering Listing 24-1: The _onFormSubmit Method of the Client-Side PageRequestManager Instance function Sys$WebForms$PageRequestManager$_onFormSubmit(evt) { . . . var formBody = new Sys.StringBuilder(); formBody.append(this._scriptManagerID + ‘=’ + this._postBackSettings.panelID + ‘&’); var count = form.elements.length; for (var i = 0; i < count; i++) { . . . } . . . var request = new Sys.Net.WebRequest(); request.set_url(form.action); request.get_headers()[‘X-MicrosoftAjax’] = ‘Delta=true’; request.get_headers()[‘Cache-Control’] = ‘no-cache’; request.set_timeout(this._asyncPostBackTimeout); request.add_completed(Function.createDelegate(this, this._onFormSubmitCompleted)); request.set_body(formBody.toString()); . . . this._request = request; request.invoke(); . . . }
Recall from Listing 12-41 of Chapter 12 that when the request is finally completed, the _onReadyStateChange method of the current XMLHttpExecutor is invoked, as shown again in Listing 24-2. As you can see from the highlighted portion of this code listing, the _onReadyStateChange method invokes the completed method on the WebRequest object that represents the current request.
Listing 24-2: The _onReadyStateChange Method this._onReadyStateChange = function () { if (_this._xmlHttpRequest.readyState === 4 /*complete*/) { _this._clearTimer(); _this._responseAvailable = true; _this._webRequest.completed(Sys.EventArgs.Empty); if (_this._xmlHttpRequest != null) { _this._xmlHttpRequest.onreadystatechange = Function.emptyMethod; _this._xmlHttpRequest = null; } } }
1180
c24.indd 1180
8/20/07 8:47:45 PM
Chapter 24: Asynchronous Partial Page Rendering Recall from Listing 12-11 of Chapter 12 that the completed method of the WebRequest object in turn calls the event handlers registered for the completed event of the WebRequest object, as shown again in the highlighted portion of Listing 24-3.
Listing 24-3: The Completed Method function Sys$Net$WebRequest$completed(eventArgs) { var handler = Sys.Net.WebRequestManager._get_eventHandlerList().getHandler( “completedRequest”); if (handler) handler(this._executor, eventArgs); handler = this._get_eventHandlerList().getHandler(“completed”); if (handler) handler(this._executor, eventArgs); }
As the boldface portion of Listing 24-3 shows, when the completed method of the WebRequest object invokes the event handlers registered for its completed event, it passes a reference to the WebRequestExecutor object responsible for executing the current request. This means that the first parameter of the _onFormSubmitCompleted method of the current client-side PageRequestManager instance references this WebResquestExecutor object. You’ll see the internal implementation of the _onFormSubmitCompleted method later in the chapter. As I mentioned earlier, our goal in this chapter is to follow the current PageRequestMananger instance through its life cycle phases to process the server response. Since the current PageRequestManager instance’s life cycle is rather complex and involves a lot of method calls, I’ve captured almost all of them in a two-part diagram shown in Figures 24-1 and 24-2 to make it easier for you to follow our discussions. The vertical axis in this two-part diagram measures increasing time (early on the top, late on the bottom). Keep this two-part diagram in mind as you’re reading through this chapter. Also keep in mind where we are on this diagram at every stage of the current PageRequestManager instance’s life cycle. As you can see from Listing 24-3, the _onFormSubmitCompleted method of the current PageRequestManager instance sets the _processingRequest field on the current clientside PageRequestManager instance to true to signal that the request is now being processed: this._processingRequest = true;
Just because the WebRequest object has fired the completed event and consequently called the _onFormSubmitCompleted method does not mean that everything went fine and the server response has arrived. The WebRequest object fires the completed event for a number of reasons. Therefore, the _onFormSubmitCompleted method takes the following steps to determine why the completed event was raised. First, it calls the get_timedOut method on the WebRequestExecutor object to return a
1181
c24.indd 1181
8/20/07 8:47:45 PM
Chapter 24: Asynchronous Partial Page Rendering PageRequestManager (Processing Server Response) - First Part WebRequestExecutor PageRequestManager _onFormSubmitCompleted ()
_endPostBack is invoked when get_timedOut returns true
get_timedOut () _endPostBack is invoked when get_aborted returns true
_endPostBack () get_aborted () _endPostBack ()
_endPostBack is invoked when get_statusCode does not returns 200
_endPostBack is invoked if _panelsToRefreshIDs contains the UniqueID of a non-existent UpdatePanel
_updateControls (updatePanelIDs, asyncPostBackControlIDs, postBackControlIDs, asyncPostBackTimeout) _endPostBack is invoked if the UpdatePanel control whose content being updated is non-existent
Figure 24-1 Boolean value that specifies whether the completed event was raised because of a timeout. If so, it calls the _endPostBack method on the current PageRequestManager instance to end the ongoing asynchronous postback request and returns the following: if (sender.get_timedOut()) { this._endPostBack(this._createPageRequestManagerTimeoutError(), sender); return; }
Next, it calls the get_aborted method on the WebRequestExecutor to return a Boolean value that specifies whether the completed event was raised because the request aborted. If so, it calls the _endPostBack method on the current PageRequestManager instance to end the ongoing request and returns this: if (sender.get_aborted()) { this._endPostBack(null, sender); return; }
Next, the _onFormSubmitCompleted method calls the get_webRequest method on the WebRequestExecutor to return a reference to the WebRequest object that represents the request that the WebRequestExecutor executed. It then compares this with the WebRequest object that the _request property of the current PageRequestManager instance references. (As the boldface portion
1182
c24.indd 1182
8/20/07 8:47:45 PM
Chapter 24: Asynchronous Partial Page Rendering PageRequestManager (Processing Server Response) - Second Part PageRequestManager document
Figure 24-2 of Listing 24-1 shows, the current PageRequestManager instance assigns the WebRequest object to an internal field named _request before it executes the request.) If these two WebRequest objects are different, the completed event was raised for a different request and consequently the _onFormSubmitCompleted method simply returns this: if (!this._request || sender.get_webRequest() !== this._request) return;
As you can see, if an application makes several overlapping asynchronous page postback requests to the server, the last request wins. Next, the _onFormSubmitCompleted method calls the get_statusCode method on the WebRequestExecutor object to return an integer that contains the response status code. If this code is not 200, it is an indication that a server error occurred, and consequently the method calls the _endPostBack method on the current PageRequestManager instance to end the current request and returns this: if (sender.get_statusCode() !== 200) { this._endPostBack( this._createPageRequestManagerServerError(sender.get_statusCode()), sender); return; }
1183
c24.indd 1183
8/20/07 8:47:46 PM
Chapter 24: Asynchronous Partial Page Rendering Next, the _onFormSubmitCompleted method calls the get_responseData method on the WebRequestExecutor object to return the string that contains the server response: var reply = sender.get_responseData();
Recall from Listing 23-52 that the server response text is a string that contains a bunch of substrings in the format length|type|id|content, where:
❑
The length part tells the current client-side PageRequestManager instance how many characters there are in the content part of the substring.
❑
The type part tells the current client-side PageRequestManager instance what type of information the content part contains.
❑
The optional id part specifies the ClientID property value of the server control associated with the information contained in the content part.
❑
The content part contains the actual information that the current server-side PageRequestManager instance has sent to the current client-side PageRequestManager instance.
Listing 24-4 contains an example of a server response text that the current server-side PageRequestManager instance sends to the current client-side PageRequestManager instance. Keep this code listing in mind as we’re walking through the implementation of the _onFormSubmitCompleted method. The main responsibility of this method is to parse a response text similar to Listing 24-4.
Listing 24-4: An Example of a Server Response Text that the Current Client-Side PageRequestManager Might Receive 586|updatePanel|UpdatePanel1|
The _onFormSubmitCompleted method recursively takes the following steps to parse each substring in the server response string:
❑
It accesses the index of the first delimiter | character of the substring: delimiterIndex = reply.indexOf(‘|’, replyIndex);
❑
If the substring does not contain this delimiter, the _onFormSubmitCompleted method calls another method named _findText, stores the return value of this method in a local field named parserErrorDetails, and exits the while loop that loops through the substrings in the server response string. In other words, it does not attempt to parse the rest of the server response string. There is no point in processing an erroneous server response. As you’ll see shortly, the first statement after this while loop checks whether the value of the parserErrorDetails field is set. If so, it takes the appropriate action to end the current request. if (delimiterIndex === -1) { parserErrorDetails = this._findText(reply, replyIndex); break; }
❑
The following code listing presents the implementation of the _findText method:
function Sys$WebForms$PageRequestManager$_findText(text, location) { var startIndex = Math.max(0, location - 20); var endIndex = Math.min(text.length, location + 20); return text.substring(startIndex, endIndex); }
❑
The _onFormSubmitCompleted method parses the first part (that is, the length part) of the substring: len = parseInt(reply.substring(replyIndex, delimiterIndex), 10); replyIndex = delimiterIndex + 1;
❑
It accesses the index of the second delimiter: delimiterIndex = reply.indexOf(delimitByLengthDelimiter, replyIndex);
❑
If the substring does not contain this delimiter, the _onFormSubmitCompleted method calls the _findText method, stores the return value of this method in the parserErrorDetails local field, and exits the while loop, as discussed earlier.
The _onFormSubmitCompleted method parses the second part (that is, the type part) of the substring: type = reply.substring(replyIndex, delimiterIndex); replyIndex = delimiterIndex + 1;
❑
It accesses the index of the third delimiter |: delimiterIndex = reply.indexOf(delimitByLengthDelimiter, replyIndex);
❑
If the substring does not contain this delimiter, the _onFormSubmitCompleted method calls the _findText method, stores the return value of this method in the parserErrorDetails local field, and exits the while loop, as discussed earlier. if (delimiterIndex === -1) { parserErrorDetails = this._findText(reply, replyIndex); break; }
❑
The _onFormSubmitCompleted method parses the third part (that is, the id part) of the substring: id = reply.substring(replyIndex, delimiterIndex); replyIndex = delimiterIndex + 1;
❑
Recall that the len local field contains the length of the content part of the substring. _onFormSubmitCompleted first checks whether the index of the expected last character of the content part of the substring is a value that exceeds the length of the substring. If so, this is an indication that the server response has problems and consequently _onFormSubmitCompleted takes the same steps discussed earlier and exits the while loop. if ((replyIndex + len) >= reply.length) { parserErrorDetails = this._findText(reply, reply.length); break; }
❑
The _onFormSubmitCompleted method accesses the fourth part (that is, the content part) of the substring. (Note that the length of the fourth part is given by the first part of the length|type|id|content format.) content = this._decodeString(reply.substr(replyIndex, len)); replyIndex += len;
1186
c24.indd 1186
8/20/07 8:47:47 PM
Chapter 24: Asynchronous Partial Page Rendering ❑
Next, _onFormSubmitCompleted checks whether the last character of the substring is the delimiter character (|). If not, this is an indication that the server response has problems and consequently _onFormSubmitCompleted method takes the same steps discussed earlier and exits the while loop. if (reply.charAt(replyIndex) !== delimitByLengthDelimiter) { parserErrorDetails = this._findText(reply, replyIndex); break; }
❑
The _onFormSubmitCompleted method creates an object literal with three name/value pairs. The name part of the first pair is the word type and its value part is the second part of the substring (that is, the type part). The name part of the second name/value pair is the word id and its value part is the third part of the substring (that is, the id part). The name part of the third name/value pair is the word content and its value part is the fourth part of the substring (that is, the content part). var obj = {type: type, id: id, content: content};
❑
The _onFormSubmitCompleted method stores the above object literal in a local array named delta.
Array.add(delta, obj);
As you can see, the _onSubmitFormCompleted method parses each substring (in the length|type|id|content format) into an object literal and stores the object in a local array named delta. After existing the while loop, the _onSubmitFormCompleted method first checks whether the value of the parseErrorDetails local field is set. If so, this is an indication that the server response had some problems and consequently _onSubmitFormCompleted invokes the _endPostBack method to end the current asynchronous page postback request. if (parserErrorDetails) { this._endPostBack(this._createPageRequestManagerParserError( String.format(Sys.WebForms.Res.PRM_ParserErrorDetails, parserErrorDetails)), sender); return; }
Next, the method iterates through the object literals in the delta array and checks the value of the type property of each enumerated object (recall that the value associated with the type property of the object contains the second part of the length|type|id|content format):
❑
If the type is the string “updatePanel”, the _onFormSubmitCompleted method adds the enumerated object to a local array named updatePanelNodes. The value of the id property of this object is a string that contains the value of the UniqueID property of an UpdatePanel
1187
c24.indd 1187
8/20/07 8:47:47 PM
Chapter 24: Asynchronous Partial Page Rendering server control. The value of the content property of this object is a string that contains the markup text for this UpdatePanel server control. case “updatePanel”: Array.add(updatePanelNodes, deltaNode); break;
❑
If the type is the string “hiddenField”, the _onFormSubmitCompleted method adds the enumerated object to a local array named hiddenFieldNodes. The value of the id property of this object is a string that contains the name of the hidden field and the value of the content property is a string that contains the value of the hidden field. case “hiddenField”: Array.add(hiddenFieldNodes, deltaNode); break;
❑
If the type is the string “arrayDeclaration”, the _onFormSubmitCompleted method adds the enumerated object to a local array named arrayDeclarationNodes. This object describes an array declaration in which the value of the id property of the object is a string that contains the name of the JavaScript array. The value of the content property of this object is a string that contains the value being added to the array. case “arrayDeclaration”: Array.add(arrayDeclarationNodes, deltaNode); break;
❑
If the type is the string “scriptBlock”, the _onFormSubmitCompleted method adds the enumerated object to a local array named scriptBlockNodes. This object describes a script block in which the value of the id property of the object is one of the following string values: “ScriptContentNoTags”, “ScriptContentWithTags”, or “ScriptPath”, and in which the value of the content property is a string that contains the associated script block: case “scriptBlock”: Array.add(scriptBlockNodes, deltaNode); break;
❑
If the type is the string “expando”, the _onFormSubmitCompleted method adds the enumerated object to a local array named expandoNodes. This object describes an expando attribute in which the value of the id property of the object is a string that contains the name of the expando attribute, and the value of the content property is a string that contains the value of the expando attribute. case “expando”: Array.add(expandoNodes, deltaNode); break;
❑
If the type is the string “onSubmit”, the _onFormSubmitCompleted method adds the enumerated object to a local array named onSubmitNodes. This object describes a dynamically added form onsubmit statement in which the value of the id property of the object is an empty string and the value of the content property of the object is a string that contains the dynamically added form onsubmit statement.
If the type is the string “asyncPostBackControlIDs”, the _onFormSubmitCompleted method assigns the enumerated object to a local field named asyncPostBackControlIDsNode. This object describes all the server controls on the page that cause asynchronous page postbacks. The value of the id property of this object is an empty string, and the value of the content property is a string that contains a comma-separated list of substrings, each substring containing the value of the UniqueID property of a server control that causes an asynchronous page postback. case “asyncPostBackControlIDs”: asyncPostBackControlIDsNode = deltaNode; break;
❑
If the type is the string “postBackControlIDs”, the _onFormSubmitCompleted method assigns the enumerated object to a local field named postBackControlIDsNode. This object describes all the server controls on the page that cause normal synchronous page postbacks. The value of the id property of this object is an empty string, and the value of the content property is a string that contains a comma-separated list of substrings, each substring containing the value of the UniqueID property of a server control that causes a synchronous page postback. case “postBackControlIDs”: postBackControlIDsNode = deltaNode; break;
❑
If the type is the string “updatePanelIDs”, the _onFormSubmitCompleted method assigns the enumerated object to a local field named updatePanelIDsNode. This object describes all the UpdatePanel server controls on the current page. The value of the id property of this object is an empty string, and the value of the content property is a string that contains a commaseparated list of substrings, each substring containing the value of the UniqueID property of an UpdatePanel server control. case “updatePanelIDs”: updatePanelIDsNode = deltaNode; break;
❑
If the type is the string “asyncPostBackTimeout”, the _onFormSubmitCompleted method assigns the enumerated object to a local field named asyncPostBackTimeoutNode. This object describes timeout value for asynchronous page postbacks. The value of the id property of this object is an empty string, and the value of the content property is a string that contains the value of the asynchronous page postback timeout: case “asyncPostBackTimeout”: asyncPostBackTimeoutNode = deltaNode; break;
1189
c24.indd 1189
8/20/07 8:47:48 PM
Chapter 24: Asynchronous Partial Page Rendering ❑
If the type is the string “childUpdatePanelIDs”, the _onFormSubmitCompleted method assigns the enumerated object to a local field named childUpdatePanelIDsNode. This object describes all the child UpdatePanel server controls on the current page that need updating because their parent UpdatePanel server controls need updating. The value of the id property of this object is an empty string, and the value of the content property is a string that contains a comma-separated list of substrings, each substring containing the value of the UniqueID property of a child UpdatePanel server control. case “childUpdatePanelIDs”: childUpdatePanelIDsNode = deltaNode; break;
❑
If the type is the string “panelsToRefreshIDs”, the _onFormSubmitCompleted method assigns the enumerated object to a local field named panelsToRefreshNode. This object describes all the UpdatePanel server controls on the current page that need updating. The value of the id property of this object is an empty string, and the value of the content property is a string that contains a comma-separated list of substrings, each substring containing the value of the UniqueID property of an UpdatePanel server control. case “panelsToRefreshIDs”: panelsToRefreshNode = deltaNode; break;
❑
If the type is the string “formAction”, the _onFormSubmitCompleted method assigns the enumerated object to a local field named formActionNode. This object describes the current form action. The value of the id property of this object is an empty string, and the value of the content property is a string that contains the value of the action property of the form. case “formAction”: formActionNode = deltaNode; break;
❑
If the type is the string “dataItem”, the _onFormSubmitCompleted method adds the enumerated object to a local array named dataItemNodes. This object describes a data item associated with a server control. The value of the id property of the object is the value of the ClientID property of the server control, and the value of the content property is a string that contains the string representation of the data item. For example, this string representation could be an XML representation of the data item. case “dataItem”: Array.add(dataItemNodes, deltaNode); break;
❑
If the type is the string “dataItemJson”, the _onFormSubmitCompleted method adds the enumerated object to a local array named dataItemJsonNodes. This object describes a data item associated with a server control. The value of the id property of the object is the value of the ClientID property of the server control, and the value of the content property is a string that contains the JSON representation of the data item. case “dataItemJson”: Array.add(dataItemJsonNodes, deltaNode); break;
1190
c24.indd 1190
8/20/07 8:47:48 PM
Chapter 24: Asynchronous Partial Page Rendering ❑
If the type is the string “scriptDispose”, the _onFormSubmitCompleted method adds the enumerated object to a local array named scriptDisposeNodes. This object describes a script that contains a call into a dispose method associated with an UpdatePanel server control. The value of the id property of the object is the value of the ClientID property of the UpdatePanel server control, and the value of the content property is a string that contains the calls into the dispose method. case “scriptDispose”: Array.add(scriptDisposeNodes, deltaNode); break;
❑
The following code fragment shows an example of the value of the content property. This example registers the $find(‘UpdatePanel1’).dispose(); script for the UpdatePanel server control whose ClientID property has the value of “UpdatePanel1”:
If the type is the string “pageRedirect”, the _onFormSubmitCompleted method assigns the value of the content property of the enumerated object to the href property of the location property of the window object. As you can see, the value of the content property of this object is a string that contains the URL to which the current window will be redirected: case “pageRedirect”: window.location.href = deltaNode.content; return;
❑
If the type is the string “error”, the enumerated object describes a server error: the value of the id property of the object is a string that contains the number associated with the error, and the value of the content property of the object is a string that contains the error message. As you can see, the _onFormSubmitCompleted method calls the _endPostBack method on the current PageRequestManager instance to end the current request: case “error”: this._endPostBack(this._createPageRequestManagerServerError( Number.parseInvariant(deltaNode.id), deltaNode.content), sender); return;
❑
If the type is the string “pageTitle”, the enumerated object describes the title of the current page: the value of the content property of the object is a string that contains the new title of the page. Because of this, the _onFormSubmitCompleted method assigns the value of the content property to the title property of the document object. case “pageTitle”: document.title = deltaNode.content; break;
1191
c24.indd 1191
8/20/07 8:47:48 PM
Chapter 24: Asynchronous Partial Page Rendering ❑
If the type is the string “focus”, the enumerated object describes the HTML element that must have the focus. The value of the id property of this object is an empty string, and the value of the content property is a string that contains the value of the ClientID property of the server control that must have the focus. As you can see, the _onFormSubmitCompleted method assigns the value of the content property of the object to the _controlIDToFocus field of the current PageRequestManager instance: case “focus”: this._controlIDToFocus = deltaNode.content; break;
❑
If the type is none of the preceding strings, the _onFormSubmitCompleted method calls the _endPostBack method on the current PageRequestManager instance to end the current postback request: default: this._endPostBack(this._createPageRequestManagerParserError( String.format(Sys.WebForms.Res.PRM_UnknownToken, deltaNode.type)), sender); return;
Next, the _onFormSubmitCompleted method stores the contents of the _updatePanelIDs array in the _oldUpdatePanelIDs array field of the current PageRequestManager instance: this._oldUpdatePanelIDs = this._updatePanelIDs;
Then the method uses the childUpdatePanelIDsNode to populate the _childUpdatePanelIDs array of the current PageRequestManager instance. Keep in mind that this array contains the value of the UniqueID properties of the UpdatePanel server controls that need updating because their parent UpdatePanel server control needs updating: var childUpdatePanelIDsString = childUpdatePanelIDsNode.content; this._childUpdatePanelIDs = childUpdatePanelIDsString.length ? childUpdatePanelIDsString.split(‘,’) : [];
Next, the method uses the panelsToRefreshNode to populate the _panelsToRefreshIDs array of the current PageRequestManager instance. Keep in mind that this array contains the value of the UniqueID properties of the UpdatePanel server controls that need updating: this._panelsToRefreshIDs = this._splitNodeIntoArray(panelsToRefreshNode);
Next the method iterates through the UniqueID property values in the _panelsToRefreshIDs array, passes each enumerated value into the _uniqueIDToClientID method to return the value of its associated ClientID property, and finally calls the getElementById method, passing in this ClientID property value to check whether the current page contains an UpdatePanel server control with the specified UniqueID and ClientID property values. If not, it calls the _endPostBack method to end the current request:
1192
c24.indd 1192
8/20/07 8:47:49 PM
Chapter 24: Asynchronous Partial Page Rendering for (i = 0; i < this._panelsToRefreshIDs.length; i++) { var panelClientID = this._uniqueIDToClientID(this._panelsToRefreshIDs[i]); if (!document.getElementById(panelClientID)) { this._endPostBack(Error.invalidOperation( String.format(Sys.WebForms.Res.PRM_MissingPanel, panelClientID)), sender); return; } }
Next, the _onFormSubmitCompleted method calls the _splitNodeIntoArray method of the PageRequestManager three times to convert asyncPostBackControlIDsNode, postBackControlIDsNode, and updatePanelIDsNode into arrays: var asyncPostBackControlIDsArray = this._splitNodeIntoArray(asyncPostBackControlIDsNode); var postBackControlIDsArray = this._splitNodeIntoArray(postBackControlIDsNode); var updatePanelIDsArray = this._splitNodeIntoArray(updatePanelIDsNode); var asyncPostBackTimeout = asyncPostBackTimeoutNode.content;
Next, it calls the _updateControls method on the current PageRequestManager instance, passing in the following parameters:
❑
updatePanelIDsArray: This parameter is an array that contains the values of the UniqueID properties of all UpdatePanel server controls on the current page after the update. I say “after
the update” because this array has just arrived from the server. Because of this, the content of the _updatePanelIDs array of the current PageRequestManager instance could be out of date: the server code may have added a new UpdatePanel server control or deleted an existing UpdatePanel server control.
❑
asyncPostBackControlIDsArray: This parameter is an array that contains the values of the UniqueID properties of all the server controls on the current page that cause asynchronous page
postbacks.
❑
postBackControlIDsArray: This parameter is an array that contains the values of the UniqueID properties of all the server controls on the current page that cause normal
synchronous page postbacks.
❑
asyncPostBackTimeout: This parameter is a string that contains the timeout value for
I thoroughly discussed the _updateControls method of the PageRequestManager in Chapter 22. Next, the _onFormSubmitCompleted method iterates through the objects in the dataItemNodes array (recall that this array contains all the objects that represent data items) and uses the value of the id property of each enumerated object as an index into the _dataItems collection of the current
1193
c24.indd 1193
8/20/07 8:47:49 PM
Chapter 24: Asynchronous Partial Page Rendering PageRequestManager instance to store the value of the content property of the enumerated object into the collection. Recall that the value of the content property of the enumerated object is a string that contains the string representation of the data item associated with the server control whose UniqueID property value is given by the value of the id property of the enumerated object. In other words, each item in the _dataItems collection of the current PageRequestManager instance contains the string representation of a data item associated with a server control that has a specified UniqueID property value: this._dataItems = {}; for (i = 0; i < dataItemNodes.length; i++) { var dataItemNode = dataItemNodes[i]; this._dataItems[dataItemNode.id] = dataItemNode.content; }
Next, the _onFormSubmitCompleted method iterates through the objects in the dataItemJsonNodes array (recall that this array contains all the objects that represent JSON data items) and uses the value of the id property of each enumerated object as an index into the _dataItems collection of the current PageRequestManager instance to store the value of the content property of the enumerated object into the collection. Recall that the value of the content property of the enumerated object is a string that contains the JSON representation of the data item associated with the server control whose UniqueID property value is given by the value of the id property of the enumerated object: for (i = 0; i < dataItemJsonNodes.length; i++) { var dataItemJsonNode = dataItemJsonNodes[i]; this._dataItems[dataItemJsonNode.id] = eval(dataItemJsonNode.content); }
Next, the _onFormSubmitCompleted method calls the get_eventHandlerList method on the current PageRequestManager instance to return a reference to the EventHandlerList that contains all the event handlers registered for the events of the PageRequestManager instance. Then it calls the getHandler method on this EventHandlerList to return a reference to a JavaScript function whose invocation automatically invokes all the event handlers registered for the pageLoading event of the current PageRequestManager instance: var handler = this._get_eventHandlerList().getHandler(“pageLoading”);
Next, it calls the _getPageLoadingEventArgs method on the current PageRequestManager instance to instantiate and return a PageLoadingEventArgs object. As you’ll see later, the PageLoadingEventArgs is the event data class for the pageLoading event of the PageRequestManager class: var Sys.WebForms.PageLoadingEventArgs args = this._getPageLoadingEventArgs();
Then it calls the previously mentioned JavaScript function and consequently all the event handlers registered for the pageLoading event of the current PageRequestManager instance, passing in a reference to the current PageRequestManager instance and the PageLoadingEventArgs object: handler(this, args);
1194
c24.indd 1194
8/20/07 8:47:49 PM
Chapter 24: Asynchronous Partial Page Rendering If you register an event handler for the pageLoading event of the current PageRequestManager instance, your event handler will receive the previously mentioned two references. Your handler can then use these two references to get the complete information about the current request and use this information to perform application-specific page-loading tasks. Next, the _onFormSubmitCompleted method checks whether the formActionNode local variable is null. Recall that this variable references the object that describes the action property of the current form. If the variable is not null, the method assigns the value of the content property of this object to the action property of the form. You may be wondering why an asynchronous page postback may end up changing the action property of the current form. This normally happens when cookieless sessions are used, in which the session ID is embedded in the target URL, which changes the action value: if (formActionNode) this._form.action = formActionNode.content;
Next, the method iterates through the objects in the updatePanelNodes array (recall that each object in this array describes an UpdatePanel server control that needs updating) and takes the following steps for each enumerated object. First, it calls the getElementById method on the document object, passing in the value of the id property of the enumerated object. Recall that the value of this property is a string that contains the value of the ClientID property of the UpdatePanel server control that the object describes. Therefore, the getElementById method returns a reference to the DOM element associated with the UpdatePanel server control: var deltaUpdatePanel = updatePanelNodes[i]; var updatePanelElement = document.getElementById(deltaUpdatePanel.id);
If the current page does not contain a DOM element associated with the UpdatePanel server control, the _onFormSubmitCompleted method calls the _endPostBack method on the current PageRequestManager instance to end the current request: if (!updatePanelElement) { this._endPostBack(Error.invalidOperation( String.format(Sys.WebForms.Res.PRM_MissingPanel, deltaPanelID)), sender); return; }
Next, the method calls the _updatePanel method on the current PageRequestManager instance, passing in a reference to the DOM element that represents the UpdatePanel server control and the value of the content property of the enumerated object. Recall that the value of this property is a string that contains the markup text for the UpdatePanel server control. As you’ll see later, the _updatePanel server control updates the content of the specified UpatePanel server control with the specified HTML markup text. this._updatePanel(updatePanelElement, deltaUpdatePanel.content);
Next, the method iterates through the objects in the scriptDisposeNodes array. Recall that the value of the content property of each object in this array contains a script that disposes the server control whose ClientID property value is given by the value of the id property of the object. The _onFormSubmitCompleted method calls the _registerDisposeScript method on the current PageRequestManager instance, passing in the values of the id and content properties of the
1195
c24.indd 1195
8/20/07 8:47:50 PM
Chapter 24: Asynchronous Partial Page Rendering enumerated object. As you’ll see later, the _registerDisposeScript method of the current PageRequestManager instances registers the specified dispose script for the specified UpdatePanel server control: for (i = 0; i < scriptDisposeNodes.length; i++) { var disposePanelId = scriptDisposeNodes[i].id; var disposeScript = scriptDisposeNodes[i].content; this._registerDisposeScript(disposePanelId, disposeScript); }
Next, the method iterates through the objects in the hiddenFieldNodes array. Recall that each object in this array describes a hidden field for which the value of the id property of the object contains the value of the id HTML attribute of the hidden field, and the value of the content property of the object contains the value that must be stored in the hidden field. The _onFormSubmitCompleted method takes the following steps for each enumerated object. First, it calls the getElementById method on the document object to check whether the current page already contains a hidden field with the specified id HTML attribute value. var hiddenFieldElement = document.getElementById(hiddenFieldNodes[i].id);
If so, it simply stores the value of the content property of the enumerated object in the existing hidden field: hiddenFieldElement.value = value;
If not, it takes the following steps to create a new hidden field. First, it calls the createElement method on the document object to create a new input HTML element: hiddenFieldElement = document.createElement(‘input’);
Then it assigns the value of the id property of the enumerated object to the id property of the newly instantiated input HTML element: hiddenFieldElement.id = hiddenFieldNodes[i].id;
Next, the _onFormSubmitCompleted method assigns the value of the id property of the enumerated object to the name property of the newly instantiated input HTML element: hiddenFieldElement.name = hiddenFieldNodes[i].id;
Next, it sets the type property of the newly instantiated input HTML element to hidden: hiddenFieldElement.type = ‘hidden’;
Finally, it calls the appendChild method on the form element to append the newly instantiated hidden field as the child of the form element: this._form.appendChild(hiddenFieldElement);
1196
c24.indd 1196
8/20/07 8:47:50 PM
Chapter 24: Asynchronous Partial Page Rendering Next, the _onFormSubmitCompleted method iterates through the objects in the arrayDeclarationNodes array. Recall that each object in this array represents an array declaration for which the value of the id property of the object contains the name of the array being declared, and the value of the content property of the object contains the value being stored in the array. As you can see, the method takes the following steps for each object in the arrayDeclarationNodes array. First, it creates a string that contains a call into the _addArrayElement static method of the PageRequestManager class, passing in the values of the id and content properties of the object as the arguments of the method. Next, it adds this string to a local string named arrayScript that accumulates all the strings associated with the objects in the arrayDeclarationNodes array: var arrayScript = ‘’; for (i = 0; i < arrayDeclarationNodes.length; i++) { arrayScript += “Sys.WebForms.PageRequestManager._addArrayElement(‘” + arrayDeclarationNodes[i].id + “’, “ + arrayDeclarationNodes[i].content + “);\r\n”; }
Next, the _onFormSubmitCompleted method iterates through the objects in the expandoNodes array. Recall that each object in this array describes an expando attribute for which the values of the id and content properties of the object contain the name and value, respectively of the expando attribute. As you can see, the _onFormSubmitCompleted method forms a string for each object that consists of two substrings separated by the equals sign, these substrings containing the name and value, respectively, of the associated expando attribute. Note that the expandoScript string accumulates all these strings. var expandoScript = ‘’; for (i = 0; i < expandoNodes.length; i++) { var propertyReference = expandoNodes[i].id; var propertyValue = expandoNodes[i].content; expandoScript += propertyReference + “ = “ + propertyValue + “\r\n”; }
As you can see, the server response to an asynchronous page postback may contain scripts. The current page may also contain scripts. Therefore, you need a way to avoid duplicate scripts. The ASP.NET AJAX client-side framework comes with an internal class named _ScriptLoader that provides the current PageRequestManager instance with script-loading services. The _onFormSubmitCompleted method of the current PageRequestManager instance, shown in Listing 24-5, uses these services to avoid loading duplicate scripts as follows:
❑
The method begins by calling the readLoadedScripts static method on the _ScriptLoader class. As you’ll see later, this static method populates an internal static collection named _referencedScripts with the values of the src HTML attributes of all the script HTML elements that currently exist on the current page. I say currently because the server response to the current asynchronous page postback request may contain references to script files that the existing script HTML elements on the current page may or may not reference. Sys._ScriptLoader.readLoadedScripts();
1197
c24.indd 1197
8/20/07 8:47:50 PM
Chapter 24: Asynchronous Partial Page Rendering ❑
The method then calls the getInstance static method of the _ScriptLoader class to access the current _ScriptLoader instance. Each page can have only one instance of the _ScriptLoader class. As you’ll see later, the getInstance method checks whether an internal static field named _instance references an instance of the _ScriptLoader class. If so, it simply returns this reference. If not, it creates and returns a new instance of the _ScriptLoader class and stores this instance in this internal field for future use. This ensures that the current page always uses the same instance of the _ScriptLoader class. var scriptLoader = Sys._ScriptLoader.getInstance();
❑
Next, the method calls the queueScriptBlock method on the current _ScriptLoader instance to queue the script contained in the arrayScript string. Recall that the arrayScript string contains the script that declares one or more JavaScript arrays. The current page may or may not contain the same ones.
❑
As you’ll see later, the queueScriptBlock method simply adds the specified script to an internal collection named _scriptsToLoad: if (arrayScript.length) scriptLoader.queueScriptBlock(arrayScript);
❑
Next, the method calls the queueScriptBlock method on the current _ScriptLoader instance to queue the script contained in the expandoScript string. Recall that the expandoScript string contains the script that defines one or more expando attributes: if (expandoScript.length) scriptLoader.queueScriptBlock(expandoScript);
❑
Then the method iterates through the objects in the scriptBlockNodes array and takes the following steps for each enumerated object:
❑
If the value of the id property of the object is the string “ScriptContentNoTags”, this is an indication that the value of the content property of the object contains a script block. Therefore, the method calls the queueScriptBlock method on the current _ScriptLoader instance to queue this script block: case “ScriptContentNoTags”: scriptLoader.queueScriptBlock(scriptBlockNodes[i].content); break;
❑
If the value of the id property of the object is the string “ScriptContentWithTags”, this is an indication that the value of the content property of the object does not contain a script block. Instead it contains the JSON representation of the attributes of a script HTML element. You can think of this JSON representation as the serialized form of these attributes. It contains one name/value pair for each attribute, where the name part of the pair is a string that contains the name of the attribute, and the value part is a string that contains the value of the attribute. Keep in mind that some of these attributes may be custom attributes.
1198
c24.indd 1198
8/20/07 8:47:51 PM
Chapter 24: Asynchronous Partial Page Rendering ❑
The _onFormSubmitCompleted method first checks whether this JSON representation contains a name/value pair for the src HTML attribute. If so, it uses the name part of this pair — that is, the keyword src — to access the value part of the pair — that is, the URL of the referenced script file — and calls the isScriptLoaded static method on the _ScriptLoader class to check whether the internal _referencedScripts collection contains an entry for this URL. (Recall that this collection contains the URLs of all the currently referenced script files.) If so, the _onFormSubmitCompleted method skips the enumerated object. If not, it calls the queueCustomScriptTag method on the current _ScriptLoader instance, passing in the JSON representation of the script attributes. As you’ll see later, this method simply adds this JSON representation to an internal collection named _scriptsToLoad. This collection contains one object for each script file that needs to be loaded, and describes the HTML standard and custom script attributes. case “ScriptContentWithTags”: var scriptTagAttributes; eval(“scriptTagAttributes = “ + scriptBlockNodes[i].content); if (scriptTagAttributes.src && Sys._ScriptLoader.isScriptLoaded(scriptTagAttributes.src)) continue; scriptLoader.queueCustomScriptTag(scriptTagAttributes); break;
❑
If the value of the id property of the object is the string “ScriptPath”, this is an indication that the value of the content property of the object does not contain a script block. Instead it contains the URL of a script file. The _onFormSubmitCompleted method first calls the isScriptLoaded static method on the _ScriptLoader class to check whether the internal _referencedScripts collection contains an entry for this URL. If so, it simply skips the enumerated object because the associated script has already been loaded. If not, it calls the queueScriptReference method on the current _ScriptLoader instance, passing in the value of the content property of the enumerated object — that is, the URL. As you’ll see later, this method creates an object with a single name/value pair and adds the object to the internal _scriptsToLoad collection. The name part of this name/value pair is the keyword src and the value part is the URL.
❑
Keep in mind that _scriptsToLoad is a collection of objects in which each object describes the HTML standard and custom script attributes associated with a particular script file. To put it differently, this collection contains information about the script files that need to be downloaded from the server. case “ScriptPath”: if (Sys._ScriptLoader.isScriptLoaded(scriptBlockNodes[i].content)) continue; scriptLoader.queueScriptReference(scriptBlockNodes[i].content); break;
❑
Next, the _onFormSubmitCompleted method iterates through the objects in the onSubmitNodes array. Recall that each object in this array describes a dynamically added form onsubmit statement for which the value of the id property of the object is an empty string and the value of the content property is a string that contains the dynamically added form onsubmit statement.
1199
c24.indd 1199
8/20/07 8:47:51 PM
Chapter 24: Asynchronous Partial Page Rendering ❑
The _onFormSubmitCompleted method creates a local string named onSubmitStatementScript that contains a script that adds a dynamically generated JavaScript function to the _onSubmitStatements collection of the current PageRequestManager instance. Note that the method iterates through the objects in the onSubmitNodes collection and adds the value of the content property of each enumerated object to the body of this dynamically generated JavaScript function. var onSubmitStatementScript = ‘’; for (var i = 0; i < onSubmitNodes.length; i++) { if (i === 0) onSubmitStatementScript = ‘Array.add(Sys.WebForms.PageRequestManager .getInstance()._onSubmitStatements, function() {\r\n’; onSubmitStatementScript += onSubmitNodes[i].content + “\r\n”; }
❑
Next, the method calls the queueScriptBlock method on the current _ScriptLoader instance that is passing in the local onSubmitStatementScript string. As you’ll see later, the queueScriptBlock method creates a object with a single name/value pair and adds the object to the internal _scriptsToLoad collection of the current _ScriptLoader instance. The name part of this name/value pair is the keyword text and the value part contains the content of the onSubmitStatementScript string. if (onSubmitStatementScript.length) { onSubmitStatementScript += “\r\nreturn true;\r\n});\r\n”; scriptLoader.queueScriptBlock(onSubmitStatementScript); }
❑
Next, the _onFormSubmitCompleted method stores the reference to the WebRequestExecutor object responsible for executing the current request in the _response field of the current PageRequestManager instance:
this._response = sender;
❑
Next, the _onFormSubmitCompleted method calls the createDelegate static method on the function to create a delegate that represents the _scriptsLoadComplete method of the current PageRequestManager instance: var scriptLoadCompleteDelegate = Function.createDelegate(this, this._scriptsLoadComplete);
❑
Finally, the _onFormSubmitCompleted method calls the loadScripts method on the current _ScriptLoader instance, passing in the delegate. As you’ll see later, this method will load the scripts in the _scriptsToLoad collection: scriptLoader.loadScripts(0, scriptLoadCompleteDelegate, null, null);
1200
c24.indd 1200
8/20/07 8:47:51 PM
Chapter 24: Asynchronous Partial Page Rendering Listing 24-5 : The _onFormSubmitCompleted Method of the PageRequestManager function Sys$WebForms$PageRequestManager$_onFormSubmitCompleted(sender, eventArgs) { this._processingRequest = true; var delimitByLengthDelimiter = ‘|’; if (sender.get_timedOut()) { this._endPostBack(this._createPageRequestManagerTimeoutError(), sender); return; } if (sender.get_aborted()) { this._endPostBack(null, sender); return; } if (!this._request || sender.get_webRequest() !== this._request) return; var errorMessage; var delta = []; if (sender.get_statusCode() !== 200) { this._endPostBack( this._createPageRequestManagerServerError(sender.get_statusCode()), sender); return; } var reply = sender.get_responseData(); var delimiterIndex, len, type, id, content; var replyIndex = 0; var parserErrorDetails = null; while (replyIndex < reply.length) { delimiterIndex = reply.indexOf(delimitByLengthDelimiter, replyIndex); if (delimiterIndex === -1) { parserErrorDetails = this._findText(reply, replyIndex); break; } len = parseInt(reply.substring(replyIndex, delimiterIndex), 10); if ((len % 1) !== 0) { parserErrorDetails = this._findText(reply, replyIndex); break; } replyIndex = delimiterIndex + 1; delimiterIndex = reply.indexOf(delimitByLengthDelimiter, replyIndex);
(continued)
1201
c24.indd 1201
8/20/07 8:47:51 PM
Chapter 24: Asynchronous Partial Page Rendering Listing 24-5 (continued) if (delimiterIndex === -1) { parserErrorDetails = this._findText(reply, replyIndex); break; } type = reply.substring(replyIndex, delimiterIndex); replyIndex = delimiterIndex + 1; delimiterIndex = reply.indexOf(delimitByLengthDelimiter, replyIndex); if (delimiterIndex === -1) { parserErrorDetails = this._findText(reply, replyIndex); break; } id = reply.substring(replyIndex, delimiterIndex); replyIndex = delimiterIndex + 1; if ((replyIndex + len) >= reply.length) { parserErrorDetails = this._findText(reply, reply.length); break; } content = this._decodeString(reply.substr(replyIndex, len)); replyIndex += len; if (reply.charAt(replyIndex) !== delimitByLengthDelimiter) { parserErrorDetails = this._findText(reply, replyIndex); break; } replyIndex++; var obj = {type: type, id: id, content: content}; Array.add(delta, obj); } if (parserErrorDetails) { this._endPostBack(this._createPageRequestManagerParserError( String.format(Sys.WebForms.Res.PRM_ParserErrorDetails, parserErrorDetails)), sender); return; } var updatePanelNodes = []; var hiddenFieldNodes = []; var arrayDeclarationNodes = []; var scriptBlockNodes = []; var expandoNodes = []; var onSubmitNodes = []; var dataItemNodes = []; var dataItemJsonNodes = []; var scriptDisposeNodes = []; var asyncPostBackControlIDsNode, postBackControlIDsNode, updatePanelIDsNode, asyncPostBackTimeoutNode, childUpdatePanelIDsNode, panelsToRefreshNode, formActionNode;
1202
c24.indd 1202
8/20/07 8:47:52 PM
Chapter 24: Asynchronous Partial Page Rendering for (var i = 0; i < delta.length; i++) { var deltaNode = delta[i]; switch (deltaNode.type) { case “updatePanel”: Array.add(updatePanelNodes, deltaNode); break; case “hiddenField”: Array.add(hiddenFieldNodes, deltaNode); break; case “arrayDeclaration”: Array.add(arrayDeclarationNodes, deltaNode); break; case “scriptBlock”: Array.add(scriptBlockNodes, deltaNode); break; case “expando”: Array.add(expandoNodes, deltaNode); break; case “onSubmit”: Array.add(onSubmitNodes, deltaNode); break; case “asyncPostBackControlIDs”: asyncPostBackControlIDsNode = deltaNode; break; case “postBackControlIDs”: postBackControlIDsNode = deltaNode; break; case “updatePanelIDs”: updatePanelIDsNode = deltaNode; break; case “asyncPostBackTimeout”: asyncPostBackTimeoutNode = deltaNode; break; case “childUpdatePanelIDs”: childUpdatePanelIDsNode = deltaNode; break; case “panelsToRefreshIDs”: panelsToRefreshNode = deltaNode; break; case “formAction”: formActionNode = deltaNode; break; case “dataItem”: Array.add(dataItemNodes, deltaNode); break; case “dataItemJson”: Array.add(dataItemJsonNodes, deltaNode); break; case “scriptDispose”: Array.add(scriptDisposeNodes, deltaNode); break;
(continued)
1203
c24.indd 1203
8/20/07 8:47:52 PM
Chapter 24: Asynchronous Partial Page Rendering Listing 24-5 (continued) case “pageRedirect”: window.location.href = deltaNode.content; return; case “error”: this._endPostBack(this._createPageRequestManagerServerError( Number.parseInvariant(deltaNode.id), deltaNode.content), sender); return; case “pageTitle”: document.title = deltaNode.content; break; case “focus”: this._controlIDToFocus = deltaNode.content; break; default: this._endPostBack(this._createPageRequestManagerParserError( String.format(Sys.WebForms.Res.PRM_UnknownToken, deltaNode.type)), sender); return; } } var i; if (asyncPostBackControlIDsNode && postBackControlIDsNode && updatePanelIDsNode && panelsToRefreshNode && asyncPostBackTimeoutNode && childUpdatePanelIDsNode) { this._oldUpdatePanelIDs = this._updatePanelIDs; var childUpdatePanelIDsString = childUpdatePanelIDsNode.content; this._childUpdatePanelIDs = childUpdatePanelIDsString.length ? childUpdatePanelIDsString.split(‘,’) : []; var asyncPostBackControlIDsArray = this._splitNodeIntoArray(asyncPostBackControlIDsNode); var postBackControlIDsArray = this._splitNodeIntoArray(postBackControlIDsNode); var updatePanelIDsArray = this._splitNodeIntoArray(updatePanelIDsNode); this._panelsToRefreshIDs = this._splitNodeIntoArray(panelsToRefreshNode); for (i = 0; i < this._panelsToRefreshIDs.length; i++) { var panelClientID = this._uniqueIDToClientID(this._panelsToRefreshIDs[i]); if (!document.getElementById(panelClientID)) { this._endPostBack(Error.invalidOperation( String.format(Sys.WebForms.Res.PRM_MissingPanel, panelClientID)), sender); return; } } var asyncPostBackTimeout = asyncPostBackTimeoutNode.content; this._updateControls(updatePanelIDsArray, asyncPostBackControlIDsArray, postBackControlIDsArray, asyncPostBackTimeout); }
1204
c24.indd 1204
8/20/07 8:47:52 PM
Chapter 24: Asynchronous Partial Page Rendering this._dataItems = {}; for (i = 0; i < dataItemNodes.length; i++) { var dataItemNode = dataItemNodes[i]; this._dataItems[dataItemNode.id] = dataItemNode.content; } for (i = 0; i < dataItemJsonNodes.length; i++) { var dataItemJsonNode = dataItemJsonNodes[i]; this._dataItems[dataItemJsonNode.id] = eval(dataItemJsonNode.content); } var handler = this._get_eventHandlerList().getHandler(“pageLoading”); if (handler) handler(this, this._getPageLoadingEventArgs()); if (formActionNode) { this._form.action = formActionNode.content; this._form._initialAction = this._form.action; } for (i = 0; i < updatePanelNodes.length; i++) { var deltaUpdatePanel = updatePanelNodes[i]; var deltaPanelID = deltaUpdatePanel.id; var deltaPanelRendering = deltaUpdatePanel.content; var updatePanelElement = document.getElementById(deltaPanelID); if (!updatePanelElement) { this._endPostBack(Error.invalidOperation( String.format(Sys.WebForms.Res.PRM_MissingPanel, deltaPanelID)), sender); return; } this._updatePanel(updatePanelElement, deltaPanelRendering); } for (i = 0; i < scriptDisposeNodes.length; i++) { var disposePanelId = scriptDisposeNodes[i].id; var disposeScript = scriptDisposeNodes[i].content; this._registerDisposeScript(disposePanelId, disposeScript); } for (i = 0; i < hiddenFieldNodes.length; i++) { var id = hiddenFieldNodes[i].id; var value = hiddenFieldNodes[i].content; var hiddenFieldElement = document.getElementById(id); if (!hiddenFieldElement) { hiddenFieldElement = document.createElement(‘input’); hiddenFieldElement.id = id; hiddenFieldElement.name = id; hiddenFieldElement.type = ‘hidden’; this._form.appendChild(hiddenFieldElement); } hiddenFieldElement.value = value; }
(continued)
1205
c24.indd 1205
8/20/07 8:47:53 PM
Chapter 24: Asynchronous Partial Page Rendering Listing 24-5 (continued) var arrayScript = ‘’; for (i = 0; i < arrayDeclarationNodes.length; i++) { arrayScript += “Sys.WebForms.PageRequestManager._addArrayElement(‘” + arrayDeclarationNodes[i].id + “’, “ + arrayDeclarationNodes[i].content + “);\r\n”; } var expandoScript = ‘’; for (i = 0; i < expandoNodes.length; i++) { var propertyReference = expandoNodes[i].id; var propertyValue = expandoNodes[i].content; expandoScript += propertyReference + “ = “ + propertyValue + “\r\n”; } Sys._ScriptLoader.readLoadedScripts(); Sys.Application.beginCreateComponents(); var scriptLoader = Sys._ScriptLoader.getInstance(); if (arrayScript.length) scriptLoader.queueScriptBlock(arrayScript); if (expandoScript.length) scriptLoader.queueScriptBlock(expandoScript); for (i = 0; i < scriptBlockNodes.length; i++) { var scriptBlockType = scriptBlockNodes[i].id; switch (scriptBlockType) { case “ScriptContentNoTags”: scriptLoader.queueScriptBlock(scriptBlockNodes[i].content); break; case “ScriptContentWithTags”: var scriptTagAttributes; eval(“scriptTagAttributes = “ + scriptBlockNodes[i].content); if (scriptTagAttributes.src && Sys._ScriptLoader.isScriptLoaded(scriptTagAttributes.src)) continue; scriptLoader.queueCustomScriptTag(scriptTagAttributes); break; case “ScriptPath”: if (Sys._ScriptLoader.isScriptLoaded(scriptBlockNodes[i].content)) continue; scriptLoader.queueScriptReference(scriptBlockNodes[i].content); break; } }
1206
c24.indd 1206
8/20/07 8:47:53 PM
Chapter 24: Asynchronous Partial Page Rendering var onSubmitStatementScript = ‘’; for (var i = 0; i < onSubmitNodes.length; i++) { if (i === 0) onSubmitStatementScript = ‘Array.add(Sys.WebForms.PageRequestManager.getInstance()._onSubmitStatements, function() {\r\n’; onSubmitStatementScript += onSubmitNodes[i].content + “\r\n”; } if (onSubmitStatementScript.length) { onSubmitStatementScript += “\r\nreturn true;\r\n});\r\n”; scriptLoader.queueScriptBlock(onSubmitStatementScript); } this._response = sender; scriptLoader.loadScripts(0, Function.createDelegate(this, this._scriptsLoadComplete), null, null); }
The _updatePanel Method of PageRequestManager Recall from Listing 24-5 that the _onFormSubmitCompleted method of the current PageRequestManager instance invokes the _updatePanel method on itself, passing in two parameters, the first of which references an UpdatePanel server control that needs refreshing and the second of which is a string that contains the new HTML markup text for this UpdatePanel server control. The main responsibility of the _updatePanel method is to the update the content of the specified UpdatePanel server control with the specified HTML markup text. As Listing 24-6 shows, this method searches through the _scriptDisposes dictionary of the current PageRequestManager instance for the collection or array that contains all the script disposes associated with the specified UpdatePanel server control. If it finds such a collection, it iterates through the script disposes in this collection and calls the eval JavaScript function on each script dispose to execute the script. This will allow these script disposes to release the resources that the UpdatePanel server control and its constituent client components are holding before the server control and its content are disposed of. It is necessary to release these resources because the UpdatePanel server control and its content is about to reload or refresh. var disposeScripts = this._scriptDisposes[updatePanelID]; for (var i = 0; i < disposeScripts.length; i++) { eval(disposeScripts[i]); }
1207
c24.indd 1207
8/20/07 8:47:53 PM
Chapter 24: Asynchronous Partial Page Rendering Recall from Listing 23-41 that you can use the RegisterDispose public method of the current ScriptManager server control to register dispose scripts for a specified child server control of a specified UpdatePanel server control on the current page. Recall that the RegisterDispose method takes two parameters. The first references the child server control for which the dispose script is being registered; the second is a string that contains the actual dispose script being registered. Next, the _onFormSubmitCompleted method deletes the collection from the _scriptDisposes dictionary. delete this._scriptDisposes[updatePanelID];
Next, it invokes the _destroyTree method on the current PageRequestManager instance, passing in the reference to the specified UpdatePanel server control to delete the DOM hierarchy associated with the server control and its content: this._destroyTree(updatePanelElement);
Finally, it assigns the string that contains the updated HTML markup text to the innerHTML property of the specified UpdatePanel server control: updatePanelElement.innerHTML = rendering;
Listing 24-6 : The _updatePanel Method of the PageRequestManager function Sys$WebForms$PageRequestManager$_updatePanel(updatePanelElement, rendering) { for (var updatePanelID in this._scriptDisposes) { var runDisposeScripts = false; var element = document.getElementById(updatePanelID); while (element) { if (element === updatePanelElement) { runDisposeScripts = true; break; } element = element.parentNode; } if (runDisposeScripts) { var disposeScripts = this._scriptDisposes[updatePanelID]; for (var i = 0; i < disposeScripts.length; i++) { eval(disposeScripts[i]); } delete this._scriptDisposes[updatePanelID]; } } this._destroyTree(updatePanelElement); updatePanelElement.innerHTML = rendering; }
1208
c24.indd 1208
8/20/07 8:47:53 PM
Chapter 24: Asynchronous Partial Page Rendering
The registerDisposeScript Method of PageRequestManager Recall from Listing 24-5 that the _onFormSubmitCompleted method of the current PageRequestManager instance iterates through a local collection named scriptDisposeNodes, as shown again in the following code listing: for (i = 0; i < scriptDisposeNodes.length; i++) { var disposePanelId = scriptDisposeNodes[i].id; var disposeScript = scriptDisposeNodes[i].content; this._registerDisposeScript(disposePanelId, disposeScript); }
As discussed earlier, the scriptDisposeNodes is a collection of objects, each of which describes a dispose script. Recall that the value of the id property of each object is a string that contains the ClientID property value of the UpdatePanel server control for which the dispose script is being registered, and that the value of the content property of this object is a string that contains the actual dispose script being registered. As the preceding code listing shows, the _onFormSubmitCompleted method calls the _registerDisposeScript method on the current PageRequestManager instance to register the specified dispose script for the UpdatePanel server control with the specified ClientID property value. Listing 24-7 presents the internal implementation of the _registerDisposeScript method. As you can see, this method first uses the ClientID property value as an index into the _scriptDisposes collection to return the array that holds all the dispose scripts registered for the UpdatePanel server control that has the specified ClientID property value. (Recall that the _scriptDisposes collection of the current PageRequestManager instance maintains one array for each server control.) Next, the _registerDisposeScript method adds the specified dispose script to the associated array.
Listing 24-7 : The _registerDisposeScript Method of the PageRequestManager function Sys$WebForms$PageRequestManager$_registerDisposeScript(panelID, disposeScript) { if (!this._scriptDisposes[panelID]) this._scriptDisposes[panelID] = [disposeScript]; else Array.add(this._scriptDisposes[panelID], disposeScript); }
_destroyTree Recall from Listing 24-6 that the _updatePanel method of the current PageRequestManager instance invokes the _destroyTree method on the current PageRequestMananger instance to destroy the entire DOM hierarchy that has the specified root DOM element. The _destroyTree method takes a reference to a DOM element and deletes it and all its descendant DOM elements. As Listing 24-8 shows, this method first makes sure that its argument is indeed an element. Then it iterates through the child DOM
1209
c24.indd 1209
8/20/07 8:47:54 PM
Chapter 24: Asynchronous Partial Page Rendering elements of the element and takes these steps for each. If the enumerated child DOM element supports the dispose method, _destroyTree invokes this method on the child element. If the enumerated child DOM element does not support the method but does expose a property named control that supports the method, _destroyTree calls the method on this property. (Recall that the control property of a DOM element references the client control associated with the element.) Next, it calls the getBehaviors method to return an array that contains all the behaviors associated with the enumerated DOM element and calls the dispose methods of these behaviors. Finally, it calls _destroyTree to destroy all the descendant DOM elements of the enumerated child element. As you can see, _destroyTree is a recursive method.
Listing 24-8: The _destroyTree Method of PageRequestManager function Sys$WebForms$PageRequestManager$_destroyTree(element) { if (element.nodeType === 1) { var childNodes = element.childNodes; for (var i = childNodes.length - 1; i >= 0; i--) { var node = childNodes[i]; if (node.nodeType === 1) { if (node.dispose && typeof(node.dispose) === “function”) node.dispose(); else if (node.control && typeof(node.control.dispose) === “function”) node.control.dispose(); var behaviors = Sys.UI.Behavior.getBehaviors(node); for (var j = behaviors.length - 1; j >= 0; j--) { behaviors[j].dispose(); } this._destroyTree(node); } } } }
_ScriptLoader The main responsibility of the _ScriptLoader class is to load the required scripts. As you saw, Listing 24-5 makes extensive use of this class. In this section, I’ll walk you though the implementation of the methods of the class.
readLoadedScripts Recall from Listing 24-5 that the _onSubmitFormCompleted method invokes the readLoadedScripts static method on the _ScriptLoader class. As Listing 24-9 shows, the readLoadedScripts method first instantiates the _referencedScripts static field of the class:
Next, it calls the getElementByTagName method on the document object to return an array that contains references to all the script HTML elements on the current page: var existingScripts = document.getElementsByTagName(‘SCRIPT’);
Finally, readLoadedScripts iterates through these script HTML elements and adds the value of the src HTML attribute of each element to the _referencedScripts static collection of the _ScriptLoader class: Array.add(Sys._ScriptLoader._referencedScripts, existingScripts[i].src);
Listing 24-9: The readLoadedScripts Static Method of the _ScriptLoader Class Sys._ScriptLoader.readLoadedScripts = function Sys$_ScriptLoader$readLoadedScripts() { if(!Sys._ScriptLoader._referencedScripts) { var existingScripts = document.getElementsByTagName(‘SCRIPT’); for (i = existingScripts.length - 1; i >= 0; i--) { if (existingScripts[i].src.length) { if (!Array.contains(Sys._ScriptLoader._referencedScripts, existingScripts[i].src)) Array.add(Sys._ScriptLoader._referencedScripts, existingScripts[i].src); } } } }
getInstance As Listing 24-10 shows, the getInstance static method of the _ScriptLoader class ensures that each page can have only one instance of the _ScriptLoader class.
Listing 24-10: The getInstance Static Method of the _ScriptLoader Class Sys._ScriptLoader.getInstance = function Sys$_ScriptLoader$getInstance() { if(!Sys._ScriptLoader._activeInstance) Sys._ScriptLoader._activeInstance = new Sys._ScriptLoader(); return Sys._ScriptLoader._activeInstance; }
1211
c24.indd 1211
8/20/07 8:47:54 PM
Chapter 24: Asynchronous Partial Page Rendering
queueScriptBlock As you can see from Listing 24-11, the queueScriptBlock method of the _ScriptLoader class creates an object with a single name/value pair and adds it to the _scriptToLoad array of the current _ScriptLoader instance. Note that the name part of this name/value pair is the keyword text and the value part contains the script being queued.
Listing 24-11: The queueScriptBlock Method of the _ScriptLoader Class function Sys$_ScriptLoader$queueScriptBlock(scriptContent) { if(!this._scriptsToLoad) this._scriptsToLoad = []; Array.add(this._scriptsToLoad, {text: scriptContent}); }
queueCustomScriptTag Recall from Listing 24-5 that the _onFormSubmitCompleted method of the current PageRequestManager instance calls the queueCustomScriptTag method on the current _ScriptLoader instance, passing in the object that represents the serialized form of the attributes of a script HTML element. As Listing 24-12 shows, the queueCustomScriptTag method adds this object to the _scriptsToLoad collection of the current _scriptLoader instance.
Listing 24-12: The queueCustomScriptTag Method of the _ScriptLoader Class function Sys$_ScriptLoader$queueCustomScriptTag(scriptAttributes) { if(!this._scriptsToLoad) this._scriptsToLoad = []; Array.add(this._scriptsToLoad, scriptAttributes); }
isScriptLoaded Recall from Listing 24-5 that the _onFormSubmitCompleted method of the current PageRequestManager instance invokes the isScriptLoaded static method on the _ScriptLoader class to determine whether the script file with the specified URL has already been loaded. Listing 24-13 presents the implementation of this method.
Listing 24-13: The isScriptLoaded Static Method of the _ScriptLoader Class Sys._ScriptLoader.isScriptLoaded = function Sys$_ScriptLoader$isScriptLoaded(scriptSrc) { var dummyScript = document.createElement(‘script’); dummyScript.src = scriptSrc; return Array.contains(Sys._ScriptLoader._getLoadedScripts(), dummyScript.src); }
1212
c24.indd 1212
8/20/07 8:47:55 PM
Chapter 24: Asynchronous Partial Page Rendering
_getLoadedScript As Listing 24-14 shows, the _getLoadedScripts static method of the _ScriptLoader class simply returns a reference to the _referencedScripts collection, which contains the values of the src HTML attributes of all the script HTML elements that currently exist on the current page.
Listing 24-14: The _getLoadedScripts Static Method of the _ScriptLoader Class Sys._ScriptLoader._getLoadedScripts = function Sys$_ScriptLoader$_getLoadedScripts() { if(!Sys._ScriptLoader._referencedScripts) { Sys._ScriptLoader._referencedScripts = []; Sys._ScriptLoader.readLoadedScripts(); } return Sys._ScriptLoader._referencedScripts; }
queueScriptReference Recall from Listing 24-5 that the _onFormSubmitCompleted method of the current client script PageRequestManager instance calls the queueScriptReference method on the current _ScriptLoader instance to queue the specified script reference. As Listing 24-15 shows, this method creates an object with a single name/value pair, the name part of the pair being the keyword src and the value part the URL of the JavaScript file passed into the method as its only argument. The method then adds this object to the _scriptsToLoad collection of the current _ScriptLoader instance.
Listing 24-15: The queueScriptReference Method of the _ScriptLoader Class function Sys$_ScriptLoader$queueScriptReference(scriptUrl) { if(!this._scriptsToLoad) this._scriptsToLoad = []; Array.add(this._scriptsToLoad, {src: scriptUrl}); }
loadScripts Recall from Listing 24-5 that the _onFormSubmitCompleted method of the current client-side PageRequestManager instance calls the loadScripts method on the current _ScriptLoader instance to load the scripts in the _scriptsToLoad collection. As Listing 24-16 shows, this method takes four parameters. The first contains the script loading timeout, the second references the JavaScript function that will be automatically invoked if all the scripts in the _scriptsToLoad collection are loaded, the third references the JavaScript function that will be automatically invoked if the script loading fails, and the fourth parameter references the JavaScript function that will be automatically invoked if the scripts in the _scriptsToLoad collection do not load within the time specified by the first parameter of the method.
1213
c24.indd 1213
8/20/07 8:47:55 PM
Chapter 24: Asynchronous Partial Page Rendering As you can see from Listing 24-16, the loadScripts method first checks whether the _loading field of the current _ScriptLoader instance is set to true. If so, this is an indication that the scripts in the _scriptsToLoad collection are already being loaded. Therefore, an invalid operation exception is raised: if(this._loading) throw Error.invalidOperation(Sys.Res.scriptLoaderAlreadyLoading);
Next, the loadScripts method sets the _loading flag to true to signal that the scripts in the _scriptsToLoad collection are being loaded: this._loading = true;
Then it stores its second parameter in the _allScriptsLoadedCallback field of the current _ScriptLoader instance: this._allScriptsLoadedCallback = allScriptsLoadedCallback;
Recall from Listing 24-5 that the _onFormSubmitCompleted method of the current PageRequestManager instance passes the following delegate as the second parameter of the loadScripts method: Function.createDelegate(this, this._scriptsLoadComplete)
As you can see, this delegate represents the _scriptLoadComplete method of the current PageRequestManager instance. This means that when all the scripts in the _scriptsToLoad collection of the current PageRequestManager instance are finally loaded, the current _ScriptLoader instance will automatically invoke this delegate and consequently the _scriptsLoadComplete method that it represents. As Listing 24-16 shows, the loadScripts method finally invokes the _loadScriptsInternal method on the current _ScriptLoader instance to load the scripts in the _scriptsToLoad collection of the current _ScriptLoader instance: this._loadScriptsInternal();
Listing 24-16: The loadScripts Method of the _ScriptLoader Class function Sys$_ScriptLoader$loadScripts(scriptTimeout, allScriptsLoadedCallback, scriptLoadFailedCallback, scriptLoadTimeoutCallback) { if(this._loading) throw Error.invalidOperation(Sys.Res.scriptLoaderAlreadyLoading); this._loading = true; this._allScriptsLoadedCallback = allScriptsLoadedCallback; this._scriptLoadFailedCallback = scriptLoadFailedCallback; this._scriptLoadTimeoutCallback = scriptLoadTimeoutCallback; this._loadScriptsInternal(); }
1214
c24.indd 1214
8/20/07 8:47:55 PM
Chapter 24: Asynchronous Partial Page Rendering
_loadScriptsInternal Listing 24-17 presents the internal implementation of the _loadScriptsInternal method of the current _ScriptLoader instance. Recall that the _scriptsToLoad array of the current _ScriptLoader instance contains one object for each script that needs to be loaded. This object contains the complete information about its associated script. Note that the _loadScriptsInternal method is a recursive function, meaning that the method calls itself to load the script described by the next object in the _scriptsToLoad array. This method checks whether the _scriptsToLoad collection contains any more objects. If not, it first calls the _stopLoading method on the current _ScriptLoader instance to end the script-loading process and then calls the _allScriptsLoadedCallback method to notify its caller that all the scripts have been loaded. As discussed earlier, the _allScriptsLoadedCallback field of the current _ScriptLoader instance references the delegate that represents the _scriptsLoadComplete method of the current PageRequestManager instance. var callback = this._allScriptsLoadedCallback; this._stopLoading(); if(callback) callback(this);
If the _scriptsToLoad collection contains more objects, the _loadScriptsInternal method calls the dequeue static method on the Array to dequeue the next object from the _scriptsToLoad collection: var nextScript = Array.dequeue(this._scriptsToLoad);
Next, it calls the _createScriptElement method on the current _ScriptLoader instance that is passing in the dequeued object. As you’ll see later, this method creates an HTML script element and uses the values of the properties of the object to initialize the attributes of this script element. var scriptElement = this._createScriptElement(nextScript);
Next, the _loadScriptsInternal method checks whether the object contains a name/value pair associated with the src script attribute. If so, this is an indication that the object describes a script file that must be downloaded from the server. Because of this, we have to worry about issues such as timeout. Therefore, the _loadScriptsInternal method instantiates an instance of an ASP.NET AJAX class named _ScriptLoaderTask, passing a reference to the newly instantiated script element and a reference to the delegate referenced by the _scriptLoadedDelegate field of the current _ScriptLoader instance. As you’ll see later, the constructor of the _ScriptLoader class creates a delegate that represents the _scriptLoadedHandler method of the current _ScriptLoader instance and assigns this delegate to the _scriptLoadedDelegate field. this._currentTask = new Sys._ScriptLoaderTask(scriptElement, this._scriptLoadedDelegate);
Next, the _loadScriptsInternal method invokes the execute method on the current ScriptLoaderTask instance to execute the task. The execute method basically downloads the script file referenced by the specified script element: this._currentTask.execute();
1215
c24.indd 1215
8/20/07 8:47:55 PM
Chapter 24: Asynchronous Partial Page Rendering If the object does not contain a name/value pair associated with the src script attribute, this indicates that the object does not describe a script file to be downloaded from the server. Instead it describes a literal script. Therefore the _loadScriptsInternal method first accesses the head HTML element: var headElement = document.getElementsByTagName(‘HEAD’)[0];
Next, it calls the appendChild method on the head HTML element to append the script element as its child element. Appending this script element immediately runs the script enclosed within the opening and closing tags of the script element: headElement.appendChild(scriptElement);
Next, the _loadScriptsInternal method removes the script element because you do not need the element after running its contained script: scriptElement.parentNode.removeChild(scriptElement);
Finally, it calls the _loadScriptsInternal method to load the script associated with the next object in the _scriptsToLoad collection: this._loadScriptsInternal();
Listing 24-17: The _loadScriptsInternal Method of the _ScriptLoader Class function Sys$_ScriptLoader$_loadScriptsInternal() { if (this._scriptsToLoad && this._scriptsToLoad.length > 0) { var nextScript = Array.dequeue(this._scriptsToLoad); var scriptElement = this._createScriptElement(nextScript); if (scriptElement.text && Sys.Browser.agent === Sys.Browser.Safari) { scriptElement.innerHTML = scriptElement.text; delete scriptElement.text; } if (typeof(nextScript.src) === “string”) { this._currentTask = new Sys._ScriptLoaderTask(scriptElement, this._scriptLoadedDelegate); this._currentTask.execute(); } else { document.getElementsByTagName(‘HEAD’)[0].appendChild(scriptElement); Sys._ScriptLoader._clearScript(scriptElement); this._loadScriptsInternal(); } }
_createScriptElement Listing 24-18 presents the internal implementation of the _createScriptElement method of the _ScriptLoader class. This method takes a single object that describes the standard and custom HTML attributes of the HTML script element being created. As you can see, this method first calls the createElement method on the document object to create the script HTML element: var scriptElement = document.createElement(‘SCRIPT’);
Next, it sets the type attribute of the script HTML element to a default value. Note that the object may contain a name/value pair for the type HTML attribute, which means that this default value may be overridden: scriptElement.type = ‘text/javascript’;
Finally, it iterates through the name/value pairs of the object, uses the name part of each as an index into the object to return the value part of the pair, and finally uses the name part of each as an index into the newly instantiated script element to store the value part of the pair. for (var attr in queuedScript) { scriptElement[attr] = queuedScript[attr]; }
Listing 24-18: The _createScriptElement Method of the _ScriptLoader Class function Sys$_ScriptLoader$_createScriptElement(queuedScript) { var scriptElement = document.createElement(‘SCRIPT’); scriptElement.type = ‘text/javascript’; for (var attr in queuedScript) { scriptElement[attr] = queuedScript[attr]; } return scriptElement; }
1217
c24.indd 1217
8/20/07 8:47:56 PM
Chapter 24: Asynchronous Partial Page Rendering
The Constructor of the _ScriptLoader Class As Listing 24-19 shows, the constructor of the _ScriptLoader class sets the _scriptsToLoad collection to null, creates a delegate the represents the _scriptLoadedHandler method of the current _ScriptLoader instance, and stores this delegate in a field named _scriptLoadedDelegate.
Listing 24-19: The Constructor of the _ScriptLoader Class Sys._ScriptLoader = function Sys$_ScriptLoader() { this._scriptsToLoad = null; this._scriptLoadedDelegate = Function.createDelegate(this, this._scriptLoadedHandler); }
_scriptLoaderHandler Listing 24-20 presents the internal implementation of the _scriptLoadedHandler method of the _ScriptLoader class. As discussed earlier, the current ScriptLoaderTask instance calls this method when it is finished loading the specified script in the _scriptsToLoad collection. As you can see, this method calls the _getLoadedScripts static method on the _ScriptLoader class to return a reference to the _referencedScripts static collection of the class. (Recall that this collection stores the URLs of all the loaded script files.) The _scriptLoadedHandler method adds the URL of the newly loaded script file into this collection: Array.add(Sys._ScriptLoader._getLoadedScripts(), scriptElement.src);
Next, it calls the dispose method on the current ScriptLoaderTask instance to allow the instance to release the resources it is holding before the instance is disposed of: this._currentTask.dispose();
Next, the _scriptLoadedHandler method calls the _loadScriptsInternal method to load the script described by the next object in the _scriptsToLoad collection. As you can see, the scripts described by the objects in the _scriptsToLoad collection are loaded one at a time; in other words, the loading of the next script does not start until the previous script is completely loaded.
Listing 24-20: The _scriptLoadedHandler Method of the _ScriptLoader Class function Sys$_ScriptLoader$_scriptLoadedHandler(scriptElement, loaded) { if(loaded && this._currentTask._notified) { if(this._currentTask._notified > 1) this._raiseError(true);
_ScriptLoaderTask In this section I’ll discuss the methods of the ASP.NET AJAX _ScriptLoaderTask class.
The Constructor of the_ScriptLoaderTask Class As Listing 24-21 shows, this constructor takes two parameters. The first references a script HTML element, and the second references the JavaScript function that will be automatically called when the specified script is downloaded for the server. Recall from Listing 24-17 that the _loadScriptsInternal method of the current _ScriptLoader instance passes the _scriptLoadedDelegate field of the current _ScriptLoader instance as the second parameter into the constructor of the _ScriptLoaderTask: this._currentTask = new Sys._ScriptLoaderTask(scriptElement, this._scriptLoadedDelegate);
Recall from Listing 24-19 that the _scriptLoadedDelegate field references the delegate that represents the _scriptLoadedHandler method of the current _ScriptLoader instance: this._scriptLoadedDelegate = Function.createDelegate(this, this._scriptLoadedHandler);
Listing 24-21: The Constructor Method of the _ScriptLoaderTask Class Sys._ScriptLoaderTask = function Sys$_ScriptLoaderTask(scriptElement, completedCallback) { this._scriptElement = scriptElement; this._completedCallback = completedCallback; this._notified = 0; }
1219
c24.indd 1219
8/20/07 8:47:57 PM
Chapter 24: Asynchronous Partial Page Rendering
execute Listing 24-22 presents the internal implementation of the execute method of the current _ScriptLoaderTask instance. As you can see, this method first creates a delegate the represents the _scriptLoadHandler method of the current _ScriptLoaderTask instance, and stores this delegate in a local variable named scriptLoadDelegate: var scriptLoadDelegate = Function.createDelegate(this, this._scriptLoadHandler);
Next, if the current browser is Internet Explorer, it invokes the $addHandler global JavaScript function to register the delegate as an event handler for the script HTML element that the _scriptElement references: $addHandler(this._scriptElement, ‘load’, scriptLoadDelegate);
Internet Explorer will automatically call this delegate, and consequently the _scriptLoadHandler method that the delegate represents, when the script associated with the specified script HTML element is downloaded from the server. If the current browser is not Internet Explorer, the execute method invokes the $addHandler global JavaScript function to register the delegate as an event handler for the readystatechange event of the script HTML element referenced by the _scriptElement field: $addHandler(this._scriptElement, ‘readystatechange’, scriptLoadDelegate);
The browser will automatically call this delegate, and consequently the _scriptLoadHandler method that the delegate represents, when the script associated with the specified script HTML element is downloaded from the server. Next, the execute method calls the getElementByTagName method on the current document object to return a reference to the head HTML element: var headElement = document.getElementsByTagName(‘HEAD’)[0];
Finally, it calls the appendChild method on the head HTML element to append the script HTML element referenced by the _scriptElement field as the child element of the head HTML element. As soon as this script HTML element is added to the DOM hierarchy of the current document, the browser automatically downloads the JavaScript file whose URL is specified by the src attribute of the newly added script HTML element, and calls the previously mentioned delegates after the download is completed.
Listing 24-22: The Execute Method of the _ScriptLoaderTask Class function Sys$_ScriptLoaderTask$execute() { var scriptLoadDelegate = Function.createDelegate(this, this._scriptLoadHandler); if (Sys.Browser.agent !== Sys.Browser.InternetExplorer) { this._scriptElement.readyState = ‘loaded’; $addHandler(this._scriptElement, ‘load’, scriptLoadDelegate); }
_scriptLoadHandler As you saw from Listing 24-22, the execute method of the current _ScriptLoader instance registers a delegate that represents the _scriptLoadHandler method of the current _ScriptLoaderTask instance as an event handler for the load or readystatechange event of the script HTML element referenced by the _scriptElement field of the current _ScriptLoaderTask instance. Listing 24-23 presents the internal implementation of the _scriptLoadhandler method. As you can see, this method simply calls the JavaScript function referenced by the _completedCallback field of the current _ScriptLoaderTask instance.
Listing 24-23: The _scriptLoadHandler Method of the _ScriptLoaderTask Class function Sys$_ScriptLoaderTask$_scriptLoadHandler() { if(this._disposed) return; var scriptElement = this.get_scriptElement(); if ((scriptElement.readyState !== ‘loaded’) && (scriptElement.readyState !== ‘complete’)) return; window.setTimeout( function() {this._completedCallback(this._scriptElement, true);}, 0); }
_scriptsLoadComplete Recall from Listing 24-23 that the current _ScriptLoaderTask instance invokes the _completedCallback delegate after loading all the scripts. Also recall that this delegate represents the _scriptsLoadComplete method of the current PageRequestMananger instance. Listing 24-24 presents the internal implementation of the _scriptsLoadComplete method. This method first calls the scrollTo method on the window object to set the scroll position: window.scrollTo(this._scrollPosition.x, this._scrollPosition.y);
Next, this method invokes the _pageLoaded method on the current PageRequestManager instance to raise the pageLoaded event: this._pageLoaded(false);
1221
c24.indd 1221
8/20/07 8:47:57 PM
Chapter 24: Asynchronous Partial Page Rendering Then it calls the _endPostBack method to end the current postback: this._endPostBack(null, this._response);
Finally, the _scriptsLoadComplete method calls the WebForm_AutoFocus global JavaScript function to set the focus to the specified element: WebForm_AutoFocus(this._controlIDToFocus);
Listing 24-24: The _scriptsLoadComplete Method of the Current PageRequestMananger function Sys$WebForms$PageRequestManager$_scriptsLoadComplete() { if (window.__theFormPostData) window.__theFormPostData = “”; if (window.__theFormPostCollection) window.__theFormPostCollection = []; if (window.WebForm_InitCallback) window.WebForm_InitCallback(); if (this._scrollPosition) { if (window.scrollTo) window.scrollTo(this._scrollPosition.x, this._scrollPosition.y); this._scrollPosition = null; } Sys.Application.endCreateComponents(); this._pageLoaded(false); this._endPostBack(null, this._response); this._response = null; if (this._controlIDToFocus) { var focusTarget; var oldContentEditableSetting; if (Sys.Browser.agent === Sys.Browser.InternetExplorer) { var targetControl = $get(this._controlIDToFocus); var focusTarget = targetControl; if (targetControl && (!WebForm_CanFocus(targetControl))) focusTarget = WebForm_FindFirstFocusableChild(targetControl); if (focusTarget && (typeof(focusTarget.contentEditable) !== “undefined”)) { oldContentEditableSetting = focusTarget.contentEditable; focusTarget.contentEditable = false; }
_pageLoaded As Listing 24-24 shows, the _scriptsLoadComplete method of the current PageRequestManager instance invokes the _pageLoaded method on the current PageRequestManager instance. Listing 24-25 presents the internal implementation of the _pageLoaded method. As you can see, this method first calls the _get_eventHandlerList method on the current PageRequestManager instance to return a reference to the EventHandlerList object that contains all the event handlers registered for the events of the current PageRequestManager instance. Then it calls the getHandler method on the EventHandlerList to return a reference to a JavaScript function whose invocation automatically invokes all the event handlers registered for the pageLoaded event of the current PageRequestManager instance: var handler = this._get_eventHandlerList().getHandler(“pageLoaded”);
Next, the _scriptsLoadComplete method calls the _getPageLoadedEventArgs method to create and to return the PageLoadedEventArgs object that contains the event data for the current pageLoaded event: var args = this._getPageLoadedEventArgs(initialLoad);
Next, it calls the previously mentioned JavaScript function, passing the reference to the current PageRequestManager instance and the preceding PageLoadedEventArgs object. This JavaScript function in turn calls all the event handlers registered for the pageLoaded event of the current PageRequestManager instance, passing the reference to the current PageRequestManager instance and the preceding PageLoadedEventArgs object: handler(this, args);
Note that the _pageLoaded method takes a Boolean parameter named initialLoad. As the name suggests, this parameter specifies whether the _pageLoaded method is being called during the initialization phase of the current PageRequestManager instance. In other words, the _pageLoaded method is invoked in two different life cycle phases of the current PageRequestManager instance:
❑
During the instantiation/initialization phase (see Figure 22-5). Recall from Listing 22-6 that the current PageRequestManager instance invokes the _pageLoaded method, passing in true as its argument during its initialization phase when the current PageRequestManager instance is being loaded for the first time.
1223
c24.indd 1223
8/20/07 8:47:58 PM
Chapter 24: Asynchronous Partial Page Rendering ❑
When the server response for an asynchronous page postback is processed and consequently the page is reloaded. Recall from Listing 24-24 that the _scriptsLoadComplete method invokes the _pageLoaded method, passing in false as its argument.
As Listing 24-25 shows, if the _pageLoaded method is invoked with false as its argument, the method invokes the raiseLoad method on the Application object that represents the current ASP.NET AJAX application. The raiseLoad method was thoroughly discussed in Chapter 7 (see Listing 7-28).
Listing 24-25: The _pageLoaded Method of the Current PageRequestManager Instance function Sys$WebForms$PageRequestManager$_pageLoaded(initialLoad) { var handler = this._get_eventHandlerList().getHandler(“pageLoaded”); if (handler) { var args = this._getPageLoadedEventArgs(initialLoad); handler(this, args); } if (!initialLoad) Sys.Application.raiseLoad(); }
_endPostBack Listing 24-26 presents a portion of Listing 24-5. Recall that Listing 24-5 presents the internal implementation of the _onFormSubmitCompleted method of the current PageRequestManager instance. As the highlighted portions of Listing 24-26 show, the current PageRequestManager instance may invoke its _endPostBack method for a number of reasons:
❑
The current request has timed out: if (sender.get_timedOut()) { this._endPostBack(this._createPageRequestManagerTimeoutError(), sender); return; }
❑
The current request has aborted: if (sender.get_aborted()) { this._endPostBack(null, sender); return; }
❑
The status code of the server response is a number other than 200:
The server response text is not in the expected format and has some problems: if (parserErrorDetails) { this._endPostBack(this._createPageRequestManagerParserError( String.format(Sys.WebForms.Res.PRM_ParserErrorDetails, parserErrorDetails)), sender); return; }
❑
The type part of a substring in the server response text is the string “error”. Recall that the server response text consists of a bunch of substrings in the format length|type|id|content, where the type part of the substring specifies the type of information that the content part contains. The server-side PageRequestManager instance sets the type part of a substring to the string “error” to signal the current client-side PageRequestManager instance that the id part of the substring contains the error code and the content part contains an error message: case “error”: this._endPostBack(this._createPageRequestManagerServerError( Number.parseInvariant(deltaNode.id), deltaNode.content), sender); return;
❑
The type part of a substring in the server response text is a string that the current client-side PageRequestManager instance does not recognize: default: this._endPostBack(this._createPageRequestManagerParserError( String.format(Sys.WebForms.Res.PRM_UnknownToken, deltaNode.type)), sender); return;
❑
The _panelsToRefreshIDs collection that the current client-side PageRequestManager instance has received from the server-side PageRequestManager instance contains the UniqueID property value of an UpdatePanel server control that does not exist on the current page. Recall that the _panelsToRefreshIDs collection contains the list of the UniqueID property values of all UpdatePanel server controls that need refreshing. for (i = 0; i < this._panelsToRefreshIDs.length; i++) { var panelClientID = this._uniqueIDToClientID(this._panelsToRefreshIDs[i]); if (!document.getElementById(panelClientID)) { this._endPostBack(Error.invalidOperation( String.format(Sys.WebForms.Res.PRM_MissingPanel, panelClientID)), sender); return; } }
1225
c24.indd 1225
8/20/07 8:47:58 PM
Chapter 24: Asynchronous Partial Page Rendering Recall that the server response text contains one or more substrings with the type value of updatePanel, to signal the current client-side PageRequestManager instance that the id part of the specified substring contains the ClientID property value of an UpdatePanel server control, and that the content part of the substring contains the HTML markup text that makes up the content of the UpdatePanel server control. Also recall that the _onFormSubmitCallback method parses these substrings into a local array named updatePanelNodes, which contains one object for each substring: the value of the id property of the object is a string that contains the id part of the associated substring, and the value of the content part of the object is a string that contains the content part of the associated substring. The id part of a substring (or the value of the id property of the associated object in the updatePanelNodes collection) contains the ClientID property value of an UpdatePanel server control that does not exist on the current page: for (i = 0; i < updatePanelNodes.length; i++) { var deltaUpdatePanel = updatePanelNodes[i]; var deltaPanelID = deltaUpdatePanel.id; var deltaPanelRendering = deltaUpdatePanel.content; var updatePanelElement = document.getElementById(deltaPanelID); if (!updatePanelElement) { this._endPostBack(Error.invalidOperation( String.format(Sys.WebForms.Res.PRM_MissingPanel, deltaPanelID)), sender); return; } this._updatePanel(updatePanelElement, deltaPanelRendering); }
As the last highlighted portion of Listing 24-26 shows, the _onFormSubmitCompleted method registers the _scriptsLoadComplete method with the current _ScriptLoader instance. As discussed earlier, this instance invokes this method when it is done with downloading all scripts: scriptLoader.loadScripts(0, Function.createDelegate(this, this._scriptsLoadComplete), null, null);
❑
Recall from Listing 24-24 that the _scriptsLoadComplete method calls the _endPostBack method after calling the _pageLoaded method, as shown again in the following code fragment: this._pageLoaded(false); this._endPostBack(null, this._response); this._response = null;
1226
c24.indd 1226
8/20/07 8:47:59 PM
Chapter 24: Asynchronous Partial Page Rendering Listing 24-26: The _onFormSubmitCompleted Method of the PageRequestManager Instance function Sys$WebForms$PageRequestManager$_onFormSubmitCompleted(sender, eventArgs) { this._processingRequest = true; var delimitByLengthDelimiter = ‘|’; if (sender.get_timedOut()) { this._endPostBack(this._createPageRequestManagerTimeoutError(), sender); return; } if (sender.get_aborted()) { this._endPostBack(null, sender); return; } if (!this._request || sender.get_webRequest() !== this._request) return; var errorMessage; var delta = []; if (sender.get_statusCode() !== 200) { this._endPostBack( this._createPageRequestManagerServerError(sender.get_statusCode()), sender); return; } var reply = sender.get_responseData(); . . . if (parserErrorDetails) { this._endPostBack(this._createPageRequestManagerParserError( String.format(Sys.WebForms.Res.PRM_ParserErrorDetails, parserErrorDetails)), sender); return; } . . . for (var i = 0; i < delta.length; i++) { var deltaNode = delta[i]; switch (deltaNode.type) { case “updatePanel”: Array.add(updatePanelNodes, deltaNode); break; case “hiddenField”: Array.add(hiddenFieldNodes, deltaNode); break; . . .
(continued)
1227
c24.indd 1227
8/20/07 8:47:59 PM
Chapter 24: Asynchronous Partial Page Rendering Listing 24-26 (continued) case “error”: this._endPostBack(this._createPageRequestManagerServerError( Number.parseInvariant(deltaNode.id), deltaNode.content), sender); return; case “pageTitle”: document.title = deltaNode.content; break; case “focus”: this._controlIDToFocus = deltaNode.content; break; default: this._endPostBack(this._createPageRequestManagerParserError( String.format(Sys.WebForms.Res.PRM_UnknownToken, deltaNode.type)), sender); return; } } var i; if (asyncPostBackControlIDsNode && postBackControlIDsNode && updatePanelIDsNode && panelsToRefreshNode && asyncPostBackTimeoutNode && childUpdatePanelIDsNode) { . . . for (i = 0; i < this._panelsToRefreshIDs.length; i++) { var panelClientID = this._uniqueIDToClientID(this._panelsToRefreshIDs[i]); if (!document.getElementById(panelClientID)) { this._endPostBack(Error.invalidOperation( String.format(Sys.WebForms.Res.PRM_MissingPanel, panelClientID)), sender); return; } } var asyncPostBackTimeout = asyncPostBackTimeoutNode.content; this._updateControls(updatePanelIDsArray, asyncPostBackControlIDsArray, postBackControlIDsArray, asyncPostBackTimeout); } . . . for (i = 0; i < updatePanelNodes.length; i++) { var deltaUpdatePanel = updatePanelNodes[i]; var deltaPanelID = deltaUpdatePanel.id; var deltaPanelRendering = deltaUpdatePanel.content; var updatePanelElement = document.getElementById(deltaPanelID);
As you can see from these discussions, the _endPostBack method of the current PageRequestManager instance can be invoked for a number of reasons. Listing 24-27 presents the internal implementation of this method. It first sets an internal flag named _processingRequest to false to signal that it is done with processing the request: this._processingRequest = false;
Then it sets the _request field of the current PageRequestManager instance to null so the same WebRequest object is not used to make the next asynchronous page postback requests to the server: this._request = null;
Next, it calls the get_eventHandlerList method on the current PageRequestManager instance to return a reference to the EventHandlerList object that contains the list of event handlers registered for the events of the current PageRequestManager instance. Then it invokes the getHandler method on this EventHandlerList object to return a reference to the JavaScript function whose invocation automatically invokes all the event handlers registered for the endRequest event of the current PageRequestManager instance: var handler = this._get_eventHandlerList().getHandler(“endRequest”);
Then the _endPostBack method instantiates an EndRequestEventArgs object, passing in three parameters: the first references the error object, the second the _dataItems collection of the current PageRequestManager instance (recall that the current PageRequestManager instance maintains all data items in this collection), and the last the WebRequestExecutor object responsible for executing the current request. As you’ll see later, the EndRequestEventArgs is the event data class associated with the endRequest event. var eventArgs = new Sys.WebForms.EndRequestEventArgs(error, this._dataItems, response);
Finally, the _endPostBack method invokes the previously mentioned JavaScript function and consequently all the event handlers registered for the endRequest event of the current PageRequestManager instance. Note that the _endPostBack method passes two parameters into
1229
c24.indd 1229
8/20/07 8:47:59 PM
Chapter 24: Asynchronous Partial Page Rendering each event handler: the first references the current PageRequestManager instance and the second references the preceding EndRequestEventArgs object: handler(this, eventArgs);
If you register an event handler for the endRequest event of the current PageRequestManager instance, your event handler will receive these two parameters. Your handler can then use them to retrieve all the required information about the current response and PageRequestManager instance and use that information to perform any necessary application-specific tasks that must be done when a request ends. Finally, the _endPostBack method calls the get_errorHandled method on the EndRequestEventArgs instance to return a Boolean value that specifies whether any of the event handlers has indeed handled the error (if any): errorHandled = eventArgs.get_errorHandled();
As you’ll see later, the EndRequestEventArgs event data class exposes a Boolean property named errorHandled. Your event handler can call the set_errorHandled method on the EndRequestEventArgs object to set the value of this property to true to signal the current PageRequestManager instance that the specified error has already been handled. This enables you to use a custom error-handling technique to handle the error, bypassing the standard ASP.NET AJAX error-handling logic. As you’ll see shortly, this standard logic simply displays a popup that contains the error message. If none of the event handlers has processed the error, the _endPostBack method simply calls the alert method to display the error message to the end user: if (error && !errorHandled) alert(error.message);
Listing 24-27: The _endPostBack Method of the Current PageRequestManager Instance function Sys$WebForms$PageRequestManager$_endPostBack(error, response) { this._processingRequest = false; this._request = null; this._additionalInput = null; var handler = this._get_eventHandlerList().getHandler(“endRequest”); var errorHandled = false; if (handler) { var eventArgs = new Sys.WebForms.EndRequestEventArgs(error, this._dataItems, response); handler(this, eventArgs); errorHandled = eventArgs.get_errorHandled(); } this._dataItems = null; if (error && !errorHandled) alert(error.message); }
1230
c24.indd 1230
8/20/07 8:48:00 PM
Chapter 24: Asynchronous Partial Page Rendering
pageLoading Recall from Figure 24-1 that the current client-side PageRequestManager instance fires its pageLoading event right before it calls the _updatePanel method once for each UpdatePanel control that needs updating. This enables you to run application-specific code that must be run before the UpdatePanel controls on the current page are updated. The client-side PageRequestManager class uses the standard ASP.NET AJAX event-implementation pattern to implement its pageLoading event, as follows:
1.
It defines a method named add_pageLoading that enables you to register event handlers for the pageLoading event of the current client-side PageRequestManager instance. As the following code fragment shows, this method first calls the get_eventHandlerList method on the current PageRequestManager instance, to return a reference to the EventHandlerList object that contains all the event handlers registered for the events of the current PageRequestManager instance. Then it calls the addHandler method on this EventHandlerList object to register the specified handler as an event handler for the pageLoading event of the current PageRequestManager instance:
function Sys$WebForms$PageRequestManager$add_pageLoading(handler) { this._get_eventHandlerList().addHandler(“pageLoading”, handler); }
2.
It defines a method named remove_ pageLoading that enables you to unregister an event handler registered for the pageLoading event of the instance:
function Sys$WebForms$PageRequestManager$remove_pageLoading(handler) { this._get_eventHandlerList().removeHandler(“pageLoading”, handler); }
The pageLoading event, like any other, is associated with an event data class whose instance acts as a container for the associated event data. The event data class associated with the pageLoading event is an ASP.NET AJAX client class named PageLoadingEventArgs. Listing 24-28 presents the internal implementation of the PageLoadingEventArgs class.
Listing 24-28: The Internal Implementation of the PageLoadingEventArgs Class Sys.WebForms.PageLoadingEventArgs = function Sys$WebForms$PageLoadingEventArgs(panelsUpdating, panelsDeleting, dataItems) { Sys.WebForms.PageLoadingEventArgs.initializeBase(this); this._panelsUpdating = panelsUpdating; this._panelsDeleting = panelsDeleting; this._dataItems = dataItems || new Object(); }
(continued)
1231
c24.indd 1231
8/20/07 8:48:00 PM
Chapter 24: Asynchronous Partial Page Rendering Listing 24-28 (continued) function { return } function { return } function { return }
As you can see, the constructor of the PageLoadingEventArgs class takes three parameters. The first is an array that contains the list of UpdatePanel server controls on the current page to be updated. Note the emphasis on to be. As I mentioned earlier, the current PageRequestManager instance first raises the pageLoading event before it invokes the _updatePanel method, once for each updating UpdatePanel control, to update the UpdatePanel controls on the current page. In other words, when the pageLoading event is raised, the UpdatePanel controls that need updating haven’t been updated yet. The second parameter is an array that contains the list of the UpdatePanel server controls on the current page to be deleted. Again, notice the emphasis on to be. In other words, when the pageLoading event is raised, the UpdatePanel controls that must be deleted haven’t been deleted yet. The last parameter, which is optional, returns an object that contains one name/value pair for each data item. Recall that the current client-side PageRequestManager instance stores all data items in an internal collection named _dataItems. This optional parameter basically returns a reference to this collection. As you can see from Listing 24-28, the constructor of the PageLoadingEventArgs class stores its parameters in private fields named _panelsUpdating, _panelsDeleting, and _dataItems. Note that the PageLoadingEventArgs class exposes three getters named get_panelsUpdating, get_panelsDeleting, and get_dataItems, which return these private fields. Next, I’ll examine what is and is not in effect or available when the current PageRequestManager instance raises its pageLoading event:
1232
c24.indd 1232
8/20/07 8:48:00 PM
Chapter 24: Asynchronous Partial Page Rendering ❑
As you can see from the following portion of Listing 24-5, the title of the current document has already taken effect. Note that even though the _controlIDToFocus field of the current PageRequestManager instance has already been set to the ClientID property value of the server control to receive the focus, the focus has not yet been given to this server control. Therefore the older server control, whatever it is, is still holding the focus at this point. for (var i = 0; i < delta.length; i++) { var deltaNode = delta[i]; switch (deltaNode.type) { . . . case “pageTitle”: document.title = deltaNode.content; break; case “focus”: this._controlIDToFocus = deltaNode.content; break; . . . } }
❑
As you can see from the following portion of Listing 24-5, the current PageRequestManager instance has already made sure that the current page contains all the UpdatePanel server controls to be refreshed. In other words, your code can safely program against these UpdatePanel server controls: for (i = 0; i < this._panelsToRefreshIDs.length; i++) { var panelClientID = this._uniqueIDToClientID(this._panelsToRefreshIDs[i]); if (!document.getElementById(panelClientID)) { this._endPostBack(Error.invalidOperation( String.format(Sys.WebForms.Res.PRM_MissingPanel, panelClientID)), sender); return; } }
❑
As you can see from the following portion of Listing 24-5, the current PageRequestManager instance has already invoked the _updateControls method: this._updateControls(updatePanelIDsArray, asyncPostBackControlIDsArray, postBackControlIDsArray, asyncPostBackTimeout);
❑
Listing 24-29 presents the internal implementation of _updateControls. As discussed in Chapter 22, this method populates the following collections of the current PageRequestManager instance:
❑
_updatePanelIDs: This collection contains the UniqueID property values of all UpdatePanel server controls on the current page after processing of the current
asynchronous page postback request on the server side and before processing of the server response to this request. This means that when the current PageRequestManager instance
1233
c24.indd 1233
8/20/07 8:48:01 PM
Chapter 24: Asynchronous Partial Page Rendering fires its pageLoading event, the current document has not yet been updated with the contents of the _updatePanelsIDs collection. Therefore, if your event handler for the pageLoading event attempts to access the UpdatePanel controls in the current document, it will receive references to the old UpdatePanel controls, which may or may not be there after the current PageRequestManager instance updates the current document with the contents of the _updatePanelIDs. In other words, the current document may contain UpdatePanel controls whose UniqueID property values are not included in the _updatePanelIDs collection, which means that these UpdatePanel controls have been deleted during processing of the current asynchronous page postback on the server side. Or the _updatePanelIDs collection may contain UniqueID property values associated with UpdatePanel server controls that do not exist in the current document, which means that these UpdatePanel server controls have been added during processing of the current asynchronous page postback on the server side.
❑
_updatePanelClientIDs: This collection is the same as the _updatePanelIDs collection, with one difference: it contains the ClientID property values of all the UpdatePanel server controls on the current page instead of their UniqueID property values. Therefore, all the same discussions apply equally to the _updatePanelClientIDs collection.
❑
_updatePanelHasChildrenAsTriggers: This collection contains one Boolean value for each UpdatePanel server control in the _updatePanelIDs collection, which specifies whether the ChildrenAsTriggers property of the UpdatePanel server control is set to true. Again, keep in mind that when the current PageRequestManager instance fires its pageLoading event, the UpdatePanel controls on the current document have not yet been updated with the contents of the _updatePanelHasChildrenAsTriggers collection.
❑
_asyncPostBackControlIDs: This collection is the same as the _syncPostBackControlIDs collection, with one main difference: this one contains the UniqueID property values of all the asynchronous page postback controls
on the current page after processing of the current asynchronous page postback request on the server side but before processing of the server response to this request on the client side. Therefore, all the same discussions presented earlier about the _syncPostBackControlIDs equally apply to the _asyncPostBackControlIDs collection.
❑
_asyncPostBackControlClientIDs: This collection is much like the _asyncPostBackControlIDs collection. The only difference is that this one contains the ClientID property values of all the asynchronous postback server controls on the current page instead of their UniqueID property values.
❑
_postBackControlIDs: This collection is much like syncPostBackControlIDs. The main difference is that this one contains the UniqueID property values of all the synchro-
nous page postback controls on the current page after processing of the current asynchronous page postback request on the server side but before processing of the server response to this request on the client side.
❑
_postBackControlClientIDs: This collection is the same as _postBackControlIDs collection, with one difference: it contains the ClientID property values of all the synchronous postback server controls on the current page instead of their UniqueID
property values.
1234
c24.indd 1234
8/20/07 8:48:01 PM
Chapter 24: Asynchronous Partial Page Rendering ❑
As you can see from the following portion of Listing 24-5, the current PageRequestManager instance has populated the _dataItems collection. Recall that this collection contains all data items after processing of the current asynchronous page postback request on the server side and before processing of the server response to this request on the client side. This means that when the current PageRequestManager instance fires its pageLoading event, the current document has not yet been updated with the contents of the _dataItems collection. Therefore, if your event handler for the pageLoading event attempts to access the data items associated with the existing controls in the current document, it will receive references to the old data items. this._dataItems = {}; for (i = 0; i < dataItemNodes.length; i++) { var dataItemNode = dataItemNodes[i]; this._dataItems[dataItemNode.id] = dataItemNode.content; } for (i = 0; i < dataItemJsonNodes.length; i++) { var dataItemJsonNode = dataItemJsonNodes[i]; this._dataItems[dataItemJsonNode.id] = eval(dataItemJsonNode.content); }
❑
As you can see from Listing 24-5, when the current PageRequestManager instance raises the pageLoading event:
❑
The action property of the form element of the current document has not yet been updated. This means two things: first, if the value of this property has been changed during processing of the current asynchronous page postback, your event handler for the pageLoading event will receive the old value of this property if it attempts to access the value of this property from the current document. Second, if some part of the logic of your application depends on the value of this property, and if you need to run some application-specific code before the value of this property changes, your event handler for the pageLoading event must contain this application-specific code.
❑
The _updatePanel method has not yet been invoked. This means that the content of none of the UpdatePanel server controls on the current page whose UniqueID property values are contained in the _updatePanelsToRefresh collection has yet been updated.
❑
The content of an UpdatePanel server control is what goes between the opening and closing tags of the child element of the tag on an .aspx page. Therefore, this content contains a bunch of HTML elements and scripts. If your event handler attempts to access any of these content HTML elements and scripts, it will get the current HTML elements and scripts, which may or may not be there after the current PageRequestManager instance is done with processing the server response.
❑
None of the scripts contained in the server response to the current asynchronous page postback request has yet been processed, and consequently they cannot be accessed from your event handler for the pageLoading event. For example, if the server response contains script blocks that reference new JavaScript files, these files have not been downloaded from the server yet. Or if the server response contains new JavaScript array declarations or form submit statements, they have not yet been added to the current
1235
c24.indd 1235
8/20/07 8:48:01 PM
Chapter 24: Asynchronous Partial Page Rendering document. Therefore, your event handler for the pageLoading event mustn’t attempt to use these scripts.
❑
If the current server response contains new hidden fields, these fields have not been yet added to the current document. Therefore, your event handler for the pageLoading event will not be able to use the DOM API to access these hidden fields from the current document.
❑
If the current server response contains new expando attributes, they have not yet been added to the current document. Therefore, your event handler for the pageLoading event will not be able to use the DOM API to access these attributes from the current document.
Listing 24-29: The _updateControls Method function Sys$WebForms$PageRequestManager$_updateControls(updatePanelIDs, asyncPostBackControlIDs, postBackControlIDs, asyncPostBackTimeout) { if (updatePanelIDs) { this._updatePanelIDs = new Array(updatePanelIDs.length); this._updatePanelClientIDs = new Array(updatePanelIDs.length); this._updatePanelHasChildrenAsTriggers = new Array(updatePanelIDs.length); for (var i = 0; i < updatePanelIDs.length; i++) { this._updatePanelHasChildrenAsTriggers[i] = (updatePanelIDs[i].charAt(0) === ‘t’); this._updatePanelIDs[i] = updatePanelIDs[i].substr(1); this._updatePanelClientIDs[i] = this._uniqueIDToClientID(updatePanelIDs[i].substr(1)); } this._asyncPostBackTimeout = asyncPostBackTimeout * 1000; } else { this._updatePanelIDs = []; this._updatePanelClientIDs = []; this._updatePanelHasChildrenAsTriggers = []; this._asyncPostBackTimeout = 0; } this._asyncPostBackControlIDs = []; this._asyncPostBackControlClientIDs = []; for (var i = 0; i < asyncPostBackControlIDs.length; i++) { Array.add(this._asyncPostBackControlIDs, asyncPostBackControlIDs[i]); Array.add(this._asyncPostBackControlClientIDs, this._uniqueIDToClientID(asyncPostBackControlIDs[i])); }
1236
c24.indd 1236
8/20/07 8:48:02 PM
Chapter 24: Asynchronous Partial Page Rendering this._postBackControlIDs = []; this._postBackControlClientIDs = []; for (var i = 0; i < postBackControlIDs.length; i++) { Array.add(this._postBackControlIDs, postBackControlIDs [i]); Array.add(this._postBackControlClientIDs, this._uniqueIDToClientID(postBackControlIDs [i])); } }
As I discussed earlier, when the current PageRequestManager instance fires its pageLoading event and invokes your event handler, it passes two parameters to your event handler. The first parameter references the current PageRequestManager instance. The second references a PageLoadingEventArgs object that contains the event data for the current pageLoading event. This event data contains three arrays: data items, panels deleting, and panels updating. What is the significance of these three arrays and what can your event handler do with them? First, let’s see the significance of the panels updating array. As you can see from Listing 24-5, and as discussed earlier, after your event handler finally returns, the current PageRequestManager instance calls the _updatePanel method shown in Listing 24-6 once for each UpdatePanel server control in the _updatePanelsToRefreshIDs to update the contents of these UpdatePanel server controls. As you can see from the highlighted portions of Listing 24-30, which repeats Listing 24-6, updating an UpdatePanel server control does the following:
❑
Runs all the dispose scripts associated with the UpdatePanel server control. If your application logic depends on resources released by these dispose scripts, your event handler for the pageLoading event must take the necessary steps before these resources are released: var disposeScripts = this._scriptDisposes[updatePanelID]; for (var i = 0; i < disposeScripts.length; i++) { eval(disposeScripts[i]); }
❑
Deletes all the dispose scripts associated with the UpdatePanel server control: delete this._scriptDisposes[updatePanelID];
❑
Invokes the _destroyTree method: this._destroyTree(updatePanelElement);
❑
The _destroyTree method recursively takes these steps for each element in the DOM descendant hierarchy of the UpdatePanel server control, as shown in the highlighted portions of Listing 24-31, which repeats Listing 24-8:
❑
Invokes the dispose method on client controls associated with the DOM element. If your application logic depends on these client controls, your event handler for the pageLoading event must take the necessary steps before these controls are disposed of: node.control.dispose();
1237
c24.indd 1237
8/20/07 8:48:02 PM
Chapter 24: Asynchronous Partial Page Rendering ❑
Invokes the dispose method on all behaviors associated with the DOM element. If your application logic depends on these behaviors, your event handler for the pageLoading event must take the necessary steps before these behaviors are disposed of: var behaviors = Sys.UI.Behavior.getBehaviors(node); for (var j = behaviors.length - 1; j >= 0; j--) { behaviors[j].dispose(); }
❑
Invokes the _destroyTree method, passing in the DOM element. This method in turn repeats the same steps — that is, it recursively invokes the dispose method on client controls and behaviors associated with each element in the DOM descendant hierarchy of the element. If your application logic depends on these client controls and behaviors, your event handler for the pageLoading event must take the necessary steps before these controls and behaviors are disposed of: this._destroyTree(node);
❑
Assigns the string that contains the new content to the innerHTML property of the UpdatePanel control. This wipes out all the old content, including the child server controls, and replaces them with the new content. If your application logic depends on any of the DOM elements enclosed within the UpdatePanel server control, your event handler for the pageLoading event must take the necessary steps before these DOM elements are wiped out and replaced.
Listing 24-30: The _updatePanel Method function Sys$WebForms$PageRequestManager$_updatePanel(updatePanelElement, htmlMarkup) { for (var updatePanelID in this._scriptDisposes) { var runDisposeScripts = false; var element = document.getElementById(updatePanelID); while (element) { if (element === updatePanelElement) { runDisposeScripts = true; break; } element = element.parentNode; }
1238
c24.indd 1238
8/20/07 8:48:02 PM
Chapter 24: Asynchronous Partial Page Rendering if (runDisposeScripts) { var disposeScripts = this._scriptDisposes[updatePanelID]; for (var i = 0; i < disposeScripts.length; i++) { eval(disposeScripts[i]); } delete this._scriptDisposes[updatePanelID]; } } this._destroyTree(updatePanelElement); updatePanelElement.innerHTML = rendering; }
Listing 24-31: The _destroyTree Method function Sys$WebForms$PageRequestManager$_destroyTree(element) { if (element.nodeType === 1) { var childNodes = element.childNodes; for (var i = childNodes.length - 1; i >= 0; i--) { var node = childNodes[i]; if (node.nodeType === 1) { if (node.dispose && typeof(node.dispose) === “function”) node.dispose(); else if (node.control && typeof(node.control.dispose) === “function”) node.control.dispose(); var behaviors = Sys.UI.Behavior.getBehaviors(node); for (var j = behaviors.length - 1; j >= 0; j--) { behaviors[j].dispose(); } this._destroyTree(node); } } } }
Keep in mind that we’re discussing the significance of the three event data arrays — data items, panels updating, and panels deleting — associated with the pageLoading event. So far, I’ve discussed the panels updating array. Now, let’s study the significance of the panels deleting array. This array contains the list of all UpdatePanel server controls that are deleted after processing of the current asynchronous page postback request on the server side and before processing of the server response to this request on
1239
c24.indd 1239
8/20/07 8:48:02 PM
Chapter 24: Asynchronous Partial Page Rendering the client side. If your application logic depends on any of these UpdatePanel controls, the DOM elements and scripts that they contain or the client controls and behaviors associated with these DOM elements, your event handler for the pageLoading event must take the necessary steps before these UpdatePanel server controls are deleted from the current document. Next, let’s study the significance of the data items dictionary. This dictionary contains all the new data items after processing of the current asynchronous page postback request on the server side and before processing of the server response to this request on the client side. Each data item in this dictionary is associated with a particular control on the current page. You can access this dictionary from within your event handler to enable the pageLoading event to do whatever application-specific tasks you deem necessary. However, keep in mind that some of these data items could be associated with the server controls that have not yet been added to the current document. Now that we’ve covered the significance of the panels deleting, panels updating, and data items collections of the PageLoadingEventArgs event data class, let revisit the following portion of Listing 24-5. Recall that this portion of the _onFormSubmitCompleted method of the current PageRequestManager instance invokes the _getPageLoadingEventArgs method on the current PageRequestManager instance to instantiate and to return an instance of the PageLoadingEventArgs class, which is then passed into the event handlers registered for the pageLoading event of the current PageRequestManager instance: var handler = this._get_eventHandlerList().getHandler(“pageLoading”); if (handler) handler(this, this._getPageLoadingEventArgs());
Listing 24-32 presents the internal implementation of the _getPageLoadingEventArgs method. Since the main responsibility of the _getPageLoadingEventArgs method is to instantiate an instance of the PageLoadingEventArgs class, and since the constructor of this class requires the list of updating and deleting UpdatePanel server controls, the _getPageLoadedEventArgs method first populates two local collections named updating and deleting with the list of the UpdatePanel server controls to be updated and the list of UpdatePanel server controls to be deleted, respectively. As you can see, the method iterates through the UniqueID property values in the _panelsToRefreshIDs collection of the current PageRequestManager instance and takes the following steps for each enumerated UniqueID property value. First, it invokes the _uniqueIDToClientID method on the current PageRequestManager instance, passing in the enumerated UniqueID property value to return its associated ClientID property value: updatePanelClientID = this._uniqueIDToClientID(refreshIDs[i]);
Next, it invokes the getElementById method on the document object passing the ClientID property value to return a reference to the associated UpdatePanel server control: updatePanel = document.getElementById(updatePanelClientID);
Finally, the _getPageLoadingEventArgs method adds the UpdatePanel server control to the updating local collection: Array.add(updating, updatePanel);
1240
c24.indd 1240
8/20/07 8:48:03 PM
Chapter 24: Asynchronous Partial Page Rendering The next order of business for the _getPageLoadingEventArgs method is to populate the deleting collection with the list of UpdatePanel server controls to be deleted. As discussed in the previous chapter, as far as the current client-side PageRequestManager instance is concerned, when an UpdatePanel server control updates, its child UpdatePanel server controls do not. Instead they are deleted from the current page and replaced with brand-new child UpdatePanel server controls that have the same UniqueID and ClientID property values as the deleted ones. In other words, the current client-side PageRequestManager instance treats all child UpdatePanel server controls of the UpdatePanel server control being updated as brand-new UpdatePanel server controls created during processing of the current asynchronous page postback request. This includes both those child UpdatePanel server controls replacing the deleted ones (that is, those with the same UniqueID and ClientID property values as the deleted ones) and those child UpdatePanel server controls that are not replacing the deleted ones (those with completely different UniqueID and ClientID property values from the deleted ones). Keep in mind that the server-side code may add new child UpdatePanel server controls to an UpdatePanel server control. As Listing 24-32 shows, the _getPageLoadingEventArgs method searches through the oldIDs collection for those UpdatePanel server controls that are being deleted from the current document, and adds them to the deleting collection: for (var i = 0; i < oldIDs.length; i++) { if (Array.indexOf(refreshedIDs, oldIDs[i]) === -1 && (Array.indexOf(newIDs, oldIDs[i]) === -1 || Array.indexOf(childIDs, oldIDs[i]) > -1)) Array.add(deleting, document.getElementById(this._uniqueIDToClientID(oldIDs[i]))); }
Finally, the _getPageLoadingEventArgs method instantiates and returns an instance of the PageLoadingEventArgs event data class passing in three collections: updating, deleting, and _dataItems. return new Sys.WebForms.PageLoadedEventArgs(updated, created, this._dataItems);
Listing 24-32: The _getPageLoadingEventArgs Method of the PageRequestManager function Sys$WebForms$PageRequestManager$_getPageLoadingEventArgs() { var updating = []; var deleting = []; var oldIDs = this._oldUpdatePanelIDs; var newIDs = this._updatePanelIDs; var childIDs = this._childUpdatePanelIDs; var refreshedIDs = this._panelsToRefreshIDs; var updatePanelClientID; var updatePanel;
(continued)
1241
c24.indd 1241
8/20/07 8:48:03 PM
Chapter 24: Asynchronous Partial Page Rendering Listing 24-32 (continued) for (var i = 0; i < refreshedIDs.length; i++) { updatePanelClientID = this._uniqueIDToClientID(refreshIDs[i]); updatePanel = document.getElementById(updatePanelClientID); Array.add(updating, updatePanel); Array.add(updating, document.getElementById(this._uniqueIDToClientID(refreshedIDs[i]))); } for (var i = 0; i < oldIDs.length; i++) { if (Array.indexOf(refreshedIDs, oldIDs[i]) === -1 && (Array.indexOf(newIDs, oldIDs[i]) === -1 || Array.indexOf(childIDs, oldIDs[i]) > -1)) Array.add(deleting, document.getElementById(this._uniqueIDToClientID(oldIDs[i]))); } return new Sys.WebForms.PageLoadingEventArgs(updating, deleting, this._dataItems); }
Using the pageLoading Event As discussed earlier, the current client-side PageRequestManager instance fires its pageLoading event right before loading new content into the current page, to enable you to perform application-specific tasks that must be performed right before the new content is loaded. Follow these steps to ensure that your required application-specific logic is executed right before the loading takes place:
1.
If your required application-specific logic is encapsulated in a method of an ASP.NET AJAX client class, invoke the createDelegate static method on the Function to instantiate a delegate that represents this method. For example, if this logic is contained in a method named myMethod that belongs to an ASP.NET AJAX class named MyClass, you’ll need to create a delegate such as the following:
var myObj = new CustomComponents.MyClass(); . . . var myDelegate = Function.createDelegate(myObj, myObj.myMethod);
2.
If your required application-specific logic in not already encapsulated in a method of an ASP. NET AJAX client class, write a new JavaScript function that encapsulates this logic.
3.
Take the following steps inside the pageLoad method:
❑
Invoke the getInstance static method on the client-side PageRequestManager class to return a reference to the current client-side PageRequestManager instance:
function pageLoad() { var prm = Sys.WebForms.PageRequestManager.getInstance(); . . . }
1242
c24.indd 1242
8/20/07 8:48:03 PM
Chapter 24: Asynchronous Partial Page Rendering ❑
Invoke the add_pageLoading method on the current client-side PageRequestManager instance to register the delegate from Step 1 or the JavaScript function from Step 2 as the event handler for the pageLoading event of the current client-side PageRequestManager instance:
function pageLoad() { var myObj = new CustomComponents.MyClass(); . . . var myDelegate = Function.createDelegate(myObj, myObj.myMethod); var prm = Sys.WebForms.PageRequestManager.getInstance(); prm.add_pageLoading(myDelegate); . . . }
Listing 24-33 contains a page that uses this recipe. If you run this page you should see the results shown in Figure 24-3. As this figure shows, this page consists of a parent UpdatePanel server control that contains a child UpdatePanel server control. If you click the button labeled Parent UpdatePanel Trigger, the page will display the popup shown in Figure 24-4. If you click the button labeled Child UpdatePanel Trigger, the page will display the popup shown in Figure 24-5. As you can see, each popup contains a message that displays some of the information available to an event handler registered for the pageLoading event right before the actual loading takes place. What you do with this information is completely up to you. Your event handler can use it to perform application-specific tasks that must be performed right before the actual loading occurs.
Figure 24-3 Now let’s walk through the code shown in Listing 24-33. As you can see, this page contains a server-side and a client-side script block. The server-side script block contains the implementation of the Page_Load method. As you can see, this method first calls the FindControl method twice on the current Page to return references to the ParentUpdatePanelLabel and ChildUpdatePanelLabel server controls, and then sets the values of their Text properties to the current time: Label parentUpdatePanelLabel = (Label)Page.FindControl(“ParentUpdatePanelLabel”); parentUpdatePanelLabel.Text = “UpdatePanel refreshed at “ + DateTime.Now.ToString(); Label childUpdatePanelLabel = (Label)Page.FindControl(“ChildUpdatePanelLabel”); childUpdatePanelLabel.Text = “UpdatePanel refreshed at “ + DateTime.Now.ToString();
As Listing 24-33 shows, the client-side script block consists of two parts. The first part contains the implementation of the pageLoad method: function pageLoad() { var prm = Sys.WebForms.PageRequestManager.getInstance(); prm.add_pageLoading(pageLoadingHandler); }
As you can see, pageLoad first calls the getInstance static method on the client-side PageRequestManager class to return a reference to the current client-side PageRequestManager instance: var prm = Sys.WebForms.PageRequestManager.getInstance();
1247
c24.indd 1247
8/20/07 8:48:05 PM
Chapter 24: Asynchronous Partial Page Rendering
Figure 24-4 Next, the method invokes the add_pageLoading method on the current PageRequestManager instance to register the pageLoadingHandler JavaScript function as an event handler for the pageLoading event of the current PageRequestManager instance: prm.add_pageLoading(pageLoadingHandler);
Now, let’s walk through the implementation of the pageLoadingHandler JavaScript function. When the current client-side PageRequestManager instance invokes this function, it passes two parameters into it. The first parameter references the current client-side PageRequestManager instance. The second parameter references the PageLoadingEventArgs object that contains the event data for the pageLoading event. As Listing 24-33 shows, the pageLoadingHandler method first calls the get_panelsUpdating method on the PageLoadingEventArgs object to return a reference to the array that contains all the UpdatePanel server controls that need to be updated: var panelsUpdating = e.get_panelsUpdating();
1248
c24.indd 1248
8/20/07 8:48:05 PM
Chapter 24: Asynchronous Partial Page Rendering
Figure 24-5 Next, it calls the get_panelsDeleting method on the PageLoadingEventArgs object to return a reference to the array that contains all the UpdatePanel server controls that need to be deleted: var panelsDeleting = e.get_panelsDeleting();
Next, the pageLoadingHandler method instantiates a StringBuilder: var builder = new Sys.StringBuilder();
Then it populates the StringBuilder with the UniqueID property values of all the UpdatePanel server controls in the panelsUpdating array: builder.append(“panelsUpdating: “); builder.appendLine(); for (var i in panelsUpdating) { builder.append(panelsUpdating[i].id); builder.appendLine(); }
1249
c24.indd 1249
8/20/07 8:48:05 PM
Chapter 24: Asynchronous Partial Page Rendering Next, it populates the StringBuilder with the UniqueID property values of the all the UpdatePanel server controls in the panelsDeleting array: for (var j in panelsDeleting) { builder.append(panelsDeleting[j].id); builder.appendLine(); }
Then the pageLoadingHandler method adds the content of the _updatePanelIDs field of the current client-side PageRequestManager instance to the StringBuilder. Recall that the first parameter (that is, the sender parameter) of the pageLoadingHandler method references the current clientside PageRequestManager instance. Also recall that the _updatePanelIDs field of the current PageRequestManager instance contains the comma-separated list of the UniqueID property values of all the UpdatePanel server controls on the current page after processing of the current request on the server side and before processing of the server response to this request on the client side: builder.appendLine(); builder.append(“_updatePanelIDs: “); builder.append(sender._updatePanelIDs);
Next, it adds the content of the _updatePanelClientIDs field of the current client-side PageRequestManager instance to the StringBuilder. Recall that the _updatePanelClientIDs field contains the comma-separated list of the ClientID property values of all the UpdatePanel server controls on the current page after processing of the current request on the server side and before processing of the server response to this request on the client side: builder.appendLine(); builder.appendLine(); builder.append(“_updatePanelClientIDs: “); builder.append(sender._updatePanelClientIDs);
Then it adds the content of the _updatePanelHasChildrenAsTriggers field of the current client-side PageRequestManager instance to the StringBuilder. Recall that the _updatePanelHasChildrenAsTriggers field contains the comma-separated list of Boolean values, one for each UpdatePanel server control in the _updatePanelIDs. builder.appendLine(); builder.appendLine(); builder.append(“_updatePanelHasChildrenAsTriggers: “); builder.append(sender._updatePanelHasChildrenAsTriggers);
Next, the pageLoadingHandler method adds the value of the _asyncPostBackTimeout field of the current client-side PageRequestManager instance to the StringBuilder. Recall that this field contains the asynchronous page postback request timeout. builder.appendLine(); builder.appendLine(); builder.append(“_asyncPostBackTimeout: “); builder.append(sender._asyncPostBackTimeout);
1250
c24.indd 1250
8/20/07 8:48:06 PM
Chapter 24: Asynchronous Partial Page Rendering Next, it adds the content of the _asyncPostBackControlIDs field of the current client-side PageRequestManager instance to the StringBuilder. Recall that the _asyncPostBackControlIDs field contains the comma-separated list of the UniqueID property values of all the asynchronous postback controls on the current page after processing of the current request on the server side and before processing of the server response to this request on the client side: builder.appendLine(); builder.appendLine(); builder.append(“_asyncPostBackControlIDs: “); builder.append(sender._asyncPostBackControlIDs);
Then it adds the content of the _asyncPostBackControlClientIDs field of the current client-side PageRequestManager instance to the StringBuilder. Recall that the _asyncPostBackControlClientIDs field contains the comma-separated list of the ClientID property values of all the server controls on the current page that cause asynchronous page postback: builder.appendLine(); builder.appendLine(); builder.append(“_asyncPostBackControlClientIDs: “); builder.append(sender._asyncPostBackControlClientIDs);
Next, the pageLoadingHandler method adds the content of the _postBackControlIDs field of the current client-side PageRequestManager instance to the StringBuilder. Recall that the _postBackControlIDs field contains the comma-separated list of the UniqueID property values of all the server controls on the current page that cause synchronous page postback: builder.appendLine(); builder.appendLine(); builder.append(“_postBackControlIDs: “); builder.append(sender._postBackControlIDs);
Then it adds the content of the _postBackControlClientIDs field of the current client-side PageRequestManager instance to the StringBuilder. Recall that the _postBackControlClientIDs field contains the comma-separated list of the ClientID property values of all the server controls on the current page that cause synchronous page postback: builder.appendLine(); builder.appendLine(); builder.append(“_postBackControlClientIDs: “); builder.append(sender._postBackControlClientIDs);
Finally, it displays the content of the StringBuilder in a popup, shown in Figure 24-4 or 24-5. alert(builder.toString());
Next, let’s study the messages shown in Figurers 24-4 and 24-5. As Figure 24-4 shows,
❑
The panelsUpdating array contains ParentUpdatePanel because the user clicked the button labeled Parent UpdatePanel Trigger, which triggers the update of ParentUpdatePanel.
1251
c24.indd 1251
8/20/07 8:48:06 PM
Chapter 24: Asynchronous Partial Page Rendering ❑
The panelsDeleting array contains the ChildUpdatePanel. This is because updating the ParentUpdatePanel wipes out the ChildUpdatePanel and replaces it with a new ChildUpdatePanel that has the same UniqueID and ClientID property values as the deleted one.
❑
The _updatePanelIDs field of the current PageRequestManager instance returns the commaseparated list of the UniqueID properties of all the UpdatePanel server controls on the current page — that is, ParentUpdatePanel and ChildUpdatePanel. Note that the UniqueID property values in this example are the same as the ID property values because none of the UpdatePanel server controls in this example belongs to a parent server control that implements the INamingContainer interface.
❑
The _updatePanelClientIDs field of the current PageRequestManager instance returns the comma-separated list of the ClientID properties of all the UpdatePanel server controls on the current page — that is, ParentUpdatePanel and ChildUpdatePanel. Note that the ClientID property values in this example are the same as the ID property values because none of the UpdatePanel server controls in this example belongs to a parent server control that implements the INamingContainer interface.
❑
The _updatePanelHasChildrenAsTriggers field of the current PageRequestManger instance returns the comma-separated list of Boolean values, one for each UpdatePanel server control. Because this example contains two UpdatePanel server controls and because the ChildrenAsTriggers properties of both UpdatePanel server controls are set to true by default, the _updatePanelHasChildrenAsTriggers field contains a comma-separated list of two true values.
❑
The _asyncPostBackTimeout field of the current PageRequestManager instance returns the default value, which is 90000.
❑
The _asyncPostBackControlIDs field of the current PageRequestManager instance returns the comma-separated list of the UniqueID property values of all asynchronous postback server controls. Our example contains two asynchronous postback Button server controls: ParentUpdatePanelTrigger and ChildUpdatePanelTrigger.
❑
The _asyncPostBackControlClientIDs field of the current PageRequestManager instance returns the comma-separated list of the ClientID property values of all asynchronous postback server controls. Our example contains two asynchronous postback Button server controls: ParentUpdatePanelTrigger and ChildUpdatePanelTrigger. Again, because these two Button server controls do not belong to a server control that implements the INamingContainer interface, their UniqueID, ClientID, and ID properties have the same values.
Keep in mind that the arrays returned from the calls into the get_panelsUpdating and get_panelsDeleting methods contain references to the actual updating and deleting UpdatePanel server controls, respectively. This gives your event handler (registered for the pageLoading event of the current PageRequestManager instance) a powerful tool with which to modify the contents of these UpdatePanel server controls or to enhance their functionality.
1252
c24.indd 1252
8/20/07 8:48:06 PM
Chapter 24: Asynchronous Partial Page Rendering
pageLoaded The current client-side PageRequestManager instance raises the pageLoaded event in two separate occasions:
❑
At the end of its instantiation/initialization phase, as shown in Figure 22-5. Recall that this phase occurs only once during the entire lifetime of the current PageRequestManager instance — when it is loaded for the first time. This scenario was thoroughly discussed in Chapter 22.
❑
At the end of the processing of the server response for an asynchronous page postback request, as shown in Figure 24-2. This could happen as many times as the current PageRequestManager instance makes asynchronous page postback requests to the server, because the current PageRequestManager instance raises the pageLoaded event at the end of the processing of the server response for every single asynchronous page postback request it makes to the server.
The client-side PageRequestManager class uses the standard ASP.NET AJAX event implementation pattern to implement its pageLoaded event, as thoroughly discussed in Chapter 22. Recall that the PageRequestManager exposes a method named _pageLoaded that raises its pageLoaded event, as shown again in the highlighted portion of Listing 24-34.
Listing 24-34: The _pageLoaded Method of the PageRequestManager function Sys$WebForms$PageRequestManager$_pageLoaded(initialLoad) { var handler = this._get_eventHandlerList().getHandler(“pageLoaded”); if (handler) handler(this, this._getPageLoadedEventArgs(initialLoad)); if (!initialLoad) Sys.Application.raiseLoad(); }
As you can see in the highlighted portion of this code listing, this method invokes the _getPageLoadedEventArgs(initialLoad) internal method on the current PageRequestManager instance to instantiate and to return an instance of the PageLoadedEventArgs event data class, which is then passed into the event handlers registered for the pageLoaded event of the current PageRequestManager instance. Listing 24-35 presents the internal implementation of the _getPageLoadedEventArgs method. Since the main responsibility of the _getPageLoadedEventArgs method is to instantiate an instance of the PageLoadedEventArgs class, and since the constructor of this class requires the list of updated and created UpdatePanel server controls, the _getPageLoadedEventArgs method first populates two local collections named updated and created with the list of the updated UpdatePanel server controls and the list of newly-created UpdatePanel server controls, respectively. As you can see, the method iterates through the UniqueID property values in the _panelsToRefreshIDs collection of the current PageRequestManager instance and takes the following steps for each enumerated UniqueID property value. First, it invokes the _uniqueIDToClientID method on the current
1253
c24.indd 1253
8/20/07 8:48:07 PM
Chapter 24: Asynchronous Partial Page Rendering PageRequestManager instance, passing in the enumerated UniqueID property value to return its associated ClientID property value: updatePanelClientID = this._uniqueIDToClientID(refreshIDs[i]);
Next, the _getPageLoadedEventArgs method invokes the getElementById method on the document object, passing the ClientID property value to return a reference to the UpdatePanel server control with the specified ClientID property value: updatePanel = document.getElementById(updatePanelClientID);
Finally, it adds the UpdatePanel server control to the updated local collection: Array.add(updated, updatePanel);
The next order of business for the _getPageLoadedEventArgs method is to populate the created collection with the list of all UpdatePanel server controls that the server-side PageRequestManager instance has created during processing of the current asynchronous page postback request. As Listing 24-35 shows, the _getPageLoadedEventArgs method searches through the newIDs collection for those UpdatePanel server controls that are child UpdatePanel server controls of other UpdatePanel server controls. Since the current client-side PageRequestManager instance treats every child UpdatePanel server control as a newly-created UpdatePanel server control during processing of the current asynchronous page postback request, all child UpdatePanel server controls are added to the created collection. This includes both those child UpdatePanel server controls that have the same UniqueID property values as the ones they’re replacing, and those child UpdatePanel server controls that do not correspond to any of the old child UpdatePanel server controls. for (var i = 0; i < newIDs.length; i++) { if (initialLoad || Array.indexOf(childIDs, newIDs[i]) !== -1) { updatePanelClientID = this._uniqueIDToClientID(newIDs[i]); updatePanel = document.getElementById(updatePanelClientID); Array.add(created, updatePanel); } }
Finally, the _getPageLoadedEventArgs method instantiates and returns an instance of the PageLoadedEventArgs event data class passing in three collections: updated, created, and _dataItems. return new Sys.WebForms.PageLoadedEventArgs(updated, created, this._dataItems);
Listing 24-35: The _getPageLoadedEventArgs Method of PageRequestManager function Sys$WebForms$PageRequestManager$_getPageLoadedEventArgs(initialLoad) { var updated = []; var created = []; var oldIDs = this._oldUpdatePanelIDs || []; var newIDs = this._updatePanelIDs;
1254
c24.indd 1254
8/20/07 8:48:07 PM
Chapter 24: Asynchronous Partial Page Rendering var childIDs = this._childUpdatePanelIDs || []; var refreshedIDs = this._panelsToRefreshIDs || []; var updatePanelClientID; var updatePanel; for (var i = 0; i < refreshedIDs.length; i++) { updatePanelClientID = this._uniqueIDToClientID(refreshIDs[i]); updatePanel = document.getElementById(updatePanelClientID); Array.add(updated, updatePanel); } for (var i = 0; i < newIDs.length; i++) { if (initialLoad || Array.indexOf(childIDs, newIDs[i]) !== -1) { updatePanelClientID = this._uniqueIDToClientID(newIDs[i]); updatePanel = document.getElementById(updatePanelClientID); Array.add(created, updatePanel); } } return new Sys.WebForms.PageLoadedEventArgs(updated, created, this._dataItems); }
end Request As thoroughly discussed earlier in this chapter, the current PageRequestManager instance invokes its _endPostBack on numerious occasions. As the highlighted portion of Listing 24-36, which repeats Listing 24-27, shows, the _endPostBack method raises the endRequest event.
Listing 24-36: The _endPostBack Method function Sys$WebForms$PageRequestManager$_endPostBack(error, response) { this._processingRequest = false; this._request = null; this._additionalInput = null; var handler = this._get_eventHandlerList().getHandler(“endRequest”); var errorHandled = false; if (handler) { var eventArgs = new Sys.WebForms.EndRequestEventArgs(error, this._dataItems, response); handler(this, eventArgs); errorHandled = eventArgs.get_errorHandled(); } this._dataItems = null; if (error && !errorHandled) alert(error.message); }
1255
c24.indd 1255
8/20/07 8:48:07 PM
Chapter 24: Asynchronous Partial Page Rendering As you can see from this code listing, the _endPostBack method instantiates an instance of an ASP.NET AJAX class named EndRequestEventArgs and passes this instance to the event handlers registered for the endRequest event of the current PageRequestManager instance. This class is the event data class associated with the endRequest event. Listing 24-37 presents the internal implementation of this class.
Listing 24-37: The EndRequestEventArgs Class Sys.WebForms.EndRequestEventArgs = function Sys$WebForms$EndRequestEventArgs(error, dataItems, response) { Sys.WebForms.EndRequestEventArgs.initializeBase(this); this._errorHandled = false; this._error = error; this._dataItems = dataItems || new Object(); this._response = response; } function Sys$WebForms$EndRequestEventArgs$get_dataItems() { return this._dataItems; } function Sys$WebForms$EndRequestEventArgs$get_error() { return this._error; } function Sys$WebForms$EndRequestEventArgs$get_errorHandled() { return this._errorHandled; } function Sys$WebForms$EndRequestEventArgs$set_errorHandled(value) { this._errorHandled = value; } function Sys$WebForms$EndRequestEventArgs$get_response() { return this._response; } Sys.WebForms.EndRequestEventArgs.prototype = { get_dataItems: Sys$WebForms$EndRequestEventArgs$get_dataItems, get_error: Sys$WebForms$EndRequestEventArgs$get_error, get_errorHandled: Sys$WebForms$EndRequestEventArgs$get_errorHandled, set_errorHandled: Sys$WebForms$EndRequestEventArgs$set_errorHandled, get_response: Sys$WebForms$EndRequestEventArgs$get_response } Sys.WebForms.EndRequestEventArgs.registerClass(‘Sys.WebForms.EndRequestEventArgs’, Sys.EventArgs);
As you can see from this code listing, the constructor of the EndRequestEventArgs class takes three parameters. The first parameter references the error object, if any. The second parameter references the object that contains one name/value pair for each data item. As the highlighted portion of Listing 24-36 shows, this parameter basically returns a reference to the _dataItems collection of the current PageRequestManager instance. The third parameter references the WebRequestExecutor object
1256
c24.indd 1256
8/20/07 8:48:08 PM
Chapter 24: Asynchronous Partial Page Rendering responsible for executing the current asynchronous page postback request. As Listing 24-37 shows, this constructor stores these three parameters in three internal fields named _error, _dataItems, and _response, respectively. Your event handler for the endRequest event can then invoke the get_error, get_dataItems, and get_response methods on the EndRequestEventArgs object passed into it to access these internal fields. As you can see from Listing 24-37, the EndRequestEventArgs event data class also exposes a Boolean property named _errorHandled and two methods named get_errorHandled and set_errorHandled that get and set the values of this property. If your event handler for the endRequest event chooses to use a custom error handler to handle the error (if any), it must call the set_errorHandled method on the EndRequestEventArgs object passed into it to set the value of the _errorHandled property to true to signal the current PageRequestManager instance that it mustn’t use the default error handler to handle the error because the error has already been handled by your custom error handler. As the boldface portions of Listing 24-36 show, when your event handler for the endRequest event finally returns, the _endPostBack method calls the get_errorHandled method on the EndRequestEventArgs object passed into your event handler to access the value of the _errorHandled property to determine whether your event handler has set this property to true. If so, the _endPostBack method bypasses the default error-handling mechanism. As the boldface portion of Listing 24-36 shows, the default error-handling mechanism simply calls the alert function to display the error message in a popup. As you should expect by now, the PageRequestManager instance exposes two methods, add_endRequest and remove_endRequest, that enable you to register and unregister an event handler for the endRequest method of the current PageRequestManager instance, as shown in the following code listing: function Sys$WebForms$PageRequestManager$add_endRequest(handler) { this._get_eventHandlerList().addHandler(“endRequest”, handler); } function Sys$WebForms$PageRequestManager$remove_endRequest(handler) { this._get_eventHandlerList().removeHandler(“endRequest”, handler); }
Using the endRequest Event As the name suggests, the current PageRequestManager instance raises the endRequest event to mark the end of the current asynchronous page postback request. Since the _endPostBack method can be invoked for a number of reasons, the endRequest event can be raised for a number of reasons as well. In other words, your event handler for the endRequest event must not assume that everything went fine and the server response successfully arrived. It must include the necessary logic to determine why the endRequest event was fired. Follow these steps to ensure that your required application-specific logic is executed when the current PageRequestManager instance fires its endRequest event:
1.
If your required application-specific logic is encapsulated in a method of an ASP.NET AJAX client class, invoke the createDelegate static method on the Function to instantiate a delegate that represents this method. For example, if this logic is contained in a method named
1257
c24.indd 1257
8/20/07 8:48:08 PM
Chapter 24: Asynchronous Partial Page Rendering myMethod that belongs to an ASP.NET AJAX class named MyClass, you’ll need to create a
delegate such as the following: var myObj = new CustomComponents.MyClass(); . . . Var myDelegate = Function.createDelegate(myObj, myObj.myMethod);
2.
If your required application-specific logic in not already encapsulated in a method of an ASP.NET AJAX client class, write a new JavaScript function that encapsulates this logic.
3.
Take the following steps inside the pageLoad method:
❑
Invoke the getInstance static method on the client-side PageRequestManager class to return a reference to the current client-side PageRequestManager instance:
function pageLoad() { var prm = Sys.WebForms.PageRequestManager.getInstance(); . . . }
❑
Invoke the add_endRequest method on the current client-side PageRequestManager instance to register the delegate from Step 1 or the JavaScript function from Step 2 as the event handler for the endRequest event of the current client-side PageRequestManager instance:
function pageLoad() { var myObj = new CustomComponents.MyClass(); . . . var myDelegate = Function.createDelegate(myObj, myObj.myMethod); var prm = Sys.WebForms.PageRequestManager.getInstance(); prm.add_endRequest(myDelegate); . . . }
As Listing 24-36 shows, the _endPostBack method uses a default error-handling mechanism to handle an error if your event handler for the endRequest event does not handle it and does not set the _errorHandled property of the EndRequestEventArgs object passed into it to true. As you can see from the bottom boldface portion of Listing 24-36, this default error-handling mechanism simply calls the alert JavaScript function to display the value of the message property of the error object in a popup. If you’re not happy with this default error mechanism, you can write your own custom error-handling routine. Such a routine normally needs to know the type of error being handled. As thoroughly discussed in Chapter 4, every error object exposes a property named name, which specifies the name or type of the exception. Your custom error-handling routine must contain a switch statement with one case statement for each type of error, something like the following:
1258
c24.indd 1258
8/20/07 8:48:08 PM
Chapter 24: Asynchronous Partial Page Rendering function myCustomErrorHandler(error) { switch (error.name) { case “...”: // Handle error here break; case “...”: // Handle error here break; case “...”: // Handle error here break; } }
As you can see from this code fragment, your custom error handler needs to know exactly what type of errors it is supposted to handle. This raises the following question: what types of exceptions could the current PageRequestManager instance throw when it is firing its endRequest event? To find the answer to this question we need to revisit those places where the current PageRequestManager instance invokes its _endPostBack method, because those are the places where the current PageRequestManager instance creates the error object and passes it as the first argument into the _endPostBack method. As we discussed earlier, the _endPostBack method, in turn, passes the error object to your event handler when it invokes your handler. As we also discussed earlier, the current PageRequestManager instance invokes the _endPostBack method on eight different occasions, as follows (the variable sender in all the following code fragments references the current WebRequestExecutor object responsible for executing the current asynchronous page postback request):
1.
When the current request times out, the current PageRequestManager instance invokes its _endPostBack method, passing in a parameter that calls the _createPageRequestManagerTimeoutError method on the current PageRequestManager instance to instantiate and return an exception of type PageRequestManagerTimeoutException. (I’ll discuss this method shortly.) if (sender.get_timedOut()) { this._endPostBack(this._createPageRequestManagerTimeoutError(), sender); return; }
2.
When the current request aborts, the current PageRequestManager instance invokes its _endPostBack method, passing in null as an error. As you can see, the absence of an error does not mean that everything went fine and the server response successfully arrived. if (sender.get_aborted()) { this._endPostBack(null, sender); return; }
When the status code of the server response is a number other than 200, the current PageRequestManager instance invokes its _endPostBack method, passing in a parameter that calls the _createPageRequestManagerServerError method on the current PageRequestManager instance to instantiate and return an exception of type PageRequestManagerServerErrorException. (I’ll discuss this method shortly.) if (sender.get_statusCode() !== 200) { this._endPostBack( this._createPageRequestManagerServerError(sender.get_statusCode()), sender); return; }
4.
Recall that the server response text consists of a bunch of substrings with the format length|type|id|content. When the type part of a substring in the server response text is the string “error”, the current PageRequestManager instance invokes its _endPostBack method, passing in a parameter that calls the _createPageRequestManagerServerError method on the current PageRequestManager instance to instantiate and return an exception of type PageRequestManagerServerErrorException. Note that the current PageRequestManager instance passes the id and content parts of the substring into the _createPageRequestManagerServerError method. Recall that these two parts respectively contain the error code and the error message.
When the type part of a substring in the server response text is a string that the current clientside PageRequestManager instance does not recognize, the current PageRequestManager instance invokes its _endPostBack method, passing in a parameter that calls the _createPageRequestManagerParserError method to instantiate and to return an exception of type PageRequestManagerParserErrorException. Note that the current PageRequestManager instance passes the type part of the substring into the _createPageRequestManagerParserError method.
When the _panelsToRefreshIDs collection that the current client-side PageRequestManager instance has received from the server-side PageRequestManager instance contains the UniqueID property value of an UpdatePanel server control that does not exist on the current page, the current PageRequestManager instance invokes its _endPostBack method, passing in a parameter that calls the invalidOperation static method on the Error to instantiate and return an exception of type InvalidOperationException. Note that the current PageRequestManager instance passes the ClientID property value of the nonexistent UpdatePanel server control as a parameter into the invalidOperation method.
1260
c24.indd 1260
8/20/07 8:48:09 PM
Chapter 24: Asynchronous Partial Page Rendering for (i = 0; i < this._panelsToRefreshIDs.length; i++) { var panelClientID = this._uniqueIDToClientID(this._panelsToRefreshIDs[i]); if (!document.getElementById(panelClientID)) { this._endPostBack(Error.invalidOperation( String.format(Sys.WebForms.Res.PRM_MissingPanel, panelClientID)), sender); return; } }
7.
When the type part of a substring in the server response text is the string “updatePanel” and the id part contains the UniqueID property value of an UpdatePanel server control that does not exist on the current page, the current PageRequestManager instance invokes its _endPostBack method, passing in a parameter that calls the invalidOperation static method on the Error to instantiate and return an exception of type InvalidOperationException. Note that the current PageRequestManager instance passes the ClientID property value of the nonexistent UpdatePanel server control as a parameter into the invalidOperation method. for (i = 0; i < updatePanelNodes.length; i++) { var deltaUpdatePanel = updatePanelNodes[i]; var deltaPanelID = deltaUpdatePanel.id; var deltaPanelRendering = deltaUpdatePanel.content; var updatePanelElement = document.getElementById(deltaPanelID); if (!updatePanelElement) { this._endPostBack(Error.invalidOperation( String.format(Sys.WebForms.Res.PRM_MissingPanel, deltaPanelID)), sender); return; } this._updatePanel(updatePanelElement, deltaPanelRendering); }
8.
When all the scripts are loaded, the current PageRequestManager instance invokes its _endPostBack method, passing in null as its argument. This scenario happens when everything goes fine and the server response is successfully processed. this._pageLoaded(false); this._endPostBack(null, this._response); this._response = null;
As you can see, the current PageRequestManager instance passes one of the following exceptions into the _endPostBack method when it invokes the method and thereafter fires its endRequest event:
❑
PageRequestManagerTimeoutException
❑
PageRequestManagerServerErrorException
❑
PageRequestManagerParserErrorException
❑
InvalidOperationException
1261
c24.indd 1261
8/20/07 8:48:09 PM
Chapter 24: Asynchronous Partial Page Rendering To understand what these exceptions are we need to study the methods that generate them, which we’ll do in the following sections.
PageRequestManagerTimeoutException Listing 24-38 presents the internal implementation of the _createPageRequestManagerTimeoutError method of the PageRequestManager class. As you can see, this method creates an error object with the following two properties:
❑
message: This property specifies the following error message: var displayMessage = “Sys.WebForms.PageRequestManagerTimeoutException: “ + Sys.WebForms.Res.PRM_TimeoutError;
❑
name: This property specifies the name of the exception, Sys.WebForms .PageRequestManagerTimeoutException.
Listing 24-38: The _createPageRequestManagerTimeoutError Method of PageRequestManager function Sys$WebForms$PageRequestManager$_createPageRequestManagerTimeoutError() { var displayMessage = “Sys.WebForms.PageRequestManagerTimeoutException: “ + Sys.WebForms.Res.PRM_TimeoutError; var e = Error.create(displayMessage, {name: ‘Sys.WebForms.PageRequestManagerTimeoutException’}); e.popStackFrame(); return e; }
PageRequestManagerServerErrorException Listing 24-39 presents the internal implementation of the _createPageRequestManagerServerError method of the PageRequestManager class. As you can see, this method creates an error object with the following three properties:
❑
message: This property specifies the following error message:
var displayMessage “Sys.WebForms.PageRequestManagerServerErrorException: “ + String.format(Sys.WebForms.Res.PRM_ServerError, httpStatusCode));
❑
name: This property specifies the name of the exception, Sys.WebForms .PageRequestManagerServerErrorException.
❑
httpStatusCode: This property specifies the HTTP status code of the server response.
1262
c24.indd 1262
8/20/07 8:48:10 PM
Chapter 24: Asynchronous Partial Page Rendering Listing 24-39: The _createPageRequestManagerServerError Method of PageRequestManager function Sys$WebForms$PageRequestManager$_createPageRequestManagerServerError( httpStatusCode, message) { var displayMessage = message || (“Sys.WebForms.PageRequestManagerServerErrorException: “ + String.format(Sys.WebForms.Res.PRM_ServerError, httpStatusCode)); var e = Error.create(displayMessage, {name: ‘Sys.WebForms.PageRequestManagerServerErrorException’, httpStatusCode: httpStatusCode}); e.popStackFrame(); return e; }
PageRequestManagerParserErrorException Listing 24-40 presents the internal implementation of the _createPageRequestManagerParserError method of the PageRequestManager class. As you can see, this method creates an error object with the following two properties:
❑
message: This property specifies the following error message:
var displayMessage = “Sys.WebForms.PageRequestManagerParserErrorException: “ + String.format(Sys.WebForms.Res.PRM_ParserError, parserErrorMessage);
❑
name: This property specifies the name of the exception, Sys.WebForms .PageRequestManagerParserErrorException.
Listing 24-40: The _createPageRequestManagerParserError Method of PageRequestManager function Sys$WebForms$PageRequestManager$_createPageRequestManagerParserError( parserErrorMessage) { var displayMessage = “Sys.WebForms.PageRequestManagerParserErrorException: “ + String.format(Sys.WebForms.Res.PRM_ParserError, parserErrorMessage); var e = Error.create(displayMessage, {name: ‘Sys.WebForms.PageRequestManagerParserErrorException’}); e.popStackFrame(); return e; }
InvalidOperationException Listing 24-41 presents the internal implementation of the invalidOperation static method of the Error class. As you can see, this method creates an error object with the following two properties:
❑
message: This property specifies the following error message: var displayMessage = “Sys.InvalidOperationException: “ + (message ? message : Sys.Res.invalidOperation);
1263
c24.indd 1263
8/20/07 8:48:10 PM
Chapter 24: Asynchronous Partial Page Rendering ❑
name: This property specifies the name of the exception, Sys.InvalidOperationException.
Listing 24-41: The invalidOperation Static Method of Error Error.invalidOperation = function Error$invalidOperation(message) { var displayMessage = “Sys.InvalidOperationException: “ + (message ? message : Sys.Res.invalidOperation); var e = Error.create(displayMessage, {name: ‘Sys.InvalidOperationException’}); e.popStackFrame(); return e; }
Listing 24-42 presents the skeleton of a sample custom error handler that you can use to handle errors that the current PageRequestManager raises when it fires its endRequest event. Use this error handler if you want to handle the error on the client side by simply displaying the appropriate error to the end user.
Listing 24-42: A Custom Error Handler Skeleton function myCustomErrorHandler(error) { switch (error.name) { case ‘Sys.WebForms.PageRequestManagerTimeoutException’: // Handle error here break; case ‘Sys.WebForms.PageRequestManagerServerErrorException’: switch (error.httpStatusCode) { case 300: // Handle error here break; case 301: // Handle error here break; case 302: // Handle error here break; case 303: // Handle error here break; case 305: // Handle error here break; case 307: // Handle error here break; case 400: // Handle error here break; case 401: // Handle error here break;
1264
c24.indd 1264
8/20/07 8:48:10 PM
Chapter 24: Asynchronous Partial Page Rendering case 403: // Handle error here break; case 404: // Handle error here break; // . . . } break; case ‘Sys.WebForms.PageRequestManagerParserErrorException’: // Handle error here break; case ‘Sys.InvalidOperationException’: // Handle error here break; default: // Handle error here break; } }
Another thing that a custom error handler can do is quietly send an e-mail to the site administration when an error occurs. Listing 24-43 presents an example of a page that uses this approach.
Listing 24-43: A Page that Uses a Custom Error Handler void Page_Load(object sender, EventArgs e) { if (Request.Form[“ErrorName”] != null) { MailMessage mail = new MailMessage(); MailAddress fromAddress = new MailAddress(“[email protected]”); mail.From = fromAddress; MailAddress toAddress = new MailAddress(“[email protected]”); mail.To.Add(toAddress); mail.Subject = “Asynchronous Page Postback Request Error at “ + DateTime.Now; mail.Body = “Error Name: “ + Request.Form[“ErrorName”]; if (Request.Form[“HttpStatusCode”] != null) mail.Body += (“” + “HTTP Status Code: “ + Request.Form[“HttpStatusCode”]); mail.IsBodyHtml = true; SmtpClient smtp = new SmtpClient(); smtp.Host = “HostName”; smtp.Send(mail); Response.End(); }
(continued)
1265
c24.indd 1265
8/20/07 8:48:10 PM
Chapter 24: Asynchronous Partial Page Rendering Listing 24-43 (continued) Label parentUpdatePanelLabel = (Label)Page.FindControl(“ParentUpdatePanelLabel”); parentUpdatePanelLabel.Text = “UpdatePanel refreshed at “ + DateTime.Now.ToString(); Label childUpdatePanelLabel = (Label)Page.FindControl(“ChildUpdatePanelLabel”); childUpdatePanelLabel.Text = “UpdatePanel refreshed at “ + DateTime.Now.ToString(); } Untitled Page function customErrorHandler(error) { var formBody = new Sys.StringBuilder(); formBody.append(‘ErrorName=’); if (!error) formBody.append( encodeURIComponent( ‘Sys.WebForms.PageRequestManagerRequestAbortedException’)); else formBody.append(encodeURIComponent(error.name)); formBody.append(‘&’); if (error && error.name == ‘Sys.WebForms.PageRequestManagerServerErrorException’) { formBody.append(‘HttpStatusCode=’); formBody.append(encodeURIComponent(error.httpStatusCode)); formBody.append(‘&’); } var request = new Sys.Net.WebRequest(); request.set_url(document.form1.action); request.set_body(formBody.toString()); request.invoke(); } function pageLoad () { var prm = Sys.WebForms.PageRequestManager.getInstance(); prm.remove_endRequest(endRequestHandler); prm.add_endRequest(endRequestHandler); }
1266
c24.indd 1266
8/20/07 8:48:11 PM
Chapter 24: Asynchronous Partial Page Rendering function endRequestHandler(sender, e) { var error = e.get_error(); if (error) { customErrorHandler(error); return; } var response = e.get_response(); if (response.get_aborted()) { customErrorHandler(null); return; } var dataItems = e.get_dataItems(); var builder = new Sys.StringBuilder(); builder.append(“dataItems: “); builder.appendLine(); for (var controlID in dataItems) { builder.append(“Control ID: “); builder.append(controlID); builder.appendLine(); builder.append(“Data Item: “); builder.append(dataItem[controlID]); builder.appendLine(); } alert(builder.toString()); }
As you can see, the pageLoad JavaScript function is where we register a JavaScript function named endRequestHandler as an event handler for the endRequest event of the current PageRequestManager instance: function pageLoad () { var prm = Sys.WebForms.PageRequestManager.getInstance(); prm.remove_endRequest(endRequestHandler); prm.add_endRequest(endRequestHandler); }
When the current PageRequestManager instance finally fires the endRequest event and invokes the endRequestHandler function, it passes two parameters into this function. The first references the current PageRequestManager instance. The second references the EndRequestEventArgs object that contains the event data for the current endRequest event. Now let’s walk through the code for the endRequestHandler function. As you can see from Listing 24-43, this function first invokes the get_error method on the EndRequestEventArgs object to return a reference to the error object, if any. var error = e.get_error();
If the current PageRequestManager instance has indeed raised an error, the endRequestHandler method invokes the custom error handler function, passing in the error object. Note that the endRequestHandler method simply returns after invoking the error handler function. I’ll discuss the customErrorHandler function shortly. if (error) { customErrorHandler(error); return; }
1269
c24.indd 1269
8/20/07 8:48:12 PM
Chapter 24: Asynchronous Partial Page Rendering Next, the endRequestHandler function invokes the get_response method on the EndRequestEventArgs object to return a reference to the WebRequestExecutor object responsible for executing the current request: var response = e.get_response();
Then the function calls the get_aborted method on the WebRequestExecutor object to return a Boolean value that specifies whether the current request has been aborted. If so, it invokes our custom error handler function, passing in null: if (response.get_aborted()) { customErrorHandler(null); return; }
Next, it invokes the get_dataItems method on the EndRequestEventArgs object to return the dictionary that contains all data items: var dataItems = e.get_dataItems();
Then it instantiates a StringBuilder and populates it with the data items in this dictionary. Note that the endRequestHandler function uses the control ID as an index into the dictionary to access its associated data item. As we discussed earlier, each data item is associated with a particular server control on the current page. var builder = new Sys.StringBuilder(); builder.append(“dataItems: “); builder.appendLine(); for (var controlID in dataItems) { builder.append(“Control ID: “); builder.append(controlID); builder.appendLine(); builder.append(“Data Item: “); builder.append(dataItem[controlID]); builder.appendLine(); } alert(builder.toString());
Next, I’ll walk you through the implementation of the customErrorHandler function. The main responsibility of this method is to make an asynchronous request containing the error information to the server. What the server does with this error information is completely up to your application. As you’ll see later in this example, the server will simply send an e-mail containing the error information to the system administrator. As you can see from Listing 24-43, the customErrorHandler function first instantiates a StringBuilder, which will accumulate a list of ampersand-separated strings that will make up the body of the request that will subsequently be sent to the server. Each string will consist of two parts
1270
c24.indd 1270
8/20/07 8:48:12 PM
Chapter 24: Asynchronous Partial Page Rendering separated by the equals sign (=), where the first part will be used as a key on the server side to access the second part. The second part contains a piece of error information. var formBody = new Sys.StringBuilder();
The customErrorHandler function adds two strings to the StringBuilder. The first part (the key) of the first string is the string ErrorName: formBody.append(‘ErrorName=’);
The second part of the first string contains the name of the error. Recall that the endRequestHandler function passes null into the customErrorHandler function if the request has been aborted. As such, the customErrorHandler appends the string Sys.WebForms.PageRequestManagerRequestAbortedException as the error name. Keep in mind that the ASP.NET AJAX client-side framework does not contain an error with this name. I’ve added this for consistency. if (!error) formBody.append( encodeURIComponent( ‘Sys.WebForms.PageRequestManagerRequestAbortedException’));
If the error object passed into the customErrorHandler function is not null, the function simply appends the value of the name property of the error object as the error name: else formBody.append(encodeURIComponent(error.name));
The customErrorHandler function appends an & character before it starts rendering the second string. Keep in mind that the strings that make up the body of the request must be separated by & character: formBody.append(‘&’);
Next, the customErrorHandler function checks whether the error is of type Sys.WebForms.PageRequestManagerServerErrorException. If so, it appends a second string as follows. First, it appends the string HttpStatusCode as the first part (that is, the key) of the string: formBody.append(‘HttpStatusCode=’);
Then it appends the value of the httpStatusCode property of the error object as the second part of the string: formBody.append(encodeURIComponent(error.httpStatusCode)); formBody.append(‘&’);
Next, it instantiates a WebRequest object to represent a new asynchronous request: var request = new Sys.Net.WebRequest();
1271
c24.indd 1271
8/20/07 8:48:12 PM
Chapter 24: Asynchronous Partial Page Rendering Then it calls the set_url method on the WebRequest object to set the target URL of the request to the value of the action property of the form DOM element: request.set_url(document.form1.action);
Next, it calls the toString method on the StringBuilder to return a string that makes up the body of the request, and passes this string into the set_body method of the WebRequest object: request.set_body(formBody.toString());
Finally the customErrorHandler function calls the invoke method on the WebRequest object to send the request to the server: request.invoke();
Next, we need to go to the server side, where this request is processed. As you can see from Listing 24-43, the Page_Load method checks whether the Form collection of the current ASP.NET Request object contains an item with the key ErrorName. If so, it takes the following steps to send an e-mail to the administrator. First, it instantiates a MailMessage object to represent the e-mail being sent: MailMessage mail = new MailMessage();
Next, it instantiates a MailAddress object to represent the e-mail address of the sender and assigns this object to the From property of the MailMessage object that represents the e-mail being sent: MailAddress fromAddress = new MailAddress(“[email protected]”); mail.From = fromAddress;
Next, it instantiates another MailAddress object to represent the e-mail address of the receiver, that is, the administrator, and adds this object to the To collection property of the MailMessage that represents the e-mail being sent: MailAddress toAddress = new MailAddress(“[email protected]”); mail.To.Add(toAddress);
Then it specifies the subject of the e-mail: mail.Subject = “Asynchronous Page Postback Request Error at “ + DateTime.Now;
Next, it specifies the body of the e-mail. Note that the body contains the error name and HTTP status code (if any): mail.Body = “Error Name: “ + Request.Form[“ErrorName”]; if (Request.Form[“HttpStatusCode”] != null) mail.Body += (“” + “HTTP Status Code: “ + Request.Form[“HttpStatusCode”]); mail.IsBodyHtml = true;
1272
c24.indd 1272
8/20/07 8:48:12 PM
Chapter 24: Asynchronous Partial Page Rendering Then it instantiates a SmptClient object to send the e-mail: SmtpClient smtp = new SmtpClient(); smtp.Host = “HostName”; smtp.Send(mail);
Finally the Page_Load method calls the End method on the ASP.NET Response object to end processing of the current request: Response.End();
Summar y This chapter followed the current PageRequestManager instance thorough its life cycle phases to process the asynchronous server response text and update the associated UpdatePanel server controls and scripts. The chapters of this book used numerous examples, code walkthroughs, and under-the-hood looks to help you gain the skills, knowledge, and experience you need to take full advantage of the rich features of the ASP.NET AJAX framework in your own Web application. The earlier chapters of the book showed you how the ASP.NET AJAX client-side framework manages to simulate the rich features of the ASP.NET/.NET framework on the client side to enable you to use an ASP.NET/.NET-like programming style and techniques in your own client code. These earlier chapters covered a wide range of topics such as JavaScript base type extensions, object-oriented programming, exception programming, type inspection/description, event programming, and component/control development. We then dived into the client-server communication layer of the ASP.NET AJAX framework, where you learned how to use a .NET-like network programming style in your client-side code to communicate with the backend server. From there we moved on to Web services, where you learned how to enable your client code to exchange SOAP and JSON messages with Web services. You also learned four different ways to make a remote method call from your client code. Those discussions took us to the next related topic, proxy classes, where you learned how to use these classes to save yourself from having to write a lot of code to make remote method calls. We then moved on to the ASP.NET AJAX behaviors, where we also discussed the ASP.NET AJAX control toolkit. Next we covered script and extender server controls, where you learned how to develop your own custom versions. Finally, we covered UpdatePanel and ScriptManager server controls and ASP.NET AJAX partial page rendering. The appendices of the book will begin by providing an in-depth coverage of ASP.NET AJAX XML-script and showing you how it enables you to implement most features of your ASP.NET AJAX application in a purely declarative fashion, without writing imperative JavaScript code. This is great news to those of you who prefer declarative programming over imperative programming. These appendices will then cover ASP.NET AJAX actions, where you’ll learn how to encapsulate your favorite client-side functionality in a component known as an action and how to execute this component in response to a specified event of a specified ASP.NET AJAX object.
1273
c24.indd 1273
8/20/07 8:48:13 PM
Chapter 24: Asynchronous Partial Page Rendering We’ll then move on to ASP.NET AJAX binding, which will teach you how to bind specified properties of a given ASP.NET AJAX object to specified properties of another ASP.NET AJAX object. The appendices will then take us to data controls, and you’ll learn how to implement your own custom data controls that can bind to your favorite data collections to display the records of these collections. We’ll then dive into templated controls, where you’ll learn how to develop your own custom templated data controls. Finally, you’ll get a complete coverage of the ASP.NET AJAX ListView templated data control.
1274
c24.indd 1274
8/20/07 8:48:13 PM
XML Script The xml-script is an XML document enclosed within the opening and closing tags of an HTML script element whose type attribute is set to text/xml-script. The xml-script, like any other XML document, has a single element known as the document element that encapsulates the rest of the xmlscript. In other words, the document element is the outermost or containing element of an XML document. The document element in the case of the xml-script XML document is an element named page that belongs to an XML namespace named http://schemas.microsoft.com/xml-script/2005. The page document element contains a child element named components, which belongs to the same XML namespace as the page element. The descendants of the components element are the declarative representations of ASP.NET AJAX client-side objects. The ASP.NET AJAX client-side framework comes with an extensible JavaScript library that parses the descendants of the components element, instantiates and initializes the ASP.NET AJAX clientside objects that these descendant elements represent, and adds these ASP.NET AJAX client-side objects to the current ASP.NET AJAX application. As you’ll see later, an ASP.NET AJAX client class named MarkupContext plays an important role in the logic that parses the xml-script document. Therefore, I’ll begin by discussing this class.
MarkupContext Every instance of the MarkupContext ASP.NET AJAX class contains two important pieces of information:
bapp01.indd 1275
❑
An XML document that contains a subtree of DOM elements. As you’ll see later, the MarkupContext class comes with methods that you can use to search this document for a particular DOM element.
❑
An object collection that contains a list of ASP.NET AJAX components. As you’ll see later, the MarkupContext class comes with methods that you can use to search this collection for a particular ASP.NET AJAX component, or to add a new component to this collection.
8/20/07 8:58:14 PM
Appendix A: XML Script In general, there’re two types of markup contexts:
❑
Global markup context: The XML document of the global markup context contains all the DOM elements in the current document, including those in the xml-script. In other words, the document object is the XML document of the global markup context. The object collection of the global markup context contains all the ASP.NET AJAX components in the current page.
❑
Local markup context: The XML document of a local markup context contains a subtree of DOM elements that do not belong to the document object. In other words, you cannot call the getElementById method on the document object to access the DOM elements in this subtree. That is why MarkupContext comes with methods that enable you to access the DOM elements in the XML document of a local markup context. Local markup contexts are normally used in ASP.NET templates. As you’ll see later, the createInstance method of the ASP.NET AJAX Template class instantiates and initializes a local MarkupContext.
The following code listing presents the constructor of the MarkupContext class: Sys.Preview.MarkupContext = function Sys$Preview$MarkupContext(document, global, parentContext, dataContext) { this._document = document; this._global = global; this._ parentContext = parentContext; this._objects = { }; this._ pendingReferences = []; this._ pendingEndUpdates = []; }
This constructor takes the four parameters shown in the following table:
Parameter document
Description This parameter references the XML document associated with the MarkupContext.
global
This Boolean parameter specifies whether the MarkupContext is global.
parentContext
This parameter references the parent markup context of the current markup context. The parent markup context of the global markup context is null.
dataContext
This parameter references the current data context. (I’ll cover data contexts later.)
Note that the constructor of the MarkupContext instantiates an internal collection named _objects, in which it will maintain the list of its associated ASP.NET AJAX client-side components. The MarkupContext class exposes a method named addComponent that adds a new ASP.NET AJAX component to the _objects collection.
1276
bapp01.indd 1276
8/20/07 8:58:14 PM
Appendix A: XML Script As you’ll see later, every time the xml-script parser parses a node in xml-script and instantiates the ASP .NET AJAX component that the node represents, it calls the addComponent method on the current MarkupContext class to add this component to its _objects collection. As you can see from the following code listing, each component is stored in this collection under its id. (Recall that every ASP.NET AJAX component is uniquely identified by its id.) Note that addComponent takes a second argument of type Boolean that specifies whether the specified component must also be added to the Application object that represents the current application. Also note that the addComponent method does not add the specified component to the current Application if the current markup context is a local markup context. function Sys$Preview$MarkupContext$addComponent(component, noRegisterWithApp) { var id = component.get_id(); if(id) this._addComponentByID(id, component, noRegisterWithApp); } function Sys$Preview$MarkupContext$_addComponentByID(id, object, noRegisterWithApp) { this._objects[id] = object; if(!noRegisterWithApp && this._global && Sys.Component.isInstanceOfType(object)) Sys.Application.addComponent(object); }
This makes finding an ASP.NET AJAX component interesting. The MarkupContext exposes a method named findComponent that takes two parameters, the first being a string that contains the id of the component that you’re looking for. If the second parameter is not specified, findComponent first searches through the _objects collection of the current markup context for the component with the specified id. If it can’t find it there, findComponent then calls the findComponent method on the parent MarkupContext object. In most cases, the parent MarkupContext object is the global markup context. If the second parameter is specified, the findComponent method simply calls the findComponent method on the Application object that represents the current application, to look for the component among the child components of the specified parent. function Sys$Preview$MarkupContext$findComponent(id, parent) { if(parent) return Sys.Application.findComponent(id, parent); else { var object = this._objects[id]; if (!object) { parent = this._parentContext || Sys.Application; object = parent.findComponent(id); } return object; } }
1277
bapp01.indd 1277
8/20/07 8:58:15 PM
Appendix A: XML Script The MarkupContext class also exposes a method named getComponents that returns all the components in its _objects collection of the current markup context. function Sys$Preview$MarkupContext$getComponents() { var res = []; var objects = this._objects; for (var id in objects) res[res.length] = objects[id]; return res; }
Another interesting method of the MarkupContext class is one named findElement. As the name implies, this method returns a reference to the DOM element with the specified id HTML attribute value. It’s interesting to see how the search for this DOM element is performed. The findElement method first calls the getElementById method to search for the DOM element in the _document XML document fragment. Recall that the _document field of MarkupContext contains the XML document fragment associated with MarkupContext. In other words, MarkupContext assumes that the DOM element you’re looking for is in this XML document fragment. If it can’t find the element there, it searches the XML document fragment of its parent MarkupContext for the DOM element. function Sys$Preview$MarkupContext$findElement(id) { if (this._opened) { var element = Sys.UI.DomElement.getElementById(id, this._document); if (!element && this._parentContext) element = Sys.UI.DomElement.getElementById(id, this._parentContext); return element; } return null; }
Note that the constructor of the MarkupContext class instantiates another internal collection named _ pendingReferences. As we discussed earlier, when the xml-script parser parses a node in the xml-script into its associated ASP.NET AJAX component, it calls the addComponent method on the current MarkupContext to add the component to its _objects collection. If this component contains a property that references another ASP.NET AJAX component, the parser also invokes the addReference method on the current MarkupContext to add a reference to the _ pendingReferences collection for this property. This reference is a JavaScript object literal that has three properties: o, which refers to the ASP.NET AJAX component that owns the property that references another ASP.NET AJAX component, p, which refers to the propertyInfo object that represents this property, and r, which refers to the id of the referenced ASP.NET AJAX component. In other words, instead of trying to initialize the property that references another ASP.NET AJAX component, the parser makes a note of it by adding this JavaScript object literal to the _ pendingReferences collection of the current MarkupContext so it can initialize the property when it’s done with parsing all the xml-script nodes associated with the current MarkupContext. This is necessary because the property could be referencing an ASP.NET AJAX component associated with an xml-script node that hasn’t yet been parsed. To put it differently, the parser performs all the cross-references when it’s done with parsing all the xml-script nodes associated with the current markup context.
1278
bapp01.indd 1278
8/20/07 8:58:15 PM
Appendix A: XML Script function Sys$Preview$MarkupContext$addReference(instance, propertyInfo, reference) { Array.add(this._pendingReferences, { o: instance, p: propertyInfo, r: reference }); }
When the xml-script parser is finally done with parsing all the xml-script nodes associated with the current markup context, it invokes the close method of the current MarkupContext to resolve the previously mentioned cross-references, as shown in the following code listing. The close method iterates through the JavaScript object literals in the _pendingReferences collection and takes the following steps for each enumerated object. First, it calls the findComponent method on the MarkupContext, passing in the value of the r property of the enumerated JavaScript object literal. Recall that this property contains the id of the component referenced by the property being initialized. Also recall that the findComponent method first looks for the referenced component in its own _objects collection. If it can’t find the component there, it calls the findComponent method on its parent MarkupContext to look for the referenced component in the _objects collection of the parent MarkupContext. This search finally ends when the referenced component is located in the _objects collection of the first ancestor MarkupContext of the current MarkupContext. Next, the close method creates the string that contains the name of the setter method of the property being initialized, and uses this string as an index into the ASP.NET AJAX component whose property is being initialized to return a reference to this setter method: var setter = instance[‘set_’ + propertyInfo.name];
Next, the close method invokes the setter method to set the value of the specified property of the referenced component. function Sys$Preview$MarkupContext$close() { this._opened = false; var i; for (i = 0; i < this._pendingReferences.length; i++) { var pendingReference = this._pendingReferences[i]; var instance = pendingReference.o; var propertyInfo = pendingReference.p; var propertyValue = pendingReference.r; var object = this.findComponent(propertyValue); var setter = instance[‘set_’ + propertyInfo.name]; setter.call(instance, object); } this._pendingReferences = null; }
1279
bapp01.indd 1279
8/20/07 8:58:15 PM
Appendix A: XML Script The open method of MarkupContext instantiates the _pendingReferences collection and marks the MarkupContext as open: function Sys$Preview$MarkupContext$open() { this._pendingReferences = []; this._pendingEndUpdates = []; this._opened = true; } MarkupContext exposes a static method named createGlobalContext that creates the global MarkupContext. Note that the document object is passed into the constructor of the MarkupContext
class to create the global markup context. Sys.Preview.MarkupContext.createGlobalContext = function Sys$Preview$MarkupContext$createGlobalContext() { return new Sys.Preview.MarkupContext(document, true); }
The MarkupContext class also exposes a static method named createLocalContext that creates a local MarkupContext. Note that the XML document fragment associated with this local markup context is passed into the constructor of the MarkupContext class. Also note that the parent MarkupContext is passed as the third argument to this constructor. Sys.Preview.MarkupContext.createLocalContext = function Sys$Preview$MarkupContext$createLocalContext(documentFragment, parentContext, dataContext) { return new Sys.Preview.MarkupContext(documentFragment, false, parentContext, dataContext); }
Processing the xml-script XML Document Listing A-1 presents the script that starts the processing of the xml-script XML document. This script is part of the PreviewScript.js JavaScript file and is loaded and executed automatically. As you can see, this script first invokes the createGlobalContext static method on the MarkupContext class to create the global MarkupContext. Recall that the XML document associated with the global markup context is the document object. Note that the script shown in Listing A-1 stores this global MarkupContext in the _markupContext private field of the Application object that represents the current ASP.NET AJAX application. Sys.Application._markupContext = Sys.Preview.MarkupContext.createGlobalContext();
Next, the script shown in Listing A-1 registers a method of the Application object named __initHandler as an event handler for the init event of the Application object: Sys.Application.add_init(Sys.Application.__initHandler);
1280
bapp01.indd 1280
8/20/07 8:58:16 PM
Appendix A: XML Script Listing A-1: The Script that Starts the Processing of the xml-script XML Document if(!Sys.Application._markupContext) { Sys.Application._markupContext = Sys.Preview.MarkupContext.createGlobalContext(); Sys.Application.add_init(Sys.Application.__initHandler); Sys.Application.add_unload(Sys.Application.__unloadHandler); }
When the Application object that represents the current ASP.NET AJAX application finally raises its init event, the Application object automatically invokes the __initHandler method. As you can see from Listing A-2, this method in turn invokes the processDocument static method on an ASP.NET AJAX client class named MarkupParser, passing in the global MarkupContext: Sys.Preview.MarkupParser.processDocument(Sys.Application._markupContext);
Listing A-2: The __initHandler Method Sys.Application.__initHandler = function Sys$Application$__initHandler() { Sys.Application.remove_init(Sys.Application.__initHandler); Sys.Preview.MarkupParser.processDocument(Sys.Application._markupContext); }
processDocument Listing A-3 presents a simplified version of the implementation of the processDocument method.
Listing A-3: The processDocument Method Sys.Preview.MarkupParser.processDocument = function Sys$Preview$MarkupParser$processDocument(markupContext) { var pageNodes = []; var scriptElements = document.getElementsByTagName(‘script’); var xmlScriptElement = null; for (var e = 0; e < scriptElements.length; e++) { if (scriptElements[e].type == ‘text/xml-script’) { xmlScriptElement = scriptElements[e]; break; } }
(continued)
1281
bapp01.indd 1281
8/20/07 8:58:16 PM
Appendix A: XML Script Listing A-3 (continued) if (xmlScriptElement) { var xmlDocument; if (Sys.Net.XMLDOM) xmlDocument = new Sys.Net.XMLDOM(scriptMarkup); else xmlDocument = new XMLDOM(xmlScriptElement.innerHTML); var documentElement = xmlDocument.documentElement; if (!documentElement || Sys.Preview.MarkupParser.getNodeName(documentElement) != =”page”) throw Error.create(‘Missing page element in xml script block.’, scriptMarkup); Sys.Preview.MarkupParser.processDocumentScripts(markupContext, documentElement); } }
This method first calls the getElementsByTagName method on the document object to return an array that contains references to all script HTML elements on the current page: var scriptElements = document.getElementsByTagName(‘script’);
Next, it searches through the script HTML elements in this array for a script HTML element with the type attribute value of text/xml-script: for (var e = 0; e < scriptElements.length; e++) { if (scriptElements[e].type == ‘text/xml-script’) { xmlScriptElement = scriptElements[e]; break; } }
As I mentioned earlier, Listing A-3 presents a simplified version of the ProcessDocument method. The full version of this method supports multiple script HTML elements with a type attribute value of text/xml-script. Next the processDocument method loads the content of this script HTML element into an XMLDOM document: var xmlDocument = new XMLDOM(xmlScriptElement.innerHTML);
Then it references the document element of the xml-script XML document. As we discussed earlier, the document element of the xml-script XML document is an element named page. If the document element
1282
bapp01.indd 1282
8/20/07 8:58:16 PM
Appendix A: XML Script does not exist or if it is anything other than the page element, the processDocument method raises an exception: var documentElement = xmlDocument.documentElement; if (!documentElement || Sys.Preview.MarkupParser.getNodeName(documentElement) != =”page”) throw Error.create(‘Missing page element in xml script block.’, scriptMarkup);
Finally, processDocument invokes the processDocumentScripts static method on the MarkupParser class, passing in the global MarkupContext and the document element of the xml-script XML document — that is, the page element or node: Sys.Preview.MarkupParser.processDocumentScripts(markupContext, documentElement);
processDocumentScripts Listing A-4 presents the implementation of the processDocumentScripts method.
Listing A-4: The processDocumentScripts Method Sys.Preview.MarkupParser.processDocumentScripts = function Sys$Preview$MarkupParser$processDocumentScripts(markupContext, pageNode) { markupContext.open(); var componentNodes = []; var pageChildNodes = pageNode.childNodes; for (var i = pageChildNodes.length - 1; i > =0; i--) { var pageChildNode = pageChildNodes[i]; if (pageChildNode.nodeType != =1) continue; var pageChildNodeName = Sys.Preview.MarkupParser.getNodeName(pageChildNode); pageChildNodeName = pageChildNodeName.toLowerCase(); if (pageChildNodeName === ‘components’) { for (var c = 0; c < pageChildNode.childNodes.length; c++) { var componentNode = pageChildNode.childNodes[c]; if (componentNode.nodeType != =1) continue; Array.add(componentNodes, componentNode); } } } Sys.Preview.MarkupParser.parseNodes(componentNodes, markupContext); markupContext.close(); }
1283
bapp01.indd 1283
8/20/07 8:58:16 PM
Appendix A: XML Script This method first invokes the open method on the global MarkupContext. Recall that the open method instantiates the _pendingReferences collection: markupContext.open();
Next, the processDocumentScripts method searches through the child elements of the page node for a child element named components. It then iterates through the child elements of the components element and adds each enumerated child element to a local collection named componentNodes. (Keep in mind that each child element of the components element is a declarative representation of an ASP.NET AJAX client component. In other words, each child element of the components element is a component node.) if (pageChildNodeName === ‘components’) { for (var c = 0; c < pageChildNode.childNodes.length; c++) { var componentNode = pageChildNode.childNodes[c]; if (componentNode.nodeType !== 1) continue; Array.add(componentNodes, componentNode); } }
Next, the processDocumentScripts method invokes the parseNodes static method on the MarkupParser class, passing in two parameters. The first parameter is the array that contains the references to all the component child nodes of the components element. The second parameter references the global MarkupContext. As you’ll see later, the parseNodes method parses the nodes in its first parameter, determines the ASP.NET AJAX type associated with each node, instantiates this type, and adds it to the _objects collection of the MarkupContext object that is passed into the method as its second argument. Sys.Preview.MarkupParser.parseNodes(componentNodes, markupContext);
Finally, the processDocumentScripts method invokes the close method on the global MarkupContext. Recall that the close method resolves the component cross-references. markupContext.close();
parseNodes The parseNodes static method of the MarkupParser class takes two parameters, as shown in the following table:
1284
bapp01.indd 1284
8/20/07 8:58:17 PM
Appendix A: XML Script Parameter
Description
Nodes
An array that contains references to xml-script nodes being parsed.
markupContext
References the current MarkupContext. For example, as you’ll see later, each element in xml-script is associated with a local markup context, which means that all descendant nodes of this element are parsed within this local markup context.
The main responsibility of the parseNodes method is to parse the specified xml-script nodes into their associated ASP.NET AJAX objects. As Listing A-5 shows, the parseNodes method iterates through these xml-script nodes and takes the following steps for each enumerated xml-script node. First, it invokes the parseNode static method on the MarkupParser class, passing in two parameters: the first is the reference to the enumerated xml-script node, and the second is the reference to the current MarkupContext. var processedObject = Sys.Preview.MarkupParser.parseNode(node, markupContext);
As you’ll see later, the parseNode method parses the specified xml-script node into its associated ASP.NET AJAX object, and returns this object. The parseNodes method then adds the object to an internal collection: if (processedObject) Array.add(objects, processedObject);
As you can see, this internal collection basically collects all the ASP.NET AJAX objects associated with the xml-script nodes passed into the parseNodes method as its first argument. The parseNodes method then returns this collection to its caller: if (processedObject) Array.add(objects, processedObject);
Listing A-5: The parseNodes Method Sys.Preview.MarkupParser.parseNodes = function Sys$Preview$MarkupParser$parseNodes(nodes, markupContext) { var objects = []; for (var i = 0; i < nodes.length; i++) { var node = nodes[i]; if (node.nodeType != =1) continue; var processedObject = Sys.Preview.MarkupParser.parseNode(node, markupContext); if (processedObject) Array.add(objects, processedObject); } return objects; }
1285
bapp01.indd 1285
8/20/07 8:58:17 PM
Appendix A: XML Script
parseNode The parseNode method, shown in Listing A-6, takes two parameters, as shown in the following table:
Parameter
Description
node
References the xml-script node being parsed
markupContext
References the current MarkupContext
The main responsibility of the parseNode method is to parse the specified xml-script node to its associated ASP.NET AJAX object. It begins by invoking the _getTagType static method on the MarkupParser class, passing in the reference to the xml-script node being parsed. As you’ll see later, the _getTagType name determines and returns the Type object that represents the type of the ASP.NET AJAX class associated with the xml-script node being parsed: var tagType = Sys.Preview.MarkupParser._getTagType(node);
Next, the parseNode method checks whether the ASP.NET AJAX class associated with the xml-script node being parsed contains a static method named parseFromMarkup. If so, it uses this method as the parsing method. If not, it walks up the ancestors of this ASP.NET AJAX class until it reaches an ancestor that supports the parseFromMarkup static method, and assigns this method as the static method of the ASP.NET AJAX class. var parseMethod = tagType.parseFromMarkup; if (!parseMethod) { var baseType = tagType.getBaseType(); while (baseType) { parseMethod = baseType.parseFromMarkup; if (parseMethod) break; baseType = baseType.getBaseType(); } tagType.parseFromMarkup = parseMethod; }
Next, it invokes the parseFromMarkup static method, passing in four parameters: the first is null, the second references the Type object that represents the ASP.NET AJAX class associated with the xml-script node being parsed, the third references the xml-script node being parsed, and the fourth references the current MarkupContext. parsedObject = parseMethod.call(null, tagType, node, markupContext);
As you’ll see later, the parseFromMarkup static method of the ASP.NET AJAX class that’s associated with the xml-script node being parsed instantiates, initializes, and returns an instance of this class.
1286
bapp01.indd 1286
8/20/07 8:58:17 PM
Appendix A: XML Script Listing A-6: The parseNode Method Sys.Preview.MarkupParser.parseNode = function Sys$Preview$MarkupParser$parseNode(node, markupContext) { var parsedObject = null; var tagType = Sys.Preview.MarkupParser._getTagType(node); if (tagType) { var parseMethod = tagType.parseFromMarkup; if (!parseMethod) { var baseType = tagType.getBaseType(); while (baseType) { parseMethod = baseType.parseFromMarkup; if (parseMethod) break; baseType = baseType.getBaseType(); } tagType.parseFromMarkup = parseMethod; } if (parseMethod) parsedObject = parseMethod.call(null, tagType, node, markupContext); } return parsedObject; }
_getTagType The _getTagType static method of the MarkupParser class, shown in Listing A-7, takes a single parameter that references the node being parsed. The main responsibility of the _getTagType method is to determine the ASP.NET AJAX type associated with the specified xml-script node. This method begins by invoking the getNodeName static method on the MarkupParser class to return the name of the xml-script node being parsed: var tagName = Sys.Preview.MarkupParser.getNodeName(node);
It then determines the XML namespace to which the node being parsed belongs: var namespaceURI = node.namespaceURI || Sys.Preview.MarkupParser._defaultNamespaceURI;
Note that the MarkupParser class exposes a static field named _defaultNamespaceURI with the following value: Sys.Preview.MarkupParser._defaultNamespaceURI = ‘http://schemas.microsoft.com/xml-script/2005’;
1287
bapp01.indd 1287
8/20/07 8:58:18 PM
Appendix A: XML Script The MarkupParser class also exposes another static collection field named _cachedNamespaceURILists, which caches the ASP.NET AJAX namespaces associated with each XML namespace. Sys.Preview.MarkupParser._cachedNamespaceURILists = {};
The _getTagType method uses the XML namespace of the node being parsed as an index into this cache to return the list of ASP.NET AJAX namespaces associated with the node: var nspaceList = Sys.Preview.MarkupParser._cachedNamespaceURILists[namespaceURI];
If the cache does not contain any ASP.NET AJAX namespaces associated with the XML namespace of the node being parsed, the _getTagType method invokes the _processNamespaceURI static method on the MarkupParser class to evaluate and return the list of ASP.NET AJAX namespaces associated with this XML namespace: nspaceList = Sys.Preview.MarkupParser._processNamespaceURI(namespaceURI);
The _getTagType method then uses the XML namespace as an index into the cache to add this list of ASP.NET AJAX namespaces to the cache. As a result, the next request for this list will be serviced directly from the cache to improve performance: Sys.Preview.MarkupParser._cachedNamespaceURILists[namespaceURI] = nspaceList;
Next, _getTagType uses the toUpperCase method to convert all lowercase characters in the name of the xml-script node to uppercase: var upperTagName = tagName.toUpperCase();
Next, _getTagType iterates through the list of ASP.NET AJAX namespaces associated with the XML namespace of the xml-script node being parsed, and invokes the parse static method on the Type class, passing in the name of the xml-script node and the enumerated ASP.NET AJAX namespace. The parse static method determines whether the enumerated ASP.NET AJAX namespace contains an ASP.NET AJAX type with the same name as the xml-script node. If so, the method returns a reference to the constructor of the ASP.NET AJAX type. for(var i=0; i < nspaceList.length; i++) { var nspace = nspaceList[i]; var type = Type.parse(tagName, nspace); if(typeof(type) === ‘function’) return type; }
If none of the ASP.NET AJAX namespaces associated with the specified XML namespace contains an ASP.NET AJAX type with the same name as the xml-script node, the _getTagType checks whether the xml-script node’s name is APPLICATION. If so, it simply returns a reference to the Sys._Application constructor. if(upperTagName === “APPLICATION”) return Sys._Application;
1288
bapp01.indd 1288
8/20/07 8:58:18 PM
Appendix A: XML Script If the xml-script node’s name is not APPLICATION either, the _getTagType checks whether the xml-script node’s name is WEBREQUESTMANAGER. If so, it simply returns a reference to the Sys.Net._WebRequestManager constructor: if(upperTagName === “WEBREQUESTMANAGER”) return Sys.Net._WebRequestManager;
If the xml-script node’s name is not WEBREQUESTMANAGER either, the _getTagType gives up and returns null to tell its caller that there’s no ASP.NET AJAX type with the same name as the xml-script node whose type is being determined: return null;
Listing A-7: The _getTagType Method Sys.Preview.MarkupParser._getTagType = function Sys$Preview$MarkupParser$_getTagType(node) { var tagName = Sys.Preview.MarkupParser.getNodeName(node); var namespaceURI = node.namespaceURI || Sys.Preview.MarkupParser._defaultNamespaceURI; var nspaceList = Sys.Preview.MarkupParser._cachedNamespaceURILists[namespaceURI]; if (typeof(nspaceList) === ‘undefined’) { nspaceList = Sys.Preview.MarkupParser._processNamespaceURI(namespaceURI); Sys.Preview.MarkupParser._cachedNamespaceURILists[namespaceURI] = nspaceList; } var upperTagName = tagName.toUpperCase(); for(var i=0; i < nspaceList.length; i++) { var nspace = nspaceList[i]; var type = Type.parse(tagName, nspace); if(typeof(type) === ‘function’) return type; } if(upperTagName === “APPLICATION”) return Sys._Application; if(upperTagName === “WEBREQUESTMANAGER”) return Sys.Net._WebRequestManager; return null; }
_processNamespaceURI The main responsibilities of the _processNamespaceURI static method of the MarkupParser class are to create and return an array that contains all the ASP.NET AJAX namespaces associated with the specified XML namespace URI. Listing A-8 contains the implementation of this method.
1289
bapp01.indd 1289
8/20/07 8:58:18 PM
Appendix A: XML Script Listing A-8: The _processNamespaceURI Method Sys.Preview.MarkupParser._processNamespaceURI = function Sys$Preview$MarkupParser$_processNamespaceURI(namespaceURI) { if(!namespaceURI || namespaceURI === Sys.Preview.MarkupParser._defaultNamespaceURI) return Sys.Preview.MarkupParser._getDefaultNamespaces(); var start = namespaceURI.slice(0, 12).toLowerCase(); if(start === “javascript:”) { namespaceURI = namespaceURI.slice(11); if(!namespaceURI.length) return []; } var nspaceList = namespaceURI.split(‘,’); list = []; for(var i=0; i < nspaceList.length; i++) { var nspaceName = nspaceList[i]; if(nspaceName.startsWith(‘ ‘)) nspaceName = nspaceName.trimStart(); if(nspaceName.endsWith(‘ ‘)) nspaceName = nspaceName.trimEnd(); if(!nspaceName.length) continue; var nspace = null; try { nspace = eval(nspaceName); } catch(e) { } if (!nspace || !Type.isNamespace(nspace)) throw Error.invalidOperation(String.format(“’{0}’ is not a valid namespace.”, nspaceName)); if(nspace) Array.add(list, nspace); } return list; }
If the specified XML namespace URI is the default namespace (that is, the standard http://schemas .microsoft.com/xml-script/2005 XML namespace) the _processNamespaceURI delegates to the _getDefaultNamespaces static method of the MarkupParser class the responsibility of creating and returning the array that contains all the ASP.NET AJAX namespaces associated with this standard XML namespace. I’ll discuss this static method in the following section. if(!namespaceURI || namespaceURI === Sys.Preview.MarkupParser._defaultNamespaceURI) return Sys.Preview.MarkupParser._getDefaultNamespaces();
1290
bapp01.indd 1290
8/20/07 8:58:18 PM
Appendix A: XML Script Next, the _processNamespaceURI splits the specified XML namespace URI into an array of XML namespace names: var nspaceList = namespaceURI.split(‘,’); list = [];
Then it iterates through these XML namespace names and invokes the eval JavaScript function once for each XML namespace name, to return one reference for each namespace to the actual XML namespace. nspace = eval(nspaceName);
As you can see, the xml-script is very strict about the names of the custom XML namespaces. They cannot include strings such as http://; they must be the name of the actual ASP.NET AJAX namespaces. The eval JavaScript function basically takes the string that contains the name of an ASP.NET AJAX namespace and returns a reference to the actual namespace. Note that if the value that the eval method returns is not a valid ASP.NET AJAX namespace, the _processNamespaceURI raises an exception: if (!nspace || !Type.isNamespace(nspace)) throw Error.invalidOperation(String.format(“’{0}’ is not a valid namespace.”, nspaceName));
Also note that the _processNamespaceURI collects in a local array the return values of the calls into the eval method (that is, the actual ASP.NET AJAX namespaces). This array is then returned to the caller of the method: Array.add(list, nspace);
_getDefaultNamespaces As you can see from Listing A-9, the _getDefaultNamespaces method populates the _defaultNamespace static array field of the MarkupParser class with the list of standard ASP.NET AJAX namespaces such as Sys, Sys.UI, Sys.Net, and so on.
Listing A-9: The _getDefaultNamespaces Method Sys.Preview.MarkupParser._getDefaultNamespaces = function Sys$Preview$MarkupParser$_getDefaultNamespaces() { if(!Sys.Preview.MarkupParser._defaultNamespaces) { var list = [ Sys, Sys.UI, Sys.Net, Sys.Preview, Sys.Preview.UI, Sys.Preview.Net, Sys.Preview.Data, Sys.Preview.UI.Data, Sys.Preview.Services.Components ]; if(Sys.Preview.UI.Effects) Array.add(list, Sys.Preview.UI.Effects); Sys.Preview.MarkupParser._defaultNamespaces = list; } return Sys.Preview.MarkupParser._defaultNamespaces; }
1291
bapp01.indd 1291
8/20/07 8:58:19 PM
Appendix A: XML Script
parseFromMarkup Each ASP.NET AJAX type either defines a static method named parseFromMarkup or inherits this method from its first ancestor, which defines this method through the process discussed earlier. This method takes the three parameters shown in the following table:
Parameter
Description
type
This parameter references the constructor of the ASP.NET AJAX type associated with the xml-script node being parsed. Recall that this ASP.NET AJAX type has the same name as the xml-node being parsed.
node
This parameter references the xml-node being parsed.
markupContext
This parameter references the current MarkupContext. Recall that the current MarkupContext internally maintains three important entities. The first one is a document fragment that contains a subtree of nodes (_document). The second is a collection of ASP.NET AJAX components (_objects). The third is a collection of JavaScript object literals, each of which represents a property of an ASP.NET AJAX component that references another ASP.NET AJAX component (_pendingReferences).
As mentioned earlier, the parseFromMarkup method is a static method: it is defined on an ASP.NET AJAX type itself, not its prototype property. The parseFromMarkup static method of a given ASP.NET AJAX type has the following main responsibilities:
❑
It must instantiate an instance of the ASP.NET AJAX type. Since the first parameter of the parseFromMarkup method references the constructor of this type, instantiating an instance is normally as simple as invoking the new JavaScript operator on this constructor:
var instance = new type();
❑
It must initialize this instance. Initializing an ASP.NET AJAX object involves two main tasks:
❑
Initializing the properties of the instance: The second parameter of the parseFromMarkup method references the xml-script node that represents this instance in xml-script. This xml-script node contains attributes or child nodes with the same names as the properties of this ASP.NET AJAX instance. The parseFromMarkup method must parse the values of these attributes or child nodes and assign them to the properties of the ASP.NET AJAX instance with the same names. For some properties of this ASP.NET AJAX instance, such as those simple properties that directly map to the attributes on the xml-script node, the parseFromMarkup method may simply use the DOM API to access the values of these attributes and directly assign them to the properties of the instance. For some more complex properties, the parseFromMarkup method delegates the responsibility of initialization to the initializeObject static method of the MarkupParser class.
❑
Registering event handlers for the events of the instance: As just mentioned, the second parameter of the parseFromMarkup method references the xml-script node that represents this instance in xml-script. This xml-script node contains attributes or child nodes with the same names as the events of this ASP.NET AJAX instance. The parseFromMarkup method must parse the values of these attributes or child nodes. These values are nothing but the
1292
bapp01.indd 1292
8/20/07 8:58:19 PM
Appendix A: XML Script names of the event handlers that must be registered for the specified events. Since the initializeObject static method of the MarkupParser class already contains the logic that knows how to get a reference to the event handler with the specified name, the parseFromMarkup method normally delegates the responsibility of registering event handlers for the events of the instance to the initializeObject method.
❑
It must add this ASP.NET AJAX instance to the _objects collection of the current MarkupContext. Recall that this collection maintains the list of all the ASP.NET AJAX instances parsed within the current MarkupContext. As we discussed earlier, the current MarkupContext exposes a method named addComponent that the parseFromMarkup method can use to add the newly parsed ASP.NET AJAX instance to this collection.
The parseFromMarkup method is the most important extensibility point of the ASP.NET AJAX xml-script-parsing infrastructure. Your custom classes can define a custom parseFromMarkup method to take complete control over how the xml-script node that represents an instance of your custom class in xml-script must be parsed. The custom parseFromMarkup method of your custom class must meet the following requirements:
❑
It must be named parseFromMarkup.
❑
It must take three parameters. The first references the constructor of your custom class, the second references the xml-script node that represents the current instance of your custom class in xml-script, and the third references the current MarkupContext.
❑
It must instantiate, initialize, and return the instance of your custom class that represents the xml-script node referenced by the second parameter.
❑
It must be static — that is, it must be defined on your custom class, not its prototype property.
You’ll see an example of a custom parseFromMarkup method in Appendix E. If your custom component does not define its own parseFromMarkup method, the ASP.NET AJAX xml-script-parsing infrastructure walks up the ancestors of your custom class searching for the first ancestor that support this method and assigns it to your custom class. In other words, your custom class will end up using the parseFromMarkup method of its first ancestor that supports this method. For example, if you implement a custom control that derives from the Control base class, and if your custom control does not directly support its own parseFromMarkup method, it will end up using the parseFromMarkup method of the Control base class, as shown in Listing A-10.
Listing A-10: The parseFromMarkup Method Sys.UI.Control.parseFromMarkup = function Sys$UI$Control$parseFromMarkup(type, node, markupContext) { var idAttribute = node.attributes.getNamedItem(‘id’); var id = idAttribute.nodeValue; var associatedElement = markupContext.findElement(id); var dataContextHidden = false; var dataContext = markupContext.get_dataContext(); if (dataContext) dataContextHidden = markupContext.hideDataContext();
(continued)
1293
bapp01.indd 1293
8/20/07 8:58:19 PM
Appendix A: XML Script Listing A-10 (continued) var newControl = new type(associatedElement); var control = Sys.Preview.MarkupParser.initializeObject(newControl, node, markupContext); if (control) { var id = control.get_id(); markupContext.addComponent(control); if (dataContext) control.set_dataContext(dataContext); } else newControl.dispose(); if (dataContextHidden) markupContext.restoreDataContext(); return control; }
This listing shows an example of the implementation of the parseFromMarkup method. You can follow this example to implement your own custom parseFromMarkup method for your own custom classes. Next, I’ll walk you through this sample parseFromMarkup method. As you can see, it begins by calling the getNamedItem method on the attributes collection of the xml-script node that represents the current control in xml-script to return a reference to the attribute node that represents the id attribute of the xml-script node: var idAttribute = node.attributes.getNamedItem(‘id’);
Next, it invokes the nodeValue property on this attribute node to access the value of the id attribute: var id = idAttribute.nodeValue;
Then it invokes the findElement method on the current MarkupContext, passing in the id attribute value to return a reference to the associated DOM element of the control. Recall that each ASP.NET AJAX client control is associated with a DOM element whose id HTML attribute is given by the id attribute of the xml-script node that represents the client control in xml-script: var associatedElement = markupContext.findElement(id);
Next, it invokes the new JavaScript operator on the constructor of the client control, passing in the reference to the associated DOM element of the control to instantiate the client control associated with the specified xml-script node. Recall that the first parameter of the parseFromMarkup method references the constructor of the ASP.NET AJAX type associated with the specified xml-script node: var newControl = new type(associatedElement);
Then the parseFromMarkup method delegates the responsibility of initializing the properties of the newly instantiated client control, and the responsibility of registering event handlers for its events, to the initializeObject static method of the MarkupParser class:
1294
bapp01.indd 1294
8/20/07 8:58:20 PM
Appendix A: XML Script var control = Sys.Preview.MarkupParser.initializeObject(newControl, node, markupContext);
Next, the parseFromMarkup method calls the addComponent method on the current MarkupContext to add the client control to its _objects collection. Recall that the current MarkupContext maintains the list of all the ASP.NET AJAX components parsed in the current markup context in this collection: markupContext.addComponent(control);
initializeObject The initializeObject method takes the three parameters described in the following table:
Parameter
Description
instance
References the ASP.NET AJAX object being initialized
node
References the xml-script node that represents the ASP.NET AJAX object being initialized
markupContext
References the current MarkupContext
As the name suggests, the initializeObject method initializes the ASP.NET AJAX object that its first parameter references. This initialization involves two main tasks:
❑
Initializing the properties of the ASP.NET AJAX object: The xml-script node referenced by the second parameter of the initializeObject method exposes attributes or child nodes with the same names as the properties of the ASP.NET AJAX object being initialized. The initializeObject method extracts the required values from these attributes or child nodes and assigns them to the properties of the ASP.NET AJAX object with the same names.
❑
Registering event handlers for the events of the ASP.NET AJAX object: The xml-script node referenced by the second parameter of the initializeObject method exposes attributes or child nodes with the same names as the events of the ASP.NET AJAX object being initialized. The initializeObject method extracts the required event handlers from these attributes or child nodes and registers them as event handlers for the events of the ASP.NET AJAX object with the same names.
Before diving into the implementation of the initializeObject method we need to revisit the ASP.NET AJAX TypeDescriptor class, because the initializeObject method makes extensive use of this class and its methods. Recall from Chapter 10 that every ASP.NET AJAX type, such as a class, is associated with an object known as a type descriptor, which generically describes the properties, events, methods, and metadata attributes of the type. This object allows the client of an ASP.NET AJAX type to inspect the type generically without knowing the actual type of the type. The ASP.NET AJAX TypeDescriptor class comes with a static method named getTypeDescriptor that takes an ASP.NET AJAX object as its argument and returns a reference to the type descriptor object that describes the type of this ASP.NET AJAX object.
1295
bapp01.indd 1295
8/20/07 8:58:20 PM
Appendix A: XML Script As you’ll see shortly, to initialize the ASP.NET AJAX object passed into it in a generic way, the initializeObject method uses the type descriptor object returned by the getTypeDescriptor static method of the TypeDescriptor class. Therefore, the type descriptor object associated with a given ASP.NET AJAX type determines how an instance of the type is initialized from the attributes and child nodes of the xml-script node that represents the instance in xml-script. Therefore, if you want to enable the clients of your custom ASP.NET AJAX type to instantiate and initialize instances of your custom type in xml-script in a purely declarative fashion, without their writing any JavaScript code, you must take extra steps to make sure that the getTypeDescriptor static method of the TypeDescriptor class returns the appropriate type descriptor object to the initializeObject method. You have two options:
❑
Have your custom type implement the ICustomTypeProvider interface, so the getTypeDescriptor static method returns your own custom type descriptor object.
❑
Define a descriptor static property on your custom type to describe the properties, events, methods, and metadata attributes of your type, as we discussed earlier.
Which approach is better? It depends on the specifics of your application requirements. In general, the first approach is more flexible than the second but requires more coding. Keep in mind that your custom type must either implement the ICustomTypeProvider interface or expose a static property named descriptor. Otherwise no one will be able to use your custom type declaratively in xml-script. The implementation of the initializeObject method is quite complex. To help you get a better understanding of this method, I’ll present an example of its implementation. This example consists of four ASP.NET AJAX client classes named MyCustomType, MyEnumeration, MyType, and MyType2. A JavaScript file named MyClientTypes.js contains the implementation of these three client classes. Listing A-11 presents the content of this JavaScript file.
Listing A-11: The Content of the MyClientTypes.js JavaScript File Type.registerNamespace(“CustomComponents”); CustomComponents.MyType2 = function CustomComponents$MyType2(param1, param2, param3) { this._param1 = param1; this._param2 = param2; this._param3 = param3; } CustomComponents.MyType2.registerClass(“CustomComponents.MyType2”); CustomComponents.MyType2.parse = function (value) { var params = value.split(‘,’); alert(“Instantiating a MyType2 object and initializing it with “ + params); return new CustomComponents.MyType2(params[0], params[1], params[2]); } /////////////////////////////// CustomComponents.MyEnumeration = function CustomComponents$MyEnumeration() { throw Error.invalidOperation(); }
1296
bapp01.indd 1296
8/20/07 8:58:20 PM
Appendix A: XML Script CustomComponents.MyEnumeration.prototype = { EnumValue1: 0, EnumValue2: 1, EnumValue3: 2 } CustomComponents.MyEnumeration.registerEnum(“CustomComponents.MyEnumeration”); ////////////////////////////// CustomComponents.MyType = function CustomComponents$MyType() { } function CustomComponents$MyType$set_myTypeProperty(value) { this._myTypeProperty = value; alert(“myTypeProperty was set to “ + value); } function CustomComponents$MyType$get_myTypeProperty() { return this._myTypeProperty; } CustomComponents.MyType.prototype = { get_myTypeProperty : CustomComponents$MyType$get_myTypeProperty, set_myTypeProperty : CustomComponents$MyType$set_myTypeProperty } CustomComponents.MyType.registerClass(“CustomComponents.MyType”); CustomComponents.MyType.descriptor = { properties : [{name : “myTypeProperty”, type : String}] } ////////////////////////////// CustomComponents.MyCustomType = function CustomComponents$MyCustomType() { CustomComponents.MyCustomType.initializeBase(this); } function CustomComponents$MyCustomType$add_myEvent(eventHandler) { this.get_events().addHandler(“myEvent”, eventHandler); alert(eventHandler + “ \n\nwas registered as event handler for myEvent event!”); } function CustomComponents$MyCustomType$remove_myEvent(eventHandler) { this.get_events().removeHandler(“myEvent”, eventHandler); } function CustomComponents$MyCustomType$set_myProperty(value) { this._myProperty = value; alert(“myProperty was set to the DOM element with id HTML attribute value of “ + value.id); }
(continued)
1297
bapp01.indd 1297
8/20/07 8:58:21 PM
Appendix A: XML Script Listing A-11 (continued) function CustomComponents$MyCustomType$get_myProperty() { return this._myProperty; } function CustomComponents$MyCustomType$set_myNonReadOnlyStringProperty(value) { this._myNonReadOnlyStringProperty = value; alert(“myNonReadOnlyStringProperty was set to “ + value); } function CustomComponents$MyCustomType$get_myNonReadOnlyStringProperty() { return this._myNonReadOnlyStringProperty; } function CustomComponents$MyCustomType$set_myProperty2(value) { this._myProperty2 = value; alert(“myProperty2 was set to “ + value); } function CustomComponents$MyCustomType$get_myProperty2() { return this._myProperty2; } function CustomComponents$MyCustomType$set_myReferenceProperty(value) { this._myReferenceProperty = value; alert(“myReferenceProperty was set to the component with the id value of “ + value.get_id()); } function CustomComponents$MyCustomType$get_myReferenceProperty() { return this._myReferenceProperty; } function CustomComponents$MyCustomType$set_myArrayProperty(value) { this._myArrayProperty = value; alert(“myArrayProperty was set to “ + value); } function CustomComponents$MyCustomType$get_myArrayProperty() { return this._myArrayProperty; } function CustomComponents$MyCustomType$get_myReadOnlyArrayProperty() { alert(“The value of myReadOnlyArrayProperty is being retrieved!”); return this._myReadOnlyArrayProperty; }
1298
bapp01.indd 1298
8/20/07 8:58:21 PM
Appendix A: XML Script function CustomComponents$MyCustomType$get_myObjectProperty() { alert(“The value of myObjectProperty is being retrieved!”); return this._myObjectProperty; } function CustomComponents$MyCustomType$get_myNonObjectNonArrayProperty() { alert(“The value of myNonObjectNonArrayProperty is being retrieved!”); if (!this._myNonObjectNonArrayProperty) this._myNonObjectNonArrayProperty = new CustomComponents.MyType(); return this._myNonObjectNonArrayProperty; } function CustomComponents$MyCustomType$set_myEnumProperty(value) { this._myEnumProperty = value; alert(“myEnumProperty was set to “ + value); } function CustomComponents$MyCustomType$get_myEnumProperty() { return this._myEnumProperty; } CustomComponents.MyCustomType.prototype = { _myReadOnlyArrayProperty : [], _myObjectProperty : {}, set_myProperty : CustomComponents$MyCustomType$set_myProperty, get_myProperty : CustomComponents$MyCustomType$get_myProperty, set_myNonReadOnlyStringProperty : CustomComponents$MyCustomType$set_myNonReadOnlyStringProperty, get_myNonReadOnlyStringProperty : CustomComponents$MyCustomType$get_myNonReadOnlyStringProperty, set_myProperty2 : CustomComponents$MyCustomType$set_myProperty2, get_myProperty2 : CustomComponents$MyCustomType$get_myProperty2, set_myReferenceProperty : CustomComponents$MyCustomType$set_myReferenceProperty, get_myReferenceProperty : CustomComponents$MyCustomType$get_myReferenceProperty, set_myArrayProperty : CustomComponents$MyCustomType$set_myArrayProperty, get_myArrayProperty : CustomComponents$MyCustomType$get_myArrayProperty, set_myEnumProperty : CustomComponents$MyCustomType$set_myEnumProperty, get_myEnumProperty : CustomComponents$MyCustomType$get_myEnumProperty, get_myReadOnlyArrayProperty : CustomComponents$MyCustomType$get_myReadOnlyArrayProperty, get_myObjectProperty : CustomComponents$MyCustomType$get_myObjectProperty, get_myNonObjectNonArrayProperty : CustomComponents$MyCustomType$get_myNonObjectNonArrayProperty, add_myEvent : CustomComponents$MyCustomType$add_myEvent, remove_myEvent : CustomComponents$MyCustomType$remove_myEvent }
(continued)
1299
bapp01.indd 1299
8/20/07 8:58:21 PM
Appendix A: XML Script Listing A-11 (continued) CustomComponents.MyCustomType.registerClass(“CustomComponents.MyCustomType”, Sys.Component); CustomComponents.MyCustomType.descriptor = { properties : [{name : ‘myProperty’, type : null, isDomElement : true}, {name : ‘myNonReadOnlyStringProperty’, type : String}, {name : ‘myReferenceProperty’, type : CustomComponents.MyCustomType}, {name : ‘myProperty2’, type : CustomComponents.MyType2}, {name : ‘myArrayProperty’, type : Array}, {name : ‘myEnumProperty’, type : CustomComponents.MyEnumeration}, {name : ‘myReadOnlyArrayProperty’, type : Array, readOnly : true}, {name : ‘myObjectProperty’, type : Object, readOnly : true}, {name : ‘myNonObjectNonArrayProperty’, type : CustomComponents.MyType, readOnly : true}], events : [{name : “myEvent”}] } if(typeof(Sys)!==’undefined’) Sys.Application.notifyScriptLoaded();
Listing A-12 presents a page that uses these client classes in xml-script in a purely declarative fashion.
Listing A-12: A Page that Uses the Client Classes Defined in Listing A-11 in xml-script Untitled Page function myEventHandler (sender, eventArgs) { }
1300
bapp01.indd 1300
8/20/07 8:58:21 PM
Appendix A: XML Script value1
I’ll walk you through the implementation of these client classes (that is, Listing A-11) as we’re walking through the implementation of the initializeObject method, shown in Listing A-13.
Listing A-13: The initializeObject Method Sys.Preview.MarkupParser.initializeObject = function Sys$Preview$MarkupParser$initializeObject(instance, node, markupContext) { var td = Sys.Preview.TypeDescriptor.getTypeDescriptor(instance); if (!td) return null; var supportsBatchedUpdates = false; if ((instance.beginUpdate && instance.endUpdate && instance !==Sys.Application)) { supportsBatchedUpdates = true; instance.beginUpdate(); } var i, a; var attr, attrName; var propertyInfo, propertyName, propertyType, propertyValue; var eventInfo, eventValue; var setter, getter; var properties = td._getProperties(); var events = td._getEvents(); var attributes = node.attributes;
Appendix A: XML Script else { eventInfo = events[attrName]; if (eventInfo) { var handler = Function.parse(attr.nodeValue); if (handler) { eventValue = instance[‘add_’ + eventInfo.name]; if (eventValue) eventValue.apply(instance, [handler]); else throw Error.invalidOperation(String.format( “The event ‘{0}’ is specified in the type descriptor, but add_{0} was not found.”, eventInfo.name)); } } else throw Error.invalidOperation( String.format(‘Unrecognized attribute “{0}” on object of type “{1}”’, attrName, Object.getTypeName(instance))); } } } var childNodes = node.childNodes; if (childNodes && (childNodes.length ! =0)) { for (i = childNodes.length - 1; i >= 0; i--) { var childNode = childNodes[i]; if (childNode.nodeType != 1) continue; var nodeName = Sys.Preview.MarkupParser.getNodeName(childNode); propertyInfo = properties[nodeName]; if (propertyInfo) { propertyName = propertyInfo.name; propertyType = propertyInfo.type; if (propertyInfo.readOnly) { getter = instance[‘get_’ + propertyName]; var nestedObject = getter.call(instance); if (propertyType === Array) { if (childNode.childNodes.length) { var items = Sys.Preview.MarkupParser.parseNodes(childNode.childNodes, markupContext); for (var itemIndex = 0; itemIndex < items.length; itemIndex++) { var item = items[itemIndex]; if(typeof(nestedObject.add) === “function”) nestedObject.add(item);
(continued)
1303
bapp01.indd 1303
8/20/07 8:58:22 PM
Appendix A: XML Script Listing A-13 (continued) else { Array.add(nestedObject, item); if(typeof(item.setOwner) === “function”) item.setOwner(instance); } } } } else if (propertyType === Object) { attributes = childNode.attributes; for (a = attributes.length - 1; a >= 0; a--) { attr = attributes[a]; nestedObject[attr.nodeName] = attr.nodeValue; } } else Sys.Preview.MarkupParser.initializeObject(nestedObject, childNode, markupContext); } else { propertyValue = null; if (propertyType == String) propertyValue = childNode.text; else if (childNode.childNodes.length != 0) { var valueNode; for (var childNodeIndex = 0; childNodeIndex < childNode.childNodes.length; childNodeIndex++) { if (childNode.childNodes[childNodeIndex].nodeType != 1) continue; valueNode = childNode.childNodes[childNodeIndex]; break; } if (valueNode) propertyValue = Sys.Preview.MarkupParser.parseNode(valueNode, markupContext); } if (propertyValue) { setter = instance[‘set_’ + propertyName]; setter.call(instance, propertyValue); } } }
1304
bapp01.indd 1304
8/20/07 8:58:23 PM
Appendix A: XML Script else { eventInfo = events[nodeName]; if (eventInfo) { var actions = Sys.Preview.MarkupParser.parseNodes(childNode.childNodes, markupContext); if (actions.length) { eventValue = instance[“add_” + eventInfo.name]; if(eventValue) { for (var e = 0; e < actions.length; e++) { var action = actions[e]; action.set_eventName(eventInfo.name); action.set_eventSource(instance); } } else throw Error.invalidOperation(String.format( “The event ‘{0}’ is specified in the type descriptor, but add_{0} was not found.”, eventInfo.name)); } } else { var type = null; var upperName = nodeName.toUpperCase(); if(upperName === ‘BINDINGS’) type = Sys.Preview.BindingBase; else if(upperName === ‘BEHAVIORS’) type = Sys.UI.Behavior; if(type) { if (childNode.childNodes.length) { var items = Sys.Preview.MarkupParser.parseNodes(childNode.childNodes, markupContext); for (var itemIndex = 0; itemIndex < items.length; itemIndex++) { var item = items[itemIndex]; debug.assert(type.isInstanceOfType(item), String.format(“The ‘{0}’ element may only contain child elements of type ‘{1}’.”, nodeName, type.getName())); if(typeof(item.setOwner) === “function”) item.setOwner(instance); } } }
(continued)
1305
bapp01.indd 1305
8/20/07 8:58:23 PM
Appendix A: XML Script Listing A-13 (continued) else throw Error.invalidOperation(String.format( ‘Unrecognized child node “{0}” on object of type “{1}”’, nodeName, Object.getTypeName(instance))); } } } } if (supportsBatchedUpdates) markupContext.addEndUpdate(instance); return instance; }
As you can see from Listing A-13, the initializeObject method begins by invoking the getTypeDescriptor static method on the TypeDescriptor class, passing in the reference to the ASP.NET AJAX object being initialized. This method returns a reference to the type descriptor object that describes the type of the ASP.NET AJAX object being initialized. var td = Sys.Preview.TypeDescriptor.getTypeDescriptor(instance);
Next, the initializeObject method invokes the getProperties method on the type descriptor object to return a dictionary that contains the complete information about the properties of the ASP.NET AJAX object being initialized: var properties = td._getProperties();
Next, the initializeObject method invokes the getEvents method on the type descriptor object to return a dictionary that contains the complete information about the events of the ASP.NET AJAX object being initialized: var events = td._getEvents();
Then the method accesses the attributes collection of the xml-script node referenced by the second parameter of the method. (Recall that this xml-script node represents the ASP.NET AJAX object being initialized.) The attributes collection contains one attribute node for each attribute on this xml-script node: var attributes = node.attributes;
Next, the initializeObject method iterates through the attribute nodes in the attributes collection and performs several tasks for each enumerated attribute node. First, the initializeObject method accesses the name of the attribute that the attribute node represents: attr = attributes[a]; attrName = attr.nodeName;
1306
bapp01.indd 1306
8/20/07 8:58:23 PM
Appendix A: XML Script The initializeObject method ignores the id attribute if the ASP.NET AJAX object being initialized is a client control. Recall from Listing A-10 that the parseFromMarkup method of the Control class has already taken care of the id attribute: if(attrName === “id” && Sys.UI.Control.isInstanceOfType(instance)) continue;
The method then uses the attribute name as an index into the properties collection, to return a reference to the property info object that contains the complete information about the property with the same name as the attribute. Recall that the properties collection is the return value of the call into the _getProperties method: propertyInfo = properties[attrName];
If the properties collection does contain a property with the same name as the attribute, the initializeObject method accesses a reference to the constructor of the type of the property: propertyType = propertyInfo.type;
It then accesses the attribute value: propertyValue = attr.nodeValue;
If the property references a JavaScript object, or an instance of the ASP.NET AJAX Component class, or an instance of the ASP.NET AJAX class that derives from the ASP.NET AJAX Component class, the initializeObject method invokes the addReference method on the current MarkupContext to add a reference for this property to the _ pendingReferences collection of the current MarkupContext. Recall that this collection contains one JavaScript object literal for each property that references another component. This JavaScript object literal exposes three properties: the first references the object that owns the property (which is the object being initialized), the second references the property info object that represents the property, and the last is the attribute value, which will be used to evaluate the property value. Recall that the actual evaluation takes place when the close method is invoked on the current MarkupContext. This is to ensure that the object being referenced is instantiated and initialized before it is referenced: if (propertyType && (propertyType === Object || propertyType === Sys.Component || propertyType.inheritsFrom(Sys.Component))) markupContext.addReference(instance, propertyInfo, propertyValue);
Next, I’ll present an example of this case. As Listing A-11 shows, the MyCustomType class exposes a property named myReferenceProperty that references another MyCustomType component in the current application: function CustomComponents$MyCustomType$set_myReferenceProperty(value) { this._myReferenceProperty = value; alert(“myReferenceProperty was set to the component with the id value of “ + value.get_id()); }
1307
bapp01.indd 1307
8/20/07 8:58:23 PM
Appendix A: XML Script Note that the setter method associated with this property pops up an alert that displays the new value of the property. As Listing A-11 shows, the value of the properties property of the descriptor static property of the MyCustomType contains the object literal shown in the boldface portion of the following code fragment, where the value of the type property of this object literal references the constructor of the MyCustomType type: CustomComponents.MyCustomType.descriptor = { properties : [. . . {name : ‘myReferenceProperty’, type : CustomComponents.MyCustomType}, . . . ], . . . }
This object literal tells the initializeObject method that the myReferenceProperty property of the MyCustomType object references another MyCustomType object in the current application. As Listing A-12 shows, this enables you to use the boldface declarative syntax shown in the following code fragment to specify the value of this property in xml-script if the value of the myReferenceProperty attribute on the element with an id property value of myCustomType1 is set to the value of the id property of the element with an id property value of myCustomType2: . . .
Now back to the implementation of the initializeObject method. If the property references a DOM element, the initializeObject invokes the findElement method on the current MarkupContext, passing in the attribute value to return a reference to the DOM element that will be used as the value of the property: if (propertyInfo.isDomElement || propertyType === Sys.UI.DomElement) propertyValue = markupContext.findElement(propertyValue);
Listing A-11 shows an example of this case, in which the MyCustomType component exposes a property named myProperty that references a DOM element. As you can see from this code listing, the value of the properties property of the descriptor property of the MyCustomType component contains an object literal, shown in the boldface portion of the following excerpt from this code listing: CustomComponents.MyCustomType.descriptor = { properties : [ {name : ‘myProperty’, type : null, isDomElement : true}, . . . ], . . . }
This enables you to declaratively specify the value of the myProperty property by declaring an attribute named myProperty on an xml-script node in xml-script, and setting the value
1308
bapp01.indd 1308
8/20/07 8:58:24 PM
Appendix A: XML Script of this attribute to the id HTML attribute value of the DOM element that the myProperty property is supposed to reference, as shown in the boldface portion of the following excerpt from Listing A-12: . . . . . .
Since the descriptor static property of the MyCustomType ASP.NET AJAX type specifies true as the value of the isDomElement property, the initializeObject method automatically passes the value of the myProperty attribute into the findElement method to return a reference to the referenced DOM element, which is the actual value of the myProperty property. Now back to the implementation of the initializeObject method. If the property is a JavaScript array, the initializeObject generates a string that encloses the attribute value within square brackets and parses this string into a JavaScript array, which will be used as the value of the property: if (propertyType === Array) propertyValue = Array.parse(‘[‘ + propertyValue + ‘]’);
Listing A-11 also shows an example of this case, in which MyCustomType exposes a property of type Array named myArrayProperty. Note that the properties property of the descriptor static property of MyCustomType contains the object literal shown in the boldface portion of the following excerpt from Listing A-11: CustomComponents.MyCustomType.descriptor = { properties : [. . . , {name : ‘myArrayProperty’, type : Array}, . . . ], . . . }
This enables you to declaratively specify the value of the myArrayProperty property by declaring in xml-script an attribute named myArrayProperty on the xml-script node and setting the value of this attribute to a comma-separated list of values, as shown in the boldface portion of the following excerpt from Listing A-12:
1309
bapp01.indd 1309
8/20/07 8:58:24 PM
Appendix A: XML Script This excerpt sets the value of the myArrayProperty attribute on the xml-script node to a comma-separated list of two values. Since the descriptor static property of MyCustomType specifies Array as the type of the myArrayProperty property, the initializeObject method automatically encloses the preceding comma-separated list of values in square brackets and passes the result into the parse method of the Array class to parse the list into a valid JavaScript array, to arrive at the actual value of the myArrayProperty property. Now back to the implementation of the initializeObject method. If the property is not a string, the initializeObject method checks whether the property is an enumeration. If so, it parses the attribute value into the appropriate enumeration value, which will be used as the value of the property. if(Type.isEnum(propertyType)) propertyValue = propertyType.parse(propertyValue, true);
Next, we’ll look at the portions of Listings A-11 and A-12 that cover this case. As Listing A-11 shows, MyCustomType exposes a property of type MyEnumeration named myEnumProperty, which has three possible values named EnumValue1, EnumValue2, and EnumValue3. Notice that the properties property of the descriptor static property of MyCustomType contains an object literal with the type value of CustomComponents.MyEnumeration, as shown in the boldface portion of the following excerpt from Listing A-11: CustomComponents.MyCustomType.descriptor = { properties : [. . . , {name : ‘myEnumProperty’, type : CustomComponents.MyEnumeration}, . . . ], . . . }
This enables you to declaratively specify the value of the myEnumProperty property by declaring in xml-script an attribute named myEnumProperty on the xml-script node and setting the value of this attribute to one of the possible values of the MyEnumeration — that is, EnumValue1, EnumValue2, or EnumValue3 — without having to specify the complete name of the value, as shown in the boldface portion of the following excerpt from Listing A-12. The complete name is prefixed by CustomComponents.MyEnumeration.
This example sets the value of the myEnumProperty attribute on the xml-script node to the enumeration value of EnumValue2 without your having to specify the complete name of the enumeration value, MyNamespace.MyEnumeration.MyEnumValue2. Since the descriptor static property of MyCustomType specifies CustomComponents.MyEnumeration as the type of the myEnumProperty property, the initializeObject method automatically calls the parse method to parse this attribute value to the actual MyNamespace.MyEnumeration.MyEnumValue2 enumeration value. Now back to the implementation of the initializeObject method. If the property is not an enumeration, the initializeObject method simply invokes the parse static method on the type of the
1310
bapp01.indd 1310
8/20/07 8:58:24 PM
Appendix A: XML Script property to parse the attribute value, which will be used as the value of the property. In other words, initializeObject assumes that the parse static method of this type knows how to parse this attribute value to the type that the property expects. else propertyValue = propertyType.parse(propertyValue);
Next, I’ll take a look at an example of this case. As you can see from Listing A-11, MyCustomType features a property named myProperty2: function CustomComponents$MyCustomType$set_myProperty2(value) { this._myProperty2 = value; alert(“myProperty2 was set to “ + value); }
As you can see from the boldface portion of the following excerpt from Listing A-11, the myProperty2 is of type CustomComponents.MyType2: CustomComponents.MyCustomType.descriptor = { properties : [. . . , {name : ‘myProperty2’, type : CustomComponents.MyType2}, . . . ], . . . }
As Listing A-11 shows, CustomComponents.MyType2 exposes the following parse static method, which parses the specified value into a CustomComponents.MyType2 object and returns this object to its caller (the caller in our case being the initializeObject method): CustomComponents.MyType2.parse = function (value) { var params = value.split(‘,’); alert(“Instantiating a MyType2 object and initializing it with “ + params); return new CustomComponents.MyType2(params[0], params[1], params[2]); }
This is a powerful technique that you can use in your own client code to enable page developers to instantiate instances of your custom client classes from xml-script in a purely declarative fashion, as you can from the boldface portion of the following excerpt from Listing A-12. Here the page developer uses a declarative approach to instantiate an instance of CustomComponents.MyType2 and to assign this instance to the myProperty2 property of the specified MyCustomType component:
1311
bapp01.indd 1311
8/20/07 8:58:25 PM
Appendix A: XML Script Now back to the implementation of the initializeObject method. Now that the property’s value has been determined, it’s time to assign this value to the property. The initializeObject method takes several steps to accomplish this.
❑
First, it accesses the property name: propertyName = propertyInfo.name;
❑
Then it generates a string that contains the name of the setter method for the property and uses this string as an index into the object being initialized to return a reference to this setter method: setter = instance[‘set_’ + propertyName];
❑
Finally, it invokes the call method on this reference to set the value of the property to the specified value: setter.call(instance, propertyValue);
As you can see, the initializeObject method expects the getter and setter methods associated with a given property to follow these naming conventions: get_PropertyName set_PropertyName PropertyName stands for the name of the property. Following these naming conventions will enable page developers to declare an attribute with the same name as the property on the xml-script node that represents an instance of your custom type in xml-script, and to assign the appropriate value to this attribute and rest assured that the initializeObject method will automatically invoke the underlying setter method to assign the specified value to the property.
Your custom ASP.NET AJAX type must explicitly describe its properties in the value of the properties property of its descriptor static property, as you saw in the previous examples. It’s very important to realize that the initializeObject method does not pick up the property information, such as name and type, from the prototype property of your custom type. Such information is picked up from the descriptor property. If you do not add object literals describing your properties to the value of the properties property of the descriptor property of your custom type, the initializeObject will have no way of knowing that your type exposes those properties. As we discussed earlier, another approach is to have your type implement the ICustomTypeProvider interface to return a type descriptor that describes these properties. If the properties collection does not contain a property with the same name as the attribute, the initializeObject method uses the attribute name as an index into the events collection to return a reference to the event info object that contains the complete information about the event with the same name as the attribute. Recall that the events collection is the return value of the call into the _getEvents method: eventInfo = events[attrName];
1312
bapp01.indd 1312
8/20/07 8:58:25 PM
Appendix A: XML Script If the events collection does indeed contain an event with the same name as the attribute, the initializeObject method performs the following tasks:
❑
First, it invokes the parse static method on the Function class, passing in the attribute value to return a reference to the event handler being registered. As you can see, the initializeObject method assumes that the value assigned to the attribute is the name of the event handler being registered for the event with the same name as the attribute name: var handler = Function.parse(attr.nodeValue);
❑
Next, it generates a string that contains the name of the method that registers event handlers for the event with the specified name, and uses this string as an index into the object being initialized in order to return a reference to this method: eventValue = instance[‘add_’ + eventInfo.name];
❑
Then the initializeObject method calls the apply method on this reference to invoke the method and consequently to register the specified event handler for the specified event of the object being initialized: eventValue.apply(instance, [handler]);
As you can see, the initializeObject method expects the methods of your custom ASP.NET AJAX type that register event handlers for events with specified names to follow this naming convention: add_EventName
EventName stands for the name of the event. Following this naming convention will enable page developers to declare an attribute with the same name as the event on the xml-script node that represents an instance of your custom type in xml-script, and to assign the name of the desired event handler to this attribute and rest assured that the initializeObject method will automatically invoke the underlying add method to register the specified event handler for the event with the specified name. For example, as you can see from Listing A-11, MyCustomType exposes a method named add_myEvent: function CustomComponents$MyCustomType$add_myEvent(eventHandler) { this.get_events().addHandler(“myEvent”, eventHandler); alert(eventHandler + “ \n\nwas registered as event handler for myEvent event!”); }
Notice that the value of the events property of the descriptor property of MyCustomType includes the object literal shown in the boldface portion of the following excerpt from Listing A-11: CustomComponents.MyCustomType.descriptor = { . . . events : [ {name : “myEvent”} ] }
1313
bapp01.indd 1313
8/20/07 8:58:25 PM
Appendix A: XML Script This object literal tells the initializeObject method that the attribute named myEvent contains the name of an event handler that must be registered for the myEvent event of the specified MyCustomType object. This enables the page developer to register an event handler such as myEventHandler in a purely declarative fashion in xml-script, as shown in the boldface portion of the following excerpt from Listing A-12:
When the initializeObject method encounters this boldface portion, it automatically calls the parse method to return a reference to the myEventHandler JavaScript function: var refTomyEventHandler = Function.parse(“myEventHandler”);
It then creates the “add_myEvent” string and uses it as an index to return a reference to the add_myEvent method of your custom type: var refToadd_myEvent = instance[“add_” + “myEvent”];
It then calls the apply method on the refToadd_myEvent reference to invoke the add_myEvent method of MyCustomType to register the myEventHandler JavaScript function for myEvent event: refToadd_MyEvent.apply(instance, [refTomyEventHandler]);
Again, it’s very important to realize that the initializeObject method does not pick up the event information from the prototype property of your custom type. That information is picked up from the descriptor property. If you do not describe the events of your custom type in the events property of the descriptor property of your custom type, the initializeObject will have no way of knowing that your type exposes those events. If neither the properties nor the events collection contains an entry with the same name as the attribute, the initializeObject method raises an exception because the specified attribute on the xmlscript node referenced by the second parameter of the initializeObject method is unrecognized. else throw Error.invalidOperation( String.format(‘Unrecognized attribute “{0}” on object of type “{1}”’, attrName, Object.getTypeName(instance)));
As you can see, the xml-script does not support expando or custom attributes. Every attribute on an xml-script node that represents an ASP.NET AJAX object must map into either a property or an event of the ASP.NET AJAX object with the same name as the attribute. Next, the initializeObject method accesses the collection that contains the child nodes of the xmlscript node referenced by the second parameter of the initializeObject method. Recall that this xml-script node represents the ASP.NET AJAX object being initialized: var childNodes = node.childNodes;
1314
bapp01.indd 1314
8/20/07 8:58:26 PM
Appendix A: XML Script Next, the initialize method iterates through these child xml-script nodes and performs several tasks for each enumerated child xml-script node. First, the initialize method ignores the child xml-script node if the node is not an element node: var childNode = childNodes[i]; if (childNode.nodeType ! =1) continue;
Next, it invokes the getNodeName static method on the MarkupParser class, passing in the child xml-script node to access the name of the node: var nodeName = Sys.Preview.MarkupParser.getNodeName(childNode);
The initialize method then uses the node name as an index into the properties collection to return a reference to the property info object that contains the complete information about the property with the same name as the child xml-script node. Recall that the properties collection is the return value of the call into the _getProperties method: propertyInfo = properties[nodeName];
If the properties collection contains a property with the same name as the child xml-script node, this is an indication that this child xml-script node represents this property. This means that the attributes and child nodes of this child xml-script node are there to specify the value of this property. Therefore, the value of this property must be an object. In other words, this property references a nested object. This is very similar to what is known in object-oriented programming as object composition, wherein one object composes or encapsulates another object. In this case, the object that owns the property encapsulates or composes the object referenced by the property. The initializeObject method performs the following tasks to initialize this property:
❑
Accesses the name of the property: propertyName = propertyInfo.name;
❑
Accesses the Type object that represents the type of the property — that is, the type of the object represented by the property, or the type of the nested or composed object: propertyType = propertyInfo.type;
If the property is read-only, the initializeObject takes the following steps. First, it generates a string that contains the name of the getter method that gets the value of the property, and uses this string as an index into the object being initialized (which is the object that owns the property), to return a reference to this getter method: getter = instance[‘get_’ + propertyName];
Next, it invokes the call method on this reference to invoke this getter method and to return the value of the property, which is the object encapsulated by the object that owns the property: var nestedObject = getter.call(instance);
1315
bapp01.indd 1315
8/20/07 8:58:26 PM
Appendix A: XML Script What happens next depends on the type of the property. If the property is a JavaScript array, the initializeObject method invokes the parseNodes static method on the MarkupParser class to parse the child xml-script nodes of the current child xml-script node: var items = Sys.Preview.MarkupParser.parseNodes(childNode.childNodes, markupContext);
As we discussed earlier, the parseNodes method parses the specified xml-script nodes into their associated ASP.NET AJAX objects and returns a collection that contains these parsed objects. The initializeObject method then adds each parsed object to the property. Recall that the property is a JavaScript array: for (var itemIndex = 0; itemIndex < items.length; itemIndex++) { var item = items[itemIndex]; if(typeof(nestedObject.add) === “function”) nestedObject.add(item); else { Array.add(nestedObject, item); if(typeof(item.setOwner) === “function”) item.setOwner(instance); } }
For example, MyCustomType, shown in Listing A-11, exposes a property of type Array named myReadOnlyArrayProperty: function CustomComponents$MyCustomType$get_myReadOnlyArrayProperty() { alert(“The value of myReadOnlyArrayProperty is being retrieved!”); return this._myReadOnlyArrayProperty; }
As the boldface portion of the following excerpt from Listing A-11 shows, the value of the properties property of the descriptor static property of MyCustomType contains an object literal that contains metadata information about the myReadOnlyArrayProperty property: CustomComponents.MyCustomType.descriptor = { properties : [. . . {name : ‘myReadOnlyArrayProperty’, type : Array, readOnly : true}, . . . ], . . . }
This enables you to declaratively specify the value of the myReadOnlyArrayProperty property in xml-script by declaring an xml-script node named myReadOnlyArrayProperty as the child node
1316
bapp01.indd 1316
8/20/07 8:58:26 PM
Appendix A: XML Script of the xml-script node, which contains a bunch of child nodes. each of these nodes represents an item in the myReadOnlyArrayProperty array property, as shown in the boldface portion of the following excerpt from Listing A-12: . . .
As you can see, each child node of a read-only array property such as myReadOnlyArrayProperty has its own attributes and child nodes. For example, each child node has its own myTypeProperty attribute. That is why the initializeObject method invokes the parseNodes method and passes all these child nodes into it to parse them into the appropriate ASP.NET AJAX objects. In our case, the parseNodes method will parse the child nodes into instances of the CustomComponents.MyType client class. Now back to the implementation of the initializeObject method. If the property is not a JavaScript array, the initializeObject checks whether the property is a JavaScript object. If so, it first accesses the attributes collection of the child xml-script node. This collection contains one attribute node for each attribute on the child xml-script node. Then it uses the attribute name as an index into the JavaScript object to access the property of the object with the same name as the attribute, and assigns the attribute value as the value of this property: else if (propertyType === Object) { attributes = childNode.attributes; for (a = attributes.length - 1; a > =0; a--) { attr = attributes[a]; nestedObject[attr.nodeName] = attr.nodeValue; } }
Now let’s take a look at an example before we continue with the implementation of the initializeObject method. As Listing A-11 shows, MyCustomType exposes a property named myObjectProperty with the following associated getter method: function CustomComponents$MyCustomType$get_myObjectProperty() { alert(“The value of myObjectProperty is being retrieved!”); return this._myObjectProperty; }
1317
bapp01.indd 1317
8/20/07 8:58:26 PM
Appendix A: XML Script As you can see from the boldface portion of the following excerpt from Listing A-12, the descriptor static property of MyCustomType describes this property as a read-only property of type Object: CustomComponents.MyCustomType.descriptor = { properties : [. . . , {name : ‘myObjectProperty’, type : Object, readOnly : true},. . . ], . . . }
This enables you to specify the value of the myObjectProperty property by declaring a xml-script node as the child node of the xml-script node and setting its myObjectPropertyProperty1 and myObjectPropertyProperty2 properties as the attributes with the same names on the xml-script node, as shown in the boldface portion of the following excerpt from Listing A-12: . . . . . .
In this case, the initializeObject method takes the following steps.
❑
First, it generates the string that contains the name of the getter method — that is, the string “get_myObjectProperty”. Next, it will use this string as an index into the ASP.NET AJAX object that represents the xml-script node, in order to return a reference to the get_myObjectProperty getter method:
var refToget_myObjectPropertyMethod = instance[‘get_myObjectProperty’];
❑
Next, it will invoke the call method on refToget_myObjectPropertyMethod to invoke this method and consequently to return a reference to the object that the myObjectProperty property references — that is, the nested or composed object:
var nestedObject = refToget_myObjectPropertyMethod.call(instance);
❑
Then it uses ‘myObjectPropertyProperty1’ and ‘myObjectPropertyProperty2’ as indexes into the nestedObject, and assigns ‘value1’ and ‘value2’:
Now back to the implementation of the initializeObject method. If the property is neither a JavaScript array nor a JavaScript Object, the initializeObject method invokes the initializeObject method once again to initialize this property. As you can see, initializeObject is a recursive method.
1318
bapp01.indd 1318
8/20/07 8:58:27 PM
Appendix A: XML Script else Sys.Preview.MarkupParser.initializeObject(nestedObject, childNode, markupContext);
Here is an example of this case. As you can see from Listing A-11, MyCustomType features a property named myNonObjectNonArrayProperty with the following associated getter method: function CustomComponents$MyCustomType$get_myNonObjectNonArrayProperty() { alert(“The value of myNonObjectNonArrayProperty is being retrieved!”); if (!this._myNonObjectNonArrayProperty) this._myNonObjectNonArrayProperty = new CustomComponents.MyType(); return this._myNonObjectNonArrayProperty; }
Notice that the value of the properties property of the descriptor static property of MyCustomType contains the object literal, which is shown in the boldface portion of the following excerpt from Listing A-11: CustomComponents.MyCustomType.descriptor = { properties : [ . . . , {name : ‘myNonObjectNonArrayProperty’, type : CustomComponents.MyType, readOnly : true} . . . ], . . . }
This object literal describes myNonObjectNonArrayProperty as a read-only property of type CustomComponents.MyType, which is neither an Array nor an Object. As the boldface portion of the following excerpt from Listing A-12 shows, you can specify the value of the myNonObjectNonArrayProperty property by declaring a myNonObjectNonArrayProperty xml-script node as the child node of the xml-script node: . . .
Note that the xml-script node that represents a non-object, non-array property in xml-script may have its own attributes and child xml-script nodes. For example, the xml-script node in the preceding xml-script fragment contains an attribute named myTypeProperty, which maps to the myTypeProperty property of the CustomComponents.MyType object represented by this xml-script node. That is why the initializeObject method invokes the initializeObject method once again to have this method use these attributes and child nodes to initialize the CustomComponents.MyType object represented by the xml-script node. Now back to the implementation of the initializeObject method. If the property is not read-only, the initializeObject method assigns the value of the text property of the child xml-script node as the value of the property if the property is a string: propertyValue = null; if (propertyType == String) propertyValue = childNode.text;
1319
bapp01.indd 1319
8/20/07 8:58:27 PM
Appendix A: XML Script For example, MyCustomType shown in Listing A-11 features a property named myNonReadOnlyStringProperty with the following associated setter method: function CustomComponents$MyCustomType$set_myNonReadOnlyStringProperty(value) { this._myNonReadOnlyStringProperty = value; alert(“myNonReadOnlyStringProperty was set to “ + value); }
As the boldface portion of the following excerpt from Listing A-11 shows, the value of the properties property of the descriptor property of MyCustomType contains an object literal that describes myNonReadOnlyStringProperty as a non-read-only property of type String: CustomComponents.MyCustomType.descriptor = { properties : [. . . , {name : ‘myNonReadOnlyStringProperty’, type : String}, . . . ], . . . }
This enables you to specify the value of the myNonReadOnlyStringProperty property by declaring a xml-script node as the child node of the xml-script node and setting the content of this child node as shown in the boldface portion of the following excerpt from Listing A-12: . . . value1 . . .
Now back to the implementation of the initializeObject method. If the property is not a string, the method first searches the child xml-script nodes of the current xml-script node for the first child xml-script node, which is an element node: var valueNode; for (var childNodeIndex = 0; childNodeIndex < childNode.childNodes.length; childNodeIndex++) { if (childNode.childNodes[childNodeIndex].nodeType ! =1) continue; valueNode = childNode.childNodes[childNodeIndex]; break; }
Then it invokes the parseNode method to parse this element node. if (valueNode) propertyValue = Sys.Preview.MarkupParser.parseNode(valueNode, markupContext);
1320
bapp01.indd 1320
8/20/07 8:58:27 PM
Appendix A: XML Script As we discussed earlier, the parseNode method parses the specified xml-script node into its associated ASP.NET AJAX object and returns this object. Now that we know the value of the property, we need to assign this value to the property. The intializeObject method first generates a string that contains the name of the setter method for this property and uses this string as an index into the object being initialized to return a reference to this setter method: setter = instance[‘set_’ + propertyName];
Next, it invokes the call method on this reference to invoke the setter method and consequently to assign the specified value as the value of the property: setter.call(instance, propertyValue);
If the properties collection does not contain a property with the same name as the child xml-script node, the initializeObject method uses the child xml-script node’s name as an index into the events collection, in order to return a reference to the event info object that provides complete information about the event with the same name as the child xml-script node: eventInfo = events[nodeName];
If the events collection does contain an event with the same name as the child xml-script node, the initializeObject method performs the following tasks:
❑
Invokes the parseNodes static method on the MarkupParser class to parse the child xml-script nodes of this child xml-script node: var actions = Sys.Preview.MarkupParser.parseNodes(childNode.childNodes, markupContext);
The parseNodes method parses the specified xml-script nodes to their associated ASP.NET AJAX objects and returns a collection that contains these parsed objects. These objects in this case are instances of an ASP.NET AJAX class named Action or one of its subclasses. (I’ll discuss the Action class and its subclasses in Appendix C.)
❑
Generates a string that contains the name of the method that registers an event handler for the specified event, and uses this string as an index into the object being initialized to return a reference to this method: eventValue = instance[“add_” + eventInfo.name];
❑
If the object being initialized does contain such a method, the initializeObject performs the following tasks for each parsed object in the collection of parsed objects returned from the parseNodes method. (Recall that each parsed object is an instance of the Action ASP.NET AJAX class or one of its subclasses.)
❑
First, the initializeObject method calls the set_eventName method on the enumerated parsed object or action to set the value of the eventName property of the parsed object to the specified event name. Recall that the Action ASP.NET AJAX class exposes a property named eventName.
1321
bapp01.indd 1321
8/20/07 8:58:28 PM
Appendix A: XML Script ❑
Next, the initializeObject method calls the set_eventSource method on the enumerated parsed object or action to set the value of the eventSource property of the parsed object or action to the object being initialized. In other words, this tells this action that the object being initialized is the source of the event with the specified name. if(eventValue) { for (var e = 0; e < actions.length; e++) { var action = actions[e]; action.set_eventName(eventInfo.name); action.set_eventSource(instance); } }
❑
If neither the properties nor the events collection contains an entry with the same name as the child xml-script node, the initializeObject method takes the following steps:
❑
Calls the toUpperCase method to convert lowercase characters of the child xml-script node’s name to uppercase: var type = null; var upperName = nodeName.toUpperCase();
❑
If the child xml-script node’s name is BINDINGS, sets a local variable named type to reference the constructor of the Sys.Preview.BindingBase class. (I’ll discuss ASP.NET AJAX binding in Appendix B.) if(upperName === ‘BINDINGS’) type = Sys.Preview.BindingBase;
❑
If the child xml-script node’s name is BEHAVIORS, sets the type local variable to reference the constructor of the Sys.UI.Behavior class: else if(upperName === ‘BEHAVIORS’) type = Sys.UI.Behavior;
❑
If the type local variable is not null — that is, if it references the constructor of either the BindingBase or the Behavior class, the initializeObject method first invokes the parseNodes static method on the MarkupParser class to parse the child xml-script nodes of the child xml-script node to their associated ASP.NET AJAX objects. Then it returns a collection that contains these parsed objects. var items = Sys.Preview.MarkupParser.parseNodes(childNode.childNodes, markupContext);
❑
If the child xml-script node’s name is BEHAVIORS, these parsed objects are instances of the Behavior ASP.NET AJAX class or its sub-classes. If the child xml-script node’s name is BINDINGS, these parsed objects are instances of the BindingBase ASP.NET AJAX class or its subclasses.
1322
bapp01.indd 1322
8/20/07 8:58:28 PM
Appendix A: XML Script ❑
Next, the initializeObject method iterates through the parsed objects in the collection returned from the call into the parseNodes method and takes the following steps for each enumerated parsed object. As just mentioned, each enumerated parsed object is either a behavior or a binding object. First, the method checks whether the enumerated parsed object supports a method named setOwner. If so, it invokes this method on the enumerated parsed object, passing in the reference to the object being initialized. This specifies the object being initialized as the owner of the behavior or binding object. for (var itemIndex = 0; itemIndex < items.length; itemIndex++) { var item = items[itemIndex]; debug.assert(type.isInstanceOfType(item), String.format(“The ‘{0}’ element may only contain child elements of type ‘{1}’.”, nodeName, type.getName())); if(typeof(item.setOwner) === “function”) item.setOwner(instance); }
❑
If the type local variable is null — that is, if the child xml-script node does not represent BindingBase or Behaviors, the initializeObject raises an exception because the child xml-script node is not recognized:
else throw Error.invalidOperation( String.format(‘Unrecognized child node “{0}” on object of type “{1}”’, nodeName, Object.getTypeName(instance)));
1323
bapp01.indd 1323
8/20/07 8:58:28 PM
bapp01.indd 1324
8/20/07 8:58:29 PM
Binding The best way to understand what a binding is and what it does is to use it in an example. Listing B-1 contains a page that binds the text property of the Label ASP.NET AJAX client control with an id property value of span1 to the text property of the TextBox ASP.NET AJAX client control with an id property value of text1. Thanks to this binding, every time you enter a different value in the text box, the span element associated with the Label control will be automatically updated with the new value.
Listing B-1: A Page that Uses Binding Untitled Page
(continued)
bapp02.indd 1325
8/20/07 8:58:54 PM
Appendix B: Binding Listing B-1 (continued)
As this example shows, the ASP.NET AJAX binding enables you to bind a specified property of a specified ASP.NET AJAX object to a specified property of another ASP.NET AJAX object. Every time the value of the specified property of the latter ASP.NET AJAX object changes, the value of the specified property of the former ASP.NET AJAX object automatically changes as well. The latter ASP.NET AJAX object is known as the data context and its associated property is known as the data path. As Listing B-1 shows, the xml-script node that represents the Label ASP.NET AJAX client control contains a child node named . This makes it seem that the Label ASP.NET AJAX client control exposes a property named bindings, which is not true. Neither the Label ASP.NET AJAX client control nor its base classes exposes such a property. As a matter of fact, none of the ASP.NET AJAX client classes currently exposes the bindings property. The only exception to this rule is the Action class. Yet the only way to use the ASP.NET AJAX binding feature in xml-script is to declare a xmlscript node. The answer to this apparent contradiction lies in the initializeObject method shown in Listing A-11. Listing B-2 presents the portion of Listing A-11 (I’ve cleaned up Listing B-2 for presentation purposes) that parses the Bindings subelement of the xml-script node that represents an ASP.NET AJAX object in xml-script. Let’s study Listing B-2 in the context of the example shown in Listing B-1. When the initializeObject method is invoked to initialize the Label ASP.NET AJAX client control shown in Listing B-1, three parameters are passed into this method. The first parameter references the Label ASP.NET AJAX client control, and the second references the xml-script node that represents this Label ASP.NET AJAX client control in xml-script. As you can see from Listing B-2, if the name of the child node of the xml-script node is Bindings, the initializeObject method invokes the parseNodes method, passing in the child nodes of the node. Recall that the child nodes of the node are the nodes. The parseNodes method parses these nodes into instances of Binding ASP.NET AJAX class and uses the attributes on each element to set the associated properties of the associated Binding ASP.NET AJAX object. Note that the initializeObject method then iterates through these Binding ASP.NET AJAX objects and invokes the setOwner method on each object to specify the Label ASP.NET AJAX object as its owner.
1326
bapp02.indd 1326
8/20/07 8:58:55 PM
Appendix B: Binding Listing B-2: The Portion of Listing A-11 that Initializes a Binding Object Sys.Preview.MarkupParser.initializeObject = function Sys$Preview$MarkupParser$initializeObject(instance, node, markupContext) { var childNodes = node.childNodes; for (i = childNodes.length - 1; i >= 0; i--) { var childNode = childNodes[i]; var nodeName = Sys.Preview.MarkupParser.getNodeName(childNode); var upperName = nodeName.toUpperCase(); if(upperName === ‘BINDINGS’) { var bindings = Sys.Preview.MarkupParser.parseNodes(childNode.childNodes, markupContext); for (var bindingIndex = 0; bindingIndex < bindings.length; bindingIndex++) { var binding = bindings[bindingIndex]; binding.setOwner(instance); } } } }
BindingBase As you saw in the previous section, each subelement of the subelement binds a specified property of an ASP.NET AJAX object (also known as the owner) to the specified property of another ASP.NET AJAX object in xml-script. Recall from Listing B-2 that the parseNodes method parses each subelement of the subelement into an instance of an ASP.NET AJAX class named Binding. The Binding class derives from a base class named BindingBase. This means that if you’re not happy with the Binding class you can implement your own custom Binding class that derives from the BindingBase class. The BindingBase class derives from the Component base class: Sys.Preview.BindingBase.registerClass(‘Sys.Preview.BindingBase’, Sys.Component, Sys.IDisposable);
The following table presents the methods of the BindingBase class:
Method
Description
get_automatic
Gets a Boolean value that specifies whether the binding object should evaluate the binding automatically.
set_automatic
Sets a Boolean value that specifies whether the binding object should evaluate the binding automatically. (continued)
1327
bapp02.indd 1327
8/20/07 8:58:55 PM
Appendix B: Binding (continued)
Method
Description
get_dataContext
Gets the current data context. The data context references the ASP.NET AJAX object whose property the specified property of the ASP.NET AJAX object that owns the binding object binds to.
set_dataContext
Sets the current data context.
get_dataPath
Gets the data path. The data path contains the name of the property of the data context that the specified property of the ASP.NET AJAX object that owns the binding object binds to.
set_dataPath
Sets the data path.
get_target
Gets the binding target. The binding target references the ASP.NET AJAX object that owns the binding object.
set_target
Sets the binding target.
get_property
Gets the name of the property of the binding target that binds to the specified property of the data context.
set_property
Sets the name of the property of the binding target that binds to the specified property of the data context.
get_propertyKey
Gets the property key. The property key enables you to bind the subproperty of a property of a binding target to the specified property of the data context.
set_propertyKey
Sets the property key.
get_transformerArgument
Gets the transformer argument.
set_transformerArgument
Sets the transformer argument.
add_transform
Adds a new event handler to the list of event handlers registered for the transform event of the binding object. This event handler is known as the transformer. In other words, transformers are treated as event handlers registered for the transform event.
remove_transform
Removes an event handler from the list of event handlers registered for the transform event of the binding object. In other words, this method removes a transformer from the list of registered transformers.
dispose
Performs the final cleanup before the binding object is disposed of.
evaluate
Takes an enumeration parameter of type BindingDirection. The method delegates to the evaluateIn method if the value of this parameter is BindingDirection.In; otherwise it delegates to the evaluateOut method.
1328
bapp02.indd 1328
8/20/07 8:58:55 PM
Appendix B: Binding evaluateIn
This method retrieves the value of the data path from the data context and assigns it to the target property.
evaluateOut
The BindingBase class does not implement this method; it delegates the implementation to its subclasses.
initialize
Initializes the binding object. The BindingBase class inherits this method from the Component base class.
setOwner
Specifies the ASP.NET AJAX object that owns the binding object. The setOwner internally invokes the set_target method.
evaluate Listing B-3 presents the implementation of the evaluate method of the BindingBase class. As you can see, this method delegates to the evaluateIn method if the BindingDirection.In value is passed into it, and delegates to the evaluateOut method otherwise. The BindingDirection is an enumeration type with three possible values: In, Out, and InOut. As you can see, the evaluateOut method handles both the BindingDirection.Out and BindingDirection.InOut cases.
Listing B-3: The evaluate Method function Sys$Preview$BindingBase$evaluate(direction) { /// if (this._bindingExecuting) return; this._bindingExecuting = true; if (direction === Sys.Preview.BindingDirection.In) this.evaluateIn(); else this.evaluateOut(); this._bindingExecuting = false; }
evaluateIn As Listing B-4 shows, the evaluateIn method first invokes the getPropertyType static method on the TypeDescriptor class to return the type object that provides complete information about the type of the property whose value is being set. Recall that this is the property of the target ASP.NET AJAX object. var targetPropertyType = Sys.Preview.TypeDescriptor.getPropertyType(this._target, this._property, this._propertyKey);
1329
bapp02.indd 1329
8/20/07 8:58:56 PM
Appendix B: Binding Under the hood, the getPropertyType method extracts the required information about the target property from the descriptor static property of the target ASP.NET AJAX object (assuming that the target ASP.NET AJAX type does not implement the ICustomTypeProvider interface). As you can see, the evaluteIn method and consequently the whole ASP.NET AJAX binding infrastructure only supports target ASP.NET AJAX objects whose types expose a descriptor static property with an entry for the target property. For example, if we have a target ASP.NET AJAX type named MyNamespace.MyType with a property of type MyNamespace.MyPropertyType named myProperty, the MyNamespace.MyType type must expose a descriptor static property that has an entry for the myProperty property, as follows: MyNamespace.MyType.descriptor = { properties: [{name: “myProperty”, type: MyNamespace.MyPropertyType}] }
Next, the evaluateIn method invokes an internal method named _getSourceValue to retrieve the value of the source property to which the target property is bound: var value = this._getSourceValue(targetPropertyType);
Then, the evaluateIn method fires the transform event of the BindingBase class and consequently invokes the event handlers registered for this event. These event handlers are known as transformers because they’re used to transforme the source property value before it is assigned to the target property. As you can see, ASP.NET AJAX transformers are treated as event handlers. Note that the evaluateIn method instantiates an instance of BindingEventArgs, passing in four parameters. The first parameter is the value of the source property, the second is the enumeration value BindingDirection.In, the third is the reference to the constructor of the type of the property, and the fourth is the transformer argument. Note that the evaluateIn method passes this BindingEventArgs object into these event handlers. These event handlers or transformers can then invoke the following getters on this BindingEventArgs object to access the same parameters that the evaluateIn method passed into the BindingEventArgs object:
❑
get_value: Returns the source property value that the evaluateIn method passed into the BindingEventArgs object
❑
get_direction: Returns the BindingDirection.In value that the evaluateIn method passed into the BindingEventArgs object
❑
get_targetPropertyType: Returns the type object that the evaluateIn method passed into the BindingEventArgs object
❑
get_transformerArgument: Returns the transformer argument value that the evaluateIn method passed into the BindingEventArgs object
Note that BindingEventArgs also exposes a setter named set_value that the event handlers can optionally invoke to request the evaluateIn method to assign a value other than the original source property value to the target property.
1330
bapp02.indd 1330
8/20/07 8:58:56 PM
Appendix B: Binding Since the BindingEventArgs class derives from the CancelEventArgs base class, it inherits the set_cancel method from this class. The event handlers or transformers can optionally invoke the set_cancel method, passing in true as its argument, to request the evaluateIn method not to assign the source property value to the target property. This in effect cancels the binding. As Listing B-4 shows, when these event handlers finally return, the evaluateIn method first invokes the get_cancel method on the BindingEventArgs object to check whether any of the handlers or transformers has placed a request for the cancellation of the assignment of the source property value to the target property. If so, the evaluateIn method does not assign the source property value to the target property. If not, the evaluteIn method invokes the get_value method on the BindingEventArgs object to return the value that must be assigned to the target property. Recall that this value is different from the original source property value if any of the event handlers or transformers has invoked the set_value method on the BindingEventArgs object to specify a different value. Finally, the evaluateIn method invokes the setProperty static method on the TypeDescriptor class to set the value of the target property: Sys.Preview.TypeDescriptor.setProperty(this._target, this._property, value, this._propertyKey);
Listing B-4: The evaluateIn Method function Sys$Preview$BindingBase$evaluateIn() { var targetPropertyType = Sys.Preview.TypeDescriptor.getPropertyType(this._target, this._property, this._propertyKey); var value = this._getSourceValue(targetPropertyType); var canceled = false; var handler = this.get_events().getHandler(“transform”); if (handler) { var be = new Sys.Preview.BindingEventArgs(value, Sys.Preview.BindingDirection.In, targetPropertyType, this._transformerArgument); handler(this, be); canceled = be.get_cancel(); value = be.get_value(); } if (!canceled) Sys.Preview.TypeDescriptor.setProperty(this._target, this._property, value, this._propertyKey); }
1331
bapp02.indd 1331
8/20/07 8:58:56 PM
Appendix B: Binding
evalulateOut As you can see from the following code listing, the BindingBase class does not implement the evaluateOut method and delegates the responsibility of implementing this method to its subclasses. Recall that the evaluateOut method handles the BindingDirection.Out and BindingDirection.InOut cases. function Sys$Preview$BindingBase$evaluateOut() { throw Error.createError(‘evaluateOut is not supported for this binding’); }
initialize The BindingBase class overrides the initialize method that inherits from the Component base class, as shown in Listing B-5.
Listing B-5: The initialize Method function Sys$Preview$BindingBase$initialize() { Sys.Preview.BindingBase.callBaseMethod(this, ‘initialize’); this._source = this._dataContext; if (!this._source) this._source = this._target.get_dataContext(); if (this._dataPath && this._dataPath.indexOf(‘.’) > 0) this._dataPathParts = this._dataPath.split(‘.’); }
Recall that BindingBase exposes a property named dataContext that you can set to reference the source ASP.NET AJAX object. If this property has not been explicitly set, the initialize method invokes the get_dataContext method on the target ASP.NET AJAX object to use as the source ASP.NET AJAX object the current data context associated with the target. this._source = this._dataContext; if (!this._source) this._source = this._target.get_dataContext();
You’ll see an example of this case in Appendix F, where we’ll use a Binding object to bind the text property of a Label ASP.NET AJAX client control to the specified data field of data records in a data collection bound to the ListView client control that contains this Label ASP.NET AJAX client control. As you’ll see, this example will not explicitly specify the dataContext property of this Binding object. Thanks to the initialize method of the BindingBase class, the Binding object will pick up the current data context, which references the current data record of the data collection bound to the ListView control. This will enable us to display the specified data field of the current data record in this Label ASP.NET AJAX client control. Next, the initialize method splits the dataPath into its constituent parts: if (this._dataPath && this._dataPath.indexOf(‘.’) > 0) this._dataPathParts = this._dataPath.split(‘.’);
1332
bapp02.indd 1332
8/20/07 8:58:57 PM
Appendix B: Binding As you can see, if you assign a string that consists of a dot-separated list of names to the dataPath property of a Binding object, the initialize method treats each name in the list as a subproperty of the previous name in the list. Here is an example. Let’s say you have an ASP.NET AJAX type named CustomComponents.MyType that exposes a property of type CustomComponents.MyPropertyType named myProperty, where the CustomComponents.MyPropertyType type itself exposes two properties, mySubProperty1 and mySubProperty2. You can then use the following Binding object to bind the text property of a Label ASP.NET AJAX client control to the mySubProperty2 property of the myProperty property of an instance of the CustomComponents.MyPropertyType type: . . .
descriptor The descriptor static property of the BindingBase class specifies those properties, methods, and events of the class that the clients of the class such as the xml-script parser can access using the ASP.NET AJAX type inspection facilities. This means that you can use these properties, methods, and events only in xml-script. Sys.Preview.BindingBase.descriptor = { properties: [ {name: ‘target’, type: Object}, {name: ‘automatic’, type: Boolean}, {name: ‘dataContext’, type: Object}, {name: ‘dataPath’, type: String}, {name: ‘property’, type: String}, {name: ‘propertyKey’ }, {name: ‘transformerArgument’, type: String} ], methods: [ {name: ‘evaluateIn’} ], events: [ {name: ‘transform’} ] }
1333
bapp02.indd 1333
8/20/07 8:58:57 PM
Appendix B: Binding
Transformers As you saw from Listing B-4, a transformer is an event handler registered for the transform event of a given binding object: it transforms the source property value before the value is assigned to the target property. The BindingBase class exposes a method named add_transform that you can use from your client code to imperatively add a transformer. As you can see, writing a custom transformer is as easy as implementing a new event handler for the transform event. This event handler takes two parameters, the first referencing the binding object that raises the transform event and the second referencing an instance of the BindingEventArgs event data class that contains the event data for the transform event. As discussed earlier, you can use the methods of the BindingEventArgs event data class to access the event data. Listing B-6 contains a page that defines a new transformer. This transformer simply adds the transformer argument to the beginning of the source property value and displays a pop-up that contains the return values of the getter methods of the BindingEventArgs object.
Listing B-6: A Page that Defines a Custom Transformer Untitled Page function transformCallback(sender, e) { var builder = new Sys.StringBuilder(); builder.append(“old value: “); builder.append(e.get_value()); builder.appendLine(); builder.append(“direction: “); builder.append(e.get_direction()); builder.appendLine(); builder.append(“target property type: “); builder.append(e.get_targetPropertyType()); builder.appendLine(); builder.append(“transformer argument: “); builder.append(e.get_transformerArgument()); builder.appendLine(); e.set_value(e.get_transformerArgument()+e.get_value()); builder.append(“new value: “); builder.append(e.get_value()); alert(builder.toString()); }
1334
bapp02.indd 1334
8/20/07 8:58:57 PM
Appendix B: Binding
In the following sections I’ll discuss some of the standard built-in ASP.NET AJAX transformers.
ToString As you can see, the ToString transformer transforms the source property value into its string representation. You can optionally pass a format string as the value of the transformerArgument property. As the following code listing shows, the ToString transformer simply passes this format string into the format static method of the String class as its first argument and the source property value as its second argument. Sys.Preview.BindingBase.Transformers.ToString = function Sys$Preview$BindingBase$Transformers$ToString(sender, eventArgs) { var value = eventArgs.get_value(); var newValue = ‘’; var formatString = eventArgs.get_transformerArgument(); var placeHolder = (formatString && (formatString.length !== 0)) ? formatString.indexOf(‘{0}’) : -1;
Invert As you can see from the following code listing, the Invert transformer simply inverts the source property value. This means that if the source property value is null, this transformer sets the value to true. Otherwise it sets the value to false.
Compare As the following code listing shows, the Compare transformer compares the source property value with the value assigned to the transformerArgument property. If they’re equal, the transformer sets the value to true. Otherwise it sets the value to false. Sys.Preview.BindingBase.Transformers.Compare = function Sys$Preview$BindingBase$Transformers$Compare(sender, eventArgs) { var value = eventArgs.get_value(); var compareValue = eventArgs.get_transformerArgument(); if (compareValue === null) value = value ? true : false; else value = (value === compareValue); eventArgs.set_value(value); }
CompareInverted As the following code listing shows, the CompareInverted transformer is the opposite of the Compare transformer. In other words, if the source property value is equal to the value assigned to the transformerArgument property, this transformer sets the value to false. Otherwise it sets the value to true. Sys.Preview.BindingBase.Transformers.CompareInverted = function Sys$Preview$BindingBase$Transformers$CompareInverted(sender, eventArgs) { Sys.Debug.assert(eventArgs.get_direction() === Sys.Preview.BindingDirection.In); var value = eventArgs.get_value(); var compareValue = eventArgs.get_transformerArgument(); if (compareValue === null) value = value ? false : true; else value = (value !== compareValue); eventArgs.set_value(value); }
1337
bapp02.indd 1337
8/20/07 8:58:58 PM
Appendix B: Binding
Binding The Binding class derives from the BindingBase class and extends its functionality to add support for a new property of type Sys.Preview.BindingDirection named direction. You can use the get_direction and set_direction methods of the Binding object to imperatively get and set the value of the direction property from your code. Sys.Preview.Binding.registerClass(‘Sys.Preview.Binding’, Sys.Preview.BindingBase);
The direction property specifies the direction of binding. By default, the target property is bound to the source property, so that changes in the source property value are reflected in the target property. The direction property value of Sys.Preview.BindingDirection.In represents this default behavior. However, you can set the direction property to the Sys.Preview.BindingDirection.Out value to instruct the Binding object that you want the binding in the opposite direction, so that the changes made in the target property are reflected in the source property. You can also set the direction property to Sys.Preview.BindingDirection.InOut to instruct the Binding object that you want a two-way binding, so that changes made in the target property are reflected in the source property and vice versa. The Binding class also overrides the evaluateOut method that it inherits from the BindingBase class. Recall that this base class did not implement this method. Listing B-3 showed that the evaluate method of the BindingBase class invokes the evaluateOut method when the binding direction is not Sys .Preview.BindingDirection.In. In other words, the evaluateOut method handles the reverse and two-way binding scenarios. Note that the binding direction affects the results of some built-in transformers such as Add and Multiply. The following code listing presents the implementation of the Add transformer. As you can see, this transformer adds the value specified in the transformerArgument property to the source property value if the binding direction is Sys.Preview.BindingDirection.In and subtracts this value from the source property value if the binding direction is Sys.Preview.BindingDirection.Out. Sys.Preview.BindingBase.Transformers.Add = function Sys$Preview$BindingBase$Transformers$Add(sender, eventArgs) { var value = eventArgs.get_value(); if (typeof(value) !== ‘number’) { if(value === “”) value = 0; else value = Number.parseInvariant(value); } var delta = eventArgs.get_transformerArgument(); if (!delta) delta = 1; if (typeof(delta) !== ‘number’) { if(value === “”) delta = 0;
1338
bapp02.indd 1338
8/20/07 8:58:58 PM
Appendix B: Binding else delta = Number.parseInvariant(delta); } if (eventArgs.get_direction() === Sys.Preview.BindingDirection.Out) delta = -delta; var newValue = value + delta; if (eventArgs.get_targetPropertyType() !== ‘number’) newValue = newValue.toString(); eventArgs.set_value(newValue); }
The Binding class exposes a descriptor static property that specifies the members of this class that you can invoke declaratively in xml-script. As the following code listing shows, you can set the direction property of a Binding object in xml-script. You can also invoke the evaluateOut method in xml-script. Sys.Preview.Binding.descriptor = { properties: [ {name: ‘direction’, type: Sys.Preview.BindingDirection} ], methods: [ {name: ‘evaluateOut’} ] }
1339
bapp02.indd 1339
8/20/07 8:58:59 PM
bapp02.indd 1340
8/20/07 8:58:59 PM
Actions Most ASP.NET AJAX client classes expose events. An action is an ASP.NET AJAX object that encapsulates a piece of client-side functionality that gets executed in response to a specified event of a specified ASP.NET AJAX object. All ASP.NET AJAX actions implement an interface named IAction, defined in Listing C-1. As you can see, this interface exposes the two methods described in the following table:
Method
Description
execute
This method executes the action’s encapsulated client-side functionality in response to a specified event of a specified ASP.NET AJAX object.
setOwner
This method specifies the owner of the action. The owner of the action is the ASP.NET AJAX object that fires the event that triggers the execution of the action’s encapsulated client-side functionality.
Listing C-1: The IAction Interface Sys.Preview.IAction = function Sys$Preview$IAction() { throw Error.notImplemented(); } function Sys$Preview$IAction$execute() { throw Error.notImplemented(); } function Sys$Preview$IAction$setOwner() { throw Error.notImplemented(); } Sys.Preview.IAction.prototype = { execute: Sys$Preview$IAction$execute, setOwner: Sys$Preview$IAction$setOwner } Sys.Preview.IAction.registerInterface(‘Sys.Preview.IAction’);
bapp03.indd 1341
8/20/07 8:59:23 PM
Appendix C: Actions
Action The ASP.NET AJAX client-side framework comes with an implementation of the IAction interface named Action, which encapsulates the base functionality that every action must support. Because of this, you should derive your custom actions from the Action base class instead of directly implementing the IAction interface, to save yourself from having to re-implement the base functionality that the Action base class already supports. The following table presents the methods of the Action class:
Method
Description
get_eventSource
Gets the reference to the ASP.NET AJAX object whose event triggers the execution of the client-side functionality that the action encapsulates.
set_eventSource
Sets the reference to the ASP.NET AJAX object whose event triggers the execution of the client-side functionality that the action encapsulates.
get_eventName
Gets the name of the event that triggers the execution of the client-side functionality that the action encapsulates.
set_eventName
Sets the name of the event that triggers the execution of the client-side functionality that the action encapsulates.
get_target
Gets the target of the action. The target of an action is an ASP.NET AJAX object to which the client-side functionality that the action encapsulates is applied. Note the difference between the target and event source of an action. The event source of an action is the ASP.NET AJAX object whose event triggers the execution of the encapsulated client-side functionality of the action.
set_target
Sets the target of the action.
get_dataContext
Returns a reference to the action. The Action inherits this method from the Component base class. This method allows the action to act as a data context for other ASP.NET AJAX objects. (A data context is an ASP.NET AJAX object that acts as a source of data for other ASP.NET AJAX objects.)
get_eventArgs
The initialize method of the Action class registers the execute method as an event handler for the event (whose name is given by the eventName property) of the event source (referenced by the eventSource property). When event source raises the event and consequently invokes the execute method, it passes two parameters into this method. The first parameter references the event source. The second parameter references an instance of the event data class associated with the event. The execute method stores this instance in an internal field named _eventArgs before it invokes the performAction method. The get_eventArgs method simply returns the value of this field. This allows the subclasses of the Action to invoke the get_eventArgs method from within their implementation of the performAction method in order to access the event data class instance that holds the event data. The execute method sets the
1342
bapp03.indd 1342
8/20/07 8:59:24 PM
Appendix C: Actions _eventArgs field to null before it returns. Therefore, you must call the get_eventArgs method only inside the performAction method of your custom action class. If you call this method after the execute method returns or before the execute method is invoked, you’ll get a null value. get_result
Returns the return value of the performAction method of the action. The execute method invokes the performAction method and stores the return value of this method in an internal field named _result. The get_result method basically returns the value of this internal field. The execute method sets the _results field to null before it returns. Therefore, you must call the get_result method only inside the performAction method of your custom action class. If you call this method after the execute method returns or before the execute method is invoked, you’ll get a null value.
get_sender
Returns a reference to the event source — in other words, the same object that get_eventSource returns.
get_bindings
Gets an array of Binding objects, each of which binds a particular property of the action to a particular property of the current data context.
dispose
Performs the final cleanup before the action is disposed of. The Action class inherits this method from the Component base class.
performAction
The subclasses of the Action base class must implement this method to encapsulate the client-side functionality that they want executed in response to a specified event of the specified ASP.NET AJAX object.
execute
Executes the client-side functionality encapsulated by the action. The Action class inherits this method from the IAction interface. Your
custom action mustn’t override this method; it must instead override the performAction method. initialize
Initializes the action. The Action class inherits this method from the Component base class. Your custom action can override this optional method to initialize itself. If you do decide to override this method, make sure you invoke the initialize method of the base class to allow the base class to perform its own initialization.
setOwner
Sets the owner of the action. The Action class inherits this method from the IAction interface. The owner of an Action object is the same as its event source.
The Action class derives from the Component base class and implements the IAction interface: Sys.Preview.Action.registerClass(‘Sys.Preview.Action’, Sys.Component, Sys.Preview.IAction);
The Action class exposes a property named eventSource, as well as a getter named get_eventSource and a setter named set_eventSource that you can use to get and set this property. The eventSource property references the ASP.NET AJAX object whose event triggers the execution of the client-side functionality encapsulated by the action.
1343
bapp03.indd 1343
8/20/07 8:59:24 PM
Appendix C: Actions Listing C-2 presents an excerpt from Listing A-13. I’ve cleaned up this excerpt for presentation purposes. As you can see, it contains the logic that initializes the ASP.NET AJAX object whose event triggers the execution of the client-side functionality encapsulated by the action. In other words, the first parameter of the initializeObject method references the ASP.NET AJAX object whose event triggers the execution of the action, and the second parameter of this method references the xml-script node that represents this ASP.NET AJAX object in xml-script.
Listing C-2: An Excerpt from Listing A-13 Sys.Preview.MarkupParser.initializeObject = function Sys$Preview$MarkupParser$initializeObject(instance, node, markupContext) { var td = Sys.Preview.TypeDescriptor.getTypeDescriptor(instance); var events = td._getEvents(); var childNodes = node.childNodes; for (i = childNodes.length - 1; i >= 0; i--) { var childNode = childNodes[i]; var nodeName = Sys.Preview.MarkupParser.getNodeName(childNode); eventInfo = events[nodeName]; if (eventInfo) { var actions = Sys.Preview.MarkupParser.parseNodes(childNode.childNodes, markupContext); if (actions.length) { eventValue = instance[“add_” + eventInfo.name]; if(eventValue) { for (var e = 0; e < actions.length; e++) { var action = actions[e]; action.set_eventName(eventInfo.name); action.set_eventSource(instance); } } } } } }
Let’s study this excerpt in the context of the example shown in Listing C-3. This example shows a page that uses an instance of an action named SetPropertyAction, which is a subclass of the Action base class. SetPropertyAction encapsulates the client-side functionality that sets the specified property of a specified ASP.NET AJAX object. In the example shown in Listing C-3, SetPropertyAction sets the value of the text property of a Label ASP.NET AJAX control with id property value of myspan, which represents a span HTML element with an id HTML attribute value of myspan. Note that the target
1344
bapp03.indd 1344
8/20/07 8:59:25 PM
Appendix C: Actions property of this SetPropertyAction contains the id property value of this Label ASP.NET AJAX control. Recall that the target property references the ASP.NET AJAX object to which the action applies. The except shown in Listing C-2 basically parses the boldface portion of Listing C-3, that is,
In other words, the first parameter of the initializeObject method references the Button ASP.NET AJAX client control with the id property value of button1, and the second parameter of this method references the xml-script node that represents this Button ASP.NET AJAX client control in xml-script — that is, the node. Note that this excerpt invokes the set_eventName setter of the SetPropertyAction action to set its eventName property to click, because this is the event that triggers this action, and invokes the set_eventSource setter of the SetPropertyAction action to set its eventSource property to a reference to the Button ASP.NET AJAX control with the id property value of button1, because this is the ASP.NET AJAX object whose event triggers the action. As you can see, the initializeObject method sets only the eventName and eventSource properties of an action. You may be wondering who is responsible for setting the rest of the properties. The answer is the parseFromMarkup static method of the Action class, as shown in Listing C-4.
Listing C-3: An Example of an Action Untitled Page Print Message
(continued)
1345
bapp03.indd 1345
8/20/07 8:59:25 PM
Appendix C: Actions Listing C-3 (continued)
Listing C-4: The parseFormMarkup Method Sys.Preview.Action.parseFromMarkup = function Sys$Preview$Action$parseFromMarkup(type, node, markupContext) { var newAction = new type(); var action = Sys.Preview.MarkupParser.initializeObject(newAction, node, markupContext); if (action) { markupContext.addComponent(action); return action; } else newAction.dispose(); return null; }
As you can see, the parseFromMarkup method first invokes the new operator on the first parameter of the method. In the case of Listing C-3, the first parameter references the constructor of the SetPropertyAction class, which means that the following statement basically instantiates an instance of the SetPropertyAction class: var newAction = new type();
Next, the parseFromMarkup method invokes the initializeObject static method on the MarkupParser class, passing in four parameters. The first parameter references the newly instantiated action, which is the newly instantiated SetPropertyAction in the case of listing C-3. The second
1346
bapp03.indd 1346
8/20/07 8:59:25 PM
Appendix C: Actions parameter references the xml-script node that represents the action in xml-script, which is the following node in the case of Listing C-3:
The third parameter references the current MarkupContext. The initializeObject method first parses the xml-script node referenced by its second parameter, which is the following node:
The method then extracts the values of the target, property, and value attributes on the xml-script node and assigns them to the target, property, and value properties of the newly instantiated SetPropertyAction action. Note that the get_target and set_target methods of the Action base class get and set the actual reference to the target ASP.NET AJAX object. If you plan to invoke the set_target method imperatively from your client code to set the target property, you must ensure that you pass the actual reference to the target ASP.NET AJAX object into this method. You may be wondering why the xml-script shown in Listing C-3 enables page developers to assign the id property value of the Label ASP.NET AJAX control to the target property of the SetPropertyAction, as opposed to assigning the actual reference to the Label ASP.NET AJAX control, as shown in the boldface portions of the following excerpt from Listing C-3:
The answer lies in what the parseFromMarkup static method of the Action base class does when the xml-script is being parsed. As discussed earlier, this method invokes the initializeObject method. As thoroughly discussed in Appendix A, this method automatically uses the value of the target attribute to access the actual reference to the Label ASP.NET AJAX control.
execute The Action class implements the execute method of the IAction interface, as shown in Listing C-5. As mentioned earlier, this method is registered as an event handler for a specified event of a specified ASP.NET AJAX object. Therefore, like any other ASP.NET AJAX event handler, it takes two arguments: the first references the object that raised the event and consequently called the method, and the second references the event data class instance that contains the event data associated with the event. As Listing C-5 shows, the execute method stores this event data class instance in a private field named _eventArgs. As I mentioned earlier, the Action class exposes a getter named get_eventArgs, which returns the value of this private field. this._eventArgs = eventArgs;
1347
bapp03.indd 1347
8/20/07 8:59:26 PM
Appendix C: Actions The execute method then calls the get_bindings method to return an array that contains all the binding objects associated with the action: var bindings = this.get_bindings();
Then the execute method iterates through the binding objects in this array and takes the following steps for each enumerated binding object. If the binding object is of type Binding or one of its subclasses, and if the binding direction of the binding object is not reverse — that is, if the get_direction method of the binding object does not return the enumeration value of Out — the execute method invokes the evaluateIn method on the binding object to have the object assign the value of the specified property of the current data context to the specified property of the action. Which property of the current data context is bound to which property of the action is determined when the associated binding object is defined and added to the bindings collection property of the action. Keep in mind that the get_bindings method of the Action class returns a reference to this bindings collection property. This logic ensures that the values of those properties of the action that are bound to the properties of some other ASP.NET AJAX objects are updated before the performAction method is invoked to execute the action. Next, the execute method invokes the performAction method to execute the action and stores the return value of this method in a private field named _result. As a matter of fact, the Action base class exposes a getter named get_result that returns the value of this private field. this._result = this.performAction();
Then the execute method iterates through the binding objects in the bindings collection property of the action once more, and takes the following steps for each enumerated binding object. If the enumerated binding object is of type Binding or one of its subclasses, and if the binding direction of the binding object is reverse or two-way — that is, if the call into the get_direction method of the binding object does not return an In enumeration value — the execute method invokes the evalutateOut method on the binding object to have this object evaluate the value of the specified property of the action and to assign this value to the specified property of the specified ASP.NET AJAX object. This ensures that if the performAction method causes one or more properties of the action to change, these changes are reflected in the properties of those ASP.NET AJAX objects that are bound to the changed properties of the action. Finally, the execute method resets the values of the _eventArgs and _result private fields. This means that the values of these two fields, and consequently the return values of the get_eventArgs and get_result getter methods, are only valid during the execution of the execute method — that is, after the execute method is invoked and before this method returns. this._eventArgs = null; this._result = null;
Note that the Action base class does not implement the performAction method; it delegates the responsibility of implementing this method to its subclasses.
1348
bapp03.indd 1348
8/20/07 8:59:26 PM
Appendix C: Actions Listing C-5: The Execute Method of the Action Base Class function Sys$Preview$Action$execute(sender, eventArgs) { this._eventArgs = eventArgs; var bindings = this.get_bindings(); var binding; var bindingType; if(bindings) { var i; for (i = 0; i < bindings.length; i++) { binding = bindings[i]; bindingType = binding ? Object.getType(binding) : null; if(bindingType && (bindingType === Sys.Preview.Binding || Sys.Preview.Binding.inheritsFrom(bindingType))) { if(binding.get_direction() !== Sys.Preview.BindingDirection.Out) binding.evaluateIn(); : } : else : binding.evaluateIn(); } }
descriptor The following code listing presents the descriptor property of the Action class. This property specifies those properties that can be set declaratively from xml-script.
InvokeMethodAction The InvokeMethodAction ASP.NET AJAX action, like any other, derives from the Action base class: Sys.Preview.InvokeMethodAction.registerClass(‘Sys.Preview.InvokeMethodAction’, Sys.Preview.Action);
As the name suggests, the InvokeMethodAction encapsulates the client-side functionality that invokes a specified method on a specified ASP.NET AJAX object. The following table presents the members of the InvokeMethodAction:
Member
Description
get_method
Gets the name of the method invoked by the InvokeMethodAction
set_method
Sets the name of the method invoked by the InvokeMethodAction
get_parameters
Returns the JavaScript object literal that contains the names and values of the parameters of the method invoked by the InvokeMethodAction
The InvokeMethodAction implements the performAction method that it inherits from the Action base class, as shown in the following code fragment. As you can see, this method calls the invokeMethod static method on the TypeDescriptor class, passing in three parameters: the first references the ASP.NET AJAX object whose method is being invoked, the second contains the name of the method being invoked, and the third is the JavaScript object literal that contains the names and values of the parameters of the method being invoked. function Sys$Preview$InvokeMethodAction$performAction() { return Sys.Preview.TypeDescriptor.invokeMethod(this.get_target(), this._method, this._parameters); }
The invokeMethod static method of the TypeDescriptor class searches for the method with the specified name in the descriptor property of the ASP.NET AJAX object that owns the method. Therefore,
1350
bapp03.indd 1350
8/20/07 8:59:26 PM
Appendix C: Actions the ASP.NET AJAX object whose method the InvokeMethodAction invokes must expose a static descriptor property with an entry for the method. Suppose you have an ASP.NET AJAX type named MyNamespace.MyType that exposes a method named MyMethod that takes a parameter of type MyNamespace.MyParameterType named MyParameter. The MyNamespace.MyType type must expose a descriptor static property with the following entry to allow the InvokeMethodAction to invoke its MyMethod method: MyNamespace.MyType.descriptor = { methods: [{name: “MyMethod”, parameters: [{name: “Parameter1”, type: MyNamespace.MyParameterType}]}] }
The InvokeMethodAction class exposes the following descriptor static property: Sys.Preview.InvokeMethodAction.descriptor = { properties: [ {name: ‘method’, type: String}, {name: ‘parameters’, type: Object, readOnly: true} ] }
This means that you can set the method and parameters properties of the InvokeMethodAction declaratively in xml-script. Keep in mind that only those properties and events of an ASP.NET AJAX class specified in the descriptor static property of the class can be set in xml-script. If a class exposes a property but does not include an entry for it in its descriptor static property, you cannot set the value of this property in xml-script. You must set it imperatively from your client code. As I mentioned earlier, another option is for the class to implement the ICustomTypeProvider interface. The following code listing contains a page that uses the InvokeMethodAction to invoke the toggleCssClass method on the Label ASP.NET AJAX client control with an id property value of myspan. Untitled Page .myCssClass { background-color: #dddddd; }
(continued)
1351
bapp03.indd 1351
8/20/07 8:59:27 PM
Appendix C: Actions (continued) Toggle CSS Class Wrox Web Site
It is very important that you use the same exact names for the method and its parameters that the descriptor property of the class that owns the method uses. For example, in this case, the Label ASP.NET AJAX client control derives from the Control base class, which exposes the following descriptor property. As the boldface portion of this code fragment shows, the descriptor property contains an entry for a method named toggleCssClass, which takes a parameter of type string named className, which are the same exact names we’ve used (as shown in the boldfaced portion of the previous code listing). Sys.UI.Control.descriptor = { properties: [ {name: ‘element’, type: Object, readOnly: true}, {name: ‘role’, type: String, readOnly: true}, {name: ‘parent’, type: Object}, {name: ‘visible’, type: Boolean}, {name: ‘visibilityMode’, type: Sys.UI.VisibilityMode} ], methods: [ {name: ‘addCssClass’, parameters: [ {name: ‘className’, type: String} ] }, {name: ‘removeCssClass’, parameters: [ {name: ‘className’, type: String} ] }, {name: ‘toggleCssClass’, parameters: [ {name: ‘className’, type: String} ] } ] }
1352
bapp03.indd 1352
8/20/07 8:59:27 PM
Appendix C: Actions
SetProper tyAction The SetPropertyAction ASP.NET AJAX action, like any other, derives from the Action base class: Sys.Preview.SetPropertyAction.registerClass(‘Sys.Preview.SetPropertyAction’, Sys.Preview.Action);
As the name suggests, the SetPropertyAction encapsulates the client-side functionality that sets the value of a specified property of a specified ASP.NET AJAX object. The following table presents the members of the SetPropertyAction:
Member
Description
get_property
Gets the name of the property set by SetPropertyAction.
set_property
Sets the name of the property set by SetPropertyAction.
get_propertyKey
Gets the name of the subproperty set by SetPropertyAction. If both the property and propertyKey properties are specified, SetPropertyAction assumes that the specified propertyKey is a subproperty of the specified property and sets the value of the subproperty.
set_propertyKey
Sets the name of the subproperty set by SetPropertyAction.
get_value
Gets the value that SetPropertyAction assigns to the specified property or subproperty.
set_value
Sets the value that SetPropertyAction assigns to the specified property or subproperty.
SetPropertyAction, like any other action, implements the performAction method that it inherits from the Action base class, as shown in the following code fragment. As you can see, this method calls the setProperty static method on the TypeDescriptor class, passing in four parameters: the first references the ASP.NET AJAX object whose property is being set, the second contains the name of the property being set, the third contains the value to be assigned to the specified property or subproperty, and the last specifies the name of the subproperty being set: function Sys$Preview$SetPropertyAction$performAction() { Sys.Preview.TypeDescriptor.setProperty(this.get_target(), this._property, this._value, this._propertyKey); return null; }
The setProperty static method of the TypeDescriptor class searches for the property with the specified name in the descriptor property of the ASP.NET AJAX object that owns the property. Therefore, the ASP.NET AJAX object whose property the InvokeMethodAction sets must expose a static descriptor property with an entry for the property.
1353
bapp03.indd 1353
8/20/07 8:59:27 PM
Appendix C: Actions The SetPropertyAction class exposes the following descriptor static property: Sys.Preview.SetPropertyAction.descriptor = { properties: [ {name: ‘property’, type: String}, {name: ‘propertyKey’ }, {name: ‘value’, type: String} ] }
This means that you can set in xml-script only those properties of the SetPropertyAction specified in this descriptor property. The following code listing contains a page that uses SetPropertyAction to set the className subproperty of the element property of the Label ASP.NET AJAX client control with an id property value of myspan to the value myCssClass: Untitled Page .myCssClass { background-color: #dddddd; } Toggle CSS Class Wrox Web Site
1354
bapp03.indd 1354
8/20/07 8:59:28 PM
Appendix C: Actions
PostBackAction The PostBackAction ASP.NET AJAX action also derives from the Action base class: Sys.Preview.PostBackAction.registerClass(‘Sys.Preview.PostBackAction’, Sys.Preview.Action);
As the name implies, PostBackAction encapsulates the client-side functionality that enables an ASP.NET AJAX object to post the current page back to the server. The best way to understand the significance of the PostBackAction action is to study its implementation of the performAction method, as shown in the following code listing: function Sys$Preview$PostBackAction$performAction() { __doPostBack(this.get_target(), this.get_eventArgument()); return null; }
As you can see, the performAction method calls the __doPostBack global JavaScript function, passing in two parameters, the return values of the get_target and get_eventArgument getter methods, respectively. Recall that the __doPostBack global JavaScript function posts the page back to the server. Also recall that this JavaScript function takes two parameters. The first is a string that contains the value of the name HTML attribute of the HTML element responsible for the postback. This HTML element is known as the event target. The second parameter is an optional string that contains extra information that helps the server-side code process the page postback. This optional parameter is known as the event argument. The following table presents the members of PostBackAction:
Member
Description
get_target
Gets the value of the name HTML attribute of the event target
set_target
Sets the value of the name HTML attribute of the event target
get_eventArgument
Gets the event argument
set_eventArgument
Sets the event argument
The PostBackAction class exposes the following descriptor static property: Sys.Preview.PostBackAction.descriptor = { properties: [ {name: ‘eventArgument’, type: String}, {name: ‘target’, type: String} ] }
This means that you can set in xml-script only those properties of PostBackAction specified in the preceding descriptor property.
1355
bapp03.indd 1355
8/20/07 8:59:28 PM
Appendix C: Actions The great thing about the PostBackAction action is that it lets you enable your ASP.NET AJAX classes to perform a page postback. For example, the Button ASP.NET AJAX client control associated with the HTML element normally does not post the page back to the server. The page shown in the following code listing demonstrates how to use PostBackAction to enable the Button ASP.NET AJAX client control associated with the HTML element to perform a page postback: Untitled Page Submit
1356
bapp03.indd 1356
8/20/07 8:59:28 PM
Data Control The ASP.NET framework comes with a server control named DataBoundControl that acts as the base class for important server controls such as GridView and DetailsView. The DataBoundControl base server control encapsulates the basic functionality that all data-bound controls must support. The ASP.NET AJAX client-side framework comes with a client control named DataControl that acts as the base control for important client controls such as ListView. The DataControl client control, just like its DataBoundControl server-side counterpart, encapsulates the base functionality that all data-bound client controls must support. In this appendix I’ll present and discuss the members of the DataControl base class to:
❑
Help you gain the skills you need to derive from this base class in order to implement your own custom data controls.
❑
Set the stage for the Appendix F, where you’ll see how the ASP.NET AJAX ListView client control extends the functionality of the DataControl base class.
The DataControl base class belongs to a namespace named Sys.Preview.UI.Data, as defined in the following: Type.registerNamespace(‘Sys.Preview.UI.Data’);
Constructor Listing D-1 presents the internal implementation of the constructor of the DataControl base class. This constructor takes a single argument that references the DOM element that the DataControl base class represents. In other words, you can think of the DataControl base class as the ASP.NET AJAX representation of this DOM element. This constructor, like that of any other subclass, first calls the initializeBase method to invoke the constructor of its base class: Sys.Preview.UI.Data.DataControl.initializeBase(this, [associatedElement]);
bapp04.indd 1357
8/20/07 8:59:54 PM
Appendix D: Data Control The base class in this case is the Control client class: Sys.Preview.UI.Data.DataControl.registerClass(‘Sys.Preview.UI.Data.DataControl’, Sys.UI.Control);
The constructor then sets the value of a property named dataIndex to 0. The value of this property will be used as an index into the collection that contains the data records to access the associated record: this._dataIndex = 0;
Listing D-1: The Internal Implementation of the Constructor of the DataControl Base Class Sys.Preview.UI.Data.DataControl = function Sys$Preview$UI$Data$DataControl(associatedElement) { Sys.Preview.UI.Data.DataControl.initializeBase(this, [associatedElement]); this._dataIndex = 0; } Sys.Preview.UI.Data.DataControl.registerClass(‘Sys.Preview.UI.Data.DataControl’, Sys.UI.Control);
prepareChange As you can see from Listing D-2, the DataControl base class comes with a method named prepareChange that returns a JavaScript object literal that contains three name/value pairs, which describe the dataIndex, canMoveNext, and canMovePrevious properties of the class, respectively. I’ll discuss these three properties shortly. As you’ll see later, other methods of the DataControl base class call the prepareChange method every time the values of these properties are about to change. These methods store the JavaScript object containing the current values of these properties so they can compare those values with the new ones and raise the necessary events if the values have indeed changed (hence the name prepareChange).
Listing D-2: The prepareChange Method of the DataControl Base Class function Sys$Preview$UI$Data$DataControl$prepareChange() { return {dataIndex: this.get_dataIndex(), canMoveNext: this.get_canMoveNext(), canMovePrevious: this.get_canMovePrevious()}; }
triggerChangeEvents As you can see from Listing D-3, the triggerChangeEvents method of the DataControl base class takes a JavaScript object literal as its sole argument. This object is the same one that the prepareChange method returns. As we discussed earlier, other methods of the DataControl base class invoke the
1358
bapp04.indd 1358
8/20/07 8:59:55 PM
Appendix D: Data Control prepareChange method to return the object that contains the current values of the dataIndex, canMoveNext, and canMovePrevious properties every time the values of these properties are about to change. After the changes occur, these methods call the triggerChangeEvents method, passing in the
object containing the old values of these properties. This method takes the following steps for each of these properties. First, it calls the associated getter method of the DataControl base class to access the current value of the property: var dataIndex = this.get_dataIndex();
Next, it compares the current value with the old value and calls the raisePropertyChanged method to raise the propertyChanged event if the two values are different: this.raisePropertyChanged(‘dataIndex’); this.raisePropertyChanged(‘dataItem’);
The DataControl class inherits the raisePropertyChanged method from its base class — that is, the Control class. Recall from the previous chapters that this method raises an event named propertyChanged. Finally, the triggerChangeEvents method assigns the new value to the respective property of the object. In other words, the new value is now the old value: oldState.dataIndex = dataIndex;
Listing D-3: The triggerChangeEvent Method of the DataControl Base Class function Sys$Preview$UI$Data$DataControl$triggerChangeEvents(oldState) { var dataIndex = this.get_dataIndex(); if (oldState.dataIndex !== dataIndex) { this.raisePropertyChanged(‘dataIndex’); this.raisePropertyChanged(‘dataItem’); oldState.dataIndex = dataIndex; } var canMoveNext = this.get_canMoveNext(); if (oldState.canMoveNext !== canMoveNext) { this.raisePropertyChanged(‘canMoveNext’); oldState.canMoveNext = canMoveNext; } var canMovePrevious = this.get_canMovePrevious(); if (oldState.canMovePrevious !== canMovePrevious) { this.raisePropertyChanged(‘canMovePrevious’); oldState.canMovePrevious = canMovePrevious; } }
1359
bapp04.indd 1359
8/20/07 8:59:55 PM
Appendix D: Data Control
get_canMoveNext The DataControl class exposes a read-only Boolean property named canMoveNext that specifies whether the data control can move to the next data record in the internal data record collection. As Listing D-4 shows, the DataControl class features a getter method named get_canMoveNext that you can use to access the value of this property. This method first checks whether the internal data collection exists to begin with. If not, it returns false: if (!this._data) return false; DataControl exposes a collection property named data that contains the data records. If the data collection does exist, it checks whether the current data index is less than the total number of data records in the data record collection: return (this._dataIndex < this.get_length() - 1);
As you’ll see later, the DataControl class exposes a getter method named get_length that returns the total number of data records in the data collection.
Listing D-4: The get_canMoveNext Method of the DataControl Base Class function Sys$Preview$UI$Data$DataControl$get_canMoveNext() { if (!this._data) return false; return (this._dataIndex < this.get_length() - 1); }
get_canMovePrevious The DataControl base class exposes a read-only Boolean property named canMovePrevious that specifies whether the data control can move to the previous record in the data record collection. As you can see from Listing D-5, the DataControl base class comes with a getter method named get_canMovePrevious that you can use to access the value of the canMovePrevious property. This method first checks whether the data record collection exists. If not, it returns false to inform its caller that the data control cannot move to the previous record: if (!this._data) return false;
If so, it checks whether the current data index is greater than 0. If so, it returns true to inform its caller that the data control can indeed move to the previous record.
1360
bapp04.indd 1360
8/20/07 8:59:55 PM
Appendix D: Data Control Listing D-5: The get_canMovePrevious Method of the DataControl Base Class function Sys$Preview$UI$Data$DataControl$get_canMovePrevious() { if (!this._data) return false; return (this._dataIndex > 0); }
get_data As I mentioned earlier, the DataControl base class exposes a collection property named data that contains the data records. The get_data getter method of the DataControl class returns a reference to this collection, as shown in Listing D-6.
Listing D-6: The get_data Method of the DataControl Base Class function Sys$Preview$UI$Data$DataControl$get_data() { return this._data; }
set_data The set_data setter method of the DataControl base class enables you to set the value of the data property of the class. As you can see from Listing D-7, this method takes a collection of data records as its single argument and assigns that collection to the data property. Here are the steps that the set_data method takes to accomplish this task. First, it calls the prepareChange method to return the JavaScript object that contains the current values of the dataIndex, canMoveNext, and canMovePrevious properties of the data control: var oldState = this.prepareChange();
As you’ll see shortly, every time the value of the data property is set — that is, every time a new data record collection is assigned to the data property — the set_data method registers a delegate named _dataChangedDelegate as an event handler for the collectionChanged event of the new data record collection, if the collection implements the INotifyCollectionChanged interface. That is why, before assigning the new data collection to the data property, the set_data setter first invokes the remove_collectionChanged method on the old data collection to remove the _dataChangedDelegate delegate from the list of event handlers registered for the collectionChanged event of the old data
1361
bapp04.indd 1361
8/20/07 8:59:55 PM
Appendix D: Data Control collection. This ensures that the old data collection no longer invokes this delegate, because it is being replaced with the new data collection: if (this._data && Sys.Preview.INotifyCollectionChanged.isImplementedBy(this._data)) { this._data.remove_collectionChanged(this._dataChangedDelegate); this._dataChangedDelegate = null; }
Next, the set_data method assigns the new data collection to the data property: this._data = value;
Next, the set_data method checks whether the new data collection implements the INotifyCollectionChanged interface. If so, it calls the createDelegate static method on the Function to create a delegate that represents a method named onDataChanged, and stores this delegate in the _dataChangedDelegate field. Next, it invokes the add_collectionChanged method on the new data collection to register this delegate as event handler for the collectionChanged event of the new data collection: if (this._data && Sys.Preview.INotifyCollectionChanged.isImplementedBy(this._data)) { this._dataChangedDelegate = Function.createDelegate(this, this.onDataChanged); this._data.add_collectionChanged(this._dataChangedDelegate); }
Next, the set_data setter calls the get_length method to determine the total number of records in the new data collection. If the current data index of the data control is greater or equal to this number, the set_data setter method invokes the set_dataIndex setter to reset the current data index to 0: if (this._dataIndex >= this.get_length()) this.set_dataIndex(0);
If the data control is not already updating, the set_data setter invokes the render method to update the data control: if (!this.get_isUpdating()) this.render();
Next, the set_data setter invokes the raisePropertyChanged method to raise the propertyChanged event and consequently to invoke all the event handlers registered for this event: this.raisePropertyChanged(‘data’);
If you need to run some custom code when the data control is bound to a new data collection, encapsulate this custom code in a method and register this method as an event handler for the propertyChanged event of the data control.
1362
bapp04.indd 1362
8/20/07 8:59:56 PM
Appendix D: Data Control Finally, the set_data setter invokes triggerChangedEvents, passing in the JavaScript object that contains the old values of the dataIndex, canMoveNext, and canMovePrevious properties to raise the associated events as discussed earlier: this.triggerChangeEvents(oldState);
Listing D-7: The set_data Method of the DataControl Base Class function Sys$Preview$UI$Data$DataControl$set_data(value) { var oldState = this.prepareChange(); if (this._data && Sys.Preview.INotifyCollectionChanged.isImplementedBy(this._data)) { this._data.remove_collectionChanged(this._dataChangedDelegate); this._dataChangedDelegate = null; } this._data = value; if (this._data && Sys.Preview.INotifyCollectionChanged.isImplementedBy(this._data)) { this._dataChangedDelegate = Function.createDelegate(this, this.onDataChanged); this._data.add_collectionChanged(this._dataChangedDelegate); } if (this._dataIndex >= this.get_length()) this.set_dataIndex(0); if (!this.get_isUpdating()) this.render(); this.raisePropertyChanged(‘data’); this.triggerChangeEvents(oldState); }
get_length The DataControl base class exposes a getter named get_length that returns the total number of records in the data collection to which the data control is bound. As Listing D-8 shows, this getter returns 0 if the data property is null — that is, if the data control is not bound any data collection: if(!this._data) return 0;
Next, the get_length getter checks whether the bound data collection implements the IData interface. If so, it invokes the get_length method on the data collection to return the total number of records in the collection: if (Sys.Preview.Data.IData.isImplementedBy(this._data)) return this._data.get_length();
1363
bapp04.indd 1363
8/20/07 8:59:56 PM
Appendix D: Data Control Then, it checks whether the bound data collection is a JavaScript array. If so, it returns the value of the length property of the data collection: if (this._data instanceof Array) return this._data.length;
If the bound data collection does not implement the IData interface and is not a JavaScript array, the get_length method returns 0 because the bound data collection is not supported: return 0;
Listing D-8: The get_length Getter function Sys$Preview$UI$Data$DataControl$get_length() { if(!this._data) return 0; if (Sys.Preview.Data.IData.isImplementedBy(this._data)) return this._data.get_length(); if (this._data instanceof Array) return this._data.length; return 0; }
get_dataIndex The get_dataIndex getter method of the DataControl base class returns the index of the current record in the data collection to which the data control is bound. This getter simply returns the value of the _dataIndex field, as shown in Listing D-9.
Listing D-9: The get_dataIndex Getter function Sys$Preview$UI$Data$DataControl$get_dataIndex() { return this._dataIndex; }
set_dataIndex The set_dataIndex setter of the DataControl base class takes the following steps (see Listing D-10). First, it checks whether the new value is different from the old value. If not, it doesn’t do anything. If so, it begins by calling the prepareChange method to return the JavaScript object that contains the current values of the dataIndex, canMoveNext, and canMovePrevious properties: var oldState = this.prepareChange();
1364
bapp04.indd 1364
8/20/07 8:59:56 PM
Appendix D: Data Control Next, it assigns the new value to the dataIndex property: this._dataIndex = value;
Finally, it invokes the triggerChangeEvents method, passing in the preceding JavaScript object to raise the required events, as discussed earlier: this.triggerChangeEvents(oldState);
Listing D-10: The set_dataIndex Setter function Sys$Preview$UI$Data$DataControl$set_dataIndex(value) { if (this._dataIndex !== value) { var oldState = this.prepareChange(); this._dataIndex = value; if (!this._suspendChangeNotifications) this.triggerChangeEvents(oldState); } }
onDataChanged Recall that the set_data setter method registers a delegate that represents the onDataChanged method as event handler for the collectionChanged event of the bound data collection if this collection implements the INotifyCollectionChanged interface. As we discussed earlier, a collection raises this event when it changes. As you can see from Listing D-11, the onDataChanged method simply invokes the render method of the data control to update the data control.
Listing D-11: The onDataChanged Method function Sys$Preview$UI$Data$DataControl$onDataChanged(sender, args) { this.render(); }
get_dataItem The get_dataItem getter method of the DataControl base class returns a reference to the current data record in the data collection bound to the data control. As Listing D-12 shows, this method first checks whether the current data index is a positive number. If not, it returns null because the data collection does not contain a data record with a negative index! If so, it checks whether the data collection implements the IData interface. If so, it invokes the getItem method on the data collection, passing in the current data index to return a reference to the data record with the specified index: if (Sys.Preview.Data.IData.isImplementedBy(this._data)) return this._data.getItem(this._dataIndex);
1365
bapp04.indd 1365
8/20/07 8:59:57 PM
Appendix D: Data Control If the data collection is a JavaScript array, the getter method simply uses the value of the data index as an index into the data collection to return a reference to the data item with the specified index: if (this._data instanceof Array) return this._data[this._dataIndex];
Listing D-12: The get_dataItem Getter Method function Sys$Preview$UI$Data$DataControl$get_dataItem() { if (this._data && (this._dataIndex >= 0)) { if (Sys.Preview.Data.IData.isImplementedBy(this._data)) return this._data.getItem(this._dataIndex); if (this._data instanceof Array) return this._data[this._dataIndex]; } return null; }
get_dataContext The DataControl base class overrides the get_dataContext method that it inherits from the Control base class, in which DataControl invokes the get_dataItem method to return a reference to the current data record in the bound data collection, as shown in Listing D-13: return this.get_dataItem();
Listing D-13: The get_dataContext Getter function Sys$Preview$UI$Data$DataControl$get_dataContext() { return this.get_dataItem(); }
addItem The addItem method of the DataControl base class enables you to add an empty record to the bound data collection. As Listing D-14 shows, this method first checks whether the data control is bound to any data collection. If not, it doesn’t do anything and returns. If so, it begins by calling the prepareChange method to return the JavaScript object that contains the current values of the dataIndex, canMoveNext, and canMovePrevious properties: var oldState = this.prepareChange();
1366
bapp04.indd 1366
8/20/07 8:59:57 PM
Appendix D: Data Control Next, it checks whether the bound data collection implements the IData interface. If so, it invokes the add method on the data collection to add an empty record to the collection: if (Sys.Preview.Data.IData.isImplementedBy(this._data)) this._data.add({});
If the bound data collection is a JavaScript array, and if it exposes a method named add, the addItem method simply calls this method to add an empty record to the data collection: else if (this._data instanceof Array) { if(typeof(this._data.add) === “function”) this._data.add({});
If the bound data collection is a JavaScript array but it does not expose the add method, the addItem method simply calls the add static method on the Array class to add an empty record to the data collection: else if (this._data instanceof Array) { if(typeof(this._data.add) === “function”) this._data.add({}); else Array.add(this._data, {}); }
Next, the addItem method sets the current data index to the index of the newly added data record: this.set_dataIndex(this.get_length() - 1);
Finally, the addItem method calls the triggerChangeEvents method, passing the JavaScript object that contains the old values of the dataIndex, canMoveNext, and canMovePrevious properties to raise the appropriate events, as discussed earlier: this.triggerChangeEvents(oldState);
Listing D-14: The addItem Method function Sys$Preview$UI$Data$DataControl$addItem() { if (this._data) { var oldState = this.prepareChange(); if (Sys.Preview.Data.IData.isImplementedBy(this._data)) this._data.add({});
(continued)
1367
bapp04.indd 1367
8/20/07 8:59:57 PM
Appendix D: Data Control Listing D-14 (continued) else if (this._data instanceof Array) { if(typeof(this._data.add) === “function”) this._data.add({}); else Array.add(this._data, {}); } this.set_dataIndex(this.get_length() - 1); this.triggerChangeEvents(oldState); } }
deleteCurrentItem As the name suggests, the deleteCurrentItem method deletes the current data record from the bound data collection — if the data control is indeed bound to a data collection. As Listing D-15 shows, this method begins by invoking the prepareChange method to return the JavaScript object that contains the current values of the dataIndex, canMoveNext, and canMovePrevious properties: var oldState = this.prepareChange();
Next, it sets an internal flag to true to signal that all change notifications must be suspended because we’re about to introduce new changes: this._suspendChangeNotifications = true;
Then it calls the get_dataItem getter to return a reference to the current data record: var item = this.get_dataItem();
Next, it resets the current data index if the current data record is the last data record in the data collection: if (this.get_dataIndex() === this.get_length() - 1) this.set_dataIndex(Math.max(0, this.get_length() - 2));
Then it checks whether the bound data collection implements the IData interface. If so, it invokes the remove method on the bound data collection to remove the current data record: if (Sys.Preview.Data.IData.isImplementedBy(this._data)) this._data.remove(item);
Next, the deleteCurrentItem method checks whether the bound data collection is a JavaScript array and whether it supports the remove method. If so, it invokes the remove method on the data collection to remove the current data record:
1368
bapp04.indd 1368
8/20/07 8:59:57 PM
Appendix D: Data Control else if (this._data instanceof Array) { if(typeof(this._data.remove) === “function”) this._data.remove(item);
If the bound data collection is a JavaScript array but does not support the remove method, it calls the remove static method on the Array class to remove the current data record for the data collection: else if (this._data instanceof Array) { if(typeof(this._data.remove) === “function”) this._data.remove(item); else Array.remove(this._data, item); }
Next, it resets the _suspendChangeNotifications flag to allow change notifications: this._suspendChangeNotifications = false;
Finally, it invokes the triggerChangeEvents method, passing in the JavaScript object that contains the old values of the dataIndex, canMoveNext, and canMovePrevious properties, to trigger the required events, as discussed earlier: this.triggerChangeEvents(oldState);
Listing D-15: The deleteCurrentItem Method function Sys$Preview$UI$Data$DataControl$deleteCurrentItem() { if (this._data) { var oldState = this.prepareChange(); this._suspendChangeNotifications = true; var item = this.get_dataItem(); if (this.get_dataIndex() === this.get_length() - 1) this.set_dataIndex(Math.max(0, this.get_length() - 2)); if (Sys.Preview.Data.IData.isImplementedBy(this._data)) this._data.remove(item); else if (this._data instanceof Array) { if(typeof(this._data.remove) === “function”) this._data.remove(item); else Array.remove(this._data, item); } this._suspendChangeNotifications = false; this.triggerChangeEvents(oldState); } }
1369
bapp04.indd 1369
8/20/07 8:59:58 PM
Appendix D: Data Control
getItem The getItem method of the DataControl base class enables you to return a reference to the data record with the specified data index. As you can see from Listing D-16, this method first checks whether the data control is indeed bound to a data collection. If not, it returns null. If so, it checks whether the bound data collection implements the IData interface. If so, it simply calls the getItem method on the data collection to return a reference to the data record with the specified index: if (Sys.Preview.Data.IData.isImplementedBy(this._data)) return this._data.getItem(index);
If not, it checks whether the bound data collection is a JavaScript array. If so, it uses the specified data index as an index into the data collection to return a reference to the data record with the specified index: if (this._data instanceof Array) return this._data[index];
Listing D-16: The getItem Method function Sys$Preview$UI$Data$DataControl$getItem(index) { if (this._data) { if (Sys.Preview.Data.IData.isImplementedBy(this._data)) return this._data.getItem(index); if (this._data instanceof Array) return this._data[index]; } return null; }
moveNext The moveNext method of the DataControl base class enables you to move to the next data record in the bound data collection. As Listing D-17 shows, if the data control is not bound to any data collection, the moveNext method does not do anything. This method begins by invoking the prepareChange method, as usual: var oldState = this.prepareChange();
Next, it calls the get_dataIndex getter to return the current data index, and increments this value by one to arrive at the new value for the current data index: var newIndex = this.get_dataIndex() + 1;
1370
bapp04.indd 1370
8/20/07 8:59:58 PM
Appendix D: Data Control If the new value is not greater than or equal to the total number of data records in the bound collection, it calls the set_dataIndex setter to set the current data index to the new value: if (newIndex < this.get_length()) this.set_dataIndex(newIndex);
Finally, it invokes the triggerChangeEvents method as usual to trigger the necessary events: this.triggerChangeEvents(oldState);
Listing D-17: The moveNext Method function Sys$Preview$UI$Data$DataControl$moveNext() { if (this._data) { var oldState = this.prepareChange(); var newIndex = this.get_dataIndex() + 1; if (newIndex < this.get_length()) this.set_dataIndex(newIndex); this.triggerChangeEvents(oldState); } }
movePrevious As the name suggests, the movePrevious method of the DataControl base class enables you to move to the previous data record of the bound data collection. As Listing D-18 shows, this method begins by calling the prepareChange method as usual: var oldState = this.prepareChange();
Next, it calls the get_dataIndex getter to return the current data index and decrements this value by one to arrive at the new value: var newIndex = this.get_dataIndex() - 1;
If the new value is a positive number, it invokes the set_dataIndex setter to set the current data index to the new value: if (newIndex >=0) this.set_dataIndex(newIndex);
Finally, it invokes the triggerChangeEvents method as usual: this.triggerChangeEvents(oldState);
1371
bapp04.indd 1371
8/20/07 8:59:58 PM
Appendix D: Data Control Listing D-18: The movePrevious Method function Sys$Preview$UI$Data$DataControl$movePrevious() { if (this._data) { var oldState = this.prepareChange(); var newIndex = this.get_dataIndex() - 1; if (newIndex >=0) this.set_dataIndex(newIndex); this.triggerChangeEvents(oldState); } }
onBubbleEvent The DataControl base class overrides the onBubbleEvent method that it inherits from the Control base class, as shown in Listing D-19. Recall that the onBubbleEvent method is where a client control captures the command events raised by its child controls. The DataControl base class’ implementation of this method only handles the select event; that is why the method begins by calling the get_commandName method on its second parameter to determine whether the current event is a select event. If so, it takes these steps to handle the event. First, it calls the get_argument method on its second parameter to return the index of the selected data record: var arg = args.get_argument();
If no data index has been specified, the onBubbleEvent takes these steps to access the current data index, and uses this index as the selected index. First, it invokes the get_dataContext to return a reference to the current data record: var dataContext = source.get_dataContext();
Next, it invokes the get_index method on the current data record to return its index, and uses this index as the selected index: arg = dataContext.get_index();
Next, it calls the set_dataIndex method to specify the selected index as the current data index: this.set_dataIndex(arg);
1372
bapp04.indd 1372
8/20/07 8:59:58 PM
Appendix D: Data Control Listing D-19: The onBubbleEvent Method function Sys$Preview$UI$Data$DataControl$onBubbleEvent(source, args) { if (args.get_commandName() === “select”) { var arg = args.get_argument(); if (!arg && arg !== 0) { var dataContext = source.get_dataContext(); if (dataContext) arg = dataContext.get_index(); } if (arg && String.isInstanceOfType(arg)) arg = Number.parseInvariant(arg); if (arg || arg === 0) { this.set_dataIndex(arg); return true; } } return false; }
descriptor The DataControl base class, like any other ASP.NET AJAX client class, exposes a static property named descriptor that describes its methods and properties to enable its clients to use the ASP.NET AJAX client-side type inspection facilities to inspect its methods and properties generically, without knowing the actual type of the class, as shown in Listing D-20.
Developing a Custom Data Control Listing D-21 presents the content of a JavaScript file named CustomTable.js that contains the implementation of a new version of the CustomTable control that derives from the DataControl base class. As you can see, the render method is where all the action is. This is the method that renders the user interface of the CustomTable custom data control. As you can see, this method begins by invoking the get_data method to return a reference to the data collection bound to the CustomTable data control. This control, like any other data control, inherits the get_data method from the DataControl base class: var dataSource = this.get_data();
Next, the render method raises an exception if the data collection bound to the data control is neither a JavaScript array nor an IData object: if (Sys.Preview.Data.IData.isImplementedBy(dataSource)) isArray = false; else if (!Array.isInstanceOfType(dataSource)) throw Error.createError(‘Unknown data source type!’);
Next, the render method simply iterates through the data records in the data collection bound to the data control to render each record in a
DOM element.
Listing D-21: The Content of the CustomTable.js JavaScript File that Contains the Implementation of the CustomTable Custom Data Control Type.registerNamespace(“CustomComponents”); CustomComponents.CustomTable = function CustomComponents$CustomTable(associatedElement) { CustomComponents.CustomTable.initializeBase(this, [associatedElement]); } function CustomComponents$CustomTable$set_dataFieldNames(value) { this._dataFieldNames = value; } function CustomComponents$CustomTable$get_dataFieldNames() { return this._dataFieldNames; } function CustomComponents$CustomTable$render() { var isArray = true; var dataSource = this.get_data(); if (Sys.Preview.Data.IData.isImplementedBy(dataSource)) isArray = false; else if (!Array.isInstanceOfType(dataSource)) throw Error.createError(‘Unknown data source type!’);
1374
bapp04.indd 1374
8/20/07 8:59:59 PM
Appendix D: Data Control var sb = new Sys.StringBuilder(‘
’); var propertyNames = []; var length = isArray ? dataSource.length : dataSource.get_length(); for (var i=0; i
Using Table Rows and Columns The previous examples used the following components:
❑
A
DOM element, as the template for building the DOM element that contains the DOM elements that display the data records.
❑
A
DOM element, as the template for building the DOM elements that display the data records.
❑
DOM elements, as the template for building the DOM elements that display the data
fields.
1432
bapp06.indd 1432
8/20/07 9:01:11 PM
Appendix F: ListView
Figure F-2 Listing F-4 presents an example in which:
❑
A DOM element is the template for building the DOM element that contains the DOM elements that display the data records.
❑
A
DOM element is the template for building the DOM elements that display the data records.
❑
DOM elements is the template for building the DOM elements that display the data fields.
If you don’t use the and elements, Internet Explorer won’t show the table. Internet Explorer expects dynamically generated tables to include and elements. If you run Listing F-4, you’ll get the result shown in Figure F-3. Note that Listing F-4 registers a JavaScript function named renderCompleteCallback as an event handler for the renderComplete event of the ListView control. The control raises this event when it completes its rendering.
Appendix F: ListView Listing F-4 (continued) function renderCompleteCallback(sender, eventArgs) { alert(“Rendering is completed!”); } function onSuccess(result, userContext, methodName) { userContext.set_data(result); if (firstTime) { firstTime = false; selectionChangedCallback(userContext); } } function onFailure(result, userContext, methodName) { var builder = new Sys.StringBuilder(); builder.append(“timedOut: “); builder.append(result.get_timedOut()); builder.appendLine(); builder.appendLine(); builder.append(“message: “); builder.append(result.get_message()); builder.appendLine(); builder.appendLine(); builder.append(“stackTrace: “); builder.appendLine(); builder.append(result.get_stackTrace()); builder.appendLine(); builder.appendLine(); builder.append(“exceptionType: “); builder.append(result.get_exceptionType()); builder.appendLine(); builder.appendLine(); builder.append(“statusCode: “); builder.append(result.get_statusCode()); builder.appendLine(); builder.appendLine(); builder.append(“methodName: “); builder.append(methodName); alert(builder.toString()); } function selectionChangedCallback(sender, eventArgs) { var authorID = sender.get_selectedValue(); var listView = Sys.Application.findComponent(“listView”); MyWebService.GetBooks(authorID, onSuccess, onFailure, listView); }
1434
bapp06.indd 1434
8/20/07 9:01:13 PM
Appendix F: ListView var firstTime = true; function pageLoad() { var listView = Sys.Application.findComponent(“listView”); listView.set_itemCssClass(“itemCssClass”); listView.set_alternatingItemCssClass(“alternatingItemCssClass”); listView.set_selectedItemCssClass(“selectedItemCssClass”); var authorList = Sys.Application.findComponent(“authorList”); if (!authorList.get_data()) MyWebService.GetAuthors(onSuccess, onFailure, authorList); } Select an author:
Title
Publisher
Price
(continued)
1435
bapp06.indd 1435
8/20/07 9:01:14 PM
Appendix F: ListView Listing F-4 (continued)
1436
bapp06.indd 1436
8/20/07 9:01:14 PM
Appendix F: ListView
Figure F-3
Surrounding the ASP.NET AJAX Classes and Interface The previous sections of this appendix showed you how to use the ListView control and its members in your own Web applications. The rest of this appendix will dive into the internal implementation of the ListView templated client control, where you’ll discover how to:
❑
Extend the functionality of the ListView client control
❑
Implement templated client controls as complex as the ListView client control
This section will discuss the surrounding ASP.NET AJAX classes and interface of the ListView client control — that is, those classes and interface that a templated client control such as ListView uses internally. I’ll begin our discussions with the interface named ITask.
ITask The ITask interface defines the API that every ASP.NET AJAX task must implement to execute a task. A task could be anything. For example, as you’ll see later, the ListView client control uses a rendering task named ListViewRenderTask to render its UI. As Listing F-5 shows, this interface exposes a single method named execute that each subclass of this interface must override to include the logic that executes its associated task. For example, ListViewRenderTask implements this interface and its execute method where it includes the logic that renders the ListView templated data control.
1437
bapp06.indd 1437
8/20/07 9:01:14 PM
Appendix F: ListView Listing F-5: The ITask Interface Sys.Preview.ITask = function Sys$Preview$ITask() { throw Error.notImplemented(); } function Sys$Preview$ITask$execute() { throw Error.notImplemented(); } Sys.Preview.ITask.prototype = { execute: Sys$Preview$ITask$execute } Sys.Preview.ITask.registerInterface(‘Sys.Preview.ITask’);
_TaskManager The ASP.NET AJAX client-side framework comes with an internal class named _TaskManager that manages all the tasks on the current page. Each ASP.NET AJAX page can contain only a single instance of this class. As the boldface portion of Listing F-6 shows, the ASP.NET AJAX framework automatically instantiates this single instance and assigns it to a global variable named Sys.Preview.TaskManager. Therefore, you must use this global variable to access the current instance of the _TaskManager class as opposed to instantiating a new one: Sys.Preview.TaskManager = new Sys.Preview._TaskManager();
I’ll discuss the methods and properties of the _TaskManager class in the following sections.
Listing F-6: The _TaskManager Class Sys.Preview._TaskManager = function Sys$Preview$_TaskManager() { Sys.Application.registerDisposableObject(this); this._tasks = []; } Sys.Preview._TaskManager.prototype = { _timeoutCookie: null, _timeoutHandler: null, addTask: Sys$Preview$_TaskManager$addTask, dispose: Sys$Preview$_TaskManager$dispose, _onTimeout: Sys$Preview$_TaskManager$_onTimeout, _startTimeout: Sys$Preview$_TaskManager$_startTimeout } Sys.Preview._TaskManager.registerClass(‘Sys.Preview._TaskManager’, null, Sys.IDisposable); Sys.Preview.TaskManager = new Sys.Preview._TaskManager();
1438
bapp06.indd 1438
8/20/07 9:01:15 PM
Appendix F: ListView Constructor As Listing F-6 shows, this constructor performs two tasks:
❑
It invokes the registerDisposableObject method on the Application object that represents the current ASP.NET AJAX application, thereby adding the current TaskManager instance to the list of disposable objects that the Application object maintains internally. Sys.Application.registerDisposableObject(this);
Recall that a disposable object is an object whose type implements the IDisposable interface. This interface exposes a method named dispose. The Application object automatically invokes the dispose methods of these disposable objects to allow these objects to perform their final cleanup before they’re disposed of. As Listing F-6 shows, the _TaskManager class implements this interface. Sys.Preview._TaskManager.registerClass(‘Sys.Preview._TaskManager’, null, Sys.IDisposable);
❑
It instantiates an array named _tasks. As you’ll see later, the current TaskManager instance will store all tasks in this array: this._tasks = [];
addTask Call the addTask method on the current TaskManager instance to add a new task to the _tasks array. As you can see from Listing F-7, this method first invokes the enqueue static method on the Array class to enqueue the specified task: Array.enqueue(this._tasks, task);
Next, it invokes the _startTimeout method to schedule the execution of the next task in the _tasks array, as we’ll discuss in the next section: this._startTimeout();
Listing F-7: The addTask Method function Sys$Preview$_TaskManager$addTask(task) { /// Array.enqueue(this._tasks, task); this._startTimeout(); }
1439
bapp06.indd 1439
8/20/07 9:01:15 PM
Appendix F: ListView _startTimeout As Listing F-8 shows, this method first checks whether the current TaskManager instance already has a timeout cookie. If not, it first invokes the createDelegate static method on the Function class to create a delegate that represents the _onTimeout method: this._timeoutHandler = Function.createDelegate(this, this._onTimeout);
Then it invokes the setTimeout method on the window object, passing in the delegate to create a new timeout cookie: this._timeoutCookie = window.setTimeout(this._timeoutHandler,
0);
Listing F-8: The _startTimeout Method function Sys$Preview$_TaskManager$_startTimeout() { if (!this._timeoutCookie) { if (!this._timeoutHandler) this._timeoutHandler = Function.createDelegate(this, this._onTimeout); this._timeoutCookie = window.setTimeout(this._timeoutHandler,
0);
} }
_onTimeout When the window object invokes the _timeoutHandler delegate, this delegate in turn invokes the _onTimeout method. As you can see from Listing F-9, the _onTimeout method invokes the dequeue static method on the Array class to dequeue the next task in the _tasks collection. Recall that dequeuing an item from an array removes the item from the array. var task = Array.dequeue(this._tasks);
Then it invokes the execute method on this task to execute it: task.execute()
If the execute method returns false, the _onTimeout method calls the enqueue static method on the Array class to enqueue the task back in the _tasks collection. This allows the task to be executed again: if (!task.execute()) Array.enqueue(this._tasks, task);
Finally, it checks whether the _tasks collection contains any more tasks. If so, it invokes the _startTimeout method to schedule the execution of the next task: if (this._tasks.length) this._startTimeout();
1440
bapp06.indd 1440
8/20/07 9:01:15 PM
Appendix F: ListView As you can see, the current TaskManager instance executes the tasks in the order in which they’re enqueued in the _tasks collection.
Listing F-9: The _onTimeout Method function Sys$Preview$_TaskManager$_onTimeout() { this._timeoutCookie = 0; var task = Array.dequeue(this._tasks); if (!task.execute()) Array.enqueue(this._tasks, task); if (this._tasks.length) this._startTimeout(); }
dispose As we discussed earlier, the _TaskManager class implements the IDisposable interface. Consequently, the class implements the dispose method, as shown in Listing F-10. The dispose method of the current TaskManager instance, like the dispose method of any other ASP.NET AJAX object, performs its final cleanup before the instance is disposed of. The method begins by invoking the clearTimeout method on the window object to release the timeout cookie: if (this._timeoutCookie) window.clearTimeout(this._timeoutCookie);
Next, it iterates through the remaining tasks in the _tasks collection and invokes the dispose method on each task to allow the task to perform its final cleanup before it is disposed of: if (this._tasks && this._tasks.length) { for (var i = this._tasks.length - 1; i >= 0; i--) { this._tasks[i].dispose(); } }
Finally, it invokes the unregisterDisposableObject method on the Application object that represents the current ASP.NET AJAX application, in order to remove the current TaskManager instance from the list of disposable objects. Recall that the constructor of the TaskManager class added the current TaskManager instance to this list. Sys.Application.unregisterDisposableObject(this);
1441
bapp06.indd 1441
8/20/07 9:01:15 PM
Appendix F: ListView Listing F-10: The dispose Method function Sys$Preview$_TaskManager$dispose() { if (this._timeoutCookie) window.clearTimeout(this._timeoutCookie); if (this._tasks && this._tasks.length) { for (var i = this._tasks.length - 1; i >= 0; i--) { this._tasks[i].dispose(); } } this._tasks = null; this._timeoutHandler = null; Sys.Application.unregisterDisposableObject(this); }
ListViewRenderTask As you can see from Listing F-11, ListViewRenderTask, like any other ASP.NET AJAX task, implements the ITask and IDisposable interfaces. The main responsibility of ListViewRenderTask is to render the specified ListView templated data control. Sys.Preview.UI.Data.ListViewRenderTask.registerClass( ‘Sys.Preview.UI.Data.ListViewRenderTask’, null, Sys.Preview.ITask, Sys.IDisposable);
I’ll discuss the methods and properties of ListViewRenderTask in the following sections.
Constructor As Listing F-12 shows, the constructor of the ListViewRenderTask class takes the parameters shown in the following table:
Parameter
Description
listView
References the ListView templated data control that the current ListViewRenderTask is to render.
Data
References the data collection bound to the ListView.
itemTemplate
References the ASP.NET AJAX Template object that represents the itemTemplate subelement of the ListView control.
itemTemplateParent
References the template DOM element for building the DOM element that acts as a container for the DOM elements that display data records.
separatorTemplate
References the ASP.NET AJAX Template object that represents the separatorTemplate subelement of the ListView control.
itemElements
Contains the DOM elements that display data records. (Keep in mind that the ListView control uses the associated DOM element of the item template as a template for building these DOM elements.) (continued)
1443
bapp06.indd 1443
8/20/07 9:01:16 PM
Appendix F: ListView (continued)
Parameter
Description
separatorElements
Contains the DOM elements that separate consecutive data DOM elements. A data DOM element is a DOM element that displays a data record.
itemClass
Specifies the name of the CSS style class that the execute method of ListViewRenderTask must apply to even-numbered data DOM elements.
alternatingItemClass
Specifies the name of the CSS style class that the execute method of ListViewRenderTask must apply to the oddnumbered data DOM elements.
separatorClass
Specifies the name of the CSS style class that the execute method of ListViewRenderTask must apply to the DOM elements that separate consecutive data DOM elements.
itemFocusHandler
Specifies the delegate that the execute method of ListViewRenderTask must register as an event handler for the focus event of the data DOM elements.
itemClickHandler
Specifies the delegate that the execute method of ListViewRenderTask must register as an event handler for the click event of the data DOM elements.
Appendix F: ListView execute ListViewRenderTask, like any other ASP.NET AJAX task, implements the execute method of the ITask interface as shown in Listing F-13. This method first takes these steps to determine the total
number of records in the data collection:
❑
If the data collection is a JavaScript array, the execute method uses the value of the length property of the data collection.
❑
If the data collection is not a JavaScript array, but it supports a method named get_length, the execute method uses the return value of this method. Data collections that implement the IData interface support this method.
❑
If the data collection is neither a JavaScript array nor supports the get_length method, the execute method uses 0 as the total number of records because the ListView control supports only these two types of data collections. var isArray = Array.isInstanceOfType(this._data); var itemLength = isArray ? this._data.length : (this._data ? (this._data.get_length ? this._data.get_length() : 0) : 0);
Next, the execute method determines how many DOM elements are left to render. Keep in mind that the execute method renders each data record in the data collection in a separate DOM element: var lastElementToRender = Math.min(itemLength, this._currentIndex + 5);
Next, the execute method enters a for loop in which each iteration takes the following steps to render the next record in the data collection. Each iteration begins by accessing the next data record in the data collection, as follows:
❑
If the data collection is a JavaScript array, it uses the current index as an index into the data collection to return the reference to the current data record.
❑
If the data collection is not a JavaScript array, it assumes that the data collection supports a method named getItem and consequently invokes this method, passing in the current index to return a reference to the current data record. var item = isArray? this._data[this._currentIndex] : this._data.getItem(this._currentIndex);
Next, the execute method performs the following tasks if the itemTemplate property of the ListView templated data control has been set. (Page developers use a declarative approach to set the itemTemplate property, adding a subelement to the subelement of the ListView control in xml-script and setting the layoutElement attribute on this subelement to the id HTML attribute of a DOM element on the current page. This tells the ListView control that they want the control to use this DOM element as the template for building the DOM elements that display the data records.)
❑
The execute method invokes the createInstance method on the itemTemplate, passing in two parameters: the first references the clone of the parent DOM element of the DOM element whose id HTML attribute is specified in the layoutElement attribute of the subelement of the element; the second references the current data record — that is, the data record being displayed.
1445
bapp06.indd 1445
8/20/07 9:01:17 PM
Appendix F: ListView var itemTemplateInstance = this._itemTemplate.createInstance(this._itemTemplateParent, item);
❑
The boldface portion of the following excerpt from Listing F-4 shows an example of this parent DOM element, in which the DOM element with the id attribute value of itemContainer is the parent DOM element of the
DOM element with the id attribute value of item. As the bottom boldface portion of this excerpt shows, the layoutElement attribute on the subelement of the subelement is set to the id attribute value of this
DOM element — that is, item. In this case, the execute method passes the clone of the DOM element with the id attribute value of itemContainer as the first parameter of the createInstance method. You may be wondering who clones this DOM element. I’ll answer that question when we discuss the render method of the ListView control. For now, suffice it to say that ListViewRenderTask receives the clone of the DOM element from the render method of the ListView control.
. . .
. . .
. . . . . . . . . . . .
1446
bapp06.indd 1446
8/20/07 9:01:17 PM
Appendix F: ListView ❑
The createInstance method takes these actions under the hood:
❑
Clones the DOM element whose id HTML attribute value is given by the layoutElement attribute on the subelement of the subelement of the ListView control. Keep in mind that cloning this DOM element also clones all its descendant DOM elements. For example, in the case of the excerpt from Listing F-4, the createInstance method clones the
DOM element with the id attribute value of item, including all its descendant DOM elements — that is, the
DOM elements with the id attribute values of title, publisher, and price. In other words, all the DOM elements shown in the boldface portion of the following excerpt (which repeats that of the one preceding) are cloned:
. . .
. . .
. . .
❑
❑
Adds this cloned DOM element, including its descendant elements, as the child element to the cloned DOM element that ListViewRenderTask receives from the render method of the ListView (as mentioned earlier). For example, in the case of this excerpt from Listing F-4, the cloned
DOM element with the id attribute value of item, including its cloned
child elements, is added to the cloned element that ListViewRenderTask receives from the render method.
❑
Instantiates a TemplateInstance object and stores a reference to this cloned DOM element in the instanceElement property of this object, and returns the object to its caller.
Accesses the cloned DOM element that the createInstance method has stored in the instanceElement property of the TemplateInstance object, as we just discussed. For example, in the case of the previous excerpt from Listing F-4, this cloned DOM element is the cloned
DOM element with the id attribute value of item:
1447
bapp06.indd 1447
8/20/07 9:01:17 PM
Appendix F: ListView var element = itemTemplateInstance.instanceElement;
❑
If the current row is an even row, createInstance assigns the CSS style class associated with the item template to the className property of the cloned DOM element. For example, in the case of the previous excerpt from Listing F-4, it assigns the CSS style class name to the className property of the cloned
DOM element with an id attribute value of item. If the current row is an alternating row, it assigns the alternating CSS style class name associated with the item template to the className property of the cloned DOM element: if (this._itemClass) { if ((this._currentIndex % 2 === 1) && (this._alternatingItemClass)) element.className = this._alternatingItemClass; else element.className = this._itemClass; }
❑
Uses the current index as an index into the _itemsElements collection to add the cloned DOM element to this collection. For example, in the case of the previous excerpt from Listing F-4, it adds the cloned
DOM element with the id attribute value of item to the _itemsElements collection. this._itemElements[this._currentIndex] = element;
❑
Sets the dataIndex property of the cloned DOM element to the current index. As you can see, each cloned DOM element in the _itemsElements collection exposes a property named dataIndex that specifies the index of the data record that the cloned DOM element displays. This is the index of the data record in the data collection bound to the ListView control. element.tabIndex = -1; element.dataIndex = this._currentIndex;
❑
Registers the specified handlers as event handlers for the focus and click events of the cloned DOM element. $addHandler(element, “focus”, this._itemFocusHandler); $addHandler(element, “click”, this._itemClickHandler);
Next, if the page developer has specified the element in the xml-script, the execute method performs the following tasks:
❑
Invokes the createInstance method on the separatorTemplate, passing in the reference to the clone of the parent DOM element of the DOM element whose id HTML attribute is specified in the layoutElement attribute of the subelement of the element. This cloned parent DOM element is the same one that ListViewRenderTask passed into the createInstance method of the itemTemplate. var separatorTemplateInstance = this._separatorTemplate.createInstance(this._itemTemplateParent);
1448
bapp06.indd 1448
8/20/07 9:01:18 PM
Appendix F: ListView ❑
❑
The createInstance method takes these steps under the hood:
❑
Clones the DOM element whose id HTML attribute value is given by the layoutElement attribute on the subelement of the subelement of the ListView control. Keep in mind that cloning this DOM element also clones all its descendant DOM elements.
❑
Adds this cloned DOM element as the child element to the cloned DOM element that ListViewRenderTask receives from the render method of the ListView, as mentioned earlier. For example, this cloned DOM element is added to the cloned element that ListViewRenderTask receives from the render method.
❑
Instantiates a TemplateInstance object and stores a reference to this cloned DOM element in the instanceElement property of this object, and returns the object to its caller.
Accesses the cloned DOM element that the createInstance method has stored in the instanceElement property of the TemplateInstance object, as just discussed. var sep = separatorTemplateInstance.instanceElement;
❑
Assigns the CSS style class associated with the separator template to the className property of this cloned DOM element: if (this._separatorClass) sep.className = this._separatorClass;
❑
Uses the current index as an index into the _separatorElements array to store this cloned DOM element into the array. this._separatorElements[this._currentIndex] = sep;
As we discussed earlier, the execute method returns a Boolean value that specifies whether the method is done with rendering all the data records. Recall from Listing F-9 that if the execute method returns false, the _onTimeout method calls the enqueue static method on the Array class to enqueue the task back in the _tasks collection so that it can be executed again. Note that the execute method invokes the _renderTaskComplete method on its associated ListView templated data control to inform the control that the execute method has completed the rendering of all the data records in the data collection bound to the ListView control, and execute returns true to inform the _onTimeout method that it has completed its execution: if (this._currentIndex === itemLength) { this._listView._renderTaskComplete(this); return true; }
1449
bapp06.indd 1449
8/20/07 9:01:18 PM
Appendix F: ListView Listing F-13: The execute Method function Sys$Preview$UI$Data$ListViewRenderTask$execute() { var isArray = Array.isInstanceOfType(this._data); var itemLength = isArray ? this._data.length : (this._data ? (this._data.get_length ? this._data.get_length() : 0) : 0); var lengthm1 = itemLength - 1; var lastElementToRender = Math.min(itemLength, this._currentIndex + 5); for (; this._currentIndex < lastElementToRender; this._currentIndex++) { var item = isArray? this._data[this._currentIndex] : this._data.getItem(this._currentIndex); if (this._itemTemplate) { var itemTemplateInstance = this._itemTemplate.createInstance(this._itemTemplateParent, item); var element = itemTemplateInstance.instanceElement; if (this._itemClass) { if ((this._currentIndex % 2 === 1) && (this._alternatingItemClass)) element.className = this._alternatingItemClass; else element.className = this._itemClass; } this._itemElements[this._currentIndex] = element; element.tabIndex = -1; element.dataIndex = this._currentIndex; $addHandler(element, “focus”, this._itemFocusHandler); $addHandler(element, “click”, this._itemClickHandler); } if (this._separatorTemplate && (this._currentIndex !== lengthm1) && this._itemTemplateParent) { var separatorTemplateInstance = this._separatorTemplate.createInstance(this._itemTemplateParent); var sep = separatorTemplateInstance.instanceElement; if (this._separatorClass) sep.className = this._separatorClass; this._separatorElements[this._currentIndex] = sep; } } if (this._currentIndex === itemLength) { this._listView._renderTaskComplete(this); return true; } else return false; }
1450
bapp06.indd 1450
8/20/07 9:01:18 PM
Appendix F: ListView
ListView The ListView control, like any other ASP.NET AJAX data control, derives from the DataControl base class: Sys.Preview.UI.Data.ListView.registerClass(‘Sys.Preview.UI.Data.ListView’, Sys.Preview.UI.Data.DataControl);
Listing F-14 presents the implementation of the ListView control. I’ll discuss the members of this control in the following sections.
Listing F-14: The ListView Control Sys.Preview.UI.Data.ListView = function Sys$Preview$UI$Data$ListView(associatedElement) { Sys.Preview.UI.Data.ListView.initializeBase(this, [associatedElement]); this._itemElements = []; this._separatorElements = []; } Sys.Preview.UI.Data.ListView.registerClass(‘Sys.Preview.UI.Data.ListView’, Sys.Preview.UI.Data.DataControl);
Constructor As Listing F-15 shows, this constructor, like that of any other ASP.NET AJAX subclass, first invokes the initializeBase method to invoke the constructor of its base class — that is, the DataControl base class: Sys.Preview.UI.Data.ListView.initializeBase(this, [associatedElement]);
Next, it instantiates the following two collections:
❑
_itemElements: This array contains all the cloned DOM elements of the DOM element whose id attribute value is given by the layoutElement attribute on the subelement of the subelement of the element in the xml-script. As we discussed
earlier, each DOM element in this array displays a data record. For example, in the case of the following excerpt from Listing F-4, the _itemElements array contains DOM elements that are the clones of the
DOM element with an id attribute value of item. Each cloned
DOM element in this example displays information about a particular book.
1451
bapp06.indd 1451
8/20/07 9:01:18 PM
Appendix F: ListView . . .
. . .
. . .
❑
_separatorElements: This array contains all the cloned DOM elements of the DOM element whose id attribute value is given by the layoutElement attribute on the subelement of the subelement of the element in the xml-script. As we discussed earlier, each DOM element in this array displays the UI that separates two consecutive data DOM elements. The DOM elements in _itemElements are also known as data DOM elements because they display data records.
Listing F-15: The Constructor of the ListView Control Sys.Preview.UI.Data.ListView = function Sys$Preview$UI$Data$ListView(associatedElement) { Sys.Preview.UI.Data.ListView.initializeBase(this, [associatedElement]); this._itemElements = []; this._separatorElements = []; }
Style Properties In this section I’ll present and discuss the implementation of the style properties of the ListView control. These properties specify the CSS style class names for specific types of rows or items of the ListView control.
1452
bapp06.indd 1452
8/20/07 9:01:19 PM
Appendix F: ListView alternatingItemClass As Listing F-16 shows, the ListView control exposes a getter named get_alternatingItemCssClass and a setter named set_alternatingItemCssClass that you can use to get and set the alternatingItemClass property of the ListView control. This property contains the CSS style class name that will be applied to the alternating rows of the control — that is, to the alternating, or odd, DOM elements in the _itemElements collection. Recall that the DOM elements in this collection display data records. The set_alternatingItemCssClass setter takes effect only if the new value is different from the current value. As you can see from Listing F-16, this setter first assigns the new value to the alternatingItemClass property: this._alternatingItemClass = value;
Next, it invokes the render method to render the ListView control so this change will take effect immediately: this.render();
Finally, it invokes the raisePropertyChanged method to raise the propertyChanged event and consequently to invoke the event handlers registered for this event. The ListView control, like any other, inherits this method from the Component base class. If you need to run some custom code when the value of the alternatingItemClass property changes, you must wrap your code in a method and register the method as an event handler for the propertyChanged event of the ListView control.
Listing F-16: The Getter and Setter Methods for Getting and Setting the alternatingItemClass Property function Sys$Preview$UI$Data$ListView$get_alternatingItemCssClass() { return this._alternatingItemClass; } function Sys$Preview$UI$Data$ListView$set_alternatingItemCssClass(value) { if (value !== this._alternatingItemClass) { this._alternatingItemClass = value; this.render(); this.raisePropertyChanged(‘alternatingItemCssClass’); } }
1453
bapp06.indd 1453
8/20/07 9:01:19 PM
Appendix F: ListView itemClass Listing F-17 presents the implementation of the get_itemCssClass and set_itemCssClass methods of the ListView control, which you can use to get and set the value of the itemCssClass property of the ListView control. This value is applied to the non-alternating, or even, rows of the ListView control — that is, the even-numbered DOM elements in the _itemElements collection. Note that set_itemCssClass doesn’t do anything if the new value is the same as the current value. As you can see, this setter first assigns the new value to the itemClass property: this._itemClass = value;
Next, it invokes the render method to re-render the ListView control so this change will take effect immediately: this.render();
Finally, it calls the raisePropertyChanged method to raise the propertyChanged event: this.raisePropertyChanged(‘itemCssClass’);
If you need to run some custom code when the value of the itemClass property changes, you must wrap your code in a method and register the method as an event handler for the propertyChanged event of the ListView control.
Listing F-17: The Getter and Setter Methods for Getting and Setting the itemClass Property function Sys$Preview$UI$Data$ListView$get_itemCssClass() { return this._itemClass; } function Sys$Preview$UI$Data$ListView$set_itemCssClass(value) { if (value !== this._itemClass) { this._itemClass = value; this.render(); this.raisePropertyChanged(‘itemCssClass’); } }
selectedItemClass Use the get_selectedItemCssClass and set_selectedItemCssClass getter and setter methods to get and set the CSS style class name for the selected row or item of the ListView control, as shown in Listing F-18.
1454
bapp06.indd 1454
8/20/07 9:01:19 PM
Appendix F: ListView Listing F-18: Getting and Setting the selectedItemClass Property function Sys$Preview$UI$Data$ListView$get_selectedItemCssClass() { return this._selectedItemClass; } function Sys$Preview$UI$Data$ListView$set_selectedItemCssClass(value) { if (value !== this._selectedItemClass) { this._selectedItemClass = value; this.render(); this.raisePropertyChanged(‘selectedItemCssClass’); } }
separatorCssClass Use the get_separatorCssClass and set_separatorCssClass getter and setter methods to get and set the CSS style class name for the separator row or item of the ListView control, as shown in Listing F-19. A separator row or item is a row or item that separates two consecutive data rows or items. In other words, the separatorCssClass is applied to the DOM elements in the _separatorElements collection.
Listing F-19: Getting and Setting the separatorClass Property function Sys$Preview$UI$Data$ListView$get_separatorCssClass() { return this._separatorClass; } function Sys$Preview$UI$Data$ListView$set_separatorCssClass(value) { if (value !== this._separatorClass) { this._separatorClass = value; this.render(); this.raisePropertyChanged(‘separatorCssClass’); } }
Template Properties This section will describe the template properties of the ListView control.
emptyTemplate Use the get_emptyTemplate and set_emptyTemplate getter and setter methods to get and set the empty template. The page developer specifies the required markup text between the opening and closing tags of the subelement of the element in the xml-script. As you’ll see later, the ListView control automatically renders this markup if the data collection bound to the ListView control does not contain any data records.
1455
bapp06.indd 1455
8/20/07 9:01:20 PM
Appendix F: ListView As Listing F-20 shows, the set_emptyTemplate setter first invokes the dispose method on the current emptyTemplate. This allows the template to perform its final cleanup before it is disposed of: if (this._emptyTemplate) this._emptyTemplate.dispose();
Next, it assigns the new template to the empty template: this._emptyTemplate = value;
Then it invokes the render method to re-render the ListView control, if the ListView control is not already updating: if (!this.get_isUpdating()) this.render();
Finally, it invokes the raisePropertyChanged method to raise the propertyChanged event and consequently to inform interested clients that the emptyTemplate property has changed its value. Clients express interest in this event by registering an event handler for it.
Listing F-20: Getting and Setting the emptyTemplate Property function Sys$Preview$UI$Data$ListView$get_emptyTemplate() { return this._emptyTemplate; } function Sys$Preview$UI$Data$ListView$set_emptyTemplate(value) { if (this._emptyTemplate) this._emptyTemplate.dispose(); this._emptyTemplate = value; if (!this.get_isUpdating()) this.render(); this.raisePropertyChanged(‘emptyTemplate’); }
itemTemplate Use the get_itemTemplate and set_itemTemplate getter and setter methods to get and set the itemTemplate property. The implementation of these two methods are very similar to that of the getter and setter methods for the emptyTemplate property, as shown in Listing F-21.
1456
bapp06.indd 1456
8/20/07 9:01:20 PM
Appendix F: ListView Listing F-21: Getting and Setting the itemTemplate Property function Sys$Preview$UI$Data$ListView$get_itemTemplate() { return this._itemTemplate; } function Sys$Preview$UI$Data$ListView$set_itemTemplate(value) { if (this._itemTemplate) this._itemTemplate.dispose(); this._itemTemplate = value; if (!this.get_isUpdating()) this.render(); this.raisePropertyChanged(‘itemTemplate’); }
layoutTemplate Use the get_layoutTemplate and set_layoutTemplate getter and setter methods to get and set the layoutTemplate property. The implementation of these two methods are very similar to that of the getter and setter methods for the emptyTemplate property, as shown in Listing F-22.
Listing F-22: Getting and Setting the layoutTemplate Property function Sys$Preview$UI$Data$ListView$get_layoutTemplate() { return this._layoutTemplate; } function Sys$Preview$UI$Data$ListView$set_layoutTemplate(value) { if (this._layoutTemplate) this._layoutTemplate.dispose(); this._layoutTemplate = value; if (!this.get_isUpdating()) this.render(); this.raisePropertyChanged(‘layoutTemplate’); }
separatorTemplate Use the get_separatorTemplate and set_separatorTemplate getter and setter methods to get and set the separator template for the ListView control, as shown in Listing F-23.
1457
bapp06.indd 1457
8/20/07 9:01:20 PM
Appendix F: ListView Listing F-23: Getting and Setting the separatorTemplate function Sys$Preview$UI$Data$ListView$get_separatorTemplate() { return this._separatorTemplate; } function Sys$Preview$UI$Data$ListView$set_separatorTemplate(value) { if (this._separatorTemplate) this._separatorTemplate.dispose(); this._separatorTemplate = value; if (!this.get_isUpdating()) this.render(); this.raisePropertyChanged(‘separatorTemplate’); }
getItemElement The get_itemElement method returns the DOM element in the _itemElements collection with the specified index, as shown in Listing F-24. If you can, always use the style and template properties of the ListView control to customize the UI that renders the data records. The problem with using style and template properties is that they are applied to all data rows or items of the ListView control. If you need to customize a specific data row or item, call the getItemElement method to return a reference to the DOM element that contains the UI that renders this row and performs your row-specific customization on this DOM element.
Listing F-24: The getItemElement Method function Sys$Preview$UI$Data$ListView$getItemElement(index) { return this._itemElements[index]; }
set_dataIndex Listing F-25 contains the implementation of the set_dataIndex method of the ListView control. This method begins by invoking the get_dataIndex method to return the current data index. The ListView control inherits the get_dataIndex method from the DataControl base class. Recall that this method returns the index of the current data record in the data collection bound to the ListView control: var oldIndex = this.get_dataIndex();
Next, it calls the getItemElement method to return a reference to the DOM element that contains the UI that renders the data record with the specified data index: var sel = this.getItemElement(oldIndex);
1458
bapp06.indd 1458
8/20/07 9:01:20 PM
Appendix F: ListView Then it removes the current CSS style class name from this DOM element. This is necessary because we’re about to change the selected item and we need to deselect the current item: if (sel && this._selectedItemClass) Sys.UI.DomElement.removeCssClass(sel, this._selectedItemClass);
Next, it invokes the set_dataIndex of its base class — that is, the DataControl class — to specify the new index as the current data index: Sys.Preview.UI.Data.ListView.callBaseMethod(this, ‘set_dataIndex’, [value]);
Then the set_dataIndex method invokes the getItemElement method to return a reference to the DOM element that contains the UI that displays the new data record with the new data index: sel = this.getItemElement(value);
Finally, it applies the selected style to this DOM element, because this DOM element is now the selected item or row of the ListView control: if (sel && this._selectedItemClass) Sys.UI.DomElement.addCssClass(sel, this._selectedItemClass);
Listing F-25: The set_dataIndex Method function Sys$Preview$UI$Data$ListView$set_dataIndex(value) { var oldIndex = this.get_dataIndex(); if (oldIndex !== value) { var sel = this.getItemElement(oldIndex); if (sel && this._selectedItemClass) Sys.UI.DomElement.removeCssClass(sel, this._selectedItemClass); Sys.Preview.UI.Data.ListView.callBaseMethod(this, ‘set_dataIndex’, [value]); sel = this.getItemElement(value); if (sel && this._selectedItemClass) Sys.UI.DomElement.addCssClass(sel, this._selectedItemClass); } }
itemTemplateParentElementId Use the get_itemTemplateParentElementId and set_itemTemplateParentElementId getter and setter methods to get and set the itemTemplateParentElementId property, as shown in Listing F-26.
1459
bapp06.indd 1459
8/20/07 9:01:21 PM
Appendix F: ListView This property specifies the id HTML attribute value of the DOM element whose clone acts as a container for the DOM elements in the _itemElements collection.
Listing F-26: Getting and Setting the itemTemplateParentElementId Property function Sys$Preview$UI$Data$ListView$get_itemTemplateParentElementId() { return this._itemTemplateParentElementId; } function Sys$Preview$UI$Data$ListView$set_itemTemplateParentElementId(value) { this._itemTemplateParentElementId = value; this.raisePropertyChanged(‘itemTemplateParentElementId’); }
renderComplete The ListView control exposes an event named renderComplete, as shown in Listing F-27. As the name suggests, the ListView control fires this event when it is completely rendered. Use the add_renderComplete method to add a new event handler to the list of those registered for the renderComplete event. Use the remove_renderComplete method to remove an event handler from the list of those registered for this event.
Listing F-27: The renderComplete Event function Sys$Preview$UI$Data$ListView$add_renderComplete(handler) { this.get_events().addHandler(“renderComplete”, handler); } function Sys$Preview$UI$Data$ListView$remove_renderComplete(handler) { this.get_events().removeHandler(“renderComplete”, handler); }
Initialize The ListView control overrides the initialize method that it inherits from its base class, in which it performs several tasks, as can be seen from Listing F-28. First, it invokes the get_element method to return a reference to the DOM element on the current page that represents the ListView control: var element = this.get_element();
Next, it creates a delegate to represent the _onGotFocus method, and stores it in a private field named _focusHandler: this._focusHandler = Function.createDelegate(this, this._onGotFocus);
Then it creates another delegate to represent the _onKeyDown method, and stores it in a private field named _keyDownHandler:
Next, the ListView control creates a third delegate to represent the _onItemFocus method, and stores it in a private field named _itemFocusHandler: this._itemFocusHandler = Function.createDelegate(this, this._onItemFocus);
Then it creates the fourth delegate to represent the _onItemClick method, and stores it in a private field named _itemClickHandler: this._itemClickHandler = Function.createDelegate(this, this._onItemClick);
Next, it invokes the initialize method of its base class to allow the base class to perform its own initialization: Sys.Preview.UI.Data.ListView.callBaseMethod(this, ‘initialize’);
Then it registers the _keyDownHandler and _focusHandler delegates as event handlers for the keydown and focus events of the DOM element that represents the ListView control: $addHandler(element, “keydown”, this._keyDownHandler); $addHandler(element, “focus”, this._focusHandler);
Next, it invokes the initialize method on the item template, if the page developer has specified this template in xml-script: if (this._itemTemplate) this._itemTemplate.initialize();
Next, ListView invokes the initialize method on the separator template, if the page developer has specified this template in xml-script: if (this._separatorTemplate) this._separatorTemplate.initialize();
Next, it invokes the initialize method on the empty template, if the page developer has specified this template in the xml-script: if (this._emptyTemplate) this._emptyTemplate.initialize();
Next, it invokes the initialize method on the layout template, if this template has been specified: if (this._layoutTemplate) this._layoutTemplate.initialize();
Finally, it invokes the render method to render the ListView control: this.render();
1461
bapp06.indd 1461
8/20/07 9:01:21 PM
Appendix F: ListView Listing F-28: The initialize Method function Sys$Preview$UI$Data$ListView$initialize() { var element = this.get_element(); this._focusHandler = Function.createDelegate(this, this._onGotFocus); this._keyDownHandler = Function.createDelegate(this, this._onKeyDown); this._itemFocusHandler = Function.createDelegate(this, this._onItemFocus); this._itemClickHandler = Function.createDelegate(this, this._onItemClick); Sys.Preview.UI.Data.ListView.callBaseMethod(this, ‘initialize’); $addHandler(element, “keydown”, this._keyDownHandler); $addHandler(element, “focus”, this._focusHandler); if (this._itemTemplate) this._itemTemplate.initialize(); if (this._separatorTemplate) this._separatorTemplate.initialize(); if (this._emptyTemplate) this._emptyTemplate.initialize(); if (this._layoutTemplate) this._layoutTemplate.initialize(); if (!element.tabIndex) element.tabIndex = 0; this.render(); }
_onGotFocus Recall from Listing F-28 that the initialize method registered the _focusHandler delegate that represents the _onGotFocus method as an event handler for the focus event of the associated DOM element of the ListView control. Recall that the associated DOM element of a control is the DOM element that represents the control on the current page. When the associated DOM element gains the focus, it automatically invokes the _focusHandler delegate, which in turn invokes the _onGotFocus method. Listing F-29 presents the implementation of this method. This method invokes the setFocus method, passing in the references to the ListView control and the DOM element that displays the selected row of the ListView control, thereby setting the focus on the selected row: this.setFocus(this, this.getItemElement(this.get_dataIndex()));
Listing F-29: The _onGotFocus Method function Sys$Preview$UI$Data$ListView$_onGotFocus(ev) { if (ev.target === this.get_element()) this.setFocus(this, this.getItemElement(this.get_dataIndex())); }
1462
bapp06.indd 1462
8/20/07 9:01:21 PM
Appendix F: ListView setFocus The setFocus method takes two parameters, as shown in Listing F-30. The main responsibility of this method is to set the focus to the DOM element referenced by its second parameter when the ASP.NET AJAX control referenced by the first parameter gains the focus. The first parameter basically references the owner control of the second parameter. As you can see, the setFocus method accesses the associated DOM element of the owner ASP.NET AJAX control: var ownerElement = owner.get_element();
Next, it calls the setTimeout method, passing in a reference to the focus method and specifying the DOM element referenced by the second parameter of the setFocus as the argument of the focus. This instructs the setTimeout method to invoke the focus method and pass this DOM element into it: setTimeout(Function.createCallback(this.focus, element), 0);
Listing F-30: The setFocus Method function Sys$Preview$UI$Data$ListView$setFocus(owner, element) { if (element.focus) { for(var i = owner.get_length() - 1; i >= 0; i--) { var sel = owner.getItemElement(i); if (sel) sel.tabIndex = -1; } var ownerElement = owner.get_element(); var t = ownerElement.tabIndex; if (t === -1) t = ownerElement.__tabIndex; element.tabIndex = t; setTimeout(Function.createCallback(this.focus, element), 0); ownerElement.__tabIndex = t; ownerElement.tabIndex = -1; } }
focus The setTimeout method finally invokes the focus method, passing in the DOM element that needs to grab the focus, as shown in Listing F-31. As you can see, the focus method simply invokes the focus method on this DOM element to set the focus on this DOM element.
1463
bapp06.indd 1463
8/20/07 9:01:22 PM
Appendix F: ListView Listing F-31: The focus Method function Sys$Preview$UI$Data$ListView$focus(element) { try { element.focus(); } catch(e) {} }
_onKeyDown Recall from Listing F-28 that the initialize method registered the _keyDownHandler delegate that represents the _onKeyDown method as an event handler for the keydown event of the associated DOM element of the ListView control. Recall that the associated DOM element of a control is the DOM element that represents the control on the current page. When the end user presses a key while the mouse is over the associated DOM element, the DOM element automatically invokes the _keyDownHandler delegate, which in turn invokes the _onKeyDown method. Listing F-32 presents the implementation of this method. When this method is invoked, a DomEvent object is passed into it. The method begins by retrieving the key code from this DomEvent object: var k = ev.keyCode ? ev.keyCode : ev.rawEvent.keyCode;
The value of the key code determines which key was pressed. The various codes are as follows:
❑
The value of Key.up or Key.left tells the _onKeyDown method that the end user wants to move the focus to the previous row or item in the ListView control. Recall that each data item or row in the ListView control is a DOM element in the _itemElements collection of the ListView control. Also recall that the ListView control maintains in a private field named _focusIndex the index of the DOM element (data row or item) that has the focus. This means that the index of the previous DOM element (data row or item) is nothing but _focusIndex - 1. As you can see, the _onKeyDown method first invokes the getItemElement method, passing in _focusIndex - 1 to return a reference to the previous DOM element (data row or item):
this.getItemElement(this._focusIndex - 1)
Next, it invokes the setFocus method, passing in the reference to this DOM element to have this method set the focus to it: this.setFocus(this, this.getItemElement(this._focusIndex - 1));
If you’re wondering who sets the _focusIndex field of the ListView control, we need to study what happens after the setFocus method is invoked. When the previous DOM element gains the focus, it invokes its focus event. As you’ll see in the following sections, the render method of the ListView control registers a delegate named _itemFocusHandler as an event handler for the focus event of all data rows or items. This delegate represents a method named
1464
bapp06.indd 1464
8/20/07 9:01:22 PM
Appendix F: ListView _onItemFocus, which assigns the data index associated with the DOM element that just gained the focus to the _focusIndex field of the ListView control. Therefore, when the previous DOM element raises its focus event, the _itemFocusHandler delegate — and consequently the _onItemFocus method — is automatically invoked, which in turn sets the _focusIndex field to the data index of the data row or item that just gained the focus. ev.preventDefault();
❑
The value of Key.down or Key.right tells the _onKeyDown method that the end user wants to move the focus to the next data row or item in the ListView control. The_onKeyDown method first invokes the getItemElement method, passing in the index of the next row or item — that is, _focusIndex + 1 — to return a reference to the next DOM element.
this.getItemElement(this._focusIndex + 1)
Next, it invokes the setFocus method, passing in the reference to this DOM element to have this method set the focus to this DOM element: this.setFocus(this, this.getItemElement(this._focusIndex + 1));
Finally, it invokes the preventDefault method on the DomEvent object to prevent the default behavior of the key from taking effect. ev.preventDefault();
Listing F-32: The _onKeyDown Method function Sys$Preview$UI$Data$ListView$_onKeyDown(ev) { if (ev.target === this.getItemElement(this._focusIndex)) { var k = ev.keyCode ? ev.keyCode : ev.rawEvent.keyCode; if ((k === Sys.UI.Key.up) || (k === Sys.UI.Key.left)) { if (this._focusIndex > 0) { this.setFocus(this, this.getItemElement(this._focusIndex - 1)); ev.preventDefault(); } } else if ((k === Sys.UI.Key.down) || (k === Sys.UI.Key.right)) { if (this._focusIndex < (this.get_length() - 1)) { this.setFocus(this, this.getItemElement(this._focusIndex + 1)); ev.preventDefault(); } }
render As the name suggests, the render method is responsible for rendering the ListView control, as shown in Listing F-33.
Listing F-33: The render Method function Sys$Preview$UI$Data$ListView$render() { var associatedElement = this.get_element(); var i, element; for (i = this._itemElements.length - 1; i >= 0; i--) { element = this._itemElements[i]; if (element) Sys.Preview.UI.ITemplate.disposeInstance(element); } this._itemElements = []; for (i = this._separatorElements.length - 1; i >= 0; i--) { element = this._separatorElements[i]; if (element) Sys.Preview.UI.ITemplate.disposeInstance(element); } this._separatorElements = []; if (associatedElement.childNodes.length) { if (this._layoutTemplateElement) Sys.Preview.UI.ITemplate.disposeInstance(this._layoutTemplateElement); } associatedElement.innerHTML = ‘’; var tasksPending = false; var items = this.get_data(); var itemLength = items ? (items.get_length ? items.get_length() : items.length) : (0);
1466
bapp06.indd 1466
8/20/07 9:01:23 PM
Appendix F: ListView if (itemLength && itemLength > 0) { var template = this.get_layoutTemplate(); if (template) { var itemTemplate = this.get_itemTemplate(); var separatorTemplate = this.get_separatorTemplate(); var layoutTemplateInstance = template.createInstance(associatedElement, null, this.findItemTemplateParentCallback, this._itemTemplateParentElementId); var itemTemplateParent = layoutTemplateInstance.callbackResult; this._layoutTemplateElement = layoutTemplateInstance.instanceElement; tasksPending = true; this._pendingTasks++; var renderTask = new Sys.Preview.UI.Data.ListViewRenderTask(this, items, itemTemplate, itemTemplateParent, separatorTemplate, this._itemElements, this._separatorElements, this._itemClass, this._alternatingItemClass, this._separatorClass, this._itemFocusHandler, this._itemClickHandler); Sys.Preview.TaskManager.addTask(renderTask); } } else { var emptyTemplate = this.get_emptyTemplate(); if (emptyTemplate) emptyTemplate.createInstance(associatedElement); var handler = this.get_events().getHandler(‘renderComplete’); if(handler) handler(this, Sys.EventArgs.Empty); } }
This method begins by invoking the get_element method to return a reference to the associated DOM element of the ListView control. The ListView control, like any other ASP.NET AJAX control, inherits the get_element method from the Control base class: var associatedElement = this.get_element();
Next, the render method iterates through the DOM elements in the _itemElements collection of the ListView control, and invokes the disposeInstance static method on the ITemplate class for each
1467
bapp06.indd 1467
8/20/07 9:01:23 PM
Appendix F: ListView enumerated DOM element. The disposeInstance method allows the template to perform a final cleanup before the DOM element is disposed of: for (i = this._itemElements.length - 1; i >= 0; i--) { element = this._itemElements[i]; if (element) Sys.Preview.UI.ITemplate.disposeInstance(element); }
Next, the render method resets the _itemElements collection, which means that all DOM elements in this collection are now disposed of. Such disposal is necessary, because we’re about to re-render the entire ListView control and consequently re-create new data DOM elements: this._itemElements = [];
Next, the render method iterates through the separator DOM elements in the _separatorElements collection, and invokes the disposeInstance static method on the ITemplate interface for each enumerated separator DOM element in order to perform the final cleanup before the DOM element is disposed of. (Recall that a separator DOM element is a DOM element that separates two consecutive data DOM elements. Also recall that a data DOM element is a DOM element that displays a data record.) for (i = this._separatorElements.length - 1; i >= 0; i--) { element = this._separatorElements[i]; if (element) Sys.Preview.UI.ITemplate.disposeInstance(element); }
Then the render method resets the _separatorElements collection, which means that all separator DOM elements are now disposed of. Again, such disposal is necessary because we’re about to re-render the entire ListView control and consequently generate new separator DOM elements: this._separatorElements = []; if (associatedElement.childNodes.length) { if (this._layoutTemplateElement) Sys.Preview.UI.ITemplate.disposeInstance(this._layoutTemplateElement); }
Next, the method resets the inner HTML of the associated DOM element of the ListView control, because we’re about to regenerate this inner HTML: associatedElement.innerHTML = ‘’;
Then it calls the get_data method to return a reference to the data collection bound to the ListView control: var items = this.get_data();
1468
bapp06.indd 1468
8/20/07 9:01:23 PM
Appendix F: ListView Next, it takes one of the following steps to determine the total number of data records in the data collection:
❑
If the data collection supports a method named get_length, it invokes this method to return the total data record count in the collection. Data collections, such as DataTable, that implement the IData interface support the get_length method.
❑
If the data collection does not support the get_length method but does support the length property, it invokes this property to return the total data record count in the collection. Data collections that are JavaScript arrays support the length property.
❑
If the data collection supports neither the get_length method nor the length property, it returns 0 as the total data record count because the ListView control supports only data collections that either implement the IData interface or are JavaScript arrays. var itemLength = items ? (items.get_length ? items.get_length() : items.length) : (0);
Next, the render method invokes the get_layoutTemplate, get_itemTemplate, and get_separatorTemplate methods to return references to the layout template, item template, and separator template, respectively: var template = this.get_layoutTemplate(); var itemTemplate = this.get_itemTemplate(); var separatorTemplate = this.get_separatorTemplate();
Then it invokes the createInstance method on the layout template. Recall that this method takes four parameters:
❑
The first parameter references the container DOM element, which is the associated DOM element of the ListView control in this case.
❑
The second parameter references the data context — that is, the data record being displayed. Since the layout template is not for displaying data records, the render method passes null for this parameter.
❑
The third parameter references the JavaScript function or delegate that the createInstance method automatically invokes after the call into the parseNodes method returns. In this case, the render method passes a reference to the findItemTemplateParentCallback method, which will be discussed later.
❑
The fourth parameter references the context object, which is the id HTML attribute value of the parent DOM element of the layout DOM element. When the createInstance method finally invokes the findItemTemplateParentCallback method, it passes this parameter as is into this method. var layoutTemplateInstance = template.createInstance(associatedElement, null, this.findItemTemplateParentCallback, this._itemTemplateParentElementId);
1469
bapp06.indd 1469
8/20/07 9:01:23 PM
Appendix F: ListView The return value of the createInstance method is an instance of the TemplateInstance class, which exposes two properties. The first is named callbackResult, and contains the return value of the call into the findItemTemplateParantCallback method. As mentioned earlier, the createInstance method internally invokes the findItemTemplateParentCallback method and stores its return value in the callbackResult property of the TemplateInstance object: var itemTemplateParent = layoutTemplateInstance.callbackResult;
The createInstance method internally clones the DOM element whose id HTML attribute value is given in xml-script by the layoutElement attribute on the subelement of the subelement of the element. The createInstance method assigns this DOM element to the instanceElement property of the TemplateInstance object. The render method uses this property to return the reference to this cloned DOM element. this._layoutTemplateElement = layoutTemplateInstance.instanceElement;
Next, the render method increments the pending task count, because we’re about to create a new rendering task: this._pendingTasks++;
Then it creates an instance of ListViewRenderTask. The main job of this task is to render the ListView control. The render method passes all the required information into this task: var renderTask = new Sys.Preview.UI.Data.ListViewRenderTask(this, items, itemTemplate, itemTemplateParent, separatorTemplate, this._itemElements, this._separatorElements, this._itemClass, this._alternatingItemClass, this._separatorClass, this._itemFocusHandler, this._itemClickHandler);
Next, it calls the addTask static method on the current TaskManager to add the new task. As you can see, the render method does not immediately render the ListView control. Instead it schedules a render task with the current TaskManager. As we discussed earlier, the current TaskManager executes each task in the order in which it is scheduled: Sys.Preview.TaskManager.addTask(renderTask);
So far we have discussed the case in which the data collection bound to the ListView control contains data records. Next, you’ll see what the render method does if the data collection is empty. The method begins by calling the get_emptyTemplate method to return a reference to the empty template: var emptyTemplate = this.get_emptyTemplate();
1470
bapp06.indd 1470
8/20/07 9:01:24 PM
Appendix F: ListView Next, it invokes the createInstance method on the empty template to render the markup text that the page developer has specified between the opening and closing tags of the subelement of the element: if (emptyTemplate) emptyTemplate.createInstance(associatedElement);
Finally, it calls the getHandler method on the EventHandlerList object that contains all the event handlers registered for the events of the ListView control, in order to return a reference to the JavaScript function whose invocation automatically invokes all the event handlers registered for the renderComplete event of the ListView control: var handler = this.get_events().getHandler(‘renderComplete’); if(handler) handler(this, Sys.EventArgs.Empty);
_onItemFocus Recall that Listing F-33 passes the _itemFocusHandler delegate that represents the _onItemFocus method into the ListViewRenderTask constructor. As we discussed earlier, ListViewRenderTask registers this delegate as event handler for the focus events of the DOM elements that display the data records. When a DOM element raises this event, the _itemFocusHandler and consequently the _onItemFocus method are automatically invoked. As Listing F-34 shows, this method simply assigns the data index of the data record that the DOM displays to the _focusIndex field of the ListView control: this._focusIndex = ev.target.dataIndex;
This ensures that the _focusIndex field is updated when a DOM element gains a focus, so you know which DOM element has the focus.
Listing F-34: The _onItemFocus Method function Sys$Preview$UI$Data$ListView$_onItemFocus(ev) { if (typeof(ev.target.dataIndex) !== “undefined”) this._focusIndex = ev.target.dataIndex; }
_onItemClick Recall that Listing F-33 passes the _itemClickHandler delegate that represents the _onItemClick method into the ListViewRenderTask constructor. As we discussed earlier, ListViewRenderTask registers this delegate as event handler for the click events of the DOM elements that display the data records. When a DOM element raises this event, the _itemClickHandler and consequently the _onItemClick method are automatically invoked. When this method is invoked, a DomEvent object is passed into it. (Recall that this object is an ASP.NET AJAX wrapper around the event object that the browser creates.) As Listing F-35 shows, the _onItemClick method first invokes the target property on this DomEvent to return a reference to the DOM element that raised the click event: var s = ev.target;
1471
bapp06.indd 1471
8/20/07 9:01:24 PM
Appendix F: ListView Next, it invokes the tagName to return a string that contains the name of the DOM element that raised the event: var srcTag = s.tagName.toUpperCase();
Next, it walks up the containment hierarchy of the DOM element, searching for the first DOM element that supports the dataIndex property. This property contains the index of the data record that the DOM element displays. It’s necessary to walk up the containment hierarchy because the DOM element that raises the click event could be the child element of the DOM element that displays the record. For example, the DOM element that displays the record may contain a button DOM element that raises the click event. Obviously the button DOM element does not support the dataIndex. It is the DOM element that contains the button DOM element that supports the dataIndex property. while (s && (typeof(s.dataIndex) === ‘undefined’)) s = s.parentNode;
Next, the _onItemClick method calls the dataIndex property on the DOM element in the containment hierarchy that supports this property, in order to determine the index of the data record that this DOM element displays: var idx = s.dataIndex;
Next, it invokes the getItemElement, passing in this data index to return a reference to DOM element: sel = this.getItemElement(idx);
Then it invokes the set_dataIndex method to set the data index of this DOM element to the preceding data index: this.set_dataIndex(idx);`
Next, it invokes the setFocus method to set the focus to the specified element, if the element is an input, text area, select, button, or link: if ((srcTag !== “INPUT”) && (srcTag !== “TEXTAREA”) && (srcTag !== “SELECT”) && (srcTag !== “BUTTON”) && (srcTag !== “A”)) this.setFocus(this, sel);
Listing F-35: The _onItemClick Method function Sys$Preview$UI$Data$ListView$_onItemClick(ev) { var s = ev.target; var srcTag = s.tagName.toUpperCase(); while (s && (typeof(s.dataIndex) === ‘undefined’)) s = s.parentNode;
1472
bapp06.indd 1472
8/20/07 9:01:24 PM
Appendix F: ListView if (s) { var idx = s.dataIndex; sel = this.getItemElement(idx); if (sel) { this.set_dataIndex(idx); if ((srcTag !== “INPUT”) && (srcTag !== “TEXTAREA”) && (srcTag !== “SELECT”) && (srcTag !== “BUTTON”) && (srcTag !== “A”)) this.setFocus(this, sel); } } }
findItemTemplateParentCallback Recall that Listing F-33 passes the findItemTemplateParentCallback method and the _itemTemplateParentElementId field into the createInstance method of the layout template. After invoking the parseNodes method, the createInstance method invokes the findItemTemplateParentCallback method, passing the value of the _itemTemplateParentElementId field into it, and stores the return value of this method in the callbackResult property of the TemplateInstance method that the createInstance method returns to its caller. As Listing F-36 shows, the findItemTemplateParentCallback method invokes the findElement method on the current MarkupContext and passes the value of the _itemTemplateParentElementId field into it to return a reference to the DOM element whose id HTML attribute is given by this field.
Listing F-36: The findItemTemplateParentCallback Method function Sys$Preview$UI$Data$ListView$findItemTemplateParentCallback( instanceElement, markupContext, id) { return markupContext.findElement(id); }
The best way to understand the significance of the findItemTemplateParentCallback method is to revisit the internal implementation of the createInstance method of the Template class. I’ll discuss the implementation of this method in the context of an example — the example presented in Listing F-4. Recall from Listing F-33 that the render method of the ListView control calls the get_layoutTemplate method on the ListView control to return a reference to the layout template. var template = this.get_layoutTemplate();
Then it calls the createInstance method on the layout template, passing in four parameters: var layoutTemplateInstance = template.createInstance(associatedElement, null, this.findItemTemplateParentCallback, this._itemTemplateParentElementId);
1473
bapp06.indd 1473
8/20/07 9:01:25 PM
Appendix F: ListView The first parameter references the associated DOM element of the ListView control, which is the DOM element shown in the top highlighted portion of the following excerpt from Listing F-4: . . . . . .
. . .
. . . . . .
The third parameter passed into the createInstance method of the layout template is a reference to the findItemTemplateParentCallback method of the ListView control. The fourth parameter is the id HTML attribute value of the DOM element, shown in the highlighted portion of the following excerpt from Listing F-4:
1474
bapp06.indd 1474
8/20/07 9:01:25 PM
Appendix F: ListView . . . . . .
. . .
. . . . . .
Now let’s walk through the implementation of the createInstance method of the layout template, as shown in Listing F-37.
Listing F-37: The createInstance Method of the Template function Sys$Preview$UI$Template$createInstance(containerElement, dataContext, instanceElementCreatedCallback, callbackContext) { var result = new Sys.Preview.UI.TemplateInstance(); result.instanceElement = this._layoutElement.cloneNode(true); var documentFragment = document.createDocumentFragment(); documentFragment.appendChild(result.instanceElement);
This method begins by creating an instance of the TemplateInstance class: var result = new Sys.Preview.UI.TemplateInstance();
Next, it invokes the cloneNode method on the DOM element shown in the highlighted portion of the following excerpt from Listing F-4: . . . . . .
. . .
1476
bapp06.indd 1476
8/20/07 9:01:25 PM
Appendix F: ListView . . . . . .
The cloneNode method clones this DOM element and creates the following subtree of DOM elements:
Keep two important things in mind. First, the cloneNode method creates a new subtree, which is not part of the current document. This means that you cannot call the getElementById method on the document object to return a reference to any of the DOM elements in the new subtree. Second, the cloneNode method clones the id attribute values as well. This means that all the DOM elements in the new subtree have the same id attribute values as the DOM elements from which they were cloned. As Listing F-37 shows, the createInstance method stores the root node of this new subtree in the instanceElement property of the newly instantiated TemplateInstance object: result.instanceElement = this._layoutElement.cloneNode(true);
Next, the createInstance method creates a new document fragment: var documentFragment = document.createDocumentFragment();
Then it adds the new subtree — that is, the cloned subtree — to this document fragment: documentFragment.appendChild(result.instanceElement);
Again, keep in mind that this document fragment is not part of the current document. It is sitting in memory on its own. Therefore, if you need to access a DOM element in the new cloned subtree you must search for it in this document fragment, not in the document object.
1477
bapp06.indd 1477
8/20/07 9:01:25 PM
Appendix F: ListView Next, the createInstance method creates a new local MarkupContext to represent this document fragment. While the global MarkupContext represents the document object, a local MarkupContext represents a document fragment, which is not part of the document object. var markupContext = Sys.Preview.MarkupContext.createLocalContext(documentFragment, this._parentMarkupContext, dataContext);
Next, the createInstance method invokes the parseNodes method to parse the nodes within the subelement of the subelement of the element in xmlscript. The parseNodes method does not do anything in the case of Listing F-4 because the subelement of the subelement in this case does not contain any child nodes: Sys.Preview.MarkupParser.parseNodes(this._scriptNode.childNodes, markupContext, this._prefixNamespaceMapping);
Next, the createInstance method invokes the findItemTemplateParentCallback method of the ListView control, passing in three parameters. The second parameter references the local MarkupContext that represents the document fragment that contains the cloned subtree. The third parameter contains the id HTML attribute value of the element: result.callbackResult = instanceElementCreatedCallback(result.instanceElement, markupContext, callbackContext);
As you saw from Listing F-36, the findItemTemplateParentCallback method invokes the findElement method on this local MarkupContext to search the cloned subtree for the DOM element. function Sys$Preview$UI$Data$ListView$findItemTemplateParentCallback( instanceElement, markupContext, id) { return markupContext.findElement(id); }
The findElement method returns a reference to the DOM element in the cloned subtree. If you were to call the getElementById method on the document object instead, you would get a reference to the original element in the current document, which is the element shown in the highlighted portion of the following excerpt from Listing F-4: . . . . . .
. . .
1478
bapp06.indd 1478
8/20/07 9:01:26 PM
Appendix F: ListView
. . . . . .
_renderTaskComplete Recall from Listing F-10 that the execute method of ListViewRenderTask invokes the _renderTaskComplete method on the ListView control after it renders the control. As Listing F-38 shows, this method first decrements the pending task count, because the current ListViewRenderTask has completed its execution: this._pendingTasks--;
If no tasks are pending, the _renderTaskComplete method raises the renderComplete event and consequently invokes all the event handlers registered for this event: var handler = this.get_events().getHandler(‘renderComplete’); if(handler) handler(this, Sys.EventArgs.Empty);
Listing F-38: the _renderTaskComplete Method function Sys$Preview$UI$Data$ListView$_renderTaskComplete(renderTask) { this._pendingTasks--; if(this._pendingTasks
