kern/superx/xml/js/dojo/README

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: