Webix DataProcessor is a functional library that lets you to ‘communicate’ with server-side backend. It
Without DataProcessor, you need to attach corresponding functions to component events (onAfterInsert/Update/Delete) to get data ready for processing.
DataProcessor object can be inited in both long and short forms. Compulsory parameters include:
Other parameters (mode, validation rules, on, etc.) and optional and can be found here.
When you define url (path to the necessary script) as value of save property for the needed component (master) - DataProcessor is automatically inited:
webix.ui({
view:"datatable",
//..config..
url: "data.php", //script that links to DataConnector and loads data
save: "connector -> data.php" //the same script used for data processing
//or
url:"data_load.php", //your custom script for loading
save:"data_save.php" //you custom script for saving
});
A short form connects the previously created dataProcessor to the component, but if there isn't any, it creates the new dataProcessor.
Short Form (master, url)
webix.dp("mylist", "some_script.php");
With a long form you make use of the new constructor where you create an object through object literals.
Full Form
dp = new webix.DataProcessor({
url: "data.php",
master: $$('mylist'),
//optional properties
});
Related sample: Server-side Integration: List
A long initialization form allows for setting an ID for the dataprocessor. Otherwise, it is given an auto-generated one.
Dataprocessor features a set of methods and properties that can be used to change default processing pattern. To make use of them, you need to get to a dataprocessor object, which can be achieved with the help of Webix dp method:
var dp = webix.dp("mylist"); //returns dataprocessor object for "list" view
var dp = webix.dp.$$("mydp");
DataProcessor interpretes client-side operations performed on each data item and defines the type of data action for it:
The default processing looks as follows:
This data action together with data of edited/added/deleted record is sent to server script the moment any editing operation is performed. Data action is passed as:
view:"list",
save:"connector->myscript.php" //link to Server Side Connector
It looks like this:
id 7
title The Shaushenk Redemption
webix_operation delete
And other protocol with implicit Dataprocessor initing for connector-based scripts:
1_!nativeeditor_status update
1_birthday 1965-08-19
1_id 1
The moment Dataprocessor returns data, script execution begins (if other is not stated):
DnD operations and data item moving can be tracked by DataProcessor like any other CRUD operation provided that you switch on DataProcessor trackMove functionality.
new webix.DataProcessor({
master: tree,
url: "...",
trackMove:true
});
Related sample: Server-side Integration: Tree
DataProcessor events (listed in API reference) can be used for different purposes. For instance, the events can help you:
1) Modify data before it's gone to server with the onBeforeDataSend event that takes the whole dataobject as parameter:
dp.attachEvent('onBeforeDataSend', function(obj){
obj.data.StartDate = webix.i18n.dateFormatStr(obj.data.StartDate);
});
2) Track successfull and unsuccessful serverside responses separately with the help of onAfterSync and onAfterSaveError events respectively:
Successful server response
dp.attachEvent('onAfterSync, function(id, text, data){
var response = data.xml(),
hash = response.data;
//hash {type:'', tid: '', sid:''}
});
tid and sid will only be different in case on insert operation. In this case, DataProcessor automatically changes client-side ID to the ID that was generated for the item on server.
Unsuccessful server response
dp.attachEvent('onAfterSaveError', function(id, status, obj){
var operation = this.getItemState(id).operation; //operation that was performed
});
In case of an error during saving, response status will always be 'error' while type of operation is derived by getItemState method.
Getting to a master component from DataProcessor
Inside DataProcessor event handlers you can reach the master component througn DataProcessor configuration objetc:
dp.attachEvent('onSomeEvent', function(id, status, obj){
var grid = this.config.master; //this == DataProcessor
});
As it was stated earlier, the new ID from response of insert request will automatically replace the temporary client-side ID. This is part of default DataProcessor behavior, and no specific actions are required.
Additionally, yuo can enable automatic data update for all fields taking part in insert and update operations. It requires the following additions to the code:
Either during explicit DataProcessor definition
new webix.DataProcessor({
updateFromResponse:true,
master:"datatable1",
url:"..."
});
Or when defining DataProcessor implicitely
view:"datatable",
save:{
url:"...",
updateFromResponse:true
}
Related sample: Datatable: Saving
It can be uselful for REST-full applications or when you need to fill in client-side fields which values can be calculated only on server side, etc.
The event system for dataProcessor helps change the default processing logic right on client-side.
To alter processing, you should manually attach processing function to the necessary DataProcessor event (onBeforeDelete, onBeforeInsert, onBeforeUpdate). For instance, set update action type on onBeforeDelete thus making connector issue UPDATE request instead of DELETE.
This is how we change deletion from database by updating this record:
webix.ui({
view:"datatable",
id:"grid",
..// config options
url:"data/employee.php",
save:"connector->data/employee.php"
});
..//function redefining removal into updating
webix.dp($$("grid")).attachEvent("onbeforedelete", function(id, action){
action.operation = "update";
action.data.deleted = webix.i18n.parseFormatStr(new Date());
});
where..
Now, when a record is removed from the component, a field deleted of this record is updated in the database table. The current date is set into it to track the moment when the record was removed on the client side.
Learn more about the possibilities of data manipulation on clent side in related articles:
Cancelling DataProcessor
Not any client-side update is to be saved to server. To temporarily cancel DataProcessor you can:
webix.dp("grid").ignore(function(){
$$("grid).add(data);
});
dp.on();
$$("grid).add(data);
dp.off();
//initially during dp configuration
new webix.DataProcessor({
updateFromResponse:true,
master:"datatable1",
url:"...",
autoupdate:false
});
//dynamically
webix.dp($$("datatable1")).define("autoupdate", false);
Enabling Dataprocessor
The following concerns only disabled DataProcessor or the one with the changed behavior or if you need to emulate DataProcessor logic. In other cases DataProcessor performs the below described actions automatically.
To enable DataProcessor, and hence, trigger, sending its data to server, save method should be used with item ID and operation name as parameters:
webix.dp($$("datatable1")).save(1, 'update');
To get all changes in the component and send them to server, send method should be used:
webix.dp($$("datatable1")).send();
Data validation is enabled by including specific rules for input field. You can read about them here. With rules specified, the validation process starts each time you try to save data to the database.
dp = new webix.DataProcessor({
rules:{
$all:webix.rules.isNotEmpty
},
url: "save.php",
master: $$('mylist')
});
There exists no possibility to send headers with DataProcessor requests as they are executed in background. However, you can catch Webix onBeforeAjax request to mpdify ANY Ajax request issued from the page:
webix.callEvent("onBeforeAjax", function(mode, url, data, request){
request.setRequestHeader("Content-type","application/json");
});
Note that Webix Ajax module features a built-in functionality for sending headers with serverside requests. The above solution is only for DataProcessor Ajax requests.