This API method provides access to the chrome-privileged XMLHttpRequest object. This means that it is possible to issue requests to domains other than that of the current page.
Additional reference may be found at:
⬆ ⬇ | Examples | See Also | Notes
GM_xmlhttpRequest( details )
Value: Function
Compatibility: Greasemonkey 0.2.5+
Access: @grant
Returns:
undefined with Greasemonkey 1.8.0-details Object
| Properties | Event Handler Callbacks | Methods |
|---|---|---|
method
user
onload
abort
url
password
onreadystatechange
headers
upload
onerror
overrideMimeType
synchronous
ontimeout
data
timeout
onprogress
binary
onabort
Value: String
Usage: details.method = "GET";
Value: String
Usage: details.url = "http://www.example.com/";
Value: Object
Usage: details.headers = {"User-Agent":"Mozilla/5.0"};
headers property is an object which is typically used to override the default browser generated headers, also known as atoms. It should contain the atom-value pairs of the headers to send.2Value: String
Compatibility: Greasemonkey 0.6.8+
Usage: details.overrideMimeType = "text/html; charset=ISO-8859-1";
Value: String
Usage: details.data = null; /* some code */ if (details.data) { /* some code */ }
data field contains form-encoded data, you must also set the header 'Content-Type': 'application/x-www-form-urlencoded' in the headers field.Value: Boolean
Compatibility: Greasemonkey 0.8.3+
Usage: details.binary = true;
Value: String
Compatibility: Greasemonkey 0.9.0+
Usage: details.user = "johndoe";
Value: String
Compatibility: Greasemonkey 0.9.0+
Usage:
details.password = "password";
Value: Object
Compatibility: Greasemonkey 0.9.9+
Value: Boolean
Default: false
Compatibility: Greasemonkey 0.9.9+
Usage: details.synchronous = true;
Value: Number
Default: 0
Compatibility: Greasemonkey 1.0.0+
Usage: details.timeout = 60000;
Usage: details.onload = function (response) { /* some code */ };
Returns: undefined, response Object
Usage: details.onreadystatechange = function (response) { /* some code */ };
Returns: undefined, response Object
Usage: details.onerror = function (response) { /* some code */ };
Returns: undefined, response Object
Usage: details.ontimeout = function (response) { /* some code */ };
Compatibility: Greasemonkey 0.9.9+*
Returns: undefined, response Object
Usage: details.onprogress = function (response) { /* some code */ };
Compatibility: Greasemonkey 0.9.9+*
Returns: undefined, response Object
Usage: details.onabort = function (response) { /* some code */ };
Compatibility: Greasemonkey 0.9.9+*
Returns: undefined, response Object
Usage: var req = GM_xmlhttpRequest({ /* Some intialization */ }); req.abort();
Compatibility: Greasemonkey 0.9.9+*
response Object
| Properties |
|---|
Properties
status
readyState
responseText
finalUrl
statusText
responseHeaders
responseXML property, contrary to what people used to XMLHttpRequest might expect. This is due to security restrictions imposed on the XMLDocument created in the privileged GM core context. One can easily create its own document object out of responseText using a DOMParser.Value: Number
Usage: if (response.status == 200) { /* some code */ }
Value: String
Usage: if (response.statusText == "OK") { /* some code */ }
Value: Number
Usage: if (response.readyState == 4) { /* some code */ }
Value: String
Usage: alert(response.responseText);
Value: String
Usage: if (response.responseHeaders) { /* some code */ }
responseHeaders is the string representation of response headers returned by XMLHTTPRequest.getAllResponseHeaders().Value: String
Compatibility: Greasemonkey 0.8.0+
Usage: if (response.finalUrl) { /* some code */ }
⬆ ⬇ | GET request | POST request | HEAD request
GM_xmlhttpRequest({
method: "GET",
url: "http://www.example.net/",
headers: {
"User-Agent": "Mozilla/5.0", // If not specified, navigator.userAgent will be used.
"Accept": "text/xml" // If not specified, browser defaults will be used.
},
onload: function(response) {
GM_log([
response.status,
response.statusText,
response.readyState,
response.responseHeaders,
response.responseText,
response.finalUrl
].join("\n"));
}
});
When making a POST request, some sites require the Content-Type header to be included as such:
GM_xmlhttpRequest({
method: "POST",
url: "http://www.example.net/login",
data: "username=johndoe&password=xyz123",
headers: {
"Content-Type": "application/x-www-form-urlencoded"
},
onload: function(response) {
if (response.responseText.indexOf("Logged in as") > -1)
location.href = "http://www.example.net/dashboard";
}
});
Sometimes responseText may be unnecessary, in which case a "HEAD" request is more advisable.
GM_xmlhttpRequest({
url: "http://www.example.com",
method: "HEAD",
onload: function(response) {
GM_log(response.responseHeaders);
}
});
1Some users have reported problems with international character sets. See these [Mailing_list] threads
Resolved: Greasemonkey exposed the overrideMimeType method to allow changing of the desired charset.
2Some header atoms may not actually work through GM_xmlhttpRequest. The Referer atom is one that is known to be recognized but appears to be content filtered by the browser. This may be due to security restrictions to keep user scripts from doing unsafe things.