Welcome, guest ( Login )

WikiHome » BabySteps

BabySteps

Version 54, changed by owen 12/09/2006.   Show version history

OBSOLETE?

Baby Steps

("Getting Started")

Originally written by Steve

Modified by Jyotiraditya Unmukt and Alex Russell

Note: Of late, I have been receiving messages about Dojo's Compatibility with Java etc. Dojo is a JavaScript toolkit, and while it can be run in a Java environment via Rhino, there is no toolkit-level compatibility.

Traditional DHTML forces you to forsake markup-based development for script-oriented page construction. Dojo doesn't force you to choose.

1. getting a dojo build.

The Dojo Foundation makes nightly builds available from http://archive.dojotoolkit.org. We'll grab the "ajax" profile build from http://archive.dojotoolkit.org/nightly-profiles/ and unzip it in a directory somewhere in the web or development root. Prior to the 0.1 release, Dojo required a web-server in order to load. Fortunantly, it can now be loaded directly from the file system.

The file dojo.js in this package is all that you'll need to include in your page.

2. Read http://www.dojotoolkit.org/intro_to_dojo_io.html (those who have already done so, directly go to step 3.)

Getting down to core understanding, Dojo has a very simple input output package that can help you use it to do simple things like checking validity of username etc. even if you havent learnt it fully. It is basically a trial version (thats unfair because whole of project is open source, but for first time user this is the best word I could use, do mail me if you have any other). All that the to-be-read page does is gives you an insight to what you can do with the dojo.io.bind() method. Lets cut the crap and bring the page down in few instructions.

  • Unzip/Untar the revolutionary packet in your document root. For example, if your document root is ~/htdocs/ or ~/mydojodir/, then after unzipping/untarring you must get a directory called dojo in either ~/htdocs/ or ~/mydojodir/ or whatever you have set as the document root. dojo is not automatically created. You have to create a directory called dojo in the documentroot and the untar/unzip.
  • Now open any browser and type in it, http://<domainname>/<documentroot>/dojo (dont be silly, this is just the synatx, you have to fit in values for things in the <> construct). You will get a folder listing. If you do not get that, it simply means that you haven't set right permissions for accessing. If you have any problems regarding this, dont panic, just take a Disprin (to avoid headaches) and mail/IM/Call me (details given below). I will respond within four hours. Thats a guarantee.
  • Once you get the folder listing, your task is more than half complete. Now you can see the following directory-file heirarchy:
    • <documentroot>
      • dojo
        • dojo_browserio_build
          • document
          • tests
          • blank.html
          • LICENSE.txt
          • __package.js__
          • readme.txt, And blah, blah, blah.
  • Now in the tests directory you have few tests which are almost self explanatory, so I am not going to document those. All you have to do, in case of failure of tests change the browser you are using or recheck whether you missed out a step. And you are always welcome to contact me.
  • Did you get that code running? If not change the browser or redo the whole process and last of course contact me (details below).

3. Got a code running. But what more ?

Okay my friend. Did a lot of hassle. Now we carry on with the original author's process setiing up an Objective.

Our Current Objective

  • Get the latest version of Dojo and install it in the PC.
  • Create a page called index.html which sets up and initialises the dojo libraries.
  • Use the dojo libraries to do a javascript call to the server, and read a file called "stuff.txt"
  • Pop the contents of the file stuff.txt up in the browser as an alert box.

Why are you telling me crap, when all I am interested in getting it and using it ?!

Ok. So, you have a directory in your home directory (documentroot) called mydojodir/htdocs/anything you named it. The first thing is to check out dojo from subversion.

Lets go into mydojodir or <documentroot> directory (cd ~/mydojodir or cd ~/<documentroot>)

