Exchanging data using the Spry framework for Ajax and PHP

Additional Requirements

• Define a Dreamweaver site with a testing server or remote server running Apache 1.3 (or later), MySQL 3.23 (or later), and PHP 4 (or later). Other servers might also work, but have not been tested.
• Make this PHP configuration setting: allow_url_fopen = on
• Install phpMyAdmin (or a similar MySQL administration tool) to import the provided articles.sql file, which will add the table adobe_xml_imagelist to your existing database.
• Optional: When enabling the script's Generate Static XML Files option, set write permission (e.g., 755) for the script's base folder on the remote server.

This tutorial describes a rather uncommon, yet sensible approach to exchanging data between PHP and the Spry framework for Ajax. Both the tutorial and the ready-to-use demo application address the following functionality:

• Making your Spry-enhanced Dreamweaver page tell a PHP script to generate an image list from a specified directory. The path to your desired image subdirectory can be an arbitrary sequence of static parameters (e.g., "foldername") or dynamic parameters (e.g., values derived from a recordset)—a flexible solution for adding a Spry-based "show related images" feature to your content management system (CMS).
• Simultaneously passing back the evaluated information to the very same Spry page as on-the-fly XML data in order to have a Spry table build an image list from the specified directory, and also providing a variety of sortable critera, such as image-related data (URL, width, and height) and file-related data (name, date, and extension).
• Simultaneously, but optionally, creating a static XML file containing all the current nodes and values.

Figure 1 shows the related images ordered by ID and Figure 2 shows the images ordered by image. In the finished application, you will be able to click the Spry table's headers to change the sorting criteria

This tutorial is based on a fictious content management system (CMS) named "articles", where all images are stored in a common directory named "images" and each recordset has its related array of images stored in a unique subdirectory named after the recordset's article_id. For example, the first recordset (article_id 1) will store its related images in the subdirectory "1" (see Figure 3).

Installing the sample files

Create a new folder named adobe_xml_imagelist in your site's root and unpack the contents of the provided archive in this directory (adobe_xml_imagelist.zip). These sample files are linked to at the beginning of this tutorial. If they are installed correctly, the resulting directory and file structure should appear as in Figure 4.

Setting up the database table

The related MySQL table named adobe_xml_imagelist is really simple and has the following structure:

For your convenience, the file articles.sql (located in the "sql" subdirectory in the sample files) can be used for adding this new table to your database plus inserting two related dummy records. When working with phpMyAdmin or another database administration tool, just use the import feature to, well, import this file. Otherwise, copy and paste the code from the articles.sql file into phpMyAdmin's "SQL" field.

Establishing a new MySQL Connection

Because several sample files, such as article_list.php and article_detail_dynamic_xml.php, are already preconfigured to query the adobe_xml_imagelist table and display the existing records including their related images, you need to create a new MySQL Connection named xml_imagelist.

Configuring the application

The following instructions will, by design, not be covering every single configuration option. I would first like to run the preconfigured, ready-to-use sample application on your local testing server without worrying about initially nonessential details. I address these in the "Information for developers" section at the end of this tutorial.

Open the file xml_imagelist_servername_inc.php (located in the "scripts" directory) and change the default value of the following variable:

You will need to update the value of this variable according to your testings server's "URL prefix" settings, as defined in your Dreamweaver site's site definition (see the Testing Server category of your site definition).

Testing the application

Now it's time to test the application:

• Open the file article_list.php in Dreamweaver and preview the page in your browser. This page is nothing to write home about. It's just a simple repeat region, showing the core data of both dummy records (ID, Headline) and a "more..." link that's passing the recordset's article_id to where the fun starts—the article_detail_dynamic_xml.php page.
• The file article_detail_dynamic_xml.php displays the "image list from directory" related to the respective article_id and allows for sorting the Spry table according to the above mentioned image and file data.

  Important: By default this file assumes that the Spry libraries are installed in the <site root>/SpryAssets/ directory. If you install them somewhere else, you'll need to adapt the path manually in lines 47 and 48 (script src="../SpryAssets/xpath.js").

If you're interested in creating your own versions of the provided public pages (article_list.php and article_detail_dynamic_xml.php) and—as a side-effect—if you're eager to learn how to build the required database queries or insert/configure the Spry table, then this section of the tutorial is for you.

