The usage of jsonmap with local data

Introduction.

jqGrid allows different sources to fill the grid. The input data will be get either from the server (see url parameter and datatype: "json" or datatype: "xml") or from input parameter data (in case of datatype: "local") or datastr (in case of datatype: "jsonstring" or datatype: "xmlstring"). In all cases with the exception of datatype: "json" without loadonce: true or datatype: "xml" without loadonce: true the input data will be saved inside of data and _index options of jqGrid.

To read the outer part of the input data jqGrid uses jsonReader, localReader or xmlReader option. The main part of input data should be array of items. Every item provides information about the row displayed in the grid. To read the information from the item of input data and to bind it to the corresponding column of colModel one uses either jsonmap (or xmlmap) property of colModel or the name alternatively.

For example, let us we use datatype: "json" with loadonce: true and we have items of input data in the following format

{ id: 123, name: { first: "Albert", last: "Einstein" }, birthday: "1879-03-14", otherPropery: ... }

and we have the columns, First Name, Last Name and Full Name defined as

{ name: "firstName", label: "First Name", jsonmap: "name.first" }
{ name: "lastName", label: "Last Name", jsonmap: "name.last" }
{ name: "fullName", label: "Full Name",
    jsonmap: function (item) {
        return item.name.first + " " + item.name.last
    } }

After the first reading of the the server response jqGrid will save the results in _index and data internal parameter of jqGrid and will change datatype from "json" to "local". The items of data array will be

{ _id_: "123", firstName: "Albert", lastName: "Einstein", fullName: "Albert Einstein", birthday: "1879-03-14" }

No other properties as the names of colModel will be saved in the items of data.

After such reading of input data jqGrid allows to sort/filter/search without any additional request to the server.

The state of the problem in jqGrid 4.7 and earlier version

In case of usage datatype: "local" jqGrid provides almost no mapping possibilities between the input data and the internal data. jqGrid expect that the names of properties of input data have one to one conformity with the values of name property of colModel. If the input data have nested structure one have to convert the data to flat model first and only then one can create the grid using input data parameter with the flat data. Such scenario is especially uncomfortable if one use editing possibilities of jqGrid or if one need multiple time update the input data.

The solution of the problem implemented in free jqGrid 4.8

Free jqGrid 4.8 allows to distinguish the "local" jqGrid filled from the server in case of loadonce: true scenario from direct filling of the grid using datatype: "local". In case of loadonce: true free jqGrid 4.8 saves the original value of datatype in the internal dataTypeOrg option. It allows to ignore jsonmap properties of colModel in loadonce: true scenario, but to use there in other cases of when we have datatype: "local".

The demo provides an example of usage nested input data with datatype: "local" without making any changes in the input data.

The input information of the grid is the following array of items

var mydata = [
        { id: 10, name: {first: "Angela", last: "Merkel"},
            address: { country: "Germany" },
            birthday: "1954-07-17",
            resume: [
                {year: 1954, event: "born"},
                {year: 2005, event: "Chancellor of Germany"}
            ] },
        { id: 20, name: {first: "Vladimir", last: "Putin"},
            address: { country: "Russia" },
            birthday: "1952-10-07",
            resume: [
                {year: 1952, event: "born"},
                {year: 2000, event: "President of Russia"}
            ] },
        { id: 30, name: {first: "Barack", last: "Obama"},
            address: { country: "USA" },
            birthday: "1961-08-04",
            resume: [
                { year: 1961, event: "born" },
                { year: 2008, event: "President of the United States of America" }
            ] }
    ];

The corresponding definition of colModel is

colModel: [
    { name: "name",
        jsonmap: function (item) {
            return item.name.first + " " + item.name.last;
        },
        sorttype: function (cell) {
            return cell.last + " " + cell.first;
        } },
    { name: "country", jsonmap: "address.country",
        sorttype: function (cell, item) {
            return item.address.country;
        } },
    { name: "birthday", formatter: "date", sorttype: "date",
        formatoptions: { newformat: "d-M-Y" } }
]

(some less important properties of colModel from the demo are not included above).