Questions and Answers Collected from the dojo-interest Mailing List

General

What is dojo?

See this link

What does dojo stand for?

It stands for "a name that won't result in Microsoft's lawyers sending

C&D's to Alex".

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.

> I'm assuming that I didn't just join a

> mailing list dedicated to training the Japanese arts of self-defense.

We're different from closed source vendors because we appropriate random

words out of *other* languages  ;-)

Regards

-- Alex Russell

Where is the manual?

• the manual
• tutorials, etc.
• or learn by example: tests and demos
• the book - currently being written

Supported Browsers

- Latest Safari (2.0.x today).

- Latest Opera (8.5 today, 9.0 soon)

- IE 5.5+

- Firefox 1.0+

- Latest Konqueror (3.5 today)

Those browsers are supported on whatever OSes you can get them to run

on.

-- Alex

Common Pitfalls

Why aren't my widgets being instantiated?

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

Wrong:



Right:


> Are they any HTML references

> indicating that only the explicit closing tag form works?

http://www.w3.org/TR/xhtml1/#C_3

http://www.w3.org/TR/html4/interact/scripts.html#h-18.2.1

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

http://www.w3.org/TR/html4/struct/text.html#h-9.3.2.1

-Mike

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",

};

Why does my CSS not apply to widgets?

You probably forgot the 'cascading' part in CSS. your style sheets that are loaded with the page, are loaded BEFORE the widget loads it's own CSS, so you HAVE to be more specific than the CSS in the templateCssPath(widget/templates/*.css). You can do this with an ID tag, or whatever.

Alternatively you can try !important at the end of the CSS rule, this property works on recent versions of FF, and IE 6/7.

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 download the kitchen sink.  I've loaded the demo Fisheye page and then

> I tried copying it into my own page and I get

>

> Error: Could not load 'dojo.widget.FisheyeList'; last tried '__package__.js'

Did you copy just the dojo.js file? You will need the src directory too. The
widgets are loaded on demand.

Dojo IO

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"

     });

}

--

Paul Sowden

Receiving JSON data

From Alex R:

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 withour page-refresh. How do i do that using dojo.io.bind.
-V

dojo.io.bind({

    url: your_url,

    formNode: dojo.byId("your_form"),

    method: "POST",

    load: function(type, value, evt) { dojo.byId("your_div").innerHTML = value; },

    error: function(type, error) { alert("Error: " + type + "n" + error); },

});

If you feel adventurous, you can do it like that:

var your_form = dojo.byId("your_form");

dojo.io.bind({

    url: your_form.action,

    formNode: your_form,

    method: your_form.method,

    load: function(type, value, evt) { dojo.byId("your_div").innerHTML = value; },

    error: function(type, error) { alert("Error: " + type + "n" + error); },

});

The latter assumes that you have correct action and method specified in your

form element. Of course, you can add some extra content to dojo.io.bind(),

if you wish to distinguish between normal submitting and Ajax submitting.

I hope it helps,

Eugene

Events

See Event Examples.

Validation

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

No. 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 the fisheye demo for an example.

Performance

See performance tuning guide.

Why is my page so slow to load?

Individual resources used by dojo.require() are loaded using synchronous XHR hits to the server. This is fine for development mode, but for deployment a build should be used. A Dojo build will combine a set of resources and their dependencies into a single file such that network latency can be avoided and the file sizes are minimized. Different profiles are available or you may create your own. Use the ant script in the buildscripts/ directory with the "release" target. See [AntIncantations] for details.

Why are there 404's when I load a page?

Resource loading sometimes requires following a path. In the case of localized resources, sometimes not all variants will have translations, but Dojo must look for them anyway. In all these cases, loading may be streamlined by using a build.

Packages and dojo.require()

When you call dojo.require("dojo.foo.bar.baz"),

Dojo tries to load the following files, in this order:

 - src/foo/bar/baz.js

 - src/foo/bar.js

 - src/foo/bar/__package__.js

 - src/foo.js

 - 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:

 - src/foo/bar/baz/__package__.js

 - src/foo/bar/baz.js

 - src/foo/bar/__package__.js

 - src/foo/bar.js

 - src/foo/__package__.js

 - src/foo.js

 - and then fail.

Custom dojo code

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

Here is what I do. Given a folder structure like so:

dojo/

turbo/

  foo.js

dojo.setModulePrefix("turbo", "../turbo"); // path is relative to dojo root

// One user had to do dojo.hostenv.setModulePrefix 9/19/2005

// dojo.hostenv.setModulePrefix is now deprecated 12/19/2005

dojo.require("turbo.foo");

Note 1: that after the "require", both 'turbo' and 'turbo.foo' are objects

(aka namespaces).

Note 2: foo.js contains the line dojo.provide("turbo.foo");

Regards,