Trust me, at least it's interesting reading: Here is where you'll get a clue about the purpose of some previously unmentioned files (article_detail_sample_xml.php and xml_imagelist_testdata.xml) and where you'll be learning some essential details.

Note: Although it is, in theory, possible to save the following pages in any folder within your Dreamweaver site, I suggest saving them in the existing adobe_xml_imagelist directory. Doing so will certainly simplify matters when it comes to checking your file versions against the provided sample files, because the generated code of database queries or links to related files will be similar and, therefore, easier to compare. However, please don't forget to do a "Save As..." on your own productions under a different name.

Creating the article_list.php file

Follow these steps to create the article_list.php file:

1. Select File > New to create a blank page in Dreamweaver. Set the page type as PHP. Because this page will only need to display a simple listing without any fancy advanced layouts, I suggest selecting the "Layout: <none>" option too.
2. Save this page in the adobe_xml_imagelist directory.
3. Optional: If you want, use the Attach Style Sheet command in Dreamweaver's to attach the provided CSS file article_styles.css located in the css subdirectory.
4. Create a recordset that queries the adobe_xml_imagelist table, as shown in Figure 5.

Selecting the table columns article_id and article_headline should be sufficient to build a simple article listing page.

5. To make your page's layout conform with the sample file, insert a centered table with two rows and three columns below your meaningful headline.
6. As the second table row is meant to display the article's "id" and "headline" values, you'll need to add the recordset's related dynamic text to the cells. If it's not already visible, open the Application panel and click the Server Behaviours tab. Next, click the plus (+) button and select the Dynamic Text menu entry to insert the article_id and article_headline placeholders into the respective cell (see Figure 6).

7. The most important page component will be the "more..." link pointing to your detail page, which in turn needs to obtain the respective article_id value in order to display images from the corresponding directory. This means you need to append a parameter to the link target using these steps:
1. Highlight "more..." and click the Property inspector's Browse for File button to select the article_detail_dynamic_xml.php file. Replace this with your own detail page.
2. Click the Parameters button and define the following settings (see Figure 7):
   1. Type article_id in the Name field.
   2. Click the Value field's lightning bolt icon and select the recordset's article_id.
   3. Confirm everything with OK and return to the page.

In order to verify that this link has been correctly parameterized, click the cursor somewhere inside the "more..." link and click your right mouse button (Control-click on Mac) on the related <a> tag visible in the Dreamweaver Tag selector at the bottom of the Design view window. Click the Quick Tag Editor in the contextual menu. The Quick Tag Editor should display the following:

8. Highlight the second table row (the one containing the dynamic text placeholders) in the Dreamweaver tag inspector, click the Server Behaviors tab, and select Repeat Region. Since the adobe_xml_imagelist table just comes with two records, it's up to you which "Show" option to choose.

Creating the article_detail_sample_xml.php file

May I call myself a soothsayer? At this point you'd rather expect me to explain how the article_detail_dynamic_xml.php page can be replicated, but there are two good reasons for elaborating on this page first:

• For building the Spry table, you will need an existing and valid XML file containing some sample data (the provided xml_imagelist_testdata.xml) because the "generate XML on the fly" dynamic file isn't capable of providing the required XML schema. Dreamweaver itself has no web server capabilities and hence cannot process dynamic files, so we'll first need to take this detour.
• Technically speaking, article_detail_dynamic_xml.php is just a spinoff product of this page consisting of just one minor difference: a modified XML source.

For these reasons, I recommend building this page first and later saving it as a secondary "to become dynamic" version. Follow these steps to do so:

1. Select File > New to create a blank PHP page without any layout options. Save this page in the adobe_xml_imagelist directory.
2. Optional: If you want, use the Attach Style Sheet feature in Dreamweaver to attach the provided CSS article_detail.css file located in the css subdirectory.
3. Create a recordset querying the adobe_xml_imagelist table (see Figure 8).

Because the to-be-displayed recordset will retrieve its article_id value from the previously explained article_list.php page, it's mandatory to define a correct filter condition:

4. After adding the obligatory page headline (e.g. "XML imagelist from directory"), you will first add the record's dummy content.

Open the Application panel, click the Server Behaviors tab, click the plus (+) button, and select the Dynamic Text menu entry. As displayed in Figure 9, the recordset's article_headline, article_id and article_content placeholders should be inserted into the page.

