NAME

HTML::FormHandlerX::Form::Login - An HTML::FormHandler login form.

VERSION

Version 0.17

SYNOPSIS

Performs login form validation, including changing passwords, forgotten passwords, and resetting passwords.

If you are working under Catalyst, take a look at CatalystX::SimpleLogin or CatalystX::Controller::Auth.

Registering...

 $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( email password confirm_password ) ] );

 $form->process( params => { email            => $email,
                             password         => $password,
                             confirm_password => $confirm_password,
                           } );

 my $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( email password ) ] );
 
 $form->process( params => { email => $email, password => $password } );

Changing a password...

 my $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( old_password password confirm_password ) ] );
 
 $form->process( params => { old_password     => $old_password,
                             password         => $password,
                             confirm_password => $confirm_password,
                           } );

Forgot password, just validates an email, or username.

Use this to create a token to send to the user to verify their email address.

 my $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( email ) ] );
 
 $form->process( params => { email => $email } );
 
 if ( $form->validated )
 {
         $form->token_salt( 'SoMeThInG R4nD0M AnD PR1V4te' );

         my $token = $form->token;
 }

Coming back from an email link, if the form validates, you would show the password reset form (carry the token in a hidden field or cookie).

 $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( token ) ] );
 
 $form->token_salt( 'SoMeThInG R4nD0M AnD PR1V4te' );
 
 $form->process( params => { token => $token } );

When trying to actually reset a password...

 $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( token password confirm_password ) ] );
 
 $form->token_salt( 'SoMeThInG R4nD0M AnD PR1V4te' );

 $form->process( params => { token            => $token,
                             password         => $password,
                             confirm_password => $confirm_password,
                           } );

DESCRIPTION

This module will validate your forms. It does not perform any actual authentication, that is still left for you.

Register

You can register with either an email or username.

Using email brings in validation using Email::Valid.

email/username, password and confirm_password are all required fields, so will fail validation if empty.

 my $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( email password confirm_password ) ] );
 
 $form->process( params => { email => $email, password => $password, confirm_password => $confirm_password } );

You can choose between an optional email and username for the unique identifier.

Using email brings in validation using Email::Valid.

 my $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( email password ) ] );
 
 $form->process( params => { email => $email, password => $password } );

Change Password

Instantiate the form by activating the 3 fields: old_password, password, and confirm_password.

All 3 fields are required, and validation will also check the confirm_password matches the password.

 my $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( old_password password confirm_password ) ] );
 
 $form->process( params => { old_password     => $old_password,
                             password         => $password,
                             confirm_password => $confirm_password,
                           } );
 
 if ( $form->validated ) { }

Forgot Password

Provide the email or username to validate, the form will then have a token for you.

You can then send this token to the user via email to verify their identity.

You need to supply a (private) token_salt to make sure your tokens are not guessable. This can be anything you like.

Tokens expire by default after 24 hours from the date/time of issue. To change this, either supply an epoch timestamp of when to expire, or give a human-friendly format of how long to wait. We like things like:

 2h - 2 hours
 3d - 3 days
 4w - 4 weeks
 5m - 5 months

If you specify add_token_field the value of this field in the form will be included in the token. This can be useful when the token is sent back, to identify the user.

 my $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( email ) ] );
 
 $form->process( params => { email => $email } );
 
 if ( $form->validated )
 {
         $form->token_salt( 'SoMeThInG R4nD0M AnD PR1V4te' );
         
         $form->add_token_field( 'email' );
         
         $form->token_expires( '3h' );
  
         my $token = $form->token;
 }

The token is comprised of a Digest::SHA hash, so can be a tad long, but has much less chance of collisions compared to an MD5.

Reset Password - Stage 1

You will usually give the token to the user in an email so they can verify they own the email address.

This step is for just showing the user a reset-password form.

The first step when the user comes back to reset their password, is to check they have not fiddled with the token.

You can safely skip this step, we check the token again when they/you actually try to change the password, this just lets you stop them in their tracks a little sooner.

Setting the token_salt is required, and must obviously be the same salt as used in the forgot-password call.

