=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
+extremely simple. It's similar to Ruby on Rails, Spring (Java), and
L<Maypole>, upon which it was originally based.
=head3 MVC
=item * B<Controller>
Control the whole request phase, check parameters, dispatch actions, flow
-control. Catalyst!
+control. Catalyst itself!
=back
If you're unfamiliar with MVC and design patterns, you may want to 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). You
-can also just Google it. Many, many web application frameworks are
-based on MVC, including all those listed above.
+Helm, Johnson, and Vlissides, also known as the Gang of Four (GoF).
+Many, many web application frameworks are based on MVC, including all
+those listed above.
=head3 Flexibility
=item * B<Unrestrained URL-to-Action Dispatching>
-Catalyst allows you to dispatch any URLs to any application L<Actions>,
+Catalyst allows you to dispatch any URLs to any application L</Actions>,
even through regular expressions! Unlike most other frameworks, it
doesn't require mod_rewrite or class and method names in URLs.
=item * B<Building Block Interface>
Components interoperate very smoothly. For example, Catalyst
-automatically makes a L<Context> object available to every
+automatically makes a L</Context> object available to every
component. Via the context, you can access the request object, share
data between components, and control the flow of your
application. Building a Catalyst application feels a lot like snapping
Now visit these locations with your favorite browser or user agent to see
Catalyst in action:
+(NOTE: Although we create a controller here, we don't actually use it.
+Both of these URLs should take you to the welcome page.)
+
+
=over 4
=item http://localhost:3000/
=back
-Dead easy!
+Easy!
=head2 How It Works
=item * B<name>
-Name of your application.
+The name of your application.
=back
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>
+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:
=item * L<Catalyst::Log>
$c->log
-
$c->log->debug('Something happened');
$c->log->info('Something you should know');
=head3 Actions
-A Catalyst controller is defined by its actions. An action is a sub 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.
+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.
Catalyst supports several types of actions:
=over 4
-=item * B<Literal>
+=item * B<Literal> (B<Path> actions)
package MyApp::Controller::My::Controller;
sub bar : Path('foo/bar') { }
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>snippets> array. In the above example, "widget23"
+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>snippets-E<gt>[0]> would be "23". If you want to pass
+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<Top-level>
+=item * B<Top-level> (B<Global>)
package MyApp;
sub foo : Global { }
Matches http://localhost:3000/foo. The function name is mapped directly
to the application base.
-=item * B<Namespace-Prefixed>
+=item * B<Namespace-Prefixed> (B<Local>)
package MyApp::Controller::My::Controller;
sub foo : Local { }
from elsewhere, be reached with
C<$c-E<gt>forward('/catalog/order/process/bar')>.
+=item * B<Args>
+
+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 bar :Local
+
+would match any URL starting /foo/bar/. To restrict this you can do
+
+ sub bar :Local :Args(1)
+
+to only match /foo/bar/*/
+
=back
B<Note:> After seeing these examples, you probably wonder what the point
-is of defining names for regex and path actions. Actually, every public
-action is also a private one, so you have one unified way of addressing
-components in your C<forward>s.
+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.
=head4 Built-in Private Actions
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
+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.
sub check_message : Private {
my ( $self, $c ) = @_;
- my $first_argument = $c->req->args[0]; # now = 'test1'
+ my $first_argument = $c->req->args->[0]; # now = 'test1'
# do something...
}
=head3 Components
-Catalyst has an uncommonly flexible component system. You can define as many
-L<Models>, L<Views>, and L<Controllers> as you like.
+Catalyst has an uncommonly flexible component system. You can define as
+many L</Models>, L</Views>, and L</Controllers> as you like.
-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).
+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 base qw/Catalyst::Model::DBIC::Schema/;
__PACKAGE__->config(
schema_class => 'Some::DBIC::Schema',
- connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}];
+ connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
);
1;