Spry dynamic region overview and structure

After you’ve created a Spry data set, you can display the data in a Spry dynamic region. A Spry dynamic region is an area on a web page that displays dynamic data from a data set, and uses HTML code to display the data so that you can easily style it. The dynamic region is bound to one or more data sets. The region also automatically updates whenever the data set is modified.

Note: You should be familiar with Spry data sets and how they work before proceding. For more information, see Working with Spry data sets.

Dynamic regions regenerate because they register themselves as observers or listeners of the data sets to which they are bound. Whenever data in any of these data sets is modified (loaded, updated, sorted, filtered, and so on), the data sets send notifications to all of their observers, triggering an automatic regeneration by the “listening” dynamic regions.

To declare a Spry dynamic region in a container tag, you use the spry:region attribute. Most HTML elements can act as dynamic-region containers, however, the following tags cannot be used:

col
colgroup
frameset
html
iframe
select
style
table
tbody
tfoot
thead
title
tr

While you cannot use any of the preceding HTML elements as Spry dynamic region containers, you can use some of them inside Spry dynamic-region containers.

Note: Dynamic regions are limited to regions within the body tag. You can't add the spry:region attribute to any tag that is outside the body tag.

In the following example, a container for a dynamic region called Specials_DIV is created using a div tag that includes a standard HTML table. Tables are typical HTML elements used for dynamic regions because the first row of the table can contain headings, and the second row can contain repeated data.

<!--Create the Spry dynamic region-->
<div id="Specials_DIV" spry:region="dsSpecials">
	<!--Display the data in a table-->
	<table id="Specials_Table">
		<tr>
			<th>Item</th>
			<th>Description</th>
			<th>Price</th>
		</tr>
		<tr spry:repeat="dsSpecials">
			<td>{item}</td>
			<td>{description}</td>
			<td>{price}</td>
		</tr>
	</table>
</div>

In the example, the div tag that creates the container for the dynamic region needs only two attributes: a spry:region attribute that declares the dynamic region and specifies the data set to use in it, and an id attribute that names the region:

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

The new region is an observer of the dsSpecials data set. Any time the dsSpecials data set changes, the new dynamic region regenerates itself with the updated data.

An HTML table displays the data:

<table id="Specials_Table">
	<tr>			
		<th>Item</th>
		<th>Description</th>	
		<th>Price</th>		
	</tr>		
	<tr spry:repeat="dsSpecials">	
		<td>{item}</td>			
		<td>{description}</td>			
		<td>{price}</td>	
	</tr>	
</table>

The values in curly braces in the second row of the table—the data references—specify some of the columns in the data set. The data references bind the table cells to the data in the specific columns of the data set. Because data—especially XML data—often includes repeating nodes, the example also declares a spry:repeat attribute in the second table row tag. This causes all of the rows in the data set to appear when the user loads the page (instead of just the data set’s current row).

It should be noted that Spry region attributes do not validate against the standard W3C (X)HTML validator. You must use a custom Spry DTD to validate Spry regions. For more information, see Validating Spry pages.