Apache2-Controller

 view release on metacpan or  search on metacpan

README.txt  view on Meta::CPAN

Apache2-Controller

fast MVC-style Apache2 mod_perl2 handler app framework

Apache2::Controller organizes subclassed Apache2::Request handler objects in
an MVC module structure. A YAML file maps url paths to modules. $self is $r,
the subclassed XS APR bindings with libapreq methods to load query string,
etc. Stream with $r->print or use a parallel web tree of Template::Toolkit
files. Hook in any model class like DBIx::Class or direct SQL or sockets,
connections cached across requests. Session cookie plugin. Other great stuff.


INSTALLATION

lib/Apache2/Controller.pm  view on Meta::CPAN

of HTTP-based API, by returning the appropriate HTTP status codes.
See L<Apache2::Controller::Refcard/status> for a list.

See L<Apache2::Controller::Render::Template> for an additional base
for your controller class to render HTML with L<Template> Toolkit,
auto-selecting a template from the include path based on the 
request URI.

=head1 DESCRIPTION

Apache2::Controller is a lightweight controller framework for 
object-oriented applications designed to run only under mod_perl 
children in high-performance Apache2 handler modules.  It features URL 
dispatch with flexible configuration, auth plugins, a cookie tracker
for Apache::Session, liberty for any storage models that work under mod_perl,
rendering using Template Toolkit or direct printing with Apache or whatever
you want,
and base inheritance configuration allowing you to 
construct your applications as you need, without trying to be all things 
to all people or assimilate the world.  
It is intended as a framework for 
new applications specialized as Apache2 handlers, not as a means to 
absorb existing applications or to create portable code.  

Apache2::Controller instantiates the L<Apache2::Request> 
object and puts it in C<< $self->{r} >>.  If you want access
to the methods directly via C<< $self >>, simply use
L<Apache2::Request> as a base and it will auto-delegate
all the methods.  
See L<Apache2::Request/SUBCLASSING Apache2::Request>.

lib/Apache2/Controller.pm  view on Meta::CPAN

and L<Apache2::Controller::Session::Cookie>.

=head2 PerlAuthenHandler Apache2::Controller::Authen::OpenID

Implements OpenID logins and redirects to your specified login 
controller by changing the dispatch selection on the fly.

See L<Apache2::Controller::Authen::OpenID>.

As for Access and Authz phases of AAA, you should
probably roll your own.  This framework isn't going
to dictate the means of your data storage or how
you organize your users.  See the mod_perl manual.

=head1 Apache2::Controller response phase handler

Apache2::Controller is set as the PerlResponseHandler if 
the dispatch class finds a valid module and method for the request.

=head2 Subclass L<Apache2::Request>

lib/Apache2/Controller.pm  view on Meta::CPAN

with many stages for which you can register handler subroutines.
If you can wrap your head around it, inheritance provides many 
solutions to problems for which elaborate measures are commonly 
re-invented.  For example if you wanted cleanup done the same way every 
time without having to remember that C<< $self->cleanup() >> line 
for each new
method, overload the constructor as per L<subclassing a2c_new( )> above 
and register a PerlCleanupHandler for every request instead,
or use a base with a DESTROY method.

Otherwise the framework ends up doing a lot of work every time
to ask, "did they implement this?  did they implement that?"
and that gets in your way, or you have to write those routines
every time even if they don't do anything, or whatever.  Bleah.
Implement what you want to implement from the controller methods.
The framework won't provide you with any more structure.

=head1 EXAMPLES

Browse the source package from CPAN
and check out t/lib/* and t/conf/extra.conf.last.in.

=head1 RELATED MODULES

L<Apache2::Controller::Directives>

lib/Apache2/Controller/NonResponseBase.pm  view on Meta::CPAN

package Apache2::Controller::NonResponseBase;

=head1 NAME

Apache2::Controller::NonResponseBase - internal base class for 
non-response handlers in Apache2::Controller framework

=head1 VERSION

Version 1.001.001

=cut

use version;
our $VERSION = version->new('1.001.001');

lib/Apache2/Controller/NonResponseBase.pm  view on Meta::CPAN

 package Apache2::Controller;
 use base Apache2::Controller::NonResponseBase;

 # no need to define handler() or new()
 
 1;

=head1 DESCRIPTION

This factors out the common parts of handlers in the C<Apache2::Controller>
framework other than the main response handler.  These non-response
handlers like Dispatch and Session do not need to create the
Apache2::Request object (I think...), so that is put off until 
the Response phase.

You should not use this module for anything that you're doing.

Pre-response phase handlers do not handle errors in the same way
that Apache2::Controller does.  If you get an error in a pre-response
phase, A2C cannot call your render class error() method, because
that stuff is not set up yet.  Instead, it spits the error to

lib/Apache2/Controller/NonResponseRequest.pm  view on Meta::CPAN

package Apache2::Controller::NonResponseRequest;

=head1 NAME

Apache2::Controller::NonResponseRequest - internal base class w/ apreq for 
non-response handlers in Apache2::Controller framework

=head1 VERSION

Version 1.001.001

=cut

use version;
our $VERSION = version->new('1.001.001');

lib/Apache2/Controller/PerChildInit.pm  view on Meta::CPAN

when the C<PerChildInitHandler> runs.

=head2 LOGGING

Replaces the L<Log::Log4perl> appender for loggers
in the L<Apache2::Controller> namespace with one that
sends the errors to the Apache2 error log facility
with the appropriate log level.

This factors out the common parts of handlers in the C<Apache2::Controller>
framework other than the main response handler.  These non-response
handlers like Dispatch and Session do not need to create the
Apache2::Request object (I think...), so that is put off until 
the Response phase.

You should not use this module for anything that you're doing.

Pre-response phase handlers do not handle errors in the same way
that Apache2::Controller does.  If you get an error in a pre-response
phase, A2C cannot call your render class error() method, because
that stuff is not set up yet.  Instead, it spits the error to

lib/Apache2/Controller/Render/Template.pm  view on Meta::CPAN

back up to the server.  

Tip: if you plan to use render_fast(), write a test suite that
tests the output of your page.

Of course you could bypass rendering altogether and just use
$self->print().  (Remember that $self is 
normally subclassed in L<Apache2::Request> which magically
delegates to C<< $self->{r} >>.)
Or maybe you should implement an ajax style control in the template
and put a limit frame on the query above, or use a paging lib, etc. ...

=cut

sub render_fast {
    my ($self) = @_;

    $self->pnotes->{a2c}{use_standard_errors} = 1;

    my $template = $self->detect_template();
    DEBUG("processing template = '$template'");

t/lib/Apache2/Controller/Test/TestRun.pm  view on Meta::CPAN

    $self->SUPER::start();

    Log::Log4perl->init(\$L4P_UNIT_CONF);
}

sub bug_report {
    my ($self) = @_;
    print <<EOI;
+-----------------------------------------------------------------------+
| Apache2::Controller - framework for Apache2 apps                      |
| Please file a bug report with CPAN RT:                                |
| http://rt.cpan.org/Public/Dist/Display.html?Name=Apache2-Controller   |
+-----------------------------------------------------------------------+
EOI
}

1;