NAME

Rose::HTML::Form::Field::DateTime::Range - Compound field for date ranges with separate text fields for the minimum and maximum dates.

SYNOPSIS

    $field =
      Rose::HTML::Form::Field::DateTime::Range->new(
        label   => 'Date',
        name    => 'date',
        default => [ '1/2/2003', '4/5/2006' ]);

    my($min, $max) = $field->internal_value; # DateTime objects

    print $min->strftime('%Y-%m-%d'); # "2003-01-02"
    print $max->strftime('%Y-%m-%d'); # "2006-04-05"

    $field->input_value('5/6/1980 3pm to 2003-01-06 20:19:55');

    my $dates = $field->internal_value;

    print $dates->[0]->hour; # 15
    print $dates->[1]->hour; # 20

    print $dates->[0]->day_name; # Tuesday

    print $field->html;

    ...

DESCRIPTION

Rose::HTML::Form::Field::DateTime::Range is a compound field that represents a date range. It is made up of two subfields: a Rose::HTML::Form::Field::DateTime::StartDate field and a Rose::HTML::Form::Field::DateTime::EndDate field.

The internal value of this field is a list (in list context) or reference to an array (in scalar context) of two DateTime objects. The first object is the start date and the second is the end date. If either of fields are not filled in or are otherwise invalid, then the internal value is undef.

The input value can be a reference to an array of DateTime objects, or strings that can be inflated into DateTime objects by the Rose::HTML::Form::Field::DateTime::StartDate and Rose::HTML::Form::Field::DateTime::EndDate classes. The input value can also be a concatenation of two such strings, joined by a string that matches the field's range_separator_regex.

This class is a good example of a compound field whose internal value consists of more than one object. See below for more compound field examples.

It is important that this class inherits from Rose::HTML::Form::Field::Compound. See the Rose::HTML::Form::Field::Compound documentation for more information.

OBJECT METHODS

range_separator [STRING]

Get or set the string used to join the output values of the start and end date subfields in order to produce this field's output value. The default string is "#". Example:

    $field->input_value([ '1/2/2003', '4/5/2006' ]);

    # "2003-01-02 00:00:00#2006-04-05 00:00:00"
    print $field->output_value; 

range_separator_regex [REGEX]

Get or set the regular expression used to split an input string into start date and end date portions. The default value is qr(#|\s+to\s+). Example:

    $field->input_value('2005-04-20 8pm to 1/7/2006 3:05 AM');

    my($min, $max) = $field->internal_value;

    print $min->day_name; # Wednesday
    print $max->day_name; # Saturday

    # Change regex, adding support for " - "
    $field->range_separator_regex(qr(#|\s+(?:to|-)\s+));

    $field->input_value('2005-04-20 8pm - 1/7/2006 3:05 AM');

    ($min, $max) = $field->internal_value;

    print $min->day_name; # Wednesday
    print $max->day_name; # Saturday

Note that the range_separator_regex must match the range_separator string.

When setting range_separator_regex, you should use the qr operator to create a pre-compiled regex (as shown in the example above) If you do not, then the regex will be recompiled each time it's used.

SEE ALSO

Other examples of custom fields:

Rose::HTML::Form::Field::Email

A text field that only accepts valid email addresses.

Rose::HTML::Form::Field::Time

Uses inflate/deflate to coerce input into a fixed format.

Rose::HTML::Form::Field::DateTime

Uses inflate/deflate to convert input to a DateTime object.

Rose::HTML::Form::Field::PhoneNumber::US::Split

A simple compound field that coalesces multiple subfields into a single value.

Rose::HTML::Form::Field::DateTime::Split::MonthDayYear

A compound field that uses inflate/deflate convert input from multiple subfields into a DateTime object.

Rose::HTML::Form::Field::DateTime::Split::MDYHMS

A compound field that includes other compound fields and uses inflate/deflate convert input from multiple subfields into a DateTime object.

AUTHOR

John C. Siracusa (siracusa@gmail.com)

LICENSE

Copyright (c) 2010 by John C. Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.