Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Form::Sensible(3)     User Contributed Perl Documentation    Form::Sensible(3)

NAME
       Form::Sensible -	A sensible way to handle form based user interface

SYNOPSIS
	   use Form::Sensible;

	   my $form = Form::Sensible->create_form( { ... } );

	   my $renderer	= Form::Sensible->get_renderer('HTML', { tt_config => {	INCLUDE_PATH =>	[ '/path/to/templates' ] }});

	   my $output =	$renderer->render($form)->complete;

	   ## Form Validation:

	   my $validation_result = $form->validate();

	   if ($validation_result->is_valid()) {
	       ## do form was valid stuff
	   } else {
	       my $output_with_messages	= $renderer->render($form)->complete;
	   }

DESCRIPTION
       Form::Sensible is a different kind of form library. Form::Sensible is
       not just	another	HTML form creator, or a	form validator,	though it can
       do both.	 Form::Sensible, instead, focuses on what forms	are: a method
       to relay	information to and from	a user interface.

       Form::Sensible forms are	primarily tied to the data they	represent.
       Form::Sensible is not tied to HTML in any way. You could	render
       Form::Sensible forms using any presentation system you like, whether
       that's HTML, console prompts, WxPerl or voice prompts. (* currently
       only an HTML renderer is	provided with Form::Sensible, but work is
       already under way to produce others.)

   FEATURES
       o   Easy	form validation

       o   Ability to easily save created forms	for future use

       o   Define form once, render any	number of ways

       o   Flexible built-in form validator

       o   Easily extended to produce new renderers, field types and
	   validation

       o   HTML	renderer produces sane html that can be	easily styled via CSS

       o   HTML	renderer allows	for custom templates to	control	all aspects of
	   form	rendering.

       o   HTML	output not tied	to any javascript library.

   Form::Sensible form lifecycle
       The Form::Sensible form lifecycle works as follows:

       Phase 1 - Show a	form

       1. Create form object
       2. Create or get	a renderer
       3. Use renderer to render form

       Phase 2 - Validate input

       1. Create form object
       2. Retrieve user	input and place	it into	form
       3. Validate form
       4. If form data is invalid, re-render the form with messages

       One of the most important features of Form::Sensible is that Forms,
       once created, are easily	stored for re-generation later.	A form's
       definition and state are	easily converted to a hashref data structure
       ready for serializing.  Likewise, the data structure can	be used	to
       create a	complete Form::Sensible	form object ready for use. This	makes
       re-use of forms extremely easy and provides for dynamic creation	and
       processing of forms.

EXAMPLES
       Form creation from simple data structure

	   use Form::Sensible;

	   my $form = Form::Sensible->create_form( {
						       name => 'test',
						       fields => [
								    {
								       field_class => 'Text',
								       name => 'username',
								       validation => { regex =>	'^[0-9a-z]*'  }
								    },
								    {
									field_class => 'Text',
									name =>	'password',
									render_hints =>	{
									       'HTML' => {
											   field_type => 'password'
											 }
									       },
								    },
								    {
									field_class => 'Trigger',
									name =>	'submit'
								    }
								 ],
						   } );

       This example creates a form from	a simple hash structure. This example
       creates a simple	(and all too familiar) login form.

       Creating	a form programmatically

	   use Form::Sensible;

	   my $form = Form::Sensible::Form->new(name=>'test');

	   my $username_field =	Form::Sensible::Field::Text->new(
								   name=>'username',
								   validation => { regex => qr/^[0-9a-z]*$/  }
								);

	   $form->add_field($username_field);

	   my $password_field =	Form::Sensible::Field::Text->new(
								   name=>'password',
								   render_hints	=> {
										       'HTML' => {
												   field_type => 'password'
												 },
										   },
								);
	   $form->add_field($password_field);

	   my $submit_button = Form::Sensible::Field::Trigger->new( name => 'submit' );

	   $form->add_field($submit_button);

       This example creates the	exact same form	as the first example. This
       time, however, it is done by creating each field	object individually,
       and then	adding each in turn to the form.

       Both of these methods will produce the exact same results when
       rendered.

       Form validation

	   ## set_values takes a hash of name->value pairs
	   $form->set_values($c->req->params);

	   my $validation_result = $form->validate();

	   if ($validation_result->is_valid) {

	       #... do stuff if	form submission	is ok.

	   } else {

	       my $renderer = Form::Sensible->get_renderer('HTML');
	       my $output = $renderer->render($form)->complete;
	   }

       Here we fill in the values provided to us via "$c->req->params" and
       then run	validation on the form.	 Validation follows the	rules provided
       in the validation definitions for each field.  Whole-form validation is
       can also	be done	if provided.  When validation is run using this
       process,	the messages are automatically available during	rendering.

METHODS
       All methods in the Form::Sensible package are class methods. Note that
       by "use"ing the Form::Sensible module, the Form::Sensible::Form and
       Form::Sensible::Field::*	classes	are also "use"d.

       "create_form($formhash)"
	       This method creates a form from the given hash structure. The
	       hash structure accepts all the same attributes that
	       Form::Sensible::Form's new method accepts. Field	definitions
	       are provided as an array	under the "field" key.	Returns	the
	       created Form::Sensible::Form object.

       "get_renderer($render_class, $options)"
	       Creates a renderer of the given class using the $options
	       provided. The format of the class name follows the convention
	       of a bare name being appended to	"Form::Sensible::Renderer::".
	       In other	words if you call
	       "<Form::Sensible-"get_renderer('HTML', {	'foo' => 'bar' })>>
	       Form::Sensible will ensure the Form::Sensible::Renderer::HTML
	       class is	loaded and will	create an object by passing the
	       hashref provided	to the "new" method. If	you wish to provide a
	       class outside of	the "Form::Sensible::Renderer::" namespace,
	       prepend the string with a "+". For example, to load the class
	       "MyRenderer::ProprietaryUI" you would pass
	       '+MyRenderer::ProprietaryUI'.

       "get_validator($validator_class,	$options)"
	       Creates a validator of the given	class using the	$options
	       provided. Follows the same convention for class name passing as
	       the get_renderer	method.

AUTHORS
       Jay Kuri	- <jayk@cpan.org>

       Luke Saunders - <luke.saunders@gmail.com>

       Devin Austin - <dhoss@cpan.org>

       Alan Rafagudinov	- <alan.rafagudinov@ionzero.com>

       Andrew Moore - <amoore@cpan.org>

SPONSORED BY
       Ionzero LLC. <http://ionzero.com/>

SEE ALSO
       Form::Sensible Wiki:
       <http://wiki.catalyzed.org/cpan-modules/form-sensible>

       Form::Sensible Discussion:
       <http://groups.google.com/group/formsensible>

       Form::Sensible Github: <https://github.com/jayk/Form-Sensible>

       Form::Sensible

LICENSE
       Copyright 2009 by Jay Kuri <jayk@cpan.org>

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 156:
	   =over should	be: '=over' or '=over positive_number'

perl v5.32.0			  2012-02-05		     Form::Sensible(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | METHODS | AUTHORS | SPONSORED BY | SEE ALSO | LICENSE | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Form::Sensible&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help