NAME

Catalyst - The Elegant MVC Web Application Framework

SYNOPSIS

See the Catalyst::Manual distribution for comprehensive
documentation and tutorials.

# Install Catalyst::Devel for helpers and other development tools
# use the helper to create a new application
catalyst.pl MyApp

# add models, views, controllers
script/myapp_create.pl model MyDatabase DBIC::Schema create=static dbi:SQLite:/path/to/db
script/myapp_create.pl view MyTemplate TT
script/myapp_create.pl controller Search

# built in testserver -- use -r to restart automatically on changes
# --help to see all available options
script/myapp_server.pl

# command line testing interface
script/myapp_test.pl /yada

### in lib/MyApp.pm
use Catalyst qw/-Debug/; # include plugins here as well

### In lib/MyApp/Controller/Root.pm (autocreated)
sub foo : Chained('/') Args() { # called for /foo, /foo/1, /foo/1/2, etc.
    my ( $self, $c, @args ) = @_; # args are qw/1 2/ for /foo/1/2
    $c->stash->{template} = 'foo.tt'; # set the template
    # lookup something from db -- stash vars are passed to TT
    $c->stash->{data} =
      $c->model('Database::Foo')->search( { country => $args[0] } );
    if ( $c->req->params->{bar} ) { # access GET or POST parameters
        $c->forward( 'bar' ); # process another action
        # do something else after forward returns
    }
}

# The foo.tt TT template can use the stash data from the database
[% WHILE (item = data.next) %]
    [% item.foo %]
[% END %]

# called for /bar/of/soap, /bar/of/soap/10, etc.
sub bar : Chained('/') PathPart('/bar/of/soap') Args() { ... }

# called after all actions are finished
sub end : Action {
    my ( $self, $c ) = @_;
    if ( scalar @{ $c->error } ) { ... } # handle errors
    return if $c->res->body; # already have a response
    $c->forward( 'MyApp::View::TT' ); # render template
}

See Catalyst::Manual::Intro for additional information.

DESCRIPTION

Catalyst is a modern framework for making web applications without the
pain usually associated with this process. This document is a reference
to the main Catalyst application. If you are a new user, we suggest you
start with Catalyst::Manual::Tutorial or Catalyst::Manual::Intro.

See Catalyst::Manual for more documentation.

Catalyst plugins can be loaded by naming them as arguments to the "use
Catalyst" statement. Omit the Catalyst::Plugin:: prefix from the
plugin name, i.e., Catalyst::Plugin::My::Module becomes
My::Module.

use Catalyst qw/My::Module/;

If your plugin starts with a name other than Catalyst::Plugin::, you can
fully qualify the name by using a unary plus:

use Catalyst qw/
    My::Module
    +Fully::Qualified::Plugin::Name
/;

Special flags like -Debug can also be specified 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 order in which they appear.

The following flags are supported:

-Debug

Enables debug output. You can also force this setting from the system
environment with CATALYST_DEBUG or _DEBUG. The environment
settings override the application, with _DEBUG having the highest
priority.

This sets the log level to 'debug' and enables full debug output on the
error screen. If you only want the latter, see $c->debug.

-Home

Forces Catalyst to use a specific home directory, e.g.:

use Catalyst qw[-Home=/usr/mst];

This can also be done in the shell environment by setting either the
CATALYST_HOME environment variable or MYAPP_HOME; where MYAPP
is replaced with the uppercased name of your application, any "::" in
the name will be replaced with underscores, e.g. MyApp::Web should use
MYAPP_WEB_HOME. If both variables are set, the MYAPP_HOME one will be used.

If none of these are set, Catalyst will attempt to automatically detect the
home directory. If you are working in a development environment, Catalyst
will try and find the directory containing either Makefile.PL, Build.PL,
dist.ini, or cpanfile. If the application has been installed into the system
(i.e. you have done make install), then Catalyst will use the path to your
application module, without the .pm extension (e.g., /foo/MyApp if your
application was installed at /foo/MyApp.pm)

-Log

use Catalyst '-Log=warn,fatal,error';

Specifies a comma-delimited list of log levels.

-Stats

Enables statistics collection and reporting.

use Catalyst qw/-Stats=1/;

You can also force this setting from the system environment with CATALYST_STATS
or _STATS. The environment settings override the application, with
_STATS having the highest priority.

Stats are also enabled if debugging is enabled.

METHODS

INFORMATION ABOUT THE CURRENT REQUEST

$c->action

Returns a Catalyst::Action object for the current action, which
stringifies to the action name. See Catalyst::Action.

$c->namespace

Returns the namespace of the current action, i.e., the URI prefix
corresponding to the controller of the current action. For example:

# in Controller::Foo::Bar
$c->namespace; # returns 'foo/bar';

$c->request

$c->req

Returns the current Catalyst::Request object, giving access to
information about the current client request (including parameters,
cookies, HTTP headers, etc.). See Catalyst::Request.

REQUEST FLOW HANDLING

$c->forward( $action [, \@arguments ] )

$c->forward( $class, $method, [, \@arguments ] )

This is one way of calling another action (method) in the same or
a different controller. You can also use $self->my_method($c, @args)
in the same controller or $c->controller('MyController')->my_method($c, @args)
in a different controller.
The main difference is that 'forward' uses some of the Catalyst request
cycle overhead, including debugging, which may be useful to you. On the
other hand, there are some complications to using 'forward', restrictions
on values returned from 'forward', and it may not handle errors as you prefer.
Whether you use 'forward' or not is up to you; it is not considered superior to
the other ways to call a method.

'forward' calls another action, by its private name. If you give a
class name but no method, process() is called. You may also optionally
pass arguments in an arrayref. The action will receive the arguments in
@_ and $c->req->args. Upon returning from the function,
$c->req->args will be restored to the previous values.

Any data returned from the action forwarded to, will be returned by the
call to forward.

my $foodata = $c->forward('/foo');
$c->forward('index');
$c->forward(qw/Model::DBIC::Foo do_stuff/);
$c->forward('View::TT');

Note that forward implies
an eval { } around the call (actually
execute does), thus rendering all
exceptions thrown by the called action non-fatal and pushing them onto
$c->error instead. If you want die to propagate you need to do something
like:

$c->forward('foo');
die join "\n", @{ $c->error } if @{ $c->error };

Or make sure to always return true values from your actions and write
your code like this:

$c->forward('foo')