NAME

SYNOPSIS

  package PersonForm;

  use base 'Rose::HTML::Form';

  use Person;

  sub build_form 
  {
    my($self) = shift;

    $self->add_fields
    (
      name  => { type => 'text',  size => 25, required => 1 },
      email => { type => 'email', size => 50, required => 1 },
      phone => { type => 'phone' },
    );
  }

  sub validate
  {
    my($self) = shift;

    # Base class will validate individual fields in isolation,
    # confirming that all required fields are filled in, and that
    # the email address and phone number are formatted correctly.
    my $ok = $self->SUPER::validate(@_);
    return $ok  unless($ok);

    # Inter-field validation goes here
    if($self->field_value('name') ne 'John Doe' &&
       $self->field_value('phone') =~ /^555/)
    {
      $self->error('Only John Doe can have a 555 phone number.');
      return 0;
    }

    return 1;
  }

  sub init_with_person # give a friendlier name to a base-class method
  {
    my($self, $person) = @_;
    $self->init_with_object($person);
  }

  sub person_from_form
  {
    my($self) = shift;

    # Base class method does most of the work
    my $person = $self->object_from_form(class => 'Person');

    # Now fill in the non-obvious details...
    # e.g., set alt phone to be the same as the regular phone
    $person->alt_phone($self->field_value('phone'));

    return $person;
  }

  ...

  #
  # Sample usage in a hypothetical web application
  #

  $form = PersonForm->new;

  if(...)
  {
    # Get query parameters in a hash ref and pass to the form
    my $params = MyWebServer->get_query_params();
    $form->params($params);

    # ...or  initialize form params from a CGI object
    # $form->params_from_cgi($cgi); # $cgi "isa" CGI

    # ...or initialize params from an Apache request object
    # (mod_perl 1 and 2 both supported)
    # $form->params_from_apache($r);

    # Initialize the fields based on params
    $form->init_fields();

    unless($form->validate) 
    {
      return error_page(error => $form->error);
    }

    $person = $form->person_from_form; # $person is a Person object

    do_something_with($person);
    ...
  }
  else
  {
    $person = ...; # Get or create a Person object somehow

    # Initialize the form with the Person object
    $form->init_with_person($person);

    # Pass the initialized form object to the template
    display_page(form => $form);
  }
  ...

DESCRIPTION

Building up a reusable library of form classes is extremely helpful when building large web applications with forms that may appear in many different places. Similar forms can inherit from a common subclass, and forms may be nested.

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

OVERVIEW

For example, instead of asking a form object for the values of the "name", "email", and "phone" fields, the user would ask the form object to return a new "Person" object that encapsulates those values.

Form objects should also accept initialization through the same kinds of objects that they return. Subclasses are encouraged to create methods such as (to use the example described above) "init_with_person()" and "person_from_form()" in order to do this. The generic methods init_with_object() and object_from_form() are meant to ease the implementation of such custom methods.

Form objects can also take input through a hash. Each hash key correspond to a field (or subfield) name, and each value is either a scalar or a reference to an array of scalars (for multiple-value fields). This hash of parameters can be queried and manipulated before finally calling init_fields() in order to initialize the fields based on the current state of the parameters.

Compound fields (fields consisting of more than one HTML field, such as a month/day/year date field with separate text fields for each element of the date) may be "addressed" by hash arguments using both top-level names (e.g., "birthday") or by subfield names (e.g., "birthday.month", "birthday.day", "birthday.year"). If the top-level name exists in the hash, then subfield names are ignored. See Rose::HTML::Form::Field::Compound for more information on compound fields.

Each form has a list of field objects. Each field object is stored under a name, which may or may not be the same as the field name, which may or may not be the same as the "name" HTML attribute for any of the HTML tags that make up that field.

Forms are validated by calling validate() on each field object. If any individual field does not validate, then the form is invalid. Inter-field validation is the responsibility of the form object.

HIERARCHY

Pushing a child adds it after the list of fields. Unshifting a child adds it before the list of fields. Popping or shifting children will pull children through, past the fields, to exit the list of children at either end. In other words, children manipulated using the child object APIs will "flow around" the list of fields.

If a particular field is a group of sibling HTML elements with no real parent HTML element (e.g., a radio button group), then the individual sibling items will be flattened out into the list returned by the children method.

If, on the other hand, a field has a true parent/child relationship (e.g., a select box which contains zero or more options) then the items it contains are not flattened by the children method.

For example, if a form has three fields, a text field, a checkbox group with three checkboxes, and a select box with three options, then the children method will return five objects: the text field object, the three checkboxes objects, and a select box object.

See the hierarchy section of the Rose::HTML::Form::Field documentation for more information about how fields made up of multiple HTML tags are treated with respect to parent/child relationships.

Finally, note that nested forms do not affect the parent/child hierarchy presented by the child-related methods inherited from Rose::HTML::Object since the fields contained in nested forms are flattened out into the field list of parent form, as described in the next section.

NESTED FORMS

Here's a simple example of a nested form made up of a "PersonForm" and an "AddressForm". (Assume "PersonForm" is constructed as per the synopsis above, and "AddressForm" is similar, with street, city, state, and zip code fields.)

    package PersonAddressForm;

    use PersonForm;
    use AddressForm;

    sub build_form
    {
      my($self) = shift;

      $self->add_forms
      (
        person  => PersonForm->new,
        address => AddressForm->new,
      );
    }

Each sub-form is given a name. Sub-field addressing incorporates that name in much the same way as compound field addressing, with dots (".") used to delimit the hierarchy. Here are two different ways to get at the person's email field.

    $form = PersonAddressForm->new;

    # These are equivalent
    $email_field = $form->field('person.email');
    $email_field = $form->form('person')->field('email');

Methods on the sub-forms maybe accessed in a similar manner.

    $person = $form->form('person')->person_from_form();

By default, methods are delegated to sub-forms automatically, so this works too.

    $person = $form->person_from_form();

(See the delegate_to_subforms() method to learn how to alter this behavior.)

Nested forms may have their own fields as well, and the nesting may continue to an arbitrary depth. Here's a form that contains a "PersonAddressForm" as well as two fields of its own.

    package PersonAddressPetsForm;

    use PersonAddressForm;

    sub build_form
    {
      my($self) = shift;

      $self->add_form(pa => PersonAddressForm->new);

      $self->add_fields
      (
        dog => { type => 'text', size => 30 },
        cat => { type => 'text', size => 30 },
      );
    }

Sub-form and field addressing works as expected. Here are several equivalent ways to get at the person's email field.

    $form = PersonAddressPetsForm->new;

    # These are all equivalent
    $email_field = $form->field('pa.person.email');
    $email_field = $form->form('pa.person')->field('email');
    $email_field = $form->form('pa')->form('person')->field('email');

Sub-form method calls and delegation also works as expected.

    # Call method on the PersonForm, two different ways
    $person = $form->form('pa')->form('person')->person_from_form();
    $person = $form->form('pa.person')->person_from_form();

    # Rely on delegation instead
    $person = $form->form('pa')->person_from_form();
    $person = $form->person_from_form();

Nested forms are a great way to build on top of past work. When combined with traditional subclassing, form generation can be entirely cleansed of duplicated code.

HTML ATTRIBUTES

    accept
    accept-charset
    accesskey
    action
    class
    dir
    enctype
    id
    lang
    method
    name
    onblur
    onclick
    ondblclick
    onfocus
    onkeydown
    onkeypress
    onkeyup
    onmousedown
    onmousemove
    onmouseout
    onmouseover
    onmouseup
    onreset
    onsubmit
    style
    tabindex
    target
    title
    value
    xml:lang

Required attributes (default values in parentheses):

    action
    enctype (application/x-www-form-urlencoded)
    method  (get)

CLASS METHODS

default_recursive_init_fields [BOOL]

Get or set a boolean value that determines the default value of the recursive_init_fields object attribute. The default value is false.

delegate_to_subforms [SETTING]

Get or set the value that determines how (or if) forms of this class delegate unresolved method calls to sub-forms. If a method is called on a form of this class, and that method does not exist in this class or any other class in its inheritance hierarchy, then the method may optionally be delegated to a sub-forms. Valid values for SETTING are:

default_trim_xy_params [BOOL]

Get or set a boolean value that is used as the default value of the trim_xy_params object attribute. The default value is true.

CONSTRUCTOR

new PARAMS

Constructs a new Rose::HTML::Form object based on PARAMS, where PARAMS are name/value pairs. Any object method is a valid parameter name.

OBJECT METHODS

add_field ARGS

Convenience alias for add_fields().

add_fields ARGS

Add the fields specified by ARGS to the list of fields contained in this form. ARGS may be a list or a reference to an array. Valid formats for elements of ARGS are:

    # Name/hashref pairs
    $form->add_fields(name  => { type => 'text',  size => 20 },
                      email => { type => 'email', size => 30 });

    # Name/type pairs
    $form->add_fields(name  => 'text',
                      email => 'email');

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

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

    # Object arguments
    $form->add_fields($name_field, $email_field);

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

    # Mixed
    $form->add_fields($name_field, 
                      email => $email_field,
                      nick  => { type => 'text', size => 15 },
                      age   => 'text');

add_field_type_classes [MAP]

Add entries to the field_type_classes hash that maps field type strings to the names of the Rose::HTML::Form::Field-derived classes. Example:

    My::HTML::Form->add_field_type_classes
    (
      nick => 'My::HTML::Form::Field::Nickname',
      age  => 'My::HTML::Form::Field::Age',
      ...
    );
    

