Editing of local data

Introduction. The state of the problem in jqGrid 4.7 and earlier version

One can use data option of jqGrid with datatype: "local" to create the grid based on array of local items. One can use any from three editing mode (inline editing, form editing or cell editing) to edit the local data. On the there side exists some problems:

• the types of properties of local items of data can be changes to strings after the editing
• one have no control on saving the data. The data will be always saved under the property with the name corresponds to the value of name property of the corresponding colModel column. There are no possibility to support nested structures in local data.

The solution of the problem implemented in free jqGrid 4.8

The main idea of the implementation

Free jqGrid allows to defines new convertOnSave and saveLocally callbacks in colModel. After end of editing the callback convertOnSave can be used to make the string, which is result of editing of the corresponding cell, to any other value. The callback saveLocally can help to persist the results of editing in the modified or in new item of data.

If one implements saveLocally callbacks in colModel, then one can in general do the conversion of data inside of it too and no convertOnSave is required. The introduction of convertOnSave on the other side allows to make the conversion only as a small addon to the actions of formatter and to hold the logic to persist the data inside of saveLocally callbacks. Free jqGrid provides for example some standard templates. For example the templates "booleanCheckbox" and "booleanCheckboxFa" can be used to display and to edit Boolean local data. The input values true and false will be displayed as checkboxes in the grid, there will be edited using <input type="checkbox"> and the results of editing will be saved as true or false. In the way one will stay inside of Boolean JavaScript type of data.

On the other side jsonmap and saveLocally callbacks could help to bind the Boolean value somewhere inside of the corresponding item of data array.

The implementation details: convertOnSave

The callback convertOnSave have one parameter, for example options. The options have the following properties:

• newValue - the modified value which need be saved
• oldValue - the old value or undefined in case of adding new row of data
• item - the full item of data (not yet modified). It can be {} in case of adding new row of data
• cm - the item in colModel which represents the editing column
• iCol - index of cm in colModel
• id - the id of the row of data with stripped idPrefix if it is used in the grid

The callback convertOnSave will be called with this initialized to DOM of the grid in the same way like almost all of jqGrid callbacks.

The callback convertOnSave should return the value which can be used instead of newValue. Bellow is the example of implementation of convertOnSave callback used in template: "integer":

convertOnSave: function (options) {
    var nData = options.newValue;
    return isNaN(nData) ? nData : parseInt(nData, 10);
}

The implementation details: saveLocally

The callback saveLocally have one parameter, for example options. The options have the following properties:

• newValue - the value of the cell which need be saved
• newItem - the object where one should save the newValue
• oldItem - the full item of data (not yet modified). It can be {} in case of adding new row of data
• cmName - the name of editing column
• cm - the item in colModel which represents the editing column
• iCol - index of cm in colModel
• id - the id of the row of data with stripped idPrefix if it is used in the grid

The callback convertOnSave will be called with this initialized to DOM of the grid in the same way like almost all of jqGrid callbacks.