Intermediate

Ajax Operations

Sending Data

The simplest AJAX call can be performed as:

webix.ajax("some.php").then(function(data){
    console.log(data.json());
});

The above code makes an asynchronous GET request to the "some.php" script and logs the response data one it is available. You can also send GET or any type of request explicitly:

webix.ajax().get("some.php");
webix.ajax().post("some.php");

Webix is integrated with the Promiz.js library to ensure Promise-based cross-browser asynchronous requests.

Passing parameters

You can pass extra parameters:

  • by including them in the request string:
webix.ajax("some.php?action=info&id=123");
  • by a separate string as the second parameter of the get method:
webix.ajax().get("some.php", "action=info&id=123");
  • by using a separate JSON object. For GET request the parameters will be appended to the query string; for other requests they will be passed in the request body:
webix.ajax().get("some.php", { action:"info", id:123 });
 
// nested JSON object is possible
webix.ajax().post("some.php",{ action:"info", id:{ row:123, column:"title" }});

Parameters that are sent as a nested object are automatically converted to strings with the stringify method before they go to the server:

{
    "action":"info",
    "id":"{\"row\":123,\"column\":\"title\"}"
}

If there are Date objects within the parameters they are formatted with the parseFormatStr method.

{
    "action":"info",
    "date":"2018-05-27 11:15:00"
}

If you want to redefine the data serialization for all AJAX calls, you can do the following:

webix.ajax.prototype.stringify = function(obj){ 
    // or use some custom serializer here
    return JSON.stringify(obj);
}

By default, parameters in request body are passed to server as FormData. You can wrap them into FormData manually, which will prevent them from being serialized by the above pattern:

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

Request types

Get

This is the default request sent to Webix:

webix.ajax("some.php").then(function(data){
    //response text
    console.log(data.text());
});

Or, you can state it explicitly and make the request with get method:

webix.ajax().get("some.php").then(function(data){
    //response text
    console.log(data.text());
});

Post

You can also make POST requests with the post method that also returns a promise:

webix.ajax().post("some.php").then(function(data){
    //response text
    console.log(data.text());
});

To provide extra parameters for a request, add them as a separate string or an object like in the case of GET requests.

Put

To send a PUT Ajax request, use the put method:

webix.ajax().put("data.php", { id : "11" }).then(function(data){
    //response text
    console.log(data.text());
});

Delete

To send a DELETE request, use the del method:

webix.ajax().del("data.php", { id : "11" }).then(function(data){
    //response text
    console.log(data.text());
});

Patch

To send a PATCH Ajax request, use the patch method:

webix.ajax().patch("data.php", { id : "11" }).then(function(data){
    //response text
    console.log(data.text());
});

Sync mode

By default, all requests are performed in the asynchronous mode, and return a promise of the would-be data. The sync method forces any request to run in a synchronous way:

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

Such notation returns an XMLHttpRequest object instead of a promise, and you can parse xhr.responseText into a data component:

var xhr = webix.ajax().sync().get("data.php");
view.parse(xhr.responseText);

Incoming Data Parsing

Any asynchronous Ajax request performed by Webix returns a promise object that is resolved when server response arrives. See how it is implemented in Webix data loading pattern.

By using then() method, you can get to the response data. The promise is resolved with the data object that has a set of methods that should be called to receive server response:

  • text() for receiving the plain text response
  • json() for getting server response parsed from JSON data
  • xml() and rawxml() for getting server response parsed from XML data

Plain Response

You can get the response text with the text() method:

webix.ajax("some.php").then(function(data){
    data = data.text();
});

JSON response

You can get the JSON data with the json() method:

webix.ajax("some.php").then(function(data){
    data = data.json();
});

XML response

If the data source returns XML, you can get it with the data.xml() method:

webix.ajax("some.php").then(function(data){
    data = data.xml();
});

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

Other formats

If the data from the server comes in some other format, you can get the plain text response and use Webix DataDrivers to parse them into the component. For example, this is how you can parse the CSV data:

CSV

webix.ajax("some.php").then(function(data){
    var arr = webix.DataDriver.csv.getRecords(data.text());
    for (var i = 0; i < arr.length; i++){
        arr[i] = webix.DataDriver.csv.getDetails(arr[i]);
    }
    $$("pivot").parse(arr);
});

Related sample:  Webix Ajax for CSV

Similarly, you can parse JSArray, HTML, etc.

Getting Binary Data

Webix 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 "arraybuffer" with some restrictions.

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

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

Sending Several Requests

You can chain several requests to process them in a sequence:

webix.ajax("someA.php").then(function(dataA){
    return webix.ajax("someB.php",{ id:dataA.id });
}).then(function(dataB){
    return webix.ajax("someC.php",{ userdata:dataB.user })
}).then(function(dataC){
    $$("grid").parse(dataC.json());
});

Or you can send them in parallel and then process their results together with webix.promise.all:

var a = webix.ajax("someA.php");
var b = webix.ajax("someB.php");
var c = webix.ajax("someC.php");
 
webix.promise.all([a,b,c]).then(function(results){
    var a_result = results[0];
    var b_result = results[1];
    var c_result = results[2];
    // do something
    // ...
});

Error handling with Promise objects

Like with native promises, you can provide two handlers within the then() method:

var promise = webix.ajax("some.php");
promise.then(function(data){
    /* handle success */
}, function(err){
    /* handle error */
});

Or, handle the fail()/ catch() (Webix alias of fail()) method:

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

If you want to perform some actions after request either succeeded or failed, use finally():

promise.finally(){
    // some actions that happen regardless of the data arrival
}

Callback of webix.ajax()

If promises are not enough, for asynchronous AJAX calls you can also define a callback as the last parameter of the methods. It can be a single function or an object with error and success callbacks.

Callback Function

The callback function takes the following arguments:

  • text - full text of response;
  • data - response data;
  • XmlHttpRequest - loader object.

This is how you can add a callback to a request:

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

If you pass parameters to the server side script, the callback is the third parameter:

webix.ajax().get("some.php", { id:12 }, function(text, data, XmlHttpRequest){
    data = data.json();
    //..
});

Callback Object

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

webix.ajax("some.php",{
    error:function(text, data, XmlHttpRequest){
        console.log("error");
    },
    success:function(text, data, XmlHttpRequest){
        console.log("success");
    }
});

Extra headers

If the server side code requires some extra headers, you can send them as:

webix.ajax().headers({
    "Sent-by":"My Script" // any custom headers can be defined in such a way
}).get("./data.php");

You can use headers in combination with all the Ajax methods (e.g. get() and post()).

JSON sending

If you are working with a web service, you may need to send JSON content to the server side. It can be done as:

webix.ajax().headers({
    "Content-type":"application/json"
}).post("./data.php", JSON.stringify(payload));
Back to top