Data Manipulation

With the first release of jqGrid, the only possible way to obtain data was via XML as described in the tutorial above. Later, many people requested the ability to obtain data via JSON, then with an array and finally with 'real' names. After lot of work and with the help of the community we now have a wide range of methods for obtaining data.

The related options (in options array) for manipulating different types of data are:

datatype: the possible options are

  • xml
  • json
  • jsonp
  • array
  • xmlstring
  • jsonstring
  • script
  • function (…)

It is very important to read this chapter, in order to understand how you should work with the data!

The default mapping for XML data is as follows:

jQuery("#gridid").jqGrid({
...
   xmlReader : { 
      root: "rows", 
      row: "row", 
      page: "rows>page", 
      total: "rows>total", 
      records : "rows>records", 
      repeatitems: true, 
      cell: "cell", 
      id: "[id]",
      userdata: "userdata",
      subgrid: { 
         root:"rows", 
         row: "row", 
         repeatitems: true, 
         cell:"cell" 
      } 
   },
...
});

If your server can provide data in this structure, you need to do nothing more; but if not, there is a way (several ways) to handle the data you are given. See XML Data below.

The default mapping for JSON data is as follows:

jQuery("#gridid").jqGrid({
...
   jsonReader : { 
      root: "rows", 
      page: "page", 
      total: "total", 
      records: "records", 
      repeatitems: true, 
      cell: "cell", 
      id: "id",
      userdata: "userdata",
      subgrid: { 
         root:"rows", 
         repeatitems: true, 
         cell:"cell" 
      } 
   },
...
});

In colModel, the related options are xmlmap for the description of an XML field, and jsonmap for the description of a JSON field. For example:

jQuery("#gridid").jqGrid({
...
   colModel : [ {name:'amount',..., xmlmap:'amt'...}...],
...
});

will cause jqGrid to search in the XML data for an 'amt' tag (when the repeatitems option is set to false. See below.).

XML Data

As mentioned above, if we do not set the datatype and xmlReader parameter in the options array, the grid expects XML data, and the structure of this data is as described in our example. But what if we do not have the chance to manipulate the server response? The solution to this problem is xmlReader, again with some additions in colModel. Here is a brief description of xmlReader.

Important note: the rules of accessing the element from XML are the same as those used in jQuery library, i.e. CSS patterns. For more information refer to: http://www.w3.org/TR/REC-CSS2/selector.html

jQuery("#gridid").jqGrid({
...
   xmlReader : { 
      root: "rows", 
      row: "row", 
      page: "rows>page", 
      total: "rows>total", 
      records : "rows>records", 
      repeatitems: true, 
      cell: "cell", 
      id: "[id]",
      userdata: "userdata",
      subgrid: { 
         root:"rows", 
         row: "row", 
         repeatitems: true, 
         cell:"cell" 
      } 
   },
...
});

As of version 4.3 jqGrid can read any attribute from the XML response. Moreover the tags can be set as function.

All the elements in the XML reader will be explained as examples rather than as strong description.

  • root element

The first setting here defines the root element. This describes where our data begins and all other loops begin from this element. For example,

... 
<invoices> 
   <request>true</request> 
   ... 
   <result> 
      <row> 
         <cell>data1</cell> 
         <cell>data2</cell> 
         <cell>data3</cell> 
         <cell>data4</cell> 
         <cell>data5</cell> 
         <cell>data6</cell> 
      </row> 
      ... 
   </result> 
</invoices>

If we set the root element to “result” all data will be processed from there. In this case, because our rows are tagged <row> and our cells tagged <cell>, all that is needed is to set

jQuery("#gridid").jqGrid({
...
   xmlReader: { root:"result" },
...
});

The next element is the

  • row element.

This describes the information for particular row. Note that row must be a child of the root element. Here, if the XML looks like this,

... 
<invoices> 
   <request>true</request> 
   ... 
   <result> 
      <invoice> 
         <cell>data1</cell> 
         <cell>data2</cell> 
         <cell>data3</cell> 
         <cell>data4</cell> 
         <cell>data5</cell> 
         <cell>data6</cell> 
      </invoice> 
      ... 
   </result> 
</invoices>

the setting to properly interpret this data would be

