Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 459 lines (297 sloc) 10.42 kb
f951727 @dodo Tag api docu
authored
1
072b284 @dodo make title as link
authored
2 # [async XML Generator](https://github.com/dodo/node-asyncxml)
f951727 @dodo Tag api docu
authored
3
19447c8 @dodo Update README.md
authored
4 > performance? foock it! i'm faster than that.
5
f951727 @dodo Tag api docu
authored
6 async xml builder and generator
97bccf4 @dodo all the newlines!
authored
7
f951727 @dodo Tag api docu
authored
8 nukular engine of [Δt](http://dodo.github.com/node-dynamictemplate/)
9
10 Runs on server and browser side (same code).
11
12 ## install
13
14 npm install asyncxml
15
a7248ba @dodo usage docu
authored
16 ## usage
17
18 ```javascript
19 asyncxml = require('asyncxml')
20 xml = new asyncxml.Builder({pretty:true})
21 xml.on('data', function (chunk) {
22 console.log(chunk);
23 })
a396756 @dodo add coffeescript example to usage docu
authored
24 // build some xml
a7248ba @dodo usage docu
authored
25 xml.tag("xml", {version:"1.0"})
26 .tag("list")
27 .tag("entry", function () {
28 this.attr('id', 1)
29 }).up()
30 .tag("entry", {id:2}, "foo").up()
31 .up()
32 .up()
33 .end()
34 ```
35
a396756 @dodo add coffeescript example to usage docu
authored
36 ```coffeescript
37 # this would result in the same xml
38 xml.tag "xml", version:"1.0", ->
39 @$tag "list", ->
40 @$tag "entry", ->
41 @attr('id', 1)
42 @$tag "entry", id:2, "foo"
43 @up().end()
44 ```
45
a7248ba @dodo usage docu
authored
46 ```xml
47 <!-- stdout -->
48 <xml version="1.0">
49 <list>
50 <entry id=1/>
51 <entry id=2>
52 foo
53 </entry>
54 </list>
55 </xml>
56
57 ```
58
f951727 @dodo Tag api docu
authored
59 ## api
60
356ed0f @dodo Builder api docu
authored
61 ### Builder([opts])
62
63 ```javascript
64 xml = new asyncxml.Builder({pretty:true})
65 ```
66 * `opts.pretty` switch to toggle pretty printing of the xml output
67 * `opts.level` start indention level of xml (starting with `-1`) when pretty is on
68
69 Use this to build and grow a XML forest.
97bccf4 @dodo all the newlines!
authored
70
356ed0f @dodo Builder api docu
authored
71 The Builder provides a single environment for many tags and an API for Adapters to interact with the tag events.
72
8eef83d @dodo sub headline for class methods in readme
authored
73 #### xml.tag(name, [attrs, [children, [opts]]])
356ed0f @dodo Builder api docu
authored
74
75 ```javascript
76 tag.tag("xml", {version:"1.0"}, function() { … })
77 ```
78 Same as `Tag::tag`.
79
80
8eef83d @dodo sub headline for class methods in readme
authored
81 #### xml.$tag(name, [attrs, [children, [opts]]])
356ed0f @dodo Builder api docu
authored
82
83 ```javascript
84 tag.$tag("xml", {version:"1.0"}, function() { … })
85 ```
86 Same as `Tag::$tag`.
87
88
2c042e4 @dodo refresh readme
authored
89 #### xml.show()
356ed0f @dodo Builder api docu
authored
90
91 ```javascript
2c042e4 @dodo refresh readme
authored
92 xml.show()
93 ```
94 Same as `Tag::show`.
95
96
97 #### xml.hide()
98
99 ```javascript
100 xml.hide()
356ed0f @dodo Builder api docu
authored
101 ```
2c042e4 @dodo refresh readme
authored
102 Same as `Tag::hide`.
103
104
105 #### xml.remove([opts])
106
107 ```javascript
108 xml.remove({soft:true})
109 ```
110 Same as `Tag::remove`.
111
112
113 #### xml.ready(callback)
114
115 ```javascript
116 xml.ready(function () {
117 console.log("builder is done.")
118 })
119 ```
120 Instead of `Tag::ready` it waits for the `end` event,
356ed0f @dodo Builder api docu
authored
121
122
8eef83d @dodo sub headline for class methods in readme
authored
123 #### xml.end()
356ed0f @dodo Builder api docu
authored
124
125 ```javascript
126 xml.end()
127 ```
128 Same as `Tag::end` but without a `close` event.
129
130
8eef83d @dodo sub headline for class methods in readme
authored
131 #### xml.register(type, checkfn)
356ed0f @dodo Builder api docu
authored
132
133 ```javascript
134 xml.register('new', function (parent, tag, next) {
135 // this gets called _before_ every new tag gets announced ('new' and 'add' event)
136 next(tag) // call next with the new tag to approve that the new tag can be announced
137 })
138 xml.register('end', function (tag, next) {
139 // this gets called _before_ every gets closed
140 next(tag) // call next with the closing tag to approve that the tag can be closed
141 })
142 ```
143 This is a plugin API method.
97bccf4 @dodo all the newlines!
authored
144
356ed0f @dodo Builder api docu
authored
145 There are only 2 types: `["new", "end"]`.
97bccf4 @dodo all the newlines!
authored
146
356ed0f @dodo Builder api docu
authored
147 The `checkfn` function of type `new` must get 3 parameters: `(parent, tag, next)`.
97bccf4 @dodo all the newlines!
authored
148
356ed0f @dodo Builder api docu
authored
149 The `checkfn` function of type `end` must get 2 parameters: `(tag, next)`.
150
89a034d @dodo add note for Δt compiler
authored
151 The [Δt Compiler](http://dodo.github.com/node-dt-compiler/) uses this API to create new tags before others.
152
153
8eef83d @dodo sub headline for class methods in readme
authored
154 #### xml.approve(type, parent, tag, callback)
356ed0f @dodo Builder api docu
authored
155
156 This is an internal API method to invoke a `checkfn` list registered with `Builder::register` by plugins.
157
158
8eef83d @dodo sub headline for class methods in readme
authored
159 #### xml.query(type, tag, key)
356ed0f @dodo Builder api docu
authored
160
161 ```javascript
162 tag.text()
163 tag.attr('id')
164 tag.add(adapter_specific_object)
165 ```
166 This is a adapter API method.
97bccf4 @dodo all the newlines!
authored
167
356ed0f @dodo Builder api docu
authored
168 Every time a text, an attribute or a tag is requested the tag will ask the builder for the values. A adapter has now the opportunity to override the `query` method of the builder instance to provide a specialised query method.
97bccf4 @dodo all the newlines!
authored
169
356ed0f @dodo Builder api docu
authored
170 The [jQuery Adapter](https://github.com/dodo/node-dt-jquery) for example uses it to provide the values right out of the DOM (eg for type text it returns the value of [jQuery.text](http://api.jquery.com/text/)).
171
172
173 ---
174
f951727 @dodo Tag api docu
authored
175 ### Tag(name, [attrs, [children, [opts]]])
176
177 ```javascript
178 tag = new asyncxml.Tag("xml", {version:"1.0"}, function() { … }, opts)
179 ```
180 * `name` the [nodeName](https://developer.mozilla.org/en/DOM:element.nodeName)
181 * `attrs` an object that contains all tag attributes
182 * `children` a function representing the children scope of the tag (see `Tag::children` for more)
183 * `opts` some internal options
184
185 Normally you don't need to instantiate this, because you should use `Tag::tag` and `Builder::tag` instead.
186
187
8eef83d @dodo sub headline for class methods in readme
authored
188 #### tag.tag(name, [attrs, [children, [opts]]])
f951727 @dodo Tag api docu
authored
189
190 ```javascript
2c042e4 @dodo refresh readme
authored
191 tag.tag("name", {attrs:null}, function () { … })
192 // these work as well:
193 tag.tag("name", {attrs:null}, "content")
194 tag.tag("name", function () {…})
195 tag.tag("name", "content")
f951727 @dodo Tag api docu
authored
196 ```
197 Same api as `Tag`.
198 __info__ tag is not closed.
199
200 Emits a `new` and `add` Event.
201
202
8eef83d @dodo sub headline for class methods in readme
authored
203 #### tag.$tag(name, [attrs, [children, [opts]]])
f951727 @dodo Tag api docu
authored
204
205 ```javascript
206 tag.$tag("sync", function() { … })
207 ```
208 Same api as `Tag`, with one difference: `tag.end()` is called right after the children scope (even when no children scope is applied).
209
210 Emits a `new`, `add` and `end` Event (end is emitted after the children scope).
211
212
8eef83d @dodo sub headline for class methods in readme
authored
213 #### tag.toString()
f951727 @dodo Tag api docu
authored
214
215 ```javascript
216 tag.$tag("tag", "content").toString()
217 (new a.Tag("tag", "content")).tag("troll").up().end().toString()
218 // both => '<tag>content</tag>'
219 ```
220 This returns the String representation of the tag when its closed.
97bccf4 @dodo all the newlines!
authored
221
f951727 @dodo Tag api docu
authored
222 It only contains text content, no children tags, because tags are garbage collected when their not in use anymore.
223
224
8eef83d @dodo sub headline for class methods in readme
authored
225 #### tag.children(childrenscope)
f951727 @dodo Tag api docu
authored
226
227 ```javascript
228 tag.children(function () {
229 this.attr({id:2})
230 this.$tag("quote", "trololo") // same as this.$tag("quote").children("trololo")
231 })
232 tag.children("content") // same as tag.text("content")
233 ```
234 This applies a children scope on a tag.
97bccf4 @dodo all the newlines!
authored
235
f951727 @dodo Tag api docu
authored
236 The tag instance directly accessible via `this`.
97bccf4 @dodo all the newlines!
authored
237
f951727 @dodo Tag api docu
authored
238 The children parameter of `Tag::tag` is passed to this method.
239
240 Emits whatever event is emitted inside the children scope (of course).
241
242
75ad651 @dodo add Tag::root doc
authored
243 #### tag.root()
244
245 ```javascript
246 tag.root()
247 ```
248
249 Returns the root parent (recursive).
250
251 Doesn't close the tag nor its parents.
252
8eef83d @dodo sub headline for class methods in readme
authored
253 #### tag.up([opts])
f951727 @dodo Tag api docu
authored
254
255 ```javascript
256 tag.up()
257 tag.up({end:false}) // don't close tag
258 ```
259 Useful for chaining, because it returns the parent tag.
97bccf4 @dodo all the newlines!
authored
260
f951727 @dodo Tag api docu
authored
261 It closes the tag by default unless `opts.end` is set to false.
262
263 Can emit an `end` Event.
264
265
8eef83d @dodo sub headline for class methods in readme
authored
266 #### tag.add(newtag)
f951727 @dodo Tag api docu
authored
267
268 ```javascript
269 other = new asyncxml.Tag("other")
270 tag.add(other)
271 ```
272 Append a new Tag.
273
274 Adapter specific objects can be passed too.
97bccf4 @dodo all the newlines!
authored
275
f951727 @dodo Tag api docu
authored
276 For example if you use the [jQuery Adapter](https://github.com/dodo/node-dt-jquery) you can pass a jQuery Object as parameter.
277
278 Emits an `add` Event.
279
280
8eef83d @dodo sub headline for class methods in readme
authored
281 #### tag.replace(newtag)
f951727 @dodo Tag api docu
authored
282
283 ```javascript
284 other = new asyncxml.Tag("other")
285 tag.replace(other)
286 ```
287 Replace a tag with another one.
97bccf4 @dodo all the newlines!
authored
288
f951727 @dodo Tag api docu
authored
289 __todo__ merge tag instances on data model level
290
291 Emits a `replace` Event.
292
293
8eef83d @dodo sub headline for class methods in readme
authored
294 #### tag.remove()
f951727 @dodo Tag api docu
authored
295
296 ```javascript
297 tag.remove()
298 ```
299 Remove a tag immediately.
300 The tag gets automatically closed.
301
302 Emits a `remove` Event.
303
304
8eef83d @dodo sub headline for class methods in readme
authored
305 #### tag.attr([key, [value]])
f951727 @dodo Tag api docu
authored
306
307 ```javascript
308 tag.attr() // results in an js object containing all tag attributes
309 tag.attr("id") // results in the value of attribute "id"
310 tag.attr("id", 3) // set attribute "id" to 3 and returns the tag instance for chaining
55cd393 @dodo attr can eat objects too
authored
311 tag.attr({id:4}) // set many attributes at once
f951727 @dodo Tag api docu
authored
312 ```
313 Set or Get tag attributes.
314
315 When using an adapter getting an attribute results in a value provided by the adapter.
97bccf4 @dodo all the newlines!
authored
316
f27d20d @dodo update readme (no attr:remove event anymore)
authored
317 When getting a value the results can be interpreted as follow:
f951727 @dodo Tag api docu
authored
318
f27d20d @dodo update readme (no attr:remove event anymore)
authored
319 * `undefined` the tag doesn't have this attribute
320 * `null` the attributes doesn't have a value
321 * everything else is a the value of the attribute
f951727 @dodo Tag api docu
authored
322
f27d20d @dodo update readme (no attr:remove event anymore)
authored
323 e.g. if you use the [jQuery Adapter](https://github.com/dodo/node-dt-jquery) the resulting value is the return value of [jQuery.attr](http://api.jquery.com/attr/).
f951727 @dodo Tag api docu
authored
324
f27d20d @dodo update readme (no attr:remove event anymore)
authored
325 Emits an `attr` Event.
f951727 @dodo Tag api docu
authored
326
327
8eef83d @dodo sub headline for class methods in readme
authored
328 #### tag.text([content, [opts]])
f951727 @dodo Tag api docu
authored
329
330 ```javascript
331 tag.text() // get text of a tag
332 tag.text("content") // set text
333 ```
334 Set or Get tag text content.
335
2c042e4 @dodo refresh readme
authored
336 Options:
337 * `escape`
338 * `append`
339
f951727 @dodo Tag api docu
authored
340 Emits a `text` and `data` Event.
341
342 When using an adapter getting text results in the content provided by the adapter.
97bccf4 @dodo all the newlines!
authored
343
f951727 @dodo Tag api docu
authored
344 e.g. if you use the [jQuery Adapter](https://github.com/dodo/node-dt-jquery) the resulting text is the return value of [jQuery.text](http://api.jquery.com/text/).
345
346
8eef83d @dodo sub headline for class methods in readme
authored
347 #### tag.raw(html, [opts])
f951727 @dodo Tag api docu
authored
348
349 ```javascript
350 tag.raw("<div>notfunny</div>")
351 ```
352 Insert raw html content into a tag.
353
8eef83d @dodo sub headline for class methods in readme
authored
354
f951727 @dodo Tag api docu
authored
355 Emits a `raw` and `data` Event.
356
357
8eef83d @dodo sub headline for class methods in readme
authored
358 #### tag.write(data, [opts])
f951727 @dodo Tag api docu
authored
359
360 ```javascript
361 fs = require('fs')
362 fs.createReadStream(filename).pipe(tag)
363 ```
364 Write tag data.
97bccf4 @dodo all the newlines!
authored
365
f951727 @dodo Tag api docu
authored
366 Useful to pipe file content into a tag (as text).
367 (dunno what happens if you pipe binary through)
368
2c042e4 @dodo refresh readme
authored
369 Options:
370 * `escape`
371
f951727 @dodo Tag api docu
authored
372 Emits a `data` Event.
373
374
8eef83d @dodo sub headline for class methods in readme
authored
375 #### tag.hide()
f951727 @dodo Tag api docu
authored
376
377 ```javascript
378 tag.hide()
379 ```
380 Hide a tag.
97bccf4 @dodo all the newlines!
authored
381
f951727 @dodo Tag api docu
authored
382 When a tag is hidden, `data` events are omitted.
383
384 Emits a `hide` Event.
385
386
8eef83d @dodo sub headline for class methods in readme
authored
387 #### tag.show()
f951727 @dodo Tag api docu
authored
388
389 ```javascript
390 tag.show()
391 ```
392 Show a tag.
97bccf4 @dodo all the newlines!
authored
393
f951727 @dodo Tag api docu
authored
394 Reverses the effect from `Tag::hide`.
395
396 Emits a `show` Event.
397
398
8eef83d @dodo sub headline for class methods in readme
authored
399 #### tag.end()
f951727 @dodo Tag api docu
authored
400
401 ```javascript
402 tag.end()
403 ```
404 Closes a tag.
97bccf4 @dodo all the newlines!
authored
405
f951727 @dodo Tag api docu
authored
406 The `end` event will only appear when all children tags are closed.
97bccf4 @dodo all the newlines!
authored
407
f951727 @dodo Tag api docu
authored
408 The `close` event gets triggered when the closing part of the tag (`</tag>`) gets emitted.
409
410 Emits an `end` and a `close` Event.
411
f074183 @dodo events docu
authored
412 ---
413
414 ## events
415
416 Some events have special behavior when it comes to where they can be received.
97bccf4 @dodo all the newlines!
authored
417
f074183 @dodo events docu
authored
418 Most events travel up the XML tree, some can be only received on their parents.
419
420 ### global
421
1624f5a @dodo code highlight event lists for better readability
authored
422 ```javascript
f27d20d @dodo update readme (no attr:remove event anymore)
authored
423 ['add', 'attr', 'text', 'raw', 'data', 'show', 'hide', 'remove', 'replace', 'close']
1624f5a @dodo code highlight event lists for better readability
authored
424 ````
f074183 @dodo events docu
authored
425 These events can be received from every single tag.
426
427 When you listen on a *specific tag* you get these events from the tag you are listening on and from all the children tags (recursive).
97bccf4 @dodo all the newlines!
authored
428
f074183 @dodo events docu
authored
429 When you listen on a *builder instance* you get all events from all tags.
430
431 ### local
f951727 @dodo Tag api docu
authored
432
1624f5a @dodo code highlight event lists for better readability
authored
433 ```javascript
434 ['new', 'end']
435 ```
f074183 @dodo events docu
authored
436 These events can be received from every single tag.
f951727 @dodo Tag api docu
authored
437
f074183 @dodo events docu
authored
438 When you listen for `new` on a *specific tag* you get 'new' events from only the tag you are listening on and from all its direct children (only 1 level deep).
97bccf4 @dodo all the newlines!
authored
439
f074183 @dodo events docu
authored
440 When you listen for `new` on a *builder instance* you get 'new' events for all the tags that are created direclty on the builder.
97bccf4 @dodo all the newlines!
authored
441
f074183 @dodo events docu
authored
442 When you listen for `end` on a *specific tag* you get the 'end' event only from the tag you are listening on.
97bccf4 @dodo all the newlines!
authored
443
f074183 @dodo events docu
authored
444 When you listen for `end` on a *builder instance* you get the 'end' event when the last tag is closed.
f951727 @dodo Tag api docu
authored
445
6a3a460 @dodo add readme
authored
446
2c042e4 @dodo refresh readme
authored
447 ## partials
448
449 It's recursive! just add a builder instance to a tag:
450 ```javascript
451 xml = new Builder
452 sub = new Builder
453 root = xml.tag('root').add(sub).end()
454 ```
455
6a3a460 @dodo add readme
authored
456
457
458 [![Build Status](https://secure.travis-ci.org/dodo/node-asyncxml.png)](http://travis-ci.org/dodo/node-asyncxml)
Something went wrong with that request. Please try again.