Class::CGI::DateTime - Fetch DateTime objects directly from your forms.
Version 0.02
use Class::CGI handlers => { date => 'Class::CGI::DateTime', order_date => 'Class::CGI::DateTime', }; my $cgi = Class::CGI->new; my $date = $cgi->param('date'); my $order_date = $cgi->param('order_date'); if ( my %errors = $cgi->errors ) { ... }
A common problem with Web programming is handling dates correctly. This Class::CGI handler attempts to do that for you in a standard way by allowing you to have separate day, month and year dropdowns but request a "date" parameter and get the correct object back, safely validated and untainted.
Class::CGI
Multiple dates may be used in a single form and you can even specify hours, minutes, timezones, and so on.
If you have a form with <select> boxes named day, month and year, you can fetch these into a DateTime object with this:
<select>
day
month
year
DateTime
use Class::CGI handlers => { date => 'Class::CGI::DateTime', }; my $cgi = Class::CGI->new; my $date = $cgi->param('date');
The value of each parameter should correspond to allowed values for that parameter to the DateTime constructor.
If you need more than one date object embedded in a form, additional date objects may be specified by prefixing the form parameter names with a unique identifier followed by a dot ("."). For example, to fetch a date and an order date, you can do the following:
use Class::CGI handlers => { date => 'Class::CGI::DateTime', order_date => 'Class::CGI::DateTime', }; my $cgi = Class::CGI->new; my $date = $cgi->param('date'); my $order_date = $cgi->param('order_date');
The date parameter will be created from the day, month and year parameters in the Class::CGI object. The order_date.date parameter will be created from the order_date.day, order_date.month and order_date.year parameters.
date
order_date.date
order_date.day
order_date.month
order_date.year
$cgi->args( date => { params => [qw/ day hour minute /] } );
You cannot change the parameter names (e.g., no changing "day" to "jour" or something like that), but you can specify additional parameters which the DateTime constructor expects. Each parameter's value must correspond to the allowed values for the DateTime object. You do this by setting the requested parameters in Class::CGI's args() method. The key is the date parameter you wish to specify the arguments for and the value should be a hashref with a key of "params" and a value being an array reference specifying the names of the parameters desired.
args()
For example, if your HTML form has day, month, year and timezone, you might do this:
use Class::CGI handlers => { date => 'Class::CGI::DateTime', }; my $cgi = Class::CGI->new; $cgi->args( date => { params => [qw/ day month year time_zone /] } ); my $date = $cgi->param('date');
The allowed parameter names, as specified from the DateTime documentation, are:
hour
minute
second
nanosecond
time_zone
As usual, any errors reported by Class::CGI::DateTime will be in the Class::CGI errors() method. However, the validation errors reported by the DateTime object are generally aimed at programmers, not users of your software. Thus, you'll want to provide more user friendly error messages. For example:
Class::CGI::DateTime
errors()
if ( my %error_for = $cgi->errors ) { if ( exists $error_for{order_date} ) { $error_for{order_date} = "You must enter a valid order date"; } }
If a date is required, it's easy to handle this:
use Class::CGI handlers => { date => 'Class::CGI::DateTime', order_date => 'Class::CGI::DateTime', }; my $cgi = Class::CGI->new; $cgi->required( qw/date order_date/ ); my $date = $cgi->param('date'); my $order_date = $cgi->param('order_date');
Class::CGI::DateTime will not create a date object if any of the required components (day, month, year and so on) are missing. Further, a descriptive error message will be set.
Also note that at the present time, Class::CGI::DateTime only ensures that we can create a valid DateTime object. Application-specific validation (such as ensuring the date is in the future) belongs in your application and should be handled there.
Curtis "Ovid" Poe, <ovid@cpan.org>
<ovid@cpan.org>
Please report any bugs or feature requests to bug-class-cgi-datetime@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Class-CGI-DateTime. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-class-cgi-datetime@rt.cpan.org
DateTime - A date and time object
Adam Kennedy (Alias): for suggesting a better interface.
Copyright 2006 Curtis "Ovid" Poe, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Class::CGI::DateTime, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Class::CGI::DateTime
CPAN shell
perl -MCPAN -e shell install Class::CGI::DateTime
For more information on module installation, please visit the detailed CPAN module installation guide.