Rose::HTML::Form::Field::DateTime::Range(3)

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) 2009 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.