Dojo Using the Dojo JavaScript Library to Build Ajax Applications James E. Harmon Upper Saddle River, NJ • Boston • Indianapolis • San Francisco New York • Toronto • Montreal • London • Munich • Paris • Madrid Cape Town • Sydney • Tokyo • Singapore • Mexico City Many of the designations used by manufacturers and sellers to distinguish their prod- Associate Publisher ucts are claimed as trademarks. Where those designations appear in this book, and Mark Taub the publisher was aware of a trademark claim, the designations have been printed with initial capital letters or in all capitals. Acquisitions Editor Debra Williams Cauley The author and publisher have taken care in the preparation of this book, but make no expressed or implied warranty of any kind and assume no responsibility for errors or Development Editor omissions. No liability is assumed for incidental or consequential damages in connec- Michael Thurston tion with or arising out of the use of the information or programs contained herein. Managing Editor The publisher offers excellent discounts on this book when ordered in quantity for bulk purchases or special sales, which may include electronic versions and/or custom covers Kristy Hart and content particular to your business, training goals, marketing focus, and branding Project Editor interests. For more information, please contact: Chelsey Marti U.S. Corporate and Government Sales Copy Editor (800) 382-3419 [email protected] Language Logistics For sales outside the United States please contact: Indexer International Sales Lisa Stumpf [email protected] Proofreader Visit us on the Web: www.informit.com/aw Kathy Ruiz Library of Congress Cataloging-in-Publication Data Technical Reviewer Harmon, James Earl. Eric Foster-Johnson Using the Dojo Javascript library to build Ajax applications / James Earl Harmon. Publishing Coordinator p. cm. Kim Boedigheimer Includes index. Cover Designer ISBN 0-13-235804-2 (pbk. : alk. paper) 1. Ajax (Web site development technology) Gary Adair 2. Java (Computer program language) I. Title. Senior Compositor TK5105.8885.A52H37 2008 Gloria Schurick 006.7’8—dc22 2008021544 Copyright © 2009 Pearson Education, Inc. All rights reserved. Printed in the United States of America. This publication is protected by copyright, and permission must be obtained from the publisher prior to any prohibited reproduction, storage in a retrieval system, or transmission in any form or by any means, electronic, mechanical, photocopying, recording, or likewise. For information regarding permissions, write to: Pearson Education, Inc Rights and Contracts Department 501 Boylston Street, Suite 900 Boston, MA 02116 Fax (617) 671 3447 ISBN-13: 978-0-132-35804-0 ISBN-10: 0-132-35804-2 Text printed in the United States on recycled paper at R.R. Donnelley in Crawfordsville, Indiana. First printing June 2008 Contents at a Glance Foreword xiii Acknowledgments xv About the Author xvi I: A Dojo Tutorial 1 Understanding Dojo: A Tutorial 3 2 Using Dojo for Client-side Validation 25 3 Using Dojo to Work with the Server 35 4 Using Dojo Widgets 51 5 Processing Forms with Dojo 59 II: Dojo Widgets 6 Introduction to Dojo Widgets 67 7 Dojo Form Widgets 91 8 Dojo Layout Widgets 137 9 Other Specialized Dojo Widgets 155 III: Dojo in Detail 10 What Is Dojo? 189 11 Technical Description of Dojo 199 12 Objects and Classes 223 13 Strings and JSON 239 14 Events and Event Handling 249 15 Ajax Remoting 259 16 Working with the DOM 277 17 Testing and Debugging 293 Index 303 Table of Contents Foreword xiii Acknowledgments xv About the Author xvi I: A Dojo Tutorial 1 Understanding Dojo: A Tutorial 3 1.1 Introduction to the Tutorial 3 1.1.1 Goals for this Tutorial 4 1.1.2 Goals for Using Dojo 4 1.2 A Standard HTML Data Entry Form 5 1.2.1 First and Last Name 6 1.2.2 User Name 7 1.2.3 Email Address 8 1.2.4 Address 8 1.2.5 State 8 1.2.6 City 10 1.2.7 Zip Code 10 1.2.8 Service Date 11 1.2.9 Comments 11 1.3 The Plan for Enhancing the Form 12 1.3.1 Including Dojo in the Form 12 1.3.2 Adding Client-side Validation 13 1.3.3 Adding Server-side Features 13 1.3.4 Using Additional Specialized Dojo Widgets 13 1.3.5 Processing the Form 14 1.4 Getting and Running the Source Code 14 1.5 Tutorial Step 1—Including Dojo 15 1.5.1 Download or Create the Source Files 15 1.5.2 Include the Code for the Dojo Toolkit 19 1.5.3 Include Dojo Style Sheets 20 1.5.4 Review All the Code Changes 21 1.5.5 Run the New Page 22 viii Contents 2 Using Dojo for Client-side Validation 25 2.1 Validating Form Fields 25 2.2 Tutorial Step 2—Adding Client-side Validation 26 2.2.1 Validate the First Name Field 27 2.2.2 Validating the Last Name Field 30 2.2.3 Validating the User Name Field 31 2.2.4 Validating the Email Address Field 31 2.2.5 Validating the Address Field 32 2.2.6 Validating the City Field 33 2.2.7 Validating the Zip Code Field 33 3 Using Dojo to Work with the Server 35 3.1 Adding Server-side Features 35 3.2 Tutorial Step 3a—Adding Server-side Validation 36 3.2.1 Assign Event Handler Function 36 3.2.2 Make a Call to the Server 38 3.3 Tutorial Step 3b—Retrieving Data from the Server 43 3.3.1 Select Appropriate Widget for the City Field 43 3.3.2 Get the Value of State and Send to the Server 45 4 Using Dojo Widgets 51 4.1 Adding Dojo Widgets to the Page 51 4.1.1 Dijit—The Dojo Widget Module 52 4.2 Tutorial Step 4—Using Dojo Widgets 52 4.2.1 Use the Dojo DateTextBox Widget 53 4.2.2 Use the Dojo Rich Text Editor Widget 55 5 Processing Forms with Dojo 59 5.1 Using Dojo to Process Forms 59 5.2 Tutorial Step 5—Processing the Form 60 5.2.1 Creating a Dojo Form Widget 60 5.2.2 Intercept Form Submission 61 5.2.3 Check That All Form Elements Are Valid 62 5.2.4 Submitting the Form to the Server 63 Contents ix II: Dojo Widgets 6 Introduction to Dojo Widgets 67 6.1 What Are Widgets? 67 6.2 What Are Dojo Widgets? 68 6.3 Components of a Dojo Widget 70 6.3.1 Widget HTML 70 6.3.2 Widget Styles 74 6.3.3 JavaScript Component of a Widget 76 6.3.4 Dojo Widget Hierarchy 78 6.3.5 Visual Overview of Dojo Widgets 83 6.3.6 Building Your Own Widgets 90 7 Dojo Form Widgets 91 7.1 Standard Forms and Dojo Form Widgets 91 7.1.1 The dijit.form._FormWidget Class 92 7.2 The Dojo Form Widget Explained 94 8 Dojo Layout Widgets 137 8.1 Understanding Page Layout 137 8.1.1 The dijit.layout._LayoutWidget Class 138 8.2 Explanation of Dojo Layout Widgets 139 9 Other Specialized Dojo Widgets 155 9.1 What Are Specialized Widgets? 155 9.2 Menu Widget 156 9.2.1 dijit.Menu 157 9.2.2 dijit.MenuItem 157 9.2.3 dijit.MenuSeparator 157 9.2.4 dijit.PopupMenuItem 158 III: Dojo in Detail 10 What Is Dojo? 189 10.1 History of JavaScript and AJAX 189 10.2 History of Dojo 191 10.3 Purpose of Dojo 191 x Contents 10.4 Description of Dojo 192 10.5 What Problems Does Dojo Solve? 193 10.6 Who Should Use Dojo? 194 10.7 Licensing 195 10.8 Competitors and Alternatives 195 10.9 The Future of Dojo 197 11 Technical Description of Dojo 199 11.1 What You Get in the Dojo Download 199 11.2 Organization of Dojo Source Code 201 11.2.1 First-level Directories 201 11.2.2 Digging Deeper into the Dojo Directory 202 11.3 Dojo Modules and Features 203 11.3.1 Naming Conventions and Name Space 204 11.3.2 Dojo Base Module 205 11.3.3 Dojo Core Modules 217 12 Objects and Classes 223 12.1 Objects Explained 223 12.1.1 Creating Objects 224 12.1.2 Encapsulation 224 12.1.3 Object Templates 225 12.1.4 JavaScript Prototypes 227 12.2 Using Dojo to Work with Objects 228 12.2.1 Dojo Function: dojo.declare 229 12.3 Defining a Class 229 12.3.1 Superclasses and Inheritance 231 12.3.2 API for dojo.declare 231 12.3.3 Other Dojo Functions 233 12.3.4 Object Graphs and Dot Notation 234 13 Strings and JSON 239 13.1 Text Strings 239 13.1.1 Dojo Function: dojo.string.pad 240 13.1.2 Usage Example for dojo.string.pad 241 13.1.3 Dojo Function: dojo.string.substitute 241 13.1.4 Usage Example for dojo.string.substitute 243 Contents xi 13.2 JSON 244 13.2.1 Dojo Function: dojo.toJson 246 13.2.2 Usage Example for dojo.toJson 246 13.2.3 Dojo Function: dojo.fromJson 247 14 Events and Event Handling 249 14.1 Description of the Event Model 249 14.1.1 What Are Events? 250 14.1.2 Additional Dojo Events 251 14.2 Defining and Assigning Event Handlers 252 14.2.1 Using dojo.connect to Assign Event Handlers 252 14.2.2 Usage Example for Assigning Event Handlers 253 14.3 Representing an Event as an Object 254 14.4 Using Aspect Oriented Programming in Dojo 256 15 Ajax Remoting 259 15.1 Remoting 259 15.2 Review of XMLHttpRequest (or XHR for Short) 260 15.2 The dojo.xhrGet Function 261 15.3.1 Parameters in Detail 264 15.4 dojo.xhrPost 264 15.4.1 Usage Example—Error Handling 268 15.5 Working with Forms 269 15.5.1 Dojo Function dojo.formToObject 270 15.5.2 Dojo Function dojo.objectToQuery 271 15.5.3 Dojo Function dojo.formToQuery 272 15.5.4 Dojo Function dojo.formToJson 274 15.5.5 Dojo Function dojo.queryToObject 274 16 Working with the DOM 277 16.1 Finding Needles in the DOM Haystack 277 16.2 Dojo Query 278 16.2.1 CSS Selectors 279 16.2.2 Using Selectors in dojo.query 282 16.2.3 Using DOM Elements Found by dojo.query 283 xii Contents 16.3 Animation 283 16.3.1 Understanding Animation 283 16.3.2 Dojo Animation Function 285 16.3.3 Standard Animation Effects 286 17 Testing and Debugging 293 17.1 Testing 293 17.1.1 Unit Testing 294 17.1.2 DOH—The Dojo Unit Testing Framework 294 17.1.3 Other Types of Testing 298 17.2 Logging 298 17.2.1 Basic Logging 299 17.2.2 Advanced Logging 300 Index 303 Foreword If there is one lesson to be learned from the Dojo Toolkit,it is “Be careful what you wish for!”When we first started Dojo, we had the modest goal of creating a JavaScript toolkit that would be useful and would prevent expert JavaScript developers from having to reinvent the wheel.With the buzz and excitement that would soon follow with the emergence of the term Ajax, we quickly found ourselves as the creators of a toolkit used by thousands and thousands of developers and millions of users in a very short time.