loadURL() Sample

This page gives a few examples of how to use the Spry.Utils.loadURL() to send "GET" and "POST" requests to the server. The Spry.Utils.loadURL() function is currently located in SpryData.js, so before you use it, you must include it:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>

...

<script src="../../includes/SpryData.js" type="text/javascript"></script>

...

</head>

Before proceeding any further, let's take a look at the arguments for the loadURL function:

var req = Spry.Utils.loadURL = function(method, url, async, callback, opts);

The arguments are as follows:

method
- String.
- Must be "GET", "POST" or "HEAD".
url
- String.
- An absolute URL to the data *or* a URL that is relative to the HTML document that is running your script. Note that the URL *MUST* refer to a document/server-side script that is on the same server from which the HTML document originated from. If it isn't, the request will fail.
async
- Boolean.
- If true, the request will be processed asynchronously, which means that the request will be made, but the response may come back some time *after* the call to loadURL() has finished. If false, the request will block until a response has been received from the server, or the request has timed out.
callback
- Function reference. This argument is optional.
- If specified, this callback function will be triggered after a response from the server has been received.
- The signature of the callback is as follows:
```
function MyCallback(req)
{
  // Do your processing here.
}
```
  When the callback is triggered, the Spry.Utils.loadURL.Request object is passed to the callback. See below for more details.
opts
- Object. This argument is optional.
- Specifies any request options. Valid options are:
  - errorCallback
    - Function Reference.
    - This callback will be triggered if the request fails. The signature of the callback is identical to the callback function argument of loadURL, mentioned above.
  - headers
    - Object.
    - Specifies additional HTTP Request header fields that should be sent along with the request. Each property in this object is the name of an HTTP header field to send. The value of the property, is the value of that field. Example:
```
// Example of creating a header object the literal way:

var header = { "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8" };

// Example of creating a header object manually:

var header = new Object;
header["Content-Type"] = "application/x-www-form-urlencoded; charset=UTF-8";
```
  - password
    - String.
    - The password to send to the server along with the request.
  - postData
    - String.
    - The format of the data in the string is up to the developer so this must be used in conjunction with the "headers" option, mentioned above, to specify the "Content-type" so the server knows how to deal with it.
  - userData
    - User Defined
    - This can be anything the developer wants it to be. This option is here so that a developer can attach some data to a request, and have that data passed along with the request to the loadURL callback or errorCallback functions.
  - username
    - String.
    - The username to send to the server along with the request.

The return value of loadURL is an object of type Spry.Utils.loadURL.Request. This is the same object that will be past into any callbacks you've passed into loadURL. The fields in this object look just like options you pass into loadURL, but it also contains fields that contain the arguments passed into the loadURL call.

Here's a list of the properties on the Request object.

async
- Boolean.
- The value of the async argument that was passed into loadURL.
method
- String.
- The value of the method argument that was passed into loadURL.
password
- String.
- The password sent to the server. This could be null if none was specified.
postData
- String.
- The post data that was sent with the loadURL request. This could be null if no postData was specified.
successCallback
- Function reference.
- The value of the callback argument that was passed into loadURL. This could be null if a callback was not specified.
url
- String.
- The URL passed into the loadURL call.
userData
- User Defined
- The userData that was passed into loadURL via the 'userData' option.
username
- String.
- The username sent to the server. This could be null if none was specified.
xhRequest
- Object.
- The Browser native XMLHttpRequest object.

Now that we know all about loadURL, lets take a look at a few sample calls.

Example: Simple "GET" request with no callback.

In this example we just want to do an asynchronous "GET" request, but we don't care about the results, so we don't register a callback.

var req = Spry.Utils.loadURL("GET", "/app/book.php?id=1&code=54321", true);

Example: "GET" request with callback.

In this example, we want to show an alert if the request completes successfully.

function MySuccessCallback(req)
{
  alert(req.url + " completed successfully!");
}

...

var req = Spry.Utils.loadURL("GET", "/app/book.php?id=1&code=54321", true, MySuccessCallback);

Example: "GET" request with user-defined data passed to the callback function.

function MySuccessCallback(req)
{
  // Throw an alert with the message that was
  // passed to us via the userData.

  alert("SUCCESS: " + req.userData.msg);
}

...

// Create some data to be sent along with the request.
// This really can be anything you want, but I'm going to
// use an object.

var myObj = new Object;
myObj.msg = "Hello World";

var req = Spry.Utils.loadURL("GET", "/app/book.php?id=1&code=54321", true, MySuccessCallback, { userData: myObj });

Example: "POST" request with no callback.

var req = Spry.Utils.loadURL("POST", "/app/book.php?id=1&code=54321", true, null, { postData: "action=update&genre=fiction", headers: { "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8" } });

Example: "POST" request with user-defined data passed to the callback and errorCallback functions.

function MySuccessCallback(req)
{
  // Throw an alert with the message that was
  // passed to us via the userData.

  alert("SUCCESS: " + req.userData.msg);
}

function MyErrorCallback(req)
{
  // Throw an alert with the message that was
  // passed to us via the userData.

  alert("ERROR: " + req.userData.msg);
}

...

// Create some data to be sent along with the request.
// This really can be anything you want, but I'm going to
// use an object.

var myObj = new Object;
myObj.msg = "Hello World";


var req = Spry.Utils.loadURL("POST", "/app/book.php?id=1&code=54321", true, MySuccessCallback, { postData: "action=update&genre=fiction", headers: { "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8" }, errorCallback: MyErrorCallback });