Configuring DataProcessor

Here we collect all the information concerning dataProcessor configuration:

Meaningful Names

The parameters c0-cN used by default aren't very useful on the server side. The dataprocessor allows using the grid columns' IDs instead of these params.

For this purpose use the enableDataNames method:

grid.setHeader("Name of the book,Name of the author")
grid.setColumnIds("book,author");
...
dp.enableDataNames(true);
 
// on the server side you'll get:
// $_GET['c0']     =>     $_GET['book']\\
// $_GET['c1']     =>     $_GET['author']

Related sample:  Meaningful names

Sending Modes

There are different ways of sending data to dataProcessor. You can set the desired mode using the setTransactionMode method. The following transaction modes are available: "POST", "GET", "REST", "JSON".

POST or GET

dataProcessor uses the GET command by default. But if you have dhtmlxConnector included on the page, dataProcessor will send parameters through the POST command. To set the GET of POST transaction mode, use the setTransactionMode method:

dp.setTransactionMode("POST");

Related sample:   Sending all at once

Sending all at once

The update for each row is sent as a separate request by default, i.e. when 20 rows are updated - 20 requests are sent to the server. This is not a good approach and instead of it, a single (more complex) request can be sent to the server side:

dp.setTransactionMode("POST",true);

Related sample:   Sending all at once

In this case the server side receives a slightly different set of parameters:

  • ids - a comma-separated list of the updated rows' IDs. For each ID in this list, the request will contain a set of details.

For example, if we have two updated rows on the client side with IDs = r2 and r3, the server-side code will receive the following: ids = r2,r3

  • r2_!nativeeditor_status - the status of an operation for the row r2
  • r2_c0 .. r2_cN - the data for a column of the row r2
  • r3_!nativeeditor_status - the status of an operation for the row r3
  • r3_c0 .. r3_cN - the data for a column of the row r3

The awaited server-side response must be presented in the same format as a usual one, but it must include the data for all the processed rows:

<data>
   <action type="some" sid="r2" tid="r2" />
   <action type="some" sid="r3" tid="r3" />
</data>

It's not recommended to set this mode if you use dhtmlxConnector. dhtmlxConnector requires using POST and sending all data at once (set by default): dp.setTransactionMode("POST",true).

REST

This mode allows using dataProcessor with the REST API.

To enable this mode, pass the "REST" parameter to the setTransactionMode method:

dp.setTransactionMode("REST");

After that all requests to the server will be processed according to the rules of the REST protocol.

Request

Thus, you can set the columns' ids and then apply them as follows:

grid.setHeader("Name of the book,Name of the author")
grid.setColumnIds("Book,Author");
...
dp.enableDataNames(true);

and your request will look like this:

URL: /api
POST:
Form data:
Book=The Green Mile
Author=Stephen King

Response

An example of the response in the REST mode is:

{"action":"updated", "sid":12, "tid":12}

JSON

This mode allows using dataProcessor in JSON mode.

To enable this mode, pass the "JSON" parameter to the setTransactionMode method:

dp.setTransactionMode("JSON");

Request

This mode is used only for the POST operation and is useful for sending complex (nested) objects:

For example, for the Grid you can send a request as:

{ "action":"inserted", "id":"12", data:{
    "book":"The Green Mile", "author":"Stephen King"
}}

Response

A simple response should look as follows:

{"action":"updated"}

Additional Settings for Sending Data

Sending custom parameters with HTTP request

You can send custom parameters with HTTP request to the server. For this purpose, you should pass to the setTransactionMode method. It takes two parameters:

  • parameters - (object) a set of request parameters:
    • mode - (string) data sending mode, GET or POST
    • headers - (object) a set of headers, defined as "key":"value" pairs that should be sent with a request
    • payload - (object) additional data, set as "key":"value" pairs that should be sent to the server
  • total - (boolean) defines, whether to send all data at once, or each record by a separate request
dp.setTransactionMode({
    mode:"POST",
    headers:{
        "Header-Name1" : "HeaderValue1"
    },
    payload:{
        "key1":"value1"
    }
}, true);

Sending just changed items

A user can enable the mode just when the changed fields and row IDs are sent to the server-side (instead of all the fields in the default mode). To enable the mode, use the enablePartialDataSend method:

dp.enablePartialDataSend(true);

Active fields

There is a possibility to define which column may trigger the update. To define the so-called 'active' columns, use the setDataColumns() method:

dp.setDataColumns([false,true,true,true]);

Related sample:  Active fields

In that case, changing the first column values will not trigger data sending to the server. Such mode makes sense only if auto-update is enabled.

Validation

Grid allows defining the validators which will be activated before data sending.

For this purpose the method setVerificator(index,method) is used. Where:

  • index - the index of the column to which verificator will be assigned;
  • method - the verification function.

The verificator function is a function which will receive the following parameters:

  • the value of a cell;
  • the id of a row;
  • indexes of columns.

The function, based on such values, must return true (to accept a value) or false (to deny a value). If any value was denied during validation, data sending will be blocked and the onValidatationError event generated.

Inside of the verificator function, "this" points to the object which dataProcessor is attached to (grid or tree).

Verificator functions are called before sending data. The exact time depends on the way DataProcessor is initialized:

  • in auto update mode the functions will be called after each operation of editing a cell (when the editor is closed).
  • in manual sending mode - after the sendData() call.

Validate message

If you need to collect all validation errors and output them as a single error message, you can make it by setting the second parameter of the validation function to true (now the function will return a text message).

Related sample:  Basic validation

Styling

You can define the style that the string will have after one of the predefined actions has been completed. For example, after you've updated a string it will have the style defined in the property dp.styles.updated.

The styles which an object can have after changing but before saving:

  • dp.styles.updated - string's style for the updated status;
  • dp.styles.inserted- string's style for the inserted status;
  • dp.styles.deleted - string's style for the deleted status;

The styles which an object can have after getting the response:

  • dp.styles.invalid - string's style for the invalid status;
  • dp.styles.invalid_cell - style assigned to the cell the validation of which failed;
  • dp.styles.error - string's style for the error status;

Default style:

  • dp.styles.clear - default style of a row.

For example the default style for the updated record is the following:

dp.styles.updated="font-weight:bold;"

You can redefine it like this for example:

dp.styles.updated="font-style:italic; color:green;"

Related sample:  Custom styles

Debugging

In order to execute dataProcessor debugging, you need to enable it using the corresponding method - enableDebug:

var dp = new dataProcessor(url);
dp.enableDebug(true);

After that you will be able to check dataProcessor debug info in the browser's console.

In case you use dhtmlxConnector, you can enable a similar functionality on the server side and write server-side exceptions into a log file.

Back to top