Merge remote branch 'dtaylor/master'

* dtaylor/master:
  Tweaks to Authorization docs
  Add docs for built-in chains and for ACL functionality.
  Improve Login form documentation.

lib/CatalystX/SimpleLogin/Form/Login.pm

@@ -117,8 +117,21 @@ A L<HTML::FormHandler> form for the login form.
 
 =head1 CUSTOMIZATION
 
-If the password and username fields have different names in your
-authentication, set them using the field's 'accessor' attribute.
+By default, the params passed to authenticate() are 'username' and
+'password'. If you need to use different names, then you'll need to
+set the correct value(s) via login_form_args in the configuration.
+The keys are 'authenticate_username_field_name' and/or
+'authenticate_password_field_name'.
+
+    __PACKAGE__->config(
+        'Controller::Login' => {
+            login_form_args => {
+               authenticate_username_field_name => 'name',
+               authenticate_password_field_name => 'password2',
+            }
+        },
+    );
+
 You can also change the way that the form is displayed by setting
 attributes.  In MyApp.pm:
 
@@ -127,7 +140,6 @@ attributes.  In MyApp.pm:
             login_form_args => {
                login_error_message => 'Login failed',
                field_list => {
-                   '+username' => { accessor => 'user_name' },
                    '+submit' => { value => 'Login' },
                }
             }

lib/CatalystX/SimpleLogin/Manual.pod

@@ -91,6 +91,57 @@ Restart the server and you can see the new action. Go to C<< htp://localhost:300
 and you'll get the 'Hello, user!' page. Now execute C<< http://localhost:3000/logout >> and try
 C<< http://localhost:3000/hello_user >> again. You will be presented with a login screen.
 
+=head3 Authorization
+
+CatalystX::SimpleLogin also provides /login/required and /login/not_required for easy
+chaining off of for actions which should only be available to authenticated users.
+
+    package MyApp::Controller::Secure;
+
+    sub setup : Chained('/login/required') PathPart('') CaptureArgs(1) {
+        my ( $self, $c, $id ) = @_;
+        # setup actions for authenticated-user-only access
+        $c->stash->{id} = $id;
+    }
+
+    sub something_secure : Chained('setup') PathPart Args(0) {
+        my ( $self, $c ) = @_;
+        # only authenticated users will have access to this action
+    }
+
+    sub open_to_all : Chained('/login/not_required') PathPart Args(0) {
+        my ( $self, $c ) = @_;
+        # this is available to everyone
+    }
+
+
+For more fine-grained control, you can use ACL checks to refine access 
+control policies. This functionality is provided via L<<Catalyst::ActionRole::ACL>>. 
+Please consult the ACL documentation for steps to setup your application.
+The ACL checks work by allowing you to add additional attributes on your
+actions which control the particular role(s) required or allowed.
+
+    package MyApp;
+    __PACKAGE__->config(
+        'Controller::Login' => {
+            actions => {
+                required => {
+                    Does => ['ACL'],
+                    AllowedRole => ['admin', 'poweruser'], # ANY of these
+                    # RequiresRole => ['extranet'], # ALL of these
+                    ACLDetachTo => 'login',
+                },
+            },
+        },
+    );
+
+    package MyApp::Controller::Foo;
+    BEGIN { extends 'Catalyst::Controller::ActionRole' }
+
+    sub do_something : Chained('/login/required')
+                     : Does('ACL') RequiredRole('createinvoice') ACLDetachTo('/login') {}
+
+
 You can also add a message, which will be put into the flash key 'error_msg'. Add
 the following to the hello_user action: