Cell editing provides the frontend user with functionality to change the contents of one single cell from a row and then the developer has the abbility to handle the changed data by AJAX or in a jqGrid cell edit event (see below).
Cell Editing supports key navigation and editing individual cells, with the following behaviour:
In order to use this module you should mark the Cell editing and Common when you download the grid. For more information refer to Download.
For Developers of the JQuery plugin itself they can use the grid.celledit.js file in the src directory.
The properties, events and methods used in cell editing are a sub-set of those of the parent grid, and described below
These properties are specific for cell editing and should be set in grid options
| Property | Type | Description | Default |
|---|---|---|---|
| cellEdit | boolean | Enables (disables) cell editing. When this option is set to true, onSelectRow event can not be used, and hovering is disabled (when mouseover on the rows). | false |
| cellsubmit | string | Determines where the contents of the cell are saved - can have two values: 'remote' or 'clientArray'. If remote the content of the cell if anything is changed is immediately saved to the server using the cellurl property, via ajax. The rowid and the cell content are added to the url by default. If you have the “mtype” setting set to post, the key value pears will be send as post variables. For example, if we save the cell named mycell,{id: rowid, mycell: cellvalue} is added to the url. If cellsubmit is 'clientArray', no ajax request is made and the content of the changed cell can be obtained via the method getChangedCells or thru a event. | remote |
| cellurl | string | the url where the cell is to be saved. You need to set this only when you use cellsubmit as 'remote'. | null |
| ajaxCellOptions | object | This option allow to set global ajax settings for the cell editiing when we save the data to the server. Note that with this option is possible to overwrite all current ajax setting in the save request including the complete event. | empty object |
When using the 'remote' setting you could add these lines to your grid configuration:
{ 'cellEdit' : true, 'cellsubmit' : 'remote', 'cellurl' : '/url/to/handling/the/changed/cell/value' }
When your are using 'clientArray' as cellsubmit setting, only these settings are important:
{ 'cellEdit' : true, 'cellsubmit' : 'remote' }
These events are related to cell editing and should be used in grid options.
Many of the following events use the parameters defined here:
| Event | Parameters | Description |
|---|---|---|
| afterEditCell | rowid, cellname, value, iRow, iCol | applies only to a cell that is editable; this event fires after the edited cell is edited - i.e. after the element is inserted into the DOM |
| afterRestoreCell | rowid, value, iRow, iCol | applies only to a cell that is editable; this event fires after calling the method restoreCell or the user press ESC leaving the changes |
| afterSaveCell | rowid, cellname, value, iRow, iCol | applies only to a cell that is editable; this event fires after the cell has been successfully saved. This is the ideal place to change other content. |
| afterSubmitCell | serverresponse, rowid, cellname, value, iRow, iCol | applies only to a cell that is editable; this event Fires after the cell and other data is posted to the server Should return array of type [success(boolean),message] when return [true,“”] all is ok and the cellcontent is saved [false,“Error message”] then a dialog appears with the “Error message” and the cell content is not saved. servereresponse is the response from the server. To use this we should use serverresponse.responseText to obtain the text message from the server. |
| beforeEditCell | rowid, cellname, value, iRow, iCol | applies only to a cell that is editable; this event fires before editing the cell. |
| beforeSaveCell | rowid, cellname, value, iRow, iCol | applies only to a cell that is editable; this event fires before validation of values if any. This event can return the new value which value can replace the edited one beforeSaveCell : function(rowid,celname,value,iRow,iCol) { if( some_condition ) { return “new value”; } } The value will be replaced with “new value” |
| beforeSubmitCell | rowid, cellname, value, iRow, iCol | applies only to a cell that is editable; this event fires before submit the cell content to the server (valid only if cellsubmit : 'remote'). Can return new array that will be posted to the server. beforeSubmitCell : function(rowid,celname,value,iRow,iCol) { if( some_condition ) { return {name1:value1,name2:value2} } else { return {} } } The returned array will be added to the cellurl posted data. |
| errorCell | serverresponse, status | fires if there is a server error; servereresponse is the response from the server. To use this we should apply serverresponse.responseText to obtain the text message from the server. status is the status of the error. If not set a modal dialog apper. |
| formatCell | rowid, cellname, value, iRow, iCol | applies only to a cell that is editable; this event allows formatting the cell content before editing, and returns the formatted value |
| onSelectCell | rowid, celname, value, iRow, iCol | applies only to cells that are not editable; fires after the cell is selected |
| serializeCellData | postdata | If set this event can serialize the data passed to the ajax request when we save a cell. The function should return the serialized data. This event can be used when a custom data should be passed to the server - e.g - JSON string, XML string and etc. To this event is passed the data which will be posted to the server |
Depending on your cellSubmit setting set to 'remote' or 'clientArray' the following events will be fired in the following order:
All of the methods below should be applied to the jqGrid object and all of them return the same object.
| Method | Parameters | Description |
|---|---|---|
| editCell | iRow, iCol, edit | edit a cell with the row index iRow( do not mix with rowid) in index column iCol. If the edit is set to false the cell is just selected and not edited. If set to true the cell is selected and edited. |
| getChangedCells | method | Returns an array of the changed cells depending on method (string, default 'all'). When 'all' this method returns all the changed rows; when 'dirty' returns only the changed cells with the id of the row |
| restoreCell | iRow, iCol | restores the edited content of cell with the row index iRow( do not mix with rowid) in index column iCol |
| saveCell | iRow, iCol | saves the cell with the row index iRow( do not mix with rowid) in index column iCol |
When the cell is edited and the input elements is created we set the following rules:
When the data is posted to the server we construct object {} that contain: