Shane O'Sullivan's technical blog… really ties the room together

Archive for the ‘documentation’ Category

Dojo Demo Engine Update

Posted by Shane O'Sullivan on January 7, 2008

A short while ago I posted about the demo engine I’m writing for the Dojo Ajax Toolkit. Click here to read that post or go to to see it in action.

Update: Version 1.0 of the demo engine has been release. See here.


Since that post, quite a lot of work has gone into both the features and the content of the demo engine, and the development process has solidified nicely. Some of the features include:

  • Tree navigation. A dijit.Tree widget, reading from a remote JSON data store is used to navigate the various demos.
  • Search feature. A dijit.form.ComboBox widget, reading from the same JSON data store as the tree, can be used to dynamically search for demos by matching any part of their name.
  • Theme switcher. A dijit.form.ComboBox widget is used to switch between the CSS styles that Dojo provides.
  • URL addressability. Using a hash identifier (e.g. #Dojo_Query_By%20Class) in the URL of the demo engine causes it to open that demo when it has finished loading. For example, if you click this link, it will open the dojo.query demo showing you how to select nodes by class name. Opening any demo changes the URL in the browser to the URL for that demo, for easy bookmarking.
  • Integrated build process. A simple build script is integrated with the Dojo build process. It builds a JSON data file listing all the existing demos and their respective files. It also builds files with URL links for each demo.


To date, a lot of content has been added. Many, many widgets in Dijit and DojoX
have have been added, including the majority of the Form Controls.

The latest, pretty cool additions have been the IO and dojo.query demos. These cover things such as:

  • Performing a XMLHttpRequest request
  • Using an iFrame transport
  • Submitting a form asynchronously
  • Loading remote JavaScript files from another domain
  • Selecting nodes using CSS selectors with dojo.query
  • Performing operations on the NodeList returned from dojo.query
  • Attaching events to the NodeList returned from dojo.query

File Naming Scheme
A simple file naming scheme is used to add content to the demo framework. Each folder beneath the root folder represents a demo. Each file in a folder must be named the same as the folder, with five possible extensions. For example, given a folder with the name ‘Button‘, the possible files are:

  • Button.html – this contains the demo to be displayed. Any JavaScript code inside <script> tags is executed, and any <link type=”text/css”> and <style> tags have their CSS loaded. The executed code is shown in the View tab, and and the source code is shown in the XML tab. The <html>, <head> and <body> tags are not required.
  • Button.js – this contains pure JavaScript code that performs the same operations as Button.html, if applicable. It is not executed however. It is shown in the JS tab.
  • Button.txt – this contains the text description of the demo. It is loaded above the tabs.
  • Button.links – this contains a JSON array of URL links. The build script transforms these links into HTML, and the result is loaded into the Links tab. One neat feature of this is that all links from sub folders are integrated with the parent folder and displayed in a nested structure. Do, for example, clicking on Dijit will show all the links for all widgets in the Dijit project.
  • Button.full.html – this is standalone demo, that is designed to run outside the demo engine. The View tab provides a link to the external file.
  • sort.txt – this contains a comma separated list of the child folders contained in this folder. It specifies the order in which to display the child demos in the tree. If this file is not specified, then an alphabetical ordering is used.

All of these files are optional. If a file in a folder does not match this naming scheme, it is assumed to be some kind of resource that the demo needs, such as an image or a JSON data file. In this case, the file can be named whatever you like.

The tree structure in the demo engine mirrors the folder layout.

Still To Do

There remains quite a lot of work ahead. There are a few bugs remaining, some more cross browser testing is needed, and of course more content is required, particularly the base Dojo package.

In the relatively near future this should be opened up to the public for development. The Dojo folks are setting up a source control server for community additions, and this demo engine should be part of that. Once that is done, people can start adding all sorts of cool stuff!
Share this post:digg it|kick it|Email it|bookmark it|reddit|liveIt

Posted in Ajax, demo, Demo Engine, dijit, documentation, Dojo, dojo.query, dojox, Javascript, json, open source | 6 Comments »

A new Demo engine for Dojo

Posted by Shane O'Sullivan on December 4, 2007

A couple of weeks ago I saw a cool demo framework for an Ajax toolkit just released as open source. It’s a very slick implementation, with a tree listing all the various demos, and a tabbed area showing the implementation, and the widget in practice.

So, I think to myself, this is exactly what the Dojo Ajax Toolkit is missing! Cut to today, and I’ve put the first rough cut at the demo framework on the web for people’s perusal. Check it out at .

Note: I have written a follow up post here.

Some of the features include:

  • Tree navigation for the demos. Demos can be nested as deep as required.
  • View tab. This shows the widgets in action.
  • HTML tab. This shows how to instantiate the widget using HTML markup.
  • JS tab. This shows how to instantiate the widget using JavaScript code.
  • Links tab. This shows various hyperlinks to alternate content for that demo, e.g. the Dojo Book.
  • Demo description. Gives a text description of the demo.
  • Theme selector. This allows you to change from one CSS theme to another
  • Ability to link to standalone demos that open in a new page. This is useful for large demos that show the integration of many widgets together, and may not fit well within the demo framework itself. See the Dijit/Mail demo for an example of this.
  • A build system that takes a very simple naming scheme for the demos, and creates a JSON data store that the framework runs off of. So, whenever a user adds a new demo, they simply have to re-run the build step, and that’s it! No need for a server side script, so you can run this right off your hard drive.

This is still very much beta code, and there are a couple of errors floating around, but those will of course be hunted down. There are also some Internet Explorer issues that I’ll get to soon, so try this in Firefox for now (update Dec 05 2007 – most of these have been solved, with one or two small bugs remaining). I’m in discussions to get this into the Dojo toolkit, so that the community at large can start adding in demos. I’ve put in quite a few already, but it’s so easy to do that this could become a huge resource for the Dojo community.

If you have any suggestions, please let me know.

Demo Framework
Share this post:digg it|kick it|Email it|bookmark it|reddit|liveIt

Posted in Ajax, demo, dijit, documentation, Dojo, dojox.image, Javascript, json, open source | 6 Comments »

The closest thing to HelloWorld tutorials in Dojo

Posted by Shane O'Sullivan on October 26, 2006

Update: I have released the Dojo Demo Framework which has many, many hello world demos. For more info, see

When it comes to documentation (or lack thereof) for the Dojo Ajax toolkit, possibly the most requested item is a set of HelloWorld tutorials that explain the basics of how to get started with each and every facet of the framework, from widgets to the event system and everything in between. What many people new to the toolkit are not aware of is that this does – kind of – exist in the directory of unit tests that are available at These tests cover the basics of how to use all the different parts of Dojo, and while they’re not particularly well commented (noticing a pattern here?), they all do very simple atomic tasks that are quite easy to understand.

Alternatively, you could pull down a copy of the build from Subversion (go here for instructions how) , and all these unit tests are in the /tests folder.

Posted in Ajax, documentation, Dojo, Javascript, open source, Technical | Leave a Comment »

Dojo documentation getting better by the day!

Posted by Shane O'Sullivan on September 22, 2006

One of the primary criticisms of the Dojo Ajax toolkit is that it’s documentation is at best scattered, and at worst non-existant. The Dojo team, and their many partner companies recognise this fact, and are hard at work to fix it. All Dojo documentation is being consolidated into the Dojo Book, which you can find at, and it’s really starting to fill out nicely.

Another welcome addition is the Dojo Api reference, located at It’s built on top of JsLinker, a new Javascript parser developed by the Dojo team and AOL, which understands the common Dojo constructs, like how widgets are defined etc. While it’s not perfect yet (some elements don’t seem to be parse correctly), it’s definitely getting there.

One of the best kept secrets of the toolkit’s documentation (I’m not sure why it’s been kept quiet up to now… probably just an oversight) is the work that the guys on IBM’s WebSphere Portal team are doing to come up with an Eclipse help system for Dojo. It’s essentially putting the Dojo Book into the Eclipse help system, and is hosted at (Update Feb 13th 2007: this address appears to be down now) Check it out, it’s well worth a read. While it’s not a comprehensive guide to all things Dojo, it’s definitely getting there, and is being added to every day.

One slightly (and I mean slightly) funny thing is that the “Where to find Documentation” page is empty… I presume that’ll be filled in any day now ๐Ÿ™‚

Posted in Ajax, documentation, Dojo, Javascript, open source, Technical | Leave a Comment »

The Cake PHP MVC framework and its Amazing Technicolor Documentation

Posted by Shane O'Sullivan on July 24, 2006

I’ve recently been looking into various MVC frameworks for PHP, and came across the Cake framework. It’s a port of Ruby On Rails to PHP (or as close to a port as possible), emphasising convention over configurabililty. While it’s very impressive from a technical standpoint, that’s not what is so pleasantly surprising about it – plenty of open source projects have very talented programmers contributing to them, making technical prowess a starting point for OS projects, not a destination. No, what surprised me was the amazing level of documentation for the project.CakePhp Logo

Simply put, CakePhp has some of the best, most comprehensive, most relevant and best organised documentation I’ve seen in an open source project. Whenever I had a question of any sort, not only did I find documentation “related” to it, I found full tutorials specifying exactly what I needed. In addition to the great docs at their manual and wiki, the also have a full set of API documentation.

Now, many projects state that they have API documentation by virtue of the fact they have some kind of automatic document generation รก la Javadoc, but in the vast majority of cases this just consists of a listing of the available objects/classes and their functions, with extremely sparse explanations of what the methods/classes actually do, how to work with them, caveats etc. CakePhp has all of this. How they convinced open source developers to spend so much time writing documentation, I’ll never understand, but I as I said, I am very, very happy to see it.

I read a blog post that evaluated a number of PHP MVC frameworks, that stated that one of the main reasons Cake didn’t top its list was the seemingly slow pace of development compared to some of the other frameworks. If this kind of documentation, which provides me with everything I could possibly need, is the result of such “slow” development, I could only wish that more open source developers would slow down a bit.

Posted in cake, cakephp, documentation, mvc, open source, php | 7 Comments »

%d bloggers like this: