Prototyping the XML (Java and XSLT)

Once the requirements and screen flow are well understood, it is possible to move on to a more rigorous design process. Web sites based on XSLT are highly modular, facilitating a design and implementation process that can be farmed out to several members of a development team. Each piece can be developed and tested independently before finally bringing everything together into the completed web application.

7.2.3. XSLT Stylesheets

Yet another member of the development team can be assigned to the task of creating XSLT stylesheets, although he or she will have to wait until the XML and XHTML prototypes are complete. More often than not, the person designing the XML will be the one creating the initial XSLT stylesheets.

At this point in the process, a tool such as XML Spy can be invaluable.[26] The ability to edit the XSLT stylesheet and click on the Refresh button in an IDE makes development a snap. Alternately, an XSLT-compatible web browser can quickly display changes as stylesheets are edited. As explained in Chapter 1, "Introduction ", Microsoft's Internet Explorer 5.x supports XSLT, provided that the updated msxml parser is installed using the xmlinst utility.[27]

[26] XML Spy is a commercial XML editor that works nicely for XSLT development. It is available at http://www.xmlspy.com.

[27] As this is written, IE 6.0 is in beta testing. It supports the latest XSLT specification. The Mozilla browser will also support XSLT at some point.

Example 7-7 shows the XSLT for the discussion forum home page.

Example 7-7. XSLT for the home page

<?xml version="1.0" encoding="UTF-8"?>
<!--
***********************************************************
** home.xslt
**
** Transforms the home page into XHTML
***********************************************************
-->
<xsl:stylesheet version="1.0" 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:import href="utils.xslt"/>
  <xsl:param name="rootDir" select="'../docroot/'"/>
  <xsl:output method="xml" version="1.0" encoding="UTF-8" 
    indent="yes" 
    doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN" 
    doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"/>
  
  <!--
  **********************************************************
  ** Create the XHTML web page
  *******************************************************-->
  <xsl:template match="/">
    <html xmlns="http://www.w3.org/1999/xhtml">
      <head>
        <title>Discussion Forum Home</title>
        <link href="{$rootDir}forum.css" 
            rel="stylesheet" type="text/css"/>
      </head>
      <body>
        <div class="box1">
          <h1>Discussion Forum Home</h1>
        </div>
        <xsl:apply-templates select="home/board"/>
      </body>
    </html>
  </xsl:template>
  
  <!--
  **********************************************************
  ** Output a box for each board in the discussion forum
  **********************************************************
  -->
  <xsl:template match="board">
    <xsl:variable name="boardID" select="@id"/>
    
    <div class="box2">
      <h2><xsl:value-of select="name"/></h2>
      <div><xsl:value-of select="description"/></div>
      <div style="margin-left: 2em;">
        <!-- create a link so the user can post a new message
             to this board -->
        <p>
        <a href="/forum/main/postMsg?mode=postNewMsg&amp;boardID={@id}">Post Message</a>
        to <xsl:value-of select="name"/>
        </p>
        
        <!-- For each month that has messages, show the 
             month name and year number as a link -->
        <xsl:for-each select="messages">
         <ahref="forum/main/viewMonth?boardID={$boardID}&amp;month={@month}&amp;year=
         {@year}">
            <xsl:call-template name="utils.printShortMonthName">
              <xsl:with-param name="monthNumber" select="@month"/>
            </xsl:call-template>
            <xsl:text>, </xsl:text>
            <xsl:value-of select="@year"/>
          </a>
          <!-- put a pipe character after 
               all but the last month -->
          <xsl:if test="position() != last( )">
            <xsl:text> | </xsl:text>
          </xsl:if>
        </xsl:for-each>
      </div>
    </div>
  </xsl:template>
</xsl:stylesheet>

This stylesheet opens with the usual <xsl:stylesheet> tag and then proceeds to import utils.xslt. This is a stylesheet that contains common templates for formatting dates. Since these utilities are needed on just about every page, they are defined a common file that is imported, as shown here. This stylesheet also takes a parameter named rootDir, allowing the web application to specify the location of the document root directory:

