forked from envjs/env-js
/
README
186 lines (137 loc) · 6.2 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
= envjs : pilot fish =
env.js : A pure JavaScript browser environment.
Developed by John Resig (http://ejohn.org)
Major Contributers:
Envjs Team
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/
Original blog post:
http://ejohn.org/projects/bringing-the-browser-to-the-server/
Rhino (Java-based JavaScript engine)
http://www.mozilla.org/rhino/
= Guides and Apis =
http://www.envjs.com/doc/guides
http://www.envjs.com/doc/apis
Getting the code:
* Check the code out from git: git clone git://github.com/thatcher/env-js.git
* Build targets
> ant //(does all the following in order)
> ant env-platforms
> ant console-specs
> ant dom-specs
> ant event-specs
> ant html-specs
> ant timer-specs
> ant parser-specs
> ant xhr-specs
> ant window-specs
== src folder ==
The source files for this project are organized by the conventions described
below. All final sources are included here, including the massaged parser.
Platform developers are welcome to use the src/env/ folder to consider a new
platform.
== specs folder ==
The 'specifications' are our best attempt at isolating some DOM Spec into
something we can measure via an existing implementation, namely Firefox, and
which also allow us to pass the same tests in a Platform.
== a couple code conventions ==
* Page width <= 80
* 'Modules' are isolated as
var A,B,C;
(function(){
A = ...;
B = ...;
C = ...;
})();
* Modules depend on each other in some order. Many modules provide mix-ins to
enhance interfaces exposed in other modules. events.js for example, provide
dom 2 events for the dom.js module, adding addEventListener etc to the dom.
Here is the general hierarchy as proposed:
dom.js |->event.js |->html.js |->timer.js |->parser.js |->xhr.js |->window.js
all together we also include what we believe is a platform specific module
that describes the interfaces that must be implemented in a platform specific
api, and this lives in src/platform/(core|rhino).
* Variable naming should be short but complete words.
* Module level internal functions should be prefixed and appended with __.
For example __example__.
== contributing tests with patches ==
Each module has a spec in env-js/specs. Most tests will run whether you
load them in the file:, http:, or https:, though once you get to xhr.js
the tests will fail for the 'file:' protocol in firefox because of
permissions. To run xhr.js and window.js specs, copy settings.js to
local_settings.js, update it, and run a local server to satisfy
those urls included in the spec.js;
== platforms ==
Out of the box we have support for native platforms with rhino. A spidermonkey
port is also being widely used, and we hope to integrate into the main branch
or as a github plugin.
Installing:
0) common usage - all you need is env.rhino.js and rhino js.jar
java -jar js.jar -opt -1 myscript.js
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:
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({
scriptTypes: {
"": true,
"text/javascript": true
}
});
All together, the steps could be:
a) simplest method:
load('env.rhino.js');
window.location = "some/file.html";
b) jQuery ready method:
load('env.rhino.js');
load('jquery.js');
window.location = "some/file.html";
load('some-code-that-sets-up-jquery-onready-behaviors.js')
jQuery.ready();
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
// step 3: tell the framework that the document is loaded
Note:
The window object can be re-used, for example when crawling
window.location = "http://www.envjs.com/";
window.location = "http://www.envjs.com/news";
Testing jQuery Compatibility:
* run ./bin/test-jquery.sh #runs 1.4.1 by default
* 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.
== 1.1 to 1.2 note ==
The goal for refactoring 1.1.rcX to 1.2.X was primarily to isolate and
organize the code into more independent areas, provide behavior driven testing
with tests that run on firefox for each module and it's dependencies.
Java command line in 1.1:
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.
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().