This method is an alias for the add_object_type_classes method inherited from Rose::HTML::Object. It is an inherited hash representing the union of the hashes of all superclasses, minus any keys that are explicitly deleted in the current class.

add_form ARGS

This is an alias for the add_forms() method.

add_forms ARGS

Add the forms specified by ARGS to the list of sub-forms contained in this form. See the nested forms section for more information.

Valid formats for elements of ARGS are:

    # Using a form class name
    emails =>
    {
      form_class => 'EmailForm',
      repeatable => 3, # Default count is 3.
    }

    # Using a form class name and form spec
    emails =>
    {
      form_class => 'EmailForm',
      form_spec  => { empty_is_ok => 1 },
      repeatable => 3, # Default count is 3.
    }

    # Using a generic form class and form spec to specify the 
    # contents of a repeated form "inline" in the repeat spec
    nicknames =>
    {
      form_class => 'My::HTML::Form',
      form_spec  => { fields => [ nick => { type => 'text' } ] },
      repeatable => 3, # Default count is 3.
    }

    # Using a prototype object
    nicknames =>
    {
      form          => NickNameForm->new,
      default_count => 0, # Explicitly set default count to 0.
      repeatable    => 1, # This key must be present even though
                          # the default count is set above.
    }

add_param_value NAME, VALUE

Add VALUE to the parameter named NAME. Example:

    $form->param(a => 1);
    print $form->param('a'); # 1

    $form->add_param_value(a => 2);

    print join(',', $form->param('a')); # 1,2
    

app [OBJECT]

Get or set a weakened reference to the application object that "owns" this form.

add_repeatable_form ARGS

This method is an alias for the add_repeatable_forms() method.

add_repeatable_forms ARGS

Add the repeatable forms specified by ARGS to the list of sub-forms contained in this form. This method takes arguments in the same format as the add_forms method, except that all argument types are coerced into a form that will cause add_forms to recognize it as a repeatable form. This is a convenient way to add repeatable forms without having to include the "repeatable" key in your repeat spec. (See the documentation for the add_forms method for more information.)

Examples

    $form->add_repeatable_forms
    (
      # Object argument
      EmailForm->new(...), 

      # Name/object pair
      colors => ColorForm->new(...),

      # Name/hashref pair. (Note: no "repeatable" key needed)
      nicknames => 
      {
        form          => NickNameForm->new,
        default_count => 2,
      },
    );
    

build_on_init [BOOL]

Get or set a boolean flag that indicates whether or not build_form() should be called from within the init() method. See build_form() for more information.

build_form

This default implementation of this method is a no-op. It is meant to be overridden by subclasses. It is called at the end of the init() method if build_on_init() is true. (Remember that this class inherits from Rose::HTML::Object, which inherits from Rose::Object, which defines the init() method, which is called from the constructor. See the Rose::Object documentation for more information.)

If build_on_init() is false, then you must remember to call build_form() manually.

Subclasses should populate the field list in their overridden versions of build_form(). Example:

  sub build_form 
  {
    my($self) = shift;

    $self->add_fields
    (
      name  => { type => 'text',  size => 25, required => 1 },
      email => { type => 'email', size => 50, required => 1 },
      phone => { type => 'phone' },
    );
  }
    

clear

Call clear() on each field object and set error() to undef.

clear_fields

Call clear() on each field object.

coalesce_hidden_fields [BOOL]

Get or set the boolean flag that controls how compound field values are encoded in hidden fields. If this flag is true, then each compound field is encoded as a single hidden field. If the flag is false (the default), then each subfield of a compound field will have its own hidden field.

coalesce_query_string_params [BOOL]

Get or set the boolean flag that controls how compound field values are encoded in the query string. If this flag is true (the default), then compound fields are represented by a single query parameter. Otherwise, the subfields of each compound field appear as separate query parameters.

compare_fields [FIELD1, FIELD2]

Compare two fields, returning 1 if FIELD1 should come before FIELD2, -1 if FIELD2 should come before FIELD1, or 0 if neither field should come before the other. This method is called from within the field_names method to determine the order of the fields in this form.

The default implementation performs a string comparison on the names of the fields.

compare_forms [FORM1, FORM2]

Compare two forms, returning 1 if FORM1 should come before FORM2, -1 if FORM2 should come before FORM1, or 0 if neither form should come before the other. This method is called from within the form_names and field_monikers methods to determine the order of the sub-forms nested within this form.

The default implementation compares the rank of the forms in numeric context.

delete_field NAME

Delete the form stored under the name NAME. If NAME "isa" Rose::HTML::Form::Field, then the name method is called on it and the return value is used as NAME.

delete_fields

