Login | Register   
Twitter
RSS Feed
Download our iPhone app
TODAY'S HEADLINES  |   ARTICLE ARCHIVE  |   FORUMS  |   TIP BANK
Browse DevX
Sign up for e-mail newsletters from DevX


advertisement
 

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

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


advertisement
Step 1—What To Do
XmlTransform supports several Boolean switches to enable or disable the supported functions:

  • xslTransform specifies to transform input to output using your XSLT specification (as opposed to simply validating a set of files).
  • generateContents specifies to generate contents files in the input tree (using contents template files as discussed earlier).
  • validateInputToSchema specifies to validate the input (using your XML Schema definition).
  • validateOutputToSchema specifies to validate the output (using your XML Schema definition).
  • validateXslBySchema is intended for advanced uses. It causes XmlTransform to validate the XSL file itself (not commonly needed because any errors will be evident when xslTransform is turned on).
Step 2—Where To Do It
You specify where your input tree resides (sourcePath) and where your output tree should be generated (targetPath). Both default to the current directory if not specified. Next, you specify the input file extension (inExtension) and the output file extension (outExtension). These default to xml and html, respectively, if not specified.

Step 3—What To Do It With
To transform each file, you must provide an XSL file that specifies the transform information (xslName). If you specify an absolute path, XmlTransform will use that file at any subdirectory depth. If, however, you specify just a base file name (such as stuff.xsl), then XmlTransform will look for a file with that name within each processed subdirectory. If it doesn't find the file there, it looks for the file of that name in your root directory (sourcePath). This provides flexibility,because you can specify one global XSL specification but override it in specific instances as required. Alternatively, if you don't provide a root XSL file, then XmlTransform processes only those subdirectories that contain a local XSL file.

To generate a table of contents for any given subdirectory, you must provide an XML file template—this is just an XML file like any other among your files, with the exception that it has one or more placeholders for referencing lists of other files, as discussed earlier in the article. You must name the template file according to the following convention: an underscore, then the contentsBaseName parameter, a dot, and the inExtension parameter (for example, _myDir.xml). XmlTransform fills in the template and stores it in your input tree as an intermediate file. The intermediate file name depends on whether you elect to store the contents file in the same directory as the contents or in the parent (contentsToParent); if in the same directory, the name will be the same base name-dot-inExtension, less the underscore. You further need to specify the group placeholder (groupPlaceHolder) indicating where in your contents template to insert content items.

Because XmlTransform writes intermediate files, in the source tree, it needs to be sure that it's not inadvertently overwriting one of your content files. On the other hand, it can't just check for the existence of the file, because XmlTransform may itself have created such a file during an earlier run. Therefore, it writes a generator identification string to a specified node in each generated intermediate file; the presence of that node indicates that the file can be overwritten. You specify what element in your XML should receive this generator identification string via the generatorNode option. The final option needed for contents file generation is groupIdXpath, which specifies an XPath expression used to find the group identifier in each file.

Step 4—How To Do It
Finally, you need to provide a few details on how the program should operate.

  • Which Subdirectories To Process— Using the dirList option, you must explicitly specify which subdirectories under sourcePath XmlTransform should process. This string should be a comma- or semicolon-separated list of subdirectory names (relative to sourcePath) such as sub1, sub1/subsub1, sub2, sub3. If omitted, XmlTransform processes only sourcePath itself (with no subdirectories).
  • Preview Mode—Until you are comfortable with the program, or if you want to check new configuration options you have made, you may see what the program would do without actually doing it. You control this with the enable flag. If omitted, the default is true. When you set enable to false, XmlTransform does no actual work—but it does report what it would do.
  • Stingy Mode—In the spirit of economy, XmlTransform does only what is necessary. That is, it keeps track of what it has done on previous invocations, and only validates or transforms files that have changed. You may override this and force it to process all files using the processAll flag. If omitted, the default is false.
  • Tracking Subdirectory Depth—This option is intended for advanced use. XmlTransform keeps track of the subdirectory depth it's processing, allowing you to define location-relative actions and paths. If for example, you are creating HTML as output, and you want to specify a relative path to an included file, you could use the depth to correctly generate a prefix such as "../../.." to prepend to a file name. Here's a simple XSL template that can generate the appropriate path:
  • <xsl:template name="buildpath"> <xsl:param name="level"></xsl:param> <xsl:if test="$level &gt; 0">../<xsl:call-template name="buildpath"> <xsl:with-param name="level"> <xsl:value-of select="$level - 1"/> </xsl:with-param> </xsl:call-template> </xsl:if> </xsl:template>

    The startDepth configuration option (default=0) allows you to specify an offset between your root (sourcePath) and the location of any referenced include files. For example, if your include files are in the directory above your HTML files, you could specify a startDepth of 1, which would direct the above XSL routine to add an extra ".." in the path. Note that XmlTransform passes the depth of the subdirectory it is processing to the XSL transformation, as an offset to this starting depth using the parameter name level. Therefore, you would use a call-template element in XSL, passing the $level parameter as its argument to create your path string in the preceding example. This is just one example; the $level parameter has other uses as well. For example, you can invoke different templates within your XSL depending on your current level.

  • Providing Custom XSL Parameters—This option is intended for advanced use. Just as the current subdirectory level is passed in to your XSL as a parameter, you may also provide user-defined values to pass using the xslParmList configuration option. This string should be a comma-separated or semicolon-separated list of parameter settings. Each parameter setting must have the form name:value, and the values may contain neither commas nor semicolons. This is useful for passing in such values as a copyright date or a release version number, for example: xslParmList=copyright:2006,relVersion:v1.2. In addition, XmlTransform makes the generator identification string (discussed earlier in the context of contents files) available automatically via this mechanism. To access the parameter, you first include this line in your XSL:
  • <xsl:param name="generator"/>

    Then to use it, you might use something like this, if you are creating HTML or XHTML:



    <meta content="{$generator}" name="myGenerator"/>

Overall, because of the number of options and their effects on the output, XmlTransform does have a fairly steep learning curve, but if you have a problem to tackle that it can handle, it can be quite a time saver. In the real world, XmlTransform originally served to generate static pages on my open source web site. Rather than write in HTML, I can write pages in a shorthand custom XML dialect and let XmlTransform automatically take care of the fancy headers, footers, page linkages, copyright date, and so forth. But XmlTransform is useful in other situations as well. For example, it can act as a SQL documentation generator akin to Ndoc (for C#) or JavaDoc (for Java). The article "Add Custom XML Documentation Capability To Your SQL Code" provides a detailed explanation of how to use XmlTransform to accomplish SQL documentation. That article shares the same set of sample source files that you can find attached to this article, and you can use those to experiment with other uses for XmlTransform.



Michael Sorens is a freelance software engineer, spreading the seeds of good design wherever possible, including through his open-source web site, teaching (University of Phoenix plus community colleges), and writing (contributed to two books plus various articles). With BS and MS degrees in computer science and engineering from Case Western Reserve University, he has worked at Fortune 500 firms and at startups, using C#, SQL, XML, XSL, Java, Perl, C, Lisp, PostScript, and others. His favorite project: designing and implementing the world's smallest word processor, where the medium was silicon, the printer "head" was a laser, and the Declaration of Independence could literally fit on the head of a pin. You can discuss this or any other article by Michael Sorens here.
Comment and Contribute

 

 

 

 

 


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

 

 

Sitemap