Apache::Application::Magic - Apache/mod_perl integration for CGI::Application::Magic
Included in CGI-Application-Plus 1.21 distribution.
The latest versions changes are reported in the Changes file in this distribution.
The distribution includes:
CGI::Application::Plus
CGI::Application rewriting with several pluses
Apache::Application::Plus
Apache/mod_perl integration for CGI::Application::Plus
CGI::Application::Magic
Template based framework for CGI applications
Apache::Application::Magic
Apache/mod_perl integration for CGI::Application::Magic
CGI::Application::CheckRM
Checks run modes using Data::FormValidator
Apache/mod_perl 1 or 2 Perl version >= 5.6.1 OOTools >= 1.6 Template::Magic >= 1.0
perl -MCPAN -e 'install CGI::Application::Plus'
If you want to install also all the prerequisites to use CGI::Application::Magic), all in one easy step:
perl -MCPAN -e 'install Bundle::Application::Magic'
From the directory where this file is located, type:
perl Makefile.PL make make test make install
# 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
This module is a CGI::Application::Magic sub class that supply a perl handler to integrate your application modules with the Apache/mod_perl server.
The CGI::Application::Magic module is fully mod_perl 1 and 2 compatible, but the 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").
Note: most of the interesting reading of how organize your application module are in CGI::Application::Magic.
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 mod_include Apache module to process the pages, but you can configure it to process the pages by using your own Apache::Application::Magic based module, that can easily implement a lot of more custom 'directives' in the form of simple labels.
mod_include
In other words: your own 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 your application does not need to handle neither run modes, nor run methods, nor template managements: all that is auto-magically handled by the 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.
All the generic CGI applications (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 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.
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:
request
This property is set to the Apache request object. Use it to interact directly with all the Apache/mod_perl internal methods.
runmode
The default runmode is set to the base name of the requested filename (e.g. being the requested filename /path/to/file.mhtml, the default runmode will be set to 'file'). This is an alternative and handy way to pass the runmode.
tm_path
The default tm_path property is set to the directory that contains the requested file.
tm_suffix
The default tm_suffix property is set to the suffix of the requested filename (e.g. being the requested filename /path/to/file.mhtml, the default tm_suffix will be set to '.mhtml').
tm_template
The default tm_template property is set to the runmode property plus the tm_suffix as usual, so with the tm_path property, the requested file will be used as the template.
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 ;-).
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 to have it automagically set.
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, you have just to avoid to set it explicitly).
The Apache configuration for mod-perl 1 or 2 is extremely simple. In order to use e.g. your FooBar.pm Application module, you have to follow these steps:
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:
@INC
PerlRequire /path/to/FooBar.pm
In .htaccess file
For mod_perl 1:
SetHandler perl-script PerlHandler FooBar
For mod_perl 2:
SetHandler perl-script PerlResponseHandler FooBar
Note: In order to use this module, the only difference between mod_perl 1 and 2 configuration, is the mod_perl handler name 'PerlHandler' that becomes 'PerlResponseHandler' for the version 2.
'PerlHandler'
'PerlResponseHandler'
Use the Apache configuration sections Location, Directory, DirectoryMatch, Files, FilesMatch etc. to restrict the use of the handler (see also the Apache Directive documentation)
Location
Directory
DirectoryMatch
Files
FilesMatch
# 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 # limited to all files '*.mhtml' in dir /some/path <Files ~ \.mhtml$> SetHandler perl-script PerlHandler FooBar </Files> </IfModule>
Note: see also the /magic_examples/perl_side_include/.htaccess file in this distribution.
This module adds just one method to the standard CGI::Application::Magic methods.
This method initializes and returns the internal Apache::Application::Magic object. You can override it if you know what you are doing, or you can simply ignore it ;-).
Note: This method is here just if you need to override the way the module generates the object. Think about this method as it were an included Instance Script that creates the object by setting different properties and/or parameters. Anyway you have alternative methods to change the object properties, such as e.g. the setup() and cgiapp_init() methods.
This module adds just one property to the standard CGI::Application::Magic properties.
This property allows you to access the request Apache object.
If you need support or if you want just to send me some feedback or request, please use this link: http://perl.4pro.net/?Apache::Application::Magic.
© 2004 by Domizio Demichelis.
1 POD Error
The following errors were encountered while parsing the POD:
Non-ASCII character seen before =encoding in '©'. Assuming CP1252
To install CGI::Application::Plus, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::Application::Plus
CPAN shell
perl -MCPAN -e shell install CGI::Application::Plus
For more information on module installation, please visit the detailed CPAN module installation guide.