=head2 What is Catalyst?
-Catalyst is an elegant web application framework, extremely flexible yet
-extremely simple. It's similar to Ruby on Rails, Spring (Java), and
-L<Maypole>, upon which it was originally based. Its most important
-design philosphy is to provide easy access to all the tools you need to
-develop web applications, with few restrictions on how you need to use
-these tools. Under Catalyst, it is always possible to do things in a
-different way. However, this does mean that it is always possible to do
-things in a different way. Other web frameworks are simpler to use and
-easy to get up and running, but achieve this by locking the programmer
-into a single set of tools. Catalyst's emphasis on flexibility means
-that you have to think more to use it. We view this as a feature.
+Catalyst is an elegant web application framework, extremely flexible
+yet extremely simple. It's similar to Ruby on Rails, Spring (Java),
+and L<Maypole>, upon which it was originally based. Its most important
+design philosphy is to provide easy access to all the tools you need
+to develop web applications, with few restrictions on how you need to
+use these tools. However, this does mean that it is always possible to
+do things in a different way. Other web frameworks are B<initially>
+simpler to use, but achieve this by locking the programmer into a
+single set of tools. Catalyst's emphasis on flexibility means that you
+have to think more to use it. We view this as a feature. For example,
+this leads to Catalyst being more suited to system integration tasks
+than other web frameworks.
=head3 MVC
the others. Catalyst promotes the re-use of existing Perl modules that
already handle common web application concerns well.
-Here's how the M, V, and C map to those concerns, with examples of
-well-known Perl modules you may want to use for each.
+Here's how the Model, View, and Controller map to those concerns, with
+examples of well-known Perl modules you may want to use for each.
=over 4
check out the original book on the subject, I<Design Patterns>, by
Gamma, Helm, Johnson, and Vlissides, also known as the Gang of Four
(GoF). Many, many web application frameworks are based on MVC, which
-is becoming a popular design method for web applications.
+is becoming a popular design paradigm for the world wide web.
=head3 Flexibility
-Catalyst is much more flexible than many other frameworks. We'll talk
-more about this later, but rest assured you can use your favorite Perl
-modules with Catalyst.
+Catalyst is much more flexible than many other frameworks. Rest assured
+you can use your favorite Perl modules with Catalyst.
=over 4
Now http://localhost:3000/hello prints "Hello World!".
-=item * B<Support for CGI, mod_perl, Apache::Request>
+=item * B<Support for CGI, mod_perl, Apache::Request, FastCGI>
-Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>.
+Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>. Other
+engines are also available.
=back
=item * B<Built-in Test Framework>
Catalyst comes with a built-in, lightweight http server and test
-framework, making it easy to test applications from the command line.
+framework, making it easy to test applications from the web browser,
+and the command line.
=item * B<Helper Scripts>
Catalyst provides helper scripts to quickly generate running starter
-code for components and unit tests. See L<Catalyst::Helper>.
+code for components and unit tests. Install L<Catalyst::Devel> and see
+L<Catalyst::Helper>.
=back
=head3 Install
- $ perl -MCPAN -e 'install Task::Catalyst'
+Installation of Catalyst can be a time-consuming and frustrating
+effort, due to its large number of dependencies. The easiest way
+to get up and running is to use Matt Trout's C<cat-install>
+script, from L<http://www.shadowcatsystems.co.uk/static/cat-install>,
+and then install L<Catalyst::Devel>.
+
+ # perl cat-install
+ # perl -MCPAN -e 'install Catalyst::Devel'
=head3 Setup
=back
-Easy!
-
=head2 How It Works
Let's see how Catalyst works, by taking a closer look at the components
and other parts of a Catalyst application.
-=head3 Application Class
+=head3 Components
-In addition to the Model, View, and Controller components, there's a
-single class that represents your application itself. This is where you
-configure your application, load plugins, and extend Catalyst.
+Catalyst has an uncommonly flexible component system. You can define as
+many L</Models>, L</Views>, and L</Controllers> as you like. As discussed
+previously, the general idea is that the View is responsible for the
+output of data to the user (typically via a web browser, but a View can
+also generate PDFs or e-mails, for example); the Model is responsible
+for providing data (typically from a relational database); and the
+Controller is responsible for interacting with the user and deciding
+how user input determines what actions the application takes.
+
+In the world of MVC, there are frequent discussions and disagreements
+about the nature of each element - whether certain types of logic
+belong in the Model or the Controller, etc. Catalyst's flexibility
+means that this decision is entirely up to you, the programmer;
+Catalyst doesn't enforce anything. See L<Catalyst::Manual::About> for
+a general discussion of these issues.
- package MyApp;
+All components must inherit from L<Catalyst::Base>, which provides a
+simple class structure and some common class methods like C<config> and
+C<new> (constructor).
+
+ package MyApp::Controller::Catalog;
use strict;
- use Catalyst qw/-Debug/;
+ use base 'Catalyst::Base';
- MyApp->config(
- name => 'My Application',
+ __PACKAGE__->config( foo => 'bar' );
- # You can put anything else you want in here:
- my_configuration_variable => 'something',
- );
1;
-In older versions of Catalyst, the application class was where you put
-global actions. However, as of version 5.66, the recommended practice is
-to place such actions in a special Root controller (see #####, below),
-to avoid namespace collisions.
+You don't have to C<use> or otherwise register Models, Views, and
+Controllers. Catalyst automatically discovers and instantiates them
+when you call C<setup> in the main application. All you need to do is
+put them in directories named for each Component type. You can use a
+short alias for each one.
=over 4
-=item * B<name>
+=item * B<MyApp/Model/>
-The name of your application.
+=item * B<MyApp/M/>
+
+=item * B<MyApp/View/>
+
+=item * B<MyApp/V/>
+
+=item * B<MyApp/Controller/>
+
+=item * B<MyApp/C/>
=back
-Optionally, you can specify a B<root> parameter for templates and static
-data. If omitted, Catalyst will try to auto-detect the directory's
-location. You can define as many parameters as you want for plugins or
-whatever you need. You can access them anywhere in your application via
-C<$context-E<gt>config-E<gt>{$param_name}>.
+In older versions of Catalyst, the recommended practice (and the one
+automatically created by helper scripts) was to name the directories
+C<M/>, C<V/>, and C<C/>. Though these still work, we now recommend
+the use of the full names.
-###### We need a short section on configuration here.
+=head4 Views
-=head3 Context
+To show how to define views, we'll use an already-existing base class for the
+L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
+inherit from this class:
-Catalyst automatically blesses a Context object into your application
-class and makes it available everywhere in your application. Use the
-Context to directly interact with Catalyst and glue your L</Components>
-together. For example, if you need to use the Context from within a
-Template Toolkit template, it's already there:
+ package MyApp::View::TT;
- <h1>Welcome to [% c.config.name %]!</h1>
+ use strict;
+ use base 'Catalyst::View::TT';
-As illustrated in our URL-to-Action dispatching example, the Context is
-always the second method parameter, behind the Component object
-reference or class name itself. Previously we called it C<$context> for
-clarity, but most Catalyst developers just call it C<$c>:
+ 1;
+
+(You can also generate this automatically by using the helper script:
+
+ script/myapp_create.pl view TT TT
+
+where the first C<TT> tells the script that the name of the view should
+be C<TT>, and the second that it should be a Template Toolkit view.)
+
+This gives us a process() method and we can now just do
+$c->forward('MyApp::View::TT') to render our templates. The base class
+makes process() implicit, so we don't have to say
+C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
sub hello : Global {
my ( $self, $c ) = @_;
- $c->res->body('Hello World!');
+ $c->stash->{template} = 'hello.tt';
}
-The Context contains several important objects:
-
-=over 4
-
-=item * L<Catalyst::Request>
+ sub end : Private {
+ my ( $self, $c ) = @_;
+ $c->forward( $c->view('TT') );
+ }
- $c->request
- $c->req # alias
+You normally render templates at the end of a request, so it's a perfect
+use for the global C<end> action.
-The request object contains all kinds of request-specific information, like
-query parameters, cookies, uploads, headers, and more.
+In practice, however, you would use a default C<end> action as supplied
+by L<Catalyst::Action::RenderView>.
- $c->req->params->{foo};
- $c->req->cookies->{sessionid};
- $c->req->headers->content_type;
- $c->req->base;
+Also, be sure to put the template under the directory specified in
+C<$c-E<gt>config-E<gt>{root}>, or you'll end up looking at the debug
+screen.
-=item * L<Catalyst::Response>
+=head4 Models
- $c->response
- $c->res # alias
+Models are providers of data. This data could come from anywhere - a
+search engine index, a spreadsheet, the file system - but typically a
+Model represents a database table. The data source does not
+intrinsically have much to do with web applications or Catalyst - it
+could just as easily be used to write an offline report generator or a
+command-line tool.
-The response is like the request, but contains just response-specific
-information.
+To show how to define models, again we'll use an already-existing base
+class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>.
+We'll also need L<DBIx::Class::Schema::Loader>.
- $c->res->body('Hello World');
- $c->res->status(404);
- $c->res->redirect('http://oook.de');
+But first, we need a database.
-=item * L<Catalyst::Config>
+ -- myapp.sql
+ CREATE TABLE foo (
+ id INTEGER PRIMARY KEY,
+ data TEXT
+ );
- $c->config
- $c->config->root;
- $c->config->name;
+ CREATE TABLE bar (
+ id INTEGER PRIMARY KEY,
+ foo INTEGER REFERENCES foo,
+ data TEXT
+ );
-=item * L<Catalyst::Log>
+ INSERT INTO foo (data) VALUES ('TEST!');
- $c->log
- $c->log->debug('Something happened');
- $c->log->info('Something you should know');
+ % sqlite /tmp/myapp.db < myapp.sql
-=item * B<Stash>
+Now we can create a DBIC::Schema model for this database.
- $c->stash
- $c->stash->{foo} = 'bar';
- $c->stash->{baz} = {baz => 'qox'};
- $c->stash->{fred} = [qw/ wilma pebbles/];
+ script/myapp_create.pl model MyModel DBIC::Schema MySchema create=static 'dbi:SQLite:/tmp/myapp.db'
-and so on.
+L<DBIx::Class::Schema::Loader> automatically loads table layouts and
+relationships, and converts them into a static schema definition C<MySchema>,
+which you can edit later.
-=back
+Use the stash to pass data to your templates.
-The last of these, the stash, is a universal hash for sharing data among
-application components. For an example, we return to our 'hello' action:
+We add the following to MyApp/Controller/Root.pm
- sub hello : Global {
- my ( $self, $c ) = @_;
- $c->stash->{message} = 'Hello World!';
- $c->forward('show_message');
+ sub view : Global {
+ my ( $self, $c, $id ) = @_;
+
+ $c->stash->{item} = $c->model('MyModel::Foo')->find($id);
}
- sub show_message : Private {
+ 1;
+
+ sub end : Private {
my ( $self, $c ) = @_;
- $c->res->body( $c->stash->{message} );
+
+ $c->stash->{template} ||= 'index.tt';
+ $c->forward( $c->view('TT') );
}
-Note that the stash should be used only for passing data in an
-individual request cycle; it gets cleared at a new request. If you need
-to maintain more persistent data, use a session.
+We then create a new template file "root/index.tt" containing:
-=head3 Actions
+ The Id's data is [% item.data %]
-A Catalyst controller is defined by its actions. An action is a
-subroutine with a special attribute. You've already seen some examples
-of actions in this document. The URL (for example
-http://localhost.3000/foo/bar) consists of two parts, the base
-(http://localhost:3000/ in this example) and the path (foo/bar). Please
-note that the trailing slash after the hostname[:port] always belongs to
-base and not to the action.
+Models do not have to be part of your Catalyst application; you
+can always call an outside module that serves as your Model:
-=over 4
+ # in a Controller
+ sub list : Local {
+ my ( $self, $c ) = @_;
+
+ $c->stash->{template} = 'list.tt';
+
+ use Some::Outside::Database::Module;
+ my @records = Some::Outside::Database::Module->search({
+ artist => 'Led Zeppelin',
+ });
+
+ $c->stash->{records} = \@records;
+ }
-=item * B<Application Wide Actions>
+But by using a Model that is part of your Catalyst application, you
+gain several things: you don't have to C<use> each component, Catalyst
+will find and load it automatically at compile-time; you can
+C<forward> to the module, which can only be done to Catalyst
+components. Only Catalyst components can be fetched with
+C<$c-E<gt>model('SomeModel')>.
-Actions which are called at the root level of the application
-(e.g. http://localhost:3000/ ) go in MyApp::Controller::Root, like
-this:
+Happily, since many people have existing Model classes that they
+would like to use with Catalyst (or, conversely, they want to
+write Catalyst models that can be used outside of Catalyst, e.g.
+in a cron job), it's trivial to write a simple component in
+Catalyst that slurps in an outside Model:
- package MyApp::Controller::Root;
- use base 'Catalyst::Controller';
- # Sets the actions in this controller to be registered with no prefix
- # so they function identically to actions created in MyApp.pm
- __PACKAGE__->config->{namespace} = '';
- sub default : Private {
- my ( $self, $context ) = @_;
- $context->response->body('Catalyst rocks!');
- }
+ package MyApp::Model::DB;
+ use base qw/Catalyst::Model::DBIC::Schema/;
+ __PACKAGE__->config(
+ schema_class => 'Some::DBIC::Schema',
+ connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
+ );
1;
-=back
+and that's it! Now C<Some::DBIC::Schema> is part of your
+Cat app as C<MyApp::Model::DB>.
-=head4 Action types
+Within Catalyst, the common approach to writing a model for your
+application is wrapping a generic model (e.g. L<DBIx::Class::Schema>, a
+bunch of XMLs, or anything really) with an object that contains
+configuration data, convenience methods, and so forth. Thus you
+will in effect have two models - a wrapper model that knows something
+about Catalyst and your web application, and a generic model that is
+totally independent of these needs.
-Catalyst supports several types of actions:
+Technically, within Catalyst a model is a B<component> - an instance of
+the model's class belonging to the application. It is important to
+stress that the lifetime of these objects is per application, not per
+request.
+
+While the model base class (L<Catalyst::Model>) provides things like
+C<config> to better integrate the model into the application, sometimes
+this is not enough, and the model requires access to C<$c> itself.
+
+Situations where this need might arise include:
=over 4
-=item * B<Literal> (B<Path> actions)
+=item *
- package MyApp::Controller::My::Controller;
- sub bar : Path('foo/bar') { }
+Interacting with another model
-Literal C<Path> actions will act relative to their current
-namespace. The above example matches only
-http://localhost:3000/my/controller/foo/bar. If you start your path with
-a forward slash, it will match from the root. Example:
+=item *
- package MyApp::Controller::My::Controller;
- sub bar : Path('/foo/bar') { }
+Using per-request data to control behavior
-Matches only http://localhost:3000/foo/bar.
+=item *
- package MyApp::Controller::My::Controller;
- sub bar : Path { }
+Using plugins from a Model (for example L<Catalyst::Plugin::Cache>).
-By leaving the C<Path> definition empty, it will match on the namespace
-root. The above code matches http://localhost:3000/my/controller.
+=back
-=item * B<Regex>
+From a style perspective it's usually considered bad form to make your
+model "too smart" about things - it should worry about business logic
+and leave the integration details to the controllers. If, however, you
+find that it does not make sense at all to use an auxillary controller
+around the model, and the model's need to access C<$c> cannot be
+sidestepped, there exists a power tool called L</ACCEPT_CONTEXT>.
- sub bar : Regex('^item(\d+)/order(\d+)$') { }
+=head4 Controllers
-Matches any URL that matches the pattern in the action key, e.g.
-http://localhost:3000/item23/order42. The '' around the regexp is
-optional, but perltidy likes it. :)
+Multiple controllers are a good way to separate logical domains of your
+application.
-Regex matches act globally, i.e. without reference to the namespace from
-which it is called, so that a C<bar> method in the
-C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
-form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
-explicitly put this in the regex. To achieve the above, you should
-consider using a C<LocalRegex> action.
+ package MyApp::Controller::Login;
-=item * B<LocalRegex>
+ use base qw/Catalyst::Controller/;
- sub bar : LocalRegex('^widget(\d+)$') { }
-
-LocalRegex actions act locally. If you were to use C<bar> in
-C<MyApp::Controller::Catalog>, the above example would match urls like
-http://localhost:3000/catalog/widget23.
-
-If you omit the "C<^>" from your regex, then it will match any depth
-from the controller and not immediately off of the controller name. The
-following example differs from the above code in that it will match
-http://localhost:3000/catalog/foo/widget23 as well.
+ sub login : Path("login") { }
+ sub new_password : Path("new-password") { }
+ sub logout : Path("logout") { }
package MyApp::Controller::Catalog;
- sub bar : LocalRegex('widget(\d+)$') { }
-For both LocalRegex and Regex actions, if you use capturing parentheses
-to extract values within the matching URL, those values are available in
-the C<$c-E<gt>req-E<gt>captures> array. In the above example, "widget23"
-would capture "23" in the above example, and
-C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to pass
-arguments at the end of your URL, you must use regex action keys. See
-L</URL Path Handling> below.
-
-=item * B<Chained>
+ use base qw/Catalyst::Controller/;
-The C<Chained> attribute allows you to chain public path parts together
-by their private names. A chain part's path can be specified with C<PathPart>
-and can be declared to expect an arbitrary number of arguments. The endpoint
-of the chain specifies how many arguments it gets through the C<Args>
-attribute. C<:Args(0)> would be none at all, C<:Args> without an integer
-would be unlimited. The path parts that aren't endpoints are using
-C<Captures> to specify how many parameters they expect to receive. As an
-example setup:
-
- package MyApp::Controller::Greeting;
- use base qw/ Catalyst::Controller /;
-
- # this is the beginning of our chain
- sub hello : PathPart('hello') Chained('/') Captures(1) {
- my ( $self, $c, $integer ) = @_;
- $c->stash->{ message } = "Hello ";
- $c->stash->{ arg_sum } = $integer;
- }
-
- # this is our endpoint, because it has no :Captures
- sub world : PathPart('world') Chained('hello') Args(1) {
- my ( $self, $c, $integer ) = @_;
- $c->stash->{ message } .= "World!";
- $c->stash->{ arg_sum } += $integer;
-
- $c->response->body( join "<br/>\n" =>
- $c->stash->{ message }, $c->stash->{ arg_sum } );
- }
-
-The debug output provides a separate table for chained actions, showing
-the whole chain as it would match and the actions it contains. Here's
-an example of the startup output with our actions above:
-
- ...
- [debug] Loaded Path Part actions:
- .-----------------------+------------------------------.
- | Path Spec | Private |
- +-----------------------+------------------------------+
- | /hello/*/world/* | /greeting/hello (1) |
- | | => /greeting/world |
- '-----------------------+------------------------------'
- ...
-
-As you can see, Catalyst only deals with chains as whole path and
-builds one for each endpoint, which are the actions with C<:Chained>
-but without C<:Captures>.
-
-Let's assume this application gets a request at the path
-C</hello/23/world/12>, what happens then? First, Catalyst will dispatch
-to the C<hello> action and pass the value C<23> as argument to it after
-the context. It does so because we have previously used C<:Captures(1)>
-to declare that it has one path part after itself as it's argument. We
-told Catalyst that this is the beginning of the chain by specifying
-C<:Chained('/')>. Also note that instead of saying C<:PathPart('hello')>
-we could also just have said C<:PathPart>, as it defaults to the name of
-the action.
-
-After C<hello> has run, Catalyst goes on to dispatch to the C<world>
-action. This is the last action to be called, as Catalyst knows this
-is an endpoint because we specified no C<:Captures> attribute. Nevertheless
-we specify that this action expects an argument, but at this point we're
-using C<:Args(1)> to do that. We could also have said C<:Args> or leave
-it out alltogether, which would mean this action gets all arguments that
-are there. This action's C<:Chained> attribute says C<hello> and tells
-Catalyst that the C<hello> action in the current controller is it's
-parent.
-
-With this we have built a chain consisting of two public path parts.
-C<hello> captures one part of the path as it's argument, and also specifies
-the path root as it's parent. So this part is C</hello/$arg>. The next part
-is the endpoint C<world>, expecting one argument. It sums up to the path
-part C<world/$arg>. This leads to a complete chain of
-C</hello/$arg/world/$arg> which is matched against the requested paths.
-
-This example application would, if run and called by e.g.
-C</hello/23/world/12>, set the stash value C<message> to C<Hello > and
-the value C<arg_sum> to C<23>. The C<world> action would then append
-C<World!> to C<message> and add C<12> to the stash's C<arg_sum> value.
-For the sake of simplicity no view is shown. Instead we just put the
-values of the stash into our body. So the output would look like:
-
- Hello World!
- 35
-
-And our test server would've given us this debugging output for the
-request:
-
- ...
- [debug] "GET" request for "hello/23/world/12" from "127.0.0.1"
- [debug] Path is "/greeting/world"
- [debug] Arguments are "12"
- [info] Request took 0.164113s (6.093/s)
- .------------------------------------------+-----------.
- | Action | Time |
- +------------------------------------------+-----------+
- | /greeting/hello | 0.000029s |
- | /greeting/world | 0.000024s |
- '------------------------------------------+-----------'
- ...
-
-What would be common usecases of this dispatching technique? It gives the
-possibility to split up logic that contains steps that each depend on each
-other. An example would be, for example, a wiki path like
-C</wiki/FooBarPage/rev/23/view>. This chain can be easily built with
-these actions:
-
- sub wiki : PathPart('wiki') Chained('/') Captures(1) {
- my ( $self, $c, $page_name ) = @_;
- # load the page named $page_name and put the object
- # into the stash
- }
-
- sub rev : PathPart('rev') Chained('wiki') Captures(1) {
- my ( $self, $c, $revision_id ) = @_;
- # use the page object in the stash to get at it's
- # revision with number $revision_id
- }
-
- sub view : PathPart Chained('rev') Args(0) {
- my ( $self, $c ) = @_;
- # display the revision in our stash. An other option
- # would be to forward a compatible object to the action
- # that displays the default wiki pages, unless we want
- # a different interface here, for example restore
- # functionality.
- }
-
-It would now be possible to add other endpoints. For example C<restore> to
-restore this specific revision as current state.
-
-Also, you of course don't have to put all the chained actions in one
-controller. The specification of the parent through C<:Chained> also takes
-an absolute action path as it's argument. Just specify it with a leading
-C</>.
-
-If you want, for example, to have actions for the public paths
-C</foo/12/edit> and C</foo/12>, just specify two actions with
-C<:PathPart('foo')> and C<:Chained('/')>. The handler for the former
-path needs a C<:Captures(1)> attribute and a endpoint with
-C<:PathPart('edit')> and C<:Chained('foo')>. For the latter path give
-the action just a C<:Args(1)> to mark it as endpoint. This sums up to
-this debugging output:
-
- ...
- [debug] Loaded Path Part actions:
- .-----------------------+------------------------------.
- | Path Spec | Private |
- +-----------------------+------------------------------+
- | /foo/* | /controller/foo_view |
- | /foo/*/edit | /controller/foo_load (1) |
- | | => /controller/edit |
- '-----------------------+------------------------------'
- ...
-
-Here's a more detailed specification of the attributes belonging to
-C<:Chained>:
-
-=over 8
-
-=item PathPart
-
-Sets the name of this part of the chain. If it is specified without
-arguments, it takes the name of the action as default. So basically
-C<sub foo :PathPart> and C<sub foo :PathPart('foo')> are identical.
-This can also contain slashes to bind to a deeper level. An action
-with C<sub bar :PathPart('foo/bar') :Chained('/')> would bind to
-C</foo/bar/...>. If you don't specify C<:PathPart> it has the same
-effect as using C<:PathPart>, it would default to the action name.
-
-=item Chained
-
-Has to be specified for every child in the chain. Possible values are
-absolute and relative private action paths, with the relatives pointing
-to the current controller, or a single slash C</> to tell Catalyst that
-this is the root of a chain. The attribute C<:Chained> without aguments
-also defaults to the C</> behaviour.
-
-Due to the fact that you can specify an absolute path to the parent
-action, it doesn't matter to Catalyst where that parent is located. So,
-if your design requests it, you can redispatch a chain through every
-controller or namespace you want.
-
-Another interesting possibility gives C<:Chained('.')>, which chains
-itself to an action with the path of the current controllers namespace.
-For example:
-
- # in MyApp::Controller::Foo
- sub bar : Chained Captures(1) { ... }
-
- # in MyApp::Controller::Foo::Bar
- sub baz : Chained('.') Args(1) { ... }
-
-This builds up a chain like C</bar/*/baz/*>. The specification of C<.>
-as argument to Chained here chains the C<baz> action to an action with
-the path of the current controller namespace, namely C</foo/bar>. That
-action chains directly to C</>, so the above chain comes out as end
-product.
-
-=item Captures
-
-Also has to be specified for every part of the chain that is not an
-endpoint. With this attribute Catalyst knows how many of the following
-parts of the path (separated by C</>) this action wants to captures as
-it's arguments. If it doesn't expect any, just specify C<:Captures(0)>.
-The captures get passed to the action's C<@_> right after the context,
-but you can also find them as array reference in
-C<$c-E<gt>request-E<gt>captures-E<gt>[$level]>. The C<$level> is the
-level of the action in the chain that captured the parts of the path.
-
-An action that is part of a chain (read: that has a C<:Chained> attribute)
-but has no C<:Captures> attribute is treated by Catalyst as a chain end.
-
-=item Args
-
-By default, endpoints receive the rest of the arguments in the path. You
-can tell Catalyst through C<:Args> explicitly how many arguments your
-endpoint expects, just like you can with C<:Captures>. Note that this
-also influences if this chain is invoked on a request. A chain with an
-endpoint specifying one argument will only match if exactly one argument
-exists in the path.
-
-You can specify an exact number of arguments like C<:Args(3)>, including
-C<0>. If you just say C<:Args> without any arguments, it is the same as
-leaving it out alltogether: The chain is matched independent of the number
-of path parts after the endpoint.
-
-Just like with C<:Captures>, the arguments get passed to the action in
-C<@_> after the context object. They can also be reached through
-C<$c-E<gt>request-E<gt>arguments>.
+ sub view : Local { }
+ sub list : Local { }
-=back
+ package MyApp::Controller::Cart;
-Note that the list of C<auto> actions called depends on the private path
-of the endpoint of the chain, not on the chained actions way. The C<auto>
-actions will be run before the chain dispatching begins. In every other
-aspect, C<auto> actions behave as documented.
+ use base qw/Catalyst::Controller/;
-The C<forward>ing to other actions does just what you would expect. But if
-you C<detach> out of a chain, the rest of the chain will not get called
-after the C<detach> returned.
+ sub add : Local { }
+ sub update : Local { }
+ sub order : Local { }
-=item * B<Top-level> (B<Global>)
+Note that you can also supply attributes via the Controller's config so
+long as you have at least one attribute on a subref to be exported
+(:Action is commonly used for this) - for example the following is
+equivalent to the same controller above:
- package MyApp::Controller::Foo;
- sub foo : Global { }
+ package MyApp::Controller::Login;
-Matches http://localhost:3000/foo. The function name is mapped
-directly to the application base. You can provide an equivalent
-function in this case by doing the following:
+ use base qw/Catalyst::Controller/;
- package MyApp::Controller::Root
- sub foo : Local { }
+ __PACKAGE__->config(
+ actions => {
+ 'sign_in' => { Path => 'sign-in' },
+ 'new_password' => { Path => 'new-password' },
+ 'sign_out' => { Path => 'sign-out' },
+ },
+ );
-=item * B<Namespace-Prefixed> (B<Local>)
+ sub sign_in : Action { }
+ sub new_password : Action { }
+ sub sign_out : Action { }
- package MyApp::Controller::My::Controller;
- sub foo : Local { }
+=head3 ACCEPT_CONTEXT
-Matches http://localhost:3000/my/controller/foo.
+Whenever you call $c->component("Foo") you get back an object - the
+instance of the model. If the component supports the C<ACCEPT_CONTEXT>
+method instead of returning the model itself, the return value of C<<
+$model->ACCEPT_CONTEXT( $c ) >> will be used.
-This action type indicates that the matching URL must be prefixed with a
-modified form of the component's class (package) name. This modified
-class name excludes the parts that have a pre-defined meaning in
-Catalyst ("MyApp::Controller" in the above example), replaces "::" with
-"/", and converts the name to lower case. See L</Components> for a full
-explanation of the pre-defined meaning of Catalyst component class
-names.
+This means that whenever your model/view/controller needs to talk to C<$c> it
+gets a chance to do this when it's needed.
-=item * B<Private>
+A typical C<ACCEPT_CONTEXT> method will either clone the model and return one
+with the context object set, or it will return a thin wrapper that contains
+C<$c> and delegates to the per-application model object.
- sub foo : Private { }
+A typical C<ACCEPT_CONTEXT> method could look like this:
-Matches no URL, and cannot be executed by requesting a URL that
-corresponds to the action key. Private actions can be executed only
-inside a Catalyst application, by calling the C<forward> method:
+ sub ACCEPT_CONTEXT {
+ my ( $self, $c, @extra_arguments ) = @_;
+ bless { %$self, c => $c }, ref($self);
+ }
- $c->forward('foo');
+effectively treating $self as a B<prototype object> that gets a new parameter.
+C<@extra_arguments> comes from any trailing arguments to
+C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...) >>,
+C<< $c->view(...) >> etc).
-See L</Flow Control> for a full explanation of C<forward>. Note that, as
-discussed there, when forwarding from another component, you must use
-the absolute path to the method, so that a private C<bar> method in your
-C<MyApp::Controller::Catalog::Order::Process> controller must, if called
-from elsewhere, be reached with
-C<$c-E<gt>forward('/catalog/order/process/bar')>.
+The life time of this value is B<per usage>, and not per request. To make this
+per request you can use the following technique:
-=item * B<Args>
+Add a field to C<$c>, like C<my_model_instance>. Then write your
+C<ACCEPT_CONTEXT> method to look like this:
-Args is not an action type per se, but an action modifier - it adds a match
-restriction to any action it's provided to, requiring only as many path parts
-as are specified for the action to be valid - for example in
-MyApp::Controller::Foo,
+ sub ACCEPT_CONTEXT {
+ my ( $self, $c ) = @_;
- sub bar :Local
+ if ( my $per_request = $c->my_model_instance ) {
+ return $per_request;
+ } else {
+ my $new_instance = bless { %$self, c => $c }, ref($self);
+ Scalar::Util::weaken($new_instance->{c}); # or we have a circular reference
+ $c->my_model_instance( $new_instance );
+ return $new_instance;
+ }
+ }
-would match any URL starting /foo/bar/. To restrict this you can do
+=head3 Application Class
- sub bar :Local :Args(1)
+In addition to the Model, View, and Controller components, there's a
+single class that represents your application itself. This is where you
+configure your application, load plugins, and extend Catalyst.
-to only match /foo/bar/*/
+ package MyApp;
-=back
+ use strict;
+ use Catalyst qw/-Debug/; # Add other plugins here, e.g.
+ # for session support
-B<Note:> After seeing these examples, you probably wonder what the point
-is of defining names for regex and path actions. Every public action is
-also a private one, so you have one unified way of addressing components
-in your C<forward>s.
+ MyApp->config(
+ name => 'My Application',
-=head4 Built-in Private Actions
+ # You can put anything else you want in here:
+ my_configuration_variable => 'something',
+ );
+ 1;
-In response to specific application states, Catalyst will automatically
-call these built-in private actions in your application class:
+In older versions of Catalyst, the application class was where you put
+global actions. However, as of version 5.66, the recommended practice is
+to place such actions in a special Root controller (see L</Actions>,
+below), to avoid namespace collisions.
=over 4
-=item * B<default : Private>
-
-Called when no other action matches. Could be used, for example, for
-displaying a generic frontpage for the main app, or an error page for
-individual controllers.
-
-If C<default> isn't acting how you would expect, look at using a
-L</Literal> C<Path> action (with an empty path string). The difference is
-that C<Path> takes arguments relative from the namespace and C<default>
-I<always> takes arguments relative from the root, regardless of what
-controller it's in.
-
-=item * B<index : Private>
-
-C<index> is much like C<default> except that it takes no arguments
-and it is weighted slightly higher in the matching process. It is
-useful as a static entry point to a controller, e.g. to have a static
-welcome page. Note that it's also weighted higher than Path.
-
-=item * B<begin : Private>
-
-Called at the beginning of a request, before any matching actions are
-called.
-
-=item * B<end : Private>
+=item * B<name>
-Called at the end of a request, after all matching actions are called.
+The name of your application.
=back
-=head4 Built-in actions in controllers/autochaining
-
- Package MyApp::Controller::Foo;
- sub begin : Private { }
- sub default : Private { }
- sub auto : Private { }
-
-You can define built-in private actions within your controllers as
-well. The actions will override the ones in less-specific controllers,
-or your application class. In other words, for each of the three
-built-in private actions, only one will be run in any request
-cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
-run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
-and C<MyApp::Controller::Catalog::Order::begin> would override this in
-turn.
+Optionally, you can specify a B<root> parameter for templates and static
+data. If omitted, Catalyst will try to auto-detect the directory's
+location. You can define as many parameters as you want for plugins or
+whatever you need. You can access them anywhere in your application via
+C<$context-E<gt>config-E<gt>{$param_name}>.
-In addition to the normal built-in actions, you have a special action
-for making chains, C<auto>. Such C<auto> actions will be run after any
-C<begin>, but before your action is processed. Unlike the other
-built-ins, C<auto> actions I<do not> override each other; they will be
-called in turn, starting with the application class and going through to
-the I<most> specific class. I<This is the reverse of the order in which
-the normal built-ins override each other>.
+=head3 Context
-Here are some examples of the order in which the various built-ins
-would be called:
+Catalyst automatically blesses a Context object into your application
+class and makes it available everywhere in your application. Use the
+Context to directly interact with Catalyst and glue your L</Components>
+together. For example, if you need to use the Context from within a
+Template Toolkit template, it's already there:
-=over 4
+ <h1>Welcome to [% c.config.name %]!</h1>
-=item for a request for C</foo/foo>
+As illustrated in our URL-to-Action dispatching example, the Context is
+always the second method parameter, behind the Component object
+reference or class name itself. Previously we called it C<$context> for
+clarity, but most Catalyst developers just call it C<$c>:
- MyApp::begin
- MyApp::auto
- MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
- MyApp::end
+ sub hello : Global {
+ my ( $self, $c ) = @_;
+ $c->res->body('Hello World!');
+ }
-=item for a request for C</foo/bar/foo>
+The Context contains several important objects:
- MyApp::Controller::Foo::Bar::begin
- MyApp::auto
- MyApp::Controller::Foo::auto
- MyApp::Controller::Foo::Bar::auto
- MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
- MyApp::Controller::Foo::Bar::end
+=over 4
-=back
+=item * L<Catalyst::Request>
-The C<auto> action is also distinguished by the fact that you can break
-out of the processing chain by returning 0. If an C<auto> action returns
-0, any remaining actions will be skipped, except for C<end>. So, for the
-request above, if the first auto returns false, the chain would look
-like this:
+ $c->request
+ $c->req # alias
-=over 4
+The request object contains all kinds of request-specific information, like
+query parameters, cookies, uploads, headers, and more.
-=item for a request for C</foo/bar/foo> where first C<auto> returns
-false
+ $c->req->params->{foo};
+ $c->req->cookies->{sessionid};
+ $c->req->headers->content_type;
+ $c->req->base;
+ $c->req->uri_with( { page = $pager->next_page } );
- MyApp::Controller::Foo::Bar::begin
- MyApp::auto
- MyApp::Controller::Foo::Bar::end
+=item * L<Catalyst::Response>
-=back
+ $c->response
+ $c->res # alias
-An example of why one might use this is an authentication action: you
-could set up a C<auto> action to handle authentication in your
-application class (which will always be called first), and if
-authentication fails, returning 0 would skip any remaining methods
-for that URL.
+The response is like the request, but contains just response-specific
+information.
-B<Note:> Looking at it another way, C<auto> actions have to return a
-true value to continue processing! You can also C<die> in the autochain
-action; in that case, the request will go straight to the finalize
-stage, without processing further actions.
+ $c->res->body('Hello World');
+ $c->res->status(404);
+ $c->res->redirect('http://oook.de');
-=head4 URL Path Handling
+=item * L<Catalyst::Config>
-You can pass variable arguments as part of the URL path, separated with
-forward slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
-must be used. For example, suppose you want to handle C</foo/$bar/$baz>,
-where C<$bar> and C<$baz> may vary:
+ $c->config
+ $c->config->root;
+ $c->config->name;
- sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
+=item * L<Catalyst::Log>
-But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
+ $c->log
+ $c->log->debug('Something happened');
+ $c->log->info('Something you should know');
- sub boo : Path('foo/boo') { .. }
- sub hoo : Path('foo/boo/hoo') { .. }
+=item * B<Stash>
-Catalyst matches actions in most specific to least specific order:
+ $c->stash
+ $c->stash->{foo} = 'bar';
+ $c->stash->{baz} = {baz => 'qox'};
+ $c->stash->{fred} = [qw/wilma pebbles/];
- /foo/boo/hoo
- /foo/boo
- /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
+and so on.
-So Catalyst would never mistakenly dispatch the first two URLs to the
-'^foo$' action.
+=back
-If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
-still match a URL containing arguments, however the arguments won't be
-available via C<@_>.
+The last of these, the stash, is a universal hash for sharing data among
+application components. For an example, we return to our 'hello' action:
-=head4 Parameter Processing
+ sub hello : Global {
+ my ( $self, $c ) = @_;
+ $c->stash->{message} = 'Hello World!';
+ $c->forward('show_message');
+ }
-Parameters passed in the URL query string are handled with methods in
-the L<Catalyst::Request> class. The C<param> method is functionally
-equivalent to the C<param> method of C<CGI.pm> and can be used in
-modules that require this.
+ sub show_message : Private {
+ my ( $self, $c ) = @_;
+ $c->res->body( $c->stash->{message} );
+ }
- # http://localhost:3000/catalog/view/?category=hardware&page=3
- my $category = $c->req->param('category');
- my $current_page = $c->req->param('page') || 1;
+Note that the stash should be used only for passing data in an
+individual request cycle; it gets cleared at a new request. If you need
+to maintain persistent data, use a session. See
+L<Catalyst::Plugin::Session> for a comprehensive set of
+Catalyst-friendly session-handling tools.
- # multiple values for single parameter name
- my @values = $c->req->param('scrolling_list');
+=head3 Actions
- # DFV requires a CGI.pm-like input hash
- my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
+A Catalyst controller is defined by its actions. An action is a
+subroutine with a special attribute. You've already seen some examples
+of actions in this document. The URL (for example
+http://localhost.3000/foo/bar) consists of two parts, the base
+(http://localhost:3000/ in this example) and the path (foo/bar). Please
+note that the trailing slash after the hostname[:port] always belongs to
+base and not to the action.
-=head3 Flow Control
+=over 4
-You control the application flow with the C<forward> method, which
-accepts the key of an action to execute. This can be an action in the
-same or another Catalyst controller, or a Class name, optionally
-followed by a method name. After a C<forward>, the control flow will
-return to the method from which the C<forward> was issued.
+=item * B<Application Wide Actions>
-A C<forward> is similar to a method call. The main differences are that
-it wraps the call in an C<eval> to allow exception handling; it
-automatically passes along the context object (C<$c> or C<$context>);
-and it allows profiling of each call (displayed in the log with
-debugging enabled).
+Actions which are called at the root level of the application
+(e.g. http://localhost:3000/ ) go in MyApp::Controller::Root, like
+this:
- sub hello : Global {
- my ( $self, $c ) = @_;
- $c->stash->{message} = 'Hello World!';
- $c->forward('check_message'); # $c is automatically included
+ package MyApp::Controller::Root;
+ use base 'Catalyst::Controller';
+ # Sets the actions in this controller to be registered with no prefix
+ # so they function identically to actions created in MyApp.pm
+ __PACKAGE__->config->{namespace} = '';
+ sub default : Private {
+ my ( $self, $context ) = @_;
+ $context->response->body('Catalyst rocks!');
}
+ 1;
- sub check_message : Private {
- my ( $self, $c ) = @_;
- return unless $c->stash->{message};
- $c->forward('show_message');
- }
+=back
- sub show_message : Private {
- my ( $self, $c ) = @_;
- $c->res->body( $c->stash->{message} );
- }
+=head4 Action types
-A C<forward> does not create a new request, so your request object
-(C<$c-E<gt>req>) will remain unchanged. This is a key difference between
-using C<forward> and issuing a redirect.
+Catalyst supports several types of actions:
-You can pass new arguments to a C<forward> by adding them
-in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
-will be changed for the duration of the C<forward> only; upon
-return, the original value of C<$c-E<gt>req-E<gt>args> will
-be reset.
+=over 4
- sub hello : Global {
- my ( $self, $c ) = @_;
- $c->stash->{message} = 'Hello World!';
- $c->forward('check_message',[qw/test1/]);
- # now $c->req->args is back to what it was before
- }
+=item * B<Literal> (B<Path> actions)
- sub check_message : Private {
- my ( $self, $c ) = @_;
- my $first_argument = $c->req->args->[0]; # now = 'test1'
- # do something...
- }
+ package MyApp::Controller::My::Controller;
+ sub bar : Path('foo/bar') { }
-As you can see from these examples, you can just use the method name as
-long as you are referring to methods in the same controller. If you want
-to forward to a method in another controller, or the main application,
-you will have to refer to the method by absolute path.
+Literal C<Path> actions will act relative to their current
+namespace. The above example matches only
+http://localhost:3000/my/controller/foo/bar. If you start your path with
+a forward slash, it will match from the root. Example:
- $c->forward('/my/controller/action');
- $c->forward('/default'); # calls default in main application
+ package MyApp::Controller::My::Controller;
+ sub bar : Path('/foo/bar') { }
-Here are some examples of how to forward to classes and methods.
+Matches only http://localhost:3000/foo/bar.
- sub hello : Global {
- my ( $self, $c ) = @_;
- $c->forward(qw/MyApp::Model::Hello say_hello/);
- }
+ package MyApp::Controller::My::Controller;
+ sub bar : Path { }
- sub bye : Global {
- my ( $self, $c ) = @_;
- $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
- }
+By leaving the C<Path> definition empty, it will match on the namespace
+root. The above code matches http://localhost:3000/my/controller.
- package MyApp::Model::Hello;
+=item * B<Regex>
- sub say_hello {
- my ( $self, $c ) = @_;
- $c->res->body('Hello World!');
- }
+ sub bar : Regex('^item(\d+)/order(\d+)$') { }
- sub process {
- my ( $self, $c ) = @_;
- $c->res->body('Goodbye World!');
- }
+Matches any URL that matches the pattern in the action key, e.g.
+http://localhost:3000/item23/order42. The '' around the regexp is
+optional, but perltidy likes it. :)
-Note that C<forward> returns to the calling action and continues
-processing after the action finishes. If you want all further processing
-in the calling action to stop, use C<detach> instead, which will execute
-the C<detach>ed action and not return to the calling sub. In both cases,
-Catalyst will automatically try to call process() if you omit the
-method.
+Regex matches act globally, i.e. without reference to the namespace from
+which it is called, so that a C<bar> method in the
+C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
+form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
+explicitly put this in the regex. To achieve the above, you should
+consider using a C<LocalRegex> action.
-=head3 Components
+=item * B<LocalRegex>
-Catalyst has an uncommonly flexible component system. You can define as
-many L</Models>, L</Views>, and L</Controllers> as you like.
+ sub bar : LocalRegex('^widget(\d+)$') { }
-All components must inherit from L<Catalyst::Base>, which provides a
-simple class structure and some common class methods like C<config> and
-C<new> (constructor).
+LocalRegex actions act locally. If you were to use C<bar> in
+C<MyApp::Controller::Catalog>, the above example would match urls like
+http://localhost:3000/catalog/widget23.
+
+If you omit the "C<^>" from your regex, then it will match any depth
+from the controller and not immediately off of the controller name. The
+following example differs from the above code in that it will match
+http://localhost:3000/catalog/foo/widget23 as well.
package MyApp::Controller::Catalog;
+ sub bar : LocalRegex('widget(\d+)$') { }
- use strict;
- use base 'Catalyst::Base';
+For both LocalRegex and Regex actions, if you use capturing parentheses
+to extract values within the matching URL, those values are available in
+the C<$c-E<gt>req-E<gt>captures> array. In the above example, "widget23"
+would capture "23" in the above example, and
+C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to pass
+arguments at the end of your URL, you must use regex action keys. See
+L</URL Path Handling> below.
- __PACKAGE__->config( foo => 'bar' );
+=item * B<Top-level> (B<Global>)
- 1;
+ package MyApp::Controller::Foo;
+ sub foo : Global { }
-You don't have to C<use> or otherwise register Models, Views, and
-Controllers. Catalyst automatically discovers and instantiates them
-when you call C<setup> in the main application. All you need to do is
-put them in directories named for each Component type. Notice that you
-can use a terse alias for each one.
+Matches http://localhost:3000/foo. The function name is mapped
+directly to the application base. You can provide an equivalent
+function in this case by doing the following:
-=over 4
+ package MyApp::Controller::Root
+ sub foo : Local { }
-=item * B<MyApp/Model/>
+=item * B<Namespace-Prefixed> (B<Local>)
-=item * B<MyApp/M/>
+ package MyApp::Controller::My::Controller;
+ sub foo : Local { }
-=item * B<MyApp/View/>
+Matches http://localhost:3000/my/controller/foo.
-=item * B<MyApp/V/>
+This action type indicates that the matching URL must be prefixed with a
+modified form of the component's class (package) name. This modified
+class name excludes the parts that have a pre-defined meaning in
+Catalyst ("MyApp::Controller" in the above example), replaces "::" with
+"/", and converts the name to lower case. See L</Components> for a full
+explanation of the pre-defined meaning of Catalyst component class
+names.
-=item * B<MyApp/Controller/>
+=item * B<Chained>
-=item * B<MyApp/C/>
+Catalyst also provides a method to build and dispatch chains of actions,
+like
-=back
+ sub catalog : Chained : CaptureArgs(1) {
+ my ( $self, $c, $arg ) = @_;
+ ...
+ }
-In older versions of Catalyst, the recommended practice (and the one
-automatically created by helper scripts) was to name the directories
-C<M/>, C<V/>, and C<C/>. Though these still work, we now recommend
-the use of the full names.
+ sub item : Chained('catalog') : Args(1) {
+ my ( $self, $c, $arg ) = @_;
+ ...
+ }
-=head4 Views
+to handle a C</catalog/*/item/*> path. For further information about this
+dispatch type, please see L<Catalyst::DispatchType::Chained>.
-To show how to define views, we'll use an already-existing base class for the
-L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
-inherit from this class:
+=item * B<Private>
- package MyApp::View::TT;
+ sub foo : Private { }
- use strict;
- use base 'Catalyst::View::TT';
+Matches no URL, and cannot be executed by requesting a URL that
+corresponds to the action key. Private actions can be executed only
+inside a Catalyst application, by calling the C<forward> method:
- 1;
+ $c->forward('foo');
-(You can also generate this automatically by using the helper script:
+See L</Flow Control> for a full explanation of C<forward>. Note that, as
+discussed there, when forwarding from another component, you must use
+the absolute path to the method, so that a private C<bar> method in your
+C<MyApp::Controller::Catalog::Order::Process> controller must, if called
+from elsewhere, be reached with
+C<$c-E<gt>forward('/catalog/order/process/bar')>.
- script/myapp_create.pl view TT TT
+=item * B<Args>
-where the first C<TT> tells the script that the name of the view should
-be C<TT>, and the second that it should be a Template Toolkit view.)
+Args is not an action type per se, but an action modifier - it adds a
+match restriction to any action it's provided to, requiring only as many
+path parts as are specified for the action to be valid - for example in
+MyApp::Controller::Foo,
-This gives us a process() method and we can now just do
-$c->forward('MyApp::View::TT') to render our templates. The base class
-makes process() implicit, so we don't have to say
-C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
+ sub bar :Local
- sub hello : Global {
- my ( $self, $c ) = @_;
- $c->stash->{template} = 'hello.tt';
- }
+would match any URL starting /foo/bar/. To restrict this you can do
- sub end : Private {
- my ( $self, $c ) = @_;
- $c->forward('MyApp::View::TT');
- }
+ sub bar :Local :Args(1)
-You normally render templates at the end of a request, so it's a perfect
-use for the global C<end> action.
+to only match /foo/bar/*/
-Also, be sure to put the template under the directory specified in
-C<$c-E<gt>config-E<gt>{root}>, or you'll be forced to look at our
-eyecandy debug screen. ;)
+=back
-=head4 Models
+B<Note:> After seeing these examples, you probably wonder what the point
+is of defining names for regex and path actions. Every public action is
+also a private one, so you have one unified way of addressing components
+in your C<forward>s.
-To show how to define models, again we'll use an already-existing base
-class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>.
-We'll also need L<DBIx::Class::Schema::Loader>.
+=head4 Built-in Private Actions
-But first, we need a database.
+In response to specific application states, Catalyst will automatically
+call these built-in private actions in your application class:
- -- myapp.sql
- CREATE TABLE foo (
- id INTEGER PRIMARY KEY,
- data TEXT
- );
+=over 4
- CREATE TABLE bar (
- id INTEGER PRIMARY KEY,
- foo INTEGER REFERENCES foo,
- data TEXT
- );
+=item * B<default : Private>
- INSERT INTO foo (data) VALUES ('TEST!');
+Called when no other action matches. Could be used, for example, for
+displaying a generic frontpage for the main app, or an error page for
+individual controllers.
+If C<default> isn't acting how you would expect, look at using a
+L</Literal> C<Path> action (with an empty path string). The difference
+is that C<Path> takes arguments relative from the namespace and
+C<default> I<always> takes arguments relative from the root, regardless
+of what controller it's in. Indeed, this is now the recommended way of
+handling default situations; the C<default> private controller should
+be considered deprecated.
- % sqlite /tmp/myapp.db < myapp.sql
+=item * B<index : Private>
-Now we can create a DBIC::SchemaLoader component for this database.
+C<index> is much like C<default> except that it takes no arguments
+and it is weighted slightly higher in the matching process. It is
+useful as a static entry point to a controller, e.g. to have a static
+welcome page. Note that it's also weighted higher than Path.
- script/myapp_create.pl model DBIC DBIC::SchemaLoader 'dbi:SQLite:/tmp/myapp.db'
+=item * B<begin : Private>
-L<DBIx::Class::Schema::Loader> automatically loads table layouts and
-relationships. Use the stash to pass data to your templates.
+Called at the beginning of a request, before any matching actions are
+called.
-We add the following to MyApp/Controller/Root.pm
+=item * B<end : Private>
- sub view : Global {
- my ( $self, $c, $id ) = @_;
-
- $c->stash->{item} = $c->model('DBIC::Foo')->find($id);
- }
+Called at the end of a request, after all matching actions are called.
- 1;
-
- sub end : Private {
- my ( $self, $c ) = @_;
-
- $c->stash->{template} ||= 'index.tt';
- $c->forward( $c->view('TT') );
- }
+=back
+
+=head4 Built-in actions in controllers/autochaining
-We then create a new template file "root/index.tt" containing:
+ Package MyApp::Controller::Foo;
+ sub begin : Private { }
+ sub default : Private { }
+ sub auto : Private { }
- The Id's data is [% item.data %]
+You can define built-in private actions within your controllers as
+well. The actions will override the ones in less-specific controllers,
+or your application class. In other words, for each of the three
+built-in private actions, only one will be run in any request
+cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
+run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
+and C<MyApp::Controller::Catalog::Order::begin> would override this in
+turn.
-Models do not have to be part of your Catalyst application; you
-can always call an outside module that serves as your Model:
+=over 4
- # in a Controller
- sub list : Local {
- my ( $self, $c ) = @_;
-
- $c->stash->{template} = 'list.tt';
-
- use Some::Outside::DBIC::Module;
- my @records = Some::Outside::DBIC::Module->search({
- artist => 'sri',
- });
-
- $c->stash->{records} = \@records;
- }
+=item * B<auto : Private>
-But by using a Model that is part of your Catalyst application, you gain
-several things: you don't have to C<use> each component, Catalyst will
-find and load it automatically at compile-time; you can C<forward> to
-the module, which can only be done to Catalyst components; and only
-Catalyst components can be fetched with
-C<$c-E<gt>model('SomeModel')>.
+In addition to the normal built-in actions, you have a special action
+for making chains, C<auto>. Such C<auto> actions will be run after any
+C<begin>, but before your action is processed. Unlike the other
+built-ins, C<auto> actions I<do not> override each other; they will be
+called in turn, starting with the application class and going through to
+the I<most> specific class. I<This is the reverse of the order in which
+the normal built-ins override each other>.
-Happily, since many people have existing Model classes that they
-would like to use with Catalyst (or, conversely, they want to
-write Catalyst models that can be used outside of Catalyst, e.g.
-in a cron job), it's trivial to write a simple component in
-Catalyst that slurps in an outside Model:
+=back
- package MyApp::Model::DB;
- use base qw/Catalyst::Model::DBIC::Schema/;
- __PACKAGE__->config(
- schema_class => 'Some::DBIC::Schema',
- connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
- );
- 1;
+Here are some examples of the order in which the various built-ins
+would be called:
-and that's it! Now C<Some::DBIC::Schema> is part of your
-Cat app as C<MyApp::Model::DB>.
+=over 4
-=head4 Controllers
+=item for a request for C</foo/foo>
-Multiple controllers are a good way to separate logical domains of your
-application.
+ MyApp::begin
+ MyApp::auto
+ MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
+ MyApp::end
- package MyApp::Controller::Login;
+=item for a request for C</foo/bar/foo>
- use base qw/Catalyst::Controller/;
+ MyApp::Controller::Foo::Bar::begin
+ MyApp::auto
+ MyApp::Controller::Foo::auto
+ MyApp::Controller::Foo::Bar::auto
+ MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
+ MyApp::Controller::Foo::Bar::end
- sub sign_in : Path("sign-in") { }
- sub new_password : Path("new-password") { }
- sub sign_out : Path("sign-out") { }
+=back
- package MyApp::Controller::Catalog;
+The C<auto> action is also distinguished by the fact that you can break
+out of the processing chain by returning 0. If an C<auto> action returns
+0, any remaining actions will be skipped, except for C<end>. So, for the
+request above, if the first auto returns false, the chain would look
+like this:
- use base qw/Catalyst::Controller/;
+=over 4
- sub view : Local { }
- sub list : Local { }
+=item for a request for C</foo/bar/foo> where first C<auto> returns
+false
- package MyApp::Controller::Cart;
+ MyApp::Controller::Foo::Bar::begin
+ MyApp::auto
+ MyApp::Controller::Foo::Bar::end
- use base qw/Catalyst::Controller/;
+=back
- sub add : Local { }
- sub update : Local { }
- sub order : Local { }
+An example of why one might use this is an authentication action: you
+could set up a C<auto> action to handle authentication in your
+application class (which will always be called first), and if
+authentication fails, returning 0 would skip any remaining methods
+for that URL.
-Note that you can also supply attributes via the Controller's config so long
-as you have at least one attribute on a subref to be exported (:Action is
-commonly used for this) - for example the following is equivalent to the same
-controller above
+B<Note:> Looking at it another way, C<auto> actions have to return a
+true value to continue processing! You can also C<die> in the auto
+action; in that case, the request will go straight to the finalize
+stage, without processing further actions.
- package MyApp::Controller::Login;
+=head4 URL Path Handling
- use base qw/Catalyst::Controller/;
+You can pass variable arguments as part of the URL path, separated with
+forward slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
+must be used. For example, suppose you want to handle C</foo/$bar/$baz>,
+where C<$bar> and C<$baz> may vary:
- __PACKAGE__->config(
- actions => {
- 'sign_in' => { Path => 'sign-in' },
- 'new_password' => { Path => 'new-password' },
- 'sign_out' => { Path => 'sign-out' },
- },
- );
+ sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
- sub sign_in : Action { }
- sub new_password : Action { }
- sub sign_out : Action { }
+But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
+
+ sub boo : Path('foo/boo') { .. }
+ sub hoo : Path('foo/boo/hoo') { .. }
-=head3 Models
+Catalyst matches actions in most specific to least specific order:
-Models are providers of data. This data could come from anywhere - a search
-engine index, a database table, etc. Typically the data source does not have
-much to do with web applications or Catalyst - it could be used to write an
-offline report generator or a command line tool just the same.
+ /foo/boo/hoo
+ /foo/boo
+ /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
-The common approach to writing a Catalyst-style model for your application is
-wrapping a generic model (e.g. L<DBIx::Class::Schema>, a bunch of XMLs, or
-anything really) with an object that contains configuration data, convenience
-methods, and so forth.
+So Catalyst would never mistakenly dispatch the first two URLs to the
+'^foo$' action.
-#### editor: move this part to =head3 Components somehow, right after this
-#### section - this will require deeply rephrasing this paragraph.
+If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
+still match a URL containing arguments, however the arguments won't be
+available via C<@_>.
-Technically, within Catalyst a model is a B<component> - an instance of the
-model's class belonging to the application. It is important to stress that the
-lifetime of these objects is per application, not per request.
+=head4 Parameter Processing
-While the model base class (L<Catalyst::Model>) provides things like C<config>
-and stuff to better integrate the model into the application, sometimes this is
-not enough, and the model requires access to C<$c> itself.
+Parameters passed in the URL query string are handled with methods in
+the L<Catalyst::Request> class. The C<param> method is functionally
+equivalent to the C<param> method of C<CGI.pm> and can be used in
+modules that require this.
-Situations where this need might arise include:
+ # http://localhost:3000/catalog/view/?category=hardware&page=3
+ my $category = $c->req->param('category');
+ my $current_page = $c->req->param('page') || 1;
-=over 4
+ # multiple values for single parameter name
+ my @values = $c->req->param('scrolling_list');
-=item *
+ # DFV requires a CGI.pm-like input hash
+ my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
-Interacting with another model
+=head3 Flow Control
-=item *
+You control the application flow with the C<forward> method, which
+accepts the key of an action to execute. This can be an action in the
+same or another Catalyst controller, or a Class name, optionally
+followed by a method name. After a C<forward>, the control flow will
+return to the method from which the C<forward> was issued.
-Using per-request data to control behavior
+A C<forward> is similar to a method call. The main differences are that
+it wraps the call in an C<eval> to allow exception handling; it
+automatically passes along the context object (C<$c> or C<$context>);
+and it allows profiling of each call (displayed in the log with
+debugging enabled).
-=item *
+ sub hello : Global {
+ my ( $self, $c ) = @_;
+ $c->stash->{message} = 'Hello World!';
+ $c->forward('check_message'); # $c is automatically included
+ }
-Using plugins in (for example L<Catalyst::Plugin::Cache>).
+ sub check_message : Private {
+ my ( $self, $c ) = @_;
+ return unless $c->stash->{message};
+ $c->forward('show_message');
+ }
-=back
+ sub show_message : Private {
+ my ( $self, $c ) = @_;
+ $c->res->body( $c->stash->{message} );
+ }
-From a style perspective usually it's bad to make your model "too smart"
-about things - it should worry about business logic and leave the
-integration details to the controllers. If, however, you find that it
-does not make sense at all to use an auxillary controller around the
-model, and the model's need to access C<$c> cannot be sidestepped, there
-exists a power tool called C<ACCEPT_CONTEXT>.
+A C<forward> does not create a new request, so your request object
+(C<$c-E<gt>req>) will remain unchanged. This is a key difference between
+using C<forward> and issuing a redirect.
-#### editor note: this part is "generic" - it also applies to views and
-#### controllers.
+You can pass new arguments to a C<forward> by adding them
+in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
+will be changed for the duration of the C<forward> only; upon
+return, the original value of C<$c-E<gt>req-E<gt>args> will
+be reset.
-=head3 ACCEPT_CONTEXT
+ sub hello : Global {
+ my ( $self, $c ) = @_;
+ $c->stash->{message} = 'Hello World!';
+ $c->forward('check_message',[qw/test1/]);
+ # now $c->req->args is back to what it was before
+ }
-Whenever you call $c->component("Foo") you get back an object - the
-instance of the model. If the component supports the C<ACCEPT_CONTEXT>
-method instead of returning the model itself, the return value of C<<
-$model->ACCEPT_CONTEXT( $c ) >> will be used.
+ sub check_message : Private {
+ my ( $self, $c ) = @_;
+ my $first_argument = $c->req->args->[0]; # now = 'test1'
+ # do something...
+ }
-This means that whenever your model/view/controller needs to talk to C<$c> it
-gets a chance to do this when it's needed.
+As you can see from these examples, you can just use the method name as
+long as you are referring to methods in the same controller. If you want
+to forward to a method in another controller, or the main application,
+you will have to refer to the method by absolute path.
-A typical C<ACCEPT_CONTEXT> method will either clone the model and return one
-with the context object set, or it will return a thin wrapper that contains
-C<$c> and delegates to the per-application model object.
+ $c->forward('/my/controller/action');
+ $c->forward('/default'); # calls default in main application
-A typical C<ACCEPT_CONTEXT> method could look like this:
+Here are some examples of how to forward to classes and methods.
- sub ACCEPT_CONTEXT {
- my ( $self, $c, @extra_arguments ) = @_;
- bless { %$self, c => $c }, ref($self);
- }
+ sub hello : Global {
+ my ( $self, $c ) = @_;
+ $c->forward(qw/MyApp::Model::Hello say_hello/);
+ }
-effectively treating $self as a B<prototype object> that gets a new parameter.
-C<@extra_arguments> comes from any trailing arguments to
-C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...) >>,
-C<< $c->view(...) >> etc).
+ sub bye : Global {
+ my ( $self, $c ) = @_;
+ $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
+ }
-The life time of this value is B<per usage>, and not per request. To make this
-per request you can use the following technique:
+ package MyApp::Model::Hello;
-Add a field to C<$c>, like C<my_model_instance>. Then write your
-C<ACCEPT_CONTEXT> method to look like this:
+ sub say_hello {
+ my ( $self, $c ) = @_;
+ $c->res->body('Hello World!');
+ }
- sub ACCEPT_CONTEXT {
- my ( $self, $c ) = @_;
+ sub process {
+ my ( $self, $c ) = @_;
+ $c->res->body('Goodbye World!');
+ }
- if ( my $per_request = $c->my_model_instance ) {
- return $per_request;
- } else {
- my $new_instance = bless { %$self, c => $c }, ref($self);
- Scalar::Util::weaken($new_instance->{c}); # or we have a circular reference
- $c->my_model_instance( $new_instance );
- return $new_instance;
- }
- }
+Note that C<forward> returns to the calling action and continues
+processing after the action finishes. If you want all further processing
+in the calling action to stop, use C<detach> instead, which will execute
+the C<detach>ed action and not return to the calling sub. In both cases,
+Catalyst will automatically try to call process() if you omit the
+method.
=head3 Testing
-Catalyst has a built-in http server for testing. (Later, you can easily
-use a more powerful server, e.g. Apache/mod_perl or FastCGI, in a
-production environment.)
+Catalyst has a built-in http server for testing or local
+deployment. (Later, you can easily use a more powerful server, for
+example Apache/mod_perl or FastCGI, in a production environment.)
Start your application on the command line...
script/myapp_test.pl http://localhost/
+Catalyst has a number of tools for actual regression testing of
+applications. The helper scripts will automatically generate basic tests
+that can be extended as you develop your project. To write your own
+comprehensive test scripts, L<Test::WWW::Mechanize::Catalyst> is an
+invaluable tool.
+
+For more testing ideas, see L<Catalyst::Manual::Tutorial::Testing>.
+
Have fun!
+=head1 SEE ALSO
+
+=over 4
+
+=item * L<Catalyst::Manual::About>
+
+=item * L<Catalyst::Manual::Tutorial>
+
+=item * L<Catalyst>
+
+=back
+
=head1 SUPPORT
IRC:
Join #catalyst on irc.perl.org.
+ Join #catalyst-dev on irc.perl.org to help with development.
-Mailing-lists:
+Mailing lists:
http://lists.rawmode.org/mailman/listinfo/catalyst
http://lists.rawmode.org/mailman/listinfo/catalyst-dev
=head1 COPYRIGHT
-This program is free software, you can redistribute it and/or modify it
+This program is free software. You can redistribute it and/or modify it
under the same terms as Perl itself.
projects / catagits/Catalyst-Runtime.git / blobdiff