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