Adding the Spry table

Here comes the truly relevant exercise: adding the Spry table! However, a picture paints a thousand words. Figure 9 shows how your page should eventually appear in Dreamweaver:

Create a Spry XML dataset by selecting Insert > Spry > Spry XML data set:

1. To define the XML source, click the Browse button and select the xml_testdata.xml file.
2. Click the "get schema" button to make Dreamweaver generate a list of XML row elements.
3. As shown in Figure 10, highlighting the imagedata row element will change the field Xpath to imagelist/imagedata and additionally create a list of Data Set columns matching the displayed row elements
4. In order to allow for a proper sorting of the XML data, define an adequate data type for each Data Set column. The values are as follows:
   • id: number
   • url: image link
   • width: number
   • height: number
   • name: string
   • filesize: number
   • filetime: string
   • fileextension: string
5. For sorting the data automatically on page load, select an arbitrary element from the Sort menu and select Ascending or Descending from the Direction menu. The provided sample data is sorted by "id" and in "ascending" order, but this shouldn't keep you from defining a more expedient order criteria like "filetime descending" to display the most recently added image first.

   I recommend leaving the options "Distinct on load", "Turn XML Data Caching Off", and "Auto refresh data" unchecked, as they will practically make no sense when loading the dynamically generated XML at a later time.

Next insert a Spry Table at the desired page position by selecting Insert > Spry > Spry Table. In the Columns panel, adjust the table columns by doing the following:

1. Click the minus (–) sign to subtract those columns you don't want to see displayed.
2. Click the up or down arrows to move a column. Moving a column up moves it further left in the displayed table; moving a column down moves it to the right.
3. To define a column to sort on, select it in the Columns panel and choose Sort Column When Header Is Clicked. Repeat this for each column you want to sort on.
4. Just skip selecting any "odd row" etc. classes, as your sortable image list can surely do without this.
5. Since you're creating a simple Spry table, leave the Update Detail Region When Row Is Clicked option unchecked.
6. When you click OK, Dreamweaver will probably ask you "Add Spry region?"; click Yes.

Applying some visual fine-tuning to the generated Spry table is easy by setting the table align to "center," as done in the provided sample page.

The XML values related to your Spry table's data references ({width}, {height}, and {filesize}) are stored and retrieved as integers, so I recommend that you add meaningful and familiar abbrevations such as these:

• {width} px
• {height} px
• {filesize} kb

The default image tag generated by the Spry table is very basic (<img src="{url}"/>) and lacks additional attributes like "width", "height", and of course the mandatory "alt" and "title".

If you feel like adding them to the tag, click the "broken image" icon and switch Dreamweaver to Code view. You'll now see the above-mentioned basic image tag already highlighted. All you need to do is add the missing attributes and values like this:

As you can see, assigning values to these attributes is simply a matter of copying and pasting already existing Spry data references you'll find elsewhere on this page.

Save this page, but leave it open.

Before previewing your article_detail_sample_xml.php version in a browser, you'll need to adapt the associated file, xml_imagelist_testdata.xml, to your local testing server environment. This XML file comes with three predefined data sets pointing to existing images located in the subdirectory images/2 and provides the following structure:

While preparing this tutorial I admittedly didn't succeed predicting your Dreamweaver testing server's settings. That's why you need to replace the default "http://localhost/guenter" component of the image's <url>...</url> with your own testings server's URL prefix. Please do this for all three <imagedata> sets and save this file.

Now enjoy the results of your hard labor by previewing your article_detail_sample_xml.php page in your browser. You certainly deserve to have some fun now. If you agree with the displayed results, save it as article_detail_dynamic_xml.php.

Creating the article_detail_dynamic_xml.php file

As I promised before, making a dynamic difference to the previous page that's driven by static XML data will be a breeze. All you need to do is switch this page to Code view and look out for the following code block:

The above code block is located in the document's <head>...</head> section. Now replace the original file pointer:

with this:

Now that you've replaced this code, you're done!

Please remember: You will not be able to preview this page directly in your browser because it's not supposed to work in a standalone way. Always load your article_list.php page to pass one of the available article_id values to this page!

Unlike a regular Spry.Data.XMLDataSet, which usually retrieves values only from a given XML file containing given static data, an application that's supposed to retrieve image and file related data from "it depends" sources initially has no indication of the data's physical location—in other words, which folder to retrieve the images from—and doesn't know how to process the data. What a dilemma.

