Andrew‎ > ‎Technology‎ > ‎

SiteTransformer (2002)

SiteTransformer is a web-authoring tool that allows for creation and maintenance of large websites. SiteTransformer is a static template engine that allows for standardization of a website's look and feel, preprocessing source files into output files (usually HTML) that can then be transferred to a web server for proper viewing.

SiteTransformer is based on a simple concept: writing in shorthand. A web-author is given a simple language for mixing files together to produce a website. Any given page needs only to consist of the real content necessary for that page, decorated with a fiew shorthand annotations. On compilation, the shorthand is resolved into the indicated text, ready for publication.

All of the heavy lifting in SiteTransformer is done by the Apache project's Xalan Java 2 and Xerces Java 2 XML engines. The "skinning" of a site is performed via a process known as XSLT.

In XSLT, you code a source document and a stylesheet document. The XSLT engine takes both source and stylesheet documents and generates the output document. The source document is an XML document of any schema you choose. The stylesheet document is an XML document with stylesheet element of the proper schema (http://www.w3.org/1999/XSL/Transform). The stylesheet describes how to transform the source document into the output document, which can be any sort of text document that you choose. I recommend that you define a schema for your source document so that it may be validated, and structure your site so that your transform can be pluggable to reskin your site.

SiteTransformer is based on an earlier effort, SiteCompiler, which involved a custom template engine. SiteCompiler used "Server Side Includes" (SSI) style directives, rather than XSLT for page transformation, leaving the source and output documents unvalidated for well-formedness and content. If you are the type of web-author that prefers to code in plain HTML, SiteCompiler is meant for you. If you use another authoring tool, but occasionally need "search and replace" functionality or insertion of dynamic values at the time of publishing, you should definitely look into that tool.

Although intended for website authoring, the text manipulations provided by SiteTransformer can be applied to any sort of text file.

For an example website that uses SiteTransformer, see the page describing construction of my site at http://barkley.info/andrew/technology/siteconstruction.html.

The rest of this document assumes that you are familiar with XSLT. The following references are helpful in learning XSLT:

No longer available for download


Screen Captures






Standard Parameters

The following is a listing of the predefined variables and a description of their values. predefined variable names start and end with a "_" character so that they are easy to identify, and will not likely appear in normal content (and be mistakenly processed). To use a parameter, first reference it in your stylesheet with an element of the format:

<xsl:param name="_DEST_NAME_"/>

where "xsl:" identifies the XSL namespace, if necessary, and "_DEST_NAME_" is an example parameter name. You may use the optional "select" attribute of the param element to specify an xpath to the default value for the parameter, which may be useful if you plan to also use your transform with a tool other than SiteTransformer that does not offer these parameters.

You include the value of the parameter with an element of the following format:

<xsl:value-of select="$_DEST_NAME_"/>

Where again "_DEST_NAME_" is an example parameter name. Here is a listing of the parameters afforded to you by SiteTransformer:

Parameter Value
_DEST_NAME_ The destination file name for the page being processed.
_SOURCE_NAME_ The source file name for the page being processed.
_SOURCE_DATE_ The source file modification time in the format like: "January 12, 1952"
_SOURCE_SHORT_DATE_ The source file modification time in the format like: "12.13.52"
_SOURCE_MEDIUM_DATE_ The source file modification time in the format like: "Jan 12, 1952"
_SOURCE_LONG_DATE_ The source file modification time in the format like: "Tuesday, April 12, 1952 AD"
_SOURCE_TIME_ The source file modification time in the format like: "3:30:32pm"
_SOURCE_SHORT_TIME_ The source file modification time in the format like: "3:30pm"
_SOURCE_LONG_TIME_ The source file modification time in the format like: "3:30:42pm PST"
_SOURCE_MONTH_ The source file modification month.
_SOURCE_WEEKDAY_ The source file day of the week.
_SOURCE_DAY_ The source file modification day of the month.
_SOURCE_YEAR_ The source file modification year.
_CURRENT_DATE_ The current time in the format like: "January 12, 1952"
_CURRENT_SHORT_DATE_ The current time in the format like: "12.13.52"
_CURRENT_MEDIUM_DATE_ The current time in the format like: "Jan 12, 1952"
_CURRENT_LONG_DATE_ The current time in the format like: "Tuesday, April 12, 1952 AD"
_CURRENT_TIME_ The current time in the format like: "3:30:32pm"
_CURRENT_SHORT_TIME_ The current time in the format like: "3:30pm"
_CURRENT_LONG_TIME_ The current time in the format like: "3:30:42pm PST"
_CURRENT_MONTH_ The current month.
_CURRENT_WEEKDAY_ The current day of the week.
_CURRENT_DAY_ The current time day of the month.
_CURRENT_YEAR_ The current year.

Installation

SiteTransformer is a Java application, and requires a Java virtual machine to run. I recommend Sun's JRE Version 1.3.1 (available at http://java.sun.com/j2se/1.3/jre/). You may already have a compatible Java VM installed. Any computer that supports a Java virtual machine of at least version 1.3 should be capable of running SiteTransformer. I run it on both Windows and Linux machines. JRE version 1.4 comes bundled with its own XML engine which is an earlier release than the one bundled with this application. It is not recommended to use JRE 1.4 at this time.

Expand the file SiteTransformer-dist.jar from the distribution zip file to a well-known place. The JRE associates with JAR files (Java ARchives) so that they can often be run as executables. This is the case with SiteTransformer. To run SiteTransformer, simply execute the file SiteTransformer-bin.jar (for example, double-click on the file in Windows).

Executing the file will usually translate to invoking the command "javaw -jar SiteTransformer-bin.jar" in your virtual machine. The main class of the file is org.andrewbarkley.sitecompiler.SiteTransformer, just in case you are needing a little more control.

Running SiteTransformer with no arguments invokes its Graphical User Interface.


User Interface

SiteTransformer has both a graphical and command-line user interface. Settings are automatically loaded and saved upon each invocation of the program. They are saved in the file "SiteTransformer.properties" in the invoking user's home directory.

SiteTransformer requires you to create your own source files using your own conventions. The user interface supplies you with a means of specifying the locations of these source files, and the convention for naming destination files based on the source. You must understand the convention well to reference HTML files in the unprocessed source files (usually for linking). A source file is designated as a file with a particular ending of its name, known as the extension. This extension is replaced with the extension for destination files when creating the destination file's name. The default source extension is ".src" and the default destination extension is ".html".

Arguments

SiteTransformer accepts command line arguments to customize its behavior. These arguments can be used to override saved settings in the user's configuration file. They are given by the following:

SiteTransformer [-nogui] [-source <SOURCE_DIRECTORY>]
[-recurse] [-source_extension <EXTENSION>]
[-dest_extension <EXTENSION>] [-help]

DESCRIPTION
Invoke the class with the virtual machine, and append the
following arguments as specified.

-nogui
This optional argument causes the GUI to not appear
and all logging goes to standard output.

-source <SOURCE_DIRECTORY>
This optional argument indicates either a single file
to process, or a root directory from which files
of the specified source extension will be found.

-recurse
If supplied, all subdirectories of the source directory
will be searched for source files. This means
nothing if the source is a single file.

-source_extension <EXTENSION>
Optionally supply the file extension of source files
(include a period for best matches.

-dest_extension <EXTENSION>

Optionally supply of the file extension of the destination
files. The destination file name will be the source file
name with the source extension replaced with the destination
extension.

-help
Displays this message.

Graphical User Interface

Almost all of the program arguments may be otherwise selected in the GUI window. Use the tool tips available on mouse-over for details.

Command Line User Interface

If you prefer to run SiteTransformer without the GUI, you may specify all parameters to SiteTransformer on the command line. The addition of the "-nogui" parameter will cause SiteTransformer to not display the GUI, and will write logs to standard output. Be sure to invoke SiteTransformer with the java command rather than the javaw command to see logging output.