<xsl:param name="rootDir" select="'../docroot/'"/>

The select attribute defines a default value for this parameter if none was specified. During the stylesheet development process, the XSLT is tested using a static XML file. This is done outside of a web application, so the parameter is not specified and the root directory defaults to ../docroot/. This makes it possible to locate the CSS file during development, when developers are working from a static directory structure on their file systems. Later, when the XSLT stylesheet is deployed to a web application and the servlet is running, the servlet can specify a different value for this parameter that indicates a directory relative to the web application context. This is a useful technique whenever a stylesheet has to reference external resources such as CSS files, JavaScript files, or images.

Next, the <xsl:output> element is used to set up XHTML output. The XHTML 1.0 Strict DTD is used, which eliminates many deprecated HTML 4.0 features. Because the strict DTD does away with many formatting tags, a CSS file is required to make the pages look presentable. All the XSLT needs to do is produce HTML code that references the external stylesheet, as shown here:

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Discussion Forum Home</title>
    <link href="{$rootDir}forum.css" 
        rel="stylesheet" type="text/css"/>
  </head>

The XSLT processor does not actually deal with the CSS file. From the perspective of XSLT, the <link> tag is just text that is copied to the result tree during the transformation process. Later, when the web browser displays the XHTML page, the actual CSS file is loaded. This technique is great because styles can be shared across all web pages without complicating the XSLT stylesheets.

The remainder of the stylesheet is pretty basic -- just matching patterns in the XML and producing XHTML content to the result tree. One important thing to point out here is the way that hyperlinks are created:

<a href="/forum/main/postMsg?mode=postNewMsg&amp;boardID={@id}">Post Message</a>

Since the ampersand character (&) is not allowed in an XML attribute value, it must be written using the & built-in entity. As it turns out, browsers deal with this just fine, and the hyperlink works anyway.[28]

[28] We will see this again when dealing with WML in Chapter 10, "Wireless Applications".

What Is the URL?

You may be wondering how you are supposed to know what each hyperlink is actually supposed to be. At this stage of the game, you probably will not know, and your links will actually look something like this:

<a href="TODO: link to post a new message">Post Message</a>

This is fine for now, because you really won't know what to put there until the servlets are fully designed. Part of the servlet design process involves figuring out what parameters are required and what the legal values are. Until this work has been completed, however, an educated guess or "TODO" comment is fine.

Another key piece of this stylesheet shows how to call a utility template:


<xsl:call-template name="utils.printShortMonthName">
  <xsl:with-param name="monthNumber" select="@month"/>
</xsl:call-template>

The utils.printShortMonthName template is part of utils.xslt and is invoked just like a local template. The only difference is that the current stylesheet must import utils.xslt or the code will fail. Prefixing the template name with utils. has nothing to do with the actual filename; it is a convention adopted only for this application that makes the code a little easier to read, reducing the chances for naming conflicts.

The reusable XSLT stylesheet, utils.xslt, is shown next in Example 7-8.