jQuery("#gridid").jqGrid({
...
   xmlReader: { root:"result", row:"invoice"  },
...
});

The

  • page
  • total and
  • records

elements describe the information needed for the pager. These elements can be, but do not have to be, a child of the root element. For example, to interpret this data,

... 
<invoices> 
   <request>true</request> 
   ... 
   <currentpage>1</currentpage>
   <totalpages>10</totalpages>
   <totalrecords>20</totalrecords>
   <result> 
      <invoice> 
         <cell>data1</cell> 
         <cell>data2</cell> 
         <cell>data3</cell> 
         <cell>data4</cell> 
         <cell>data5</cell> 
         <cell>data6</cell> 
      </invoice> 
      ... 
   </result> 
</invoices>

the xmlReader will have to look like this:

jQuery("#gridid").jqGrid({
...
   xmlReader: { 
      root:"result", 
      row:"invoice",
      page:"invoices>currentpage", 
      total:"invoices>totalpages", 
      records:"invoices>totalrecords"
  },
...
});

The * repeatitems and * cell elements tells jqGrid that the information for the data in the row is repeatable - i.e. the elements have the same tag cell described in cell element. For this example,

... 
<invoices> 
   <request>true</request> 
   ... 
   <currentpage>1</currentpage>
   <totalpages>10</totalpages>
   <totalrecords>20</totalrecords>
   <result> 
      <invoice> 
         <invcell>data1</invcell> 
         <invcell>data2</invcell> 
         <invcell>data3</invcell> 
         <invcell>data4</invcell> 
         <invcell>data5</invcell> 
         <invcell>data6</invcell> 
      </invoice> 
      ... 
   </result> 
</invoices>

the xmlReader will look like this:

jQuery("#gridid").jqGrid({
...
   xmlReader: { 
      root:"result", 
      row:"invoice",
      page:"invoices>currentpage", 
      total:"invoices>totalpages", 
      records:"invoices>totalrecords",
      repeatitems:true,
      cell:"invcell"
  },
...
});

Next is the

  • id

element. If repeatitems is set to true and key option in colModel is set to false the id, if present in XML data, must be a attribute of the row element. Lets look at the example:

... 
<invoices> 
   <request>true</request> 
   ... 
   <currentpage>1</currentpage>
   <totalpages>10</totalpages>
   <totalrecords>20</totalrecords>
   <result> 
      <invoice asin='12345'> 
         <invcell>data1</invcell> 
         <invcell>data2</invcell> 
         <invcell>data3</invcell> 
         <invcell>data4</invcell> 
         <invcell>data5</invcell> 
         <invcell>data6</invcell> 
      </invoice> 
      ... 
   </result> 
</invoices>

In this case the xmlReader is:

jQuery("#gridid").jqGrid({
...
   xmlReader: { 
      root:"result", 
      row:"invoice",
      page:"invoices>currentpage", 
      total:"invoices>totalpages", 
      records:"invoices>totalrecords",
      repeatitems:true,
      cell:"invcell",
      id : "[asin]"
  },
...
});

Let's suppose that the structure of the XML document returned from the server has the following format:

... 
<invoices> 
   <request>true</request> 
   ... 
   <currentpage>1</currentpage>
   <totalpages>10</totalpages>
   <totalrecords>20</totalrecords>
   <result> 
      <invoice> 
         <asin>12345</asin>
         <invoiceno>data1</invoiceno>
         <invoicedate>data2</invoicedate> 
         <invoiceamount>data3</invoiceamount> 
         <invoicetax>data4</invoicetax> 
         <invoicetotal>data5</invoicetotal> 
         <notes>data6</notes> 
      </invoice> 
      ... 
   </result> 
</invoices>

where the <asin> tag describes the unique id and this should be set as the row id in the grid and not displayed in the grid. Following the rules we can construct the following:

jQuery("#gridid").jqGrid({
...
   xmlReader: { 
      root:"result", 
      row:"invoice",
      page:"invoices>currentpage", 
      total:"invoices>totalpages", 
      records:"invoices>totalrecords",
      repeatitems:false,
      id : "asin"
  },
...
});
 
and our colModel from the example should look like this:
 
