Martii / greasemonkey forked from greasemonkey/greasemonkey

Greasemonkey is a user script manager for Firefox.

Home | Edit | New

GM_xmlhttpRequest

Description

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

Syntax

GM_xmlhttpRequest( details )

Value: Function
Returns: undefined
Compatibility: Greasemonkey 0.5b+
details Object
Properties Event Handler Callbacks
method onload
url onreadystatechange
headers onerror
overrideMimeType
data
binary
All properties and event handler callbacks are optional except method and url.

top

Properties

method

Value: String
Usage: details.url = “GET”

top | back

url

Value: String
Usage: details.url = “http://www.example.com/”;
  • Must be an absolute URL.

top | back

headers

Value: Object
Usage: details.headers = { “User-Agent”:“Mozilla/5.0” };
  • The 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.[2]

top | back

overrideMimeType

Value: String
Usage: details.overrideMimeType = “text/html; charset=ISO-8859-1”;
Compatibility: Greasemonkey 0.6.8+
  • While each character set name may have multiple aliases defined, there may be a preferred name which can be found at IANA.

top | back

data

Value: String
Usage: details.data = null; /* some code */ if (details.data) { /* some code */ }
  • Note that if the data field contains form-encoded data, you must also set the header "Content-Type": "application/x-www-form-urlencoded" in the headers field.
  • [1]

top | back

binary

Value: Boolean
Compatibility: Greasemonkey 0.8.3+
Usage: details.binary = true;
  • Sends data as type binary in Firefox 3.x or above.

top | back

Event Handler Callbacks

onload

Usage: details.onload = function (response) { /* some code */ };
Returns: undefined, response Object

top | back

onreadystatechange

Usage: details.onreadystatechange = function (response) { /* some code */ };
Returns: undefined, response Object

top | back

onerror

Usage: details.onerror = function (response) { /* some code */ };
Returns: undefined, response Object

top | back

response Object
Properties
status readyState responseText finalUrl
statusText responseHeaders
  • Note: there is no 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 XMLDocument out of responseText using a DOMParser (see examples below).

top

Properties

status

Value: Number
Usage: if (response.status == 200) { /* some code */ }

top | back

statusText

Value: String
Usage: if (response.statusText == "OK) { /* some code */ }

top | back

readyState

Value:
Usage: if (response.readyState == 4) { /* some code */ }

top | back

responseText

Value: String
Usage: alert (response.responseText);

top | back

responseHeaders

Value: String
Usage: if (response.responseHeaders { /* some code */ }
  • The responseHeaders is the string representation of response headers returned by XMLHTTPRequest.getAllResponseHeaders().

top | back

finalUrl

Value: String
Compatibility: Greasemonkey 0.8.0+
Usage: if (response.finalUrl { /* some code */ }

top | back

Examples

GET Request | POST request | HEAD request

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"));
  }
});

top | back

POST request

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";
  }
});

top | back

HEAD request

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

top | back

See Also

top

Notes


1 Some 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.

2 Some 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.

top

Pages feed

Last edited by Martii, Thu Jan 28 12:50:01 -0800 2010
Home | Edit | New
Versions: