Dive Into Greasemonkey

Teaching an old web new tricks

Name

GM_xmlhttpRequest — make an arbitrary HTTP request

Synopsis

GM_xmlhttpRequest(details);
                     

                  

               

               
 
                  
                  
Description

                  
                  
GM_xmlhttpRequest makes an arbitrary HTTP request.  The details argument is an object that can contain up to seven fields.
                  

                  
                  

                     

                        
method

                        
a string, the HTTP method to use on this request.  Required.  Generally GET, but can be any HTTP verb, including POST, PUT, and DELETE.
                        

                        
url

                        
a string, the URL to use on this request.  Required.

                        
headers

                        
an associative array of HTTP headers to include on this request.  Optional, defaults to an empty array.  Example:
                           
headers: {'User-Agent': 'Mozilla/4.0 (compatible) Greasemonkey',
          'Accept': 'application/atom+xml,application/xml,text/xml'}

                        

                        
data

                        
a string, the body of the HTTP request.  Optional, defaults to an empty string.  If you are simulating posting a form (method == 'POST'), you must include a Content-type of 'application/x-www-form-urlencoded' in the headers field, and include the URL-encoded form data in the data field.
                        

                        
onload

                        
a function object, the callback function to be called when the request has finished successfully.

                        
onerror

                        
a function object, the callback function to be called if an error occurs while processing the request.

                        
onreadystatechange

                        
a function object, the callback function to be called repeatedly while the request is in progress.

                     

                  

                  
                  
                  
 
                     
                     
onload callback
                     

                     
                     
The callback function for onload takes a single parameter, responseDetails.
                     

                     
                     
function onloadCallback(responseDetails);
                        

                     

                     
                     
responseDetails is an object with five fields.
                     

                     
                     

                        

                           
status

                           
an integer, the HTTP status code of the response.  200 means the request completed normally.
                           

                           
statusText

                           
a string, the HTTP status text.  Status text is server-dependent.
                           

                           
responseHeaders

                           
a string, the HTTP headers included in the response.
                           

                           
responseText

                           
a string, the body of the response.

                           
readyState

                           
unused

                        

                     

                     
                  

                  
                  
                  
 
                     
                     
onerror callback
                     

                     
                     
The callback function for onerror takes a single parameter, responseDetails.
                     

                     
                     
function onerrorCallback(responseDetails);
                        

                     

                     
                     
responseDetails is an object with five fields.
                     

                     
                     

                        

                           
status

                           
an integer, the HTTP error code of the response.  404 means the page was not found.
                           

                           
statusText

                           
a string, the HTTP status text.  Status text is server-dependent.
                           

                           
responseHeaders

                           
a string, the HTTP headers included in the response.
                           

                           
responseText

                           
a string, the body of the response.  The body of an HTTP error page is server-dependent.
                           

                           
readyState

                           
unused

                        

                     

                     
                     
                  

                  
                  
                  
 
                     
                     
onreadystatechange callback
                     

                     
                     
The callback function for onreadystatechange is called repeatedly while the request is in progress.  It takes a single parameter, responseDetails.
                     

                     
                     

                           

                              function onreadystatechangeCallback(
                               
                              responseDetails);
                              
                           

                        

                     

                     
                     
responseDetails is an object with five fields.  The responseDetails.readyState denotes what stage the request is currently in.
                     

                     
                     

                        

                           
status

                           
an integer, the HTTP status code of the response.  This will be 0 when responseDetails.readyState < 4.
                           

                           
statusText

                           
a string, the HTTP status text.  This will be an empty string when responseDetails.readyState < 4.
                           

                           
responseHeaders

                           
a string, the HTTP headers included in the response.  This will be an empty string when responseDetails.readyState < 4.
                           

                           
responseText

                           
a string, the body of the response.  This will be an empty string when responseDetails.readyState < 4.
                           

                           
readyState

                           
an integer, the stage of the HTTP request.
                              

                                 

                                    
1

                                    
loading.  The request is being prepared.

                                    
2

                                    
loaded.  The request is ready to be sent to the server, but nothing has been sent yet.

                                    
3

                                    
interactive.  The request has been sent and the client is waiting for the server to finish sending data.

                                    
4

                                    
complete.  The request is completed and all response data is available in other fields.

                                 

                              

                           

                        

                     

                     
                  

                  
                  
               

               
 
                  
                  
Examples

                  
                  
The following code fetches the Atom feed from http://greaseblog.blogspot.com/ and displays an alert with the results.
                  

                  
                  
GM_xmlhttpRequest({
    method: 'GET',
    url: 'http://greaseblog.blogspot.com/atom.xml',
    headers: {
        'User-agent': 'Mozilla/4.0 (compatible) Greasemonkey',
        'Accept': 'application/atom+xml,application/xml,text/xml',
    },
    onload: function(responseDetails) {
        alert('Request for Atom feed returned ' + responseDetails.status +
              ' ' + responseDetails.statusText + '\n\n' +
              'Feed data:\n' + responseDetails.responseText);
    }
});

                  
               

               
 
                  
                  
Bugs

                  
                  
The onreadystatechange callback does not work properly with readyState < 4.
                  

                  
               

               
 
                  
                  
Notes

                  
                  
Unlike the XMLHttpRequest object, GM_xmlhttpRequest is not restricted to the current domain; it can GET or POST data from any URL.
                  

                  
               

               
 
                  
                  
History

                  
                  
GM_xmlhttpRequest was introduced in Greasemonkey 0.2.6.
                  

                  
                  

                        
Futher reading

                  

                  
               

            

            
← GM_registerMenuCommand

            
List of “further reading” links →
            

            

            

               
Copyright © 2005 Mark Pilgrim · mark@diveintomark.org · Terms of use