thatcher / env-js forked from jeresig/env-js

env.js : A pure JavaScript browser environment.
Developed by John Resig (http://ejohn.org)

Major Contributers:
Chris Thatcher (http://github.com/thatcher)

GitHub repositories:
http://github.com/jeresig/env-js/
http://github.com/thatcher/env-js/

Mailing List:
http://groups.google.com/group/envjs

Lighthouse (Bug Tracking):
http://envjs.lighthouseapp.com/projects/21590-envjs/

Build Status:
http://runcoderun.com/thatcher/env-js

Original blog post:
http://ejohn.org/projects/bringing-the-browser-to-the-server/

Rhino (Java-based JavaScript engine)
http://www.mozilla.org/rhino/

Getting the code:

* Check the code out from git: git clone git://github.com/thatcher/env-js.git

Building:
* run "ant concat"
* Creates a platform-agnostic "dist/env.js" file and a Rhino-specific "dist/env.rhino.js" file.

Testing:
* Checkout qunit: "git submodule update --init"
* run "ant test"

Java command line:

env.rhino.js can be run either with a "generic" version of the Rhino
library (js.jar), or with the repackaged/extended version of Rhino
supplied with env.js (env-js.jar).  If your application uses multiple
windows, frames, or iframes, or if it depends on precise adherence to
JavaScript object scoping in event handlers, you will have to use
env-js.jar.  Simple applications may be able to run with the generic
version of Rhino.

The command line used for testing env.js can be found in build.xml,
although the general form is:
     java -jar [jar file] [javascript file]
Where "jar file" is either "dist/env-js.jar", "rhino/js.jar", or your
local path to a different version of the Rhino js.jar file.  The
"javascript file" is the path to the JavaScript you wish to execute.

Installing:
1) Include the proper env.js file for your platform.
     load('env.rhino.js'); //if in a Rhino script

2) Tell env.js to load an HTML file from your file system that it should model:
     Envjs("some/file.html");
       or
     var someWindow = window.open("some/file.html");
       or
     window.location = "some/file.html";

   Optionally you can turn on/off settings by passing an options object:
     Envjs("some/file.html", {log: function(msg){ console.debug(msg) }});

3) Optionally trigger "document ready" events in one of these ways:

4) Start processing of window(s)' event queue:
     Envjs.wait();

All together, the steps could be:

   a) simplest method:
     load('env.rhino.js');
     Envjs("some/file.html");
     Envjs.wait();

   b) jQuery ready method:
     load('env.rhino.js');
     load('jquery-1.3.2.js');
     Envjs("some/file.html");
     load('some-code-that-sets-up-jquery-onready-behaviors.js')
     jQuery.ready();
     Envjs.wait();

   c) Other JavaScript frameworks have their own methods of setup, but the general pattern is:
     // step 1: load env.js
     // optionally: load your framework(s)
     // step 2: tell env.js the base DOM to model
     // optionally: run any setup code for your framework(s0
     // step 3: tell the framework that the document is loaded
     // step 4: Envjs.wait();

Note that env.js is currently limited to loading a single HTML page
from the original window.  If you are going to load multiple pages in
succession into the same window, load the first into a new window
object using window.open().

Testing jQuery Compatibility:
* run ./bin/test-jquery.sh 1.3.2
* run ./bin/test-jquery.sh 1.3.1
* run ./bin/test-jquery.sh 1.2.6
* Checks out the given jQuery tag from Subversion into test/vendor/jQuery/[version], 
  moves dist/env.rhino.js into the correct location in their tree, and runs the test suites.

Changes with new timer code:

Previously with envjs, you could call Java's thread sleep() method to delay execution. This was mostly used in test 
suites. This may no
longer work the same since it will inhibit all events from firing. You can now use the Envjs.wait(milliseconds) call to 
achieve an
effect similar to calling sleep().