HTML::FormHandlerX::Form::Login - An HTML::FormHandler login form.
Version 0.17
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, } );
Login with either an optional email or username parameter.
email
username
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.
token
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, } );
This module will validate your forms. It does not perform any actual authentication, that is still left for you.
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.
password
confirm_password
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.
Instantiate the form by activating the 3 fields: old_password, password, and confirm_password.
old_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 ) { }
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.
token_salt
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.
add_token_field
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.
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.
salt
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 ) { }
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.
token_field
$form->field( 'email' )->value;
And now know which user to update.
$form->token
Returns a unique string for the email or username validated by the form.
You typically send this to the users email.
$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.
$form->token_salt
Your own (random string) salt used to create the reset-password token.
$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.
$form->field('token')
This field is used when attempting to reset a password.
$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).
openid_identifier
$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.
HTML::FormHandler
$form->field('password')
Used for logging in, changing and/or resetting a password to something new.
$form->field('confirm_password')
Required for changing and/or resetting the password.
$form->field('remember')
Useful for a "remember me" checkbox.
$form->field('submit')
The submit button.
The internal validation of the token when attempting to reset a password.
This method has been populated to ensure all fields in error have the error CSS class assigned to the labels.
error
This form does some subtle rendering tricks, renaming buttons and labels based on which fields are active.
Look at password type fields, pre-set char-length, etc. and/or import types from HTML::FormHandler directly.
Rob Brown, <rob at intelcompute.com>
<rob at intelcompute.com>
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.
bug-html-formhandlerx-form-login at rt.cpan.org
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/
gshank: Gerda Shank <gshank@cpan.org>
t0m: Tomas Doran <bobtfish@bobtfish.net>
castaway: Jess Robinson (OpenID support)
Copyright 2012 Rob Brown.
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.