Example 7-8. Reusable XSLT code

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  
  <xsl:template name="utils.printShortMonthName">
    <xsl:param name="monthNumber"/>
    <xsl:choose>
      <xsl:when test="$monthNumber='0'">Jan</xsl:when>
      <xsl:when test="$monthNumber='1'">Feb</xsl:when>
      <xsl:when test="$monthNumber='2'">Mar</xsl:when>
      <xsl:when test="$monthNumber='3'">Apr</xsl:when>
      <xsl:when test="$monthNumber='4'">May</xsl:when>
      <xsl:when test="$monthNumber='5'">Jun</xsl:when>
      <xsl:when test="$monthNumber='6'">Jul</xsl:when>
      <xsl:when test="$monthNumber='7'">Aug</xsl:when>
      <xsl:when test="$monthNumber='8'">Sep</xsl:when>
      <xsl:when test="$monthNumber='9'">Oct</xsl:when>
      <xsl:when test="$monthNumber='10'">Nov</xsl:when>
      <xsl:when test="$monthNumber='11'">Dec</xsl:when>
    </xsl:choose>
  </xsl:template>
  
  <xsl:template name="utils.printLongMonthName">
    <xsl:param name="monthNumber"/>
    <xsl:choose>
      <xsl:when test="$monthNumber='0'">January</xsl:when>
      <xsl:when test="$monthNumber='1'">February</xsl:when>
      <xsl:when test="$monthNumber='2'">March</xsl:when>
      <xsl:when test="$monthNumber='3'">April</xsl:when>
      <xsl:when test="$monthNumber='4'">May</xsl:when>
      <xsl:when test="$monthNumber='5'">June</xsl:when>
      <xsl:when test="$monthNumber='6'">July</xsl:when>
      <xsl:when test="$monthNumber='7'">August</xsl:when>
      <xsl:when test="$monthNumber='8'">September</xsl:when>
      <xsl:when test="$monthNumber='9'">October</xsl:when>
      <xsl:when test="$monthNumber='10'">November</xsl:when>
      <xsl:when test="$monthNumber='11'">December</xsl:when>
    </xsl:choose>
  </xsl:template>
</xsl:stylesheet>

Month numbers are indexed from position 0 to be consistent with the java.util.Calendar class, which also uses 0 to represent January. The templates convert the month number into an English month name.

viewMonth.xslt is shown in Example 7-9. It generates an XHTML page that shows all messages in a month for a particular board.

Example 7-9. XSLT for the View Month page

<?xml version="1.0" encoding="UTF-8"?>
<!--
***********************************************************
** viewMonth.xslt
**
** Shows a month-view of messages in a given board.
***********************************************************
-->
<xsl:stylesheet version="1.0" 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:import href="utils.xslt"/>
  <xsl:param name="rootDir" select="'../docroot/'"/>
  <xsl:output method="xml" version="1.0" encoding="UTF-8" 
    indent="yes" 
    doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN" 
    doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"/>
  <!-- ================= Global Variables ================= -->
  <xsl:variable name="global.boardName" select="/viewMonth/board/name"/>
  <xsl:variable name="global.boardID" select="/viewMonth/board/@id"/>
  <xsl:variable name="global.monthNum" select="/viewMonth/@month"/>
  <xsl:variable name="global.yearNum" select="/viewMonth/@year"/>
  
  <!--
  **********************************************************
  ** Create the XHTML web page
  *******************************************************-->
  <xsl:template match="/">
    <html xmlns="http://www.w3.org/1999/xhtml">
      <head>
        <title>
          <xsl:value-of select="$global.boardName"/>
        </title>
        <!-- reference an external CSS file to keep this
             XSLT stylesheet smaller -->
        <link href="{$rootDir}forum.css" 
            rel="stylesheet" type="text/css"/>
      </head>
      <body>
        <div class="box1">
          <h1>
            <xsl:value-of select="$global.boardName"/>
          </h1>
        </div>
        <div class="box2">
          <xsl:text>Messages for </xsl:text>
          <xsl:call-template name="utils.printLongMonthName">
            <xsl:with-param name="monthNumber" select="$global.monthNum"/>
          </xsl:call-template>
          <xsl:text>, </xsl:text>
          <xsl:value-of select="$global.yearNum"/>
        </div>
        <!-- ===== Quick Actions ====== -->
        <h3>Quick Actions</h3>
        <ul>
          <li>
            <a href="postMsg?mode=postNewMsg&amp;boardID={$global.boardID}">
          Post</a> a new message...</li>
          <li>Return to the <a href="home">home page</a>...</li>
        </ul>
        <!-- ===== Recursively show the message tree ===== -->
        <xsl:apply-templates select="viewMonth/message"/>
      </body>
    </html>
  </xsl:template>

  <!--
  **********************************************************
  ** Display a one-line summary for each message.
  *******************************************************-->
  <xsl:template match="message">
    <xsl:param name="indent" select="0"/>
    
    <!-- indent according to the 'indent' parameter -->
    <div style="margin-left: {$indent}em;">
      <a href="viewMsg?msgID={@id}">
        <xsl:value-of select="subject"/>
      </a>
      <xsl:text> posted by </xsl:text>
      <xsl:apply-templates select="authorEmail"/>
      <xsl:text> on </xsl:text>
      <xsl:value-of select="@day"/>
      <xsl:text disable-output-escaping="yes">&amp;nbsp;
      <xsl:call-template name="utils.printShortMonthName">
        <xsl:with-param name="monthNumber" select="$global.monthNum"/>
      </xsl:call-template>
            <xsl:text disable-output-escaping="yes">&amp;nbsp;
      <xsl:value-of select="$global.yearNum"/>
      
      <!-- recursively select all messages that are 
          responses to this one. Increment the indentation 
          with each call -->
      <xsl:apply-templates select="message">
        <xsl:with-param name="indent" select="$indent + 1"/>
      </xsl:apply-templates>
    </div>
  </xsl:template>
  
  <!--
  **********************************************************
  ** Show the author's email address.
  *******************************************************-->
  <xsl:template match="authorEmail">
    <a href="mailto:{.}">
      <xsl:value-of select="."/>
    </a>
  </xsl:template>