Delete all fields, leaving the list of fields empty. The field_rank_counter is also reset to 1.

delete_field_type_class TYPE

Delete the type/class mapping entry for the field type TYPE.

delete_form NAME

Delete the form stored under the name NAME. If NAME "isa" Rose::HTML::Form, then the form_name method is called on it and the return value is used as NAME.

delete_forms

Delete all sub-forms, leaving the list of sub-forms empty.

delete_param NAME [, VALUES]

If just the NAME argument is passed, the parameter named NAME is deleted.

If VALUES are also passed, then VALUES are deleted from the set of values held by the parameter name NAME. If only one value remains, then it is the new value for the NAME parameter (i.e., the value is no longer an array reference, but a scalar instead). If every value is deleted, then the NAME parameter is deleted as well. Example:

    $form->param(a => [ 1, 2, 3, 4 ]);

    $form->delete_param(a => 1);
    $vals = $form->param('a'); # [ 2, 3, 4 ]

    $form->delete_param(a => [ 2, 3 ]);
    $vals = $form->param('a'); # 4

    $form->delete_param(a => 4);
    $vals = $form->param('a'); # undef
    $form->param_exists('a');  # false
    

delete_params

Delete all parameters.

delete_repeatable_form NAME

Delete the repeatable form stored under the name NAME. If NAME "isa" Rose::HTML::Form, then the form_name method is called on it and the return value is used as NAME.

delete_repeatable_forms

Delete all repeatable sub-forms.

empty_is_ok [BOOL]

Get or set a boolean value that indicates whether or not validate will be allowed to return true if every field in the form is empty, even if some of them are required. The default value is false.

end_html

Returns the HTML required to end the form.

end_xhtml

Returns the XHTML required to end the form.

end_multipart_html

Returns the HTML required to end a multipart form.

end_multipart_xhtml

Returns the XHTML required to end a multipart form.

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 VALUE must be a Rose::HTML::Form::Field or a reference to a hash whose contents are as described in the documentation for the add_fields method.

fields [FIELDS]

If FIELDS are passed, this method deletes all existing fields and then calls add_fields, passing all arguments.

The return value is an ordered list of this form's field objects in list context, or a reference to this list in scalar context. The order of the fields matches the order of the field names returned by the field_monikers method.

fields_depth_first

Returns a list (in list context) or reference to an array (in scalar context) of this form's field objects ordered according to a depth-first traversal of all sub-forms. Fields within a given form are ordered by rank, and all fields at a given level precede any sub-forms nested under that level.

field_monikers

Returns an ordered list of field monikers in list context, or a reference to this list in scalar context. A "moniker" is a fully qualified name, including any sub-form or sub-field prefixes (e.g., "pa.person.email" as seen in the nested forms section above).

The order is determined by the compare_forms and compare_fields methods. The compare_forms method is passed the parent form of each field. If it returns a true value, then that value is used to sort the two fields being compared. If it returns false, then the compare_fields method is called with the two field objects as arguments and its return value is used to determine the order. See the documentation for the compare_forms and compare_fields methods for more information.

field_names

This method simply calls field_monikers.

field_rank_counter [INT]

Get or set the value of the counter used to set the rank of fields as they're added to the form. The counter starts at 1 by default.

field_type_class TYPE [, CLASS]

Given the field type string TYPE, return the name of the Rose::HTML::Object-derived class mapped to that name. If a CLASS is passed, the field type TYPE is mapped to CLASS.

This method is an alias for the object_type_class method inherited from Rose::HTML::Object. It is an inherited hash representing the union of the hashes of all superclasses, minus any keys that are explicitly deleted in the current class.

field_type_classes [MAP]

Get or set the hash that maps object type strings to the names of the Rose::HTML::Object-derived classes. This map

If passed MAP (a list of type/class pairs or a reference to a hash of the same) then MAP replaces the current field type mapping. Returns a list of type/class pairs (in list context) or a reference to a hash of type/class mappings (in scalar context).

This method is an alias for the object_type_classes method inherited from Rose::HTML::Object. It is an inherited hash representing the union of the hashes of all superclasses, minus any keys that are explicitly deleted in the current class.

The default mapping of type names to classes is shown in the Rose::HTML::Object documentation.

field_value NAME [, VALUE]

If passed NAME and VALUE arguments, then the input_value of the field named NAME is set to VALUE. If passed only a NAME, then the internal_value of the field named NAME is returned. In other words, this:

    $form->field_value(zip_code => '11787');
    

is equivalent to this:

    $form->field('zip_code')->input_value('11787');
    

and this:

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

is equivalent to this:

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

If no field named NAME exists, a fatal error will occur.

form NAME [, OBJECT]

Get or set the sub-form named NAME. If just NAME is passed, the specified sub-form object is returned. If no such sub-form exists, undef is returnend.

