Tutorial Layout (XSLT)

9.3. Tutorial Layout

Before we talk about the details of the XML document design and the XSLT source code, we'll review the actual HTML, zip, and PDF files we need to create. One advantage we had in this project is that we didn't have any existing XML documents to contend with; this advantage gave us complete freedom over the XML document design.

Each panel has a masthead and footer, which are defined by corporate standards. They are generated by named templates cleverly named masthead and footer. As corporate standards are updated, we simply change those templates to change the look and feel of the tutorial panel.

9.3.2. Individual Panels

Most HTML files that make up a complete tutorial use this format. Notice that the panel contains the text page 1 of 6; we generate this text with XPath expressions. The 1 is generated by the position() function, and the 6 is generated by the count() function. Each panel's navigation bar also contains links to the Main menu panel and the Section menu panel. An individual panel looks like Figure 9-4.

Figure 9-4. An individual tutorial panel

9.3.3. Section Menu

If you click on the "Section menu" item while on any panel in a tutorial, you'll see a listing similar to Figure 9-5.

Figure 9-5. A section menu

You can click on the title of any panel to go directly to it. We generate the panel titles with a <xsl:for-each select="panel/title"> element. We'll discuss how we generate the links between panels soon.

9.3.4. Feedback Panel

The Toot-O-Matic generates a Feedback panel automatically. The Feedback panel contains an HTML form that lets readers send in their comments on the tutorial. Code on the server takes reader comments and stores them in a database automatically. Figure 9-6 shows what the generated Feedback panel looks like.

Figure 9-6. A typical Feedback panel

The XML document identifies one panel as the Feedback panel. The Feedback button on the navigation bar of every HTML file points to the HTML file with the feedback form. Again, all of these cross-references are generated automatically through the magic of XSLT and XPath.

9.3.5. Email Panel

Another feature of our tutorials is that you can email the URL of the tutorial to a friend. Clicking the "e-mail it!" icon on any panel displays a new browser window as shown in Figure 9-7.

Figure 9-7. The email panel

In this example, the text beneath the title of the tutorial is derived from the abstract attribute of the <tutorial> element.

9.3.6. Zip File

To help readers who have either occasional or expensive web access, we build a zip file that contains everything they need to use the tutorial on their machines. The contents include all generated HTML files, all of the standard graphics used in the header and footer, and any referenced graphics from the tutorial itself.

9.3.7. PDF Files

For readers who want to print out the tutorial and read it offline, we produce two PDF versions of the tutorial, one for letter-sized paper, and one for A4-sized paper. Although we could provide an HTML file that simply contains the HTML rendering of all the pages of the tutorial, we want higher-quality printable output. The first page of the tutorial, shown in Figure 9-8, features the title of the tutorial and a table of contents.

Figure 9-8. First page of the tutorial PDF file

In the table of contents, both the section titles and the page numbers are hyperlinks. If you view the PDF file online, you can click on those items and go directly to the various parts of the tutorial. Even if you read a printout of the PDF file, the page numbers are still an important navigational tool. Cross-references between panels in the tutorial are similarly converted to hyperlinks and printable page numbers. Best of all, any hyperlinks to web sites are also converted to hyperlinks. If your machine is connected, and you have a recent version of the Adobe Acrobat Reader, you can click on the web site and go directly to it.