Revision as of 12:44, 6 December 2007

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:

http://www.w3.org/TR/XMLHttpRequest

[Examples][Notes]

Syntax

GM_xmlhttpRequest( details )

Compatibility: Greasemonkey 0.2.5+

Returns: Nothing

details Object
Properties	Event Handler Callbacks
`method`	`onload`
`url`	`onreadystatechange`
`headers`	`onerror`
`overrideMimeType`
`data`

All properties and event handler callbacks are optional except method and url.

Properties

`method`

Value: String

Usage: details.method = "GET"';

[top][back]

`url`

Value: String

Usage: details.url = "http://www.greasespot.net/"';

[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.

[top][back]

`overrideMimeType`

Value: String

Usage: details.overrideMimeType = "application/xhtml+xml";

[top][back]

`data`

Value: String

Usage: details.data = null;

[top][back]

Event Handler Callbacks

onload

Usage: details.onload = function (response) { // Some code };

Returns: Nothing

[top][back]

onreadystatechange

Usage: details.onreadystatechange = function (details) { // Some code };

Returns: Nothing

[top][back]

onerror

Usage: details.onerror = function (details) { // Some code };

Returns: Nothing

[top][back]

response Object
Properties	Event Handler Callbacks
`responseText`
`status`
`statusText`
`readyState`
`responseHeaders`

Properties

responseText

Value: String

Usage: alert(response.responseText);

[top][back]

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: Number

Usage: if (response.readyState == 4) { //Some code }

[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]

Examples

GM_xmlhttpRequest({
  method:"GET",
  url:"http://www.greasespot.net/",
  headers:{
    "User-Agent":"Mozilla/5.0",            // Recommend using navigator.userAgent when possible
    "Accept":"text/xml"
  },
  onload:function(response) {
    alert([
      response.status,
      response.statusText,
      response.readyState,
      response.responseHeaders,
      response.responseText
    ].join("\n"));
  }
});

[top]

Notes

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.

Some users have reported problems with international character sets. See these mailing list threads

The overrideMimeType parameter became available in version 0.6.8.

[top]

@@ Line 1: / Line 1: @@
 {{underscore|title=GM_xmlhttpRequest}}
+__NOTOC__
+= Description =
+This API method provides access to the chrome-privileged [http://developer.mozilla.org/en/docs/XMLHttpRequest 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:
+* [http://www.w3.org/TR/XMLHttpRequest/| http://www.w3.org/TR/XMLHttpRequest]
+[[#Examples|[Examples]]][[#Notes|[Notes]]]
 = Syntax =
@@ Line 5: / Line 16: @@
 '''GM_xmlhttpRequest(''' ''details'' ''')'''
-= Description =
+:Compatibility: Greasemonkey 0.2.5+
+:Returns: Nothing
+:{| border="1" cellpadding="5"
+|+ details Object
+!|'''Properties''' || !|'''Event Handler Callbacks'''
+|-
+| <code>[[#method |method]]</code> ||<code>[[#onload|onload]]</code>
+|-
+|<code>[[#url |url]]</code> ||<code>[[#onreadystatechange|onreadystatechange]]</code>
+|-
+|<code>[[#headers |headers]]</code> ||<code>[[#onerror|onerror]]</code>
+|-
+|<code>[[#overrideMimeType |overrideMimeType]]</code>
+|-
+|<code>[[#data |data]]</code>
+|}
+:* All properties and event handler callbacks are optional except method and url.
+=== Properties ===
+----
+==== <code>method</code> ====
+:Value: String
+:Usage: <code>details.'''method''' = "GET"';</code>
+[[#Description|[top]]][[#Syntax|[back]]]
+==== <code>url</code> ====
+:Value: String
+:Usage: <code>details.'''url''' = "<nowiki>http://www.greasespot.net/</nowiki>"';</code>
+[[#Description|[top]]][[#Syntax|[back]]]
+==== <code>headers</code> ====
+:Value: Object
+:Usage: <code>details.'''headers''' = {"User-Agent":"Mozilla/5.0"};</code>
+:The <code>headers</code> 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.
+[[#Description|[top]]][[#Syntax|[back]]]
+==== <code>overrideMimeType</code> ====
+:Value: String
+:Usage: <code>details.'''overrideMimeType''' = "application/xhtml+xml";</code>
+[[#Description|[top]]][[#Syntax|[back]]]
+==== <code>data</code> ====
+:Value: String
+:Usage: <code>details.'''data''' = null;</code>
+[[#Description|[top]]][[#Syntax|[back]]]
+=== Event Handler Callbacks ===
+----
+==== onload ====
+:Usage: <code>details.'''onload''' = function (''response'') { // ''Some code'' };</code>
+:Returns: Nothing
+[[#Description|[top]]][[#Syntax|[back]]]
+==== onreadystatechange ====
+:Usage: <code>details.'''onreadystatechange''' = function (details) { // ''Some code'' };</code>
+:Returns: Nothing
+[[#Description|[top]]][[#Syntax|[back]]]
+==== onerror ====
+:Usage: <code>details.'''onerror''' = function (details) { // ''Some code'' };</code>
+:Returns: Nothing
+[[#Description|[top]]][[#Syntax|[back]]]
+:{| border="1" cellpadding="5"
+|+ response Object
+!|'''Properties''' ||'''Event Handler Callbacks'''
+|-
+|<code>[[#responseText |responseText]]</code>
+|-
+|<code>[[#status |status]]</code>
+|-
+|<code>[[#statusText |statusText]]</code>
+|-
+|<code>[[#readyState |readyState]]</code>
+|-
+|<code>[[#responseHeaders |responseHeaders]]</code>
+|}
+==== Properties ====
+----
+===== responseText =====
+:Value: String
+:Usage: <code>alert(response.'''responseText''');</code>
+[[#Description|[top]]][[#Event_Handler_Callbacks|[back]]]
+===== status =====
+:Value: Number
+:Usage: <code>if (response.'''status''' == 200) { ''//Some code'' };</code>
+[[#Description|[top]]][[#Event_Handler_Callbacks|[back]]]
+===== statusText =====
+:Value: String
+:Usage: <code>if (response.'''statusText''' == "OK") { ''//Some code'' };</code>
+[[#Description|[top]]][[#Event_Handler_Callbacks|[back]]]
+===== readyState =====
+:Value: Number
+:Usage: <code>if (response.'''readyState''' == 4) { ''//Some code'' }</code>
+[[#Description|[top]]][[#Event_Handler_Callbacks|[back]]]
-This API provides access to the chrome-privileged [http://developer.mozilla.org/en/docs/XMLHttpRequest XMLHttpRequest] object.
+===== responseHeaders =====
-This means that it '''is''' possible to issue requests to domains other than that of the current page.
+:Value: String
+:Usage: <code>if (response.'''responseHeaders''') { ''//Some code'' };</code>
-The details parameter is an object having the following properties: method, url, headers, onload, onreadystatechange, onerror, data, overrideMimeType.
+:The <code>responseHeaders</code> is the string representation of response headers returned by <code>XMLHTTPRequest.getAllResponseHeaders()</code>.
-All fields are optional except method and url.
-The headers field is an object which should contain the name-value pairs of the headers to send, for instance {"User-Agent":"Mozilla"}.
-The onload, onreadystatechange, and onerror parameters are callback functions which are called when the corresponding events occur.
-Callback functions should accept a single object parameter having the following properties: responseText, status, statusText, readyState, and responseHeaders.
+[[#Description|[top]]][[#Event_Handler_Callbacks|[back]]]
-The responseHeaders is the string representation of response headers returned by <code>XMLHTTPRequest.getAllResponseHeaders()</code>.
 = Examples =
+<code>
   GM_xmlhttpRequest({
     method:"GET",
-    url:"<nowiki>http://youngpup.net/</nowiki>",
+    url:"<nowiki>http://www.greasespot.net/</nowiki>",
     headers:{
-      "User-Agent":"monkeyagent",        ''// Recommend using navigator.userAgent when possible''
+      "User-Agent":"Mozilla/5.0",            ''// Recommend using navigator.userAgent when possible''
-      "Accept":"text/monkey,text/xml"
+      "Accept":"text/xml"
     },
-    onload:function(details) {
+    onload:function(response) {
       alert([
-        details.status,
+        response.status,
-        details.statusText,
+        response.statusText,
-        details.readyState,
+        response.readyState,
-        details.responseHeaders,
+        response.responseHeaders,
-        details.responseText
+        response.responseText
       ].join("\n"));
     }
   });
+</code>
+[[#Description|[top]]]
 = Notes =
-Note that some attributes may not actually work through GM_xmlhttpRequest. The Referer header 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. References here:
+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.
 * http://groups.google.com/group/greasemonkey-dev/browse_thread/thread/77c94cc17c6b2669
 * http://userscripts.org/forums/1/topics/1302?page=1#posts-5312
@@ Line 51: / Line 174: @@
 The <code>overrideMimeType</code> parameter became available in [[Version history#0.6.8|version 0.6.8]].
+[[#Description|[top]]]
 [[Category:API Reference|X]]

GM.xmlHttpRequest: Difference between revisions

Revision as of 12:44, 6 December 2007

Description

Syntax

Properties

`method`

`url`

`headers`

`overrideMimeType`

`data`

Event Handler Callbacks

onload

onreadystatechange

onerror

Properties

responseText

status

statusText

readyState

responseHeaders

Examples

Notes

Navigation menu

Page actions

Page actions

Personal tools

Navigation

Search

Tools