view release on metacpan or  search on metacpan

lib/Apache/Application/Magic.pm  view on Meta::CPAN

=back

=head1 INSTALLATION

=over

=item Prerequisites

    Apache/mod_perl 1 or 2
    Perl version    >= 5.6.1
    OOTools         >= 1.6
    Template::Magic >= 1.0

=item CPAN

    perl -MCPAN -e 'install CGI::Application::Plus'

If you want to install also all the prerequisites to use C<CGI::Application::Magic>), all in one easy step:

    perl -MCPAN -e 'install Bundle::Application::Magic'

=item Standard installation

From the directory where this file is located, type:

    perl Makefile.PL
    make
    make test
    make install

=back

=head1 SYNOPSIS

   # use instead of CGI::Application::Magic
   use base 'Apache::Application::Magic';
   
   # direct interaction with the Apache request object
   $r = $self->request ;
   %headers = $r->headers_in ;
   
   # Perl Side Include
   # instead of using this link
   http://www.yourdomain.com/cgi-bin/appScript.pl?rm=aMtFile
   
   # you can use this
   http://www.yourdomain.com/aMtFile.mhtml

=head1 DESCRIPTION

This module is a C<CGI::Application::Magic> sub class that supply a perl handler to integrate your application modules with the Apache/mod_perl server.

The C<CGI::Application::Magic> module is fully mod_perl 1 and 2 compatible, but the C<Apache::Application::Magic> module supplies an easy implementation of a sort of "Perl Side Include" (sort of easier, more powerful and flexible "Server Side Include...

B<Note>: most of the interesting reading of how organize your application module are in L<CGI::Application::Magic>.

=head2 Perl Side Include

SSI (Server Side Includes) are directives that are placed in HTML pages, and evaluated on the server while the pages are being served. The Apache server uses the C<mod_include> Apache module to process the pages, but you can configure it to process t...

In other words: your own C<Apache::Application::Magic> based module transparently process the pages of a web dir, supplying the dinamic content that will be included in the page just before they are served.

With this technique B<your application does not need to handle neither run modes, nor run methods, nor template managements>: all that is auto-magically handled by the C<Apache::Application::Magic> super class.

Please, take a look at the 'perl_side_include' example in this distribution to understand all the advantages offered by this technique.

=head2 No Instance Script needed

All the generic CGI applications I<(old, Plus and Magic)>, use an Instance Script to call the Application Module. The script is usually like this:

    #!/usr/bin/perl -w
    use MyWebApp;                   # the Application module
    my $webapp = MyWebApp->new();   # create a new instance
    $webapp->run();                 # run and produce the output page

With C<Apache::Application::Plus> the Apache/mod_perl server will use the Application module directly (throug the perl handler supplied by this module), without the need of any Instance Script.

=head2 The Perl Handler

This module provide a mod_perl 1 and 2 compatible handler that internally creates and run() the Application object, after setting the following object properties:

=over

=item * request

This property is set to the Apache request object. Use it to interact directly with all the Apache/mod_perl internal methods.

=item * runmode

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

=item * tm_path

The default C<tm_path> property is set to the directory that contains the requested file.

=item * tm_suffix

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

=item * tm_template

The default C<tm_template> property is set to the C<runmode> property plus the C<tm_suffix> as usual, so with the C<tm_path> property, the requested file will be used as the template.

=back

B<Note>: Usually you don't need to use neither the perl handler nor these properties, because they are all internally managed. Just write the lookup-related code in your application, and let the default do their job by ignoring them ;-).

=head2 How to pass the runmode

In a generic CGI Application the run mode usually comes from a query parameter or from code inside your application. Both ways are still working with this module, but you don't need to pass the runmode anymore: just link the template files toghether ...

B<Note>: Remember that this technique utilize the default runmode. Default means that it is overridable by setting explicitly the runmode inside your code, or passing an explicit 'rm' query parameter. (i.e. if you want to use the provided default, yo...

=head1 Apache configuration

The Apache configuration for mod-perl 1 or 2 is extremely simple. In order to use e.g. your F<FooBar.pm> Application module, you have to follow these steps:

=over

=item 1 tell mod_perl to load FooBar.pm