Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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