Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 238 lines (156 sloc) 7.739 kB
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
1 # jsdom 0.2.0
e1abc48 @tmpvar added some metadata
authored
2
2141fa9 @tmpvar update readme
authored
3 A javascript implementation of the W3C DOM.
3235f39 @tmpvar
authored
4
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
5 ## Install
edfe278 @tmpvar
authored
6
4faadca @tmpvar updated readme
authored
7 npm install jsdom
aeb0e9c @tmpvar updated readme
authored
8
4faadca @tmpvar updated readme
authored
9 or
03a6f07 @tmpvar formatting
authored
10
4faadca @tmpvar updated readme
authored
11 git clone http://github.com/tmpvar/jsdom.git
12 cd jsdom
13 npm link .
70fb7ec @tmpvar updated readme
authored
14
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
15 ## Easymode
4faadca @tmpvar updated readme
authored
16
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
17 Bootstrapping a DOM is generally a difficult process involving many error prone steps. We didn't want jsdom to fall into the same trap and that is why a new method, `jsdom.env()`, has been added in jsdom 0.2.0 which should make everyone's lives easier.
4faadca @tmpvar updated readme
authored
18
76c7415 @karunasagark fixed the example to config object
karunasagark authored
19 with URL
20
4faadca @tmpvar updated readme
authored
21 // Count all of the links from the nodejs build page
22 var jsdom = require("jsdom");
23
76c7415 @karunasagark fixed the example to config object
karunasagark authored
24 jsdom.env("http://nodejs.org/dist/",
25 [
26 'http://code.jquery.com/jquery-1.5.min.js'
27 ],
28 function(errors, window) {
29 console.log("there have been", window.$("a").length, "nodejs releases!");
30 });
4faadca @tmpvar updated readme
authored
31
32 or with raw html
33
34 // Run some jQuery on a html fragment
35 var jsdom = require('jsdom');
36
76c7415 @karunasagark fixed the example to config object
karunasagark authored
37 jsdom.env('<p><a class="the-link" href="http://jsdom.org>JSDOM\'s Homepage</a></p>',
38 [
39 'http://code.jquery.com/jquery-1.5.min.js'
40 ],
41 function(errors, window) {
42 console.log("contents of a.the-link:", window.$("a.the-link").text());
43 });
4faadca @tmpvar updated readme
authored
44
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
45 or with a configuration object
46
82b86b3 @tmpvar added hackernews example in the readme
authored
47 // Print all of the news items on hackernews
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
48 var jsdom = require('jsdom');
49
76c7415 @karunasagark fixed the example to config object
karunasagark authored
50 jsdom.env({
51 html: 'http://news.ycombinator.com/',
52 scripts: [
53 'http://code.jquery.com/jquery-1.5.min.js'
54 ],
55 done: function(errors, window) {
56 var $ = window.$;
57 console.log('HN Links');
58 $('td.title:not(:last) a').each(function() {
59 console.log(' -', $(this).text());
60 });
61 }
62 });
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
63
82b86b3 @tmpvar added hackernews example in the readme
authored
64
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
65 ### How it works
66 `jsdom.env` is built for ease of use, which is rare in the world of the DOM! Since the web has some absolutely horrible javascript on it, as of jsdom 0.2.0 `jsdom.env` will not process external resources (scripts, images, etc). If you want to process the javascript use one of the methods below (`jsdom.jsdom` or `jsdom.jQueryify`)
4faadca @tmpvar updated readme
authored
67
1d79a8c @tmpvar preparing for takeoff
authored
68 jsdom.env(html, [scripts], [options], callback)
69
70 - `html` (**required**)
71 May be a url, html fragment, or file
72
73 - `scripts` (**optional**)
74 May contain files or urls
75
76 - `callback` (**required**)
77 Takes 2 arguments:
78 - `errors` : array of errors
79 - `window` : a brand new window
80
2de13bb @tmpvar readme update
authored
81 _example:_ jsdom.env(html, function(`errors`, `window`) {})
1d79a8c @tmpvar preparing for takeoff
authored
82
83
84 If you would like to specify a configuration object
dccaea1 @ulteriorlife actually added link to website in the readme.md
ulteriorlife authored
85
1d79a8c @tmpvar preparing for takeoff
authored
86 jsdom.env({ /* config */ })
2351e18 @tmpvar
authored
87
1d79a8c @tmpvar preparing for takeoff
authored
88 - config.html : see `html` above
89 - config.scripts : see `scripts` above
90 - config.done : see `callback` above
aeb0e9c @tmpvar updated readme
authored
91
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
92 ## For the hardcore
1d79a8c @tmpvar preparing for takeoff
authored
93
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
94 If you want to spawn a document/window and specify all sorts of options this is the section for you. This section covers the `jsdom.jsdom` method:
1d79a8c @tmpvar preparing for takeoff
authored
95
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
96 var jsdom = require("jsdom").jsdom,
97 doc = jsdom(markup, level, options),
98 window = doc.createWindow();
1d79a8c @tmpvar preparing for takeoff
authored
99
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
100 - `markup` is a full html/xml document to be parsed
101 - `level` is `null` (which means level3) by default, but you can pass another level if you'd like.
1d79a8c @tmpvar preparing for takeoff
authored
102
103
104 var jsdom = require('jsdom'),
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
105 doc = jsdom.jsdom('<html><body></body></html>', jsdom.dom.level1.core)
1d79a8c @tmpvar preparing for takeoff
authored
106
107 - `options` see the **Flexibility** section below
108
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
109 ### Flexibility
1d79a8c @tmpvar preparing for takeoff
authored
110
111 One of the goals of jsdom is to be as minimal and light as possible. This section details how
aeb0e9c @tmpvar updated readme
authored
112 someone can change the behavior of `Document`s on the fly. These features are baked into
4faadca @tmpvar updated readme
authored
113 the `DOMImplementation` that every `Document` has, and may be tweaked in two ways:
aeb0e9c @tmpvar updated readme
authored
114
115 1. When you create a new `Document` using the jsdom builder (`require('jsdom').jsdom()`)
116
dbca1f1 @tmpvar indentation in readme +1
authored
117 var jsdom = require('jsdom').jsdom,
118 doc = jsdom("<html><body></body></html>", null, {
119 features: {
120 FetchExternalResources : ['img']
121 }
122 });
aeb0e9c @tmpvar updated readme
authored
123
124 Do note, that this will only affect the document that is currently being created. All other documents
125 will use the defaults specified below (see: Default Features)
126
127 2. Previous to creating any documents you can modify the defaults for all future documents
128
1d79a8c @tmpvar preparing for takeoff
authored
129 require('jsdom').defaultDocumentFeatures = {
130 FetchExternalResources : ['script'],
131 ProcessExternalResources : false,
132 MutationEvents : false,
133 QuerySelector : false
134 }
aeb0e9c @tmpvar updated readme
authored
135
136
137
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
138 #### Default Features
aeb0e9c @tmpvar updated readme
authored
139
140 Default features are extremely important for jsdom as they lower the configuration requirement and present developers a set of consistent default behaviors. The following sections detail the available features, their defaults, and the values that jsdom uses.
141
142
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
143 `FetchExternalResources`
144 _Default_: ['script']
145 _Allowed_: ['script', 'img', 'css', 'frame', 'link'] or false
aeb0e9c @tmpvar updated readme
authored
146
147 Enables/Disables fetching files over the filesystem/http
148
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
149 `ProcessExternalResources`
150 _default_: ['script']
151 _allowed_: ['script'] or false
152
153 Disabling this will disable script execution (currently only javascript).
aeb0e9c @tmpvar updated readme
authored
154
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
155 `MutationEvents`
156 _default_: '2.0'
157 _allowed_ : '2.0' or false
aeb0e9c @tmpvar updated readme
authored
158
159 Initially enabled to be up to spec. Disable this if you do not need mutation events and want jsdom to be a bit more efficient.
160
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
161 **Note**: `ProcessExternalResources` requires this to be enabled
aeb0e9c @tmpvar updated readme
authored
162
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
163 `QuerySelector`
164 _default_ : false
165 _allowed_ : true
aeb0e9c @tmpvar updated readme
authored
166
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
167 This feature is backed by [sizzle][] but currently causes problems with some libraries. Enable this if you want `document.querySelector` and friends, but be aware that many libraries feature detect for this, and it may cause you a bit of trouble.
1d79a8c @tmpvar preparing for takeoff
authored
168
169 [sizzle]:http://sizzlejs.com/
2351e18 @tmpvar
authored
170
4faadca @tmpvar updated readme
authored
171 # More Examples
2351e18 @tmpvar
authored
172
0df8ca5 @tmpvar updated readme with some important updates
authored
173 ## Creating a document-less window
174
8e0528b @tmpvar
authored
175 var jsdom = require("jsdom"),
33797d9 @tmpvar update to jsdom.createWindow(), docs, and a version bump
authored
176 window = jsdom.createWindow();
f25097f @tmpvar
authored
177
33797d9 @tmpvar update to jsdom.createWindow(), docs, and a version bump
authored
178 console.log(window.document);
179 // output: undefined
f25097f @tmpvar
authored
180
33797d9 @tmpvar update to jsdom.createWindow(), docs, and a version bump
authored
181 ## Creating a document
182 var jsdom = require("jsdom"),
183 doc = new (jsdom.dom.level1.core.Document)();
184 console.log(doc.nodeName);
185 // outputs: #document
0df8ca5 @tmpvar updated readme with some important updates
authored
186
33797d9 @tmpvar update to jsdom.createWindow(), docs, and a version bump
authored
187 ## Creating a browser-like BOM/DOM/Window
0df8ca5 @tmpvar updated readme with some important updates
authored
188
4faadca @tmpvar updated readme
authored
189 var jsdom = require("./lib/jsdom").jsdom,
190 document = jsdom("<html><head></head><body>hello world</body></html>"),
191 window = document.createWindow();
0df8ca5 @tmpvar updated readme with some important updates
authored
192
a60bb1c @tmpvar
authored
193 console.log(window.document.innerHTML);
194 // output: '<html><head></head><body>hello world</body></html>'
0df8ca5 @tmpvar updated readme with some important updates
authored
195
a60bb1c @tmpvar
authored
196 console.log(window.innerWidth)
197 // output: 1024
0df8ca5 @tmpvar updated readme with some important updates
authored
198
a60bb1c @tmpvar
authored
199 console.log(typeof window.document.getElementsByClassName);
200 // outputs: function
0df8ca5 @tmpvar updated readme with some important updates
authored
201
a60bb1c @tmpvar
authored
202
30575d5 @tmpvar fixed examples, and a bug in createWindow()
authored
203 ## jQueryify
204
205 var jsdom = require("jsdom"),
a60bb1c @tmpvar
authored
206 window = jsdom.jsdom().createWindow();
30575d5 @tmpvar fixed examples, and a bug in createWindow()
authored
207
66018a3 @fgnass Added missing quote
fgnass authored
208 jsdom.jQueryify(window, 'http://code.jquery.com/jquery-1.4.2.min.js' , function() {
209 window.$('body').append('<div class="testing">Hello World, It works</div>');
210 console.log(window.$('.testing').text());
a60bb1c @tmpvar
authored
211 });
4faadca @tmpvar updated readme
authored
212
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
213 # W3C Test Compliance:
214
215 - DOM Level 1 html/svg/xml (100%)
216 - DOM Level 2 html/events/core (100%)
217 - DOM Level 3 core (14%)
218
219 see: [testlog][] for w3/jsdom test compliance
220
4faadca @tmpvar updated readme
authored
221 # More
222
223 see: [mailing list][]
224
13a80d6 @tmpvar readme fixes, changed request dep to >=1.0.0 for pre-node 0.3.6 support
authored
225
4faadca @tmpvar updated readme
authored
226
227 see: [plan][] for roadmap and thoughts about this project
228
229 see: [project site][] for additional information
230
231 [mailing list]: http://groups.google.com/group/jsdom
232 [project site]: http://www.jsdom.org
233 [mjsunit.runner]: http://github.com/tmpvar/mjsunit.runner
234 [testlog]: http://github.com/tmpvar/jsdom/blob/master/test/testlog.txt
235 [plan]: http://github.com/tmpvar/jsdom/blob/master/PLAN.json
236
237 [mjsunit.runner]: http://github.com/tmpvar/mjsunit.runner
Something went wrong with that request. Please try again.