AJAX Requests

There are times when a page reload is just not good enough and AJAX requests are required to dynamically update a page. The following steps describe how a new AJAX request can be enabled for any component.

1. System Overview

All AJAX requests must be sent to the url /request/[v:class]/[v:method] where [v:class] is the name of a PHP class and [v:method] the name of a method of the class. The class and the method must be defined in the folder server/ajax/.

The folder server/ajax/ already contains several files holding class definitions and methods which are used as AJAX request callbacks and can serve as examples. Note that the following two files are special utility files and should not be extended lightly:

• server/ajax/BaseAjax.php: A base class which provides easy access to services and ACL control. When creating a new AJAX request class use this as parent.
• server/ajax/AjaxRequest: A wrapper class which will
  • load the correct php file
  • instantiate the class indicated with the request url
  • execute the callback method by passing POST parameters
  • evaluate ACL as defined in the class BaseAjax
  • encode the return value of the callback function as JSON

2. Create the Request Callback

To create a new request callback, either create a new method in an existing class or create a new class. Note that if a new class is created it must be placed in a new file and the file name must match the class name exactly and requires the .php file extension.

The callback method receives the php $_POST variable as parameter. Hence, all request data needs to be sent via POST to the server and cannot be attached as GET variables. The callback function must reurtn a result which can be encoded as JSON string.

The reply data will be of the form

{
  "success": <boolean>
  "data": <payload>
}

On success, the key success will hold the value true and on failure the value false. Further, on success the key payload will hold the return value of the callback function and on failure an error message.

3. AJAX Call from Javascript

To perform an AJAX call from Javascript there are several ways to do this. Given that jQuery is available I would suggest to use the post method:

$.post(
  BASE_PATH + '/request/__class_name__/__method_name__',
  {
    // your post data
  },
  function(data) {
    if(data.success) {
      // do your magic
    } else {
      console.log(data)
    }
  },
  'json'
}

where __class_name__ is the class to be instantiated and __method_name__ is the name of the callback method.

4. Enable AJAX Call

In order to grant the proper access rights, all AJAX calls have to be enabled in the component which uses them. This will allow to perform ACL checks based on the parent page ID which holds the component performing AJAX requests.

To enable an AJAX request add the following line to the constructor of the (style-)component:

$this->set_request_access($id_page, "__class_name__", "__method_name__");

where __class_name__ is the class to be instantiated and __method_name__ is the name of the callback method.