====== Dojo Toolkit ==
===== Links ==

[[dojo>quickstart/index|Tutorial]] --- [[dojo>quickstart/dojo-basics|dojo-basics]] --- [[dojo>manual/index|Reference]] --- [[http://api.dojotoolkit.org/|API Reference]] --- [[http://dojocampus.org/explorer/|Feature explorer]] (incomplete?) --- [[http://dev.aol.com/dojo|Dojo Lib from AOL's CDN]] --- [[http://www.sitepen.com/blog/series/dojo-quick-start-guide/|Old quick start]] --- [[javascript]]

===== Why Dojo? ==

  * Can do what jquery is famous for [[dojo>dojo/query|as well]]
  * Has complete GUI widgets
  * Custom (downsized) builds make it attractive for usage on embedded systems

===== First Steps ==

  * [[dojo>quickstart/gettingstarted|Hello World example]]
  * The syntax for including remote dojo libs can be found [[dojo>quickstart/cross-domain|here]]. The latest Revision number to specify can be found [[dojo>releasenotes/index|here]].
  * Debugging and Logging: Use Firebug together with ''console.log()'' and friends. [[dojo>quickstart/debugging|More]]

===== DOM Manipulation ==

^ Dojo API ^ DOM API ^
| dojo.byId() | document.getElementById() |

FIXME Does this table make sense at all?

===== Use Dojo from your Own Server ==

Download the "Dojo Toolkit Release" from http://dojotoolkit.org/download#getdojo and install it on your server to ''/var/www/htdocs/lib/''

See also: http://docs.dojocampus.org/quickstart/install#use-dojo-from-your-own-server Note that the ''themeTester.html'' mentioned there does //not// exist in the install.

===== Make a custom Build ==

A custom build is necessary for example when public [[dojo>quickstart/cross-domain|cross-domain distributions]] are not accessible (isolated network) //and// the size of the [[http://o.dojotoolkit.org/downloads|standard dojo package]] is to big for the server (e.g. on an embedded system). With a custom build you can do both: Reduce the size and make it cross-domain capable.

Further reading: [[dojo>quickstart/custom-builds]] --- [[ibm>web/library/wa-aj-custom/|Create optimized Dojo builds for your custom Dojo artifacts]]


==== Make a cross-domain Build ==

The following exemplary steps build a cross-domain build with standard profile to be installed on the machine of the browser. Hence the browser machine needs a webserver as well! The actual dojo app can live on a space limited device where the browser connects to:

  - [[http://dojotoolkit.org/download/|Download]] and extract latest stable //source// release
  - Create the build destination dir as root, eg. ''/var/www/htdocs/lib/dojo/1.4/''
  - Cd into dojo-release-1.4.1-src/util/buildscripts
  - Run this as root:<code bash>./build.sh profile=standard loader=xdomain xdDojoPath=http://localhost/lib/dojo/1.4 action=release releaseName=1.4 releaseDir=/var/www/htdocs/lib/dojo</code>
  - The necessary include path then yield to:<code html><link rel="stylesheet" type="text/css" href="http://localhost/lib/dojo/1.4/dijit/themes/tundra/tundra.css">
<script type="text/javascript" src="http://$your_hostname/lib/dojo/1.4/dojo/dojo.xd.js" djConfig="parseOnLoad: true"></code>

==== Make a size-optimized Build ==
=== Build ==

Download and extract latest stable //source// release. Tip: Use SVN, e.g: ''svn co http://svn.dojotoolkit.org/src/branches/1.4 dojo-svn''

You need a build profile with an arbitrary name, eg ''exorsus'':  ''dojo-svn/util/buildscripts/profiles/exorsus.profile.js''. In the build profile you specifiy all the modules which you would normally include with ''dojo.require()'' and an arbitrary name for the resulting .js file (called layer), in this example ''exodojo.js''. All modules specified in the dependencies will end up in the layer file:

<code javascript>
dependencies = {
    layers:  [
        {
            name: "exodojo.js",
            dependencies: [
                "dijit.layout.ContentPane",
                "dijit.layout.BorderContainer",
                "dijit.layout.TabContainer",
                "dijit.layout.AccordionContainer",
                "dijit.form.CheckBox",
                "dijit.form.Slider"
            ]
        }
    ] /* ,
    // build produces the same result with or without the prefixes attribute
    prefixes: [
        [ "dijit", "../dijit" ],
        [ "dojox", "../dojox" ]
    ] */
};
</code>

Cd into ''dojo-svn/dojo-svn/util/buildscripts/'' and issue the following command (you will use different languages in ''localeList''):

  ./build.sh profile=exorsus action=clean,release localeList=en-us,de-de cssOptimize=comments

The build is created in ''dojo-svn/release/''

<note tip>Tip: Save the build profile file and the build command in the source tree of your own web app and just create symlinks from ''dojo-svn/...'' to the files in your web app!</note>

=== Deploy ==

This is no cross-domain build, i.e. the build has to be installed on the same server, where the web app which uses the dojo build lives.

Copy the follwing files and directories from ''dojo-svn/release/'' to the web root of your webserver, eg. ''/var/www/htdocs/'':

  .
  `-- dojo
      |-- dijit
      |   `-- themes
      |       `-- tundra
      |           |-- images
      |           |   |-- accordionItemActive.gif
      |           |   |-- ...
      |           |   |-- ... everything except the .psd files 
      |           |   |-- ...
      |           |   `-- warning.png
      |           `-- tundra.css
      `-- dojo
          |-- dojo.js
          |-- exodojo.js
          `-- nls
              |-- exodojo_ROOT.js
              |-- ...
              |-- ... everything that begins with the name of your layer file
              |-- ...
              `-- exodojo_xx.js
              
The example assumes that you work with the tundra theme. Of course you have to take the files of the theme you use!

<note important>You need to maintain the same directory structure in the web root of your webserver as given in ''dojo-svn/release/''!</note>

<note tip>Tip: The ''images/'' subdir of the tundra theme contains (useless?) Photoshop images (''*.psd''). Remove them to save space!</note>

Now remove all calls to ''dojo.require()'' in your web app and instead include your own layer file:

<code html>
<link rel="stylesheet" type="text/css" href="/dojo/dijit/themes/tundra/tundra.css">
...
<script type="text/javascript" src="/dojo/dojo/dojo.js">
<script type="text/javascript" src="/dojo/dojo/exodojo.js"></script>
</code>

=== Currently known Issues ==

  * ''djConfig.isDebug'' must be set to ''false''
  * IE looks for a file called ''ressources/blank.gif'' relativley to the root of your web app when working with the AccordionContainer.

=== Possible Improvements ==

In order to furher reduce the size of the lib you may:

  * Name unused css modules with the ''cssImportIgnore'' command line attribute when calling ''build.sh''. You can easily spot unused css modules by looking at ''dojo-svn/dijit/themes/tundra/tundra.css''.
  * Unused images may be picked out from ''dojo-svn/dijit/themes/images/''. For, you look in ''dojo-svn/dijit/themes/tundra/tundra.css'' for all references to the ''image'' subdir and there you remove all images which are //not// referenced.

===== Dijit ==

Dijit widgets are wrappers around native DOM nodes.

''dojo.byId()'' returns the DOM node, whereas [[dojo>dijit/byId|dijit.byId()]] returns the Dijit widget.

Dijit widgets have an attribute called ''domNode'' to access the DOM node. [[dojo>dijit/info|More]]

===== Events ==

Normal DOM events are lowercase (like ''onclick''). Whereas Dojo widget events are camel case (''onClick''). 

''dojo.connect'' is a more powerful replacement for native event handling. More: [[dojo>quickstart/events|JavaScript events and Dojo]] / [[javascript#events|Javascript events]]

===== Todo ==

  * Check: [[http://www.ibm.com/developerworks/web/tutorials/wa-dojotoolkit/|Build an Ajax application with the Dojo Toolkit]]