=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
=head1 Skipping your VCS's directories
-Catalyst uses Module::Pluggable to load Models, Views, and Controllers.
-Module::Pluggable will scan through all directories and load modules
+Catalyst uses L<Module::Pluggable> to load Models, Views, and Controllers.
+L<Module::Pluggable> will scan through all directories and load modules
it finds. Sometimes you might want to skip some of these directories,
for example when your version control system makes a subdirectory with
meta-information in every version-controlled directory. While
setup_components => { except => qr/SCCS/ },
);
-See the Module::Pluggable manual page for more information on B<except>
+See the L<Module::Pluggable> manual page for more information on B<except>
and other options.
=head1 Users and Access Control
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).
Now follow these few steps to implement the application:
-1. Install Catalyst (5.61 or later), Catalyst::Plugin::XMLRPC (0.06 or
-later) and SOAP::Lite (for XMLRPCsh.pl).
+=over 4
+
+=item 1.
-2. Create an application framework:
+Install L<Catalyst> (5.61 or later), L<Catalyst::Plugin::XMLRPC> (0.06 or
+later) and L<SOAP::Lite> (for F<XMLRPCsh.pl>).
+
+=item 2.
+
+Create an application framework:
% catalyst.pl MyApp
...
% cd MyApp
-3. Add the XMLRPC plugin to MyApp.pm
+=item 3.
+
+Add the XMLRPC plugin to MyApp.pm
use Catalyst qw/-Debug Static::Simple XMLRPC/;
-4. Add an API controller
+=item 4.
+
+Add an API controller
% ./script/myapp_create.pl controller API
-5. Add a XMLRPC redispatch method and an add method with Remote
-attribute to lib/MyApp/Controller/API.pm
+=item 5.
+
+Add a XMLRPC redispatch method and an add method with Remote
+attribute to F<lib/MyApp/Controller/API.pm>
sub default :Path {
my ( $self, $c ) = @_;
The C<add> method is not a traditional action; it has no private or
public path. Only the XMLRPC dispatcher knows it exists.
-6. That's it! You have built your first web service. Let's test it with
-XMLRPCsh.pl (part of SOAP::Lite):
+=item 6.
+
+That's it! You have built your first web service. Let's test it with
+F<XMLRPCsh.pl> (part of L<SOAP::Lite>):
% ./script/myapp_server.pl
...
Views pertain to the display of your application. As with models,
Catalyst is uncommonly flexible. The recipes below are just a start.
-=head2 Catalyst::View::TT
+=head2 L<Catalyst::View::TT>
One of the first things you probably want to do when starting a new
Catalyst application is set up your View. Catalyst doesn't care how you
L<Template Toolkit|Template> is probably the most popular.
Once again, the Catalyst developers have done all the hard work, and
-made things easy for the rest of us. Catalyst::View::TT provides the
+made things easy for the rest of us. L<Catalyst::View::TT> provides the
interface to Template Toolkit, and provides Helpers which let us set it
up that much more easily.
=head3 Creating your View
-Catalyst::View::TT provides two different helpers for us to use: TT and
+L<Catalyst::View::TT> provides two different helpers for us to use: TT and
TTSite.
=head4 TT
script/myapp_create.pl view TT TT
-This will create lib/MyApp/View/MyView.pm, which is going to be pretty
+This will create F<lib/MyApp/View/MyView.pm>, which is going to be pretty
empty to start. However, it sets everything up that you need to get
started. You can now define which template you want and forward to your
view. For instance:
=item *
-INCLUDE_PATH defines the directories that Template Toolkit should search
+C<INCLUDE_PATH> defines the directories that Template Toolkit should search
for the template files.
=item *
-PRE_PROCESS is used to process configuration options which are common to
+C<PRE_PROCESS> is used to process configuration options which are common to
every template file.
=item *
-WRAPPER is a file which is processed with each template, usually used to
+C<WRAPPER> is a file which is processed with each template, usually used to
easily provide a common header and footer for every page.
=back
template and config files for us! In the 'root' directory, you'll notice
two new directories: src and lib.
-Several configuration files in root/lib/config are called by PRE_PROCESS.
+Several configuration files in F<root/lib/config> are called by C<PRE_PROCESS>.
-The files in root/lib/site are the site-wide templates, called by
-WRAPPER, and display the html framework, control the layout, and provide
+The files in F<root/lib/site> are the site-wide templates, called by
+C<WRAPPER>, and display the html framework, control the layout, and provide
the templates for the header and footer of your page. Using the template
organization provided makes it much easier to standardize pages and make
changes when they are (inevitably) needed.
The template files that you will create for your application will go
-into root/src, and you don't need to worry about putting the <html>
-or <head> sections; just put in the content. The WRAPPER will the rest
+into root/src, and you don't need to worry about putting the C<< <html> >>
+or C<< <head> >> sections; just put in the content. The C<WRAPPER> will the rest
of the page around your template for you.
$c->forward( $c->view('TT') );
}
-Then, in hello.tt:
+Then, in F<hello.tt>:
<strong>Hello, [% name %]!</strong>
application around without having to worry that everything is going to
break. One of the areas that used to be a problem was with the http
links in your template files. For example, suppose you have an
-application installed at http://www.domain.com/Calendar. The links point
-to "/Calendar", "/Calendar/2005", "/Calendar/2005/10", etc. If you move
-the application to be at http://www.mydomain.com/Tools/Calendar, then
+application installed at C<http://www.domain.com/Calendar>. The links point
+to "C</Calendar>", "C</Calendar/2005>", "C</Calendar/2005/10>", etc. If you move
+the application to be at C<http://www.mydomain.com/Tools/Calendar>, then
all of those links will suddenly break.
That's where C<< $c->uri_for() >> comes in. This function will merge its
Although the parameter starts with a forward slash, this is relative
to the application root, not the webserver root. This is important to
remember. So, if your application is installed at
-http://www.domain.com/Calendar, then the link would be
-http://www.mydomain.com/Calendar/Login. If you move your application
+C<http://www.domain.com/Calendar>, then the link would be
+C<http://www.mydomain.com/Calendar/Login>. If you move your application
to a different domain or path, then that link will still be correct.
Likewise,
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
+C<http://www.domain.com/Calendar>. and if the template is called from
C<MyApp::Controller::Display>, then the link would become
-http://www.domain.com/Calendar/Display/2005/10/24.
+C<http://www.domain.com/Calendar/Display/2005/10/24>.
If you want to link to a parent uri of your current namespace you can
-prefix the arguments with multiple '../':
+prefix the arguments with multiple 'C<../>':
<a href="[% c.uri_for('../../view', stashed_object.id) %]">User view</a>
Once again, this allows you to move your application around without
having to worry about broken links. But there's something else, as
-well. Since the links are generated by uri_for, you can use the same
+well. Since the links are generated by C<uri_for>, you can use the same
template file by several different controllers, and each controller
will get the links that its supposed to. Since we believe in Don't
Repeat Yourself, this is particularly helpful if you have common
the normal view action first to get the objects, then handle the output
differently.
-=head3 Using XML::Feed
+=head3 Using L<XML::Feed>
Assuming we have a C<view> action that populates
-'entries' with some DBIx::Class iterator, the code would look something
+'entries' with some L<DBIx::Class> iterator, the code would look something
like this:
sub rss : Local {
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
=head3 A word of warning
-You can put root actions in your main MyApp.pm file, but this is deprecated,
+You can put root actions in your main F<MyApp.pm> file, but this is deprecated,
please put your actions into your Root controller.
=head3 Flowchart
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<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
}
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.
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
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
projects / catagits/Catalyst-Manual.git / blobdiff