Dojo The Definitive Guide Matthew A. Russell Beijing • Cambridge • Farnham • Köln • Sebastopol • Taipei • Tokyo Table of Contents Foreword . xiii Preface . xv Part I. Base and Core 1. Toolkit Overview . 3 Overview of Dojo’s Architecture 3 Prepping for Development 7 Terminology 12 Bootstrapping 15 Exploring Dojo with Firebug 21 Summary 31 2. Language and Browser Utilities . 32 Looking Up DOM Nodes 32 Type Checking 33 String Utilities 34 Array Processing 35 Managing Source Code with Modules 40 JavaScript Object Utilities 48 Manipulating Object Context 52 DOM Utilities 55 Browser Utilities 62 Summary 66 vii 3. Event Listeners and Pub/Sub Communication . 67 Event and Keyboard Normalization 67 Event Listeners 70 Publish/Subscribe Communication 76 Summary 79 4. AJAX and Server Communication . 80 Quick Overview of AJAX 80 AJAX Made Easy 82 Deferreds 89 Form and HTTP Utilities 98 Cross-Site Scripting with JSONP 99 Core IO 101 JSON Remote Procedure Calls 110 OpenAjax Hub 112 Summary 113 5. Node Manipulation . 114 Query: One Size Fits All 115 NodeList 121 Creating NodeList Extensions 130 Behavior 131 Summary 135 6. Internationalization (i18n) . 136 Introduction 136 Internationalizing a Module 137 Dates, Numbers, and Currency 140 Summary 143 7. Drag-and-Drop . 144 Dragging 144 Dropping 155 Summary 164 8. Animation and Special Effects . 165 Animation 165 Core fx 176 viii | Table of Contents Animation + Drag-and-Drop = Fun! 185 Colors 186 Summary 194 9. Data Abstraction . 196 Shifting the Data Paradigm 196 Data API Overview 197 The APIs 198 Core Implementations of Data APIs 204 Summary 221 10. Simulated Classes and Inheritance . 222 JavaScript Is Not Java 222 One Problem, Many Solutions 223 Simulating Classes with Dojo 227 Multiply Inheriting with Mixins 237 Summary 241 Part II. Dijit and Util 11. Dijit Overview . 245 Motivation for Dijit 245 Accessibility (a11y) 248 Dijit for Designers 251 The Parser 257 Hands-on Dijit with NumberSpinner 261 Overview of Stock Dijits 266 Dijit API Drive-By 270 Summary 271 12. Dijit Anatomy and Lifecycle . 272 Dijit Anatomy 272 Dijit Lifecycle Methods 275 Your First Dijit: HelloWorld 282 Parent-Child Relationships with _Container and _Contained 293 Rapidly Prototyping Widgets in Markup 293 Summary 295 Table of Contents | ix 13. Form Widgets . 297 Drive-By Form Review 297 Form Dijits 300 TextBox Variations 304 FilteringSelect 323 MultiSelect 324 Textarea Variations 325 Button Variations 325 Slider 333 Form 338 Summary 339 14. Layout Widgets . 340 Layout Dijit Commonalities 340 ContentPane 342 BorderContainer 346 StackContainer 351 TabContainer 353 AccordionContainer 355 Rendering and Visibility Considerations 357 Summary 358 15. Application Widgets . 359 Tooltip 359 Dialog Widgets 360 ProgressBar 364 ColorPalette 366 Toolbar 367 Menu 369 TitlePane 374 InlineEditBox 375 Tree 377 Editor 388 Summary 395 16. Build Tools, Testing, and Production Considerations . 396 Building 396 Dojo Objective Harness (DOH) 407 Browser-Based Test Harness 411 x | Table of Contents Performance Considerations 413 Summary 415 A. A Firebug Primer . 417 B. A Brief Survey of DojoX . 428 Index . 431 Table of Contents | xi Foreword 1 Truth be told, it was DHTML that got me kicked out of college. I still vividly recall the 3 A.M. moments when endless trolling of MSDN documenta- tion and W3C specifications and hundreds of comp.lang.javascript posts all coa- lesced into dozens of “what if...” moments. Like hot brands on the hide of my brain, each of these tiny discoveries would not let their mark off of me until I had exhausted all inroads into making the browser do what I wanted it to. Back then, a small community of folks were all doing the same, feverishly one-upping each other and posting to the DHTMLCentral forums with each new component, technique, or hack to make things work on Netscape. Nothing about 7 A.M. Latin conjugations or endless lectures on Java™ held much appeal by comparison to discovering the true beauty of closures, or finally, completely understanding prototypal inheritance. Even my Christmas holidays were engulfed in JavaScript learning and hacking. I’m sure my girlfriend and my parents worried for me greatly, but they never said anything. From the ashes of my truncated academic career came an understanding of open source (http://opensource.org), lasting friendships, and, eventually, Dojo. Overtime, the job of the DHTML hackerhas changed. We know most of the tricks that we can expect a browser to do, and where there is overlap between browsers, we’ve probably already exploited it...just look at the depth and diversity of modules in Dijit and DojoX. The work of a DHTML/Ajax developer now is to press the avail- able technology into the service of users and developers in ways that are better for end users and developers alike. The story of Dojo is the story of that transition. A beautiful architecture that fails to deliver better things in the lives of users is a fail- ure. Likewise, beautiful graphics and interfaces that aren’t maintainable, can’t be coherently understood by developers, and that make designer/developer collabora- tion harder aren’t going to get us where we want to be. All of us involved with Dojo have matured along with the Web, and with the release of Dojo 1.0 and this book, it’s safe to say that Dojo has fully arrived. The roadmap documents we started so long ago now have all of the boxes checked, sites that serve billions of page views a month lean on Dojo for their entire user experience, and large teams of designers and developers work together to create better experiences on top of the toolkit. xiii These kinds of accomplishments aren’t the work of one person, or even a small team. The numberof people who have contributedto Dojo’s evolution, believed in the project, and worked together to deliver a better Web are too numerous to mention. We copied what we thought were the best bits of the structures of other projects, and the result has been a level playing field and rules that are fair to users, contributors, and sponsors alike. Dojo is proof that open source isn’t just a handy distribution model for closed systems, but that collaborative, open projects can thrive when they adopt policies that let users trust a project and when those inside the project finds ways to trust each other. For all of the technical achievements embodied in the tool- kit, I’m most proud that we’ve done it in the open, with anyone who will join us, and done it honestly. We set out to build a project that values all kinds of contributions, not just code. A project that would help change the tone of open source develop- ment to encourage collegial, civil discourse. A project dedicated to building with the community and not to treat users as “them.” “They” are “us” and this book makes plain the open philosophy underwhich the toolkit was built, and by which we encourage all those reading it to help us evolve it for the future. By the time I met Matthew Russell face-to-face, this book was nearly “in the can.” Open source is funny like that—you can work for years with someone, yet the pieces picked up overmailing lists and IRC don’t fall into place until you’retalking about the mundane and thrilling over a good local ale (or, in a pinch, Guinness). It wasn’t until Matthew and I were comparing notes in an old, small, quiet pub in San Fran- cisco’s North Beach district that it clicked: his technical depth, curiosity, and ability to meet you on your level are the hallmarks of a great teacher. As I reviewed the draft chapters in turn, I found myself constantly deleting what I’d just written by way of critique as Matthew laid out the concepts in just the right order. Matthew’s illumina- tions make Dojo approachable, friendly, and productive. The constant delight of dis- covery that glows so brightly when you talk to Matthew in person are a true gift to this volume. It has been like this forme fornearlyfouryearsnow as I’ve had the chance to put faces to the IRC handles and forum posts. In open source, each person enters your world as a technical problem to be solved, a bug to be fixed, or a feature to be con- sidered. Only later is the full measure of the people you’re working with made plain, and it’s nearly always a breathtaking revelation. The kindness, selfless effort, and tal- ent that are freely given are humbling particularly in light of the personal sacrifices that each person makes to be a part of the project. Matthew’s book is a credit to the amazing team I’ve had the honor to work with. I can’t say that I recommend dropping out of college to work on things that no one will pay you for, but if that fire starts in your brain, don’t ignore it. If it leads you to people only half as wonderful as those I’ve met and now count among my friends, it will be worth every sleepless night. —Alex Russell Cofounder, Dojo Toolkit, and Dojo Foundation President xiv | Foreword Preface2 Users now demand web applications that look and feel like those of the desktop. Home computers have long since become ubiquitous, web browsers are the enabling platform, and virtually everyone on the planet is a potential end user. Software devel- opers are spending more time than ever getting their applications into the browser for a potential audience of millions—many of them trying to grab a handful of the multibillion dollar advertising wave, while others are capitalizing on the sheer ele- gance and convenience of an application that is impressive enough that people will be willing to pay for access to it.