=head1 NAME

CatalystX::SimpleLogin::Manual - How to use and customise CatalystX::SimpleLogin.

=head2 Tutorial

We're using a sample application here, to make the instructions a little
easier. This assumes that you have Catalyst, Catalyst::Devel,
Template Toolkit, and the Catalyst authentication and session plugins
installed.

    catalyst.pl MyApp
    cd MyApp
    script/myapp_create.pl view HTML TT

Edit lib/MyApp.pm and add CatalystX::SimpleLogin,  Authenticate, and the
Session plugins to the use Catalyst plugin list:

    use Catalyst qw/-Debug
                    ConfigLoader
                    +CatalystX::SimpleLogin
                    Authentication
                    Session
                    Session::Store::File
                    Session::State::Cookie
                    Static::Simple/;

Add the following config for authentication, including two sample users:

    __PACKAGE__->config(
        'Plugin::Authentication' => {
            default => {
                credential => {
                    class => 'Password',
                    password_field => 'password',
                    password_type => 'clear'
                },
                store => {
                    class => 'Minimal',
                    users => {
                        bob => {
                            password => "bobpw",
                        },
                        william => {
                            password => "billpw",
                        },
                    },
                },
            },
        },
    );

Execute C< script/myapp_server.pl > and, as part of the debug output, you should see:

    [debug] Loaded Chained actions:
    .-------------------------------------+--------------------------------------.
    | Path Spec                           | Private                              |
    +-------------------------------------+--------------------------------------+
    | /login                              | /login/login                         |
    | /logout                             | /login/logout                        |
    '-------------------------------------+--------------------------------------'

Go to C< localhost:3000 > and you should see the Catalyst welcome screen. Go to
C< localhost:3000/login > and you should get a login screen containing username and
password text fields, a 'Remember' checkbox, and a 'Login' button. Enter 'bob' and
'bobpw'. You should be logged in and taken to the welcome screen. If you execute
C< localhost:3000/logout > you will be logged out, and should see this in the
debug output (the welcome screen will stay the same).

Now go to C< lib/MyApp/Controller/Root.pm > and remove the lines saying:

    use strict;
    use warnings;
    use parent 'Catalyst::Controller';

and add the following lines:

    use Moose;
    use namespace::autoclean;
    BEGIN { extends 'Catalyst::Controller' }

Now add a new action to C< lib/MyApp/Controller/Root.pm > and include
C< Does('NeedsLogin') > to use the Catalyst ActionRole that is part of SimpleLogin:

    sub hello_user : Local Does('NeedsLogin') {
        my ( $self, $c ) = @_;
        $c->res->body('<h2>Hello, user!</h2>');
    }

Restart the server and you can see the new action. Go to C<< htp://localhost:3000/hello_user >>
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' }

    sub do_something : Chained('/login/required')
                     : Does('ACL') RequiresRole('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:

  : LoginRedirectMessage('Please Login to view this Action')

Now we'll create a Template Toolkit template that can be customized. Create a
C< root/login/login.tt > file with the following lines.

  [% error_msg %]
  [% render_login_form %]

Now edit C< lib/MyApp.pm > and add the config shown below
to remove the 'RenderAsTTTemplate' trait, and add
'flash_to_stash' for L<Catalyst::Plugin::Session>
(to allow the error message to be passed to the next request):

    __PACKAGE__->config(
        'Plugin::Session' => {
            flash_to_stash => 1
        },
        'Controller::Login' => {
            traits => ['-RenderAsTTTemplate'],
        },
        # Other config..
    );

Restart the server and try to view the hello_user page without being logged in.
You should be redireced to the login page with the error message displayed at
the top.

You can replace C< [% render_login_form %] > with your own html, and customize
it as you please.

    <div class="error">[% error_msg %]</div>
    <form id="login_form" method="post" >
    <fieldset class="main_fieldset">
    <div><label class="label" for="username">Username:
    </label><input type="text" name="username" id="username" value="" />
    </div>

    <div><label class="label" for="password">Password: </label>
    <input type="password" name="password" id="password" value="" />
    </div>

    <div><label class="label" for="remember">Remember: </label>
    <input type="checkbox" name="remember" id="remember" value="1" />
    </div>

    <div><input type="submit" name="submit" id="submit" value="Login" />
    </div>
    </fieldset></form>

Or you can customize it using L<HTML::FormHandler> HTML rendering features, and
the 'login_form_args' config key.

To alter the amount the remember me extends the session by alter the C<remember_me_expiry>
configuration setting.

    __PACKAGE__->config(
        'Controller::Login' => {
            remember_me_expiry => 999999999, # the default is about 32 years.
        },
        # Other config..
    );


=cut