Rose::HTML::Form 0.53

Rose::HTML::Form is a HTML form base class.

SYNOPSIS

package PersonForm;

use Rose::HTML::Form;
our @ISA = qw(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(name)->internal_value ne John Doe &&
$self->field(phone)->internal_value =~ /^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(phone)->internal_value);

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);
}
...

Rose::HTML::Form is more than just an object representation of the

HTML tag. It is meant to be a base class for custom form classes that can be initialized with and return "rich" values such as objects, or collections of objects.

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.