Static Site Builder Util (SBU) 1.0 Documentation

Index Introduction File Filters File Handlers Default Source Parser Data Providers Extending SBU

Introduction

What is the Static Site Builder Util (SBU) for?

The basic idea was this: Having a static web site represented as a set of HTML files - how to a add a navigation menu that is controlled locally? Usually you would add the menu to each page, adapting the contained links' to related files (other menu items) if a change occurs.

The first version of Static Site Builder Utils (called "Site Navigator") did this concentrating on the navigation menu items. Basically a navigation structure was defined that linked each item to an HTML page. Each HTML file was parsed and the relevant part was processed with a layout that could use both information parts. Binary parts could be copied. In a later version the FREEMARKER JAVA library was used for the transformation process - allowing more flexible control over the layout by defining the template file (on the cost of a bit more of complexity).

The current version has much more power but is still related to the initial idea. You will put your source (eg. HTML) and binary (e.g. images, CSS) files into the source folder. Static Site Builder produces a copied and/or transformed set of files from a source folder ("src"). The resulting files will be stored in the output folder ("out"). Work process configuration files (eg. templates) are located in a different resource folder ("resource"). The actual configuration defining the overall transformation process is an XML file located in the parent folder of those folders - or in other words: the three folders are sub directories of the configuration file's folder.

How it works

The used path format to a specified source, resource or output file is '/{relative sub path from related folder, path separator is '/', closed with '/'}{file name}'. Related folders can be either the source folder (reading), the resource folder (reading) or the output folder (writing/replacing!). Example: '/subfolder/file.htm'.

Since switching from the old project "Site Navigator" the configuration has become more abstract to allow a better possibility to extend functionality by plug-ins. The configuration provides a list of instructions. Each instruction consists of two types of information:

For each file within the source folder and its sub folders the sequence of instructions will be scanned for a first matching file filter. If there is one - the related file handler will transform the source file and write the corresponding output file. It might use custom configuration files (eg. FTL templates) from the resource folder and its sub folders.

Instructions are specified by the XML configuration file. The format definition for the build-in system is offered as an XSD: sbu-configuration-1.0.xsd. XML elements correspond to JAVA classes and properties. A JavaDoc (the API documentation) is offered. It will provide important information besides the XSD structure. The following example is a basic configuration:

<?xml version="1.0" encoding="UTF-8"?>
<sbu-configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="file:./sbu-configuration.xsd">
    
    <instruction>
        <filter-chain>
            <suffix-filter suffix="htm"/>
        </filter-chain>
        <ftl-file-handler>
            <layout-template>layout.ftl</layout-template>         
        </ftl-file-handler>        
    </instruction>
    
</sbu-configuration>
	

Only .htm files will be handled by the the FREEMARKER layout file (resource/layout.ftl). Because this is the only instruction all other source files will be ignored. The XSD is expected in the configuration file's folder.

Running SBU

SBU is a JAVA program running on JDK 1.5+. The distribution archive comes with the JAR, the used library JARs, the configuration XSD, a CASTOR configuration file (relevant for writing extensions) and documentation files. Expecting the JAVA path to be in your evironment SBU and that a configuration file 'congig.xml' is in the same folder as the program main JAR 'sbu.jar' and the lib sub folder:

	java -jar sbu.jar ./config.xml

This reads files from folders 'src' and 'resource' and writes resulting files in a sub folder 'out' - the given configuration matching the provided XSD. The configuration file is the root folder for proccessing.

On default UTF-8 will be the used charset during parsing the configuration file. Another encoding can be forced by an optional second argumet matching a JAVA charset String:

	java -jar sbu.jar ./config.xml ISO-8859-15

This version only has console support. All results are also written in a file 'logs/sbu.log'. This file will be versioned for a large amount of time. The information consists of logging output. The related library is Log4J 1.2. A custom LOG4J configuration may be used by defining a system variable 'log4j.configuration' pointing to a valid LOG4J configuration file. This property can also be set as JVM paramter:

	java -Dlog4j.configuration=file:<path to configuration file> -jar sbu.jar ./config.xml
previous page next page