Client / server data - legacy

Important: The documentation on this page refers to the client / server data interchange format using by Editor 1.0-1.4. 1.5 has a new format that supports multi-row editing. This documentation is maintained for legacy reference only. It is not recommended that any new server-side implementations use this method.§

Editor is a Javascript program which runs in the web-browser, therefore for it has to interact with the server, where the information from the end user will be permanently stored. For this communication to occur between the client and server successfully and with any server-side environment, Editor uses the protocol defined here. Although Editor has a number of pre-written server-side scripts available for it, this protocol provides complete separation between the client and server logic, ensuring that any server platform you wish to use can be used with Editor.

In the examples on this site just below the DataTable in each example the data that is submitted to and return by the server is shown live, so you can experiment with the examples and see the results immediately. Additionally, there are examples for the client-server communication shown below.

Data parameters

The communication between the client and server in Editor is initiated by an Ajax request (see ajax) with the data from Editor provided as HTTP parameters, and the data returned by the server given in a JSON format. The parameters for both the client-to-server and server-to-client communication are defined below.

Client-to-server

When a Editor form is submitted to the server it sends the following HTTP parameters:

If you wish to add additional parameters to be set to the server you can use the preSubmit event to manipulate the data object that is sent by Editor to the server.

Server-to-client

Once a form has been submitted to the server, Editor expects a JSON object to be returned with the following parameters:

If you wish to have the server return additional parameters that can be read and used on the client-side, use the postSubmit event to obtain the data (and potentially manipulate it if required) before Editor performs its client-side actions, such as updating a row, or submitSuccess to obtain the data after Editor has performed its client-side actions.

DataTables parameters

The above communications are used by Editor for the Create, Update and Delete actions, while the Read operation is performed by DataTables. The libraries available for Editor have the ability to handle all four data request types, but the DataTables request is really independent of how Editor operates.

For information on how DataTables obtains data, please refer to the DataTables manual for data sourcing, with particular emphasis on the ajax and columns.data option to define where Ajax data should be loaded from and the data source properties to read data from.

In addition to the default DataTables communication, Editor can listen for the Ajax loading of DataTables data to populate the options of the built in select, radio and checkbox field types. This is particularly useful when working with joined tables where a list of options must be presented to the user, defined by the information already in the database.

Editor does this by listening for the xhr event from the host table and searching for the options object in the JSON. If found it will loop over the properties of that object and match those properties against the field names. If found it will use the field's update() method to populate the options.

The options that Editor will take action on the DataTables Ajax data are defined below:

Example data exchanges

Create

action           = create
data[extn]       = 2947
data[first_name] = Fiona
data[last_name]  = Green
data[office]     = San Francisco
data[position]   = Chief Operating Officer (COO)
data[salary]     = 850000
data[start_date] = 2010-03-11

{
    "row": {
        "DT_RowId":   "row_29",
        "first_name": "Fiona",
        "last_name":  "Green",
        "position":   "Chief Operating Officer (COO)",
        "office":     "San Francisco",
        "extn":       "2947",
        "salary":     "850000",
        "start_date": "2010-03-11"
    }
}

Create - with a field error

action           = create
data[extn]       = 2947
data[first_name] = 
data[last_name]  = 
data[office]     = San Francisco
data[position]   = Chief Operating Officer (COO)
data[salary]     = 850000
data[start_date] = 2010-03-11

{
    "fieldErrors": [
        {
            "name":   "first_name",
            "status": "This field is required"
        },
        {
            "name":   "last_name",
            "status": "This field is required"
        }
    ]
}

Edit

action           = edit
data[extn]       = 2947
data[first_name] = Fiona
data[last_name]  = Green
data[office]     = San Francisco
data[position]   = Chief Operating Officer (COO)
data[salary]     = 850000
data[start_date] = 2010-03-11
id               = row_29

{
    "row": {
        "DT_RowId":   "row_29",
        "first_name": "Fiona",
        "last_name":  "Green",
        "position":   "Chief Operating Officer (COO)",
        "office":     "San Francisco",
        "extn":       "2947",
        "salary":     "850000",
        "start_date": "2010-03-11"
    }
}

Remove

action = remove
id[]   = row_29
id[]   = row_53

{ }