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