lib/Catalyst/Manual/Tutorial/09_AdvancedCRUD/09_FormSensible.pod

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