vnfmarket/src/main/webapp/vnfmarket/node_modules/method-override/README.md

   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 <!-- eslint-env browser -->
  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/