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