<code javascript>
jQuery("#gridid").jqGrid({
...
   colModel :[ 
      {name:'invid', index:'invid', width:55, xmlmap:"invoiceno"}, 
      {name:'invdate', index:'invdate', width:90, xmlmap:"invoicedate"}, 
      {name:'amount', index:'amount', width:80, align:'right', xmlmap:"invoiceamount"}, 
      {name:'tax', index:'tax', width:80, align:'right', xmlmap:"invoicetax"}, 
      {name:'total', index:'total', width:80, align:'right', xmlmap:"invoicetotal"}, 
      {name:'note', index:'note', width:150, sortable:false, xmlmap:"notes"} 
   ],
   xmlReader: { 
      root:"result", 
      row:"invoice",
      page:"invoices>currentpage", 
      total:"invoices>totalpages", 
      records:"invoices>totalrecords",
      repeatitems:false,
      id : "asin"
  },
...
});

We can use another trick. If the names in colModel are not important for you, you can do the following.

jQuery("#gridid").jqGrid({
...
   colModel :[ 
      {name:'invoiceno', index:'invid', width:55}, 
      {name:'invoicedate', index:'invdate', width:90}, 
      {name:'invoiceamount', index:'amount', width:80, align:'right'}, 
      {name:'invoicetax', index:'tax', width:80, align:'right'}, 
      {name:'invoicetotal', index:'total', width:80, align:'right'}, 
      {name:'notes', index:'note', width:150, sortable:false} 
   ],
   xmlReader: { 
      root:"result", 
      row:"invoice",
      page:"invoices>currentpage", 
      total:"invoices>totalpages", 
      records:"invoices>totalrecords",
      repeatitems:false,
      id : "asin"
  },
...
});

In other words, jqGrid first looks to see if there is an xmlmap option available; if this option is not available the name is used as the xmlmap. But all of this is true only if the repeatitems element in xmlReader is set to false.

The subgrid option is included in several of the xmlReader examples above. The principles in constructing the rules for this data are the same as those described above. More details about subgrids can be found in the section on Subgrids.

XML String

The xmlstring option has similar features to the XML option (See above). The only difference is that the data is passed as string. In this case we need to have a valid XML data string. To do that we can use a datastr option. The example from our tutorial can look like this.

If you use an XML string to obtain the data - after the data is retrieved the datatype option automatically is set to local - i.e. (currently) the paging will not work!

<script>
var mystr =
"<?xml version='1.0' encoding='utf-8'?>
<invoices>
    <rows>
        <row>
            <cell>data1</cell>
            <cell>data2</cell>
            <cell>data3</cell>
            <cell>data4</cell>
            <cell>data5</cell>
            <cell>data6</cell>    
        </row>
    </rows>
</invoices>";
 
jQuery(document).ready(function(){ 
  jQuery("#list").jqGrid({
    datatype: 'xmlstring',
    datastr : mystr,
    colNames:['Inv No','Date', 'Amount','Tax','Total','Notes'],
    colModel :[ 
      {name:'invid', index:'invid', width:55, sorttype:'int'}, 
      {name:'invdate', index:'invdate', width:90, sorttype:'date', datefmt:'Y-m-d'}, 
      {name:'amount', index:'amount', width:80, align:'right', sorttype:'float'}, 
      {name:'tax', index:'tax', width:80, align:'right', sorttype:'float'}, 
      {name:'total', index:'total', width:80, align:'right', sorttype:'float'}, 
      {name:'note', index:'note', width:150, sortable:false} ],
    pager: '#pager',
    rowNum:10,
    viewrecords: true,
    caption: 'My first grid'
  }); 
}); 
</script>

As you can see, this example introduces another option in colModel: sorttype. This option describes how a particular column is to be sorted, because when using xmlstring as the source for the grid, jqGrid uses client-side sorting.

XML Notes and Limitations

  • Attributes in any XML tag can not be used to obtain the data. The only exception is the id
  • When the option repeatitems in xmlReader is set to true the number of columns defined in ColModel should be equal of the number of cells in the row element
  • When the option repeatitems in xmlReader is set to true the id of the row can be set using the key option in colModel
  • When the option repeatitems in xmlReader is set to false it is NOT necessary that the number of columns defined in ColModel should be equal of “number of cells in the row element”.
  • When the option repeatitems in xmlReader is set to false the row tag can not contain any child elements

