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:

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.

Figure A-1. Docbase installation test page

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:

Delete the contents of WEB_ABSOLUTE/Docbase/StatusReport/docs. Then adapt the following scripts and templates to your new docbase:

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