If both NAME and OBJECT are passed, a new sub-form is added under NAME.

NAME is a fully-qualified sub-form name. Components of the hierarchy are separated by dots ("."). OBJECT must be an object that inherits from Rose::HTML::Form.

forms [FORMS]

If FORMS are passed, this method deletes all existing forms and then calls add_forms, passing all arguments.

The return value is an ordered list of this form's sub-form objects (if any) in list context, or a reference to this list in scalar context. The order of the forms matches the order of the form names returned by the form_names method.

See the nested forms section to learn more about nested forms.

form_name [NAME]

Get or set the name of this form. This name may or may not have any connection with the value of the "name" HTML attribute on the <form> tag. See the documentation for the name method for details.

form_names

Returns an ordered list of form names in list context, or a reference to this list in scalar context. The order is determined by the compare_forms method. Note that this only lists the forms that are direct children of the current form. Forms that are nested more than one level deep are not listed.

form_rank_counter [INT]

This method is deprecated and will be removed in a future release.

hidden_fields

Returns one or more Rose::HTML::Form::Field::Hidden objects that represent the hidden fields needed to encode all of the field values in this form.

If coalesce_hidden_fields() is true, then each compound field is encoded as a single hidden field. Otherwise, each subfield of a compound field will be have its own hidden field.

html_hidden_fields

Returns the HTML serialization of the fields returned by hidden_fields(), joined by newlines.

init_fields [PARAMS]

Initialize the fields based on params(). In general, this works as you'd expect, but the details are a bit complicated.

The intention of init_fields() is to set field values based solely and entirely on params(). That means that default values for fields should not be considered unless they are explicitly part of params().

In general, default values for fields exist for the purpose of displaying the HTML form with certain items pre-selected or filled in. In a typical usage scenario, those default values will end up in the web browser form submission and, eventually, as as an explicit part of part params(), so they are not really ignored.

But to preserve the intended functionality of init_fields(), the first thing this method does is clear() the form. (This is the default. See the "no_clear" parameter below.)

If a parameter name exactly matches a field's name (note: the field's name, which is not necessarily the the same as the name that the field is stored under in the form), then the (list context) value of that parameter is passed as the input_value() for that field.

If a field "isa" Rose::HTML::Form::Field::Compound, and if no parameter exactly matches the name of the compound field, then each subfield may be initialized by a parameter name that matches the subfield's name.

If a field is an "on/off" type of field (e.g., a radio button or checkbox), then the field is turned "on" only if the value of the parameter that matches the field's name exactly matches (string comparison) the "value" HTML attribute of the field. If not, and if params_exist(), then the field is set to "off". Otherwise, the field is not modified at all.

PARAMS are name/value pairs. Valid parameters are:

    package RegistrationForm;
    ...
    sub build_form 
    {
      my($self) = shift;

      $self->add_fields
      (
        name => { type => 'text', size => 25 },

        gender => 
        {
          type    => 'radio group',
          choices => { 'm' => 'Male', 'f' => 'Female' },
          default => 'm'
        },

        hobbies =>
        {
          type    => 'checkbox group',
          name    => 'hobbies',
          choices => [ 'Chess', 'Checkers', 'Knitting' ],
          default => 'Chess'
        },

        bday = => { type => 'date split mdy' }
      );
    }

    ...

    $form = RegistrationForm->new();

    $form->params(name    => 'John', 
                  gender  => 'm',
                  hobbies => undef,
                  bday    => '1/24/1984');

    # John, Male, no hobbies, 1/24/1984
    $form->init_fields;

    $form->reset;
    $form->params(name  => 'John', 
                  bday  => '1/24/1984');

    # No name, Male, Chess, 1/24/1984
    $form->init_fields(no_clear => 1);

    $form->reset;
    # Set using subfield names for "bday" compound field
    $form->params('name'       => 'John',
                  'bday.month' => 1,
                  'bday.day'   => 24,
                  'bday.year'  => 1984);

    # John, Male, no hobbies, 1/24/1984
    $form->init_fields();

    $form->reset;
    $form->params('bday'       => '1/24/1984',
                  'bday.month' => 12,
                  'bday.day'   => 25,
                  'bday.year'  => 1975);

    # No name, no gender, no hobbies, but 1/24/1984 because
    # the "bday" param trumps any and all subfield params.
    $form->init_fields();

    $form->reset;

    # Explicitly set hobbies field to Knitting...
    $form->field('hobbies')->input_value('Knitting');

    # ...but then provide a hobbies param with no value
    $form->params('hobbies' => undef);

    # Fields are not cleared, but the existence of the hobbies
    # param with an empty value causes the hobbies list to be
    # empty, instead of the default Chess.  Thus:
    #
    # No name, Male, no hobbies, no birthday
    $form->init_fields(no_clear => 1);