JSON Data

As of version 3.6.5 the returned JSON string should a valid JSON string.
For more information refer HERE and HERE

JSON data is handled in a fashion very similar to that of XML data. What is important is that the definition of the jsonReader matches the data being received

datatype : json or jsonp, (or jsonstring)

The default definition of the jsonreader is as follows:

jQuery("#gridid").jqGrid({
...
   jsonReader : {
     root: "rows",
     page: "page",
     total: "total",
     records: "records",
     repeatitems: true,
     cell: "cell",
     id: "id",
     userdata: "userdata",
     subgrid: {root:"rows", 
        repeatitems: true, 
       cell:"cell"
     }
   },
...
});

If the parameter datatype is 'json', jqGrid expects the following default format for JSON data.

{ 
  "total": "xxx", 
  "page": "yyy", 
  "records": "zzz",
  "rows" : [
    {"id" :"1", "cell" :["cell11", "cell12", "cell13"]},
    {"id" :"2", "cell":["cell21", "cell22", "cell23"]},
      ...
  ]
}

The tags used in this example are described in the following table:

TagDescription
totaltotal pages for the query
pagecurrent page of the query
recordstotal number of records for the query
rowsan array that contains the actual data
idthe unique id of the row
cellan array that contains the data for a row

The structure of the jsonReader is very similar to the xmlReader. The only missing part is the row element which is not needed for JSON data. Let's begin our walk through the jsonReader.

The first element is a

  • root

element. This element describes where our data begins. In other words, this points to the array that contains the data. If we set

jQuery("#gridid").jqGrid({
...
   jsonReader : {root:"invdata"},
...
});

then the returned string should be

{ 
  "total": "xxx", 
  "page": "yyy", 
  "records": "zzz",
  "invdata" : [
    {"id" :"1", "cell" :["cell11", "cell12", "cell13"]},
    {"id" :"2", "cell":["cell21", "cell22", "cell23"]},
      ...
  ]
}

The

  • page
  • total
  • records

elements describe the information needed for the pager. For example, if the jsonReader is set as follows,

jQuery("#gridid").jqGrid({
...
   jsonReader : {
      root:"invdata",
      page: "currpage",
      total: "totalpages",
      records: "totalrecords"
   },
...
});

then the data should be

{ 
  "totalpages": "xxx", 
  "currpage": "yyy",
  "totalrecords": "zzz",
  "invdata" : [
    {"id" :"1", "cell" :["cell11", "cell12", "cell13"]},
    {"id" :"2", "cell" :["cell21", "cell22", "cell23"]},
      ...
  ]
}

The

  • cell

element describes the array which contains the data for the row.

jQuery("#gridid").jqGrid({
...
   jsonReader : {
      root:"invdata",
      page: "currpage",
      total: "totalpages",
      records: "totalrecords",
      cell: "invrow"
   },
...
});

The data to match this description would be

{ 
  "totalpages": "xxx", 
  "currpage": "yyy",
  "totalrecords": "zzz",
  "invdata" : [
    {"id" :"1", "invrow" :["cell11", "cell12", "cell13"]},
    {"id" :"2", "invrow" :["cell21", "cell22", "cell23"]},
      ...
  ]
}

The

  • id

element descibes the unique id for the row

jQuery("#gridid").jqGrid({
...
   jsonReader : {
      root:"invdata",
      page: "currpage",
      total: "totalpages",
      records: "totalrecords",
      cell: "invrow",
      id: "invid"
   },
...
});

The data for this description is:

{ 
  "totalpages": "xxx", 
  "currpage": "yyy",
  "totalrecords": "zzz",
  "invdata" : [
    {"invid" :"1", "invrow" :["cell11", "cell12", "cell13"]},
    {"invid" :"2", "invrow" :["cell21", "cell22", "cell23"]},
      ...
  ]
}

It is possible to set the cell element to an empty string. And, it is possible to set the id as number. Here is an example of these possibilities:

jQuery("#gridid").jqGrid({
...
   jsonReader : {
      root:"invdata",
      page: "currpage",
      total: "totalpages",
      records: "totalrecords",
      cell: "",
      id: "0"
   },
...
});

In this case the id is the first element from the row data

