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:

Name Type Description
action string On create: create
On edit: edit
On remove: remove

Tell the server what action that Editor is performing. This is used to instruct the server if it should do an INSERT, UPDATE or DELETE on the database (if using an SQL backend, of course!) to reflect the changes requested by the client.
data object On create: Object of key / values pairs with the data from the form
On edit: Object of key / values pairs with the data from the form
On remove: Not sent

This parameter is an object where the parameter names match the field names in the form and the values of those parameters are the inputs from the end user. As such, the exact contents of this object will depend on the way Editor is configured for your form.
id array / string On create: Not sent
On edit: The row id to be edited (string)
On remove: Array of row ids to be deleted

This parameter is used to instruct the server on what existing data it should be operating for edit and remove events. The value of this parameter is determined by the idSrc option.

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:

Name Type Description
error string Optional - Error message to display to the end user

This property is used to indicate when an error has occurred in processing the data sent by the form submission, but is an error which cannot be attributed to any individual field (for which fieldErrors is used). The string returned in this parameter is shown to the end user as the error message for the submission. If no error has occurred, this parameter can either be omitted entirely or set to be an empty string.
fieldErrors array Optional - Individual field error messages

This property is used to indicate that one or more fields are in error (typically due to failed validation) and tell Editor what the error message to show to the end user for that field is.

Each array entry defines a field in error (so to indicate multiple field errors, simply put multiple entries into this array), where the entry is an object which two parameters: name - which is the fields.name of the field in error, and status which is the error message for the field to be displayed. If no field errors have occurred, this parameter can either be omitted entirely or set to an empty array.
row object / array On create: Data of the added / edited row
On edit: Data of the added / edited row
On remove: Not used / not required

When performing the create and edit actions, this parameter will contain the data that represents the new / updated row in the database - i.e. you would query the database, after doing the insert, to get the very latest data for just this row.

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:

Name Type Description
options object Optional - An object containing a list of field names with options to populate a field with.

Example data exchanges

Create

Client sends (as HTTP variables):

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

Server replies with the row parameter defining the data object for the row:

{
    "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

Client sends (as HTTP variables):

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

Server replies with two field errors:

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

Edit

Client sends (as HTTP variables):

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

Server replies with the row parameter defining the data object for the row:

{
    "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

Client sends (as HTTP variables) - note this example deletes two rows:

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

Server replies with an empty object - no error occurred. If an error were to occur, error should be set:

{ }