init_fields_with_cgi CGI [, ARGS]

This method is a shortcut for initializing the form's params with a CGI object and then calling init_fields. The CGI argument is passed to the params_from_cgi method and ARGS are passed to the init_fields method.

For example, this:

    $form->init_fields_with_cgi($cgi, no_clear => 1);
    

Is equivalent to this:

    $form->params_from_cgi($cgi);
    $form->init_fields(no_clear => 1);
    

See the documentation for the params_from_cgi and init_fields methods for more information.

init_fields_with_apache APR [, ARGS]

This method is a shortcut for initializing the form's params with an apache request object and then calling init_fields. The APR argument is passed to the params_from_apache method and ARGS are passed to the init_fields method.

For example, this:

    $form->init_fields_with_apache($r, no_clear => 1);
    

Is equivalent to this:

    $form->params_from_apache($r);
    $form->init_fields(no_clear => 1);
    

See the documentation for the params_from_apache and init_fields methods for more information.

init_with_object OBJECT

Initialize the form based on OBJECT. First, the form is clear()ed. Next, for each field name(), if the object has a method with the same name, then the return value of that method (called in scalar context) is passed as the input_value() for the form field of the same name.

The actual code for the init_with_object() method may be more clear than the description above. Essentially, it does this:

    sub init_with_object
    {
      my($self, $object) = @_;

      $self->clear();

      foreach my $field ($self->fields)
      {
        my $name = $field->local_name;

        if($object->can($name))
        {
          $field->input_value(scalar $object->$name());
        }
      }
    }
    

Use this method as a "helper" when writing your own methods such as "init_with_person()", as described in the example in the overview. init_with_object() should be called in the code for subclasses of Rose::HTML::Form, but never by an end-user of such classes.

