https://wiki.greasespot.net/api.php?action=feedcontributions&user=Franklin+Yu&feedformat=atomGreaseSpot Wiki - User contributions [en]2024-03-28T18:37:07ZUser contributionsMediaWiki 1.41.0https://wiki.greasespot.net/index.php?title=GM.xmlHttpRequest&diff=7737GM.xmlHttpRequest2020-04-24T22:03:25Z<p>Franklin Yu: /* Arguments */ add default value and mark parameters as required (although it was already implied)</p>
<hr />
<div>== Description ==<br />
<br />
This method performs a similar function to the standard [http://developer.mozilla.org/en/docs/XMLHttpRequest XMLHttpRequest] object, but allows these requests to cross the [https://developer.mozilla.org/En/Same_origin_policy_for_JavaScript same origin policy] boundaries.<br />
<br />
== Syntax ==<br />
<br />
{{Function|GM.xmlHttpRequest|details}}<br />
<br />
Compatibility: [[Version_history#4.0_2|Greasemonkey 4.0+]]<br />
<br />
=== Arguments ===<br />
<br />
This method only takes one argument, the <code>details</code> object.<br />
Described below are the ''properties'' that may be defined on that object.<br />
See [[#Examples]] for more detail on how to use each.<br />
<br />
Fields:<br />
<br />
; <code>binary</code><br />
: <code>Boolean</code> Optional, default false. When true, the <code>data</code> is sent as a Blob.<br />
; <code>context</code><br />
: <code>Object</code> (Compatibility: [[Version_history#1.10|1.10+]]) Optional, any object. This object will also be the <code>context</code> property of the [[#Response Object]].<br />
; <code>data</code><br />
: <code>String</code> Optional. Data to send in the request body. Usually for <code>POST</code> method requests. <sup>[[#Notes|[1]]]</sup><br />
; <code>headers</code><br />
: <code>Object</code> Optional. A set of headers to include in the request. <sup>[[#Notes|[2]]]</sup><br />
; <code>method</code><br />
: <code>String</code> Required. Type of HTTP request to make (E.G. <code>"GET"</code>, <code>"POST"</code>)<br />
; <code>overrideMimeType</code><br />
: <code>String</code> Optional. A MIME type to specify with the request (E.G. <code>"text/html; charset=ISO-8859-1"</code>).<br />
; <code>password</code><br />
: <code>String</code> Optional. Password to use for authentication purposes.<br />
; <code>synchronous</code><br />
: <code>Boolean</code> Defaults to false. When true, this is a ''synchronous'' request. '''Be careful''': The entire Firefox UI will be locked and frozen until the request completes. In this mode, more data will be available in the [[#Returns|return value]].<br />
; <code>timeout</code><br />
: <code>Number</code> The number of milliseconds to wait before terminating the call; zero (the default) means wait forever.<br />
; <code>upload</code><br />
: <code>Object</code> Optional. Object containing optional function callbacks (<code>onabort</code>, <code>onerror</code>, <code>onload</code>, <code>onprogress</code>) to monitor the upload of data. Each is passed one argument, the [[#Response Object]].<br />
; <code>url</code><br />
: <code>String</code> Required. The URL to make the request to. Must be an absolute URL, beginning with the scheme. May be relative to the current page.<br />
; <code>user</code><br />
: <code>String</code> Optional. User name to use for authentication purposes.<br />
<br />
Event handlers:<br />
<br />
; <code>onabort</code><br />
: <code>Function</code> Optional. Will be called when the request is aborted. Passed one argument, the [[#Response Object]].<br />
; <code>onerror</code><br />
: <code>Function</code> Optional. Will be called if an error occurs while processing the request. Passed one argument, the [[#Response Object]].<br />
; <code>onload</code><br />
: <code>Function</code> Optional. Will be called when the request has completed successfully. Passed one argument, the [[#Response Object]].<br />
; <code>onprogress</code><br />
: <code>Function</code> Optional. Will be called when the request progress changes. Passed one argument, the [[#Response Object]].<br />
; <code>onreadystatechange</code><br />
: <code>Function</code> Optional. Will be called repeatedly while the request is in progress. Passed one argument, the [[#Response Object]].<br />
; <code>ontimeout</code><br />
: <code>Function</code> Optional. Will be called if/when the request times out. Passed one argument, the [[#Response Object]].<br />
<br />
==== Response Object ====<br />
<br />
All of the callback functions defined in the <code>details</code> object, if called, will receive this type of object as their first (and only) argument.<br />
The data available will vary slightly, depending on the type of callback.<br />
<br />
Properties based on a standard [https://developer.mozilla.org/en/xmlhttprequest#Properties XMLHttpRequest] object:<br />
* <code>readyState</code><br />
* <code>responseHeaders</code><br />
* <code>responseText</code><br />
* <code>status</code><br />
* <code>statusText</code><br />
<br />
Greasemonkey custom properties:<br />
* <code>context</code><br><code>Object</code> The same object passed into the original request.<br />
<!-- Not yet in 4.x<br />
* <code>finalUrl</code><br><code>String</code> (Compatibility: [[Version_history#0.8.20080609.0|0.8.0+]]) The final URL requested, if <code>Location</code> redirects were followed.<br />
--><br />
<br />
Properties for <code>progress</code> callbacks, based on [https://developer.mozilla.org/En/nsIDOMProgressEvent nsIDOMProgressEvent]:<br />
* <code>lengthComputable</code><br />
* <code>loaded</code><br />
* <code>total</code><br />
<br />
== Returns ==<br />
<br />
<code>undefined</code><br />
<br />
== Examples ==<br />
<br />
=== Bare Minimum ===<br />
<br />
<pre class='sample'><br />
GM.xmlHttpRequest({<br />
method: "GET",<br />
url: "http://www.example.com/",<br />
onload: function(response) {<br />
alert(response.responseText);<br />
}<br />
});<br />
</pre><br />
<br />
=== GET request ===<br />
<br />
<pre class='sample'><br />
GM.xmlHttpRequest({<br />
method: "GET",<br />
url: "http://www.example.net/",<br />
headers: {<br />
"User-Agent": "Mozilla/5.0", // If not specified, navigator.userAgent will be used.<br />
"Accept": "text/xml" // If not specified, browser defaults will be used.<br />
},<br />
onload: function(response) {<br />
var responseXML = null;<br />
// Inject responseXML into existing Object (only appropriate for XML content).<br />
if (!response.responseXML) {<br />
responseXML = new DOMParser()<br />
.parseFromString(response.responseText, "text/xml");<br />
}<br />
<br />
console.log([<br />
response.status,<br />
response.statusText,<br />
response.readyState,<br />
response.responseHeaders,<br />
response.responseText,<br />
response.finalUrl,<br />
responseXML<br />
].join("\n"));<br />
}<br />
});<br />
</pre><br />
<br />
=== POST request ===<br />
<br />
When making a POST request, '''most''' sites require the Content-Type header to be defined as such:<br />
<br />
<pre class='sample'><br />
GM.xmlHttpRequest({<br />
method: "POST",<br />
url: "http://www.example.net/login",<br />
data: "username=johndoe&password=xyz123",<br />
headers: {<br />
"Content-Type": "application/x-www-form-urlencoded"<br />
},<br />
onload: function(response) {<br />
if (response.responseText.indexOf("Logged in as") > -1) {<br />
location.href = "http://www.example.net/dashboard";<br />
}<br />
}<br />
});<br />
</pre><br />
<br />
=== HEAD request ===<br />
<br />
As defined in HTTP, you may issue a HEAD request to get the response headers, without receiving the entire response body.<br />
<br />
<pre class='sample'><br />
GM.xmlHttpRequest({<br />
url: "http://www.example.com",<br />
method: "HEAD",<br />
onload: function(response) {<br />
console.log(response.responseHeaders);<br />
}<br />
});</pre><br />
<br />
== Notes ==<br />
<br />
If the <code>data</code> field contains form-encoded data, you usually must also set the header <code>'Content-Type': 'application/x-www-form-urlencoded'</code> in the <code>headers</code> field.<br />
<br />
[[Category:API_Reference|X]]</div>Franklin Yu