Client / server data

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 returned 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.

Form 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 (form data POST values by default), 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 parameters:

Name	Type	Description
`action`	`string`	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. On create: `create` On edit: `edit` On remove: `remove`
`data`	`object`	An object containing the row ids and data to act upon. Each key / value pair represents a different row where the object keys are unique for each row being created, edited or deleted. Each key may be used more than once to allow an inner object for each row to be described. This inner object represents the data for each row being acted upon. The inner object's parameter names match the field names defined 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. Please note that depending upon the Editor configuration not all parameters will always be sent (unaltered values, for example, may not be sent based on the `form-options` configuration). On create the row(s) submitted are given the parameter keys 0...N. On the server-side these data can safely be used for iteration of the incoming data. On edit, the parameter keys reflect the primary key values for the row(s) being edited (specified by `idSrc`). The inner object still reflects the values of the form, as entered by the user. On remove, the parameter keys again reflect the primary key values for the row(s) in question (`idSrc`) and the inner object is the original data source object for each row. The PHP, .NET and NodeJS libraries for Editor only use the parameter key from this information, but you may find the rest of the data useful for performing actions based on the rows being deleted. Please see the examples further down this page for illustrations of the data sent to the server.

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
`data`	`array`	On create: Data of the added / edited row(s) On edit: Data of the added / edited row(s) On remove: Not used / not required When performing the create and edit actions, this parameter will contain the data that represents the new or updated rows in the database - i.e. you would query the database, after doing the insert, to get the very latest data for just this row.
`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.
`cancelled`	`array`	Optional - Row id's that were not processed A server-side process can optionally make the decision to not process the submitted data. In the case of the provided PHP and .NET libraries, this allows the `preCreate`, `preEdit` and `preRemove` events to be cancellable. Note that if a validation error is given for a row or field, the `cancelled` parameter does not need to be set - it is only used if validation has passed.

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.

Additionally Editor can also check the return object for information about uploaded files. This data can be used with the file() method and the upload and uploadMany field types.

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.
`files`	object	Optional - An object containing meta information about uploaded files. See the upload manual and `file()`.

File upload

Editor's file upload feature will send an Ajax request to the server when a file is selected - this happens asynchronously with respect to the rest of the form, so the file is already at the server-side when the rest of the form is submitted. The server should respond with JSON information about the newly uploaded file, including an identifier (typically a primary key value, although it could also be the file name), so that value may be used as part of the form's values.

Client-to-server

When Editor uploads a file to the server, the following parameters are submitted:

Name	Type	Description
`action`	`string`	Tell the server what action is taken place. In this case the value will be `upload`.
`uploadField`	`string`	Identify to the server the field name (`fields.name`) for the field which triggered the upload. This allows multiple upload fields to be used in a single form, since the server can distinguish between them.
`upload`	File	The file being uploaded

Server-to-client

Once the file has been successfully processed by the server, a JSON return is expected by Editor that contains information about the uploaded file. The parameters required in the JSON object are:

Name	Type	Description
`upload.id`	`string` or `number`	The unique value that can be used to identify the file - typically a primary key value
`files.{tableName}.{id}`	`object`	An object of information that describes the file held on the server. The exact composition of this object will vary from implementation to implementation, but it will typically include the file name and a web accessible path to the file. The `{tableName}` variable in the parameter name should match the database table name where information about the file is stored, and `{id}` should match the value in `upload.id`.

Example data exchanges

Create

Client sends (as HTTP parameters in the request body) - single row creation:

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

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

{
    "data": [
        {
            "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[0][extn]       = 2947
data[0][first_name] = 
data[0][last_name]  = 
data[0][office]     = San Francisco
data[0][position]   = Chief Operating Officer (COO)
data[0][salary]     = 850000
data[0][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 parameters in the request body) - single row edit:

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

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

{
    "data": [
        {
            "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"
        }
    ]
}

Multi-row edit

Client sends (as HTTP parameters in the request body) - note that only a single field's value is being submitted:

action               = edit
data[row_29][salary] = 110000
data[row_34][salary] = 110000

Server replies with the data parameter defining the data object for the edited rows:

{
    "data": [
        {
            "DT_RowId":   "row_29",
            "first_name": "Fiona",
            "last_name":  "Green",
            "position":   "Chief Operating Officer (COO)",
            "email":      "f.green@datatables.net",
            "office":     "San Francisco",
            "extn":       "2947",
            "age":        "48",
            "salary":     "110000",
            "start_date": "2015-05-22"
        },
        {
            "DT_RowId":   "row_34",
            "first_name": "Gavin",
            "last_name":  "Cortez",
            "position":   "Team Leader",
            "email":      "g.cortez@datatables.net",
            "office":     "San Francisco",
            "extn":       "2860",
            "age":        "22",
            "salary":     "110000",
            "start_date": "2008-10-26"
        }
    ]
}

Remove

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

action                   = remove
data[row_29][DT_RowId]   = row_29
data[row_29][first_name] = Fiona
data[row_29][last_name]  = Green
data[row_29][position]   = Chief Operating Officer (COO)
data[row_29][email]      = f.green%40datatables.net
data[row_29][office]     = San Francisco
data[row_29][extn]       = 2947
data[row_29][age]        = 48
data[row_29][salary]     = 850000
data[row_29][start_date] = 2015-05-22
data[row_34][DT_RowId]   = row_34
data[row_34][first_name] = Gavin
data[row_34][last_name]  = Cortez
data[row_34][position]   = Team Leader
data[row_34][email]      = g.cortez%40datatables.net
data[row_34][office]     = San Francisco
data[row_34][extn]       = 2860
data[row_34][age]        = 22
data[row_34][salary]     = 235500
data[row_34][start_date] = 2008-10-26

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

{ }

Upload

Client sends (as HTTP variables):

action       = upload
uploadField  = image
upload       = ... // File information and binary content

Server replies with:

{
    "files": {
        "files": {
            "1": {
                "filename": "Screen Shot.png",
                "web_path": "\/upload\/1.png"
            }
        }
    },
    "upload": {
        "id": "1"
    }
}