Web Tool Programmer's Guide
I. The Perl Database
II. The CGI Interface
III. Web Tool Editor Execution Loop
IV. Perl References
This is a basic overview of some of the internal functionality. In addition, the AdminGuide.html file describes how to create template files.
I. The Perl Database
Web Tool uses a Perl hash-of-hashes structure to store the data during the
editor session. The quickest way to understand how Web Tool works is to look
at the perl database file: it's a text file that represents all the data in
a Perl hash-of-hashes structure. It's in the cgi-bin/WebTool/Data directory,
and is named after your BASE_TITLE. So if you're BASE_TITLE is 'Test Name' then
the Perl database file would be cgi-bin/WebTool/Data/TestName.pm.
A Perl Hash Overview
A hash is a collection of keys/value pairs:
my %myHash;
$myHash{'a string for a key'} = 'a string value';
$myHash{thisisatest} = 10;
$myHash{5555} = $any_variable;
etc.
The key is within the brackets, the value is what the variable gets assigned
to. Every key has a value, and vis-versa. Values and keys can be strings or
numbers (only strings with whitespace need quotes). Hashes are also called
associative arrays, and aren't specific to Perl, but Perl implements them in a
way that maximizes their utility:
1) A hash has a key and a value, but that value can be a reference to
another hash, which can have keys that reference yet another hash and so
on. This is written in Perl as:
$myHash{vehicles}{pickups}{chevy}{S10}{1991}{comments} = 'a test of perl
hashes';
So this one line of Perl creates a structure where each name in the
curly braces corresponds to a hash key, and the value of that key is a reference to another Perl hash key. This also demonstrates
2) Perl hashes can create deep structures out of thin air. By
this I mean that each level of the structure above did NOT need to be
initialized beforehand. The non-Perl way of doing the above example might
be:
$myReference = $myHash{vehicles};
$myNextRef1 = $myReference{pickups};
$myNextRef2 = $myNextRef1{chevy};
So Perl always you to create an instance of a variable anywhere in the
data structure, even if any or all of the sub-hashes do not exist.
$myHash{vehicles}{pickups}{chevy}{S10}{1991}{comments} = 'a test of perl
hashes';
The hash keys of 'vehicles' (or any of the other sub-hashes) may or may
not have already existed; it doesn't matter; Perl will either create it or
use what is already there.
I should mention that there are a number of different ways to reference a Perl hash, many of them are different ways of doing the same thing. As a single example (there are many more variants):
This:
my $ref = \%myHash;
$comment = $ref->vehicles->pickups->chevy->S10->1991->comments;
Is the same as this:
$comment = $myHash{vehicles}{pickups}{chevy}{S10}{1991}{comments};
3) Perl does not have any size limits. Each level of the
hash-of-hashes
structure can have an infinite number of entries, and can be infinitely
deep... limited by the memory of your system, of course, but no other
internal limitations. Strings (including the key values) can also be
infinitely large.
So this hash entry is completely valid:
$myHash{'Perl does not have any size limits. Each level of the
hash-of-hashes structure can have an infinite number of entries, and
can be infinitely deep'} = '... limited by the memory of your system,
of course, but no other internal limitations. Strings (including the
key values) can also be infinitely large.';
This would work even if the string was 10 megabytes long, and the system had over 10 megabytes of memory available for the Perl process. This type of functionality isn't theoretical, it's been tested, and it works. An entire web page can be put in a single string and be pointed to by a deep structure of perl hash keys where each key represents where that page exists on the web site. This is exactly what Web Tool does.
Web Tool user creates a link structure that is exactly duplicated by the
structure of the Perl hash-of-hashes structure. The link names on the
editor page are the hash keys. When you browse the link structure in your
web browser, you are actually browsing through the Perl database structure.
So the web page content:
$myHash{vehicles}{pickups}{chevy}{S10}{1991}{content} =
' < HTML > < HEAD >
< /HEAD >
< BODY >
< /BODY >
< /HTML > '
;
can be found in:
baseWebToolDir/vehicles/pickups/chevy/S10/1991/1991.html
after the 'end session' button is pressed.
When the user adds new content or a new link, the Perl database file is
rewritten with the new info and the page is marked as modified.
II. The CGI Interface
A simple overview:
The URL to a CGI script executes the script on the server and
prints the standard output of the program to the web
browser screen. So the content of every 'print' statement
appears in the web browser.
Input from the user is passed to the script via environment
variables, which are parsed and put into a single hash of name-value
pairs.
Perl/CGI script such as Web Tool work by simply re-executing the script
over and over each time the user clicks on a button. Each button submits a
different value, and the script reads the input to determine which
operation was requested.
This is a very inefficient in that a unix process is started, the
entire program is read from disk, Perl 'compiles' the code, and the code
is executed... each time you click on a button.
But the fact is that even with fairly large programs this all takes
place in a fraction of a second. Web Tool is a very large program relative
to most Perl/CGI scripts. But the response time is very fast. Avoiding Perl
because of 'speed' is solving a problem that doesn't exist.
As a site grows larger, the CGI response will begin to degrade, but 1)
this only applies to the editor session, not the finished HTML pages, which
are static files, and 2) mod_perl completely solves this CGI response
problem, and apache servers are relatively easy to configure with mod_perl
enabled (if you can install Apache, you can install Apache with mod_perl).
III. Web Tool Editor Execution Sequence
When the script is initially called, the perl database is read in from
the cgi-bin/WebTool/Data directory. It is named after the BASE_TITLE
configured in cgi-bin/WebTool/Config/wtConfig.pm. So if your BASE_TITLE is
'Chico Digital', the database file would be Data/ChicoDigital.pm.
The ChicoDigital/LinkMethods.pm package is the direct interface to this
data structure. All data is referenced via an object derived from
LinkMethods.pm.
So, a basic overview of the execution sequence of Web Tool:
1) The default editor page is printed out using the HTML template
toolPage.html. The editor page is a form where all the buttons
submit a single command value back to the script.
2) The script reads the input parameter variables and determines
what operation is requested.
Here are the main operations:
- navigate to another page
- save the current page and preview HTML
- delete the current page
- end the edit session
Navigate to another page
The page is selected by specifying a path on the query string.
The path is a list of keys that point to the current page in the Perl
hash structure that was originally read from the database file.
This path information string, $FORM{path}, is passed to
FormMethods::setPath($FORM{path}) which calls
ChicoDigital::LinkMethods->new($baseRef,$DELIMITER,$globalPath) to
create a LinkMethods object.
All further reference to the LinkMethods object will use this path
information to reference the hash that represents the current page.
The page selected by the $FORM{path} is printed out to the browser
screen using data from WebTool::FormMethods::getHTMLStrings(), and the
template found in Templates/toolPage.html.
Save the current page and preview HTML
The form data, which includes the text body and new
links, is written to the perl database file using the current
LinkMethods object. Then the current page reference is handed to
HTMLWriter.pm module, which uses the template
Templates/contentPage.html to create an HTML file in string format,
which is sent to the browser screen with a print statement.
Delete the current page
The current page reference is used to point to the correct entry
in the perl database. That entry is deleted and the database file is rewritten. The editor page is redisplayed with the new database file.
End the Edit Session
Before this operation, all the page data and link modifications
exist only in the Perl database; no HTML files have been
created.
This operation writes all HTML files using using the current
database information. The $CONTENT_DIR
and $CONTENT_URL point to the directory where the new pages will be
written. This operation traverses the data structure and
for every hash that represents an HTML page, writes the corresponding
hard HTML file using the specified template file in Templates/user/.
The entire perl hash is traversed by a loop that iterates on itself to
descend to the next level down. At each page level, the content is
rewritten to the directory specified by it's location in the Perl hash
structure. All modified pages are written as static HTML using the appropriate template file.
This operation creates a directory structure on disk
that corresponds to the link structure created by the user.
IV. Perl References
Here are some Perl documents on the web that help explain OO syntax and
Perl hash data structures.