Now to check out dojo (svn co http://www.dojotoolkit.org/svn/dojo) lots of output later (no errors though hopefully). Once thats checked out, inside of ~/mydojodir/ or Document Root directory you will get a new directory called "dojo". There are all sorts of interesting things in there, which I reccomend you go through.

For God's sake now what is this SVN ??

Check out dojo from the anonymous subversion at http://www.dojotoolkit.org/svn/dojo. Thats real crap for beginners. How can one know this silly SVN thing, when he is a beginner. But dont panic. It is just a good tool for development of software. Now you as a beginner are interested only in getting the source code and using it. Sor you just download the root code.

What you can do is you download from http://dojotoolkit.org/viewcvs/viewcvs.py/root.tar.gz?view=tar a latest version. And then untar/unzip in your documentroot. Having problems? Go through the section 2. Similar steps. SVN!! Forgive me for I dont know you.

On untarring you will get a directory called 'root' inside the Document Root Directory. For historic reasons rename this 'root' directory to 'dojo'.


Yeah, I got it, but how to use that?

Now that we have dojo somewhere that we can access using the new domain, its time to create the all important "index.html". This is to be created historically again in the document root directory.

Here's original author's first stab at it: 

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "\-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xml:lang="en" lang="en">
<head>
<title>This Is A Test</title>

<body>
This is just a bit of text to make the page look less boring.

Now if you do an "ls" or "dir", and you are in the Documentroot directory, you see index.html and a directory called "dojo".

Now create a text file called "test.txt" in this folder itself and write in it "Working at last!!".

Now if you do an "ls" or "dir", and you are in the Documentroot directory, you see index.html and a directory called "dojo" alongwith a file called "test.txt".

Right Then! The first thing you will feel that you need to do is to create a javascript variable called djConfig (case sensitive), which tells all of the other dojo bits and pieces some important information.

Here's original author's: (which lives inside the <head> of index.html) 

<script language="JavaScript" type="text/javascript">
// Dojo configuration
djConfig = {
    isDebug: true
};
</script>

I'll mention now, even though it seems silly, that the above bit of javascript should appear before any other javascript in the head of the document. I'm only saying, because it took me longer than it probably should have to realise why nothing was working :D

Actually, before I start describing the config (above), i'll show you the rest of my stunningly simple example, so you can see the destination before I describe my somewhat meandering route.

Here's my final index.html: 

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "\-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xml:lang="en" lang="en">
<head>
<script language="JavaScript" type="text/javascript">
// Dojo configuration
djConfig = {
    isDebug: true
};
</script>
<script language="JavaScript" type="text/javascript" src="dojo/__package__.js" />
<body>

<script language="JavaScript" type="text/javascript">
dojo.hostenv.loadModule("dojo.io.\*");
dojo.io.bind({
    url: "test.txt",
    load: function(type, data, evt){alert(data);},
    mimetype: "text/plain"
});

</script>
This is just a bit of text to make the page look less boring.

Now if you get to open index.html through the whole path you will get an alert stating "Working at last!!". The beauty is in place of url variable you can put any other url and then do whatever you like with the data on it. Sounds Amazing!! Doesnt it ??

I got that working. But whats going in the back?

Here's something I dont want to change as the original author has done already a lot (esp his refrences like "Girls like that" have make me feel that might be I aint able like him to understand the psychology of technical writing). Few points I would like to mention:

  • Dont do that very fast for if you do that you will miss the beauty.
  • And only try to follow author's technical remarks.
  • Where ever ~/mydojodir is mentioned it is nothing but original author's Document Root. So if you have documentroot as xyz, for you it becomes ~/xyz/.
  • Instead of using the name if the text file, you can use its oath as seen by the server. For example, if your domain name is "my.domain.blah", document root is 'xyz' and you have a file 'input.txt' in dojo/tests then you can set value of url as "http://my.domain.blah/xyz/dojo/tests/input.txt".

STORY BEGINS (contributed by original author)

OK! Back to the configuration (which I pasted in earlier), which lives inside ALWAYS THE FIRST <script> tags. So, this sets up a djConfig variable, with two parameters (not sure if thats the right terminology). One called baseRelativePath, and another called isDebug. The isDebug variable I set to true, as it outputs lots of debugging information, and makes my relatively simple script look far more complicated than it actually is. (The girls love to see nice debugging)

The baseRelativePath parameter had me a bit confused for a while as to where its meant to point. It tells dojo, how to find the files that live under ~/mydojodir/dojo/. If your setup is the same as mine, then what I pasted above should be correct. This parameter should end in a "/". OK!

So, for a bit of (observed) background. Dojo is spread amongst more than three files, however i've only included three using the <script> tags above. They both live in the ~/mydojodir/dojo/src/ directory, and are available from a web browser at /dojo/src/filename.suffix

The first file is bootstrap1.js, and sets up the very first things that dojo needs to get itself up and running. When you include this file, it reads the djConfig variables (I think), and sets up some dojo specific functions.

The second file (hostenv_browser.js) is a little cunning :D Because dojo works on more than just web browsers, you get to decide its configuration by changing the name of the next file to include. (in this case, obviously, i'm using a web browser) however this next one would be different if we were doing javascript inside Adobe SVG viewer say, (or spidermonkey or rhino (I guess these are non-browser javascript interpreters) (i'm just guessing by the name of the files. I could google, but that would spoil the fun)). So then, I include hostenv_browser.js and dojo continues setting itself up, this time, defining lots of handy functions that have web browser specific implementations, and which I imagine change if your not in a web browser. (Things like outputting a line of text (dojo.hostenv.println("woo") would be different in SVG as it would be a web browser. (In the case of the web browser, it does this to create the println function:

dojo.hostenv.println = function(s){
var ti = document.createElement("div");
document.body.appendChild(ti);
ti.innerHTML = s;
}

)(I removed the try block around it to keep it simple, but then complicated it again by saying I removed it here :S)

OK! So we've got bootstrap1.js included, and also the web browser specific hostenv_browser.js included. Now its time to include bootstrap2.js (Which I guess can do its bootstrapping blissfully unaware of the fact its in a web-browser, thanks to the sterling work done by the hostenv_browser.js file, which abstracted any differences away).

The whole time I was doing this, by the way, I had firefox open on the server hosted version of index.html, refreshing when I changed things, and watching the Javascript Console for any errors (of which there were many, until I worked out what I was meant to be doing).

So! We've done a bit of configuration. We've included the first bootstrap, setup the hostenv (Host Environment? (browser in this case)), and then included the second bootstrap javascript!. If your setup is like mine , then you should be able to do this, and load the page without getting anything appear in the Javascript console. Here's the full index.html so far: 

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "\-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xml:lang="en" lang="en">
<head>
<script language="JavaScript" type="text/javascript">
// Dojo configuration
djConfig = {
    isDebug: true
};
</script>
<script language="JavaScript" type="text/javascript" src="dojo/__package__.js" />
<body>
This is just a bit of text to make the page look less boring.

Now for the funky stuff! If you think the stuff so far was difficult, think of it as the equivalent of putting your shoes (or trainers) on your feet before going running.

The next (which i'll put below) bit of <script> I put inside the <body> tags, but I think it could be included from an external .js file (which is included AFTER the others) if you want to keep yourself organised.

This is where all of the magic of dojo becomes apparent. Before you do this, create a file called ~/mydojodir/test.txt and put some text in there. Traditionally this would be "Hello World!" however because i'm a little hungry, i'm going put "Hmmmm Pie!" in there. This is the file that we're going to get dojo to read from the server, so our new aim is to have an alert box that shows the text "Hmmmm Pie!".

Here's the magical next <script> tag: 

<script language="JavaScript" type="text/javascript">
dojo.hostenv.loadModule("dojo.io.\*");
dojo.io.bind({
    url: "test.txt",
    load: function(type, data, evt){alert(data);},
    mimetype: "text/plain"
});
</script>

I'll describe the javascript, and what I've learned/assumed it does. (never assume! Naughty! (I actually read the code (until I got hungry with all this talk of pies), I just wanted to look like I could assume correctly))

dojo.hostenv.loadModule("dojo.io.*"); This line uses dojo.hostenv.loadModule function to load dojo's dojo.io.* classes! Obvious now? Because its in the hostenv namespace, we can assume it does something specific to web browsers here in order to load the libraries. In this case, it does some kind of background request magic to load the javascript for these modules from the server (unless you've already loaded it, in which case theres nothing to do! (Clever eh?)).

Here's the docs from the bootstrap1.js file for the loadModule function (I know your interested):

* loadModule("A.B") first checks to see if symbol A.B is defined.
* If it is, it is simply returned (nothing to do).
* If it is not defined, it will look for "A/B.js" in the script root directory, followed
* by "A.js".
* It throws if it cannot find a file to load, or if the symbol A.B is not defined after loading.
* It returns the object A.B.

This dojo.hostenv.loadModule function uses the "baseRelativePath" configuration parameter that we defined earlier, so that it knows where to get the javascript modules from. This would mean that for the hypothetical example of loadModule("dojo.steakandkidney") you would guess (using the configuration above) that it would try to load dojo/dojo/steakandkidney/steakandkidney.js from the server. (The first dojo of the path being the dojo from the baseRelativePath configuration parameter). However there is a special case! If the name of the module begins with "dojo" then it is replaced with "src" when looking on the server. So in fact, (still in the hypothetical example), it looks for "dojo/src/steakandkidney/steakandkidney.js". This is really handy, as it means you can use dojo directly from subversion, however had me confused as to how it works (and I suspect may change at some future date).

Its probably worth also noting, that my example code, does a loadModule("dojo.io.*") call, (notice the * on the end). What this effectiveley means is that (after reading the previous paragraph about the dojo/src replacement). That dojo looks for a file called dojo/src/io/__package__.js (which it evaluates inside the browser, and actually contains the dojo.hostenv.loadModule("something.something") calls, which will load the entire module! How clever is that? (I'm actually lying/ignorant here, the call is slightly different, but seems to do effectiveley the same thing). Have a look at the file if you want, it lives in ~/mydojodir/dojo/src/__package__.js And i'll give you a nice pie as first prize if you can guess (with one try) the url with which you can see that file on from your web-browser. (Or if you can spot the surplus word in that previous sentence).

The next function call, dojo.io.bind is far more superioraly described here http://www.dojotoolkit.org/intro_to_dojo_io.html so I wont rabbit on about it, and i'm sure you can see the tweaks i've made from the example in that link, in order to get it to do my bidding. I added the "alert(data)" to the block of the function which is set as the "load" parameter.

SO THEN! Type it in, press reload, and SEE THE MESSAGE! You know you want to! What did it say? Did it work? Mine did! (Eventually). (Very eventually actually, it took me a while of reading the code and debugging to figure out i'd put the configuration at the end (a beginners mistake I hear you chuckle))

Steve

Thanks Steve. But what next.

If you are now ready the whole world is watching you. Start building applications like slideshow websites and explore its uses. Join the dojo interest mailing list and get in touch with us.

Anyways, in traditional Japanese, Dojo is an environment or setup for karate. So dont try googling for Dojo. Come here, and without any fear, ask me dear!!

Jyotiraditya Unmukt, eid: jyotiraditya@da-iict.org, IM(yahoo): jyotiraditya_ict, Cell: +919327508956, Snail mail: G212, Boys Hostel, DA-IICT, Near Indroda Circle, Gandhinagar, Gujarat, India.

Original Author :Steve email: dojo@bigsteve.org

Attachments (0)

  File By Size Attached Ver.