Ajax

This section is dedicated to the Ajax helper and describes the operations which can be performed with the help of Ajax.

• dhtmlxAjax API

• Migration to v4.1

Sending Data

The simplest Ajax call can be performed as:

dhx.ajax("some.php", function(text){
    dhx.message(text); // show server-side response
});

The above code makes an asynchronous GET request to the "some.php" script and shows its response through a callback function.

Passing parameters

You can pass extra parameters:

• by including them in the request string:

dhx.ajax("some.php?action=info&id=123");

• by a separate string with parameters:

dhx.ajax.get("some.php", "action=info&id=123");

• by using a separate JSON object:

dhx.ajax.get("some.php",{ action:"info", id:123 });

In case of object notation, the library will escape values automatically except for the case with FormData.

• by using FormData:

var formData = new FormData();
 
formData.append("action", "info");
formData.append("id", "123");
 
dhx.ajax.post("some.php", formData);

Post mode

The same function can be used to make POST requests:

dhx.ajax.post("some.php");

Here you can use two methods to provide extra parameters:

//$_POST["action"]="info", $_POST["id"]="123"
dhx.ajax.post("some.php","action=info&id=123");
dhx.ajax.post("some.php", { action:"info", id:123});

Sync mode

There are two ways that Ajax can access the server:

• synchronous (before continuing, script waits for the server to reply back).
• asynchronous (script continues page processing and handles the reply as it comes).

By default, all requests are performed in the asynchronous mode, but there is a synchronous alternative:

dhx.ajax.sync().get("some.php");
dhx.ajax.sync().post("some.php");

Callback

For asynchronous Ajax calls you can define a callback function as the last parameter of the method. For GET and POST requests the syntax is the same.

The callback function takes the following arguments:

• text - full text of response;
• data - response data that should be parsed as JSON or XML, whichever is applicable. It features the following methods to get the data:
  • json() - parses data as JSON;
  • xml() - parses data as XML;
  • rawxml() - gets raw XML data;
  • text() - gets response text;
• XmlHttpRequest - loader object.

GET requests:

dhx.ajax("some.php", function(text, data, XmlHttpRequest){
    data = data.json();
    //..
}); 
 
dhx.ajax.get("some.php", function(text, data, XmlHttpRequest){
    //...
});

POST request:

dhx.ajax.post("some.php", function(text, data, XmlHttpRequest){
    //...
});

If you pass parameters to the server side script, the syntax is as follows:

dhx.ajax.get(url, params, callback);
dhx.ajax.post(url, params, callback);

It's possible to define two callback methods, one for valid server side response and the second one for the error response:

dhx.ajax("some.php",{
    error:function(text, data, XmlHttpRequest){
        alert("error");
    },
    success:function(text, data, XmlHttpRequest){
        alert("success");
    }
});

If you need to trigger multiple callbacks after the method's execution is finished, you can define an array of callbacks as the last parameter:

//GET requests
dhx.ajax.get(url, [array of callbacks]);
dhx.ajax.get(url, params, [array of callbacks]);
 
//POST requests
dhx.ajax.post(url, [array of callbacks]);
dhx.ajax.post(url, params, [array of callbacks]);

In some cases you may need to provide some extra data for callback, which can be done in the next way:

function after_call(text){
    alert("Call: "+this.data+", response: "+text);
};
dhx.ajax.get("some.php", after_call, { data:"my ajax"});

Basically, the parameter after callback will be accessible as "this" in the callback method.

For sync requests, there is no callback, because there is no need for waiting:

var xhr = dhx.ajax.sync().get("some.php");
var text = xhr.responseText;

Extra headers

If the server side code requires some extra headers, you can send them using the headers param of the dhx.ajax.query method, as in:

dhx.ajax.query({
    method:"POST",
    url:"some.php",
    data:"k1=v1&k2=v2",
    async:true,
    callback:function(){},
    headers:{
        "Sent-by":"My Script" // any custom headers can be defined in such a way        
    }
});

Incoming Data Parsing

Plain response

In general case you can use the text parameter of the callback to access the data:

dhx.ajax("./data.php", function(text){
    dhx.message(text);
})

JSON response

While you can use the above code to access raw text response, there is a more neat solution:

