Creating dynamic tables with the Spry framework

Additional Requirements

Spry Prerelease 1.4

• Download Spry Prerelease 1.4

Optional: Dreamweaver CS3

• Try
• Buy

This tutorial provides an overview of how the Spry framework works. To make the overview applicable to a real-world application, we’ll be building a small project that uses HTML and XML files. The instructions and sample files for this tutorial are designed to illustrate the process of converting an HTML table containing static data to a page that uses the Spry framework to load data dynamically. The completed project will display two different sets of data within a table that adjusts the number of rows based on the data being displayed.

To see a working example of the completed files online, visit the Static Table Sample page.

Now we’re ready to get started. First, let’s review the table we'll be working with, so we have a clear understanding of how we want the data to display:

Examining the existing HTML code

To begin our conversion process, the first thing we’ll do is review how the HTML markup displays the static table data. If you’ve downloaded the sample files for this tutorial, open up the file basic_table.html and review the code using Dreamweaver. The markup for the static HTML page containing the table looks like this:

The HTML code displayed above is the initial markup of our static table. It is important to review the table structure first, so that we can set up the same formatting dynamically. Now that we’ve reviewed the HTML, we can proceed to the next step—connecting external data to an HTML page.

Pages that display external, (rather than embedded) data are much easier to maintain. By separating the functionality from the data, you will find that your site files are much easier to update, especially if the content on the pages changes often. In this section of the tutorial we’ll extract the data from an XML file so that we can load the data dynamically through the browser. If you’ve downloaded the sample files, open the XML file named employees-01.xml and review the code using Dreamweaver. The structured data in the XML file looks like this:

The code above contains the tags that surround the data from our static HTML table in an XML format. At this point, you may find it useful to toggle back and forth between the files using the Dreamweaver Code window, or open two browser windows with this tutorial so you can compare the HTML and XML code examples side by side. As you review the HTML, you’ll see the markup tags that define each table element surrounding the static data.

When you review the XML, you’ll see that the tags surrounding each piece of data are broken into nodes, surrounding by <employee> tags. Each of the <employee> nodes contains all of the relevant data pertaining to a specific employee. The tags surrounding each data item have names that refer to the data being stored, and the information is structured in a manner so that the employee’s last name, first name, phone number and user names are all listed in the same order within each node. It is also important to notice that each employee’s ID number is an attribute assigned to the <employee> tag itself.

The names of the tags and attributes you choose to use when creating your own XML file is up to you. However, it is critical that all of the data in your XML file—for each row of the original table—is structured the same way, and that each corresponding data item exists at the same level of the XML tag structure. When designing your own XML file, you may wish to create just one node that contains each of the lines of data, and then copy / paste that node repeatedly to ensure that the structure remains the same, before updating each node with its own unique set of data.

Now that we’ve reviewed both the HTML file and the data in the XML file, we'll need to modify our original HTML file so that it can find the XML file.

Additionally, since we no longer need all of the static data in the table, the code has been updated to remove all but one row of static data—which we'll be using later on.

Adding links to the data framework

Using Dreamweaver, update the HTML page by typing the highlighted code in the example below. By adding these lines of code, we are adding links to include the JavaScript files that define our data framework. Also delete the extra <tr> tags after the first two, so that only one set of "header information" and one set of "employee data" remain, as shown below:

Defining the data set to load external data

In the previous step, we added links to include the xpath.js and SpryData.js files. This is critical, because if we do not add this code to the HTML page, we cannot use the data framework.

Next, we'll add some JavaScript to define a data set that can load our data. Using Dreamweaver, add the highlighted code from the example below:

Let’s take a look at what we’ve added to our file so far. We’ve basically added three new areas of <script> tags: a link to xpath.js, a link to SpryData.js and a link that defines the location of our data set via a link to the employees-01.xml file. Make sure your HTML file contains these three sections inside the <head> portion of the HTML. Without adding these links, the upcoming steps of this tutorial will not work because the HTML page will be unable to find the data.

In the previous section of this tutorial, we added a few critical lines of code to the HTML page to create a new XMLDataSet object. We also assigned some additional arguments within the parenthesis. Let’s review this code by itself for a moment, so that we can examine exactly what is being defined and how this works:

The script tag itself is nothing new—You’ve seen it many times before, because the same syntax is often used to link external files that are relevant to an HTML page.

Let’s focus on the highlighted code within the <script> tags. This is the interesting part. In this line of code we are creating an XMLDataSet by using the JavaScript 'new' keyword.

In the example above, we’ve created a Spry.Data.XMLDataSet object named "dsEmployees". The first argument passed to the XMLDataSet constructor is the URL to the data you want to load. For the purposes of this tutorial, we are using a relative URL path to our XML file named "employees-01.xml", but it is important to note that this first argument could also be a fully qualified or relative URL to some web service/application within your domain that requires URL arguments. The path that you define to the data (as the first argument) doesn't have to be a static XML file.

