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 (…)

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

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" 
      } 
   },
...
});

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.

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.

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

• 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 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:

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"},
      ...
  ]
}

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.

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"} 
    ] 
}

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

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

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>

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')