view release on metacpan or  search on metacpan

lib/CatalystX/SimpleLogin/Manual.pod  view on Meta::CPAN

=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
    }