File Coverage

blib/lib/CatalystX/SimpleLogin.pm

Criterion	Covered	Total	%
statement	9	9	100.0
branch			n/a
condition			n/a
subroutine	3	3	100.0
pod			n/a
total	12	12	100.0

package CatalystX::SimpleLogin;
use Moose::Role;
use CatalystX::InjectComponent;
use namespace::autoclean;

our $VERSION = '0.21';

after 'setup_components' => sub {
    my $class = shift;
    CatalystX::InjectComponent->inject(
        into => $class,
        component => 'CatalystX::SimpleLogin::Controller::Login',
        as => 'Controller::Login'
    );
};

=head1 NAME

CatalystX::SimpleLogin - Provide a simple Login controller which can be reused

=head1 SYNOPSIS

    package MyApp;
    use Moose;
    use namespace::autoclean;

    use Catalyst qw/
        +CatalystX::SimpleLogin
        Authentication
        Session
        Session::State::Cookie
        Session::Store::File
    /;
    extends 'Catalyst';

    __PACKAGE__->config(
        'Plugin::Authentication' => { # Auth config here }
    );

   __PACKAGE__->config(
        'Controller::Login' => { # SimpleLogin config here }
   );

   __PACKAGE__->setup;

=head1 ATTENTION!

If you're new here, you should start by reading
L<CatalystX::SimpleLogin::Manual>, which provides a gentler introduction to
using this code. Come back here when you're done there.

=head1 DESCRIPTION

CatalystX::SimpleLogin is an application class L<Moose::Role> which will
inject a L<Catalyst::Controller>
which is an instance of L<CatalystX::SimpleLogin::Controller::Login> into your
application. This provides a simple login and logout page with the addition
of only one line of code and one template to your application.

=head1 REQUIREMENTS

=over

=item A Catalyst application

=item Working authentication configuration

=item Working session configuration

=item A view

=back

=head1 CUSTOMISATION

CatalystX::SimpleLogin is a prototype for CatalystX::Elements. As such, one of the goals
is to make it easy for users to customise the provided component to the maximum degree
possible, and also, to have a linear relationship between effort invested and level of
customisation achieved.

Three traits are shipped with SimpleLogin: WithRedirect, Logout, and RenderAsTTTemplate.
These traits are set in the config:

   __PACKAGE__->config(
        'Controller::Login' => {
            traits => [qw/ Logout WithRedirect RenderAsTTTemplate /],
            login_form_args => { # see the login form },
   );

=head1 COMPONENTS

=over

=item *

L<CatalystX::SimpleLogin::Controller::Login> - first point of call for customisation.
Override the action configs to reconfigure the paths of the login or logout actions.
Subclass to be able to apply method modifiers to run before / after the login or
logout actions or override methods.

=item *

L<CatalystX::SimpleLogin::TraitFor::Controller::Login::Logout> - provides the C<logout> action
and associated methods. You can compose this manually yourself if you want just that
action.

This trait is set by default, but if you set another trait in your config, you
will have to include it.

=item *

L<CatalystX::SimpleLogin::TraitFor::Controller::Login::WithRedirect> - provides the C<login>
action with a wrapper to redirect to a page which needs authentication, from which the
user was previously redirected. Goes hand in hand with L<Catalyst::ActionRole::NeedsLogin>

=item *

L<CatalystX::SimpleLogin::TraitFor::Controller::Login::RenderAsTTTemplate> - sets
the stash variable 'template' to point to a string reference containing the
rendered template so that it's not necessary to have a login.tt template file.

=item *

L<CatalystX::SimpleLogin::Form::Login> - the L<HTML::FormHandler> form for the login form.

=item *

L<Catalyst::ActionRole::NeedsLogin> - Used to cause a specific path to redirect to the login
page if a user is not authenticated.

=back

=head1 TODO

Here's a list of what I think needs working on, in no particular order.

Please feel free to add to or re-arrange this list :)

=over

=item Fix extension documentation

=item Document all this stuff.

=item Examples of use / customisation in documentation

=item Fixing one uninitialized value warning in LoginRedirect

=item Disable the use of NeedsLogin ActionRole when WithRedirect is not loaded

=back

=head1 SOURCE CODE

    http://github.com/bobtfish/catalystx-simplelogin/tree/master

    git://github.com/bobtfish/catalystx-simplelogin.git

Forks and patches are welcome. #formhandler or #catalyst (irc.perl.org)
are both good places to ask about using or developing this code.

=head1 SEE ALSO

=over

=item *

L<Catalyst>

=item *

L<Moose> and L<Moose::Role>

=item *

L<MooseX::MethodAttributes::Role> - Actions composed from L<Moose::Role>.

=item *

L<CatalystX::InjectComponent> - Injects the controller class

=item *

L<HTML::FormHandler> - Generates the login form

=item *

L<Catalyst::Plugin::Authentication> - Responsible for the actual heavy lifting of authenticating the user

=item *

L<Catalyst::Plugin::Session>

=item *

L<Catalyst::Controller> - Allows you to decorate actions with roles (E.g L<Catalyst::ActionRole::NeedsLogin|To force a redirect to the login page>)

=item *

L<CatalystX::Component::Traits> - Allows L<Moose::Role|roles> to be composed onto components from config

=back

=head1 AUTHORS

=over

=item Tomas Doran (t0m) C<< [e-mail] >>

=item Zbigniew Lukasiak

=item Stephan Jauernick (stephan48) C<< [e-mail] >>

=item Gerda Shank (gshank) C<< [e-mail] >>

=item Florian Ragwitz C<< [e-mail] >>

=item Shlomi Fish

=item Oleg Kostyuk (cub-uanic) C<< [e-mail] >>

=back

=head1 LICENSE

Copyright 2009 Tomas Doran. Some rights reserved.

This software is free software, and is licensed under the same terms as perl itself.

=cut

1;