=pod

=head1 NAME

Apache2::ASP::Manual::GlobalASA - Documentation about the GlobalASA

=head1 SYNOPSIS

  package GlobalASA;
  
  use strict;
  use warnings 'all';
  use base 'Apache2::ASP::GlobalASA';
  
  use vars qw(
    $Request $Response
    $Session $Application
    $Server $Form
    $Config
  );
  
  sub Script_OnParse
  {
    my $sourceref = shift(@_);
  }# end Script_OnParse()
  
  sub Script_OnStart
  {
  }# end Script_OnStart()
  
  sub Script_OnFlush
  {
  }# end Script_OnFlush()
  
  sub Script_OnEnd
  {
  }# end Script_OnEnd()
  
  sub Script_OnError
  {
    my ($error, $stacktrace) = ($@, @_);
  }# end Script_OnError()
  
  sub Session_OnStart
  {
  }# end Session_OnStart()
  
  sub Application_OnStart
  {
  }# end Application_OnStart()
  
  1;# return true:

=head1 DESCRIPTION

B<IMPORTANT:> This is the Manual for GlobalASA development.  If you are looking for general API
information, please refer to L<Apache2::ASP::GlobalASA> instead.

Your GlobalASA is a central place that makes it easy to specify event listeners
that respond to different kinds of events in your web applications.

Developers experienced with "classic" ASP will recognize that there are several more events 
available here than they are familiar with.

Adding a GlobalASA class to your website is B<completely optional>.  If you don't have a GlobalASA
then the default GlobalASA class will be used instead.  Its event handlers do nothing.

=head1 GETTING STARTED

First, navigate to your C<DocumentRoot> as specified in your C<httpd.conf>.  Please refer to 
L<Apache2::ASP::Manual::HttpdConf> for details about that.

So, supposing your C<DocumentRoot> is C</var/www/html> you would create a new file at
C</var/www/html/GlobalASA.pm> and open it in your favorite text editor.

For this example, we will use the namespace C<DefaultApp::> but you should use the value you
used in your C<apache2-asp-config.xml> file under C<application_name>.

To start, we'll just add the following code:

  package DefaultApp::GlobalASA;
  
  use strict;
  use warnings 'all';
  use base 'Apache2::ASP::GlobalASA';
  
  use vars qw(
    $Request $Response
    $Session $Application
    $Server $Form
    $Config
  );
  
  1;# return true:

You have a perfectly valid GlobalASA class, but it does nothing.

If you wanted to set some special C<$Session> variables when a visitor first enters the
site, you could simply add the following:

  sub Session_OnStart
  {
    $Session->{counter} = 0;
    $Session->{referer} = $ENV{HTTP_REFERER} || '';
  }# end Session_OnStart()

Then, later if you wanted to keep track of how many page requests the user made on the site,
you could do something like this:

  sub Script_OnStart
  {
    $Session->{counter}++;
  }# end Script_OnStart()

If you wanted to receive an email about errors on the website, do this:

  sub Script_OnError
  {
    my $stacktrace = shift;
    my $err = $@;
    
    $Server->Mail(
      To  => 'you@youraddress.com',
      From => 'apache@' . $ENV{HTTP_HOST},
      Subject => 'Error on website',
      Message => "Error on website: $@ \n\n" . $stacktrace->as_string
    );
    
    # Also print something nice to the poor user:
    $Response->Write("<p>Sorry about the error - the admin has been notified.</p>");
  }# end Script_OnError()

If you wanted to make sure that only "logged in" people are allowed to access a part of the site:

  sub Script_OnStart
  {
    # Find out what folder we're in:
    my ($folder) = $Request->ServerVariables("SCRIPT_NAME") =~ m/^(.*?)[^\/]+$/;
    $folder =~ s/\/$//;
    
    if( $folder =~ m/^members/ )
    {
      # We're in the /members folder - are we logged in?
      if( ! $Session->{logged_in} )
      {
        # Unauthenticated users are forced to go to /login.asp
        $Response->Redirect("/login.asp");
      }# end if()
    }# end if()
  }# end Script_OnStart()

If you want to de-spamify all email addresses to be user-at-server-dot-com:

  sub Script_OnFlush
  {
    my $contentref = shift(@_);
    $contentref =~ s/\b([a-z0-9\.\-_]+)@([a-z0-9\.\-]+)\.([a-z]+)\b/$1-at-$2-dot-$3/ig;
  }# end Script_OnFlush()

=head1 WHEN EVENTS ARE CALLED

The event-call timing is documented in L<Apache2::ASP::GlobalASA>.

=head1 IMPORTANT

Please note - your GlobalASA class will not be reloaded if you change it.  You will need to restart
Apache to make sure your changes take effect.

=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