NAME

SYNOPSIS

    package MyFullNameField;

    use base qw(Rose::HTML::Form::Field::Compound
                Rose::HTML::Form::Field::Text);

    sub build_field
    {
      my($self) = shift;

      $self->add_fields
      (
        first  => { type => 'text', size => 15, maxlength => 50 },
        middle => { type => 'text', size => 15, maxlength => 50 },
        last   => { type => 'text', size => 20, maxlength => 50 },
      );
    }

    sub coalesce_value
    {
      my($self) = shift;
      return join(' ', map { defined($_) ? $_ : '' } 
                       map { $self->field($_)->internal_value } 
                       qw(first middle last));
    }

    sub decompose_value
    {
      my($self, $value) = @_;

      return undef  unless(defined $value);

      if($value =~ /^(\S+)\s+(\S+)\s+(\S+)$/)
      {
        return
        {
          first  => $1,
          middle => $2,
          last   => $3,
        };
      }

      my @parts = split(/\s+/, $value);

      if(@parts == 2)
      {
        return
        {
          first  => $parts[0],
          middle => undef,
          last   => $parts[1],
        };
      }

      return
      {
        first  => $parts[0],
        middle => $parts[1],
        last   => join(' ', @parts[2 .. $#parts]),
      };      
    }

    # Override these methods to determine how sub-fields are arranged
    sub html_field  { ... }
    sub xhtml_field { ... }
    ...


    use MyFullNameField;

    $field =
      MyFullNameField->new(
        label   => 'Full Name', 
        name    => 'name',
        default => 'John Doe');

    print $field->internal_value; # "John Doe"

    $field->input_value('Steven Paul Jobs');

    print $field->field('middle')->internal_value; # "Paul"

    print $field->html;
    ...

DESCRIPTION

Externally, a compound field must field look and behave as if it is a single, simple field. Although this can be done in many ways, it is important for all compound fields to actually inherit from Rose::HTML::Form::Field::Compound. Rose::HTML::Form uses this relationship in order to identify compound fields and handle them correctly. Any compound field that does not inherit from Rose::HTML::Form::Field::Compound will not work correctly with Rose::HTML::Form.

This class inherits from, and follows the conventions of, Rose::HTML::Form::Field. Inherited methods that are not overridden will not be documented a second time here. See the Rose::HTML::Form::Field documentation for more information.

HIERARCHY

See the "hierarchy" sections of the "HIERARCHY" in Rose::HTML::Form::Field and "HIERARCHY" in Rose::HTML::Form documentation for more information about how field objects that are really "groups of siblings" behave with respect to the the child-related methods inherited from Rose::HTML::Object.

SUBCLASSING

SUBFIELD ADDRESSING

To that end, compound fields use the "." character to partition the namespace. For example, the "month" sub-field of a compound field named "date" could be addressed from the form that contains the field using the name "date.month". As a consequence of this convention, field names may not contain periods.

Subfields are addressed by their "relative" names from the perspective of the caller. For example, the Rose::HTML::Form::Field::DateTime::Split::MDYHMS custom field class contains a two compound fields: one for the time (split into hours, minutes, seconds, and AM/PM) and one for the date (split into month, day, and year). Here are a few ways to address the various sub-fields.

    $datetime_field = 
      Rose::HTML::Form::Field::DateTime::Split::MDYHMS->new(
        name => 'datetime');

    ## Get the (compound) sub-field containing the month, day, and year
    $mdy_field = $datetime_field->field('date');


    ## Get the year sub-field of the month/day/year sub-field 
    ## in two different ways:

    # Fully-qualified sub-field access
    $year_field = $datetime_field->field('date.year');

    # Relative sub-field access
    $year_field = $datetime_field->field('date')->field('year');

See the Rose::HTML::Form documentation for more information on how forms address and initialize fields based on query parameter names.

VALIDATION

But as you'll see when you start to write your own decompose_value() methods, it's often nice to know whether the input is valid before you try to decompose it into sub-field values. Valid input can usually be divided up very easily, whereas invalid input requires some hard decisions to be made. Consequently, most decompose_value() methods have one section for handling valid input, and another that makes a best-effort to handle invalid input.

There are several ways to determine whether or not a value passed to decompose_value() is valid. You could actually call validate(), but that is technically a violation of the API since decompose_value() only knows that it's supposed to divvy up the value that it is passed. It is merely assuming that this value is also the current value of the field. In short, don't do that.

The decompose_value() method could try to validate the input directly, of course. But that seems like a duplication of code. It might work, but it is more effort.

The recommended solution is to rely on the fact that most overridden inflate_value() methods serve as an alternate form of validation. Really, the decompose_value() method doesn't want to "validate" in the same way that validate() does. Imagine a month/day/year compound field that only accepts dates in the 1990s. As far as validate() is concerned, 12/31/2002 is an invalid value. But as far as decompose_value() is concerned, it's perfectly fine and can be parsed and divided up into sub-field values easily.

This is exactly the determination that many overridden inflate_value() methods must also make. For example, that month/day/year compound field may use a DateTime object as its internal value. The inflate_value() method must parse a date string and produce a DateTime value. The decompose_value() method can use that to its advantage. Example:

    sub decompose_value
    {
      my($self, $value) = @_;

      return undef  unless(defined $value);

      # Use inflate_value() to do the dirty work of
      # sanity checking the value for us
      my $date = $self->SUPER::inflate_value($value);

      # Garbage input: try to do something sensible
      unless($date) 
      {
        my($month, $day, $year) = split('/', $value);

        return
        {
          month => $month || '',
          day   => $day   || '',
          year  => $year  || '',
        }
      }

      # Valid input: divide up appropriately
      return
      {
        month => $date->month,
        day   => $date->day,
        year  => $date->year,
      };
    }

This technique is sound because both decompose_value() and inflate_value() work only with the input they are given, and have no reliance on the state of the field object itself (unlike validate()).

If the inflate_value() method is not being used, then decompose_value() must sanity check its own input. But this code is not necessarily the same as the code in validate(), so there is no real duplication.

OBJECT METHODS

add_field ARGS

Convenience alias for add_fields().

add_fields ARGS

Add the fields specified by ARGS to the list of sub-fields in this compound field.

If an argument is "isa" Rose::HTML::Form::Field, then it is added to the list of fields, stored under the name returned by the field's name() method.

If an argument is anything else, it is used as the field name, and the next argument is used as the field object to store under that name. If the next argument is not an object derived from Rose::HTML::Form::Field, then a fatal error occurs.

The field object's name() is set to the name that it is stored under, and its parent_field() is set to the form object.

Returns the full list of field objects, sorted by field name, in list context, or a reference to a list of the same in scalar context.

Examples:

    $name_field = 
      Rose::HTML::Form::Field::Text->new(name => 'name',
                                         size => 25);

    $email_field = 
      Rose::HTML::Form::Field::Text->new(name => 'email',
                                         size => 50);

    # Field arguments
    $compound_field->add_fields($name_field, $email_field);

    # Name/field pairs
    $compound_field2->add_fields(name  => $name_field, 
                                 email => $email_field);

    # Mixed
    $compound_field3->add_fields($name_field, 
                                 email => $email_field);
    

auto_invalidate_parents [BOOL]

Get or set a boolean value that indicates whether or not the internal value of any parent fields are automatically invalidated when the input value of this field is set. The default is true.

build_field

This method must be overridden by subclasses. Its job is to build the compound field by creating and then adding the sub-fields. Example:

    sub build_field
    {
      my($self) = shift;

      $self->add_fields
      (
        first  => { type => 'text', size => 15, maxlength => 50 },
        middle => { type => 'text', size => 15, maxlength => 50 },
        last   => { type => 'text', size => 20, maxlength => 50 },
      );
    }
    

See the documentation for add_fields() for a full description of the arguments it accepts.

coalesce_value

This method must be overridden by subclasses. It is responsible for combining the values of the sub-fields into a single value. Example:

    sub coalesce_value
    {
      my($self) = shift;
      return join(' ', map { defined($_) ? $_ : '' } 
                       map { $self->field($_)->internal_value } 
                       qw(first middle last));
    }
    

The value returned must be suitable as an input value. See the Rose::HTML::Form::Field documentation for more information on input values.

decompose_value VALUE

This method must be overridden by subclasses. It is responsible for distributing the input value VALUE amongst the various sub-fields. This is harder than you might expect, given the possibility of invalid input. Nevertheless, subclasses must try to divvy up even garbage values such that they eventually produce output values that are equivalent to the original input value when fed back through the system.

The method should return a reference to a hash of sub-field-name/value pairs.

In the example below, the method's job is to decompose a full name into first, middle, and last names. It is not very heroic in its efforts to parse the name, but it at least tries to ensure that every significant piece of the value ends up back in one of the sub-fields.

    sub decompose_value
    {
      my($self, $value) = @_;

      return undef  unless(defined $value);

      # First, middle, and last names all present
      if($value =~ /^(\S+)\s+(\S+)\s+(\S+)$/)
      {
        return
        {
          first  => $1,
          middle => $2,
          last   => $3,
        };
      }

      my @parts = split(/\s+/, $value);

      # First and last?
      if(@parts == 2)
      {
        return
        {
          first  => $parts[0],
          middle => undef,
          last   => $parts[1],
        };
      }

      # Oh well, at least try to make sure all the non-whitespace
      # characters get fed back into the field
      return
      {
        first  => $parts[0],
        middle => $parts[1],
        last   => join(' ', @parts[2 .. $#parts]),
      };      
    }
    

disabled [BOOL]

This method calls the "disabled()" method on all fields that possess such a method, passing all arguments. Set to true to disable all eligible sub-fields, false to enable them.

field NAME [, VALUE]

Get or set the field specified by NAME. If only a NAME argument is passed, then the field stored under the name NAME is returned. If no field exists under that name exists, then undef is returned.

If both NAME and VALUE arguments are passed, then the field VALUE is stored under the name NAME. If VALUE is not an object derived from Rose::HTML::Form::Field, a fatal error occurs.

fields

Returns the full list of field objects, sorted by field name, in list context, or a reference to a list of the same in scalar context.

field_value NAME

Returns the internal_value of the sub-field named NAME. In other words, this:

    $val = $field->field_value('zip_code');
    

is just a shorter way to write this:

    $val = $field->field('zip_code')->internal_value;
    

html_field

Returns the HTML serialization of the field. The default implementation calls html_field on each of the fields and then concatenates and the results. Override this method in your compound field subclass to lay out your sub-fields as desired.

invalidate_value

Invalidates the field's value, and the value of all of its parent fields, and so on. This will cause the field's values to be recreated the next time they are retrieved.

is_empty

Returns true if all of the sub-fields are empty, false otherwise.

is_full

Returns false if any of the sub-fields are empty, true otherwise. Subclasses can override this method to indicate that a valid value does not require all sub-fields to be non-empty.

For example, consider a compound time field with sub-fields for hours, minutes, seconds, and AM/PM. It may only require the hour and AM/PM sub-fields to be filled in. It could then assume values of zero for all of the empty sub-fields.

Note that this behavior is different than making "00" the default values of the minutes and seconds sub-fields. Default values are shown in the HTML serializations of fields, so the minutes and seconds fields would be pre-filled with "00" (unless the field is cleared--see Rose::HTML::Form::Field's reset and clear methods for more information).

If a subclass does override the "is_full" method in order to allow one or more empty sub-fields while still considering the field "full," the subclass must also be sure that its coalesce_value method accounts for and handles the possibility of empty fields.

See the Rose::HTML::Form::Field::Time::Split::HourMinuteSecond source code for an actual implementation of the behavior described above. In particular, look at the implementation of the "is_full" and "coalesce_value" methods.

subfield_input_value NAME [, VALUE]

Get or set the input value of the sub-field named NAME. If there is no sub-field by that name, a fatal error will occur.

This method has the same effect as fetching the sub-field using the field method and then calling input_value directly on it, but with one important exception. Setting a sub-field input value using the subfield_input_value method will not invalidate the value of the parent field.

This method is therefore essential for implementing compound fields that need to set their sub-field values directly. Without it, any attempt to do so would cause the compound field to invalidate itself.

See the source code for Rose::HTML::Form::Field::DateTime::Range's inflate_value method for a real-world usage example of the subfield_input_value method.

xhtml_field

Returns the XHTML serialization of the field. The default implementation calls xhtml_field on each of the fields and then concatenates and the results. Override this method in your compound field subclass to lay out your sub-fields as desired.

SUPPORT

<http://groups.google.com/group/rose-html-objects>

Although the mailing list is the preferred support mechanism, you can also email the author (see below) or file bugs using the CPAN bug tracking system:

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Rose-HTML-Objects>

There's also a wiki and other resources linked from the Rose project home page:

<http://rosecode.org>

AUTHOR

LICENSE