Login | Register   
RSS Feed
Download our iPhone app
Browse DevX
Sign up for e-mail newsletters from DevX


XmlTransform—A General-Purpose XSLT Pre-Processor : Page 2

Use this XmlTransform application to generate sets of HTML pages, SQL documentation, or apply it to your own particular needs.

No File Is an Island
Figure 2 illustrates XmlTransform's capability to automatically populate a contents page for a web section using elements from each sibling or child web page. The figure shows how XmlTransform can extract a portion of the <title> element and a portion of a specific <meta> element from each page in a relevant set of pages and combine those into a single contents page. That way, if you add or remove pages from the set, you need only rerun XmlTransform to update the generated contents page.

Figure 2. Automatic Contents Generation: XmlTransform can automatically generate contents pages (shown at the bottom) from selected details it extracts from source files.
If you look at Figure 1 you can see that XmlTransform not only generates files in your target tree but it also generates a few intermediate "contents" files in your source tree (highlighted in magenta in the figure). You create a template for a contents file, which must be named _index.xml and stored in the directory containing the files it will summarize, and XmlTransform populates that template with the summary information. For example, the _index.xml file shown below was used to generate the output in Figure 2:

<?xml version="1.0"?> <cc:cleanCodeDoc> <cc:head> <cc:title>CleanCode::Web Guidelines</cc:title> <cc:id>$Id: _index.xml 20 2006-12-29 00:03:27Z dellxp $</cc:id> <cc:version>$Revision: 20 $</cc:version> <cc:generator/> </cc:head> <cc:body> <h1>Web Guidelines</h1> <h2>Design Considerations for Web Sites</h2> <cc:files group=""/> <br /> </cc:body> </cc:cleanCodeDoc>

Unlike other files in each directory, this _index.xml template file must undergo an extra processing step before being transformed along with the rest of the files in your source tree. This extra step fleshes out the template with the files under its jurisdiction; you control the operation with the <cc:files> element in the template code above. XmlTransform fills this template out and writes it to an intermediate file named web info.xml in the source tree as shown in Figure 1, before performing the rest of the transformations. Here's the relevant portion of this intermediate file (web info.xml); if you compare it to the template shown above, you'll see how XmlTransform has filled out the <cc:files> element with information about each of the other files in the directory:

<?xml version="1.0"?> <cc:cleanCodeDoc> <cc:head> <cc:title>CleanCode::Web Guidelines</cc:title> <cc:id>$Id: _index.xml 20 2006-12-29 00:03:27Z dellxp $</cc:id> <cc:version>$Revision: 20 $</cc:version> <cc:generator/> </cc:head> <cc:body> <h1>Web Guidelines</h1> <h2>Design Considerations for Web Sites</h2> <cc:files group=""> <cc:file> <cc:relfile>webRules/accessibility.html</cc:relfile> <cc:absfile>/usr/doc/webRules/accessibility.xml</cc:absfile> </cc:file> <cc:file> <cc:relfile>webRules/antispam.html</cc:relfile> <cc:absfile>/usr/doc/webRules/antispam.xml</cc:absfile> </cc:file> <cc:file> <cc:relfile>webRules/browser.html</cc:relfile> <cc:absfile>/usr/doc/webRules/browser.xml</cc:absfile> </cc:file> <cc:file> <cc:relfile>webRules/cssConformance.html</cc:relfile> <cc:absfile>/usr/doc/webRules/cssConformance.xml</cc:absfile> </cc:file> . . . </cc:files> <br /> </cc:body> </cc:cleanCodeDoc>

The contents page template may include any other HTML that you wish. Only the marker element (<cc:files>) is significant to XmlTransform, letting it know where to insert the generated contents. The preceding example shows a very basic page that adds only <h1> and <h2> header elements. The intermediate file is now ready to be processed—along with all the referenced pages—by the XSLT transformations specified in your mapping file. Here's the reference code from the supplied translate.xsl that turns the intermediate-file XML shown above into XHTML:

<xsl:template match="cc:files"> <xsl:apply-templates/> </xsl:template> <xsl:template match="cc:file"> <xsl:variable name="extNode" select="document(cc:absfile)/cc:cleanCodeDoc"/> <div class="guidelink"><a href="{cc:relfile}"> <xsl:call-template name="trim"> <xsl:with-param name="s"> <xsl:value-of select="$extNode/cc:head/cc:title"/> </xsl:with-param> </xsl:call-template> </a>:<xsl:text> </xsl:text> <xsl:value-of select= "$extNode/cc:head/xhtml:meta[ @name='description']/@content"/> </div> </xsl:template>

If you study the components of this short XSLT fragment and compare it to the output shown in Figure 2, you'll see how it targets only the relevant information. (The trim function invoked in the preceding XSLT code, but not shown, returns the final octet of a colon-separated string; it has no particular significance other than it is the convention I chose to work with in my coding style.) For completeness, here is the relevant fragment of the final XHTML page rendered by the XSLT transformation:

<body> . . . <h1>Web Guidelines</h1> <h2>Design Considerations for Web Sites</h2> <div class="guidelink"> <a href="webRules/accessibility.html"> Accessibility</a>: Don't discriminate on physical ability when you design web pages. </div> <div class="guidelink"> <a href="webRules/antispam.html"> Anti-Spam</a>: Design defensively so you do not make it easy for spammers to enlist you to help them. </div> <div class="guidelink"> <a href="webRules/browser.html"> Browser Compliance</a>: Design economically by considering the technology of your audience. </div> <div class="guidelink"> <a href="webRules/cssConformance.html"> CSS Conformance</a>: Use CSS to improve your design, reduce duplication, and simplify maintenance, but getting it right can be a challenge. </div> . . .

The example above generates an ungrouped contents file; in other words, it places the items into a single list on the contents page, but you may refine this by creating an arbitrary set of smaller, named groups. You could, for example, have an introductory paragraph, and then some generated contents entries, another introductory paragraph, some more contents entries, and so forth. Furthermore, you can specify a contents template for each directory, so you may tailor them as your content dictates.

Author's Note: As a further example this web page example shows a contents page with 19 files arranged in six sections.

The contents or summary page shown in this section provides a mechanism for drilling or navigating down one hierarchy level. The next section completes the picture by demonstrating how to navigate up as well as side to side, which also raises the interesting question of where to place the generated contents file.

Comment and Contribute






(Maximum characters: 1200). You have 1200 characters left.