dhx.ajax("some.php", function(text, data){
    //text = '{ some :"abc"}'
    alert(data.json().some); //abc
});

the second parameter of response can provide you with a ready-to-use JSON object.

XML response

The same as it was described above, you can use:

dhx.ajax("some.php", function(text, data){
    //text = '<data some='abc'></data>'
    alert(data.xml().some); //abc
});

If necessary, you can access raw XML object by using data.rawxml().

Other formats

CSV

dhx.ajax("some.php", function(text, xml){
    var obj = dhx.DataDriver.csv.toObject(text,xml);
    alert(obj[0][0]); //row and column indexes
});

JSArray

dhx.ajax("some.php", function(text, xml){
    var obj = dhx.DataDriver.jsarray.toObject(text,xml);
    alert(obj[0][0]); //row and column indexes
});

HTML

dhx.ajax("some.php", function(text,xml){
    //text = '<ul><li some='abc'></ul>'
    var obj = dhx.DataDriver.html.toObject(text,xml);
    alert(obj[0].some); //abc
});

Extra parameters

If all above is not enough, you can access raw xmlHttpRequest and poll it for additional data:

dhx.ajax("some.php", function(text,xml, ajax){
    alert(ajax.status);
});

Getting Binary Data

DHTMLX Ajax class offers a pattern for retrieving binary data objects from the server.

It can be done with the dedicated response() method that allows setting responseType directly. Now only "blob" type is fully supported and "document" with some restrictions.

dhx.ajax.response("blob").get("patch.zip", function(text, data){
  //data - is a data blob
});

Functionality will not work in IE8-IE9 as these browsers cannot work with blob objects at all.

Promise API for Ajax requests

DHTMLX is integrated with the Promiz.js library, which allows treating the result of asynchronous operations without callbacks.

In other words, any Ajax request performed by DHTMLX returns a promise object that represents the eventual result of this request. It can be treated by the then() method that is automatically executed when server response arrives.

//"promise" object is returned by either of these methods
var promise = dhx.ajax("some.php");
var promise = dhx.ajax.get("some.php");
var promise = dhx.ajax.post("some.php");
 
//realdata - data that came from server
promise.then(function(realdata){
    ...
});

Forming a chain of requests with Promises

dhx.ajax("someA.php").then(function(realdataA){
    return dhx.ajax("someB.php");
}).then(function(realdataB){
    return dhx.ajax("someC.php")
}).then(function(realdataC){
    ...
});

Error handling with Promise objects

then() method can be used to treat errors:

var promise = dhx.ajax("some.php")
promise.then(function success(realdata){}, function error(err){});

Additionally, the fail() method can be used for error handling:

var promise = dhx.ajax("a.php");
...
promise.then(function(realdata){ /*success*/});
promise.fail(function(err){/*error*/});

Or, you can do it in one and the same function:

promise.then(function(realdata){
    //success
}).fail(function(err){
    //error
});

All the methods of the promise object come from the Promiz.js library and can be found there.

dhx.promise interface

DHTMLX offers an interface for working with promise objects - dhx.promise - featuring a set of methods that duplicate Promise object methods.

dhx.promise constructor

var my_promise = new dhx.promise(function(success, fail){
    dhx.ajax("some.php", function(text){
        if (text) success(text);
        else fail(text.error)
    });
});
 
//realdata - data that came from server
my_promise.then(function(realdata){
    ...
});

dhx.promise can be used, for instance, in the following cases:

• Resolve all promises in the resulting array

You can treat several Ajax requests and perform some action when callbacks are received from all of them using the all() method:

first = dhx.ajax("someA.php");
second = dhx.ajax("someB.php");
third = dhx.ajax("someC.php");
 
 
dhx.promise.all([first,second,third]).then(function(results){
    var first_result = results[0];
    var second_result = results[1];
    var third_result = results[2];
    // do something
    ...
});

• Create a new instance of a deferred object

For this, you need to use the defer() method:

var deferred_promise = dhx.promise.defer();
 
dhx.ajax("some.php", function(text){
    if (text) deferred_promise.resolve(text);
    else deferred_promise.reject(text.error)
});
 
deferred_promise.then(function(realdata){...});

Back to top