{ 
  "totalpages" : "xxx", 
  "currpage" : "yyy",
  "totalrecords" : "zzz",
  "invdata" : [
    ["1", "cell11", "cell12", "cell13"],
    ["2", "cell21", "cell22", "cell23"],
      ...
  ]
}

The

  • repeatitems

element tells jqGrid that the information for the data in the row is repeatable - i.e. the elements have the same tag cell described in cell element. Setting this option to false instructs jqGrid to search elements in the json data by name. This is the name from colModel or the name described with the jsonmap option in colModel.

Here is an example:

jQuery("#gridid").jqGrid({
...
   jsonReader : {
      root:"invdata",
      page: "currpage",
      total: "totalpages",
      records: "totalrecords",
      repeatitems: false,
      id: "0"
   },
...
});

The resulting data in our example should be:

{ 
  "totalpages" : "xxx", 
  "currpage" : "yyy",
  "totalrecords" : "zzz",
  "invdata" : [
    {"invid" : "1","invdate":"cell11", "amount" :"cell12", "tax" :"cell13", "total" :"1234", "note" :"somenote"},
    {"invid" : "2","invdate":"cell21", "amount" :"cell22", "tax" :"cell23", "total" :"2345", "note" :"some note"},
      ...
  ]
}

The id element in this case is 'invid'.

A very useful feature here (repeatitems:false) is that there is no need to include all the data that is represented in colModel. Since we make a search by name, the order does not need to match the order in colModel. Hence the following string will be correctly interpreted in jqGrid.

{ 
  "totalpages" : "xxx", 
  "currpage" : "yyy",
  "totalrecords" : "zzz",
  "invdata" : [
    {"invid" :"1", "invdate" : "cell11", "note" :"somenote"},
    {"invid" :"2", "amount" : "cell22", "tax" :"cell23", "total" :"2345"},
      ...
  ]
}

JSON String

The jsonstring option has the same features as json. The only difference is that the data is passed as string. In this case we need to have a valid JSON data string. To do that we can use a datastr option. See the xmlstring example.

If you use a jsonstring to obtain the data - after the data is retrieved the datatype option automatically is set to local - i.e. (currently) the paging will not work!

JSON dot notation

When using JSON data with named values (i.e the repeatitems option is false) we can use so named dot notation and index notation.

For example, our colModel definition might be as follows:

jQuery("#gridid").jqGrid({
...
 colModel:[
   {name:'name',label:'Name', width:150,editable: true},
   {name:'id',width:50, sorttype:"int", editable: true,formatter:strongFmatter},
   {name:'email',label:'Email', width:150,editable: true,formatter:'email'},
   {name:'stock',label:'Stock', width:60, align:"center", editable: true,formatter:'checkbox',edittype:"checkbox"},
   {name:'item.price',label:'Price', width:100, align:"right", editable: true,formatter:'currency'},
   {name:'item.weight',label:'Weight',width:60, align:"right", editable: true,formatter:'number'},
   {name:'ship',label:'Ship Via',width:90, editable: true,formatter:'select', edittype:"select",editoptions: value:"2:FedEx;1:InTime;3:TNT;4:ARK;5:ARAMEX"}},      
   {name:'note',label:'Notes', width:100, sortable:false,editable: true,edittype:"textarea", editoptions:{rows:"2",cols:"20"}}      
 ],
...
});

Note the elements defined as name:'item.price' and name:'item.weight'

Then our data:

{
   "page":"1",
   "total":2,
   "records":"13", 
   "rows":[ 
      {"id":"12345","name":"Desktop Computers","email":"josh@josh.com","item":{"price":"1000.72", "weight": "1.22" }, "note": "note", "stock": "0","ship": "1"}, 
      {"id":"23456","name":"<var>laptop</var>","note":"Long text ","stock":"yes","item":{"price":"56.72", "weight":"1.22"},"ship": "2"},
      {"id":"34567","name":"LCD Monitor","note":"note3","stock":"true","item":{"price":"99999.72", "weight":"1.22"},"ship":"3"},
      {"id":"45678","name":"Speakers","note":"note","stock":"false","ship":"4"} 
    ] 
}

jsonReader as Function

