htmlPX: User's Guide

Introduction

htmlPX, the HTML Programmer's Extension, is a tool to help the user build and maintain their website. htmlPX is a command-line Java application that pre-processes HTML template files to create HTML files. It provides a way of creating consistent, well-designed websites easily. It also supports maintenance by making it easy to modify the template files and then regenerate the website. htmlPX was designed with the experienced power-user or programmer in mind.

The basic process is that variables are defined and values are assigned to those variables. Then HTML template files are processed and replacements are made based on keywords that match the variables. Colors, images, text, and formatting can be dependent on the values assigned to each variable. htmlPX also supports conditional generation based upon the values of the variables. Other files can be inserted into the HTML files as they are being generated so that true reuse of code can be achieved. This, of course, means that less HTML code actually has to be written. When the processing has completed, a set of HTML files have been generated that are ready to be put onto the web.

htmlPX Processing

To understand htmlPX, you must think of your website, many HTML files and assorted images and binary files, as a project. htmlPX is a utility that will generate the website from the files that make up the project. There are three types of files that make up an htmlPX project. They are:

the .SF file - the site file
.HTT files - the HTML template files
.LIB files - the code library files

The site file is really the project file. That file is passed to htmlPX where it serves as the driver behind the site generation process. The site file contains definitions of global variables that will be used by the site and the #MAKE commands that identify the HTML template files that need to be processed to generate the desired site. Each line in the .SF and the template files is checked to determine if it is an htmlPX command. htmlPX commands all begin with the '#'. If the line is a command, the command is processed. If the line is not a command, it is written to the output file.

One or more library files can be loaded by the site file. Each library file contains variable definitions, code block definitions, and function definitions. These defined "objects" can be used by any of the template files.

Each #MAKE command results in an HTML template file being processed and an HTML file being generated. Defined variables that are delimited by '{' in the front and '}' in the back are replaced by the value currently assigned to that variable.

You should read the Reference Guide for a more detailed description of each command.

A site file could look like the following:
#SET name Keith Wilson #SET color red #MAKE index.htt index.hmtl #MAKE second.htt second.html

Executing htmlPX

htmlPX is a command-line program, so you execute it from a command-line shell. A batch file is included as a sample, since it is easier to execute with a batch file. Using the batch file included, you can execute it with a command such as

htmlpx mysite.sf.

The complete format of the command is

htmlpx [-a] [var1 var2 var3 var4 var5 var6 var7]

where [-a] is an optional parameter that causes all output files to be remade regardless of dates. Var1 - var7 are optional variables that are passed to the templates as keywords #CL1 - #CL7. These can be used however you want within your htmlpx scripts. One suggested use is for conditional generation.

Sample Site

The help files, which you are now looking at, serve as a sample of the use of htmlPX. htmlPX was used to generate these help files. You can go to the subdirectory SAMPLE where you installed htmlPX to see the template files, the library file, and the site file used to generate these files. This is a rather simple example, but it serves as a reasonable starting place to begin learning the power of htmlPX.

Special Topics

Scope

Variables, code blocks, and functions can be defined in the site file, a library file, a template file, or an included file. The scope of the object varies depending on where it is defined. The rule is quite simple, an object is only available at the level it is defined and all levels below. Thus, a function defined in the library file is available for all template files and all included files that the template files access. A code block defined in an included file will only be available in that template file, and will go out of scope and " disappear" when that template file is completed.

An object can be overridden by a definition at a lower level. When the new definition goes out of scope, the previous value or definition will be available once again.

Placing Variables, Code Blocks, and Functions in Template Files

Variables, code blocks, and functions can be defined in template files as well as library files. When they are defined in template files, they are only available for that template file and will go out of scope when that file is completed.

Processing Data Files

ASCII text files can be processed as data files using the #FORALL/#ENDLOOP commands. Each row in the data file will be processed in succession. The fields in each row will be parsed and can be accessed by the code in the block by referring to them as {$1}, {$2}, etc.

Which Output Files are Made?

htmlPX has a make facility which allows HTML files that do not need to be remade to be skipped. This makes it quicker to regenerate a site that has only a few changes in one or more template files. You can cause all HTML files to be made by placing a '-a' parameter as the first parameter passed to htmlPX. Please also read in the Reference Guide about #USING to see more on the make facility.