view release on metacpan or  search on metacpan

lib/Form/Sensible/Overview.pod  view on Meta::CPAN

=head1 NAME

Form::Sensible::Overview - Getting started with Form::Sensible

=head1 INTRODUCTION

Form::Sensible is a different way of handling form based user input.
Many people have heard of MVC.  The separation of programming concerns
into that of the data model, the view, and the controller is by
now familiar territory.  Many implementations are available and some
of them are really good.  Unfortunately, more often than not the user
input portion of the View is neglected.  Handling user interaction
is pushed into the controller where direct access to the methods
of input occur.

Form::Sensible is an attempt to abstract user input in a way that is similar
to the abstraction provided for the presentation portion of the view. As such,
Form::Sensible takes a different approach to representing a form. Instead of
defining a form in terms of what your user will see (checkboxes, dropdowns,
text fields, etc.) you define your form in terms of the information you want
to collect from the user.

If you want to have a user select an item from a set of options, you
create a Select field.  If you want a number between 1975 and 2010,
then you create a Number field.  Ultimately, your code just wants
the correct information.  It doesn't matter whether the number is
from a text entry field, or from a dropdown select box.  Likewise
when selecting a preferred item from a number of options, your code
doesn't care whether the selection is presented as a dropdown box
or a set of checkboxes.  (How many times have you been asked to
change a select dropdown to a set of checkboxes or vice-versa?)

Form::Sensible provides a conduit for information to and from the
user.  It is a mechanism for prompting the user with questions, for
collecting the information you need, for ensuring that
the value collected fits your constraints, and for indicating errors
and other important information to the user.

With Form::Sensible, however, the method by which the user is queried
for the information is abstracted from the code that uses the
information.  This allows you to change the details of what
the interface looks like without adjusting your code.  It also allows
you to completely change your interface mechanism without rewriting your
code.  You can, for example, swap out your in-browser HTML based forms with a
desktop-GUI by simply replacing the L<Renderer|Form::Sensible::Renderer>*
(or, more accurately, you will be able to in the not-too-distant future.)

=head1 OVERVIEW

As we mentioned, Form::Sensible abstracts the method of querying the user
from the code that's actually using the data.  Many people will use
L<Form::Sensible> primarily for HTML based forms only and those who do use
it for other things are likely familiar with HTML based form handling so
we will use them as our unfortunate victim, er... example.

When comparing Form::Sensible to HTML forms, there are a few big differences
from what you are probably used to. First off, you are probably used to
defining fields in terms of how they will eventually be shown. You create text
fields, password fields, radio buttons, etc. in a template of some kind. Then
you collect the information in its raw form and boil it down to something
that you can use in your code. Then you write code to perform validation of
your data and then set up a mechanism for reporting any errors to the user. A
number of modules and libraries have been created to make portions of this
easier to deal with HTML generators, Form Validators, etc. But when it comes
down to it, the process is the same just slightly more succinct.

In Form::Sensible you approach it from a different perspective. Fields are
defined in terms of the data they represent. For each field in a form, you
define the constraints and other parameters important to the type of data it
represents. Once this is done, you simply pass the form to a Form renderer and
it takes care of turning it into something presentable for the user.

It is important to note that unlike HTML forms which bind to a particular
action for form processing, forms in Form::Sensible simply provide a way
to bundle a set of fields together.  They are simply a handle for working
with more than one field at once.

Once the user's response to the form is collected, you can easily ensure that
it is valid by triggering form validation.  The easiest method for doing so
is to simply call C<< $form->validate() >>.  This will validate the values
provided by the user against the constraints defined for each field (and the
collection of fields together) and will set up messaging for any errors that
are found.  Then you can choose to represent the form to the user or if
validation succeeded, you can proceed to do whatever is appropriate for
your data.

It is important to note also that Form::Sensible forms are intended to
be queried for their data.  Meaning if you want the value of your
C<year_of_birth> field, you call C<< $form->field('year_of_birth')->value() >>.
This allows your code to be separate from the mechanism of retrieving the
value in the first place.  This makes things significantly easier when
it comes time to port your application to a new user interface method.

=head1 USING IT

Until now we've spoken in very general terms about how you do things
with Form::Sensible.  Now we will actually demonstrate it, starting
with creating a form.

=head2 CREATING AND RENDERING A FORM

You can create Form::Sensible forms using an object-oriented process of
creating a form object, creating field objects, and then adding each field
object to the form object. While useful in certain circumstances, most people
tend to create a form in a static manner. As such, an easier and significantly