1 | # method-override
|
2 |
|
3 | [![NPM Version][npm-image]][npm-url]
|
4 | [![NPM Downloads][downloads-image]][downloads-url]
|
5 | [![Build Status][travis-image]][travis-url]
|
6 | [![Test Coverage][coveralls-image]][coveralls-url]
|
7 | [![Gratipay][gratipay-image]][gratipay-url]
|
8 |
|
9 | Lets you use HTTP verbs such as PUT or DELETE in places where the client doesn't support it.
|
10 |
|
11 | ## Install
|
12 |
|
13 | This is a [Node.js](https://nodejs.org/en/) module available through the
|
14 | [npm registry](https://www.npmjs.com/). Installation is done using the
|
15 | [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
|
16 |
|
17 | ```sh
|
18 | $ npm install method-override
|
19 | ```
|
20 |
|
21 | ## API
|
22 |
|
23 | **NOTE** It is very important that this module is used **before** any module that
|
24 | needs to know the method of the request (for example, it _must_ be used prior to
|
25 | the `csurf` module).
|
26 |
|
27 | ### methodOverride(getter, options)
|
28 |
|
29 | Create a new middleware function to override the `req.method` property with a new
|
30 | value. This value will be pulled from the provided `getter`.
|
31 |
|
32 | - `getter` - The getter to use to look up the overridden request method for the request. (default: `X-HTTP-Method-Override`)
|
33 | - `options.methods` - The allowed methods the original request must be in to check for a method override value. (default: `['POST']`)
|
34 |
|
35 | If the found method is supported by node.js core, then `req.method` will be set to
|
36 | this value, as if it has originally been that value. The previous `req.method`
|
37 | value will be stored in `req.originalMethod`.
|
38 |
|
39 | #### getter
|
40 |
|
41 | This is the method of getting the override value from the request. If a function is provided,
|
42 | the `req` is passed as the first argument, the `res` as the second argument and the method is
|
43 | expected to be returned. If a string is provided, the string is used to look up the method
|
44 | with the following rules:
|
45 |
|
46 | - If the string starts with `X-`, then it is treated as the name of a header and that header
|
47 | is used for the method override. If the request contains the same header multiple times, the
|
48 | first occurrence is used.
|
49 | - All other strings are treated as a key in the URL query string.
|
50 |
|
51 | #### options.methods
|
52 |
|
53 | This allows the specification of what methods(s) the request *MUST* be in in order to check for
|
54 | the method override value. This defaults to only `POST` methods, which is the only method the
|
55 | override should arrive in. More methods may be specified here, but it may introduce security
|
56 | issues and cause weird behavior when requests travel through caches. This value is an array
|
57 | of methods in upper-case. `null` can be specified to allow all methods.
|
58 |
|
59 | ## Examples
|
60 |
|
61 | ### override using a header
|
62 |
|
63 | To use a header to override the method, specify the header name
|
64 | as a string argument to the `methodOverride` function. To then make
|
65 | the call, send a `POST` request to a URL with the overridden method
|
66 | as the value of that header. This method of using a header would
|
67 | typically be used in conjunction with `XMLHttpRequest` on implementations
|
68 | that do not support the method you are trying to use.
|
69 |
|
70 | ```js
|
71 | var express = require('express')
|
72 | var methodOverride = require('method-override')
|
73 | var app = express()
|
74 |
|
75 | // override with the X-HTTP-Method-Override header in the request
|
76 | app.use(methodOverride('X-HTTP-Method-Override'))
|
77 | ```
|
78 |
|
79 | Example call with header override using `XMLHttpRequest`:
|
80 |
|
81 |
|
82 |
|
83 | ```js
|
84 | var xhr = new XMLHttpRequest()
|
85 | xhr.onload = onload
|
86 | xhr.open('post', '/resource', true)
|
87 | xhr.setRequestHeader('X-HTTP-Method-Override', 'DELETE')
|
88 | xhr.send()
|
89 |
|
90 | function onload () {
|
91 | alert('got response: ' + this.responseText)
|
92 | }
|
93 | ```
|
94 |
|
95 | ### override using a query value
|
96 |
|
97 | To use a query string value to override the method, specify the query
|
98 | string key as a string argument to the `methodOverride` function. To
|
99 | then make the call, send a `POST` request to a URL with the overridden
|
100 | method as the value of that query string key. This method of using a
|
101 | query value would typically be used in conjunction with plain HTML
|
102 | `<form>` elements when trying to support legacy browsers but still use
|
103 | newer methods.
|
104 |
|
105 | ```js
|
106 | var express = require('express')
|
107 | var methodOverride = require('method-override')
|
108 | var app = express()
|
109 |
|
110 | // override with POST having ?_method=DELETE
|
111 | app.use(methodOverride('_method'))
|
112 | ```
|
113 |
|
114 | Example call with query override using HTML `<form>`:
|
115 |
|
116 | ```html
|
117 | <form method="POST" action="/resource?_method=DELETE">
|
118 | <button type="submit">Delete resource</button>
|
119 | </form>
|
120 | ```
|
121 |
|
122 | ### multiple format support
|
123 |
|
124 | ```js
|
125 | var express = require('express')
|
126 | var methodOverride = require('method-override')
|
127 | var app = express()
|
128 |
|
129 | // override with different headers; last one takes precedence
|
130 | app.use(methodOverride('X-HTTP-Method')) // Microsoft
|
131 | app.use(methodOverride('X-HTTP-Method-Override')) // Google/GData
|
132 | app.use(methodOverride('X-Method-Override')) // IBM
|
133 | ```
|
134 |
|
135 | ### custom logic
|
136 |
|
137 | You can implement any kind of custom logic with a function for the `getter`. The following
|
138 | implements the logic for looking in `req.body` that was in `method-override@1`:
|
139 |
|
140 | ```js
|
141 | var bodyParser = require('body-parser')
|
142 | var express = require('express')
|
143 | var methodOverride = require('method-override')
|
144 | var app = express()
|
145 |
|
146 | // NOTE: when using req.body, you must fully parse the request body
|
147 | // before you call methodOverride() in your middleware stack,
|
148 | // otherwise req.body will not be populated.
|
149 | app.use(bodyParser.urlencoded())
|
150 | app.use(methodOverride(function (req, res) {
|
151 | if (req.body && typeof req.body === 'object' && '_method' in req.body) {
|
152 | // look in urlencoded POST bodies and delete it
|
153 | var method = req.body._method
|
154 | delete req.body._method
|
155 | return method
|
156 | }
|
157 | }))
|
158 | ```
|
159 |
|
160 | Example call with query override using HTML `<form>`:
|
161 |
|
162 | ```html
|
163 | <!-- enctype must be set to the type you will parse before methodOverride() -->
|
164 | <form method="POST" action="/resource" enctype="application/x-www-form-urlencoded">
|
165 | <input type="hidden" name="_method" value="DELETE">
|
166 | <button type="submit">Delete resource</button>
|
167 | </form>
|
168 | ```
|
169 |
|
170 | ## License
|
171 |
|
172 | [MIT](LICENSE)
|
173 |
|
174 | [npm-image]: https://img.shields.io/npm/v/method-override.svg
|
175 | [npm-url]: https://npmjs.org/package/method-override
|
176 | [travis-image]: https://img.shields.io/travis/expressjs/method-override/master.svg
|
177 | [travis-url]: https://travis-ci.org/expressjs/method-override
|
178 | [coveralls-image]: https://img.shields.io/coveralls/expressjs/method-override/master.svg
|
179 | [coveralls-url]: https://coveralls.io/r/expressjs/method-override?branch=master
|
180 | [downloads-image]: https://img.shields.io/npm/dm/method-override.svg
|
181 | [downloads-url]: https://npmjs.org/package/method-override
|
182 | [gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg
|
183 | [gratipay-url]: https://www.gratipay.com/dougwilson/
|