Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 158 lines (100 sloc) 4.755 kb
9828d88 @felixge Initial documentation
authored
1 # Formidable
2
3 ## Purpose
4
5 A node.js module for dealing with web forms.
6
7 ## Features
8
3eb0f94 @felixge Used an actual boundary from firefox for benchmark
authored
9 * Fast (~500mb/sec), non-buffering multipart parser
81b31ea @felixge Further doc improvements
authored
10 * Automatically writing file uploads to disk
11 * Low memory footprint
9828d88 @felixge Initial documentation
authored
12 * Graceful error handling
dd4b802 @felixge Update readme
authored
13 * Very high test coverage
9828d88 @felixge Initial documentation
authored
14
15 ### Todo
16
17 * Limit buffer size for fields
132d716 @felixge Support for urlencoded forms
authored
18 * Implement QuerystringParser the same way as MultipartParser
9828d88 @felixge Initial documentation
authored
19
dd4b802 @felixge Update readme
authored
20 ## Installation
21
22 Via [npm](http://github.com/isaacs/npm):
23
24 npm install formidable@latest
25
8ead0e5 @felixge Manual install instructions
authored
26 Manually:
27
28 git clone git://github.com/felixge/node-formidable.git formidable
29 vim my.js
30 # var formidable = require('./formidable');
31
32 Note: Formidable requires [gently](http://github.com/felixge/node-gently) to run the unit tests, but you won't need it for just using the library.
dd4b802 @felixge Update readme
authored
33
9828d88 @felixge Initial documentation
authored
34 ## Example
35
36 Parse an incoming file upload.
37
38 var formidable = require('formidable')
39 , http = require('http')
aa57d74 @felixge Improved the Readme example
authored
40 , sys = require('sys');
41
9828d88 @felixge Initial documentation
authored
42 http.createServer(function(req, res) {
aa57d74 @felixge Improved the Readme example
authored
43 if (req.url == '/upload' && req.method.toLowerCase() == 'post') {
44 // parse a file upload
45 var form = new formidable.IncomingForm();
9828d88 @felixge Initial documentation
authored
46 form.parse(req, function(fields, files) {
47 res.writeHead(200, {'content-type': 'text/plain'});
48 res.write('received upload:\n\n');
49 res.end(sys.inspect({fields: fields, files: files}));
50 });
aa57d74 @felixge Improved the Readme example
authored
51 return;
9828d88 @felixge Initial documentation
authored
52 }
aa57d74 @felixge Improved the Readme example
authored
53
54 // show a file upload form
55 res.writeHead(200, {'content-type': 'text/html'});
56 res.end
57 ( '<form action="/upload" enctype="multipart/form-data" method="post">'
58 + '<input type="text" name="title"><br>'
59 + '<input type="file" name="upload" multiple="multiple"><br>'
60 + '<input type="submit" value="Upload">'
61 + '</form>'
62 );
9828d88 @felixge Initial documentation
authored
63 });
64
65 ## API
66
67 ### formdiable.IncomingForm
68
69 #### new formdiable.IncomingForm()
70
71 Creates a new incoming form.
72
73 #### incomingForm.encoding = 'utf-8'
74
75 The encoding to use for incoming form fields.
76
77 #### incomingForm.uploadDir = '/tmp'
78
79 The directory for placing file uploads in. You can later on move them using `fs.rename()`.
80
10c57f0 @felixge New feature: form.keepExtensions
authored
81 #### incomingForm.keepExtensions = false
82
83 If you want the files written to `incomingForm.uploadDir` to include the extensions of the original files, set this property to `true`.
84
9828d88 @felixge Initial documentation
authored
85 #### incomingForm.type
86
87 Either 'multipart' or 'urlencoded' depending on the incoming request.
88
89 #### incomingForm.bytesReceived
90
7efb618 @felixge New 'progress' event
authored
91 The amount of bytes received for this form so far.
9828d88 @felixge Initial documentation
authored
92
93 #### incomingForm.bytesExpected
94
95 The expected number of bytes in this form.
96
97 #### incomingForm.parse(request, [cb])
98
99 Parses an incoming node.js `request` containing form data. If `cb` is provided, all fields an files are collected and passed to the callback:
100
101 incomingForm.parse(req, function(err, fields, files) {
102 // ...
103 });
104
81b31ea @felixge Further doc improvements
authored
105 #### incomingForm.onPart(part)
106
107 You may overwrite this method if you are interested in directly accessing the multipart stream. Doing so will disable any `'field'` / `'file'` events processing which would occur otherwise, making you fully responsible for handling the processing.
108
109 incomingForm.onPart = function(part) {
110 part.addListener('data', function() {
111 // ...
112 });
113 }
114
f23f547 @felixge Make auto-handling only certain parts to easier
authored
115 If you want to use formidable to only handle certain parts for you, you can do so:
116
117 incomingForm.onPart = function(part) {
118 if (!part.filename) {
119 // let formidable handle all non-file parts
120 incomingForm.handlePart(part);
121 }
122 }
123
81b31ea @felixge Further doc improvements
authored
124 Check the code in this method for further inspiration.
125
7efb618 @felixge New 'progress' event
authored
126 #### Event: 'progress' (bytesReceived, bytesExpected)
127
128 Emitted after each incoming chunk of data that has been parsed. Can be used to roll your own progress bar.
129
9828d88 @felixge Initial documentation
authored
130 #### Event: 'field' (name, value)
131
132 Emitted whenever a field / value pair has been received.
133
134 #### Event: 'file' (name, file)
135
136 Emitted whenever a field / file pair has been received. `file` is a JS object with the following properties:
137
138 { path: 'the path in the uploadDir this file was written to'
139 , filename: 'the name this file had on the computer of the uploader'
140 , mime: 'the mime type specified by the user agent of the uploader'
141 }
142
143 #### Event: 'error' (err)
144
145 Emitted when there is an error processing the incoming form. A request that experiences an error is automatically paused, you will have to manually call `request.resume()` if you want the request to continue firing `'data'` events.
146
147 #### Event: 'end' ()
148
96b9551 @felixge License and credits
authored
149 Emitted when the entire request has been received, and all contained files have finished flushing to disk. This is a great place for you to send your response.
150
151 ## License
152
153 Formidable is licensed under the MIT license.
154
155 ## Credits
156
157 * [Ryan Dahl](http://twitter.com/ryah) for his work on [http-parser](http://github.com/ry/http-parser) which heavily inspired multipart_parser.js
Something went wrong with that request. Please try again.