GM.xmlHttpRequest

From GreaseSpot Wiki
Revision as of 22:30, 8 February 2010 by Arantius (talk | contribs) (simplify)
Jump to navigationJump to search


Description

This method performs a similar function to the standard XMLHttpRequest object, but allows these requests to cross the same origin policy boundaries.

Compatibility: Greasemonkey 0.2.5+

Syntax

function GM_xmlhttpRequest( details )

Arguments

This method only takes one argument, the details object. Described below are the properties that may be defined on that object. See #Examples for more detail on how to use each.

method
String Type of HTTP request to make (E.G. "GET", "POST")
url
String The URL to make the request to. Must be an absolute URL, beginning with the scheme.
headers
Object Optional. A set of headers to include in the request. [2]
overrideMimeType
String (Compatibility: 0.6.8+) Optional. A MIME type to specify with the request (E.G. "text/html; charset=ISO-8859-1").
data
String Optional. Data to send in the request body. Usually for POST method requests. [1]
binary
Boolean (Compatibility: 0.8.3+) Optional, default false. When true, use the underlying .sendAsBinary() method.
onerror
Function Optional. Will be called when the request has completed successfully. Passed one argument, the #Response Object.
onload
Function Optional. Will be called when the request has completed successfully. Passed one argument, the #Response Object.
onreadystatechange
Function Optional. Will be called when the request has completed successfully. Passed one argument, the #Response Object.

Response Object

All three of the callback functions defined in the details object, if called, will receive this type of object as their first (and only) argument.

status
Integer The HTTP response status (E.G. 200 or 404) upon success, or null upon failure.
statusText
String The HTTP response status line (E.G. "OK", "Not Found") upon success, or null upon failure.
readyState
Number The readyState as defined in XMLHttpRequest.
responseText
String The responseText as defined in XMLHttpRequest.
responseHeaders
String The response headers as defined in XMLHttpRequest.
finalUrl
String (Compatibility: 0.8.0+) The final URL requested, if Location redirects were followed.

Examples

GET 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) {
    // Inject responseXML into existing Object if not present
    if (!response.responseXML) {
      response.responseXML = new DOMParser()
        .parseFromString(response.responseText, "text/xml");
    }

    GM_log([
      response.status,
      response.statusText,
      response.readyState,
      response.responseHeaders,
      response.responseText,
      response.finalUrl,
      response.responseXML
    ].join("\n"));
  }
});

POST request

When making a POST request, most sites require the Content-Type header to be defined 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";
    }
  }
});

HEAD request

As defined in HTTP, you may issue a HEAD request to read the response headers, but skip reading the entire response body. This request type must be supported by the server (but is by most).

GM_xmlhttpRequest({
  url: "http://www.example.com",
  method: "HEAD",
  onload: function(response) {
    GM_log(response.responseHeaders);
  }
});

Notes

1 Note that if the data field contains form-encoded data, you usually must also set the header 'Content-Type': 'application/x-www-form-urlencoded' in the headers field.

2 Some headers may not actually work through GM_xmlhttpRequest. For example, the Referer header cannot be overriden. [1] [2]