Andrew‎ > ‎Technology‎ > ‎

SiteCompiler (2000)

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

SiteCompiler 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.

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 this tool.

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

SiteCompiler came into existence due to my need for a program that offered similar features to "Server Side Includes" (SSI) directives used in many web servers for preprocessing static HTML files. These directives offer support for including other files, replacing variables with dynamic values, etc. My web hosting ISP did not support SSI, so I needed something like SSI directives that could be evaluated without a web server, and the rendered HTML files saved to files that could then be uploaded. SiteCompiler performs these directives in one fell-swoop, so that the web server does not need to parse HTML files.

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

No longer available for dowload.


Screen Captures





Directives

SiteCompiler supports many directives for text file manipulation. A directive is a command that will be interpreted by SiteCompiler when a file is being processed. They can generally begin anywhere on a line of text, but the line will not be present in the output file. A directive starts with a "#" character so that they can be easily recognized, but are not likely to appear in normal web (and mistakenly processed).

For file name arguments, the """ character can be used to surround the name if it contains whitespace. The file name must be separated from the directive by whitespace. Trailing whitespace and other characters after the file name are ignored as comments.

For variable name arguments, the variable name is found as the word separated by whitespace immediately after the directive. The value is separated by whitespace from the variable. It may contain whitespace, but trailing whitespace is ignored.

The directives are:

#include <file>
This directive allows for the inclusion of a file within another file. This is useful for including standard components of a page. The line containing the directive (at any location) is replaced with all lines of the specified text file.
#define <variable> <value>
This directive allows for the assignment of a variable. Any number of variables can be assigned, given that there are resource limits on your machine.

If the variable already is defined upon #define, the old value is not lost. A variable maintains a stack of values. This directive pushes new values onto the stack. With a matching #popdefine directive, the new value is removed, revealing the last value.

Variables are used in both replacements and in conditional tests (#ifdef, #ifndef). On future lines not containing other variable definitions, #ifdef, or #ifndef directives, a variable is replaced with its value. If the value contains a variable, it is also replaced. The process is repeated on a line until no replacements are made, or a few hundred replacements have been made and there seems to be an infinite loop. There are many predefined variables with useful values (see section title "Standard Variables").

#execute <command>
This directive executes the specified command (another program), and replaces the directive line with lines output by the program, if any. This directive can be used to setup files for testing or inclusion or to generate any sort of text as content in a page. Please note that using this directive makes your source files platform dependent. This directive has been renamed from the SSI equivalent due to massive maintenance headaches.
#undefine <variable>
With this directive, the value (or values) of the variable are completely removed, and the variable can no longer be used for replacements or in conditionals until redefined. It is generally recommended to use #popdefine instead.
#popdefine <variable>
This directive performs the inverse of #define, and was covered briefly in that section. This directive removes the current value of a variable to reveal the previously defined value. If the directive is used on a variable that only has one value left, the variable is completely undefined.
#ifdef <variable>
This directive is used to set up conditional sections of text. If the variable is set (has a value), then the lines of text between this directive line and the first line after it containing either a #else or #endif directive will appear in the output file.
#ifndef <variable>
This directive is the reverse of #ifdef, working only if the indicated variable does not have a value.
#ifexists <file>
This directive is similar to #ifdef, but is true only if the indicated file exists. The file may be in the current directory, the "includes" directory, or may be an absolute file name.
#ifnexists <file>
This directive is the reverse of #ifexists, and is true only if the indicated file does not exist.
#else
This directive ends a previous conditional directive. If the conditional evaluated to false, then the lines between this directive line and the next #endif directive line will be visible in the output. Having this directive negates the utility of having complementary conditional tests, but they do make the source easier to read.
#endif
This directive completely ends a conditional section of text, either from the last #else or conditional directive.

Standard Variables

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).

VariableValue
_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

SiteCompiler 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 SiteCompiler. I run it on both Windows and Linux machines.

Expand the file SiteCompiler-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 SiteCompiler. To run SiteCompiler, simply execute the file SiteCompiler-bin.jar (for example, double-click on the file in Windows).

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

Running SiteCompiler with no arguments invokes its Graphical User Interface.


User Interface

SiteCompiler 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 "SiteCompiler.properties" in the invoking user's home directory.

SiteCompiler 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

SiteCompiler 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:

SiteCompiler [-nogui] [-source <SOURCE_DIRECTORY>] [-include <INCLUDES_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.

-include <INCLUDES_DIRECTORY>
This optional argument specifies a directory to include
files from. The local directory of the file is searched
first, then the included directory is. The default is
the source directory.

-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 SiteCompiler without the GUI, you may specify all parameters to SiteCompiler on the command line. The addition of the "-nogui" parameter will cause SiteCompiler to not display the GUI, and will write logs to standard output. Be sure to invoke SiteCompiler with the java command rather than the javaw command to see logging output.