X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FCookbook.pod;h=1800657599c22cfa384df09b0a38e3e7dd7b5849;hp=8c4b7d43d334697ece9d5cbe29bee368d989a752;hb=e8200f38d465b85ad84eb11718db1e61230ce73b;hpb=6f660c96dfb8eea0b0790d635d8e2afa7fa42947 diff --git a/lib/Catalyst/Manual/Cookbook.pod b/lib/Catalyst/Manual/Cookbook.pod index 8c4b7d4..1800657 100644 --- a/lib/Catalyst/Manual/Cookbook.pod +++ b/lib/Catalyst/Manual/Cookbook.pod @@ -117,41 +117,39 @@ reference. =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 @@ -176,7 +174,7 @@ separate configuration file. =head3 Using Config::General -L is a method for creating flexible +L 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. @@ -221,12 +219,12 @@ L explains precedence of multiple sources for configuration values, how to access the values in your components, and many 'base' config variables used internally. -See also L. +See also L. =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 to load Models, Views, and Controllers. +L 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 @@ -242,7 +240,7 @@ You can make Catalyst skip these directories using the Catalyst config: setup_components => { except => qr/SCCS/ }, ); -See the Module::Pluggable manual page for more information on B +See the L manual page for more information on B and other options. =head1 Users and Access Control @@ -310,9 +308,9 @@ C<< $c->user >> call. 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 @@ -322,8 +320,8 @@ within this system; you will need to do it yourself. 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 @@ -332,7 +330,7 @@ credential verifier, and is filled with the retrieved user information. Examples: - Hash - A simple hash of keys and values. + Hash - A simple hash of keys and values. =head3 ACL authorization @@ -361,67 +359,67 @@ the user is a member. =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 @@ -575,7 +573,7 @@ clean up in your C private action instead. Also, it's important to note that if you restrict access to "/" then C, C, etc. will also be restricted. - MyApp->acl_allow_root_internals; + MyApp->acl_allow_root_internals; will create rules that permit access to C, C, and C in the root of your app (but not in any other controller). @@ -687,25 +685,37 @@ Response: 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. + +Install L (5.61 or later), L (0.06 or +later) and L (for F). + +=item 2. -2. Create an application framework: +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 sub default :Path { my ( $self, $c ) = @_; @@ -724,8 +734,10 @@ class. The C 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 (part of L): % ./script/myapp_server.pl ... @@ -750,7 +762,7 @@ enforce a specific one. 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 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 @@ -762,13 +774,13 @@ and though there are several template systems available, L