In certain situation you will obtain the data from a web service. In this case it is not possible to configure all the properties of the response so that the grid will work properly. As of version 3.6.4 it is possible to define the elements of the jsonReader as function. Below is a example on how this can be used:

jsonReader: {
    repeatitems: false,
    id: "Id",
    root: function (obj) { return obj; },
    page: function (obj) { return 1; },
    total: function (obj) { return 1; },
    records: function (obj) { return obj.length; }
}

Where obj is the response from the service/server

Array Data

Despite the fact that the primary goal of jqGrid is to represent dynamic data returned from a database, jqGrid includes a wide range of methods to manipulate data at client side: Array data.

Related options in options array: datataype
Related options in colModel: sorttype, datefmt
Related methods : getRowData, delRowData, setRowData, addRowData, updateGridRows See Methods

As of version 3.7 we introduce two additional parameters data and localReader. The data parameter is described in grid options. The localReader has the same sense as jsonReader described above, but applied to array data that is stored locally.
The initial configuration of the localReader is the same as those from jsonReader

localReader = {
   root: "rows",
   page: "page",
   total: "total",
   records: "records",
   repeatitems: false,
   cell: "cell",
   id: "id",
   userdata: "userdata",
   subgrid: {root:"rows", repeatitems: true, cell:"cell"}
}

All operations that are valid for jsonReader can be applied to localReader.

If we have defined a pager for grid with client side data, the buttons in pager are automatically disabled. In other words, the current release of grid does not support client side paging and serching.

First we must instruct jqGrid that the data that will be present is at client side. This is done with the option datatype. To use this we must set

jQuery("#grid_id").jqGrid({
...
   datatype: "clientSide",
...
});

The other option that can be used is “local” i.e. datatype: “local” These are the same.
Having this it is a good idea to set the sorttypes for the columns. If the sorttype is not set the default sorttype is “text”. Let's consider our example in terms of array data.

...
<script>
jQuery(document).ready(function(){ 
    jQuery("#list").jqGrid({
        datatype: 'clientSide',
        colNames:['Inv No','Date', 'Amount','Tax','Total','Notes'],
        colModel :[ 
        {name:'invid',index:'invid', width:55, sorttype:'int'}, 
        {name:'invdate',index:'invdate', width:90, sorttype:'date', datefmt:'Y-m-d'}, 
        {name:'amount',index:'amount', width:80, align:'right',sorttype:'float'}, 
        {name:'tax',index:'tax', width:80, align:'right',sorttype:'float'}, 
        {name:'total',index:'total', width:80,align:'right',sorttype:'float'}, 
        {name:'note',index:'note', width:150, sortable:false} ],
        pager: '#pager',
        rowNum:10,
        viewrecords: true,
        caption: 'My first grid'
   }); 
...
}); 
</script>

You can see the new setting here: datatype, sortype and datefmt.
The possible values for the sorttype are:
int - the data is interpreted as integer,
float - the data is interpreted as decimal number
date - the data is interpreted as date
text - the data is interpreted as text

We need this information for the appropriate sorting of these types. Additionally for the sorttype date we must known the format of the data that will be present in the grid. The default format is a ISO format 'Y-m-d'. The description of the date format is like a PHP way. For more information refer to php.net.

Let's add some data. This can be done with the method addRowData.
The parameters to this method are:

jQuery("#grid_id").addRowData( rowid, data, position, srcrowid );

where:

  • rowid: this value will be set as the id of the row
  • data: is the array of data in pair name:value, where the name is the name from colModel
  • position: specifies where to add the data - first, last, before or after. “first” adds the new row at the top of the grid; “last” adds the data in the last position; “before” and “after” refer to the row identified in srcrowid.
  • srcrowid: the id of a row which the new data is to be added either “before” or “after”
<script>
...
var myfirstrow = {invid:"1", invdate:"2007-10-01", note:"note", amount:"200.00", tax:"10.00", total:"210.00"};
jQuery("#list").addRowData("1", myfirstrow);
...
</script>

With this line we have added our first row. It is important to note that the order of the name-value pairs is arbitrary. Moreover, we can set a single name-value pair, like this.

<script>
...
jQuery("#list").addRowData("2", {amount:"300.00"});
...
</script>

With this line we have added second row with only a value in the amount column.

To get data from the particular row we should use getRowData method:

