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:

A block of data is sent with the request in the message body. There are usually extra headers to describe this message body, like "Content-Type:" and "Content-Length:".
The request URI is not a resource to retrieve but, instead, a program to handle the data you are sending.
The HTTP response is normally program output, not a static file.

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
}