- The Book of Dojo
- Quick Installation
- Hello World
- Debugging Tutorial
- Introduction
- Part 1: Life With Dojo
- Part 2: Dijit
- Part 3: JavaScript With Dojo and Dijit
- Part 4: Testing, Tuning and Debugging
- Part 5: DojoX
- The Dojo Book, 0.4
dojo.require
Submitted by Carla on Sat, 04/07/2007 - 17:59.
dojo.require(String module)
If you've followed through the previous sections, you already know how important dojo.require is. In general if you use a function
dojo.someModule.someFunction();
You need to include
dojo.require("dojo.someModule");
If you don't, your scripts will throw a "dojo.someModule not defined" or "dojo.someModule.someFunction not defined..
Dojo's code is split into modules which are similar to packages in Java except that in Dojo a module can contain both constructors (like classes in Java) and simple functions. For example, the "dojo.string" module contains a number of functions, such as dojo.string.substitute(). The "dojo.dnd" module contains a number of constructors such as dojo.dnd.Container dojo.dnd.Source in additon to top-level functions and properties on the dojo.dnd object. We'll learn a lot more about this in Modules
Note the naming convention - functions, properties, and namespace objects start with a lowercase letter, and constructors (which are technically functions but act more like classes) start with a capital letter.
It may seem painful to require all modules, but dojo rewards by:
- Loading any dependent scripts for you. If dijit.form.TextBox requires dojo.math, you still need only require dijit.form.TextBox.
- Preventing loading dojo packages twice. dojo.require will simply return if the package is already loaded.
- Allowing you to build streamlined versions of dojo. If you use dijit.form.TextBox a lot, you can build a custom version of dojo that loads dijit.form.TextBox quickly. Dojo.require() knows whether the function is already loaded, and so you don't have to change any of your code. See The Build System for a discussion.
So you might wonder "So, don't I have to require the dojo module itself to use dojo.require?" Nope. Any function in the top-level package "dojo" is loaded automatically (dojo.query(), dojo.byId(), etc.). These are dojo's Core functions, and represent the most used functions according to usage patterns in the community. This is similar to the Java package java.lang, which is automatically available to all Java programs.
- Printer-friendly version
- Login or register to post comments
- Unsubscribe post
Programming Dojo 101
I could not at first figure out why these next pages were confusing me. I think the problem is that there is reference style information mixed in with HOWTO information. Some of the pages also assume I've read other parts, by saying things like, "By now you know that..." Each page should be as independent as possible and not assume I've read the others.
I would suggest a single additional page slipped in before "Functions Used Everywhere". This would be titled something like "Programming Dojo 101". It should list the following points.
ONE. All dojo features are available through HTML or by programmatic means.
TWO. You can use the HTML examples. Here is what you need to know to translate the HTML examples into code:
a) The dojoType parameter is used as a constructor. So if you see
<div dojoType='a.b.c'></div>
, then your javascript would bevar x = new x.y.z()
.b) You must add a "dojo.require('x.y.z')" call somewhere in your code. By convention these are put into a script block in the
<head>
section of your page. However, if your site is highly dynamic and you don't know which ones to require, you can either in require them all (recommended) or require them right before creating an object (there is no error if you require the same item twice). The parameter is a string.c) The parameters of the HTML examples are passed as the first parameter to the constructor, using JSON notation. In this notation you pass a set of property: value pairs, separated by commas, inside a set of curly braces, as in:
In the example above, the first parameter gets a string literal value which is in quotes, and the second parameter references some object, such as a javascript array or function.
d) Your page must contain at least one empty html element to get started. The first widget you create will replace that widget. So you can have an HTML page that looks like this:
<div id="div0"></div>
</body>
...and your code will look like:
THREE: You can nest objects one inside the other by using the addChild() method of any object.
/* the page must have a div object named div0 */
var x = new x.y.z({parm:value, parm:value},dojo.byId('div0'));
/* Now add children */
var child1 = new a.b.c();
x.addChild(child1);
var child2 = new u.s.a();
x.addChild(child2);
</script>
FOUR: If you are used to using PHP or write database apps, remember to do your testing in plain old HTML files, providing static content. This is the easiest way to get confident with Dojo, and after that you can move the code into dynamic pages.
A case of converting HTML to Javascript
As a followup to my above comment, here is a tutorial linked to on the page on grids:
http://www.sitepen.com/blog/2007/11/06/simple-dojo-grids/
The tutorial is pure code up until the end, where he tosses in HTML:
structure="structure" autoWidth="true"></div>
If you follow the above instructions and convert to Javascript, you get:
model: model,
structure: structure,
autoWidth: true
},dojo.byId('div0'));
...note that it seems to be required to close the curly brace and list the next parameter on the same line. I'm not a js guru but when I did this more readable version it would not work:
var theGrid = new dojox.Grid(
{
model: model,
structure: structure,
autoWidth: true
},
dojo.byId('div0')
);
Not a Bad Idea
I see your point, and I think it's a good one. Am not sure whether to make that section a tutorial (along with our new Hello World and Debugger Tutorials) or inline it here. If someone would like to take up this topic, be my guest! Otherwise, I will mull it over and pick it up for my next round of edits, scheduled for late December.