jQuery("#grid_id").getRowData( rowid );

where rowid is the id for the row which values we will obtain

jQuery("#list").getRowData( "1" );

will return array of name-value pairs - the result is

{invid:"1", invdate:"2007-10-01", note:"note", amount:"200.00", tax:"10.00", total:"210.00"};

To delete a row we should use delRowData method:

jQuery("#grid_id").delRowData( rowid );

where rowid is the id of the row that can be deleted.

jQuery("#list").delRowData( "2" );

will delete the row with the id = 2.
This method returns true if the deletion is successfully, false otherwise

To change all or part of the values in a given row, we can use a setRowData method.

jQuery("#grid_id").setRowData( rowid, data );

where rowid is the id of the row which values will be changed
data is a array of data that contain the new values. The structure of array is in type name:value.

jQuery("#list").setRowData( "1", { tax:"5", total:"205" });

will change the values tax and total of row with id = 1.
The method returns true if update is successful, otherwise false.

To update a set of grid rows at once we can use updateGridRows. For more info refer to Addon methods

Function

This option does not really define the datatype at all, but rather how to handle the data that is provided by the server (which would still come as either xml or json data). The functions defined as a Datatype should (or can) call addXMLData, addJSONData or addRowData once the data has been received. If you use a pager, it is useful to call your_grid.setGridParam({lastpage: your_number}) to specify the number of pages.
Calling Convention:

datatype : function(postdata) {
// do something here
}

Datatype functions are supplied with a single object containing the request information (parameter postdata), which normally would have been transformed into GET or POST arguments. This object is compatible with the data: option supplied to the jQuery $.ajax function.

Consider our example here is how this will work with datatype function:

<script type="text/javascript">
...
jQuery(document).ready(function(){ 
  jQuery("#list").jqGrid({
    datatype: function(postdata) {
        jQuery.ajax({
           url: 'example.php',
           data:postdata,
           dataType:"xml",
           complete: function(xmldata,stat){
              if(stat=="success") {
                 var thegrid = jQuery("#list")[0];
                 thegrid.addXmlData(xmldata.responseXML);
              }
           }
        });
    },
    colNames:['Inv No','Date', 'Amount','Tax','Total','Notes'],
    colModel :[ 
      {name:'invid', index:'invid', width:55}, 
      {name:'invdate', index:'invdate', width:90}, 
      {name:'amount', index:'amount', width:80, align:'right'}, 
      {name:'tax', index:'tax', width:80, align:'right'}, 
      {name:'total', index:'total', width:80, align:'right'}, 
      {name:'note', index:'note', width:150, sortable:false} 
    ],
    pager: '#pager',
    rowNum:10,
    rowList:[10,20,30],
    sortname: 'invid',
    sortorder: 'desc',
    viewrecords: true,
    caption: 'My first grid'
  }); 
}); 
...
</script>

User Data

In some cases we need to have custom data returned from the request that is not automatically displayed by jqGrid, that we use either in a later process or to display additional information somewhere in the HTML page or associated with the grid. To do that a userdata tag can be used.

In xmlReader this is defined as:

xmlReader: {
  ...
  userdata: "userdata",
  ...
}

This describes the tag where our custom data is. The important part here is that the XML tag should have a attribute name in order to associate data.
In the data received from the server, this could be structured as follows

<invoices>  
    <request>true</request>  
    <userdata name="totalinvoice"> 240.00 </userdata>  
    <userdata name="tax"> 40.00</userdata>
    ... 
    <result>  
      <row>  
        <cell>data1</cell>
        <cell>data2</cell>
        <cell>data3</cell>
        <cell>data4</cell>
        <cell>data5</cell>
        <cell>data6</cell>
      </row>
      ... 
    </result> 
</invoices>

If using json data, the definition might look like this:

jsonReader: {
  ...
  userdata: "userdata",
  ...
}

and the data received, like this:

{ 
  total: "xxx", 
  page: "yyy", 
  records: "zzz", 
  userdata: {totalinvoice:240.00, tax:40.00}, 
  rows : [ 
    {id:"1", cell:["cell11", "cell12", "cell13"]}, 
    {id:"2", cell:["cell21", "cell22", "cell23"]}, 
    ... 
  ] 
}

