your C<use Catalyst> statement . However, you can also enable it using
environment variable, so you can (for example) get debug info without
modifying your application scripts. Just set C<CATALYST_DEBUG> or
-C<E<lt>MYAPPE<gt>_DEBUG> to a true value.
+C<< <MYAPP>_DEBUG >> to a true value.
=head2 Sessions
=head3 EXAMPLE
- package MyApp;
- use Moose;
- use namespace::autoclean;
-
- use Catalyst qw/
- Session
- Session::Store::FastMmap
- Session::State::Cookie
- /;
- extends 'Catalyst';
- __PACKAGE__->setup;
-
- package MyApp::Controller::Foo;
- use Moose;
- use namespace::autoclean;
- BEGIN { extends 'Catalyst::Controller' };
- ## Write data into the session
-
- sub add_item : Local {
- my ( $self, $c ) = @_;
-
- my $item_id = $c->req->params->{item};
-
- push @{ $c->session->{items} }, $item_id;
+ package MyApp;
+ use Moose;
+ use namespace::autoclean;
+
+ use Catalyst qw/
+ Session
+ Session::Store::FastMmap
+ Session::State::Cookie
+ /;
+ extends 'Catalyst';
+ __PACKAGE__->setup;
+
+ package MyApp::Controller::Foo;
+ use Moose;
+ use namespace::autoclean;
+ BEGIN { extends 'Catalyst::Controller' };
+ ## Write data into the session
+
+ sub add_item : Local {
+ my ( $self, $c ) = @_;
- }
+ my $item_id = $c->req->params->{item};
- ## A page later we retrieve the data from the session:
+ push @{ $c->session->{items} }, $item_id;
+ }
- sub get_items : Local {
- my ( $self, $c ) = @_;
+ ## A page later we retrieve the data from the session:
- $c->stash->{items_to_display} = $c->session->{items};
+ sub get_items : Local {
+ my ( $self, $c ) = @_;
- }
+ $c->stash->{items_to_display} = $c->session->{items};
+ }
=head3 More information
-L<http://search.cpan.org/dist/Catalyst-Plugin-Session>
+L<Catalyst::Plugin::Session>
-L<http://search.cpan.org/dist/Catalyst-Plugin-Session-State-Cookie>
+L<Catalyst::Plugin::Session::State::Cookie>
-L<http://search.cpan.org/dist/Catalyst-Plugin-Session-State-URI>
+L<Catalyst::Plugin::Session::State::URI>
-L<http://search.cpan.org/dist/Catalyst-Plugin-Session-Store-FastMmap>
+L<Catalyst::Plugin::Session::Store::FastMmap>
-L<http://search.cpan.org/dist/Catalyst-Plugin-Session-Store-File>
+L<Catalyst::Plugin::Session::Store::File>
-L<http://search.cpan.org/dist/Catalyst-Plugin-Session-Store-DBI>
+L<Catalyst::Plugin::Session::Store::DBI>
=head2 Configure your application
=head3 Using Config::General
-L<Config::General|Config::General> is a method for creating flexible
+L<Config::General> is a method for creating flexible
and readable configuration files. It's a great way to keep your
Catalyst application configuration in one easy-to-understand location.
-Now create C<myapp.conf> in your application home:
+Now create F<myapp.conf> in your application home:
name MyApp
values, how to access the values in your components, and many 'base'
config variables used internally.
-See also L<Config::General|Config::General>.
+See also L<Config::General>.
=head1 Skipping your VCS's directories
Examples:
- Password - Simple username/password checking.
- HTTPD - Checks using basic HTTP auth.
- TypeKey - Check using the typekey system.
+ Password - Simple username/password checking.
+ HTTPD - Checks using basic HTTP auth.
+ TypeKey - Check using the typekey system.
=head3 Storage backends
Examples:
- DBIC - Storage using a database via DBIx::Class.
- Minimal - Storage using a simple hash (for testing).
+ DBIC - Storage using a database via DBIx::Class.
+ Minimal - Storage using a simple hash (for testing).
=head3 User objects
Examples:
- Hash - A simple hash of keys and values.
+ Hash - A simple hash of keys and values.
=head3 ACL authorization
=head3 EXAMPLE
- package MyApp;
- use Moose;
- use namespace::autoclean;
- extends qw/Catalyst/;
- use Catalyst qw/
- Authentication
- Authorization::Roles
- /;
+ package MyApp;
+ use Moose;
+ use namespace::autoclean;
+ extends qw/Catalyst/;
+ use Catalyst qw/
+ Authentication
+ Authorization::Roles
+ /;
- __PACKAGE__->config(
- authentication => {
- default_realm => 'test',
- realms => {
- test => {
- credential => {
- class => 'Password',
- password_field => 'password',
- password_type => 'self_check',
- },
- store => {
- class => 'Htpasswd',
- file => 'htpasswd',
- },
- },
- },
- },
- );
+ __PACKAGE__->config(
+ authentication => {
+ default_realm => 'test',
+ realms => {
+ test => {
+ credential => {
+ class => 'Password',
+ password_field => 'password',
+ password_type => 'self_check',
+ },
+ store => {
+ class => 'Htpasswd',
+ file => 'htpasswd',
+ },
+ },
+ },
+ },
+ );
- package MyApp::Controller::Root;
- use Moose;
- use namespace::autoclean;
+ package MyApp::Controller::Root;
+ use Moose;
+ use namespace::autoclean;
- BEGIN { extends 'Catalyst::Controller' }
+ BEGIN { extends 'Catalyst::Controller' }
- __PACKAGE__->config(namespace => '');
+ __PACKAGE__->config(namespace => '');
- sub login : Local {
- my ($self, $c) = @_;
+ sub login : Local {
+ my ($self, $c) = @_;
- if ( my $user = $c->req->params->{user}
- and my $password = $c->req->param->{password} )
- {
- if ( $c->authenticate( username => $user, password => $password ) ) {
- $c->res->body( "hello " . $c->user->name );
- } else {
- # login incorrect
- }
- }
- else {
- # invalid form input
- }
- }
+ if ( my $user = $c->req->params->{user}
+ and my $password = $c->req->param->{password} )
+ {
+ if ( $c->authenticate( username => $user, password => $password ) ) {
+ $c->res->body( "hello " . $c->user->name );
+ } else {
+ # login incorrect
+ }
+ }
+ else {
+ # invalid form input
+ }
+ }
- sub restricted : Local {
- my ( $self, $c ) = @_;
+ sub restricted : Local {
+ my ( $self, $c ) = @_;
- $c->detach("unauthorized")
- unless $c->check_user_roles( "admin" );
+ $c->detach("unauthorized")
+ unless $c->check_user_roles( "admin" );
- # do something restricted here
- }
+ # do something restricted here
+ }
=head3 Using authentication in a testing environment
Also, it's important to note that if you restrict access to "/" then
C<end>, C<default>, etc. will also be restricted.
- MyApp->acl_allow_root_internals;
+ MyApp->acl_allow_root_internals;
will create rules that permit access to C<end>, C<begin>, and C<auto> in the
root of your app (but not in any other controller).
=over
-=item
+=item *
INCLUDE_PATH defines the directories that Template Toolkit should search
for the template files.
-=item
+=item *
PRE_PROCESS is used to process configuration options which are common to
every template file.
-=item
+=item *
WRAPPER is a file which is processed with each template, usually used to
easily provide a common header and footer for every page.
of the page around your template for you.
-=head3 $c->stash
+=head3 C<< $c->stash >>
Of course, having the template system include the header and footer for
you isn't all that we want our templates to do. We need to be able to
and allows you to truly keep your presentation logic separate from the
rest of your application.
-=head3 $c->uri_for()
+=head3 C<< $c->uri_for() >>
One of my favorite things about Catalyst is the ability to move an
application around without having to worry that everything is going to
the application to be at http://www.mydomain.com/Tools/Calendar, then
all of those links will suddenly break.
-That's where $c->uri_for() comes in. This function will merge its
+That's where C<< $c->uri_for() >> comes in. This function will merge its
parameters with either the base location for the app, or its current
namespace. Let's take a look at a couple of examples.
The first parameter does NOT have a forward slash, and so it will be
relative to the current namespace. If the application is installed at
http://www.domain.com/Calendar. and if the template is called from
-MyApp::Controller::Display, then the link would become
+C<MyApp::Controller::Display>, then the link would become
http://www.domain.com/Calendar/Display/2005/10/24.
If you want to link to a parent uri of your current namespace you can
Further Reading:
-L<http://search.cpan.org/perldoc?Catalyst>
+L<Catalyst>
-L<http://search.cpan.org/perldoc?Catalyst%3A%3AView%3A%3ATT>
+L<Catalyst::View::TT>
-L<http://search.cpan.org/perldoc?Template>
+L<Template>
=head2 Adding RSS feeds
spaces in the filename are handled by the browser.
Put this right before calling C<< $c->res->body >> and your browser
-will download a file named C<Important Orders.csv> instead of
+will download a file named F<Important Orders.csv> instead of
C<export>.
You can also use this to have the browser download content which it
Assume our Controller module starts with the following package declaration:
- package MyApp::Controller::Buckets;
+ package MyApp::Controller::Buckets;
and we are running our application on localhost, port 3000 (the test
server default).
controller namespace, an absolute path will represent an exact
matching URL.
- sub my_handles : Path('handles') { .. }
+ sub my_handles : Path('handles') { .. }
becomes
- http://localhost:3000/buckets/handles
+ http://localhost:3000/buckets/handles
and
- sub my_handles : Path('/handles') { .. }
+ sub my_handles : Path('/handles') { .. }
becomes
- http://localhost:3000/handles
+ http://localhost:3000/handles
See also: L<Catalyst::DispatchType::Path>
name of the action is matched in the URL. The namespaces created by
the name of the controller package is always part of the URL.
- sub my_handles : Local { .. }
+ sub my_handles : Local { .. }
becomes
- http://localhost:3000/buckets/my_handles
+ http://localhost:3000/buckets/my_handles
=item Global
A Global attribute is similar to a Local attribute, except that the
namespace of the controller is ignored, and matching starts at root.
- sub my_handles : Global { .. }
+ sub my_handles : Global { .. }
becomes
- http://localhost:3000/my_handles
+ http://localhost:3000/my_handles
=item Regex
sounds like. This one takes a regular expression, and matches starting
from root. These differ from the rest as they can match multiple URLs.
- sub my_handles : Regex('^handles') { .. }
+ sub my_handles : Regex('^handles') { .. }
matches
- http://localhost:3000/handles
+ http://localhost:3000/handles
and
- http://localhost:3000/handles_and_other_parts
+ http://localhost:3000/handles_and_other_parts
etc.
A LocalRegex is similar to a Regex, except it only matches below the current
controller namespace.
- sub my_handles : LocalRegex(^handles') { .. }
+ sub my_handles : LocalRegex(^handles') { .. }
matches
- http://localhost:3000/buckets/handles
+ http://localhost:3000/buckets/handles
and
- http://localhost:3000/buckets/handles_and_other_parts
+ http://localhost:3000/buckets/handles_and_other_parts
etc.
to create your own internal actions, which can be forwarded to, but
won't be matched as URLs.
- sub my_handles : Private { .. }
+ sub my_handles : Private { .. }
becomes nothing at all..
to find out where it was the user was trying to go, you can look in
the request object using C<< $c->req->path >>.
- sub default :Path { .. }
+ sub default :Path { .. }
works for all unknown URLs, in this controller namespace, or every one
if put directly into MyApp.pm.
actions are defined, then index will be used instead of default and
Path.
- sub index :Path :Args(0) { .. }
+ sub index :Path :Args(0) { .. }
becomes
- http://localhost:3000/buckets
+ http://localhost:3000/buckets
=item begin
app. A single begin action is called, its always the one most relevant
to the current namespace.
- sub begin : Private { .. }
+ sub begin : Private { .. }
is called once when
- http://localhost:3000/bucket/(anything)?
+ http://localhost:3000/bucket/(anything)?
is visited.
always the one most relevant to the current namespace.
- sub end : Private { .. }
+ sub end : Private { .. }
is called once after any actions when
- http://localhost:3000/bucket/(anything)?
+ http://localhost:3000/bucket/(anything)?
is visited.
called. (In contrast, only one of the begin/end/default actions will
be called, the relevant one).
- package MyApp::Controller::Root;
- sub auto : Private { .. }
+ package MyApp::Controller::Root;
+ sub auto : Private { .. }
and
will both be called when visiting
- http://localhost:3000/bucket/(anything)?
+ http://localhost:3000/bucket/(anything)?
=back
this:
<form action="/upload" method="post" enctype="multipart/form-data">
- <input type="hidden" name="form_submit" value="yes">
- <input type="file" name="my_file">
- <input type="submit" value="Send">
+ <input type="hidden" name="form_submit" value="yes">
+ <input type="file" name="my_file">
+ <input type="submit" value="Send">
</form>
It's very important not to forget C<enctype="multipart/form-data"> in
The form should have this basic structure:
<form action="/upload" method="post" enctype="multipart/form-data">
- <input type="hidden" name="form_submit" value="yes">
- <input type="file" name="file1" size="50"><br>
- <input type="file" name="file2" size="50"><br>
- <input type="file" name="file3" size="50"><br>
- <input type="submit" value="Send">
+ <input type="hidden" name="form_submit" value="yes">
+ <input type="file" name="file1" size="50"><br>
+ <input type="file" name="file2" size="50"><br>
+ <input type="file" name="file3" size="50"><br>
+ <input type="submit" value="Send">
</form>
And in the controller:
$c->stash->{template} = 'file_upload.html';
}
-C<for my $field ($c-E<gt>req->upload)> loops automatically over all file
+C<< for my $field ($c->req->upload) >> loops automatically over all file
input fields and gets input names. After that is basic file saving code,
just like in single file upload.
Notice: C<die>ing might not be what you want to do, when an error
occurs, but it works as an example. A better idea would be to store
-error C<$!> in $c->stash->{error} and show a custom error template
+error C<$!> in C<< $c->stash->{error} >> and show a custom error template
displaying this message.
For more information about uploads and usable methods look at
C<forward>; in earlier versions, you can manually set the arguments in
the Catalyst Request object:
- # version 5.30 and later:
- $c->forward('/wherever', [qw/arg1 arg2 arg3/]);
+ # version 5.30 and later:
+ $c->forward('/wherever', [qw/arg1 arg2 arg3/]);
- # pre-5.30
- $c->req->args([qw/arg1 arg2 arg3/]);
- $c->forward('/wherever');
+ # pre-5.30
+ $c->req->args([qw/arg1 arg2 arg3/]);
+ $c->forward('/wherever');
(See the L<Catalyst::Manual::Intro> Flow_Control section for more
information on passing arguments via C<forward>.)
=head2 Chained dispatch using base classes, and inner packages.
- package MyApp::Controller::Base;
- use base qw/Catalyst::Controller/;
+ package MyApp::Controller::Base;
+ use base qw/Catalyst::Controller/;
- sub key1 : Chained('/')
+ sub key1 : Chained('/')
=head2 Extending RenderView (formerly DefaultEnd)
method:
sub end : ActionClass('RenderView') {
- my ( $self, $c ) = @_;
- # do stuff here; the RenderView action is called afterwards
+ my ( $self, $c ) = @_;
+ # do stuff here; the RenderView action is called afterwards
}
To add things to an C<end> action that are called I<after> rendering,
sub render : ActionClass('RenderView') { }
sub end : Private {
- my ( $self, $c ) = @_;
- $c->forward('render');
- # do stuff here
+ my ( $self, $c ) = @_;
+ $c->forward('render');
+ # do stuff here
}
Static::Simple is a plugin that will help to serve static content for your
application. By default, it will serve most types of files, excluding some
standard Template Toolkit extensions, out of your B<root> file directory. All
-files are served by path, so if B<images/me.jpg> is requested, then
-B<root/images/me.jpg> is found and served.
+files are served by path, so if F<images/me.jpg> is requested, then
+F<root/images/me.jpg> is found and served.
=head3 Usage
Using the plugin is as simple as setting your use line in MyApp.pm to include:
- use Catalyst qw/Static::Simple/;
+ use Catalyst qw/Static::Simple/;
and already files will be served.
=head3 Configuring
Static content is best served from a single directory within your root
-directory. Having many different directories such as C<root/css> and
-C<root/images> requires more code to manage, because you must separately
-identify each static directory--if you decide to add a C<root/js>
+directory. Having many different directories such as F<root/css> and
+F<root/images> requires more code to manage, because you must separately
+identify each static directory--if you decide to add a F<root/js>
directory, you'll need to change your code to account for it. In
contrast, keeping all static directories as subdirectories of a main
-C<root/static> directory makes things much easier to manage. Here's an
+F<root/static> directory makes things much easier to manage. Here's an
example of a typical root directory structure:
root/
root/static/js/code.js
-All static content lives under C<root/static>, with everything else being
+All static content lives under F<root/static>, with everything else being
Template Toolkit files.
=over 4
You may of course want to change the default locations, and make
Static::Simple look somewhere else, this is as easy as:
- MyApp->config(
- static => {
- include_path => [
- MyApp->path_to('/'),
- '/path/to/my/files',
- ],
- },
- );
+ MyApp->config(
+ static => {
+ include_path => [
+ MyApp->path_to('/'),
+ '/path/to/my/files',
+ ],
+ },
+ );
When you override include_path, it will not automatically append the
normal root path, so you need to add it yourself if you still want
If you want to force some directories to be only static, you can set
them using paths relative to the root dir, or regular expressions:
- MyApp->config(
- static => {
- dirs => [
- 'static',
- qr/^(images|css)/,
- ],
- },
- );
+ MyApp->config(
+ static => {
+ dirs => [
+ 'static',
+ qr/^(images|css)/,
+ ],
+ },
+ );
=item File extensions
be processed by Catalyst): B<tmpl, tt, tt2, html, xhtml>. This list can
be replaced easily:
- MyApp->config(
+ MyApp->config(
static => {
ignore_extensions => [
qw/tmpl tt tt2 html xhtml/
],
},
- );
+ );
=item Ignoring directories
Entire directories can be ignored. If used with include_path,
directories relative to the include_path dirs will also be ignored:
- MyApp->config( static => {
+ MyApp->config( static => {
ignore_dirs => [ qw/tmpl css/ ],
- });
+ });
=back
=head3 More information
-L<http://search.cpan.org/dist/Catalyst-Plugin-Static-Simple/>
+L<Catalyst::Plugin::Static::Simple>
=head3 Serving manually with the Static plugin with HTTP::Daemon (myapp_server.pl)
my ( $self, $c ) = @_;
$c->forward( 'MyApp::View::TT' )
- unless ( $c->res->body || !$c->stash->{template} );
+ unless ( $c->res->body || !$c->stash->{template} );
}
This code will only forward to the view if a template has been
previously defined by a controller and if there is not already data in
-C<$c-E<gt>res-E<gt>body>.
+C<< $c->res->body >>.
Next, create a controller to handle requests for the /static path. Use
the Helper to save time. This command will create a stub controller as
-C<lib/MyApp/Controller/Static.pm>.
+F<lib/MyApp/Controller/Static.pm>.
$ script/myapp_create.pl controller Static
When using Apache, you can bypass Catalyst and any Static
plugins/controllers controller by intercepting requests for the
-C<root/static> path at the server level. All that is required is to
+F<root/static> path at the server level. All that is required is to
define a DocumentRoot and add a separate Location block for your static
content. Here is a complete config for this application under mod_perl
1.x:
Catalyst provides a convenient way of testing your application during
development and before deployment in a real environment.
-C<Catalyst::Test> makes it possible to run the same tests both locally
+L<Catalyst::Test> makes it possible to run the same tests both locally
(without an external daemon) and against a remote server via HTTP.
=head3 Tests
-Let's examine a skeleton application's C<t/> directory:
+Let's examine a skeleton application's F<t/> directory:
mundus:~/MyApp chansen$ ls -l t/
total 24
=over 4
-=item C<01app.t>
+=item F<01app.t>
Verifies that the application loads, compiles, and returns a successful
response.
-=item C<02pod.t>
+=item F<02pod.t>
Verifies that all POD is free from errors. Only executed if the C<TEST_POD>
environment variable is true.
-=item C<03podcoverage.t>
+=item F<03podcoverage.t>
Verifies that all methods/functions have POD coverage. Only executed if the
C<TEST_POD> environment variable is true.
two. The second line tests and loads our application in test mode. The
fourth line verifies that our application returns a successful response.
-C<Catalyst::Test> exports two functions, C<request> and C<get>. Each can
+L<Catalyst::Test> exports two functions, C<request> and C<get>. Each can
take three different arguments:
=over 4
request('/my/path');
request('http://www.host.com/my/path');
-=item An instance of C<URI>.
+=item An instance of L<URI>.
request( URI->new('http://www.host.com/my/path') );
-=item An instance of C<HTTP::Request>.
+=item An instance of L<HTTP::Request>.
request( HTTP::Request->new( GET => 'http://www.host.com/my/path') );
=back
-C<request> returns an instance of C<HTTP::Response> and C<get> returns the
+C<request> returns an instance of L<HTTP::Response> and C<get> returns the
content (body) of the response.
=head3 Running tests locally
your application. In C<CGI> or C<FastCGI> it should be the host and path
to the script.
-=head3 C<Test::WWW::Mechanize> and Catalyst
+=head3 L<Test::WWW::Mechanize> and Catalyst
-Be sure to check out C<Test::WWW::Mechanize::Catalyst>. It makes it easy to
+Be sure to check out L<Test::WWW::Mechanize::Catalyst>. It makes it easy to
test HTML, forms and links. A short example of usage:
use Test::More tests => 6;
=over 4
-=item Catalyst::Test
-
-L<Catalyst::Test>
+=item * L<Catalyst::Test>
-=item Test::WWW::Mechanize::Catalyst
+=item * L<Test::WWW::Mechanize::Catalyst>
-L<http://search.cpan.org/dist/Test-WWW-Mechanize-Catalyst/lib/Test/WWW/Mechanize/Catalyst.pm>
+=item * L<Test::WWW::Mechanize>
-=item Test::WWW::Mechanize
+=item * L<WWW::Mechanize>
-L<http://search.cpan.org/dist/Test-WWW-Mechanize/Mechanize.pm>
+=item * L<LWP::UserAgent>
-=item WWW::Mechanize
+=item * L<HTML::Form>
-L<http://search.cpan.org/dist/WWW-Mechanize/lib/WWW/Mechanize.pm>
+=item * L<HTTP::Message>
-=item LWP::UserAgent
+=item * L<HTTP::Request>
-L<http://search.cpan.org/dist/libwww-perl/lib/LWP/UserAgent.pm>
+=item * L<HTTP::Request::Common>
-=item HTML::Form
+=item * L<HTTP::Response>
-L<http://search.cpan.org/dist/libwww-perl/lib/HTML/Form.pm>
+=item * L<HTTP::Status>
-=item HTTP::Message
+=item * L<URI>
-L<http://search.cpan.org/dist/libwww-perl/lib/HTTP/Message.pm>
+=item * L<Test::More>
-=item HTTP::Request
+=item * L<Test::Pod>
-L<http://search.cpan.org/dist/libwww-perl/lib/HTTP/Request.pm>
+=item * L<Test::Pod::Coverage>
-=item HTTP::Request::Common
+=item * L<prove> (L<Test::Harness>)
-L<http://search.cpan.org/dist/libwww-perl/lib/HTTP/Request/Common.pm>
-
-=item HTTP::Response
-
-L<http://search.cpan.org/dist/libwww-perl/lib/HTTP/Response.pm>
-
-=item HTTP::Status
-
-L<http://search.cpan.org/dist/libwww-perl/lib/HTTP/Status.pm>
-
-=item URI
-
-L<http://search.cpan.org/dist/URI/URI.pm>
-
-=item Test::More
-
-L<http://search.cpan.org/dist/Test-Simple/lib/Test/More.pm>
-
-=item Test::Pod
-
-L<http://search.cpan.org/dist/Test-Pod/Pod.pm>
+=back
-=item Test::Pod::Coverage
+=head3 More Information
-L<http://search.cpan.org/dist/Test-Pod-Coverage/Coverage.pm>
+=over 4
-=item prove (Test::Harness)
+=item * L<Catalyst::Plugin::Authorization::Roles>
-L<http://search.cpan.org/dist/Test-Harness/bin/prove>
+=item * L<Catalyst::Plugin::Authorization::ACL>
=back
-=head3 More Information
-
-L<http://search.cpan.org/perldoc?Catalyst::Plugin::Authorization::Roles>
-L<http://search.cpan.org/perldoc?Catalyst::Plugin::Authorization::ACL>
-
=head1 AUTHORS
Catalyst Contributors, see Catalyst.pm