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