[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / Tutorial / 09_AdvancedCRUD / 09_FormSensible.pod

=head1 NAME

Catalyst::Manual::Tutorial::09_AdvancedCRUD::09_FormSensible - Catalyst Tutorial - Chapter 9: Advanced CRUD - FormSensible


=head1 OVERVIEW

This is B<Chapter 9 of 10> for the Catalyst tutorial.

L<Tutorial Overview|Catalyst::Manual::Tutorial>

=over 4

=item 1

L<Introduction|Catalyst::Manual::Tutorial::01_Intro>

=item 2

L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>

=item 3

L<More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>

=item 4

L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>

=item 5

L<Authentication|Catalyst::Manual::Tutorial::05_Authentication>

=item 6

L<Authorization|Catalyst::Manual::Tutorial::06_Authorization>

=item 7

L<Debugging|Catalyst::Manual::Tutorial::07_Debugging>

=item 8

L<Testing|Catalyst::Manual::Tutorial::08_Testing>

=item 9

B<09_Advanced CRUD::09_FormHandler>

=item 10

L<Appendices|Catalyst::Manual::Tutorial::10_Appendices>

=back


=head1 DESCRIPTION

This part of the tutorial explores managing your CRUD operations with L<Form::Sensible> and L<Form::Sensible::Reflector::DBIC>. 
As of this writing, Form::Sensible is at version 0.20002 and Form::Sensible::Reflector::DBIC is at 0.0341.

See 
L<Catalyst::Manual::Tutorial::09_AdvancedCRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
for additional form management options other than L<Form::Sensible>.

=head1 Installing Form::Sensible

The easiest way to install L<Form::Sensible> is via CPAN:

    cpan Form::Sensible

or just

    cpan Form::Sensible::Reflector::DBIC

if you're using the reflector.

Also, add:

    requires 'Form::Sensible';

or

    requires 'Form::Sensible::Reflector::DBIC';

to your app's C<Makefile.PL>.

=head1 Form Creation

Here we split a bit:

L<Form::Sensible Form Creation>

L<Form::Sensible::Reflector::DBIC Form Creation>

=head1 Form::Sensible Form Creation

From the documentation, we can see that you are able to create forms via simple data structures or programmatically.
Typically, it's easiest to the do former, so we'll use that example here:

    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'
                                                             }
                                                          ],
                                            } );

=head1 Form::Sensible::Reflector::DBIC Form Creation

A reflector literally reflects off of a data source, whether it's configuration files, XML files, or in this case, a L<DBIx::Class> schema object.

The long and the short of this is that Form::Sensible::Reflector::DBIC searches through your schema and creates the appropriate form field types from the data types your columns are defined as.

All you need is your schema object from your model:

    my $output;
    my $captcha   = $c->captcha_string;  # from Plugin::CAPTCHA
    my $reflector = Form::Sensible::Reflector::DBIC->new;
    my $form      = $reflector->reflect_from( $c->model('Database::Quote'),
        { form => { name => 'uploads' } } );
    my $captcha_field = Form::Sensible::Field::Text->new(
        name          => 'captcha',
        default_value => $captcha,
        required      => 1
    );
    my $submit_button = Form::Sensible::Field::Trigger->new( name => 'add' );
    my $renderer = Form::Sensible->get_renderer('HTML');

    $form->add_field($captcha_field);
    $form->add_field($submit_button);

    if ( $c->req->param('add') ) {

        $c->forward(qw/Controller::API::Quote create/);

    }

    my $output = $renderer->render($form)->complete( '/quotes/new', 'POST' );
    $c->stash( form => $output );
Commit	Line	Data
27b397a3	1	=head1 NAME
	2
	3	Catalyst::Manual::Tutorial::09_AdvancedCRUD::09_FormSensible - Catalyst Tutorial - Chapter 9: Advanced CRUD - FormSensible
	4
	5
	6	=head1 OVERVIEW
	7
	8	This is B<Chapter 9 of 10> for the Catalyst tutorial.
	9
	10	L<Tutorial Overview\|Catalyst::Manual::Tutorial>
	11
	12	=over 4
	13
	14	=item 1
	15
	16	L<Introduction\|Catalyst::Manual::Tutorial::01_Intro>
	17
	18	=item 2
	19
	20	L<Catalyst Basics\|Catalyst::Manual::Tutorial::02_CatalystBasics>
	21
	22	=item 3
	23
	24	L<More Catalyst Basics\|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>
	25
	26	=item 4
	27
	28	L<Basic CRUD\|Catalyst::Manual::Tutorial::04_BasicCRUD>
	29
	30	=item 5
	31
	32	L<Authentication\|Catalyst::Manual::Tutorial::05_Authentication>
	33
	34	=item 6
	35
	36	L<Authorization\|Catalyst::Manual::Tutorial::06_Authorization>
	37
	38	=item 7
	39
	40	L<Debugging\|Catalyst::Manual::Tutorial::07_Debugging>
	41
	42	=item 8
	43
	44	L<Testing\|Catalyst::Manual::Tutorial::08_Testing>
	45
	46	=item 9
	47
	48	B<09_Advanced CRUD::09_FormHandler>
	49
	50	=item 10
	51
	52	L<Appendices\|Catalyst::Manual::Tutorial::10_Appendices>
	53
	54	=back
	55
	56
2354efc7	57	=head1 DESCRIPTION
	58
	59	This part of the tutorial explores managing your CRUD operations with L<Form::Sensible> and L<Form::Sensible::Reflector::DBIC>.
	60	As of this writing, Form::Sensible is at version 0.20002 and Form::Sensible::Reflector::DBIC is at 0.0341.
	61
	62	See
	63	L<Catalyst::Manual::Tutorial::09_AdvancedCRUD\|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
	64	for additional form management options other than L<Form::Sensible>.
	65
	66	=head1 Installing Form::Sensible
	67
	68	The easiest way to install L<Form::Sensible> is via CPAN:
	69
	70	cpan Form::Sensible
	71
	72	or just
	73
	74	cpan Form::Sensible::Reflector::DBIC
	75
	76	if you're using the reflector.
	77
	78	Also, add:
	79
	80	requires 'Form::Sensible';
	81
	82	or
	83
	84	requires 'Form::Sensible::Reflector::DBIC';
	85
	86	to your app's C<Makefile.PL>.
	87
	88	=head1 Form Creation
	89
	90	Here we split a bit:
	91
	92	L<Form::Sensible Form Creation>
	93
	94	L<Form::Sensible::Reflector::DBIC Form Creation>
	95
	96	=head1 Form::Sensible Form Creation
	97
	98	From the documentation, we can see that you are able to create forms via simple data structures or programmatically.
	99	Typically, it's easiest to the do former, so we'll use that example here:
	100
	101	use Form::Sensible;
	102
	103	my $form = Form::Sensible->create_form( {
	104	name => 'test',
	105	fields => [
	106	{
	107	field_class => 'Text',
	108	name => 'username',
	109	validation => { regex => '^[0-9a-z]*' }
	110	},
	111	{
	112	field_class => 'Text',
	113	name => 'password',
	114	render_hints => {
	115	'HTML' => {
	116	field_type => 'password'
	117	}
	118	},
	119	},
	120	{
121	field_class => 'Trigger',
122	name => 'submit'
123	}
124	],
125	} );
126
127	=head1 Form::Sensible::Reflector::DBIC Form Creation
128
129	A reflector literally reflects off of a data source, whether it's configuration files, XML files, or in this case, a L<DBIx::Class> schema object.
130
131	The long and the short of this is that Form::Sensible::Reflector::DBIC searches through your schema and creates the appropriate form field types from the data types your columns are defined as.
132
133	All you need is your schema object from your model:
134
135	my $output;
136	my $captcha = $c->captcha_string; # from Plugin::CAPTCHA
137	my $reflector = Form::Sensible::Reflector::DBIC->new;
138	my $form = $reflector->reflect_from( $c->model('Database::Quote'),
139	{ form => { name => 'uploads' } } );
140	my $captcha_field = Form::Sensible::Field::Text->new(
141	name => 'captcha',
142	default_value => $captcha,
143	required => 1
144	);
145	my $submit_button = Form::Sensible::Field::Trigger->new( name => 'add' );
146	my $renderer = Form::Sensible->get_renderer('HTML');
147
148	$form->add_field($captcha_field);
149	$form->add_field($submit_button);
150
151	if ( $c->req->param('add') ) {
152
153	$c->forward(qw/Controller::API::Quote create/);
154
155	}
156
157	my $output = $renderer->render($form)->complete( '/quotes/new', 'POST' );
158	$c->stash( form => $output );