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.

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:

  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.

 $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.

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:

* year

* month

* day

* 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:

  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>

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.

* 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.