Subgrid

There are times when we need to be able to easily display (or edit) records that are the children of a selected record in the parent grid. We would, of course, want to show only those records that are the children of the selected record in the grid, never the children of all records.

jqGrid offers two ways of handling child records:

• a subGrid
• a grid as a subGrid

In order to use this module you should mark the Subgrid when you download the grid. For more information refer to Download.
For Developers - this is the grid.subgrid.js in the src directory.

SubGrids use the following properties, events and methods of the parent grid - i.e. you should set these properties in the grid options

In order to configure the subgrid you will need to configure the subgrid item in xmlReader or jsonReader. The default setting for these are:

xmlReader : {
...
   subgrid: {
      root: "rows", 
      row: "row", 
      repeatitems: true, 
      cell: "cell"
   }
}

and a jsonReader

jsonReader : {
...
   subgrid: {
      root: "rows", 
      repeatitems: true, 
      cell: "cell"
   }
}

The mapping rules are the same as those in the basic grid. For more information refer to Retrieving Data.

In order to use correct subGridType as service below is a simple code which shows how this can be achieved:

jQuery("#grid_id").jqGrid({
...
   subgridtype: function(rowidprm) {
      jQuery.ajax({
         url:'url_to_the_service',
         data:rowidprm,
         dataType:"json",
         complete: function(jsondata,stat){
            if(stat=="success") {
               var thegrid = jQuery("#grid_id")[0];
               thegrid.subGridJson(eval("("+jsondata.responseText+")"),rowidprm.id);
            }
         }
      });
   },subgrid
...
});

Where rowidprm is array that contains the id of the row plus other parameters as required to set subGridModel parameters and subGridJson is a method which is described below.

In these events,

• pID is the unique id of the div element where we can put contents when subgrid is enabled,
• id is the id of the row
• sPostData - the data which is posted when a subgrid request is made

Continuing to use the example from the tutorial, let's suppose that there is a need to display the line items for each invoice in a subgrid. The Java script code should look like this.

<script type="text/javascript">
jQuery(document).ready(function(){ 
  jQuery("#list").jqGrid({
    url:'example.php',
    datatype: 'xml',
    mtype: 'GET',
    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',
    subGrid: true,
    subGridUrl : "subgrid.php",
    subGridModel : [ 
      {
      name  : ['No', 'Item', 'Qty', 'Unit', 'Line Total'],
      width : [55, 200, 80, 80, 80],
      align : ['left','left','right','right','right'],
      params: ['invdate'] 
      }
    ]
  }); 
}); 
</script>

The next step is to configure the subgrid.php file. The example is in PHP and MySQL.
We suppose that the table name that contain the invoice item data has name invlines and has the following names: invid, item_num, item, qty, unit

subgrid
<?php
// get the id passed automatically to the request
$id = $_GET['id']; 
// get the invoice date passed to this request via params array in
//subGridModel. We do not use it here - this is only demostration
$date_inv = $_GET['invdate'];
 
		suboptions = {
			plusicon : "ui-icon-plus",
			minusicon : "ui-icon-minus",
			openicon: "ui-icon-carat-1-sw",
			expandOnLoad:  false,
			delayOnLoad : 50,
			selectOnExpand : false,
			reloadOnExpand : true
		};
 
// connect to the database 
$db = mysql_connect($dbhost, $dbuser, $dbpassword) or die("Connection Error: " . mysql_error()); 
 
mysql_select_db($database) or die("Error conecting to db."); 
 
// construct the query		suboptions = {
			plusicon : "ui-icon-plus",
			minusicon : "ui-icon-minus",
			openicon: "ui-icon-carat-1-sw",
			expandOnLoad:  false,
			delayOnLoad : 50,
			selectOnExpand : false,
			reloadOnExpand : true
		};
 
$SQL = "SELECT item_num, item, qty, unit FROM invlines WHERE invid=".$id." ORDER BY item"; 
$result = mysql_query( $SQL ) or die("Couldn?t execute query.".mysql_error()); 
 
// set the header information
if ( stristr($_SERVER["HTTP_ACCEPT"],"application/xhtml+xml") ) { 
            header("Content-type: application/xhtml+xml;charset=utf-8"); 
} else { 
            header("Content-type: text/xml;charset=utf-8"); 
} 
 
echo "<?xml version='1.0' encoding='utf-8'?>"; 
echo "<rows>"; 
// be sure to put text data in CDATA 
while($row = mysql_fetch_array($result,MYSQL_ASSOC)) { 
            echo "<row>"; 
            echo "<cell>". $row[item_num]."</cell>"; 
            echo "<cell><![CDATA[". $row[item]."]]></cell>"; 
            echo "<cell>". $row[qty]."</cell>"; 
            echo "<cell>". $row[unit]."</cell>"; 
            echo "<cell>". number_format($row[qty]*$row[unit],2,'.',' ')."</cell>"; 
            echo "</row>"; 
} 
echo "</rows>";
 
?>

A subGrid can be enabled (or disabled) dynamically (to respond to changes in the data in the main grid, for example).
To disable subgrid :

jQuery("#grid_id").hideCol('subgrid');

To enable subgrid

jQuery("#grid_id").showCol('subgrid');

Where

• grid_id is to be replaced by the name of your grid, but
• subgrid is a keyword, not to be replaced

To make this work, subGrid must be initially set to true in the jqGrid properties; only then can we enable and disable it using the code above.