A Better Params Trap

So with great pleasure I present OO::Form 0.01-alpha-experimental. (which has been kicking around for a week fews, but I finally added some POD)

A Curiosity

My Favorite Feature

OO::Form – pod2html

• NAME
• SYNOPSIS
• DESCRIPTION
• USAGE
• Field Profile
• 2 Error Handling and Validation
• METHODS

NAME

OO::Form – an object oriented framework for building, displaying, and processing forms.

SYNOPSIS

package MyApp::AddWidgetForm;

use base ‘OO::Form’;

  our $FIELDPROFILE = {
          fields  => 
                  [qw(name widgetstyle note expirationdate) ],
          types   => { 
                  widgetstyle     => 'select', 
                  note             => 'textarea', 
                  expirationdate  => 'date'
          },
          options  => {
                  widgetstyle     => [qw(blue green chrome)]
          },
          required  => [qw(name widgetstyle)]
  };

  sub new {
          my $class = shift;
          my $self = $class->SUPER::new(@);
          $self->addfields($FIELDPROFILE);
          $self->submitfield('addwidget');
          return $self;
  }

….

  (else where in your application)

  my $form = MyApp::AddWidgetForm->new({query => $query, ...});
  if ($form->issubmitted and $form->validates ) {
          MyAdd::Widget->newwidget({
                  name => $form->name->value,
                  widgetstyle => $form->widgetstyle->value,
                  note => $form->note->value,
                  expiration-date => $form->expirationdate->value

          });
          displaywidgetaddedconfirmation();
  }
  else {
          # form hasn't been submitted, or we encountered an error
          displaypage($template, { form => $form } );
  }

  (mean while, in a nearby template)

  [% IF form.errors %]
  <ul class="errors">
    [% FOREACH e = form.errors %]<li>[% e %]</li>[% END %]
  </ul>
  [% END %]

  Name:       [% form.name.html(size => '40') %]<br />
  Style:      [% form.widgetstyle.html(default => 'blue') %] <br />
  Expiration: [% form.expirationdate.html %]
  Note: <br />
  [% form.note.html(rows =>4, cols=>50) %]<br />
  <input type="submit" name="[%form.submitfield%]" value="Add Widget" />               


...,

DESCRIPTION

OO::Form represents an HTML form as a collection of OO::Form::Field objects, a state (is submitted), and some basic error handling. It was inspired by CGI::FormBuilder, and by the difficulty I had integrating CGI::FormBuilder into my application. The OO::Form was designed to be used in conjuction with the Template Toolkit, and Class::DBI though they aren’t tightly coupled.

The most straightforward way to use OO::Form is to create your own subclass of OO::Form for each form in your application. (though create and update pages can usually re-use the same form object, and for very simple forms, it is probably less useful)

Then pass a ‘fields profile’ to the OO::Form->addfields() method which is a factory method for creating object of type OO::Form::Field and its varied subclasses.

• fields
  
An arrayref of the names of fields to instantiate. Names must be unique, and they must not have the same name as any method of your form object (as they will be accessed by calling $form->$fieldname())
• types
  
A hashref of names mapped to their field types. Any field which is not given a type will be a generic field object, and will be drawn as a text field if their html() method is called.

OO::Form::Field-factory()> will be called for each field, and be passed its type. The default factory() method tries to instantiate an object of type OO::Form::Field::$type. You can subclass OO::Form::Field to provide a whole set of new field types, or new behaviour for old field types. Additionally if anyone has suggestions for a smarter factory method, I’m interested.

Current types are the basic HTML fields: text, password, checkbox, textarea, select

Also the composite field type: date (represented as 3 pulldowns) is available.

See OO::Form::Field for more detail

• options
  
For field types with options (selects aka pulldown menus, and radio/checkbox groups) values can be passed with the options field.

A hashref of field names pointing to either an arrayref of options (when you want value and text to be the same) or a hashref of value to text mappings.

• values
  
A hashref of field name to value mappings. If you want your field to start preconfigured with certain values, pass in a values hash.

If your values hashref contains a subclass of Class::Accessor (like a Class::DBI object) then the objects get() method will be called, allowing forms to be rapidly populated from a database.

• required
  
An arrayref of names of the required fields. OO::Form-validate> will return false (and populate an errors array) if any required fields are missing

2 Error Handling and Validation

There are hooks for a future implementation of a full blown validation framework (probably using Data::FormValidator).

In the meantime OO::Form checks that required fields have been filled in, and that none of the various fields through their own error.

Calling the instance method validate() (validates() is a synonym), returns true or false depending on whether there are any error conditions in the current form. It also populates and errors array, useful for re-displaying the form page with a list of errors.

A useful idiom for calling validates in demonstrated in the synops.

Besides the form wide errors array (accessible at $form->errors() ), each field can have their own error (though only one) accessible at $form->widgetstyle->error(), this is useful for re-displaying a form, with error messages inlined.

• new($params)
  
Construct a new form. Often you’ll want to override this with your own constructor. The default constructor looks for (and will supply defaults if it doesn’t find): query'',submitfield”, “time_zone”.

* query is a CGI.pm object, or something else which masquerades as one

* submitfield is the name of the button that submits this form (checked by issubmitted.

* time_zone is used by OO::Form::Field::date to do intelligent localization of date/time values

Additionally in the future OO::Form::new should take a locale.

• addfields($fieldprofile)
  
Take a field profile (as discussed in the previous section) an populate a form.
• field(...)
  
A field accessor. Can take a hashref (or field object) and passes it to OO::Form::Field-factory()>, and attach the results to the current form.

Otherwise assume a string was passed in, and return the field with that name. (AUTOLOAD will call field($field_name) for unknown methods)