Spry basic master and detail region overview and structure

When working with Spry data sets, you can create master and detail dynamic regions to display more detail about your data. One region on the page (the master), drives the display of the data in another region on the page (the detail).

Typically, the master region displays an abbreviated form of a set of records from the data set, and the detail region displays more information about a selected record. Because the detail region depends on the master region, any time the data in the master region changes, the data in the detail region changes as well.

Note: This section covers basic master and detail relationships where both regions are dependent on the same data set. For information on master and detail regions that use more than one data set, see Spry advanced master/detail region overview and structure.

In the following example, a master dynamic region displays general data from the dsSpecials data set, and a detail dynamic region displays more detail about the row of data that’s been selected in the master region:

<head>
. . .
<script type="text/javascript" src="../includes/xpath.js"></script>
<script type="text/javascript" src="../includes/SpryData.js"></script>
<script type="text/javascript">
	var dsSpecials = new Spry.Data.XMLDataSet("data/cafetownsend.xml", "specials/menu_item");
</script>
</head>
. . .
<body>
<!--Create a master dynamic region-->	
<div id="Specials_DIV" spry:region="dsSpecials">
	<table id="Specials_Table">
		<tr>	
			<th>Item</th>	
			<th>Description</th>
			<th>Price</th>
		</tr>
		<!--User clicks to reset the current row in the data set-->
		<tr spry:repeat="dsSpecials" spry:setrow="dsSpecials">
			<td>{item}</td>				
			<td>{description}</td>
			<td>{price}</td>	
		</tr>
	</table>
</div>
<!--Create the detail dynamic region-->
<div id="Specials_Detail_DIV" spry:detailregion="dsSpecials">
	<table id="Specials_Detail_Table">
		<tr>	
			<th>Ingredients</th>
			<th>Calories</th>
		</tr>	
		<tr>	
			<td>{ingredients}</td>
			<td>{calories}</td>
		</tr>
	</table>
</div>
. . .
</body>

Note: The source data for this example is similar to the XML file in Spry XML Data Set basic overview, but that example does not contain nodes for ingredients or calories. The ingredients and calories nodes have been added to the data set for this example.

In the example, the first div tag contains the id and spry:region attributes that create a container for the master dynamic region:

<div id="Specials_DIV" spry:region="dsSpecials">

The first table-row tag of the master region contains a spry:setrow attribute that sets the value of the current row in the data set when the user clicks the row.

<tr spry:repeat="dsSpecials" spry:setrow="dsSpecials">

The second div tag contains the attributes that create a container for the detail dynamic region:

<div id="Specials_Detail_DIV" spry:detailregion="dsSpecials">

Every Spry data set maintains the notion of a current row. By default, the current row is set to the first row in the data set. A spry:detailregion works in exactly the same way as a spry:region except that when the data set’s current row changes, the detail region updates automatically.

The data references in the detail region ({ingredients} and {calories}) display data from the data set’s current row. When a user clicks a row in the master region table, the spry:setrow attribute changes the current row in the data set to the row the user selected.

The {ds_RowID} data reference is a built-in part of the Spry framework that points to an automatically generated unique ID for each row in the data set. (See Data reference options.) When the user selects a row in the master region table, the spry:setrow attribute supplies the unique ID to the setCurrentRow method, which sets the current row in the data set.

Whenever the data set is modified, all dynamic regions bound to that data set regenerate themselves and display the updated data. Because the detail region, like the master region, is an observer of the dsSpecials data set, it also changes as a result of the modification, and displays data related to the row the user selected (the new current row).

The difference between a spry:region and a spry:detailregion is that the spry:detailregion specifically listens for CurrentRowChange notifications (in addition to DataChanged notifications) from the data set, and updates itself when it receives one. Normal spry:regions, on the other hand, ignore the CurrentRowChange notification, and only update when they receive a DataChanged notification from the data set.