The second argument passed to the XMLDataSet constructor is an XPath expression. The XPath describes where the data you are interested in displaying exists within the XML structure. In this example, when you review our XML data, all of our data exists in the "employee" node, so the result of our XPath expression "employees/employee" is the set of XML employee nodes. This will allow the HTML page to connect correctly with the data information stored in the XML file.

Since data sets are tabular, the data in each of the employee nodes is flattened, producing an array of objects (rows) whose properties (columns) are the names of the tags or attributes. If you think of these concepts (array of objects=rows and properties of each data set=columns) while reviewing the first version of the HTML (basic_table.html) and then comparing that with the data written as key-value pairs as shown below, you’ll see the relationship between the sets of data, and the values assigned to each property:

In the example above, the "keys" are the items that appear in front of each colon, and the corresponding "value" for each key is listed directly after, like this:

"key" : "value"

Commas separate each of the key-value pairs, and curly braces surround each unique node of data (for each employee). The entire data set is surrounded by square brackets. This is the correct syntax, and it is important to note how the structure of the individual key-value pairs remains consistent in regards to the order they are listed. (In other words, within each set of curly braces, the keys are always listed in this order: id, lastname, firstname, phone, and username).

After studying this structure, you can see how you could visualize the code structure shown above could be converted into a table format that looks something like this:

Using the "@" character to identify attribute data

Attributes on tags are prefixed with an "@" character. The "@" character is a way of designating that the text following the @ is an attribute of a node of data. In the example above, we have a column named "@id" which represents the "id" attribute that exists on the <employee> tag in the XML file.

To explain this another way, if the <firstname> tag in the XML file had a nickname attribute assigned as "Eddie," like this:

<firstname nickname="Eddie">Edward</firstname>

Then if we were only displaying the single line of data, the table would contain two columns: one with a header named "firstname" with a value of "Edward" and another column named "firstname/@nickname" with a value of "Eddie," like this:

In the next section of this tutorial, we’ll create a dynamic region so that the data can be pulled in from an external XML file and will populate the table cells.

After defining our data set and reviewing the structure of our XML data, we are ready to set the table into a dynamic region. Dynamic regions are very powerful, because an area of the HTML page that is set as a dynamic region has the ability to automatically regenerate itself whenever the data in the data set is loaded or changed.

To set up the dynamic regions within our HTML, we first need to wrap our table with a <div> tag. Update your HTML page using Dreamweaver, to add the code highlighted below:

The placement of the <div> tags is important. In this example, the opening <div> tag appears immediately following the <body> tag, and the closing <div> is placed immediately before the closing </body> tag. This placement of the <div> means that everything within the <body> tags (that is, everything that is visible when the browser displays the HTML page) exists within the <div> tag that is named "dsEmployees."

In the code above, we’re using a "spry:region" attribute on the <div> tag to convert markup on the static HTML page into a dynamic region.

Understanding the "spry:region" attribute

By adding a "spry:region" attribute to the <div> tag that surrounds the content, we are specifying to the data framework that the contents of the <div> tag should be treated as a dynamic region. The value of the "spry:region" attribute is "dsEmployees" which alerts the framework that this dynamic region is bound to data that exists in the "dsEmployees" data set. Setting the "spry:region" and binding the data also directs the framework to regenerate this portion of the page anytime the data in "dsEmployees" is changed.

If the dynamic region is bound to more than one data set, you would simply list the data set names, separated by spaces, as the value of the "spry:region" attribute. Here’s an example of a <div> tag with an attribute of "spry:region" that is bound to three data sets:

In the example above, notice that the data set names do not have a comma separating them, and that all of the data set names are enclosed within a single set of double quotes.

Now that we have defined our dynamic region within the HTML page, we can insert data from our data set into the region. This is accomplished by using data references, which are written using this syntax:

Modify your HTML file using Dreamweaver, replacing the hard coded values within the second group of <tr> so that each <td> displays data referenced from the XML file, rather than the static values embedded in the table cells. Update the values within the <td> tags, as shown in the highlighted code below:

In the example above, we’ve just added data references within our second row of the table, which will insert the data from the specified data set. Within each <td> tag, we are formally specifying that we wish to retrieve data from the dsEmployees data set, and then we are specifying the key that should be accessed, so that its corresponding value will be displayed within each table cell in that row.

In the previous section of this tutorial, we set up an area of the HTML page as a dynamic region, specified which data set to use, and then added data references in the locations within the HTML where we want our data to appear (in the table cells).

At this point, it is important to point out that if the dynamic region is only bound to one data set, you can leave off the data set name in the data reference. In other words, instead of formally specifying the data set named dsEmployees, like this:

We can instead use the "shorthand" method for specifying data references, like this:

The <div> tag that defines the dynamic region already references the data set "dsEmployees" so it is not necessary to repeat the data set name reference in your code if there is only one data set being used.

