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