cf2:ajax.Request

Purpose

Handles AJAX requests and responses.

Note:

At present AJAX supports only JSON structures, i.e. XDIME fragments cannot be sent using AJAX.

Exported Features

cf2:ajax.Request

Imported Features

n/a

JavaScript

The V$.ajax.Request class handles AJAX requests. It supports the following methods:

(url, options)

Initializes a request object.

Parameter Description Type
url The host or page relative URL. xs:string
options

The optional request options. Please note that, unless otherwise stated, the callback functions take two arguments, the request object and the response. The response encapsulates the result of the request.
Option Description Type Default
method The HTTP method to use. Must be one of the following: get, post, put, delete. String post
contentType The content type of the request body. String application/x-www-form-urlencoded
encoding The character encoding of the request body. String UTF-8
parameters Map of the parameters to send in either the query string, or the body depending on the method. The parameters are encoded using application/x-www-form-urlencoded. Map  
headers Map of the headers to send in the request. Map  
onSuccess A callback function to be executed when the request succeeds, i.e. a '2xx' status code is returned from the server. Function  
onException A callback function to be executed when an exception arises during processing of the request. In this case the first argument is the request object and the second argument is the exception, not the response. Function  
onFailure A callback function to be executed when the request fails, i.e. a non '2xx' status code is returned from the server. Function  
onComplete A callback function to be executed after all the other callbacks have been invoked. Function  
send()

Sends the request to the URL.

The V$.ajax.Response class provides the following methods:

status()

Returns the HTTP response status code.

contentType()

Returns the content type.

asText()

Returns the body of the response as text.

Coupling requests and responses

This component provides support for making asynchronous requests to a server. The main challenge with asynchronous requests is how to couple the response received in the callback with the original request, for example, if a request asks for the data to be used by a template, then the callback needs to know which template to update. There are two supported solutions to this problem:

The following example shows how to add the additional information to the request and use it with a callback function. There is a handler added to a button which, when activated, will cause a request to be sent to the server. The response will be used to update the data associated with the selected template. The button will be inactive until the server returns the response.

function onSuccess(request, response) {
  var t = request.cxTemplate;
  t.setData(response.asJSON());
}

function onComplete(request, response) {
  var b = request.cxButton;
  b.setEnabled(true);
}

V$C.linking(function(c) {

  // Resolve the reference to the template object.
  var template = c.get("template");

  // Resolve the reference to the button object.
  var button = c.get("button");

  // Create a response that will be used whenever
  // the button is pressed.
  var r = new V$.ajax.Request("list", {
    method: "get",
    onSuccess: onSuccess
  });
    
  // Store the reference to the button and the
  // template into the request.
  r.cxTemplate = template;
  r.cxButton = button;

  button.evtRegister(
    function(e) {
      // Disable the button.
      button.setEnabled(false);

      // Send the request.
      r.send();
    }
    "cf2:activate");
  }
}

XDIME example

<?xml version="1.0" encoding="UTF-8"?>
<html
  xmlns="http://www.w3.org/2002/06/xhtml2"
  xmlns:mcs="http://www.volantis.com/xmlns/2006/01/xdime/mcs"
  xmlns:cf2="http://www.volantis.com/xmlns/2009/07/cf2"  
  xmlns:event="http://www.w3.org/2001/xml-events"  
  xmlns:ui="http://www.volantis.com/xmlns/2009/07/cf2/ui"    
  xmlns:template="http://www.volantis.com/xmlns/marlin-template">
  <head>
    <title>Ajax with JSON response</title>
    <style type="text/css">
      ui|button {
        border: 1px solid red;
        color: white;
      }
    </style>
    <mcs:script src="/scripts/ajax-sample.mscr"/> 
    <mcs:script>
      function myOnSuccess(request, response) {
        var p = V$E('popup'); 
        var styles = response.asJSON();
        p.v_setStyles(styles);
      }
    </mcs:script>
  </head>
  <body>
    <div>    
      <ui:button>
        Click me
        <cf2:on event="cf2:activate">                  
          var r = new V$.ajax.Request("jsonResponse.xdime", {
            onSuccess: myOnSuccess
          }); 
          r.send();
        </cf2:on>
      </ui:button>
      <ui:box style="visibility: hidden; width: 300px;" id="popup">
        I am a box opened thanks to styles sent using ajax.
      </ui:box>
    </div>
  </body>
</html>

Where, jsonResponse.xdime contains the following code:

<json:response xmlns:json="http://www.volantis.com/xmlns/2009/07/json">
  <json:object>
    <json:property name="visibility">
      <json:string>visible</json:string>
    </json:property>
    <json:property name="border">
      <json:string>2px solid red </json:string>
    </json:property>
    <json:property name="color">
      <json:string>green</json:string>
    </json:property>
  </json:object>
</json:response>

Related topics