source: trip-planner-front/node_modules/content-disposition/README.md@ 6a3a178

Last change on this file since 6a3a178 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 5.1 KB
Line 
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<!-- eslint-disable no-unused-vars -->
20
21```js
22var contentDisposition = require('content-disposition')
23```
24
25### contentDisposition(filename, options)
26
27Create an attachment `Content-Disposition` header value using the given file name,
28if supplied. The `filename` is optional and if no file name is desired, but you
29want to specify `options`, set `filename` to `undefined`.
30
31<!-- eslint-disable no-undef -->
32
33```js
34res.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
38header through a means different from `setHeader` in Node.js, you'll want to specify
39the `'binary'` encoding in Node.js.
40
41#### Options
42
43`contentDisposition` accepts these properties in the options object.
44
45##### fallback
46
47If the `filename` option is outside ISO-8859-1, then the file name is actually
48stored in a supplemental field for clients that support Unicode file names and
49a ISO-8859-1 version of the file name is automatically generated.
50
51This specifies the ISO-8859-1 file name to override the automatic generation or
52disables 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
60If the `filename` option is ISO-8859-1 and this option is specified and has a
61different value, then the `filename` option is encoded in the extended field
62and this set as the fallback field, even though they are both ISO-8859-1.
63
64##### type
65
66Specifies 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
69it). The type is normalized to lower-case.
70
71### contentDisposition.parse(string)
72
73<!-- eslint-disable no-undef, no-unused-vars -->
74
75```js
76var disposition = contentDisposition.parse('attachment; filename="EURO rates.txt"; filename*=UTF-8\'\'%e2%82%ac%20rates.txt')
77```
78
79Parse a `Content-Disposition` header string. This automatically handles extended
80("Unicode") parameters by decoding them and providing them under the standard
81parameter name. This will return an object with the following properties (examples
82are 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
95var contentDisposition = require('content-disposition')
96var destroy = require('destroy')
97var fs = require('fs')
98var http = require('http')
99var onFinished = require('on-finished')
100
101var filePath = '/path/to/public/plans.pdf'
102
103http.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
Note: See TracBrowser for help on using the repository browser.