NAME

Apache::CGI::Builder - CGI::Builder and Apache/mod_perl (1 and 2) integration

VERSION 1.3

The latest versions changes are reported in the Changes file in this distribution. To have the complete list of all the extensions of the CBF, see "Extensions List" in CGI::Builder

INSTALLATION

Prerequisites

    Apache/mod_perl 1 or 2 (PERL_METHOD_HANDLERS enabled)
    CGI::Builder >= 1.2

CPAN

    perl -MCPAN -e 'install Apache::CGI::Builder'

You have also the possibility to use the Bundle to install all the extensions and prerequisites of the CBF in just one step. Please, notice that the Bundle will install A LOT of modules that you might not need, so use it specially if you want to extensively try the CBF.

    perl -MCPAN -e 'install Bundle::CGI::Builder::Complete'

Standard installation

From the directory where this file is located, type:

    perl Makefile.PL
    make
    make test
    make install

SYNOPSIS

   # use instead of the CGI::Builder
   use Apache::CGI::Builder
   qw| ... other inclusions ...
     |;
   
   # deprecated way of inclusion still working
   use CGI::Builder
   qw| Apache::CGI::Builder
       ... other inclusions ...
     |;
   
   # direct interaction with the Apache request object
   $r = $self->r ;
   %headers = $self->r->headers_in ;
   
   # virtual pages: instead of using this
   http://www.yourdomain.com/cgi-bin/IScript.cgi?p=a_page
   
   # you can use this
   http://www.yourdomain.com/a_page

DESCRIPTION

Note: You should know CGI::Builder.

This module is a subclass of CGI::Builder that supply a perl method handler to integrate your CBB with the Apache/mod_perl server: most of the interesting reading about how to organize your CBB are in CGI::Builder.

You should use this module instead of CGI::Builder if your application can take advantage from accessing the Apache request object (available as the r property), and/or to run your application in a handy and alternative way. If you don't need any of the above features, you can use the CGI::Builder module that is however fully mod_perl 1 and 2 compatible.

Note: An extremely powerful combination with this extension is the CGI::Builder::Magic, that can easily implement a sort of Perl Side Include (sort of easier, more powerful and flexible "Server Side Include").

IMPORTANT NOTE: If you use 'mod_perl2' (new namespace), you must use the Apache2::CGI::Builder module, installed with this distribution.

DIFFERENCES

This module implements a few differences with the regular CGI::Builder module:

Passing the page_name

In a regular CBA the page_name usually comes from a query parameter or from code inside your application (if you have overridden the get_page_name() method). Both ways are still working with this extension, but you have another way: use the base filename of your links as the page_name.

E.g.: Providing that the RootDirectory of 'yourdomain.com' has been correctly configured to be handled by your CBB:

Instead of using this (good for any regular CBA):

    http://www.yourdomain.com/cgi-bin/IScript.pl?p=a_page

You can use this:

    http://www.yourdomain.com/a_page

Same thing with more query parameters:

    http://www.yourdomain.com/cgi-bin/IScript.pl?p=a_page&myField=aValue
    http://www.yourdomain.com/a_page?myField=aValue

Note: Remember that this technique utilizes the default page_name. Default means that it is overridable by setting explicitly the page_name inside your code, or passing an explicit 'p' query parameter. (i.e. if you want to use the provided default, you have just to avoid to set it explicitly).

Warning: This extension sets the page_name property to the basename of the Apache filename variable, which is the result of the URI -> filename translation. For this reason, on some systems, the page_name could be not exactly the basename of the requested URI, and it could result in a string composed by all small caps characters, even if the requested URI was composed by all upper caps characters.

For example this URI:

    http:://www.yourdomain.com/aPage.html

could generate a page_name equal to 'apage' which probably does not match with your SH_aPage PH_aPage handlers, so in order to avoid possible problems, I would suggest the most simple and compatible solution, which is: always use all small caps for page names, templates names, page and switch handlers, URLs, ...

No Instance Script

A regular CGI::Builder application, uses an Instance Script to make an instance of the CBB. With Apache::CGI::Builder the Apache/mod_perl server uses the CBB directly (throug the perl method handler supplied by this module), without the need of any Instance Script.

Passing Arguments

You usually don't need to pass any argument to the new method, because this module internally creates the new object and executes the process at each request, but sometimes it may be useful to set some properties from outside the CBB. In order to do so, even if you don't have any instance script, you can however pass the arguments that your CBB needs from the Apache configuration files (see "Apache Configuration" for more details).

Apache Configuration

This module provides a mod_perl 1 and 2 compatible method handler which internally creates the CBB object and produce the output page, after setting a few properties.

Note: Since the provided handler is a method handler, your mod_perl must have PERL_METHOD_HANDLERS enabled in order to work. If your mod_perl is > 1.25 you can check the option by running the following code:

   $ perl -MApache::MyConfig \
   -e 'print $Apache::MyConfig::Setup{PERL_METHOD_HANDLERS};'
   1

