Ajax API (ai.ajax)

Enable in conf/config.xml:

<config>
  <js-api>
    <ajax />
  </js-api>
</config>

API

Request

ai.ajax.request(url, callback, args)

Request resources via ajax over the fit server. This function accepts the following parameters:

  • @param {String} url URL for the URL to load, by default is processed via ai.urls.composeUrl (see perfectUrl setting below to prevent this)
  • @param {Function} callback function to call with the result of the ajax request
  • @param {Object} args parameters for the request, see request arguments

Request Arguments

The request can be called with several optional arguments. These Arguments are passed as attributes of an object:

{
    method: {String}
  , data: {Object[]}
  , timeout: {Number}
  , headers: {Object[]}
  , callbackData: {Mixed}
  , marks: {Object[]}
  , perfectUrl: {Boolean}
  , abortCallback: {Function}
  , timeoutCallback: {Function}
  , errorCallback: {Function}
  , allowUCM: {Boolean}
  , async: {Boolean}
}

Parameters

  • method: {String} method to use (‘GET’ or ‘POST’)
  • data: {Object[]} form data to send with the request. This is in the form of an array of objects with these members:

    • name: {String} name of the parameter to send.
    • value: {String} value of the parameter.
    • dontEncode: {Boolean} (optional) name and value of the parameter are by default encoded with encodeURIComponent. If dontencode is set to true, the values are send as is.
  • timeout: {Number} time in seconds without response until the requests is aborted

  • headers: {Object[]} additional headers to send with the ajax request, in the following form: [{name: 'X-Foo', value: 'bar'}]
    • X-Requested-With: XMLHttpRequest will be added by FIT and should not be added again.
  • callbackData: {Mixed} data that is passed to the callback function
  • marks: {Object[]} URL Marks to be sent with the request, in the following form: [{name: 'foo', value: 'bar'}]
  • perfectUrl: {Boolean} if true, the URL is not be processed by ai.urls.composeUrl (is ignored if marks are set)
  • abortCallback: {Function} function that is called if the request is aborted
  • timeoutCallback: {Function} function that is called if the request times out
  • errorCallback: {Function} function that is called if an error occurs during the request
  • allowUCM: {Boolean} if true the url provided will be enriched with the ucm mark (advanced-cache-control)
  • async: {Boolean} if true the request is sent asynchronously (default)

Callback Functions

The callback function for the request response:

callback(responseData, callbackData) {}

Parameters

  • @param responseData {Object} the response of the request, see below for details
  • @param callbackData {Mixed} data that can be passed by the user

Error callbacks

errorCallback(eventData, callbackData) {}

timeoutCallback(eventData, callbackData) {}

abortCallback(eventData, callbackData) {}

errorCallback The errorCallback is called whenever any error occurs during an ajax request.

timeoutCallback The timeoutCallback is called whenever a timeout occurs.

abortCallback The abortCallback is called whenever a request is aborted.

Parameters

All error callback functions are called with the following parameters:

  • @param eventData {Object} the data of the event, see below for details
  • @param callbackData {Mixed} data that can be passed by the user

Response Data

The response callback function is called with the following object.

{
    responseText: {String}
  , responseXML: {Document}
  , status: {Number}
  , contentType: {String}
  , effectiveUrl: {String}
  , pplf: {boolean}
  , dontPushState: {boolean}
}

Parameters

  • responseText: {String} text value of the ajax response
  • responseXML: {Document} parsed response or null
  • status: {Number} status code of response
  • contentType: {String} content type of response
  • effectiveUrl: {String} (optional) the response of an ajax request may come from a different URL than the requested, if a redirect occurs. In this case the effectiveUrl parameter is provided in the responseData Object to notify the client of the actual origin URL.
  • pplf: {boolean} (optional) the response contains only fragments’ content (Partial Page Loading with fragments).
  • dontPushState: {boolean} (optional) the response contains a redirect script and must not be pushed into the browser history.

Events

Every Ajax request fires events that can be listened to via the JavaScriptEvents API

Events

  • xhrstart - start of the request
  • xhrend - successful completion of request
  • xhrerror - one of the following errors occurred
  • xhrtimeout - the request between client and fit server timed out
  • xhrnetworkerror - no network connection
  • xhrabort - the request was aborted
  • xhrbadhttpstatus - fired if response has a http status code other than 200

Event Data

Every event gets an object with data concerning the event.

{
    request: {
      href: {String}
    , urlFragment: {String}
    , method: {String}
    , formData: {String}
    , headers: {Object[]}
    , timeout: {Number}
    , triggerAbortOnTimeout: {Boolean}
    , triggerNetworkOnTimeout {Boolean}
  }
  , response: {
    , contentType: {String}
    , status: {Number}
    , xml: {Document}
    , text: {String}
  }
  , xhr: {XMLHttpRequest}
  , xhrProgress: {Event}
  , error: {String}
  , preventDefault: {Function} 
}

Parameters

  • request: {Object} an object containing information concerning the request, with the following attributes:
    • href: {String} URL of the requested resource.
      • urlFragment: {String} The fragment of the URL that was passed to be requested. Usually contains the ID of an anchor that will be scrolled to.
      • method: {String} method that will be used for the request as string. Can be ‘GET’ or ‘POST’
      • formData: {String} Array of key-value pairs. For example [‘a=b’, ‘c=d’]. Will be transformed to form data and passed with the request.
    • headers: {Object[]} Array of http headers that will be added to the request. Takes objects with the structure {name: 'headername', value: 'headervalue'}. For example [{name:'X-Foo', value: 'bar'}].
    • timeout: {Number} Duration in milliseconds until FIT will abort the request in the client. This has nothing to do with a network timeout. If set to false FIT will not abort the request.
    • triggerAbortOnTimeout: {Boolean} In case FIT aborts the request in the client due to the timeout settings it will suppress the xhrabort event from triggering. If this is set to true, it will trigger the xhrabort, unless you prevent the default of the xhrtimeout error.
    • triggerNetworkOnTimeout {Boolean} In case a timeout error is thrown a network error will be suppressed, unless this is set to true.
  • response: {Object} an object containing information concerning the response, with the following attributes:
    • contentType: {String} The content type the response was sent with. For example: 'text/xml; charset=UTF-8'
    • status: {Number} Integer representing the http status code
    • xml: {Document} the responseXML property as passed by the XMLHttpRequest
    • text: {String} the responseText property as passed by the XMLHttpRequest
  • xhr: {XMLHttpRequest} the XMLHttpRequest Object
  • xhrProgress: {Event} the XMLHttpRequest progress event object. This is a {ProgressEvent} after an error.
  • error: {String} the error type as string. null if no error occurred. Can be one of null, 'timeout', 'clienttimeout', 'network', 'aborted', 'badHttpStatus'
  • preventDefault: {Function} Function that prevents the default for the event. Currently only has effect for the xhrtimeout error, which by default aborts an XHR.