</xsl:stylesheet>

Because viewMonth.xslt shows a summary view of a large number of messages, the actual text content for each message is not included in the output. Instead, the message subject, author, and create date are displayed. These lines are grouped and indented according to replies, making threads of discussion immediately visible.

This stylesheet declares a series of global variables. These can be referenced throughout the stylesheet and are designed to make the code more maintainable. Since each variable is prefixed with global., the code is easy to understand when using the variables:

<xsl:value-of select="$global.boardName"/>

NOTE: The global. naming convention is not a standard part of XSLT. It is just a convention used here to make the XSLT more self-documenting.

The interesting part of this stylesheet involves construction of the tree of messages. Since messages in the XML are hierarchical, the XSLT must recursively process the data to properly show threads of discussion. Here is another look at a portion of the viewMonth.xml file presented earlier in this chapter:

<viewMonth month="1" year="2001">
  <board id="1">
    <name>Java Programming</name>
    <description>General programming questions about Java.</description>
  </board>
  <message id="1" day="1">
    <subject>First test message</subject>
    <authorEmail>burke_e@yahoo.com</authorEmail>
    <message id="2" day="2">
      <subject>Re: First test message</subject>
      <authorEmail>aidan@nowhere.com</authorEmail>
    </message>
  </message>
  <message id="3" day="4">
    <subject>Another test message</subject>
    <authorEmail>burke_e@yahoo.com</authorEmail>
  </message>
</viewMonth>

In the XSLT stylesheet, the first part of the recursive process selects all <message> elements occurring immediately below the <viewMonth> element:

<xsl:apply-templates select="viewMonth/message"/>

This selects messages with ids 1 and 3, causing the following template to be instantiated:

<xsl:template match="message">
  <xsl:param name="indent" select="0"/>

This template takes a parameter for the level of indentation. If the parameter is not specified, as in this first usage, it defaults to 0. This code is followed by very basic XSLT code to produce a one-line summary of the current message, and then the template recursively instantiates itself:

<xsl:apply-templates select="message">
  <xsl:with-param name="indent" select="$indent + 1"/>
</xsl:apply-templates>

This efficiently selects all <message> elements that occur immediately within the current message and increments the indentation by 1. This allows the stylesheet to indent replies appropriately. The recursive process continues until no messages remain.

Another stylesheet, viewMsg.xslt, is responsible for displaying a single message. This is a simple XSLT stylesheet and can be found in Appendix A, "Discussion Forum Code". The only remaining stylesheet, postMsg.xslt, is shown in Example 7-10. This stylesheet supports two modes of operation. Therefore, it is more complicated than the previous examples.