add_token_field as you did during the forgot-password process. This will populate the unique identifier field for you.

 $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( token ) ] );
 
 $form->token_salt( 'SoMeThInG R4nD0M AnD PR1V4te' );
 
 $form->add_token_field( 'email' );
 
 $form->process( params => { token => $token } );
 
 if ( $form->validated ) { }

Reset Password - Stage 2

You have now shown the user a form to enter a new password (and confirm it).

Either hidden in that form, or as a cookie, you have also stored the token.

 $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( token password confirm_password ) ] );
 
 $form->token_salt( 'SoMeThInG R4nD0M AnD PR1V4te' );
 
 $form->add_token_field( 'email' );
 
 $form->process( params => { token            => $token,
                             password         => $password,
                             confirm_password => $confirm_password,
                           } );
 
 if ( $form->validated ) { }

If you specified the token_field as email, you can now collect that from the form as the record to update safely.

 $form->field( 'email' )->value;

And now know which user to update.

METHODS

Attributes

token

 $form->token

Returns a unique string for the email or username validated by the form.

You typically send this to the users email.

token_fields

 $form->add_token_field( 'email' );

Specifies which fields to include in the token for you to identify which user it is trying to reset their password when they come back.

Either email or username is normal.

token_salt

 $form->token_salt

Your own (random string) salt used to create the reset-password token.

token_expires

 $form->token_expires

Dictates how long the token is valid for, default is 1 day.

Possible formats are 2h, 3d, 6w, 1m, or an epoch timestamp.

Fields

token

 $form->field('token')

This field is used when attempting to reset a password.

email / username / openid_identifier

 $form->field('email')
 
 $form->field('username')

 $form->field('openid_identifier')

The openid_identifier field used by Catalyst::Authentication::Credential::OpenID for OpenID logins, username field, or use the specific email field for extra validation (employing Email::Valid).

old_password

 $form->field('old_password')

Required when changing a known password.

HTML::FormHandler has a built-in length restriction for password fields of 6-characters, we drop that to 1-character, it is up to you to come with your own rules.

password

 $form->field('password')

Used for logging in, changing and/or resetting a password to something new.

HTML::FormHandler has a built-in length restriction for password fields of 6-characters, we drop that to 1-character, it is up to you to come with your own rules.

confirm_password

 $form->field('confirm_password')

Required for changing and/or resetting the password.

remember

 $form->field('remember')

Useful for a "remember me" checkbox.

submit

 $form->field('submit')

The submit button.

Validation

validate_token

The internal validation of the token when attempting to reset a password.

html_attributes

This method has been populated to ensure all fields in error have the error CSS class assigned to the labels.

RENDERING

This form does some subtle rendering tricks, renaming buttons and labels based on which fields are active.

TODO

Look at password type fields, pre-set char-length, etc. and/or import types from HTML::FormHandler directly.

AUTHOR

Rob Brown, <rob at intelcompute.com>

BUGS

Please report any bugs or feature requests to bug-html-formhandlerx-form-login at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTML-FormHandlerX-Form-Login. I will be notified, and then you will automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc HTML::FormHandlerX::Form::Login

You can also look for information at:

RT: CPAN's request tracker (report bugs here)

http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTML-FormHandlerX-Form-Login
AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/HTML-FormHandlerX-Form-Login
CPAN Ratings

http://cpanratings.perl.org/d/HTML-FormHandlerX-Form-Login
Search CPAN

http://search.cpan.org/dist/HTML-FormHandlerX-Form-Login/

ACKNOWLEDGEMENTS

gshank: Gerda Shank <gshank@cpan.org>

t0m: Tomas Doran <bobtfish@bobtfish.net>

castaway: Jess Robinson (OpenID support)

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

To install HTML::FormHandlerX::Form::Login, copy and paste the appropriate command in to your terminal.

cpanm

cpanm HTML::FormHandlerX::Form::Login

CPAN shell

perl -MCPAN -e shell
install HTML::FormHandlerX::Form::Login

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

Register

Login

Change Password

Forgot Password

Reset Password - Stage 1

Reset Password - Stage 2

METHODS

Attributes

token

token_fields

token_salt

token_expires

Fields

token

email / username / openid_identifier

old_password

password

confirm_password

remember

submit

Validation

validate_token

html_attributes

RENDERING

TODO

AUTHOR

BUGS

SUPPORT

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Module Install Instructions