When this data has been received, this information is stored in the userData array of the options array. Whichever format the data comes in, in this case we would have:

userData = {totalinvoice:240.00, tax:40.00}

The data can be accessed using a getGridParam method. To do that we need to request this data:

jQuery("grid_id").jqGrid('getGridParam', 'userData')

and using the old API (not preferr)

jQuery("grid_id").getGridParam('userData')

Discussion

Gordon Frobenius, 2011/07/21 18:51

I am using jqgrid with ColdFusion, and it works great. Just have one issue I can't seem to figure out. I'm using the “Prefix serialized JSON with” setting in ColdFusion. (See http://help.adobe.com/en_US/ColdFusion/9.0/CFMLRef/WSc3ff6d0ea77859461172e0811cbec22c24-750b.html the secureJSON and secureJSONPrefix options) Here's another a link that talks about it http://www.petefreitag.com/item/720.cfm.

It basically just adds some characters to beginning of the JSON string that is sent back like this… {“rows”:[{“cell”:[””,10000228637555,”ACSN”,”444657#002”,””,”OPEN”,”GFHGVKJLM”],”ID”:10000228637555},{“cell”:[etc….. Notice the leading ””. My question is, is there a way I can manipulate the response before it tries to act on it so I do not receive parseerror?

Thank you. gordon@psasys.com.

Gordon Frobenius, 2011/07/21 18:53

My last post had some characters stripped out for some reason. Before the JSON string there are two leading forward slashes. I need to be able to remove those before jqgrid trys to render the grid.

Jeremy, 2011/12/20 12:59

Great work!!! 10k likes! You described alot on the format of JSON data. However how can i send an empty json data; or rather how i can i format my json data so that jqGrid Json reader knows that there's no data.

And, i noticed on the GET['rows'] is set to 20 (by default); does it i can only send a maximum of 20 records?

How can i configure the options to set my grid to be able to receive any number of records, without pager and only vertical scrollbar?

Cheers Mate! Many thanks! And You Better Watch OUT!!! Cause Santa Claus is coming to town….. MERRY XMAS!

Jeremy, 2011/12/20 12:59

Great work!!! 10k likes! You described alot on the format of JSON data. However how can i send an empty json data; or rather how i can i format my json data so that jqGrid Json reader knows that there's no data.

And, i noticed on the GET['rows'] is set to 20 (by default); does it i can only send a maximum of 20 records?

How can i configure the options to set my grid to be able to receive any number of records, without pager and only vertical scrollbar?

Cheers Mate! Many thanks! And You Better Watch OUT!!! Cause Santa Claus is coming to town….. MERRY XMAS!

Steve 'Cutter' Blades, 2012/01/03 19:38

When creating a function datatype, it is often necessary to use function accessors for defining the root, page, total and records attributes within one's jsonReader configuration. This is great, because often the location of this information is in the incoming data, and not always easily defined. Programmatic reference is the better option here.

I believe the same to be true for id. I've recently been writing a series on using jqGrid, and I am using ColdFusion on the backend. ColdFusion's json serialization of it's native query object is a bit different than the 'standard' json recordset structure, trimming the overall bit traffic by not repeating the column names with each and every record. This is a perfect example for using the function datatype, until you start working with the multiselect grid option. When working with multiselect it becomes very important that the grid knows which column holds the record's unique ID value.

There are two issues at play here. First, jqGrid does not allow a function accessor for the reader's id attribute. Second, ColdFusion does not allow one to control the column order in it's native query return. I believe I have found a very easy solution to this.

Lines 1272 - 1276, of the grid.base.js, currently read like this:

if( ts.p.keyIndex===false ) {
	idn = dReader.id;
} else {
	idn = ts.p.keyIndex;
}

If this can be changed to the following, then it can still be used in it's traditional manner, as well as allowing for a function accessor definition:

if( ts.p.keyIndex===false ) {
	idn = $.jgrid.getAccessor(data,dReader.id);
} else {
	idn = ts.p.keyIndex;
}

This will allow either of these options within a jsonReader config:

jsonReader: {
	id: "ID",
	// ...
	id: function(obj){return $.inArray("ID",obj.data.COLUMNS);},
	// ...
},

This appears to be a minor change, and I hope that it can make it into a future version of the jqGrid code.


;