Modify your HTML file using Dreamweaver, updating the highlighted code as shown below:

In the example above, the references for data (the code within the curly braces) illustrate how you can leave out the data set name in a data reference if the region is only bound to a single data set. If you use the shorthand references for data, your code will be cleaner and easier to read.

After following the steps in the previous sections of this tutorial, it is time to take a step back and see how our recent code modifications to the HTML file allow the external data to load within the table cells.

If you view your modified HTML page in a browser, you should see the following table displayed, which is pulling in the first node of employee data from our specified data set into the second row of cells in the table:

Every data set understands the concept of a current row. By default, the current row is set to zero. In the code example from the previous section of this tutorial, the data framework replaced our data references with the values in the current row of the "dsEmployees" data set. Since these are the first values encountered by the browser in the XML file (referenced by the HTML page) these values are displayed in the table cells.

Since we have more than one set of values within our defined data set, we need to use a strategy that will allow us to keep gathering the data in our data set and display each set of values in its own row of the table. Our goal here is to construct a looping mechanism that will cause the code to continually re-iterate through the rows in our data set, and will display all of the data in our data set in subsequent table rows (until there is no more data to be displayed).

In order to accomplish this, we’ll need to specify that we want the framework to loop through the data using the "spry:repeat" attribute. Here’s how this works:

We’ll designate that we want the data framework to iterate over the rows of our data set by specifying a "spry:repeat" attribute on the node we want to repeat for each row in the data set. Set the value of the "spry:repeat" attribute to the name of the data set you want to iterate over, by adding the highlighted code below into the second <tr> tag:

In the modification above, we’ve added the "spry:repeat" to attribute to the <tr> tag that contains the row that will be displaying our dynamic data. By adding the "spry:repeat" attribute, we are telling the data framework to repeatedly review each node of data for an element and then display its contents for every row of a data set. By looping through the data, you can dynamically generate the data for the entire data set, and the table will automatically generate as many table rows as needed to display each element of external data.

View your modified HTML file in a browser to see the table display with looping specified for the dsEmployees data set. Your code should look like this:

The static HTML content has now successfully been converted into a dynamic table that can load external data! This is very exciting; especially when you consider that the content of the HTML page can now be updated by simply modifying the URL used by the data set. Even more functionality can be imagined if the XML file was dynamically generated using a web service, rather than referencing static XML file. With the HTML formatting separated from the content, you can ensure consistent formatting across site pages.

This separation could even be taken a step further, by using an external CSS style sheet to format the HTML page’s layout and set the text formatting. To learn more about working with CSS to design your HTML pages, visit the CSS Topic Center within the Dreamweaver Developer Center.

Before we conclude, let's take this tutorial one step further. In this next section, we’ll add the ability to sort the items in the table—based on a mouse click on a specific column header. To accomplish this, we’ll add a "spry:sort" attribute to each column header in the table.

Modify your HTML file using Dreamweaver, updating the highlighted code as shown below:

In the code example above, we’re using the sort() method to sort the data in a data set. Any regions bound to the data set will automatically regenerate themselves.

The sort method on the "dsEmployees" data set takes the name of the data set column and uses that name to perform its sorting operation. Sorting causes the order of the data in the data set to change. This means that every time sorting is invoked, the dynamic region automatically regenerates itself to reflect the new ordering of the data. To see how this works, view your HTML file in a browser, then click on any of the column headers to see the data dynamically display in a new order.

Using loadData to load data from external files

Aside from sorting, we can also completely change the data being displayed by simply changing the URL on the data set and telling the framework to reload its data. Modify your HTML file using Dreamweaver, adding the highlighted code as shown below:

In the code example above, we are loading in new data by changing the URL on the data set and calling the loadData() function within the selection menu tag.

When you preview your HTML file with the code above in a browser, you can use the select form menu element to switch between loading two different sets of data. As you select each item from the menu, the data dynamically updates to display the values of each data set.

To see a working example of the completed files online, visit the Static Table Sample page.

After completing this tutorial you’ve seen that by adding just a few lines of JavaScript, you can convert your static HTML table page into a dynamic document that can load and display data from any number of external XML files. As you continue with your experimentation, keep in mind that you can turn almost any HTML element on a page into a dynamic region. The possibilities are limited only by your imagination. To begin exploring further, take a look at the demos that are distributed with the Spry framework. After defining dynamic regions and linking to external data files, you’ll begin to get an idea of just how flexible it is.

Spry framework resources

To get an overview of the Spry framework technology, read Logged In: Introducing the Spry framework for Ajax. To learn more about working with dynamic regions, see the Developer Center article: Building a photo album with the Spry framework. Read up on working with data, effects and widgets in the Spry Documentation. Visit the Spry framework for Ajax (Prerelease) Forum to discuss development issues with the online community and learn tips from other developers. Also, be sure to check out the newest information at the Spry framework home page on Adobe Labs.