=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, Johson 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.
+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.
=head3 Flexibility
sub hello : Global {
my ( $self, $context ) = @_;
- $context->response->output('Hello World!');
+ $context->response->body('Hello World!');
}
Now http://localhost:3000/hello prints "Hello World!".
MyApp->config(
name => 'My Application',
- root => '/home/joeuser/myapp/root',
# You can put anything else you want in here:
my_configuration_variable => 'something',
sub default : Private {
my ( $self, $context ) = @_;
- $context->response->output('Catalyst rockz!');
+ $context->response->body('Catalyst rockz!');
}
1;
-For most applications, Catalyst requires you to define only two config
-parameters:
+For most applications, Catalyst requires you to define only one config
+parameter:
=over 4
Name of your application.
-=item * B<root>
-
-Path to additional files such as templates, images, or other static data.
-
=back
-However, 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}>.
+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}>.
=head3 Context
sub hello : Global {
my ( $self, $c ) = @_;
- $c->res->output('Hello World!');
+ $c->res->body('Hello World!');
}
The Context contains several important objects:
The response is like the request, but contains just response-specific
information.
- $c->res->output('Hello World');
+ $c->res->body('Hello World');
$c->res->status(404);
$c->res->redirect('http://oook.de');
sub show_message : Private {
my ( $self, $c ) = @_;
- $c->res->output( $c->stash->{message} );
+ $c->res->body( $c->stash->{message} );
}
Note that the stash should be used only for passing data in an individual
=item * B<Literal>
+ package MyApp::C::My::Controller;
sub bar : Path('foo/bar') { }
+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:
+
+ package MyApp::C::My::Controller;
+ sub bar : Path('/foo/bar') { }
+
Matches only http://localhost:3000/foo/bar.
+ package MyApp::C::My::Controller;
+ sub bar : Path { }
+
+By leaving the C<Path> definition empty, it will match on the namespace root.
+The above code matches http://localhost:3000/my/controller.
+
=item * B<Regex>
sub bar : Regex('^item(\d+)/order(\d+)$') { }
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.
+the regex. To achieve the above, you should consider using a C<LocalRegex> action.
+
+=item * B<LocalRegex>
+
+ 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
+differes from the above code in that it will match
+http://localhost:3000/catalog/foo/widget23 as well.
-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
+ 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 ("widget23" would capture "23" 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.
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
+being that C<Path> takes arguments relative from the namespace and
+C<default> takes arguments relative from the root.
+
+=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.
+
=item * B<begin : Private>
Called at the beginning of a request, before any matching actions are
=back
-=head4 B<Built-in actions in controllers/autochaining>
+=head4 Built-in actions in controllers/autochaining
Package MyApp::C::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,
place of C<MyApp::begin> if you're in the C<catalog> namespace, and
C<MyApp::C::Catalog::Order::begin> would override this in turn.
-In addition to the normal built-ins, you have a special action for
-making chains, C<auto>. Such C<auto> actions will be run after any
+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>.
+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>.
Here are some examples of the order in which the various built-ins
would be called:
action; in that case, the request will go straight to the finalize
stage, without processing further actions.
-=head4 B<URL Path Handling>
+=head4 URL Path Handling
You can pass variable arguments as part of the URL path. In this case,
you must use regex action keys with '^' and '$' anchors, and the
So Catalyst would never mistakenly dispatch the first two URLs to the
'^foo$' action.
-=head4 B<Parameter Processing>
+=head4 Parameter Processing
Parameters passed in the URL query string are handled with methods in
the L<Catalyst::Request> class. The C<param> method is functionally
sub show_message : Private {
my ( $self, $c ) = @_;
- $c->res->output( $c->stash->{message} );
+ $c->res->body( $c->stash->{message} );
}
A C<forward> does not create a new request, so your request
sub say_hello {
my ( $self, $c ) = @_;
- $c->res->output('Hello World!');
+ $c->res->body('Hello World!');
}
sub process {
my ( $self, $c ) = @_;
- $c->res->output('Goodbye World!');
+ $c->res->body('Goodbye World!');
}
Note that C<forward> returns to the calling action and continues
1;
-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.
+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
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>.)
+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::V::TT') to render our templates. The base class makes
$c->forward('MyApp::V::TT');
}
-You normally render templates at the end of a request, so it's a perfect use for
-the global C<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-E<gt>{root}>, or you'll be forced to look at our eyecandy debug
-screen. ;)
+C<$c-E<gt>config-E<gt>{root}>, or you'll be forced to look at our
+eyecandy debug screen. ;)
=head4 Models
1;
+ # Then, in a TT template:
The id is [% item.data %]
+Models do not have to be part of your Catalyst application; you
+can always call an outside module that serves as your Model:
+
+ # in a Controller
+ sub list : Local {
+ my ( $self, $c ) = @_;
+ $c->stash->{template} = 'list.tt';
+ use Some::Outside::CDBI::Module;
+ my @records = Some::Outside::CDBI::Module->retrieve_all;
+ $c->stash->{records} = \@records;
+ }
+
+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>comp('MyApp::M::SomeModel')>.
+
+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::M::Catalog;
+ use base qw/Catalyst::Base Some::Other::CDBI::Module::Catalog/;
+ 1;
+
+and that's it! Now C<Some::Other::CDBI::Module::Catalog> is part of your
+Cat app as C<MyApp::M::Catalog>.
+
=head4 Controllers
Multiple controllers are a good way to separate logical domains of your
package MyApp::C::Login;
- sign-in : Local { }
- new-password : Local { }
- sign-out : Local { }
+ sub sign-in : Local { }
+ sub new-password : Local { }
+ sub sign-out : Local { }
package MyApp::C::Catalog;
projects / catagits/Catalyst-Runtime.git / blobdiff