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=bf6372bc664a3dab5dc107268f4ddc68d6553699;hp=8c4b7d43d334697ece9d5cbe29bee368d989a752;hb=02bb2b5a140dc22d7d002fcdce868656d704676a;hpb=6f660c96dfb8eea0b0790d635d8e2afa7fa42947

diff --git a/lib/Catalyst/Manual/Cookbook.pod b/lib/Catalyst/Manual/Cookbook.pod
index 8c4b7d4..bf6372b 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<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.
 
@@ -221,7 +219,7 @@ L<Catalyst> 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<Config::General|Config::General>.
+See also L<Config::General>.
 
 =head1 Skipping your VCS's directories
 
@@ -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<end> private action instead.
 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).
@@ -821,17 +819,17 @@ This time, the helper sets several options for us in the generated View.
 
 =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.
@@ -856,7 +854,7 @@ or <head> sections; just put in the content. The WRAPPER will the rest
 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
@@ -911,7 +909,7 @@ This is the most basic usage, but Template Toolkit is quite powerful,
 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
@@ -922,7 +920,7 @@ to "/Calendar", "/Calendar/2005", "/Calendar/2005/10", etc.  If you move
 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.
 
@@ -944,7 +942,7 @@ 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
-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
@@ -1083,7 +1081,7 @@ attached. These can be one of several types.
 
 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).
@@ -1097,19 +1095,19 @@ or an absolute path. A relative path will be relative to the
 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>
 
@@ -1119,22 +1117,22 @@ When using a Local attribute, no parameters are needed, instead, the
 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
 
@@ -1142,15 +1140,15 @@ By now you should have figured that a Regex attribute is just what it
 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.
 
@@ -1161,15 +1159,15 @@ See also: L<Catalyst::DispatchType::Regex>
 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.
 
@@ -1184,7 +1182,7 @@ Last but not least, there is the Private attribute, which allows you
 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..
 
@@ -1201,7 +1199,7 @@ part of your namespace, you'll get an error page instead. If you want
 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.
@@ -1213,11 +1211,11 @@ namespace of your controller. If index, default and matching Path
 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
 
@@ -1227,11 +1225,11 @@ can be used to set up variables/data for this particular part of your
 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.
 
@@ -1243,11 +1241,11 @@ processing to the View component. A single end action is called, its
 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.
 
@@ -1258,8 +1256,8 @@ chain of paths up to and including the ending namespace, will be
 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
 
@@ -1267,7 +1265,7 @@ and
 
 will both be called when visiting
 
- http://localhost:3000/bucket/(anything)?
+    http://localhost:3000/bucket/(anything)?
 
 =back
 
@@ -1360,9 +1358,9 @@ To implement uploads in Catalyst, you need to have a HTML form similar to
 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
@@ -1396,11 +1394,11 @@ Code for uploading multiple files from one form needs a few changes:
 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:
@@ -1444,22 +1442,22 @@ action. As of version 5.30, arguments can be passed in the call to
 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)
 
@@ -1476,8 +1474,8 @@ To add something to an C<end> action that is called before rendering
 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,
@@ -1486,9 +1484,9 @@ you can set it up like this:
     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
     }
 
 
@@ -1512,7 +1510,7 @@ F<root/images/me.jpg> is found and served.
 
 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.
 
@@ -1547,14 +1545,14 @@ Template Toolkit files.
 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
@@ -1566,14 +1564,14 @@ served.
 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
 
@@ -1581,22 +1579,22 @@ By default, the following extensions are not served (that is, they will
 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
 
@@ -1620,7 +1618,7 @@ static content to the view, perhaps like this:
         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