The convention for naming such methods is "init_with_foo", where "foo" is a (lowercase, underscore-separated, please) description of the object (or objects) used to initialize the form. You are free to accept and handle any kind or number of arguments in your "init_with_foo()"-style methods (all which you'll carefully document, of course).

The field names may not match up exactly with the object method names. In such cases, you can use init_with_object() to handle all the fields that do match up with method names, and then handle the others manually. Example:

    sub init_with_person 
    {
      my($self, $person) = @_;

      # Handle field names that match method names
      $self->init_with_object($person); 

      # Manually set the non-matching or other fields
      $self->field('phone2')->input_value($person->alt_phone);
      $self->field('is_new')->input_value(1);
      ...
    }
    

is_empty

Returns true if each field and nested form in this form is_empty(), false otherwise.

is_repeatable

Returns true if this form is a repeatable form, false otherwise.

local_field NAME [, VALUE]

Get or set a field that is an immediate child of the current form. That is, it does not belong to a nested form. If the field specified by NAME does not meet these criteria, then undef is returned. In all other respects, this method behaves like the field method.

Note that NAME should be the name as seen from the perspective of the form object upon which this method is called. So a nested form can always address its local fields using their "short" (unqualified) names even if the form is actually nested within another form.

local_fields

Returns a list of fields that are immediate children of the current form (i.e., fields that do not belong to a nested form).

local_form NAME [, OBJECT]

Get or set a form that is an immediate child of the current form. That is, it does not belong to a nested form. If the form specified by NAME does not meet these criteria, then undef is returned. In all other respects, this method behaves like the form method.

Note that NAME should be the name as seen from the perspective of the form object upon which this method is called. So a nested form can always address its local sub-forms using their "short" (unqualified) names even if the parent form itself is actually nested within another form.

name [NAME]

If passed a NAME argument, then the "name" HTML attribute is set to NAME.

If called without any arguments, and if the "name" HTML attribute is empty, then the "name" HTML attribute is set to the form_name.

Returns the value of the "name" HTML attribute.

object_from_form OBJECT | CLASS | PARAMS

Returns an object built based on the contents of the form.

For each field name(), if the object has a method with the same name, then the internal_value() of the field is passed to the object method of that name. The actual code is almost as simple as this:

  foreach my $field ($self->fields)
  {
    my $name = $field->local_name;

    if($object->can($name))
    {
      $object->$name($field->internal_value);
    }
  }
    

The only wrinkle is the case where a sub-form and a parent form have fields with the same local_name. In that case, the field "closer" to the "root" form (in terms of the parent/child relationship tree) takes precedence. For example, consider the following fields:

    name
    vendor.name
    vendor.country.name
    

The local_name for all of these fields is "name", but object_from_form will pass the value of the "name" field to the "name()" method of the object. See the nested forms section of the documentation for more information on nested forms.

In order to return an object based on a form, object_from_form needs an object. If passed an OBJECT argument, then that's the object that's used. If passed a CLASS name, then a new object is constructed by calling new() on that class. OBJECT or CLASS may alternately be passed as a name/value pair in PARAMS.

Use this method as a "helper" when writing your own methods such as "person_from_form()", as described in the example in the overview. object_from_form() should be called in the code for subclasses of Rose::HTML::Form, but never by an end-user of such classes.

The convention for naming such methods is "foo_from_form", where "foo" is a (lowercase, underscore-separated, please) description of the object constructed based on the values in the form's fields.

The field names may not match up exactly with the object method names. In such cases, you can use object_from_form() to handle all the fields that do match up with method names, and then handle the others manually. Example:

  sub person_from_form
  {
    my($self) = shift;

    my $person = $self->object_from_form(class => 'Person');

    $person->alt_phone($self->field('phone2')->internal_value);
    ...
    return $person;
  }
    

It is the caller's responsibility to ensure that the object class ("Person" in the example above) is loaded prior to calling this method.

param NAME [, VALUE]

Get or set the value of a named parameter. If just NAME is passed, then the value of the parameter of that name is returned. If VALUE is also passed, then the parameter value is set and then returned.

If a parameter has multiple values, the values are returned as a reference to an array in scalar context, or as a list in list context. Multiple values are set by passing a VALUE that is a reference to an array of scalars.

Failure to pass at least a NAME argument results in a fatal error.

params [PARAMS]

Get or set all parameters at once.

PARAMS can be a reference to a hash or a list of name/value pairs. If a parameter has multiple values, those values should be provided in the form of a reference to an array of scalar values. If the list of name/value pairs has an odd number of items, a fatal error occurs.

If PARAMS is a reference to a hash, then it is accepted as-is. That is, no copying of values is done; the actual hash references is stored. If PARAMS is a list of name/value pairs, then a deep copy is made during assignment.

Regardless of the arguments, this method returns the complete set of parameters in the form of a hash (in list context) or a reference to a hash (in scalar context).

In scalar context, the hash reference returned is a reference to the actual hash used to store parameter names and values in the object. It should be treated as read-only.

The hash returned in list context is a deep copy of the actual hash used to store parameter names and values in the object. It may be treated as read/write.

params_exist

Returns true if any parameters exist, false otherwise.

param_exists NAME

Returns true if a parameter named NAME exists, false otherwise.

param_exists_for_field [ NAME | FIELD ]

Returns true if a param exists that addresses the field named NAME or the Rose::HTML::Form::Field-derived object FIELD, false otherwise.

This method is useful for determining if any query parameters exist that address a compound field. For example, a compound field named "a.b.c.d" could be addressed by any one of the following query parameters: "a", "a.b", "a.b.c", or "a.b.c.d". This method also works with fields inside sub-form. Examples:

    $form = Rose::HTML::Form->new;
    $form->add_field(when => { type => 'datetime split mdyhms' });

    $form->params({ 'when.date' => '2004-01-02' });

    $form->param_exists_for_field('when');            # true
    $form->param_exists_for_field('when.date');       # true
    $form->param_exists_for_field('when.date.month'); # true
    $form->param_exists_for_field('when.time.hour');  # false

    $subform = Rose::HTML::Form->new;
    $subform->add_field(subwhen => { type => 'datetime split mdyhms' });
    $form->add_form(subform => $subform);

    $form->params({ 'subform.subwhen.date' => '2004-01-02' });

    $form->param_exists_for_field('subform.subwhen');            # true
    $form->param_exists_for_field('subform.subwhen.date');       # true
    $form->param_exists_for_field('subform.subwhen.date.month'); # true
    $form->param_exists_for_field('subform.subwhen.time.hour');  # false

    $form->param_exists_for_field('when');            # false
    $form->param_exists_for_field('when.date');       # false
    $form->param_exists_for_field('when.date.month'); # false
    $form->param_exists_for_field('when.time.hour');  # false
    

params_from_apache APR

Set params by extracting parameter names and values from an apache request object. Calling this method entirely replaces the previous params.

If running under mod_perl 1.x, the APR argument may be:

params_from_cgi CGI

Set params by extracting parameter names and values from a CGI object. Calling this method entirely replaces the previous params. The CGI argument must be either a CGI object or must have a "param()" method that behaves in the following way:

param_value_exists NAME, VALUE

Determines if a parameter of a particular name exists and has a particular value. This method returns true if the parameter named NAME exists and also has a value that is equal to (string comparison) VALUE. Otherwise, it returns false.

A fatal error occurs unless both NAME and VALUE arguments are passed.

parent_form [FORM]

Get or set the parent form, if any. The reference to the parent form is "weakened" using Scalar::Util::weaken() in order to avoid memory leaks caused by circular references.

prepare [PARAMS]

Prepare the form by calling the prepare method on each field, passing all arguments. This same method is also called for each sub-form, passing all arguments plus the "form_only" parameter with a true value.

PARAMS are name/value pairs. Valid parameters are:

query_string

Returns a URI-escaped (but not HTML-escaped) query string that corresponds to the current state of the form. If coalesce_query_string_params() is true (which is the default), then compound fields are represented by a single query parameter. Otherwise, the subfields of each compound field appear as separate query parameters.

rank [INT]

Get or set the form's rank. This value can be used for any purpose that suits you, but by default it's used by the compare_forms method to sort sub-forms.

recursive_init_fields [BOOL]

Get or set a boolean value indicating the default value of the <recursive> parameter to the init_fields method. This attribute, in turn, defaults to the value returned by the default_recursive_init_fields class method.

repeatable_form NAME [, OBJECT]

Get or set the repeatable sub-form named NAME. If just NAME is passed, the specified repeatable sub-form object is returned. If no such repeatable sub-form exists, undef is returnend.

If both NAME and OBJECT are passed, a new repeatable sub-form is added under NAME.

NAME is a fully-qualified sub-form name. Components of the hierarchy are separated by dots ("."). OBJECT must be an object that inherits from Rose::HTML::Form::Repeatable.

repeatable_forms [FORMS]

If FORMS are passed, this method deletes all existing repeatable forms and then calls add_repeatable_forms, passing all arguments.

The return value is an ordered list of this form's repeatable sub-form objects (if any) in list context, or a reference to this list in scalar context. The order of the forms matches the order of the form names returned by the form_names method.

See the nested forms section to learn more about nested forms, and the Rose::HTML::Form::Repeatable documentation to learn more about repeatable forms.

reset

Call reset() on each field object and set error() to undef.

reset_fields

Call reset() on each field object.

self_uri

Returns a Rose::URI object corresponding to the current state of the form. If uri_base() is set, then it is included in front of what would otherwise be the start of the URI (i.e., the value of the form's "action" HTML attribute).

start_html

Returns the HTML that will begin the form tag.

start_xhtml

Returns the XHTML that will begin the form tag.

start_multipart_html

Sets the "enctype" HTML attribute to "multipart/form-data", then returns the HTML that will begin the form tag.

start_multipart_xhtml

Sets the "enctype" HTML attribute to "multipart/form-data", then returns the XHTML that will begin the form tag.

trim_xy_params [BOOL]

Get or set a boolean value that determines whether or not params that end in ".x" or ".y" have that suffix trimmed off. This is useful for handling query parameters created by some web browsers in response to clicks on image buttons and other image-based elements. Setting this attribute will propagate the value down to all sub-forms.

The default value is the value returned by the default_trim_xy_params class method.

uri_base [STRING]

Get or set the URI of the form, minus the value of the "action" HTML attribute. Although the form action can be a relative URI, I suggest that it be an absolute path at the very least, leaving the uri_base() to be the initial part of the full URI returned by self_uri(). Example:

    $form->action('/foo/bar');
    $form->uri_base('http://www.foo.com');

    # http://www.foo.com/foo/bar
    $uri = $form->self_uri;
    

uri_separator [CHAR]

Get or set the character used to separate parameter name/value pairs in the return value of query_string() (which is in turn used to construct the return value of self_uri()). The default is "&".

validate [PARAMS]

Validate the form by calling validate() on each field and validate() on each each sub-form. If any field or form returns false from its "validate()" method call, then this method returns false. Otherwise, it returns true.

If this method is about to return false and the error attribute of this form is not set, then it is set to a generic error message.

PARAMS are name/value pairs. Valid parameters are:

    $form = Rose::HTML::Form->new;
    $form->add_field(foo => { type => 'text' });

    $subform = Rose::HTML::Form->new;
    $subform->add_field(bar => { type => 'text' });

    $form->add_form(sub => $subform);

    # Call validate() on fields "foo" and "sub.bar" and
    # call validate(form_only => 1) on the sub-form "sub"
    $form->validate;

    # Same as above
    $form->validate(cascade => 1);

    # Call validate() on fields "foo" and "sub.bar"
    $form->validate(cascade => 0);

    # Call validate(form_only => 1) on the sub-form "sub"
    $form->validate(form_only => 1);

    # Don't call validate() on any fields or sub-forms
    $form->validate(form_only => 1, cascade => 0);

validate_field_html_attrs [BOOL]

Get or set a boolean flag that indicates whether or not the fields of this form will validate their HTML attributes. If a BOOL argument is passed, then it is passed as the argument to a call to validate_html_attrs() on each field. In either case, the current value of this flag is returned.

was_submitted

Returns true id params exist for any field, false otherwise.

xhtml_hidden_fields

Returns the XHTML serialization of the fields returned by hidden_fields(), joined by newlines.

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