CleanCode::Products::XmlTransform

N U T S H E L L
Product	XmlTransform
Description	XML/HTML tree transformer, validator, pre-processor
Language	Java
Interface	command-line
Platform	any Java-supported (Windows,Linux,...)
Reference	API

XmlTransform is a general-purpose XML transformer and/or validator that operates on an arbitrarily deep tree of files, optionally generating multi-level indices and adding navigational linkages. But what is it good for, you wonder? The validation side is reasonably straight-forward: it allows you to check that a collection of XML files are grammatically correct, or more formally, that they are valid per your XML Schema specification. You may check either your input files, or your output files after transformation, or both.

Perhaps the more interesting part, however, is the transformation capability, more typically thought of as a pre-processor. And a pre-processor is a very handy thing indeed when designing--for instance--web pages. XmlTransform is an HTML pre-processor, though it is not limited to just HTML. XmlTransform is actually an XML pre-processor; since well-formed HTML is a flavor of XML (well, technically it needs to be XHTML), XmlTransform handles web pages quite nicely. The illustration shows what XmlTransform does with some of the parameters you may use to tailor its operation to your needs. Click on the illustration to enlarge it.

So what is a pre-processor and why is it useful? Maintenance is what consumes resources on any software project--more than the original design and implementation of the project. A pre-processor can help you reduce maintenance costs. For example, say that you include a logo of a certain size on every one of your 509 web pages. A year passes, and one day word comes down from above that the corporation is getting a new look--new letterhead, new typefaces, and oh, yes, a new logo (which is, of course, a different size). You must then edit each of your 500+ pages to point to the new logo graphic... or you could play smart and just give the new logo the same file name. Whew! Saved all those edits. When you view your home page, however, the logo is a bit distorted. That is because you design your web pages properly, providing height and width attributes in your <img> elements. So even though you've replaced the image, you still have to update its size in every one of your web pages. Ah, you proclaim, but you also use cascading style sheets, and all of your pages refer to the common logo style that specifies logo size. So you have only to update your single CSS file to correct the logo display. Good for you... but remember the memo on the new corporate image that mentioned that the wording of the copyright notice is also changed? And that copyright notice is hard-coded in every web page. Ugh.

Just like a style sheet lets you define something once and reuse it over and over, a pre-processor does the same thing for anything in your web page, not just styles. Why not, for example, create your own new HTML element, call it <footer>. When you use that element, you really want to see the HTML code shown in the figure, including the comments. With XmlTransform, you create your own XSLT template that specifies precisely what should happen when <footer> is encountered. You provide a list of all your directories that should be transformed (your source path), and indicate where to place the output files (your target path). There are a number of other parameters that you need to consider, though most default to some reasonable value. The bulk of your effort will be in creating the XSLT specification that drives the transformation engine. Below, for example is the XSLT necessary to recognize the <footer> element and generate the HTML fragment above. Designing clean, useful XSLT does take some effort, but it can be quite useful in the long run.

So far we have talked about maintenance when something on the web page changes. Now let's consider interactions between web pages. Say, for example, you have a series of web pages that have a natural order, say lessons in a tutorial. Each web page has navigational buttons to advance to the next page, go back to the previous page, and so forth. When you want to add a new lesson, remove a lesson, or re-order lessons, you would typically have to manually edit all the linkages, a time-consuming and error-prone process. In the illustration, you'll see a representation of four such related pages, with navigation buttons to go to the first and last pages, the previous and next pages, and the parent page. Again, with appropriate XSLT code in your transformation specification, these links can be generated automatically by XmlTransform. And, in fact the very same buttons on the CleanCode site were generated by XmlTransform in this fashion.

Another benefit of XmlTransform is maintainability. (I cannot emphasize enough that reducing maintenance should really be a priority.) As shown in the illustration, XmlTransform has the capability to automatically populate a parent contents page using elements from each web page. You create the template for the contents page, complete with any other HTML that you wish. You then add a marker element that tells XmlTransform where to insert the generated contents. And you are not limited to a single list; XmlTransform can apply groupings so that you could, for example, have an introductory paragraph, then some generated contents entries, another introductory paragraph, then some additional generated contents entries, and so forth. The contents templates are specified independently for each directory, so you may tailor them as your web content dictates.

To get you started, here is a "sandbox" for XmlTransform, providing several simple examples on how to use it, or, for a real-world example, see the source code of the CleanCode web site itself here.

CleanCode -- The Website for Clean DesignRevised 2013.06.30