=head1 DESCRIPTION
-This is a brief overview of why and how to use Catalyst. It explains how Catalyst works and shows how to quickly get a simple application up and running.
+This is a brief overview of why and how to use Catalyst. It explains how Catalyst works and shows how to get a simple application up and running quickly.
=head2 What is Catalyst?
=head3 MVC
-Catalyst follows the Model-View-Controller (MVC) design pattern, allowing you to easily separate concerns, like content, presentation and flow control, into separate modules. This separation allows you to modify code that handles one concern without affecting code that handles the others. Catalyst promotes re-use of existing Perl modules that already handle common web application concerns well.
+Catalyst follows the Model-View-Controller (MVC) design pattern, allowing you to easily separate concerns, like content, presentation, and flow control, into separate modules. This separation allows you to modify code that handles one concern without affecting code that handles 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 M, V, and C map to those concerns, with examples of well-known Perl modules you may want to use for each.
=over 4
=item * B<View>
-Present content to the user. L<Template Toolkit|Template>, L<Mason|HTML::Mason>...
+Present content to the user. L<Template Toolkit|Template>, L<Mason|HTML::Mason>, L<HTML::Template>...
=item * B<Controller>
=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. We'll talk more about this later, but rest assured you can use your favorite Perl modules with Catalyst.
=over 4
-=item * B<Multiple Models, Views and Controllers>
+=item * B<Multiple Models, Views, and Controllers>
-To build a Catalyst application, you handle each type of concern inside special modules called L</Components>. Often this code will be very simple, just calling out to Perl modules like those listed above under L</MVC>. Catalyst handles these components in a very flexible way. Use as many Models, Views and Controllers as you like, using as many different Perl modules as you like, all in the same application. Want to manipulate multiple databases, and retrieve some data via LDAP? No problem. Want to present data from the same Model using L<Template Toolkit|Template> and L<PDF::Template>? Easy.
+To build a Catalyst application, you handle each type of concern inside special modules called L</Components>. Often this code will be very simple, just calling out to Perl modules like those listed above under L</MVC>. Catalyst handles these components in a very flexible way. Use as many Models, Views, and Controllers as you like, using as many different Perl modules as you like, all in the same application. Want to manipulate multiple databases, and retrieve some data via LDAP? No problem. Want to present data from the same Model using L<Template Toolkit|Template> and L<PDF::Template>? Easy.
=item * B<Reuseable Components>
See L<Catalyst::Model::CDBI> for L<Class::DBI>, or L<Catalyst::View::TT> for L<Template Toolkit|Template>. You can even get an instant web database front end with L<Catalyst::Model::CDBI::CRUD>.
-=item * B<Builtin Test Framework>
+=item * B<Built-in Test Framework>
-Catalyst comes with a builtin, lightweight http server and test framework, making it easy to test applications from the command line.
+Catalyst comes with a built-in, lightweight http server and test framework, making it easy to test applications from the command line.
=item * B<Helper Scripts>
=head3 Setup
$ catalyst.pl MyApp
+ # output omitted
$ cd MyApp
- $ script/create.pl controller My::Controller
+ $ script/myapp_create.pl controller Library::Login
=head3 Run
- $ script/server.pl
+ $ script/myapp_server.pl
Now visit these locations with your favorite browser or user agent to see Catalyst in action:
=item http://localhost:3000/
-=item http://localhost:3000/my_controller/
+=item http://localhost:3000/library/login/
=back
=head3 Application Class
-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, define application-wide actions and extend Catalyst.
+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, define application-wide actions, and extend Catalyst.
package MyApp;
name => 'My Application',
root => '/home/joeuser/myapp/root',
- # You can put whatever you want in here:
- # my_param_name => $my_param_value,
+ # You can put anything else you want in here:
+ my_configuration_variable => 'something',
);
sub default : Private {
=item * B<root>
-Path to additional files like templates, images or other static data.
+Path to additional files such as templates, images, or other static data.
=back
=head3 Context
-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.
+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:
+
+ <h1>Welcome to [% c.config.name %]!</h1>
As illustrated earlier 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>:
$c->request
$c->req # alias
-The request object contains all kinds of request-specific information, like query parameters, cookies, uploads, headers and more.
+The request object contains all kinds of request-specific information, like query parameters, cookies, uploads, headers, and more.
$c->req->params->{foo};
$c->req->cookies->{sessionid};
sub hello : Global {
my ( $self, $c ) = @_;
$c->stash->{message} = 'Hello World!';
- $c->forward('show-message');
+ $c->forward('show_message');
}
- sub show-message : Private {
+ sub show_message : Private {
my ( $self, $c ) = @_;
$c->res->output( $c->stash->{message} );
}
-=head3 Actions
+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.
-A Catalyst controller is defined by it's actions. An action is a sub
-with a special attribute. You've already seen some example of actions
+=head3 Actions
-in this document.
+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.
Catalyst supports several types of actions:
=item * B<Literal>
- sub bar : Path('/foo/bar') { }
+ sub bar : Path('foo/bar') { }
Matches only http://localhost:3000/foo/bar.
=item * B<Regex>
- sub bar : Regex('^foo(\d+)/bar(\d+)$') { }
+ sub bar : Regex('^item(\d+)/order(\d+)$') { }
+
+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. :)
-Matches any URL that matches the pattern in the action key, e.g. http://localhost:3000/foo23/bar42. The '' around the regexp is optional, but perltidy likes it. :)
+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.
-If you use capturing parantheses to extract values within the matching URL (23, 42 in the above example), those values are available in the $c->req->snippets array. If you want to pass arguments at the end of your URL, you must use regex action keys. See L</URL Argument Handling> below.
+If you use capturing parentheses to extract values within the matching URL (23, 42 in the above example), those values are available in the $c->req->snippets array. If you want to pass arguments at the end of your URL, you must use regex action keys. See L</URL Argument Handling> below.
-=item * B<Toplevel>
+=item * B<Top-level>
package MyApp;
sub foo : Global { }
-Matches http://localhost:3000/foo. The function name is mapped
-directly to the application base.
+Matches http://localhost:3000/foo. The function name is mapped directly
+to the application base.
=item * B<Namespace-Prefixed>
Matches http://localhost:3000/my/controller/foo.
-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::C" 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 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::C" 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<Private>
$c->forward('foo');
-See L</Flow Control> for a full explanation of C<forward>.
+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 reach with C<$c-E<gt>forward('/catalog/order/process/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 forwards.
+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.
-=head4 Builtin Private Actions
+=head4 Built-in Private Actions
-In response to specific application states, Catalyst will automatically call these built in private actions:
+In response to specific application states, Catalyst will automatically call these built-in private actions:
=over 4
Called at the end of a request, after all matching actions are called.
-=head4 B<Builtin actions in controllers/autochaining>
+=head4 B<Built-in actions in controllers/autochaining>
Package MyApp::C::Foo;
sub begin : Private { }
sub default : Private { }
-You can define the Builtin Private Actions within your controllers as
-well. The actions will override the ones in lower level controllers/
-global.
+You can define the Built-in Private Actions within your controllers as
+well. The actions will override the ones in lower level controllers or
+your global application.
-In addition to the normal builtins, you have a special action for
-making inheritance chains, 'auto'. These will be run after begin,
+In addition to the normal built-ins, you have a special action for
+making inheritance chains, 'auto'. These will be run after C<begin>,
but before your action is processed.
=over 4
MyApp::begin
MyApp::auto
- MyApp::default
+ MyApp::C::Foo::default
MyApp::end
=item for a request for /foo/bar/foo
=back
-I<Note:> You can also die in the autochain action, in that case,
-the request will go straight to the finalize stage, without processing
+B<Note:> auto actions have to return a true value to continue
+processing! You can also die in the autochain action, in that case, the
+request will go straight to the finalize stage, without processing
further actions.
But what if you also defined actions for /foo/boo and /foo/boo/hoo ?
- sub boo : Path('/foo/boo') { .. }
- sub hoo : Path('/foo/boo/hoo') { .. }
+ sub boo : Path('foo/boo') { .. }
+ sub hoo : Path('foo/boo/hoo') { .. }
Catalyst matches actions in most specific to least specific order:
sub hello : Global {
my ( $self, $c ) = @_;
$c->stash->{message} = 'Hello World!';
- $c->forward('check-message');
+ $c->forward('check_message');
}
- sub check-message : Private {
+ sub check_message : Private {
my ( $self, $c ) = @_;
return unless $c->stash->{message};
- $c->forward('show-message');
+ $c->forward('show_message');
}
- sub show-message : Private {
+ sub show_message : Private {
my ( $self, $c ) = @_;
$c->res->output( $c->stash->{message} );
}
-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 asbolute path.
+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.
$c->forward('/my/controller/action');
$c->forward('/default');
=head3 Components
-Again, 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).
- package MyApp::C::MyController;
+ package MyApp::C::Catalog;
use strict;
use base 'Catalyst::Base';
1;
-You don't have to C<use> or otherwise register Models, Views and Controllers. Catalyst automatically discovers and instantiates them when you call 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 some very terse aliases for each one.
+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 some very terse aliases for each one.
=over 4
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 to create a Template Toolkit
+view, and the second tells the script that its name should be C<TT>.)
+
This gives us a process() method and we can now just do $c->forward('MyApp::V::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::V::TT process/)>.
sub hello : Global {
$c->forward('MyApp::V::TT');
}
-You normally render templates at the end of a request, so it's a perfect use for the global end action.
+You normally render templates at the end of a request, so it's a perfect use for the global C<end> action.
-Also, be sure to put the template under the directory specified in C<$c-E<gt>config->{root}>, or you'll be forced to look at our eyecandy debug screen. ;)
+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. ;)
=head4 Models
=head4 Controllers
-Multiple Controllers are a good way to separate logical domains of your application.
+Multiple controllers are a good way to separate logical domains of your application.
package MyApp::C::Login;
- sign-in : Relative { }
- new-password :Relative { }
- sign-out : Relative { }
+ sign-in : Local { }
+ new-password : Local { }
+ sign-out : Local { }
package MyApp::C::Catalog;
=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, in a production environment).
+Catalyst has a built-in http server for testing! (Later, you can easily use a more powerful server, e.g. Apache/mod_perl, in a production environment.)
Start your application on the command line...
- script/server.pl
+ script/myapp_server.pl
...then visit http://localhost:3000/ in a browser to view the output.
You can also do it all from the command line:
- script/test.pl http://localhost/
+ script/myapp_test.pl http://localhost/
Have fun!
Join #catalyst on irc.perl.org.
-Mailing-Lists:
+Mailing-lists:
http://lists.rawmode.org/mailman/listinfo/catalyst
http://lists.rawmode.org/mailman/listinfo/catalyst-dev
Sebastian Riedel, C<sri@oook.de>
David Naughton, C<naughton@umn.edu>
Marcus Ramberg, C<mramberg@cpan.org>
+Jesse Sheidlower, C<jester@panix.com>
=head1 COPYRIGHT
projects / catagits/Catalyst-Runtime.git / blobdiff