Spry

Spry HTML data set basic overview

The Spry HTML data set lets you use standard HTML tables and other structured HTML code as a data source. HTML data sets work the same way as XML data sets, creating a kind of virtual holding container, or table, when you create the data set. The advantage of using an HTML table as a data source is that it is already structured with rows and columns, and is easy to read and use.

Optional sorting, caching, distinct, and load-interval parameters used with XML data sets also work in a similar way with HTML data sets.

Note: HTML datasets work best with relatively small amounts of data. A large number of rows in the data source can negatively affect performance.

if you’re dealing with 100s of rows it’s probably best use a database. Otherwise, you’re going to start having *runtime* performance issues in the browser (we may be able to make some improvements here but there is definitely a limit to what we can do

The following example shows a page, datatable.html, that contains the HTML table that this discussion uses as a sample data source:

<table id="datatable1" width="532" border="1" >
  <tr>
    <th>first name</th>
    <th>last name</th>
    <th>username</th>
    <th>phone</th>
  </tr>
  <tr>
    <td>Kirk</td>
    <td>Davis</td>
    <td>kdavis</td>
    <td>(415) 333-4334</td>
  </tr>
  <tr>
    <td>James</td>
    <td>Miller</td>
    <td>jmiller</td>
    <td>(415) 333-7566</td>
  </tr>
  <tr>
    <td>Alex</td>
    <td>Wilson</td>
    <td>awilson</td>
    <td>(415) 333-9843</td>
  </tr>
  <tr>
    <td>Albert</td>
    <td>Moore</td>
    <td>amoore</td>
    <td>(415) 333-7584</td>
  </tr>
</table>

The page is not a full HTML page, but rather an HTML fragment. HTML datasets can load either full HTML pages or HTML fragments.

Notice that the table has the ID “datatable1”. When Spry creates the data set, it uses this ID to identify the table as the data source.

On the page that displays the data, a few snippets of code creates the HTML data set. The following example shows an HTML data set called ds1:

<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<title>Spry Example</title>
	<!--Link the Spry libraries-->
	<script type="text/javascript" src="includes/SpryData.js"></script>
	<script type="text/javascript" src="includes/SpryHTMLDataSet.js"></script>
	<!--Create a data set object-->
	<script type="text/javascript">
		var ds1 = new Spry.Data.HTMLDataSet("datatable.html", "datatable1");
	</script>
</head>
. . .
<body>
</body>

The data set loads data from the table with the ID “datatable1”. The identified table resides in the source file, datatable.html.

Note: The examples in this document are for reading purposes only and not intended for execution. For working samples, see the demos folder in the Spry folder on Adobe Labs.

In this example, the first script block links the SpryData.js data library, which is stored in a folder called includes on the server:

<script type="text/javascript" src="includes/SpryData.js"></script>

The second script tag links to the SpryHTMLDataSet.js file, which is also stored in a folder called includes on the server. This file lets you specify HTML tables (and other properly structured code) as your data source:

<script type="text/javascript" src="includes/SpryHTMLDataSet.js"></script>
Note: You do not need to attach the XPath.js file; it is used only for XML data sets.

The third script block contains the statement that creates the ds1 data set:

<script type=”text/javascript”>
var ds1 = new Spry.Data.HTMLDataSet("datatable.html", "datatable1");
</script>
Note: HTML data sets are case sensitive, so make sure that the scripts, files names, and table IDs you specify are capitalized (or not capitalized) appropriately.

In JavaScript the new operator is used to create objects. The Spry.Data.HTMLDataSet() method is a constructor in the Spry data library that creates new HTML data set objects. The constructor takes two parameters: the location of the data ("dataset.html", in this case, a URL relative to the page) and an identified data source that specifies where the data will come from ("datatable1").

Each data set maintains the notion of a current row. By default, the current row is set to the first row in the data set. (In an HTML table, this is not the header row, but the first row of the table that contains actual data.) Later, you can change the current row programmatically by calling the setCurrentRow() method on the data set object.

Note: The data set contains no data after you've created it with the new JavaScript operator. To load data into the dataset immediately, call the data set's loadData() method, which executes a request to load the HTML data. Spry regions and detail regions do this automatically for the data sets they depend on, but if you are not using one of these regions, call the loadData() method manually in your page code. This loading is asynchronous, so the data might still be unavailable if you try to access it immediately after calling loadData().

Example

<script type="text/javascript">
	var dsSpecials = new Spry.Data.HTMLDataSet (....);
	dsSpecials.loadData();
</script>

Variation on tags used for data set structure

In the preceding examples, a common table structure is used to store the information for the data set:

<table id="datatable1">
	<tr>
		<td>
		<td>

This three-level structure (with the third level repeating) is essential for the HTML data set to work properly; the structure, however, is more important than the actual tags you decide to use. Spry reads the structure (not table tags necessarily) and creates the data set accordingly. As long as the three-level structure is in place, you can use any grouping of HTML tags to create the data set:

<div id=”datadiv1”>
	<ul> 
		<li> 
		<li>

Here’s another example:

<div id=”datadiv1”>
	<div> 
		<span> 
		<span>