Example 7-10. XSLT for the Post/Reply message page

<?xml version="1.0" encoding="UTF-8"?>
<!--
***********************************************************
** postMsg.xslt
**
** Creates the "Post New Message" XHTML page and the
** "Reply to Message" XHTML page.
***********************************************************
-->
<xsl:stylesheet version="1.0" 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:import href="utils.xslt"/>
  
  <!-- pass the root directory as a parameter, thus
       allowing this stylesheet to refer to the CSS file -->
  <xsl:param name="rootDir" select="'../docroot/'"/>
  
  <xsl:output method="xml" version="1.0" encoding="UTF-8" 
    indent="yes" 
    doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN" 
    doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"/>

  <!-- ===== Global Variables ===== -->
  <xsl:variable name="global.subject" select="/postMsg/prefill/subject"/>
  <xsl:variable name="global.email" select="/postMsg/prefill/authorEmail"/>
  <xsl:variable name="global.message" select="/postMsg/prefill/message"/>
  
  <xsl:variable name="global.title">
    <xsl:choose>
      <xsl:when test="/postMsg/inResponseTo">
        <xsl:text>Reply to Message</xsl:text>
      </xsl:when>
      <xsl:otherwise>
        <xsl:text>Post New Message</xsl:text>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:variable>
    
  <!--
  **********************************************************
  ** Create the XHTML web page
  *******************************************************-->
  <xsl:template match="/">
    <html xmlns="http://www.w3.org/1999/xhtml">
      <head>
        <title><xsl:value-of select="$global.title"/></title>
        <link href="{$rootDir}forum.css"
            rel="stylesheet" type="text/css"/>
      </head>
      <body>
        <!-- show the page title and board name -->
        <div class="box1">
          <h1><xsl:value-of select="$global.title"/></h1>
          <div>
            <xsl:value-of select="postMsg/board/name"/>
          </div>
        </div>
        <xsl:apply-templates select="postMsg/inResponseTo"/>
        
        <div class="box2">
          <!-- optionally display error message -->
          <xsl:if test="postMsg/error/@code='ALL_FIELDS_REQUIRED'">
            <p class="error">All fields are required...</p>
          </xsl:if>
          
          <!-- Create an XHTML form. The user will provide
               the subject, and Email address, and 
               the message text -->
          <form method="post" action="postMsg">
            <div>
            <input type="hidden" name="boardID" 
                value="{postMsg/board/@id}"/>
            
            <!-- Determine the mode of operation -->
            <xsl:choose>
              <xsl:when test="/postMsg/inResponseTo">
                <input type="hidden" name="origMsgID"
                         value="{postMsg/inResponseTo/@id}"/>
                <input type="hidden" name="mode" value="replyToMsg"/>
              </xsl:when>
              <xsl:otherwise>
                <input type="hidden" name="mode" value="postNewMsg"/>
              </xsl:otherwise>
            </xsl:choose>
            </div>
            
            <!-- Show the input fields in a table to
                 keep things aligned properly -->
            <table>
              <tr>
                <td>Subject:</td>
                <td>
                  <input type="text" name="msgSubject" 
                      value="{$global.subject}" size="60" maxlength="70"/>
                </td>
              </tr>
              <tr>
                <td nowrap="nowrap">Your Email:</td>
                <td>
                  <input type="text" name="authorEmail" 
                      value="{$global.email}" size="60" maxlength="70"/>
                </td>
              </tr>
              <tr valign="top">
                <td>Message:</td>
                <td>
                  <!-- xsl:text prevents the XSLT processor from collapsing to
                       <textarea/>, which caused problems with many browsers. -->
                  <textarea name="msgText" wrap="hard" rows="12" 
                      cols="60"><xsl:value-of 
                      select="$global.message"/><xsl:text> </xsl:text></textarea>
                </td>
              </tr>
              <!-- The last table row contains a submit
                   and cancel button -->
              <tr>
                <td> </td>
                <td>
                  <input type="submit" name="submitBtn" value="Submit"/>
                  <input type="submit" name="cancelBtn" value="Cancel"/>
                </td>
              </tr>
            </table>
          </form>
        </div>
      </body>
    </html>
  </xsl:template>
  
  <!--
  **********************************************************
  ** Show the text: 'In Response to: Msg Subject'
  *******************************************************-->  
  <xsl:template match="inResponseTo">
    <div>
      In Response to:
      <span style="font-weight: bold;">
      <xsl:value-of select="subject"/>
      </span>
    </div>
  </xsl:template>
