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
  9Create and parse HTTP `Content-Disposition` header
 10
 11## Installation
 12
 13```sh
 14$ npm install content-disposition
 15```
 16
 17## API
 18
 19```js
 20var contentDisposition = require('content-disposition')
 21```
 22
 23### contentDisposition(filename, options)
 24
 25Create an attachment `Content-Disposition` header value using the given file name,
 26if supplied. The `filename` is optional and if no file name is desired, but you
 27want to specify `options`, set `filename` to `undefined`.
 28
 29```js
 30res.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
 34header through a means different from `setHeader` in Node.js, you'll want to specify
 35the `'binary'` encoding in Node.js.
 36
 37#### Options
 38
 39`contentDisposition` accepts these properties in the options object.
 40
 41##### fallback
 42
 43If the `filename` option is outside ISO-8859-1, then the file name is actually
 44stored in a supplemental field for clients that support Unicode file names and
 45a ISO-8859-1 version of the file name is automatically generated.
 46
 47This specifies the ISO-8859-1 file name to override the automatic generation or
 48disables 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
 56If the `filename` option is ISO-8859-1 and this option is specified and has a
 57different value, then the `filename` option is encoded in the extended field
 58and this set as the fallback field, even though they are both ISO-8859-1.
 59
 60##### type
 61
 62Specifies 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
 65it). The type is normalized to lower-case.
 66
 67### contentDisposition.parse(string)
 68
 69```js
 70var disposition = contentDisposition.parse('attachment; filename="EURO rates.txt"; filename*=UTF-8\'\'%e2%82%ac%20rates.txt"');
 71```
 72
 73Parse a `Content-Disposition` header string. This automatically handles extended
 74("Unicode") parameters by decoding them and providing them under the standard
 75parameter name. This will return an object with the following properties (examples
 76are 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
 89var contentDisposition = require('content-disposition')
 90var destroy = require('destroy')
 91var http = require('http')
 92var onFinished = require('on-finished')
 93
 94var filePath = '/path/to/public/plans.pdf'
 95
 96http.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]: http://nodejs.org/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