Looking for help with Dojo?

Many frequently asked questions are answered below, but here are a few quick links if you alerady know where you're going:

There are a number of different resources you can find for help with Dojo...to start with, you can look at the Manual, which is a work in progress...there is also the Jot Wiki, which we treat as a kind of "SVN for documentation"...feel free to look through to find what you're looking for.

We also have a mailing list that we maintain for all sorts of questions and answers; if you prefer browser-based access, Open Symphony has gratiously donated space in thier support forums for you to use.

If you're feeling adventurous, you can hit the project developer site for detailed information.

Finally, if you're familiar with IRC, we keep a room open on irc.freenode.net:

The FAQs

Or "Questions and Answers Collected From the Dojo-Interest Mailing List"

(The most current version of this document can be found at http://dojo.jot.com/WikiHome/FAQ)

General

What is dojo?

Read about it here, but the short answer is "a standard library for JavaScript that excells in helping you build responsive apps faster"

What does dojo stand for?

It stands for "a name that won't result in Microsoft's lawyers sending C&D's to Alex".

From Alex Russell: Actually, I was uncreative enough to name my last toolkit "netWindows" so this go-round we actually took a vote. Leondard Lin suggested "Dojo", and it won the vote. It doesn't really stand for anything.

We're different from closed source vendors because we appropriate random words out of *other* languages ;-)

Where is the manual?

Supported Browsers

Common Pitfalls

Why aren't my widgets being instantiated?

Often this is caused by closing tags with /> syntax. For example:

wrong:
<script src="dojo.js" />
<div dojoType="DatePicker" />
	
right:
<script src="dojo.js"></script>
<div dojoType="DatePicker"></div>
	

Are they any HTML references indicating that only the explicit closing tag form works?

And for comparison, the br tag, which does allow the <br /> notation:

Why does IE say I have a syntax error?

You probably have an extra comma at the end of a list. For example:

	var request = dojo.io.bind({
		url: this.actionURL,
		method: 'get',
		content: {
			id: this.rowId,
			field: this.dbField,
			value: this.checkbox.checked
		},  <---- This comma shouldn't be here!
	});
	

Or:

var foo = [ 1 , 2, 3, ];

Or:

var obj = {
	apple: "delicious",
	brussel sprouts: "yucky",
};
	

If I add a comment line in my HTML template file my widget does not render. Why is it so?

It's because the template file is no longer a tree; it's a forest (there are two top level nodes, a comment node and the real node). You can "goose" the widget system by setting dojoAttachPoint="domNode" on what you'd *like* to be the visible root of your widget. That'll work regardless of how many peers or parents that widget has. It's also a great way to implement state-only widgets (state1 -> state2 -> state3 -> etc.).

Why do I get the error "could not download widget XXX"?

I've downloaded the kitchen sink, I've loaded the demo Fisheye page and the I tried copying it into my own page. I get: Error: Could not load "dojo.widget.FisheyeList"; last tried "__package__.js" What am I doing wrong?

Did you copy just the dojo.js file? You will need the src directory too. The widgets are loaded on demand in all builds distributed from dojotoolkit.org. It's possible to build widget resources into a dojo.js file, but that will require a custom build.

Dojo I/O

How do I attach dojo.io.bind to a load function in my own class?

This might be simple, but I can't figure it out: How can I write a self-contained widget that handles its own callback from a dojo.io.bind() call? Specifically, how can I bind the callbacks (load, error) from a dojo.io.bind call to an object's method?

You could use:

 	
this.clicked = function() {
	dojo.io.bind({
		url: this.actionURL,
		method: 'get',
		content: {
			id: this.rowId,
			field: this.dbField,
			value: this.checked
		},
		load: dojo.lang.hitch(this, this.clickSuccess)
	});
}

Can Dojo help me pass query strings and POST data to the server?

Dojo can URL encode the arguments list for you, like so:

function GetRSS(id,url,limit){
	var obj = document.getElementById(id);
	dojo.io.bind({
		url: "http://localhost/rss/getRSS.php",
		content: {rssurl: url, rsslimit: limit},
		load: function(type, data, evt){
			RSSLoaded(obj,data); // error handling needed
		},
		mimetype: "text/plain"
	});
}
	

Receiving JSON data

To receive JSON data, just do:

	
var myVeryCoolObject = null;
var bindArgs = {
	url:  "foo.js",
	type: "text/javascript",
	load: function(type, data, evt){
		myVeryCoolObject = data;
	}
};
dojo.io.bind(bindArgs);
	

Submitting a Form

I want to do a simple procedure, where a user submits a form from the front-end using POST and a success message comes back in a specified div id without page-refresh. How do i do that using dojo.io.bind?

As of Dojo 0.3.0, you can use the dojo.io.updateNode method to simplify the case where you want to do innerHTML replacement.

dojo.io.updateNode("target_div_id", {
	formNode: dojo.byId("your_form_id"),
	method: "post"
});

Using formBind like this also helps to prevent memory leaks since the replaced content will have dojo.event.browser.clean() called over it prior to removal.

Regular-old dojo.io.bind() supports submitting forms and will take it's configuration from the from unless you over-ride it.

dojo.io.bind({
	formNode: dojo.byId("your_form_id"),
	load: function(type, data, evt){/* do something with the return */}
});

In this example we expect the form node that is passed to have action and method properties defined which will determine the url and method arguments to the bind call.

Events

See Event Examples.

Validation

Doesn't Dojo require writing HTML that doesn't validate?

No. Dojo can help you validate. As of the 0.2 release, you can use namespaces for attributes and class declarations to declare the dojo type.

<button class="dojo-button2" dojo:caption="hello world" />

See the fisheye demo for an example.

Performance

See the Performance Tuning Guide.

Packages and dojo.require()

When you call dojo.require("dojo.foo.bar.baz"), Dojo tries to load the following files, in this order:

  1. src/foo/bar/baz.js
  2. src/foo/bar.js
  3. src/foo/bar/__package__.js
  4. src/foo.js
  5. src/foo/__package__.js
and then fail.

When the ".*" suffix is added, Dojo searches for a "__package__.js" file *first*. When you call dojo.require("dojo.foo.bar.baz.*"), Dojo tries to load the following files, in this order:

  1. src/foo/bar/baz/__package__.js
  2. src/foo/bar/baz.js
  3. src/foo/bar/__package__.js
  4. src/foo/bar.js
  5. src/foo/__package__.js
  6. src/foo.js
and then fail.

Custom dojo code

How can I use JavaScript in a namespace outside "dojo"?

Given a folder structure like so:

dojo/
turbo/
	foo.js

...you can use the setModulePrefix method to "register" the namespace for use with the Dojo loading system, like so:

dojo.setModulePrefix("turbo","../turbo"); // relative to the dojo root
dojo.require("turbo.foo");

How can I build a custom profile with code/widgets outside the dojo source tree?

Let's say you have this folder structure:

projects/
	dojo/
		buildscripts/
	foo-project/
		src/
			foo/
				Bar.js

...where projects/foo-project/src/foo/Bar.js contains:

dojo.provide("foo.Bar");
foo.Bar=function(){ ... }

...in your custom profile.js script, you need to specify the module prefixes, something to this effect:

var dependencies = [
	"dojo.io",
	"dojo.event.*",
	"dojo.io.BrowserIO",
	"dojo.xml.Parse",
	"dojo.webui.widgets.*",
	"dojo.webui.DomWidget",
	"dojo.animation.*",
	"foo.Bar"
];

dependencies.prefixes = [
	// this HAS to be relative to DOJO_HOME/ folder
	['foo', '../foo-project/src/foo']
];

load("getDependencyList.js");

Animations

See Animation.

Widgets

See Widgets FAQ.

Tools

IDEs

Using Subversion "externals" to include dojo in your project

If your project uses Subversion for your source code version control, and you need to bundle the dojo toolkit into your project, you can use the Subversion "externals" feature to include dojo "by reference" instead of "by copy". For more info see the subversion manual. Or if you're using TortoiseSVN, see section 5.2.4 of PDF TortoiseSVN manual.

Debugging

Debugging with Firefox

I am attempting to debug code loaded via dojo.require using Venkman. However I am not sure how to place a break point in the loaded code. Does anyone familiar with venkman have a nice solution?

Yes. There's an optional flag available called "debugAtAllCosts" that pulls files in the "expensive" way, in order to provide exactly this. It requires that you include one more line in your usage. Here's how you might use it:

<script>
djConfig = {
	isDebug: true,
	debugAtAllCosts: true
};
</script>
<script src="/path/to/dojo/dojo.js"></script>
<script>
	// dojo includes here
	dojo.require("dojo.myModule");
	dojo.hostenv.writeIncludes(); // this is a new line
</script><!--
		you MUST close the script tag here in order to use debugAtAllCosts
	-->

Once you've structured your code this way, if you open up Venkman, you'll see all the constituent files listed and you can then set breakpoints.

Can I Control Presentation of Dojo Debug Messages?

Is there a way to attach a css style to the dojo debug messages. In my case they always appeared behind some div, so i couldnt see them. How can i specify where they appear?

In djConfig, you can specify which element they are appended to by providing an id of that element: i.e.:

var djConfig={
	isDebug:true,
	debugContainerId:"dojoDebug"
};

for <div id="dojoDebug"></div>

Can I debug with IE?

Yes, use Microsoft Script Editor.

Can I debug with Safari?

The Safari Developer FAQ has some general information about developing with Safari, as well as instructions on how to turn on a debug menu that allows showing a javascript console.

There does not seem to be a venkman-equivalent debugger for Safari though. There is a "dom inspector" type tool, but it requires using a nightly build of Safari.

How do I debug syntax errors? aka How can I find this syntax error in bootstrap?

Sometimes dojo's error messages about syntax errors are really cryptic due to how dojo loads files via dojo.require(); however, you can get a better message by simply directly including the js file with the <script> tag.

There's also a lint program that Brian has recommended.

DOM viewers

When you install Firefox, you should select the option for DOM inspector. This tool shows you the DOM tree after the dojo widgets have been expanded. It's indespensible.

There are similar tools for IE. We recommend Microsoft's own Developer Toolbar.

Javascript shell

While it's not a debugger, we've found the JavaScript Shell to be a really great tool for analyzing problems, and even just exploring JavaScript libraries like dojo. It works best as a Firefox bookmarklet, in which case you can open it in the context of any given page and invoke javascript functions yourself, evaluate expressions, redefine functions, etc.

HTTP monitor/debuggers

HTTP monitors and debuggers are tools that monitor the HTTP traffic to/from the server; they are essential for ajax debugging. For WinXP there is a handy tool called Fiddler; it configures itself as proxy and it's a one click configure and use kind of tool, so it's just easier to use than Achillies and others we've tried. Shows all the parameters from the client going out to the server, and raw text and XML, even compressed HTML coming back; opens up the client so it's not a black box any more.

Ethereal is also very popular.

Dojo culture

What parts of dojo are fairly stable, and what parts are rapidly evolving?

Almost everything is rapidly evolving. There has been some major refactoring between 0.1 and 0.2 and again between 0.2.x and 0.3. This will continue apace until we're much closer to a 1.0 release. If you want to get a sense of how stable something is, one heuristic is to have a look at how many unit tests there are for it, and whether those tests pass.

Unit tests

Does the project have some norms about when unit tests should pass? Are unit tests always supposed to run error free, or is that only true for sections of the code that are fairly old and no longer rapidly evolving?

Unit tests should pass for things that the module maintainer considers to be "working". At any point in time, most unit tests should pass, but many may fail in modules that are still be actively developed. In these cases, module maintainers should be marking untested code using the dojo.experimental function. By running the unit tests and watching for "experimental" warnings you should be able to get some sense of which modules are rapidly evolving and which are fairly stable.

Licenses and legal questions

Can I Combine Dojo with LGPL Software?

Is Dojo compatible with the LGPL, and could parts of Dojo be used and licensed under the LGPL later?

Short answer: yes.

Long answer: a combined work may be created out of Dojo that is distributed under the LGPL so long as you abide by the terms of our licenses. Our licenses are more permissive in every way than the (L)GPL, so the restrictions are subsumed by the subsequent restrictions of the (L)GPL. The AFL gives you sub-licensing rights, but the FSF disputes the compatibility of the AFL with the GPL. Therefore, if you choose to accept Dojo as BSD-licensed software and reproduce our copyright statement (listed below), you may use Dojo in your LGPL software.

If you use all or part of Dojo in an (L)GPL work, the copyright statement you must include is:

Copyright (c) 2004-2006, The Dojo Foundation
All Rights Reserved

See also:

Miscellaneous

How can I define M$-like "behaviors" with Dojo?

dojo.require("dojo.widget.*");
dojo.require("dojo.event.*");

function bindBehavior(obj, funcName){
	if(!funcName){ funcName = obj; obj = dj_global; }
	var lfn = funcName.toLowerCase();
	dojo.widget.tags["dojo:"+lfn] = function(fragment){
		var node = fragment["dojo:"+lfn].nodeRef;
		obj[funcName](node);
	}
	// or use dojo.widget.tags.addParseTreeHandler("dojo:"+lfn)?
}

function mouseoverbehavior(node){
	dojo.event.connect(node, "onmouseover", function(){
		dj_debug("mouse over!");
	});
}
// register a tag handler
bindBehavior("mouseoverbehavior");
	

Can Dojo work with Ruby on Rails?

As of Dojo rev1641 (two major releases ago), you should now be able to drop Dojo into RoR apps without hesitation.

What does dojo.lang.mixin do?

Could somebody explain how dojo.lang.mixin works? This is the code:

dojo.lang.mixin = function(obj, props){
	var tobj = {};
	for(var x in props){
		if(typeof tobj[x] == "undefined"){
			obj[x] = props[x];
		}
	}
	return obj;
}

I just don't get it. It looks like tobj is never changed and always empty producing => all properties are copied from props to obj. What is the purpose of tobj?

dojo.lang.mixin doesn't quite copy all properties, and that is the point of tobj. It copies all properties that are not also properties of the empty object. So it won't clobber any, uh, 'custom' properties of Object.

Adding Functions and Build Scripts

I am just starting out using Dojo and thought I might add a new function to my version of the dojo.html namespace dojo.html.getClassArray. So I have started off as simple as I can get it:

dojo.html.getClassArray = function(){
   alert();
}
		
But not even that works when I call dojo.html.getClassArray(), though the other functions in the namespace continue to work. Is there something I am missing do I need to state somewhere that the function exists or something?

Sounds like the build of dojo.js that you are using includes (the old version of) dojo.html, so your modified html.js file isn't even getting included. You probably want to rebuild dojo.js using the tools in the buildscripts/ directory.

How to Run Code When Dojo is Loaded?

Just getting going with Dojo and don't claim much Javascript experience as well - so this question may be naive... I am trying a basic test to learn how I can tie together event processing across Dojo widgets. In my code below, I am trying to get an external button to control the play/pause on the slideshow. My code is not working - the alerts showup with "0", "undefined" and "undefined" - don't know if I'm missing something.

Before calling dojo.widget.manager.widgets.length dojo needs to be fully initialised (all widgets loaded). This can be tested by calling dojo.addOnLoad(yourInitializationMethod), which will call yourInitializationMethod once Dojo itself is fully loaded.

How to Prevent Default Event Action?

I'd ideally like to be able to say:

<a href="valid url" >Foo</a>
dojo.event.connect(href, "onclick", function(){ 
	new Object().foo(); 
	return false; 
});

The same applies to form submissions, or anything else where returning false can cancel the original event chain. Anyone have any ideas?

You should use event.preventDefault(). Example:

dojo.event.connect(myForm, "onsubmit", function(e){
	e.preventDefault();
	... do some magic ...
});