D-Net

The Dojo Toolkit

----------------

Dojo is a portable JavaScript toolkit for web application developers and

JavaScript professionals. Dojo solves real-world problems by providing powerful

abstractions and solid, tested implementations.

Getting Started

---------------

To use Dojo in your application, download one of the pre-built editions from the

Dojo website, http://dojotoolkit.org. Once you have downloaded the file you will

need to unzip the archive in your website root. At a minimum, you will need to

extract:

    src/ (folder)

    dojo.js

    iframe_history.html

To begin using dojo, include dojo in your pages by using:

    <script type="text/javascript" src="/path/to/dojo.js"></script>

Depending on the edition that you have downloaded, this base dojo.js file may or

may not include the modules you wish to use in your application. The files which

have been "baked in" to the dojo.js that is part of your distribution are listed

in the file build.txt that is part of the top-level directory that is created

when you unpack the archive. To ensure modules you wish to use are available,

use dojo.require() to request them. A very rich application might include:

    <script type="text/javascript" src="/path/to/dojo.js"></script>

    <script type="text/javascript">

        dojo.require("dojo.event.*");       // sophisticated AOP event handling

        dojo.require("dojo.io.*");          // for Ajax requests

        dojo.require("dojo.storage.*");     // a persistent local data cache

        dojo.require("dojo.json");          // serialization to JSON

        dojo.require("dojo.dnd.*");         // drag-and-drop

        dojo.require("dojo.lfx.*");         // animations and eye candy

        dojo.require("dojo.widget.Editor2");// stable, portable HTML WYSIWYG

    </script>

Note that only those modules which are *not* already "baked in" to dojo.js by

the edition's build process are requested by dojo.require(). This helps make

your application faster without forcing you to use a build tool while in

development. See "Building Dojo" and "Working From Source" for more details.

Compatibility

-------------

In addition to it's suite of unit-tests for core system components, Dojo has

been tested on almost every modern browser, including:

    - IE 5.5+

    - Mozilla 1.5+, Firefox 1.0+

    - Safari 1.3.9+

    - Konqueror 3.4+

    - Opera 8.5+

Note that some widgets and features may not perform exactly the same on every

browser due to browser implementation differences.

For those looking to use Dojo in non-browser environments, please see "Working

From Source".

Documentation and Getting Help

------------------------------

Articles outlining major Dojo systems are linked from:

    http://dojotoolkit.org/docs/

Toolkit APIs are listed in outline form at:

    http://dojotoolkit.org/docs/apis/

And documented in full at:

    http://manual.dojotoolkit.org/

The project also maintains a JotSpot Wiki at:

    http://dojo.jot.com/

A FAQ has been extracted from mailing list traffic:

    http://dojo.jot.com/FAQ

And the main Dojo user mailing list is archived and made searchable at:

    http://news.gmane.org/gmane.comp.web.dojo.user/

You can sign up for this list, which is a great place to ask questions, at:

    http://dojotoolkit.org/mailman/listinfo/dojo-interest

The Dojo developers also tend to hang out in IRC and help people with Dojo

problems. You're most likely to find them at:

    irc.freenode.net #dojo

Note that 3PM Wed PST in #dojo-meeting is reserved for a weekly meeting between

project developers, although anyone is welcome to participate.

Working From Source

-------------------

The core of Dojo is a powerful package system that allows developers to optimize

Dojo for deployment while using *exactly the same* application code in

development. Therefore, working from source is almost exactly like working from

a pre-built edition. Pre-built editions are significantly faster to load than

working from source, but are not as flexible when in development.

There are multiple ways to get the source. Nightly snapshots of the Dojo source

repository are available at:

    http://archive.dojotoolkit.org/nightly.tgz

Anonymous Subversion access is also available:

    %> svn co http://svn.dojotoolkit.org/dojo/trunk/ dojo

Each of these sources will include some extra directories not included in the

pre-packaged editions, including command-line tests and build tools for

constructing your own packages.

Running the command-line unit test suite requires Ant 1.6. If it is installed

and in your path, you can run the tests using:

    %> cd buildscripts

    %> ant test

The command-line test harness makes use of Rhino, a JavaScript interpreter

written in Java. Once you have a copy of Dojo's source tree, you have a copy of

Rhino. From the root directory, you can use Rhino interactively to load Dojo:

    %> java -jar buildscripts/lib/js.jar

    Rhino 1.5 release 3 2002 01 27

    js> load("dojo.js");

    js> print(dojo);

    [object Object]

    js> quit();

This environment is wonderful for testing raw JavaScript functionality in, or

even for scripting your system. Since Rhino has full access to anything in

Java's classpath, the sky is the limit!

Building Dojo

-------------

Dojo requires Ant 1.6.x in order to build correctly. While using Dojo from

source does *NOT* require that you make a build, speeding up your application by

constructing a custom profile build does.

Once you have Ant and a source snapshot of Dojo, you can make your own profile

build ("edition") which includes only those modules your application uses by

customizing one of the files in:

    [dojo]/buildscripts/profiles/

These files are named *.profile.js and each one contains a list of modules to

include in a build. If we created a new profile called "test.profile.js", we

could then make a profile build using it by doing:

    %> cd buildscripts

    %> ant -Dprofile=test -Ddocless=true release intern-strings

If the build is successful, your newly minted and compressed  profile build will

be placed in [dojo]/release/dojo/

-------------------------------------------------------------------------------

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

vim:ts=4:et:tw=80:shiftwidth=4: