[% TAGS [** **] -%]
=head1 DYNAMIC CONTENT GENERATION VIA APACHE/MOD_PERL HANDLER

NOTE: This section currently only exists in bare-bones form.  It will be
fleshed out RSN.

The Template module can be used in a similar way from an Apache/mod_perl
handler.  Here's an example of a typical Apache F<httpd.conf> file:

    PerlModule CGI;
    PerlModule Template
    PerlModule MyOrg::Apache::User

    PerlSetVar websrc_root   /home/abw/websrc

    <Location /user/bin>
        SetHandler     perl-script
        PerlHandler    MyOrg::Apache::User
    </Location>

This defines a location called '/user/bin' to which all requests will
be forwarded to the handler() method of the MyOrg::Apache::User
module.  That module might look something like this:

    package MyOrg::Apache::User;
    
    use strict;
    use vars qw( $VERSION );
    use Apache::Constants qw( :common );
    use Template qw( :template );
    use CGI;
    
    $VERSION = 1.59;
    
    sub handler {
    	my $r = shift;
    
    	my $websrc = $r->dir_config('websrc_root')
    	    or return fail($r, SERVER_ERROR,
    			   "'websrc_root' not specified");
    
    	my $template = Template->new({ 
    	    INCLUDE_PATH  => "$websrc/src/user:$websrc/lib",
    	    PRE_PROCESS   => 'config',
    	    OUTPUT        => $r,     # direct output to Apache request
    	});
    
    	my $params = {
    	    uri     => $r->uri,
    	    cgi     => CGI->new,
    	};
    
    	# use the path_info to determine which template file to process
    	my $file = $r->path_info;
    	$path =~ s[^/][];
    
    	$r->content_type('text/html');
    	$r->send_http_header;
    	
    	$template->process($path, $params) 
    	    || return fail($r, SERVER_ERROR, $template->error());
    
    	return OK;
    }
    
    sub fail {
    	my ($r, $status, $message) = @_;
    	$r->log_reason($message, $r->filename);
    	return $status;
    }

The handler accepts the request and uses it to determine the 'websrc_root'
value from the config file.  This is then used to define an INCLUDE_PATH
for a new Template object.  The URI is extracted from the request and a 
CGI object is created.  These are both defined as template variables.

The name of the template file itself is taken from the PATH_INFO element
of the request.  In this case, it would comprise the part of the URL 
coming after '/user/bin',  e.g for '/user/bin/edit', the template file
would be 'edit' located in "$websrc/src/user".  The headers are sent 
and the template file is processed.  All output is sent directly to the
print() method of the Apache request object.