The Apache configuration for mod-perl 1 or 2 is extremely simple. In order to use e.g. your FooBar.pm CBB from any .htaccess file or httpd.conf, you have to follow these steps:

1 tell mod_perl to load FooBar.pm

You can do this in several ways.

In the startup.pl file (or equivalent) you can simply add:

    use FooBar () ;

or you can tell mod_perl to load it from inside any configuration files:

    PerlModule FooBar

or if your FooBar.pm file is not in the mod_perl @INC this will work as well from any Apache configuration file:

   PerlRequire /path/to/FooBar.pm

2 tell mod_perl to use it as a (response) handler

The only difference between mod_perl 1 and 2 configuration, is the mod_perl handler name 'PerlHandler' that becomes 'PerlResponseHandler' for the version 2.

For mod_perl 1:

    SetHandler perl-script
    PerlHandler FooBar

For mod_perl 2:

    SetHandler perl-script
    PerlResponseHandler FooBar

Note: If you need to pass some arguments to the new object you can create and pass it as the handler:

   <perl>
       $My::Obj = FooBar->new ( my_param1 => 'value1' ,
                                my_param2 => 'value2' )
   </perl>
   
   SetHandler perl-script
   PerlHandler $My::Obj

3 restrict its use to fit your needs

Use the Apache configuration sections Location, Directory, DirectoryMatch, Files, FilesMatch etc. to restrict the use of the handler (see also the Apache Directive documentation)

   # example 1: httpd.conf
   # only if runs under mod_perl
   <IfModule mod_perl.c>
        PerlModule FooBar
        # limited to the dir /some/path
        <Directory /some/path>
            SetHandler perl-script
            PerlHandler FooBar
        </Directory>
   </IfModule>

   # example 2: /some/path/.htaccess file
   # only if runs under mod_perl
   <IfModule mod_perl.c>
        PerlModule FooBar
        SetHandler perl-script
        PerlHandler FooBar
   </IfModule>

Note: see also the /magic_examples/perl_side_include/.htaccess file in this distribution.

METHODS

This module adds a few internally used methods to your CBB. You don't need to use them directly, but you should know that they exist in order to avoid to unwittingly override them.

handler

Generic method used as a method handler dispatcher

PerlHandler

This method is used as the response method handler

PerlResponseHandler

PerlHandler alias used by mod_perl 2

OH_init

This method internally initializes the page_name, page_path, page_suffix defaults.

PROPERTY ACCESSORS

r

This is the only property added to the standard CGI::Builder properties. It is set to the Apache request object: use it to interact directly with all the Apache/mod_perl internal methods.

CBF changed property defaults

CBF page_name

The default page_name is set to the base name of the requested filename (e.g. being the requested filename /path/to/file.mhtml, the default page_name will be set to 'file'). This is an alternative and handy way to avoid to pass the page_name with the query.

Note:In case you have to handle a file with a multiple suffix like 'file.tar.gz' the page_name will be 'file'

CBF page_path

The default page_path property is set to the directory that contains the requested file.

CBF page_suffix

The default page_suffix property is set to the suffix of the requested filename (e.g. being the requested filename /path/to/file.mhtml, the default page_suffix will be set to '.mhtml').

Note:In case you have to handle a file with a multiple suffix like 'file.tar.gz' the suffix will be '.tar.gz'

CBF Overriding

CBF no_page_content_status

This extension overrides this class property by just changing the '204 No Content' (that the CBF sets when no page_content has been produced by the process), with a more consistent '404 Not Found' status. It does so because the client is requesting a simple not found page, which is a very different situation from a found CGI script that does not send any content (204 No Content).

Selfloading Perl*Handlers

The CBB that uses this module, will have a special feature: a sort of Selfloading of Perl*Handlers.

When you pass a CBB class (or an instance of the CBB) as a Perl*Handler, this module will use (as the method handler) the method called with the same name of the Perl*Handler. For example:

    PerlAnyHandler My::CBB

which normally would mean:

    PerlAnyHandler My::CBB->handler

get interpreted by this module as:

    PerlAnyHandler My::CBB->PerlAnyHandler

This means that if any extension needs to implement any handler, it could just define a Perl*Handler() method with the same name, and recommend the use of the CBB class as that particular Perl*Handler. This feature adds some encapsulation and simplify the use of the extension.

Note: the user could explicitly bypass this feature by using explicit method handlers e.g.:

    PerlAnyHandler My::CBB->AnySpecialHandler

SUPPORT

See "SUPPORT" in CGI::Builder.

AUTHOR and COPYRIGHT

© 2004 by Domizio Demichelis (http://perl.4pro.net)

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as perl itself.

cpanm Apache::CGI::Builder

perl -MCPAN -e shell
install Apache::CGI::Builder