Mastering Dojo: JavaScript and Ajax Tools for Great Web Experiences

545 Pages·2008·11.12 MB·English

by  Craig Riecke

What readers are saying about Mastering Dojo
I’m so glad to see this book released. Dojo has a lot of power, but
there’salso a lot of complexity to knowing which API methods to use
when, and how to use them, and this book goes beyond just explain-
ing the Dojo API to explaining what developers need to know to use it
effectively.
Bill Keese
Project lead for Dijit
IBM, Emerging Technology Group
Mastering Dojo will teach you how to build an Internetapplication
that will impress your end users and delight you while you’re writing
it. The book also explains Dojo’s JavaScript underpinnings, both for
newcomers and for refugees from other languages.
Ian Dees
Softwareengineer
The book really rolls out the red carpet for Dojo to emerge with guns
blazing! The authors show you how easy it is to use impressive
widgets without installing a thing. I was amazed to discover that
JavaScript is not just a toy language, how Dojo is built on top of it,
and how both are invaluable in any web development project. Buy
this book. It’s the next best thing to having the authors working at
your side.
Brian C. Reeve
Application developer, bluecomIT.com
Mastering Dojo is an understandable, in-depth guide to learning the
Dojo Toolkit. It’s a great supplement to the Dojo Toolkit’s online docu-
mentation.
Steve Orvell
Senior Engineer, WaveMaker Software
Mastering Dojo
JavaScript and Ajax Tools
for Great Web Experiences
Rawld Gill
Craig Riecke
Alex Russell
The Pragmatic Bookshelf
Raleigh,NorthCarolina Dallas,Texas
Many of the designations used by manufacturers and sellers to distinguish their prod-
uctsareclaimedastrademarks.Wherethosedesignationsappearinthisbook,andThe
Pragmatic Programmers, LLC was aware of a trademark claim, the designations have
been printed in initial capital letters or in all capitals. The Pragmatic Starter Kit, The
PragmaticProgrammer,PragmaticProgramming,PragmaticBookshelfandthelinkingg
devicearetrademarksofThePragmaticProgrammers,LLC.
The Browser Application Framework code is Copyright © 2000-2008, Vista Information
Technologies,Inc.,andreleasedundertheBSDlicense.
Every precaution was taken in the preparation of this book. However, the publisher
assumesnoresponsibility for errorsor omissions,or for damagesthatmay result from
theuseofinformation(includingprogramlistings)containedherein.
Our Pragmatic courses, workshops, and other products can help you and your team
create better software and have more fun. For more information, as well as the latest
Pragmatictitles,pleasevisitusat
http://www.pragprog.com
Copyright©2008RawldGill,CraigRieckeandAlexRussell.
Allrightsreserved.
Nopartofthispublicationmaybereproduced,storedinaretrievalsystem,ortransmit-
ted, in any form, or by any means, electronic,mechanical,photocopying, recording, or
otherwise,withoutthepriorconsentofthepublisher.
PrintedintheUnitedStatesofAmerica.
ISBN-10:1-934356-11-5
ISBN-13:978-1-934356-11-1
Printedonacid-freepaperwith50%recycled,15%post-consumercontent.
Contents
1 Introduction 9
1.1 Key Aspects of Dojo . . . . . . . . . . . . . . . . . . . . . 12
1.2 Using the Book . . . . . . . . . . . . . . . . . . . . . . . 15
1.3 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 17
I Ajax the Dojo Way 19
2 Powerful Web Forms Made Easy 20
2.1 What Customers Are Saying About Your Form . . . . . 21
2.2 Installing Dojo on Your Own Server. . . . . . . . . . . . 21
2.3 Adding Dojo and Dijit to a Page . . . . . . . . . . . . . . 22
2.4 Laying Out the Form . . . . . . . . . . . . . . . . . . . . 26
2.5 Improved Form Controls . . . . . . . . . . . . . . . . . . 31
2.6 Wrapping It Up . . . . . . . . . . . . . . . . . . . . . . . 34
3 Connecting to Outside Services 37
3.1 Dojo Remote Scripting . . . . . . . . . . . . . . . . . . . 37
3.2 JavaScript Idioms for Calling XHR . . . . . . . . . . . . 39
3.3 A Wish List with dojo.data and dojox.grid.Grid . . . . . . 46
3.4 Researching Cigars Using JSONP . . . . . . . . . . . . . 56
3.5 Reviews with dojo.xhrGet . . . . . . . . . . . . . . . . . 63
3.6 Errors and Debugging . . . . . . . . . . . . . . . . . . . 67
II The Dojo APIs 70
4 Dojo In Depth 71
4.1 Modularizing JavaScript . . . . . . . . . . . . . . . . . . 71
4.2 Dojo Source Code Organization . . . . . . . . . . . . . . 75
4.3 Loading Dojo . . . . . . . . . . . . . . . . . . . . . . . . . 78
CONTENTS 6
5 JavaScript Language Extensions 83
5.1 Binding with dojo.hitch. . . . . . . . . . . . . . . . . . . 83
5.2 JavaScript 1.6 Array Methods . . . . . . . . . . . . . . . 90
5.3 Support for Polymorphism . . . . . . . . . . . . . . . . . 94
5.4 Combining, Structuring, and Copying Objects . . . . . 96
6 Asynchronous Programming 101
6.1 Programming DOM Events with Dojo. . . . . . . . . . . 101
6.2 Connecting to User-Defined Events with Dojo . . . . . 117
6.3 Publish-Subscribe . . . . . . . . . . . . . . . . . . . . . . 120
6.4 Managing Callbacks with dojo.Deferred . . . . . . . . . 123
7 DOM Utilities 140
7.1 Core Dojo DOM Utility Functions . . . . . . . . . . . . . 140
7.2 Finding and Editing Nodes . . . . . . . . . . . . . . . . . 145
7.3 Inserting, Moving, and Deleting DOM Nodes . . . . . . 158
7.4 Positioning DOM Nodes . . . . . . . . . . . . . . . . . . 161
7.5 Animation . . . . . . . . . . . . . . . . . . . . . . . . . . 168
8 Remote Scripting with XHR, script, and iframe 178
8.1 Native Remote Scripting . . . . . . . . . . . . . . . . . . 178
8.2 Using the Dojo XHR Framework . . . . . . . . . . . . . 180
8.3 Remote Scripting with script. . . . . . . . . . . . . . . . 199
8.4 Remote Scripting with iframe . . . . . . . . . . . . . . . 207
8.5 Leveraging Remote Scripting to Access Web Services . 211
8.6 Bookmarking and the Back Button Without Navigating 218
9 Defining Classes with dojo.declare 225
9.1 Why Use Object-Oriented Programming in JavaScript? 225
9.2 Defining a Simple Class . . . . . . . . . . . . . . . . . . 226
9.3 Defining a Subclass with Single Inheritance . . . . . . 234
9.4 Mixins and Multiple Inheritance . . . . . . . . . . . . . 239
9.5 Preprocessing Constructor Arguments . . . . . . . . . . 248
9.6 Resolving Property Name Clashes . . . . . . . . . . . . . 252
9.7 Two-Phase Construction . . . . . . . . . . . . . . . . . . 255
9.8 Creating Custom Objects Without Constructors . . . . 257
10 dojo.data 260
10.1 The Big Picture . . . . . . . . . . . . . . . . . . . . . . . 261
10.2 dojo.data and Incremental Search . . . . . . . . . . . . 268
10.3 Partitioning with QueryReadStore . . . . . . . . . . . . 272
10.4 Calling Read Methods fromJavaScript . . . . . . . . . . 275
10.5 A Yahoo Search Driver . . . . . . . . . . . . . . . . . . . 280
CONTENTS 7
11 The Dojo Loader and Build System 286
11.1 The Big Picture . . . . . . . . . . . . . . . . . . . . . . . 287
11.2 The Dojo Loader . . . . . . . . . . . . . . . . . . . . . . . 290
11.3 Optimizing Deployment with the Dojo Build System . . 299
11.4 Compressing JavaScript Resources with Dojo-Rhino . 313
III Advanced Dijit 318
12 Scripting Widgets 319
12.1 What Exactly Is a Widget? . . . . . . . . . . . . . . . . . 319
12.2 Finding and Manipulating Declarative Widgets . . . . . 322
12.3 Creating Instances Programmatically . . . . . . . . . . 327
12.4 Extension Points . . . . . . . . . . . . . . . . . . . . . . 331
12.5 Example: Live Forms . . . . . . . . . . . . . . . . . . . . 338
13 Tree 341
13.1 A Simple Tree . . . . . . . . . . . . . . . . . . . . . . . . . 341
13.2 Hierarchical Data Stores . . . . . . . . . . . . . . . . . . 344
13.3 Extension Points . . . . . . . . . . . . . . . . . . . . . . 349
13.4 Manipulating the Tree . . . . . . . . . . . . . . . . . . . . 351
13.5 Drag and Drop . . . . . . . . . . . . . . . . . . . . . . . . 356
14 Grid 366
14.1 Grid Display and Design . . . . . . . . . . . . . . . . . . 367
14.2 Programmatic Structures . . . . . . . . . . . . . . . . . 372
14.3 Extension Points . . . . . . . . . . . . . . . . . . . . . . 375
14.4 Cell Editing . . . . . . . . . . . . . . . . . . . . . . . . . . 385
14.5 Grid Manipulation . . . . . . . . . . . . . . . . . . . . . . 389
15 Form Controls 394
15.1 Form Control Features . . . . . . . . . . . . . . . . . . . 394
15.2 Streamlined Editing . . . . . . . . . . . . . . . . . . . . . 397
15.3 Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
15.4 Dates, Numbers, and i18n . . . . . . . . . . . . . . . . . 409
15.5 Action Buttons, Toolbars, and Menus . . . . . . . . . . 418
15.6 A11y. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
16 Dijit Themes, Design, and Layout 428
16.1 Theme Structure . . . . . . . . . . . . . . . . . . . . . . 428
16.2 Changing Look and Feel . . . . . . . . . . . . . . . . . . 435
16.3 A11y and Themes . . . . . . . . . . . . . . . . . . . . . . 440
16.4 Panes: ContentPane and TitlePane . . . . . . . . . . . . 442
CONTENTS 8
16.5 The Alignment Container: BorderContainer . . . . . . . 447
16.6 Stack Containers . . . . . . . . . . . . . . . . . . . . . . 451
17 Creating and Extending Widget Classes 455
17.1 Widget Classes Using dijit.Declaration . . . . . . . . . . 456
17.2 Widget Classes Using dojo.declare . . . . . . . . . . . . 461
17.3 The Widget Life Cycle . . . . . . . . . . . . . . . . . . . . 466
17.4 Extending Widgets . . . . . . . . . . . . . . . . . . . . . 469
17.5 Example: A Yahoo Answers Widget . . . . . . . . . . . . 470
IV Rich Internet Applications 476
18 Building a Rich Internet Application 477
18.1 The Big Picture . . . . . . . . . . . . . . . . . . . . . . . 477
18.2 Step 1: Create the Application Skeleton . . . . . . . . . 486
18.3 Step 2: The Main Menu and Command System . . . . . 491
18.4 Step 3: A Custom Statusbar Widget . . . . . . . . . . . 499
19 Adding Dynamic Content to an RIA 505
19.1 Step 4: The Navigator Pane and On-Demand Data Store 505
19.2 Step 5: Workspace Objects . . . . . . . . . . . . . . . . . 515
20 Going Forward 529
20.1 Foundations . . . . . . . . . . . . . . . . . . . . . . . . . 529
20.2 Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
20.3 Dojo Data and Storage . . . . . . . . . . . . . . . . . . . 532
V Appendixes 533
A Bibliography 534
Index 536
OhKate,nicecustomscurtsytogreatkings.DearKate,you
andIcannotbeconfinedwithintheweaklistofacountry’s
fashion.Wearethemakersofmanners.
WilliamShakespeare,HenryV
Chapter 1
Introduction
There’s a new king in town.
Over the past couple of years we’ve seen new technologies redefine the
rules of server-side web app development. It’s the client’s turn. Get
ready to throw out your current “customs” of client-side development.
With Dojo, we’re entering a new era of browser-based applications.
Dojoisasetoftoolsthathelpsyoubuildbetterbrowser-basedapplica-
tions. Dojo is built mostly using client-side JavaScript, and it expands
the capabilities of the modern browser (and even Internet Explorer) far
enough that the line between local, native applications and browser-
based applications has all but disappeared.
This is a pretty significant statement. It means that browser-based
(and, therefore, web-based) user interfaces can be made indistinguish-
ablefromthoseincluded withthebest local, nativeapplications. And it
means thattheuser interfaceof local applications can be implemented
inthebrowserratherthanthroughoneoftheheavy,platform-sensitive,
andcomplex nativeGUIframeworks(Windows,Tk, Qt,Fox, AWT,SWT,
Swing, Cocoa, and the rest).
The ubiquitous browser becomes the user interface platform. It no
longer matters where the back end lives: on a network of distant HTTP
serversor in a small local programthatimplements theHTTP protocol.
Unfortunately, the “modern” browser provides an incomplete, incon-
venient, and incompatible programming environment. You could get
around these problems using a plug-in such as ActionScript, but this
breaksanimportantrule:locallyinstalledsoftwareisstrictlyforbidden.
CHAPTER 1. INTRODUCTION 10
Although it may be OK to break this rule for a local application, it is
certainly not OK to break it for a web-based application.1 Enter Dojo.
Dojo fixes browser defects such as browser incompatibilities and mem-
ory leaks, and it adds important capabilities such as HTML user inter-
face controls and DOM querying. Although many JavaScript libraries
are available, most focus on one particular idea. Some include effects
libraries, others concentrate on perceived core JavaScript omissions,
and still others implement one or more HTML widgets (user interface
controls).Incontrast,Dojoaddressesallofthesefunctionalareas—and
manyothers—extensively.Inthisrespect,wesaythatDojohasbreadth
and depth unlike any other open source solution.
Forexample, looking atDojo’s depth,Dojonormalizestheeventsystem
amongthepopular browsers(InternetExplorerdoesnotimplementthe
W3C event model, and it leaks memory; most other browsers do the
opposite). If you want to connect to a click event in Dojo, you can write
the following:
dojo.connect(myButton,"click",myFunction);
Thiscodewillworkperfectlyonanysupportedbrowser.Youcaninclude
a tree control on a web page by writingthis:
<divdojoType="dijit.Tree"label="Order"id="ordTree"store="ordJson"></div>
This is quite a bit easier than what’s required in many native frame-
works.
Dojo also has incredible breadth. It includes some forty user interface
controls, a graphics framework, cometd support,2 a packaging system,
and much more. Today, Dojo stands alone in its vast capabilities.
You maybeconcernedthatall ofthiscapability implies increasedcom-
plexity. We think theopposite it true—at least if you compare apples to
apples. Dojo is organized into a hierarchy of functionality. This allows
you to focus on just the area you need for the current work at hand.
As your needs change and expand, Dojo will be ready to answer those
needs precisely because of its breath and depth. Contrast this to a
smaller, less-ambitious library. Although such an alternative may be
1. In the corporate world, installing anything on company computers is a big deal. If
you eliminate this road block, you can instantly open markets that were previously
untouchable.
2. Cometd is a low-latency communications technique that allows the server to push
datatothebrowser.Seehttp://cometd.com/.