The Docbase kit (http://udell.roninhouse.com/examples/Docbase-1.0.tar.gz) includes the family of modules used in Chapter 6, and Chapter 7:
Essential CGI functions
Common definitions and functions for the Docbase system
Dynamic generation of input forms; previewing; validation; record storage
Convert meta-tagged headers into sequential and tabbed-index controls
Navigational controls for dynamically viewed Docbases
The kit also includes a set of templates for the ProductAnalysis docbase illustrated in the book, along with some sample records. Here is the complete list of files included in the kit:
MANIFEST Changes Makefile.PL test.pl Docbase.pm.safe lib/TinyCGI.pm lib/Docbase/Docbase.pm lib/Docbase/Input.pm lib/Docbase/Navigate.pm lib/Docbase/Indexer.pm cgi/ProductAnalysis/docbase-template.htm cgi/ProductAnalysis/dynamic-navigation-template.htm cgi/ProductAnalysis/dynamic-sequence-template.htm cgi/ProductAnalysis/form-template.htm cgi/ProductAnalysis/frame-template.htm cgi/ProductAnalysis/indexer.pl cgi/ProductAnalysis/seqinfo/seqinfo cgi/ProductAnalysis/static-sequence-template.htm cgi/ProductAnalysis/submit.pl cgi/ProductAnalysis/test.pl cgi/doc-nav.pl cgi/doc-view.pl cgi/final-submit.pl cgi/formgen.pl web/ProductAnalysis/docs/1999-06-24-000001.htm web/ProductAnalysis/docs/1999-06-24-000002.htm web/ProductAnalysis/idxs/idxs web/ProductAnalysis/seq/seq web/ProductAnalysis/style.css web/img/next.gif web/img/prev.gif
After unzipping and untarring the kit into a scratch directory, you follow the usual procedure for installing a Perl module:
perl Makefile.PL
make (nmake, for Win32 environments)
make test
make install
This script, which builds the makefile used to do the installation, asks for some details about your web server installation:
Absolute CGI path (default: /home/httpd/cgi-bin): /web/cgi Relative CGI path (default: /cgi-bin): /cgi Absolute Web path (default: /home/httpd/html): /web Relative Web path (default: )(nothing is ok): Web server running as user (default: nobody)(Unix only): Using these values: cgi_absolute: /web/cgi cgi_relative: /cgi web_absolute: /web web_relative: webserver running as: nobody Are you sure? This makefile will try to install scripts and templates based on these values. [N,y]:
The defaults are those for my Linux system running Apache. In this example, I’m installing on my NT system running IIS. The Docbase system needs to know both the absolute and web-server relative paths to the Web (that is, HTML document) and CGI (that is, script) areas on your server.
In this example, the Docbase-generic scripts will be copied to
/web/cgi/Docbase
, and the Docbase-specific
scripts will be copied to
/web/cgi/Docbase/Product-Analysis
.
This step assumes that you have a make tool on your system, which, in the Win32 world, many people do not. In that case, you can get a free copy of nmake at ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe.
This step runs a series of tests that try to validate that your installation went correctly. You should see output like this:
1..7 ok 1 Testing TinyCGI ok 2 Testing Docbase::Docbase ProductAnalysis.../web/cgi/Docbase...multi...ok 3 N...ok 4 Testing Docbase::Input ok 5 Testing Docbase::Navigate ok 6 Testing Docbase::Indexer ok 7 For further testing, try this URL: /cgi/Docbase/ProductAnalysis/test.pl after you have run 'make install'.
Part of the test script uses Docbase::Indexer to derive tabbed-index pages and sequential navigation controls from the two sample docbase records included with the kit.
The final message indicates that you can use your browser to try out these navigational mechanisms on the sample docbase—ProductAnalysis—that’s installed with the kit. But first, you have to complete the installation.
This step moves the Perl modules from the scratch directory to their official locations and builds one or more types of documentation, depending on your platform and configuration.
Note that once you’ve run make install, the perldoc command is one way to view the POD (plain old documentation) that’s built into a Perl module:
C:>perldoc Docbase::Input NAME Docbase::Input - Generate and process Docbase input forms. SYNOPSIS use strict; use TinyCGI; my $cgi = TinyCGI->new(); print $cgi->printHeader; my $vars = $cgi->readParse(); use Docbase::Docbase; my $db = Docbase::Docbase->new($vars->{app}); use Docbase::Input; my $di = Docbase::Input->new($db); $di->formGen($vars); AUTHOR Jon Udell, [email protected]
You can also try the test page
(/CGI_RELATIVE/Docbase/ProductAnalysis/test.pl
).
Figure 1.1 shows how that page should look in a
browser.
To make a new docbase, you start with the version of
lib/Docbase/Docbase.pm
that’s in your
scratch (build) directory. It contains this structure:
my $docbase_defaults = { 'ProductAnalysis' => { 'tabstyle' => 'multi', 'navstyle' => 'dynamic', 'indexed_fields' => ['company','product','analyst','duedate'], 'tab_functions' => { 'company' => $tabFnFirstChar, 'product' => $tabFnFirstChar, 'duedate' => $tabFnFirstSevenChars, 'analyst' => $tabFnAll, }, 'sort_specs' => { 'company' => 'ascending', 'product' => 'ascending', 'analyst' => 'ascending', 'duedate' => 'descending', }, }, 'AnotherDocbase' => {}, };
Suppose you want to make a status report docbase, with controlled
fields employee ,department, andweek_of. You might extend$docbase_defaults
by adding:
'StatusReport' => { 'tabstyle' => 'multi', 'navstyle' => 'dynamic', 'indexed_fields' => ['department','employee','week_of'], 'tab_functions' => { 'week_of' => $tabFnFirstSevenChars, 'employee' => $tabFnAll, 'department' => $tabFnAll, }, 'sort_specs' => { 'week_of' => 'descending', 'employee' => 'ascending', 'department' => 'ascending' } }
Do this to the copy of Docbase.pm
in your
scratch directory, then rerun make test and
make install.
Next, clone two subdirectories as follows:
CGI_ABSOLUTE/Docbase/ProductAnalysis
→
CGI_ABSOLUTE/Docbase/StatusReport
|
WEB_ABSOLUTE/Docbase/ProductAnalysis
→
WEB_ABSOLUTE/Docbase/StatusReport
|
Delete the contents of
WEB_ABSOLUTE/Docbase/StatusReport/docs
. Then
adapt the following scripts and templates to your new docbase:
CGI_ABSOLUTE/form-template.htm
This is the template for the input form.
CGI_ABSOLUTE/docbase-template.htm
This is the XML template for the stored record.
CGI_ABSOLUTE/dynamic-navigation-template.htm
This is the template for the tabbed-index controls.
CGI_ABSOLUTE/dynamic-sequence-template.htm
This is the template for the sequential controls used by the dynamic version of the viewer.
CGI_ABSOLUTE/submit.pl
This script validates input, classifies problems as warnings or errors, and invokes the previewer.
CGI_ABSOLUTE/indexer.pl
This script, which you’ll probably want to run on a scheduled
basis, updates the navigational indexes. You can omit the
buildStaticControls( )
call if you’re only
using the dynamic viewer.
CGI_ABSOLUTE/static-sequence-template.htm
This is the template for the sequential controls used by the static version of the viewer. Not needed if you’re only using the dynamic viewer.
CGI_ABSOLUTE/frame-template.htm
This is the template for the framesets that control the static version of the viewer. Also not needed if you’re only using the dynamic viewer.
Remember to use app=StatusReport
in the URLs that
operate on this docbase. For example, to add records to the
StatusReport docbase, you’d use a URL like this:
CGI_RELATIVE/Docbase/formgen.pl?app=StatusReport&employee=Jon+Udell