</xsl:stylesheet>

Since this stylesheet must work for posting new messages as well as for replying to messages, it must determine the appropriate mode of operation. This can be accomplished by checking for the existence of elements that occur only in one mode or the other. For example, the <inResponseTo> XML element occurs only when the user replies to an existing message. Therefore, the XSLT stylesheet can define a variable for the page title as follows:

<xsl:variable name="global.title">
  <xsl:choose>
    <xsl:when test="/postMsg/inResponseTo">
      <xsl:text>Reply to Message</xsl:text>
    </xsl:when>
    <xsl:otherwise>
      <xsl:text>Post New Message</xsl:text>
    </xsl:otherwise>
  </xsl:choose>
</xsl:variable>

<xsl:when test="/postMsg/inResponseTo"> returns true when the <inResponseTo> element exists in the original XML data. In this case, the global.title variable is set to "Reply to Message." Otherwise, the title defaults to "Post New Message."

This stylesheet optionally displays an error message when the user partially fills out the XHTML form and submits the data. The servlet redisplays the page with an error message, allowing the user to fix the problem. It does this by inserting the following XML element into the data:

<error code="ALL_FIELDS_REQUIRED"/>

The XSLT stylesheet tests for the existence of this element as follows:

<xsl:if test="postMsg/error/@code='ALL_FIELDS_REQUIRED'">
   <p class="error">All fields are required...</p>
</xsl:if>

An additional trick used in this stylesheet involves its interaction with a servlet. When the user submits the XHTML form data, the servlet must determine which mode of operation the user was in. For this task, the servlet looks for a request parameter called mode. Legal values for this parameter are replyToMsg and postNewMsg. Since the user is submitting an XHTML form, the easiest way to pass this data is via a hidden form field named mode. Here is the code that does the work:

<xsl:choose>
  <xsl:when test="/postMsg/inResponseTo">
    <input type="hidden" name="origMsgID"
         value="{postMsg/inResponseTo/@id}"/>
    <input type="hidden" name="mode" value="replyToMsg"/>
  </xsl:when>
  <xsl:otherwise>
    <input type="hidden" name="mode" value="postNewMsg"/>
  </xsl:otherwise>
</xsl:choose>

The stylesheet also inserts a hidden form field that contains the original message ID whenever the mode is replyToMsg. On the servlet side, the code looks something like this:

public void doGet(HttpServletRequest request, HttpServletResponse response) ... {
    String mode = request.getParameter("mode");
    if ("replyToMsg".equals(mode)) {
        String origMsgID = request.getParameter("origMsgID");
        ....

7.2. Prototyping the XML

7.2.1. XHTML Prototypes

Example 7-1. forum.css

Figure 7-2. Home page prototype

Example 7-2. Home page XHTML source

Figure 7-3. View Month prototype

Figure 7-4. Post Message prototype

Figure 7-5. View Message prototype

7.2.2. XML Samples

Example 7-3. home.xml

Iterative Design

Example 7-4. viewMonth.xml

Example 7-5. postMsg.xml

Example 7-6. viewMsg.xml

7.2.3. XSLT Stylesheets

Example 7-7. XSLT for the home page

What Is the URL?

Example 7-8. Reusable XSLT code

Example 7-9. XSLT for the View Month page

Example 7-10. XSLT for the Post/Reply message page