4.28 XXX XXX XX XX:00:00 2005
- fixed isa tree (Christian Hansen)
+ - Reworked documentation (Andrew Ford <A.Ford@ford-mason.co.uk>)
4.27 Sat Mar 19 01:00:00 2005
- debug message for parameters
+ - Fix redirects (Christian Hansen <ch@ngmedia.com>)
- some random fixes
- new helper api for Catalyst::Helper::* support
you have to update script/create.pl to use it
See L<Catalyst::Manual> for more documentation.
-Omit the Catalyst::Plugin:: prefix from plugins.
-So Catalyst::Plugin::My::Module becomes My::Module.
+Catalyst plugins can be loaded by naming them as arguments to the "use Catalyst" statement.
+Omit the C<Catalyst::Plugin::> prefix from the plugin name,
+so C<Catalyst::Plugin::My::Module> becomes C<My::Module>.
use Catalyst 'My::Module';
-You can also set special flags like -Debug and -Engine.
+Special flags like -Debug and -Engine can also be specifed as arguments when
+Catalyst is loaded:
use Catalyst qw/-Debug My::Module/;
-The position of plugins and flags in the chain is important,
-because they are loaded in the same order they appear.
+The position of plugins and flags in the chain is important, because they are
+loaded in exactly the order that they appear.
-=head2 -Debug
+The following flags are supported:
+
+=over 4
+
+=item -Debug
+
+enables debug output, i.e.:
use Catalyst '-Debug';
-is equivalent to
+this is equivalent to:
use Catalyst;
sub debug { 1 }
-=head2 -Engine
+=item -Engine
Force Catalyst to use a specific engine.
-Omit the Catalyst::Engine:: prefix.
+Omit the C<Catalyst::Engine::> prefix of the engine name, i.e.:
use Catalyst '-Engine=CGI';
-=head2 METHODS
+=back
-=head3 debug
+=head1 METHODS
+
+=over 4
+
+=item debug
Overload to enable debug messages.
sub debug { 0 }
-=head3 config
+=item config
Returns a hashref containing your applications settings.
$caller->log->debug(qq/Loaded engine "$engine"/) if $caller->debug;
}
+=back
+
=head1 SUPPORT
IRC:
It provides you with a generic new() for instantiation through Catalyst's
component loader with config() support and a process() method placeholder.
-=head2 METHODS
+=head1 METHODS
+
+=over 4
+
+=item new($c)
-=head3 new
=cut
sub new {
return $self->NEXT::new( $self->config );
}
-=head3 config
+# remember to leave blank lines between the consecutive =item's
+# otherwise the pod tools don't recognize the subsequent =items
+
+=item $c->config
+
+=item $c->config($hashref)
+
+=item $c->config($key, $value, ...)
=cut
return $self->_config;
}
-=head3 process
+=item $c->process()
=cut
=head1 DESCRIPTION
-=head2 METHODS
+=head1 METHODS
-=head3 action
+=over 4
+
+=item $c->action( $name => $coderef, ... )
+
+=item $c->action( $name )
+
+=item $c->action
Add one or more actions.
}
}
-=head3 benchmark
+
+=item $c->benchmark($coderef)
Takes a coderef with arguments and returns elapsed time as float.
return wantarray ? ( $elapsed, @return ) : $elapsed;
}
-=head3 component (comp)
+=item $c->comp($name)
+
+=item $c->component($name)
Get a component object by name.
}
}
-=head3 errors
+=item $c->errors
+
+=item $c->errors($error, ...)
+
+=item $c->errors($arrayref)
Returns an arrayref containing errors messages.
return $c->{errors};
}
-=head3 finalize
+=item $c->finalize
Finalize request.
sub finalize {
my $c = shift;
+
+ if ( my $location = $c->res->redirect ) {
+ $c->log->debug(qq/Redirecting to "$location"/) if $c->debug;
+ $c->res->headers->header( Location => $location );
+ $c->res->status(302);
+ }
+
if ( !$c->res->output || $#{ $c->errors } >= 0 ) {
$c->res->headers->content_type('text/html');
my $name = $c->config->{name} || 'Catalyst Application';
</html>
}
- if ( my $location = $c->res->redirect ) {
- $c->log->debug(qq/Redirecting to "$location"/) if $c->debug;
- $c->res->headers->header( Location => $location );
- $c->res->status(302);
- }
$c->res->headers->content_length( length $c->res->output );
my $status = $c->finalize_headers;
$c->finalize_output;
return $status;
}
-=head3 finalize_headers
+=item $c->finalize_headers
Finalize headers.
sub finalize_headers { }
-=head3 finalize_output
+=item $c->finalize_output
Finalize output.
sub finalize_output { }
-=head3 forward
+=item $c->forward($command)
Forward processing to a private/public action or a method from a class.
If you define a class without method it will default to process().
return $c->process( $class, $code );
}
-=head3 handler
+=item $c->handler($r)
Handles the request.
return $status;
}
-=head3 prepare
+=item $c->prepare($r)
-Turns the request (Apache, CGI...) into a Catalyst context.
+Turns the engine-specific request (Apache, CGI...) into a Catalyst context.
=cut
return $c;
}
-=head3 prepare_action
+=item $c->prepare_action
Prepare action.
if ( $c->debug && @args );
}
-=head3 prepare_cookies;
+=item $c->prepare_cookies;
Prepare cookies.
sub prepare_cookies { }
-=head3 prepare_headers
+=item $c->prepare_headers
Prepare headers.
sub prepare_headers { }
-=head3 prepare_parameters
+=item $c->prepare_parameters
Prepare parameters.
sub prepare_parameters { }
-=head3 prepare_path
+=item $c->prepare_path
Prepare path and base.
sub prepare_path { }
-=head3 prepare_request
+=item $c->prepare_request
Prepare the engine request.
sub prepare_request { }
-=head3 prepare_uploads
+=item $c->prepare_uploads
Prepare uploads.
sub prepare_uploads { }
-=head3 process
+=item $c->process($class, $coderef)
Process a coderef in given class and catch exceptions.
Errors are available via $c->errors.
return $status;
}
-=head3 remove_action
+=item $c->remove_action($action)
Remove an action.
}
}
-=head3 request (req)
+=item $c->request
+
+=item $c->req
Returns a C<Catalyst::Request> object.
my $req = $c->req;
-=head3 response (res)
+=item $c->response
+
+=item $c->res
Returns a C<Catalyst::Response> object.
my $res = $c->res;
-=head3 setup
+=item $class->setup
Setup.
}
}
-=head3 setup_components
+=item $class->setup_components
Setup components.
if $self->debug;
}
-=head3 stash
+=item $c->stash
Returns a hashref containing all your data.
return $prefix;
}
+=back
+
=head1 AUTHOR
Sebastian Riedel, C<sri@cpan.org>
=head1 DESCRIPTION
-The Apache Engine.
+This is the Catalyst engine specialized for Apache (i.e. for mod_perl).
-=head2 METHODS
+=head1 METHODS
-=head3 apache_request
+=over 4
+
+=item $c->apache_request
Returns an C<Apache::Request> object.
-=head3 original_request
+=item $c->original_request
Returns the original Apache request object.
-=head2 OVERLOADED METHODS
+=back
+
+=head1 OVERLOADED METHODS
This class overloads some methods from C<Catalyst::Engine>.
-=head3 finalize_headers
+=over 4
+
+=item $c->finalize_headers
=cut
return 0;
}
-=head3 finalize_output
+=item $c->finalize_output
=cut
$c->original_request->print( $c->response->{output} );
}
-=head3 prepare_cookies
+=item $c->prepare_cookies
=cut
{ Apache::Cookie->new( $c->apache_request )->fetch } );
}
-=head3 prepare_headers
+=item $c->prepare_headers
=cut
$c->req->headers->header( %{ $c->apache_request->headers_in } );
}
-=head3 prepare_parameters
+=item $c->prepare_parameters
=cut
$c->req->parameters( \%args );
}
-=head3 prepare_path
+=item $c->prepare_path
=cut
$c->req->base( $base->as_string );
}
-=head3 prepare_request
+=item $c->prepare_request($r)
=cut
$c->original_request($r);
}
-=head3 prepare_uploads
+=item $c->prepare_uploads
=cut
}
}
+=back
+
=head1 SEE ALSO
L<Catalyst>.
=head1 SYNOPSIS
+A script using the Catalyst::Engine::CGI module might look like:
+
#!/usr/bin/perl -w
use strict;
MyApp->run;
-See L<Catalyst>.
+The application module (C<MyApp>) would use C<Catalyst>, which loads the
+appropriate engine module.
=head1 DESCRIPTION
-This is the CGI engine for Catalyst.
+This is the Catalyst engine specialized for the CGI environment (using the
+C<CGI::Simple> and C<CGI::Cookie> modules). Normally Catalyst will select the
+appropriate engine according to the environment that it detects, however you
+can force Catalyst to use the CGI engine by specifying the following in your
+application module:
+
+ use Catalyst qw(-Engine=CGI);
-The script shown above must be designated as a "Non-parsed Headers"
-script to function properly.
-To do this in Apache name the script starting with C<nph->.
+Catalyst::Engine::CGI generates a full set of HTTP headers, which means that
+applications using the engine must be be configured as "Non-parsed Headers"
+scripts (at least when running under Apache). To configure this under Apache
+name the starting with C<nph->.
The performance of this way of using Catalyst is not expected to be
useful in production applications, but it may be helpful for development.
-=head2 METHODS
+=head1 METHODS
-=head3 run
+=over 4
+
+=item $c->run
To be called from a CGI script to start the Catalyst application.
-=head3 cgi
+=item $c->cgi
This config parameter contains the C<CGI::Simple> object.
-=head2 OVERLOADED METHODS
+=back
+
+=head1 OVERLOADED METHODS
This class overloads some methods from C<Catalyst>.
-=head3 finalize_headers
+=over 4
+
+=item $c->finalize_headers
=cut
print $c->cgi->header(%headers);
}
-=head3 finalize_output
+=item $c->finalize_output
+
+Prints the response output to STDOUT.
=cut
print $c->response->output;
}
-=head3 prepare_cookies
+=item $c->prepare_cookies
+
+Sets up cookies.
=cut
sub prepare_cookies { shift->req->cookies( { CGI::Cookie->fetch } ) }
-=head3 prepare_headers
+=item $c->prepare_headers
=cut
}
}
-=head3 prepare_parameters
+=item $c->prepare_parameters
=cut
$c->req->parameters( {%vars} );
}
-=head3 prepare_path
+=item $c->prepare_path
=cut
$c->req->base( $base->as_string );
}
-=head3 prepare_request
+=item $c->prepare_request
=cut
sub prepare_request { shift->cgi( CGI::Simple->new ) }
-=head3 prepare_uploads
+=item $c->prepare_uploads
=cut
sub run { shift->handler }
+=back
+
=head1 SEE ALSO
L<Catalyst>.
projects / catagits/Catalyst-Runtime.git / commitdiff