Foundations.Comms.AjaxCall

Wrappers for async Ajax calls and a Palm bus service call. All calls are made asynchronously and are implemented using 'Futures', Palm's mechanism for async calls. See the Futures documentation for more information. The examples provided with each call demonstrate how Futures are used.

Ajax Options

The Ajax calls detailed below can each take the following options object:

{
  "bodyEncoding"    : string,
  "customRequest"   : string,
  "headers"         : any object,
  "joinableHeaders" : string array,
  "nocompression"   : boolean   // not currently supported; "true" by default
}

Element Required Type Description
bodyEncoding No string Encoding of the body data. Can be either 'ascii' or 'utf8'; 'utf8' is the default.
customRequest No string Used to specify a custom request method such as "PROPFIND", instead of the usual "GET" or "POST".
headers No object array Array of headers to send in an Ajax POST request.
joinableHeaders No string array

Set of response headers joined as a comma-delimited list when more than one instance is received from a server, per RFC 2616 (Hypertext Transfer Protocol -- HTTP/1.1), section 4.2.

Example:
options = { "joinableHeaders": ['Set-Cookies']};
 
When received as:
    "Set-Cookies: YT-1300"
    "Set-Cookies: T-16"
will be packaged as:
    "Set-Cookies": "YT-1300, T-16"
noncompression No boolean If 'true', accepted response encodings do not include compressed formats. Compression is useful if a large amount of data is sent in the response.

AjaxCall.get

Syntax

    Future AjaxCall.get(url, options);

Parameters

Argument Required Type Description
url Yes string URL
options No object See details in Communication Utilities overview.

Returns

Text from server.

Example

var libraries = MojoLoader.require({ name: "foundations", version: "1.0" });
var Future = libraries["foundations"].Control.Future;
var AjaxCall = libraries["foundations"].Comms.AjaxCall;

var options = { "bodyEncoding":"utf8"};
var future1 = AjaxCall.get("http://www.w3schools.com/ajax/ajax_info.txt", options);
future1.then(function(future)
{
  if (future.result.status == 200) // 200 = Success
      Mojo.Log.info('Ajax get success ' + JSON.stringify(future.result));
  else Mojo.Log.info('Ajax get fail');
});

Example Output

Ajax get success 
{
  "readyState":4,
  "responseText":"<p>AJAX is not a new programming language.</p>\r\n<p>AJAX is a technique for creating fast and dynamic web pages.</p>",
  "onloadstart":null,
  "onerror":null,
  "onabort":null,
  "withCredentials":false,
  "status":200,
  "responseXML":null,
  "onload":null,
  "onprogress":null,
  "upload":{
      "onloadstart":null,
      "onabort":null,
      "onerror":null,
      "onload":null,
      "onprogress":null
  },
  "statusText":"",
  "_complete":true
}


AjaxCall.head

Returns only the meta-information contained in the HTTP headers.

Syntax

    Future AjaxCall.head(url, options);

Parameters

Argument Required Type Description
url Yes string URL
options No object See details in Communication Utilities overview

Returns

Response object from server.

Example

var libraries = MojoLoader.require({ name: "foundations", version: "1.0" });
var Future      = libraries["foundations"].Control.Future;
var AjaxCall = libraries["foundations"].Comms.AjaxCall;

var options = { "bodyEncoding":"utf8"};
var future1 = AjaxCall.head("http://www.w3schools.com/ajax/ajax_info.txt", options);
future1.then(function(future)
{
  if (future.result.status == 200)  // 200 = Success
      Mojo.Log.info('Ajax head success ' + JSON.stringify(future.result));
  else Mojo.Log.info('Ajax head fail');
});

Example Output

Ajax head success 
{
  "readyState":4,
  "responseText":"",
  "onloadstart":null,
  "onerror":null,
  "onabort":null,
  "withCredentials":false,
  "status":200,
  "responseXML":null,
  "onload":null,
  "onprogress":null,
  "upload":{
      "onloadstart":null,
      "onabort":null,
      "onerror":null,
      "onload":null,
  "onprogress":null
  },
  "statusText":"",
  "_complete":true
}


AjaxCall.post

A post request is different from a get request in the following ways:

Syntax

    Future AjaxCall.post(url, body, options);

Parameters

Argument Required Type Description
url Yes string URL
body Yes any Additional data, i.e., form data.
options No object See details in Communication Utilities overview

Returns

Response object from server.

Example

var libraries   = MojoLoader.require({ name: "foundations", version: "1.0" });
var AjaxCall    = libraries["foundations"].Comms.AjaxCall;
var Future      = libraries["foundations"].Control.Future;

var options = { "bodyEncoding":"utf8", "headers": [{"Content-type":"application/x-www-form-urlencoded"}]};
var url = "http://www.javascriptkit.com/dhtmltutors/basicform.php?name=HuggyBear&age=25";
var body = "";
var future1 = AjaxCall.post(url, body, options);
future1.then(function(future)
{
  if (future.result.status == 200) // Success
  Mojo.Log.info('Ajax post success ' + JSON.stringify(future.result));
  else Mojo.Log.info('Ajax post fail ='+ JSON.stringify(future.result));
});

Example Output

Ajax post success 
{
  "readyState":4,
  "responseText":"<span style='color:red'>Welcome <b>HuggyBear</b> to JavaScript Kit.
      So you're <b>25</b> years old eh?</span>",
  "onloadstart":null,
  "onerror":null,
  "onabort":null,
  "withCredentials":false,
  "status":200,
  "responseXML":null,
  "onload":null,
  "onprogress":null,
  "upload":{
      "onloadstart":null,
      "onabort":null,
      "onerror":null,
      "onload":null,
      "onprogress":null
  },
  "statusText":"",
  "_complete":true
}