1. Pike's Website Compiler (Perl HP) Info
Perl HP was written to create pre-processed and template driven websites. In some ways it is like php in that you can jump in and out of perl code at anytime during the reading of files. It was originally meant to be somewhat understandable to a non-techies (or even techies) but was a miserable failure in that regard. Instead, it's overpowered for a small site and requires knowledge of XML, Perl and HTML to use.
In its defense, this is the tool that allows me to maintain and update this site effortlessly. It outputs the rss feeds automatically based on the XML sitemap. I gave up trying to make the tool entirely XML based as there was very little point to doing that. Only the website definition is in XML.
2. Basic Setup
The included files and folders with the compiler are set up so you can parse the example file. Open a terminal window and ensure your working directory is the webcc directory and type in perl webcc.pl to compile the example file. webcc.pl sets up the compile engine and passes control to the engine to handle rendering. Typing in perl webcc.pl -help-help will output everything you need to know about how to envoke it.
3. Setup API
The engine has several functions that allow you to setup the program. Simply edit webcc.pl to change how it configures the engine. Defaults are shown to the right of the function name. Calling any of these function without any parameters returns the variable instead of setting it.
rootDir( String ) |
./ |
|
All files and folders are relative to this directory unless they start with a '/'.
| |
gParamFile( String ) |
gparameter.txt |
|
Location of global substitution file.
| |
websiteDefFile ( String ) |
site.xml |
|
Location of the xml site definition file.
| |
templateFolder ( String ) |
templates/ |
|
Location of the folder containing the templates.
| |
htmlFolder ( String ) |
output/ |
|
Location of the folder containing the files which have substitutions which are performed on the templates to create the output files.
| |
outputFolder ( String ) |
output/ |
|
Where the output files are placed.
| |
my $compiler = WebccEngine->new();
$compiler->rootDir("/Users/foobar/Documents/Homepage/");
$compiler->gParamFile ("gparameter.txt");
$compiler->websiteDefFile ("site.xml");
Omit the rootDir call if you want everything to be relative to the current working directory. All directories need a final /. All files and folders are relative to the directory set with rootDir(...) if they do not start in a / or ./.
4. Website Definition File
The definition file is an XML file which tells PerlHP the structure of the website. This file allows the setting of options, the template used for each file, the path to the files and more. The Perl based XML parser used is non-validating (and only understands very simple XML).
The path attribute is the path to the substitution file. Thi
Notes:
5. Template Files
A template is simply a file containing substitution placeholders and other text. When the template is parsed the text is written to an output file and the substitution placeholders are replaced with the substitutions. Substitution placeholders (_pageTitle_ and _pageBody_) are shown in the next example.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html> <head> <title>_pageTitle_</title> </head> <body>return '_pageBody_'; </body> </html>
6. Substitution Files
Substitution files are fairly simple. Substitutions are declared by starting a line (ie: no spaces or tabs or other white space at the beginning) with a name (consisting of any combination of letters) followed by an =. Everything after the equals sign is part of that substitution. Substitution placeholders can be placed in a substitution file as well, but, the substitution must be pre-declared.
Substitution placeholders with the ending .mod are reserved for on-the-fly substitutions and ones beginning with webcc- are reserved for predefined substitutions.
There are five types of substitutions your templates and substitution files can use. They are listed below in order of their precedence with later ones masking earlier ones if a substitution of the same name exists at two different levels.
title=Website Compiler
caption=Perl HP
keywords=website, preprocessor, pre, processor, xml, webpage
description=A html pre-processor for template driven websites.
headParam=<style type="text/css">
.apiExp {
width:100%;
margin-left:auto;
'include=' is reserved for including files with additional substitutions. Useful for have a group of substitutions common across a set of files. The included file is immediately parsed and its substitutions are placed into the template before continuing.
A useful trick is for the included file to contain substitution holders for substitutions in the file that included it. This creates a template within the template.
7. Predefined Substitutions
Program Specific
Substitution | Description |
| webcc-author | The author of the compiler |
| webcc-version | Version number of compiler |
| webcc-releasedate | Release Date of compiler |
| webcc-compiletime | Compile time |
| webcc-website | Website definition file path |
File Specific
Substitution | Description |
| webcc-timeStamp | The last time the file was modified |
| webcc-currentName | File title of currently parsing file |
| webcc-currentFile | File path of currently parsing file's parent (if one exists) |
| webcc-parentName | File title of currently parsing file's parent (if one exists) |
8. Website Structure Substitutions
Substitution | Description |
| webcc-htmlStruct | Indented list of files showing the website's structure |
| webcc-menuStruct | Drop down based file list. (Requires additional JavaScript code to work) |
function formHandler(form){
var URL = document.form.site.options[document.form.site.selectedIndex].value;
window.location.href = URL;
}
9. On-the-fly Substitutions
Substitution | Description |
| list.filepath.mod | Lists the node's children of the node with the path attribute the same as filepath. |
| num.plus.name.mod | A counting variable. Starts at 0 and increases by 1 and returns the incremented value every time the substitution is used. |
| num.minus.name.mod | A counting variable. Starts at 0 and decreases by 1 and returns the decremented value every time the substitution is used. |
| num.zero.name.mod | A counting variable. Resets the value to zero. Returns nothing. |
All .mod ending substitutions are reserved for on-the-fly substitutions.
10. Perl Coding
Anything inside <perl> tags in a template or any substitution file is interpreted as Perl code. The returned value is substituted for the perl tags.
11. Download - Version 1.1!
See version history page.