Scott (Miles)


You can do something like the following:

  dojo.setModulePrefix("webwork", "../webwork"); // was dojo.hostenv.setModulePrefix("webwork", "../webwork");

Which will make all require()s that start with "webwork" look at the

folder "webwork" next to the dojo one (in your case, that'd be

"/webwork/webwork"). Note that the path is relative to the dojo base

path. So, to pull in your custom thinger, you'd do:

  dojo.require("webwork.customThinger"); // will look for

/webwork/webwork/customThinger.js

  dojo.require("webwork.*"); // will look for /webwork/webwork/__package__.js

-d (David Schontzler)

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

lets say you have this folder layout :

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() {

}

etc..


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

var dependencies = [

	"dojo.io.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

Eclipse: http://www.alphaworks.ibm.com/tech/ajaxtk

MyEclipse: http://www.myeclipseide.com/

JSEclipse: http://interaktonline.com/

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

See Debugging Javascript for details on debugging in IE, firefox, safari.

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 that will continue. 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. By running the unit tests, you may be able to get some sense of which modules are rapidly evolving and which are fairly stable. Also,

Licenses and legal questions

Can I Combine Dojo with LGPL Software?

On Tuesday 06 December 2005 12:21 am, Sebastian Werner wrote:

>> Hi!

>>

>> I just want to ask if the last change of the license in dojo makes it

>> also compatible to the LGPL. Means could parts of dojo be used and

>> licensed under 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-2005, The Dojo Foundation

	All Rights Reserved

Regards

-- Alex Russell

See also:
licensing goals
licensing terms
contributor license agreement

Miscellaneous

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

1. Use Ben Nolan's Behaviours package

2. Use capabilities built in to Dojo, e.g.

<head>

 <title>Behaviors with Dojo!</title>
   
<body>

 <button class="dojo-mouseoverbehavior" label="built using XHTML class attribute">

  mouse over me!

Can Dojo work with Ruby on Rails?

We've had a couple of requests to use Dojo in a Ruby on Rails

environment (aka: Prototype co-existence) and so far it hasn't worked.

This evening I was able to make Prototype 1.3.1 and Dojo HEAD co-exist.

As of rev1641, you should now be able to drop Dojo into RoR apps

without hesitation.

Regards

--

Alex Russell

09/28/2005

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?

It doesn't quite copy all properties, and I believe 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.

--

Martin Cooper

How About Them New Storage APIs

Q: David Ascher

A: Alex Russell

>> Dojo will automatically load flash, and give

>> you a persistent storage on that browser installation?

Correct. This is handled via the SharedObject API in Flash, which by

default allows you 100K of string-indexed storage per domain.

>> How do you remove things from this storage?

It occured to me that we should have an unset(key, ns) or remove(key,

ns) method in storage, but I would assume that it'll just set things to

a blank string.

>> What's the use case?

Anything that would like to start up faster on the second visit. Think

message lists in webmail or durable user preferences for widget state

in an app. Or even caching code. The best bytes on the wire are the

ones you don't (re)send.

>> Curious minds want to know!

I'm actually just as curious to know what kinds of services things like

this get pressed into as you are. I can see this being useful to a lot

of apps, but not central to very many of them, although that could

change depending on what the browser vendors do.

>> Is it possible to use the flash storage if available, and default

>> to something else behind the scenes if flash is disabled (I know

>> almost no one w/ JS disabled, but quite a few w/ Flash disabled).

Yes. The current implementation only has one StorageProvider class

implemented (the flash one), but the hope is that others will spring up

as people think of clever hacks and/or the browsers gain this feature

natively (see the latest WHATWG webapps spec draft).

>> What are the security concerns w/ these storage systems?

Same as with cookies, only they aren't transmitted over the wire for

every request.

Adding Functions and Build Scripts

Wayne Douglas wrote:

> 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?

>

> Cheers in advance

>

> w

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.

-Bill Keese

How to Run Code When Dojo is Loaded?

Dojo Fan wrote:

>  Folks,

>

> 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:

dojo.addOnLoad(yourInitMethod);

This calls yourInitMethod once dojo is fully loaded.

Then place all the script in the last script tag inside a function called 'yourInitMethod'.

- Richard Paul

dojo.addOnLoad is not working right... firing before the page is loaded.

In order for dojo.addOnLoad to work properly, you need to wrap your calls inside of an init function... for example

instead of dojo.addOnLoad(alert("this page is not yet loaded"); you would do

function init() {

  alert("this page is fully loaded!");

}

dojo.addOnLoad(init);

Since the alert function is inside the init function dojo's addOnLoad is able to process it correctly.

Hope this helps more people

-Karl

How to Prevent Default Event Action?

On 11/25/05, Jesse Kuhnert wrote:

>> 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 ...

});

- David Schontzler