But rather than breaking out in a sweat, simply make PHP do the donkeywork for you and, furthermore, allow for an essential feature: a bidirectional exchange of data! As displayed in the data flow schema in Figure 11, the xml_imagelist.php script actually plays the decisive role as mediator between your page and the three underlying workhorses (xml_imagelist_applogic.inc.php, xml_imagelist_config_inc.php, and xml_imagelist_servername_inc.php), which are located in a separate scripts folder.

Dissecting article_detail_dynamic_xml.php

The "data source" parameter of the regular Spry.Data.XMLDataSet object is slightly modified to utilize a server-side scripting feature that's not available with static XML files: appending parameters to referenced PHP files.

In order to define the correct directory path (relative to your server root) to the desired image folder, you're sending a sequence of successive directory path information (also known as "directory drill-down") to xml_imagelist.php as URL parameters:

• The value of the first parameter, path_to_mediator, points to the working directory of the file xml_imagelist.php. In our case, it's the adobe_xml_imagelist directory.
• The value assigned to the second parameter, path_to_images, points to the desired image folder located below the abovementioned working directory of the "mediator" script.

  In this example, I'm pointing to an image directory located two levels below xml-imagelist.php. I know the first directory by name ("images"), but as the second directory depends on the currently effective "article_id" value retrieved from the recordset, I'll simply be using the related dynamic data "$row_article['article_id']" for the second directory.

  I next combine the static and dynamic information to a valid file path: "images/<?php echo $row_article['article_id']; ?>"

Here is the complete directory drill-down specifications used in our sample file:

Dissecting xml_imagelist.php ("mediator")

This file provides dual capacity by simultaneously doing the following:

• Forwarding the abovementioned directory drill-down information to the data processing files located in the scripts folder
• When those fellas have done their work, passing back the processed results to article_detail_dynamic_xml.php as dynamically generated XML data

Though doubtlessly playing a significant role, xml_imagelist.php has the only purpose of being a simple middleman. This means you can count yourself lucky to just make it require the necessary data processing (xml_imagelist_applogic_inc.php) and application configuration (xml_imagelist_config_inc.php) scripts:

If you're a developer with some PHP knowledge, you might raise the legitimate question, "Why didn't you roll all functionality into one by throwing all data processing functionality in this file rather than spreading them across external files?" Good question.

This would indeed have been possible, but this separation allows for something important to users who'd like to go beyond the provided sample application and create their own "dynamic image list from directory" application. By using PHP's require function, it's a breeze to create an xml_imagelist.php derivate by just including a different configuration file, while keeping the xml_imagelist_applogic_inc.php file untouched (recommended, as you'll later see).

There's yet another benefit from outsourcing the configuration and application logic scripts: The whole scripts folder including, its contents, may also be moved to a different location on your server to allow for multiple scripts to access a centralized logistics. When creating your own mediator scripts, you'd just need to adjust their "require" file path specification to match the changed location of the scripts folder. Please note that the specified file paths are always relative to your mediator script!

Rules for developing your own mediator scripts

As the schema in Figure 12 demonstrates, the provided application logic gives you a maximum of freedom regarding where the scripts folder and your Dreamweaver page may be located. But there's indeed one simple rule of thumb that says where your mediator script needs to be physically located (both apply):

• Underneath at least one subdirectory relative to the server root
  (variable "path_to_mediator")
• Above at least one directory pointing to the desired image folder(s)
  (variable "path_to_images")

While the technical requirement of having this file pointing to one or more subdirectories for grabbing the images may be obvious to experienced PHP developers—the @fopen function initially starts in the current working directory and then drills down to the directory specified in the path_to_images variable—some users might prefer to have this file located in the server root. Sorry, but this will not work because the application logic was designed to require at least one subdirectory below the server root. But isn't it great to be a skilled developer? You can change all that yourself .

Dissecting xml_imagelist_servername_inc.php

