Dojo is quite a lot of things. It has a staggering amount of widgets, to begin with; Dialogs, Panes, Menus, WYSIWYG editors, Buttons, Color pickers, Clocks, Layout Managers and a host of other things- just in the widgets department. Then there’s the very handy encryption package, handy for hashing things coming to and from the server-side, the Drag-n-Drop package which works with nearly any element on the page, the essential Collections API with Java-like iterators and whatnot, and of course the powerful proper Ajax functionality with several bells and whistles of its own.
Apart from the sheer amount of functionality available in dojo, there are a few architectural differences compared to most other frameworks; Dojo uses namespaces. This means that dojo always includes the package names in an object reference. If I want use the very nice for-each loop function, for instance, I have to refer to is like this; “dojo.lang.forEach(listOfThings, myFunc);”, instead of just “forEach(listOfThings, myFunc);”.
It seems to be a lot of trouble and waste a lot of space, but in reality it’s not a big change and it increases readability when debugging or refactoring things later. Another example is that when you want to refer to a DOM element the “dojo way”, you write “dojo.byId(el.id);” instead of prototypes inarguably more compact “$(el.id);” Another big change in philosophy between dojo and prototype is that prototype has a long and glorious history of changing basic javascript objects, such as adding useful new functions to the string object.
This has resulted in collisions or erratic behavior when using other javascript libraries which want to change or assume a certain functionality of the very same function names. By using namespaces, dojo ensures that no collisions occur between itself and any other libraries on the same page.
I’m going to use the dojo API version 0.4.2 in the examples, since the upcoming 0.9 only has reached milestone 2 as of this writing.
Getting the right stuff and copying the right files to your server
You might think that using a javascript-based framework should be dead simple. In many cases it is, but due to de facto standards set up by many smaller frameworks (or libraries), some design choices in dojo requires reading some of the fine print – or reading this article 
. The most important thing to remember is that dojo is more that just the file dojo.js. It is not uncommon for people starting to use dojo to assume that the src/ directory really isn’t needed, and probably is shipped only as a kind of open source service to the developer.
However, when you download and unzip the “standard” dojo package (dojo 0.4.2-ajax), the dojo.js file is only the starting point, the kernel so to speak, of dojo. All real functionality exists – and exists only - in files under the src/ directory. Also, most widgets have a lot of template html files and images that they have to get at, so the short dance version of this point is; Copy everything.
Check the test to see how things are done
The biggest problem the dojo community faces (IMHO) is the lack of a thorough API documentation and walk-through examples. True, there’s a very useful (at least to the intermediate-level dojo hacker) API tool, and there are several good sites which give fairly up-to-date walk-throughs and examples in specific areas. But the really good bits can be found on the test directory which also ships with the standard package.
If you go to http://download.dojotoolkit.org/release-0.4.2/dojo-0.4.2p1-widget you’ll see two interesting directories; demo and tests. The reason I refer to the live URL at the dojo download site is that you might want to poke around at other (upcoming) versions. The demo directory contains a fair number of demos, which are neatly organized in the following sections; Demo Applications (Mail client, Text editor), Effects (Fades, Wipes, Slides, et.c.), Drag and Drop, Storage, RPC, Layout Widgets, Form Widgets and General Widgets (Buttons, Menus, Fisheye menus, Tooltips, et.c.). This is a good place to let your jaw drop a bit and get some inspiration.
But the really good stuff is found under the tests directory. Here you will find unit tests for almost all widgets, layout containers, graphics, and lots of other things you’ll find truly useful. The reason the tests are more useful is that they are short, focussed and sometimes even (drumrolll, please) commented! My recommendation is to check out tests/widget for test_ModalFloatingPane, test_Dialog and test_Menu2_Node for some basic examples on how to use dojo widgets. Although dojo is an Ajax framework, much of the truly sterling functionality it offers has little if anything to do with client-sever communication – as you will find out.