testing new parallax image
[josuexyz/.git] / node_modules / content-disposition / README.md
1 # content-disposition
2
3 [![NPM Version][npm-image]][npm-url]
4 [![NPM Downloads][downloads-image]][downloads-url]
5 [![Node.js Version][node-version-image]][node-version-url]
6 [![Build Status][travis-image]][travis-url]
7 [![Test Coverage][coveralls-image]][coveralls-url]
8
9 Create and parse HTTP `Content-Disposition` header
10
11 ## Installation
12
13 ```sh
14 $ npm install content-disposition
15 ```
16
17 ## API
18
19 ```js
20 var contentDisposition = require('content-disposition')
21 ```
22
23 ### contentDisposition(filename, options)
24
25 Create an attachment `Content-Disposition` header value using the given file name,
26 if supplied. The `filename` is optional and if no file name is desired, but you
27 want to specify `options`, set `filename` to `undefined`.
28
29 ```js
30 res.setHeader('Content-Disposition', contentDisposition('∫ maths.pdf'))
31 ```
32
33 **note** HTTP headers are of the ISO-8859-1 character set. If you are writing this
34 header through a means different from `setHeader` in Node.js, you'll want to specify
35 the `'binary'` encoding in Node.js.
36
37 #### Options
38
39 `contentDisposition` accepts these properties in the options object.
40
41 ##### fallback
42
43 If the `filename` option is outside ISO-8859-1, then the file name is actually
44 stored in a supplemental field for clients that support Unicode file names and
45 a ISO-8859-1 version of the file name is automatically generated.
46
47 This specifies the ISO-8859-1 file name to override the automatic generation or
48 disables the generation all together, defaults to `true`.
49
50   - A string will specify the ISO-8859-1 file name to use in place of automatic
51     generation.
52   - `false` will disable including a ISO-8859-1 file name and only include the
53     Unicode version (unless the file name is already ISO-8859-1).
54   - `true` will enable automatic generation if the file name is outside ISO-8859-1.
55
56 If the `filename` option is ISO-8859-1 and this option is specified and has a
57 different value, then the `filename` option is encoded in the extended field
58 and this set as the fallback field, even though they are both ISO-8859-1.
59
60 ##### type
61
62 Specifies the disposition type, defaults to `"attachment"`. This can also be
63 `"inline"`, or any other value (all values except inline are treated like
64 `attachment`, but can convey additional information if both parties agree to
65 it). The type is normalized to lower-case.
66
67 ### contentDisposition.parse(string)
68
69 ```js
70 var disposition = contentDisposition.parse('attachment; filename="EURO rates.txt"; filename*=UTF-8\'\'%e2%82%ac%20rates.txt');
71 ```
72
73 Parse a `Content-Disposition` header string. This automatically handles extended
74 ("Unicode") parameters by decoding them and providing them under the standard
75 parameter name. This will return an object with the following properties (examples
76 are shown for the string `'attachment; filename="EURO rates.txt"; filename*=UTF-8\'\'%e2%82%ac%20rates.txt'`):
77
78  - `type`: The disposition type (always lower case). Example: `'attachment'`
79
80  - `parameters`: An object of the parameters in the disposition (name of parameter
81    always lower case and extended versions replace non-extended versions). Example:
82    `{filename: "€ rates.txt"}`
83
84 ## Examples
85
86 ### Send a file for download
87
88 ```js
89 var contentDisposition = require('content-disposition')
90 var destroy = require('destroy')
91 var http = require('http')
92 var onFinished = require('on-finished')
93
94 var filePath = '/path/to/public/plans.pdf'
95
96 http.createServer(function onRequest(req, res) {
97   // set headers
98   res.setHeader('Content-Type', 'application/pdf')
99   res.setHeader('Content-Disposition', contentDisposition(filePath))
100
101   // send file
102   var stream = fs.createReadStream(filePath)
103   stream.pipe(res)
104   onFinished(res, function (err) {
105     destroy(stream)
106   })
107 })
108 ```
109
110 ## Testing
111
112 ```sh
113 $ npm test
114 ```
115
116 ## References
117
118 - [RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1][rfc-2616]
119 - [RFC 5987: Character Set and Language Encoding for Hypertext Transfer Protocol (HTTP) Header Field Parameters][rfc-5987]
120 - [RFC 6266: Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP)][rfc-6266]
121 - [Test Cases for HTTP Content-Disposition header field (RFC 6266) and the Encodings defined in RFCs 2047, 2231 and 5987][tc-2231]
122
123 [rfc-2616]: https://tools.ietf.org/html/rfc2616
124 [rfc-5987]: https://tools.ietf.org/html/rfc5987
125 [rfc-6266]: https://tools.ietf.org/html/rfc6266
126 [tc-2231]: http://greenbytes.de/tech/tc2231/
127
128 ## License
129
130 [MIT](LICENSE)
131
132 [npm-image]: https://img.shields.io/npm/v/content-disposition.svg?style=flat
133 [npm-url]: https://npmjs.org/package/content-disposition
134 [node-version-image]: https://img.shields.io/node/v/content-disposition.svg?style=flat
135 [node-version-url]: https://nodejs.org/en/download
136 [travis-image]: https://img.shields.io/travis/jshttp/content-disposition.svg?style=flat
137 [travis-url]: https://travis-ci.org/jshttp/content-disposition
138 [coveralls-image]: https://img.shields.io/coveralls/jshttp/content-disposition.svg?style=flat
139 [coveralls-url]: https://coveralls.io/r/jshttp/content-disposition?branch=master
140 [downloads-image]: https://img.shields.io/npm/dm/content-disposition.svg?style=flat
141 [downloads-url]: https://npmjs.org/package/content-disposition