This file contains three variables for defining your local and remote HTTP server name (let's call this "connection" for now) plus instructing xml_imagelist_applogic_inc.php, which "connection" is currently getting used.

This must equal the URL prefix specified in your Dreamweaver site definition:

This is required when running the application from your remote host:

This defines which of the abovementioned server names is currently getting used:

The options are:

• "a": use local server name
• "b" or "": use remote server name

In case you're wondering about the reason to determine a connection, because the generated XML data should be as portable as possible, you'll need to ensure an absolute file path (e.g., <img src="http://www.domain.com/adobe_xml_imagelist/images/1/logo.gif">) used for all images' SRC attributes, depending on whether you're running the application from your local testing server or from your remote website.

Dissecting xml_imagelist_config_inc.php

Besides including the previously mentioned connection file, this file contains eight variables, which are meant to control the general application behavior that's encapsulated in the script xml_imagelist_applogic_inc.php mentioned next.

The default values provided in this script do match the sample application's settings, which means you will not have to change them. Please note that the following explanation on the variables is also provided within the script itself.

This points to a specified subdirectory below your HTTP server root; it will also be used for assembling the correct image URL:

Change this according to the file path declared in your Dreamweaver page:

It will be used for assembling the correct image URL. For example:

This is a comma-separated list of allowed file extensions (case insentitive!):

This affects the appearance of filenames: "Y" replaces underscores with spaces. Leave empty ("") to display the filename as is:

Filenames starting with a specified char will be excluded. Leave empty ("") to allow for all files:

This is the file last modified; change the display format according to your preferences:

Please read the PHP date() function page on the W3Schools website for more information on the PHP date() function and the variety of date-formatting options. Some commonly used international formats are as follows:

• "d-m-Y": 31-12-1961
• "d/m/Y": 31/12/1961
• "d.m.Y": 31.12.1961 (the usual German format)

This is an advanced option. Every time the Dreamweaver page containing the Spry table is launched, allow the referenced script (e.g., xml_imagelist.php) to additionally create a static XML file containing all the current nodes and values. Please specify the desired storage device in the following variable, $create_static_xml_file_in_directory:

This option defaults to "N" so just set it to "Y" to activate this feature.

The filename to be created is assembled using the following static and dynamic components:

• Main script referenced from the Dreamweaver page, minus the file extension ("xml_imagelist")
• Hard-coded underscore (_)
• Script's "filepath". Slashes will be converted to underscore ("news_1")
• Hard-coded suffix (".xml")

Example: xml_imagelist_images_1.xml

Specify the subdirectory (relative to the mediator script referenced from your Dreamweaver page) where the XML file(s) will be created. It defaults to xml_data. Hint: Set to "." to create the file in the script's working directory.

Note: Please enable write permission (e.g., 755) for the specified directory. Otherwise the file might not be generated!

Dissecting xml_imagelist_applogic_inc.php

This file is what I'd call the technology center; here is where the images from the specified directory:

• Get "read in" and popped in a so-called "array"
• Get examined for several image and file-related criteria, which will be formatted according to the rules you determined in the configuration file

And all of their related data will be rendered as dynamic XML.

XML structure generated on the fly

Complete script code

Where to go from here

Besides trying to explore yet another real-world application and hoping that approach and result is considered useful by other developers, I wrote this tutorial primarily to illuminate one of Spry's comparatively undervalued capabilities: Its openness to have inquiring developers easily add behaviors by using their familiar server-side scripting language skills.

Of course, none of the illustrated methods can honestly be considered virgin soil, if you look at them separately. Everyone knows that the Spry framework for Ajax, as such, is meant to handle XML data, and learning how to grab file contents from a directory belongs to any PHP developer's basic skills.

Something unexpected dawned on me while I was developing the application. It might not be the most consummate thing there is, but it's indeed a good example of "give and take" between technologies. This is not the ordinary XML one-way street, and the functional benefits are mutual.

Some features of this application would, in real life, certainly qualify as a "because you can" feasibility study rather than a realistic endeavor. If you were to develop this for your customer, image sorting criteria like "by file size" certainly wouldn't make sense within the context of a "related slide show" CMS module. But you can, that's why you're a developer, right?

So, where to go from here? In theory, there are many options at your disposal besides improving the provided application or extending features as you see fit. This idea alone can very easily be adapted to build dynamic "related files" listings rather than images, and it will certainly be interesting to explore how this conception can be extended to embrace other features like Spry paging (introduced in version 1.5).

I hope this tutorial has a welcome side-effect: encouraging you to be innovative and adventurous when it comes to building a bridge between things—in the best Adobe tradition. Cheers! ;-)