=pod

=head1 NAME

Apache2::ASP::Manual::Handlers - Documentation about writing Handlers

=head1 SYNOPSIS

Here is a basic handler:

  package MyHandler;
  
  use strict;
  use warnings 'all';
  use base 'Apache2::ASP::FormHandler';
  
  use vars qw(
    $Request $Response
    $Session $Server
    $Application $Form
    $Config
  );
  
  sub run
  {
    # Perform some work, then:
    $Response->Redirect("/another-page.asp");
  }# end run()
  
  1;# return true:

=head1 INTRODUCTION

=head2 What are Handlers?

Handlers are a kind of middle-ground for ASP programmers.  There are no <% %> tags
and no HTML parsing, but you still have the ASP objects ($Request, $Response, $Session, etc).

=head2 What makes them special?

Handlers are an object-oriented approach to form processing in a web application.

This means that Handlers that derive from one root Handler class will have different properties
than Handlers that derive from another root Handler class.

=head2 What are Handlers for?

Handlers are intended for processing forms or responding to AJAX Web2.0 applications
where you don't need to worry about large chunks of HTML embedded in your code.

=head2 What kinds of Handlers are there?

Handlers can subclass the following root classes:

=over 4

=item Apache2::ASP::FormHandler

Subclasses of L<Apache2::ASP::FormHandler> are used for processing form input.  
Typically a FormHandler will redirect the user to another page after the request
has been processed.

=item Apache2::ASP::UploadHandler

Subclasses of L<Apache2::ASP::UploadHandler> are used for processing file uploads.
Unless you need to start completely from scratch, you're probably better off 
subclassing L<Apache2::ASP::MediaManager>.

=item Apache2::ASP::MediaManager

Subclasses of L<Apache2::ASP::MediaManager> get instant file-upload manager functionality
just by showing up.  Override a method or two and you've got basic file management that
should work fine for most small websites.  Override a couple more methods and you can
have enterprise-class file management.

=item Apache2::ASP::PageHandler

All ASP scripts are compiled into a Perl module that subclasses L<Apache2::ASP::PageHandler>.

Learn more about ASP compilation at L<Apache2::ASP::Manual::ASP_Compilation>.

=back

=head1 SUBCLASSING OTHER HANDLERS

All Handlers are subclasses of L<Apache2::ASP::Handler>.  L<Apache2::ASP::MediaManager>
is a subclass of L<Apache2::ASP::UploadHandler>.

You could make your own "private" Handler classes (not installed under C</handlers> on your site)
that your "public" Handlers (available under C</handlers> on your site) derive from.

For example, one could write an abstract "shopping cart" Handler that others are derived from,
only adding or replacing functionality specific to their needs.

So C<Generic::Handler::Newsletter::Signup> might contain all the logic necessary to add
someone to a mailing list (in general).  C<Newsletter::Signup> could subclass 
C<Generic::Handler::Newsletter::Signup> and handle the redirect part.

=head2 Example

  package Newsletter::Signup;
  
  use strict;
  use warnings 'all';
  use base 'Generic::Handler::Newsletter::Signup';
  use vars qw(
    $Request $Response
    $Session $Server
    $Application $Form
    $Config
  );
  
  sub run
  {
    my $s = shift;
    
    # Have Generic::Handler::Newsletter::Signup do the heavy lifting:
    $s->SUPER::run( @_ );
    
    # Now just redirect the user:
    $Response->Redirect("/thank-you.asp");
  }# end run()
  
  1;# return true:

=head1 READ THIS

Please note - your Handlers are not automatically reloaded if you make changes to them.

You will have to restart Apache to make sure that your changes take effect.

On a B<strictly development webserver> you could use L<Apache::Reload> to help this, but
even then you may get some strange behavior.

=head1 BUGS

It's possible that some bugs have found their way into this release.

Use RT L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Apache2-ASP> to submit bug reports.

=head1 HOMEPAGE

Please visit the Apache2::ASP homepage at L<http://www.devstack.com/> to see examples
of Apache2::ASP in action.

=head1 AUTHOR

John Drago L<mailto:jdrago_999@yahoo.com>

=head1 COPYRIGHT AND LICENSE

Copyright 2007 John Drago, All rights reserved.

This software is free software.  It may be used and distributed under the
same terms as Perl itself.

=cut