lib/Catalyst/Manual/Tutorial/AdvancedCRUD/FormFu.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::Tutorial::AdvancedCRUD::FormFu - Catalyst Tutorial - Part 9: Advanced CRUD - FormFu
   4
   5
   6 NOTE:  This part of the tutorial is in progress and will be ready soon.
   7
   8 =head1 OVERVIEW
   9
  10 This is B<Part 9 of 10> for the Catalyst tutorial.
  11
  12 L<Tutorial Overview|Catalyst::Manual::Tutorial>
  13
  14 =over 4
  15
  16 =item 1
  17
  18 L<Introduction|Catalyst::Manual::Tutorial::Intro>
  19
  20 =item 2
  21
  22 L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
  23
  24 =item 3
  25
  26 L<More Catalyst Basics|Catalyst::Manual::Tutorial::MoreCatalystBasics>
  27
  28 =item 4
  29
  30 L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
  31
  32 =item 5
  33
  34 L<Authentication|Catalyst::Manual::Tutorial::Authentication>
  35
  36 =item 6
  37
  38 L<Authorization|Catalyst::Manual::Tutorial::Authorization>
  39
  40 =item 7
  41
  42 L<Debugging|Catalyst::Manual::Tutorial::Debugging>
  43
  44 =item 8
  45
  46 L<Testing|Catalyst::Manual::Tutorial::Testing>
  47
  48 =item 9
  49
  50 B<Advanced CRUD>
  51
  52 =item 10
  53
  54 L<Appendices|Catalyst::Manual::Tutorial::Appendices>
  55
  56 =back
  57
  58
  59 =head1 DESCRIPTION
  60
  61 This portion of the tutorial explores L<HTML::FormFu|HTML::FormFu> and
  62 how it can be used to manage forms, perform validation of form input,
  63 as well as save and restore data to/from the database.
  64
  65 See
  66 L<Catalyst::Manual::Tutorial::AdvancedCRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
  67 for additional form management options other than
  68 L<HTML::FormFu|HTML::FormFu>.
  69
  70
  71 =head1 Install C<HTML::FormFu>
  72
  73 If you are following along in Ubuntu, it turns out that C<HTML::FormFu>
  74 is not yet available as a package at the time this was written.  To
  75 install it with a combination of C<apt-get> packages and traditional
  76 CPAN modules, first use C<apt-get> to install most of the modules
  77 required by C<HTML::FormFu>:
  78
  79     sudo apt-get install libtest-nowarnings-perl libdatetime-format-builder-perl \
  80     libdatetime-format-strptime-perl libdatetime-locale-perl \
  81     libhtml-tokeparser-simple-perl liblist-moreutils-perl \
  82     libregexp-copy-perl libregexp-common-perl libyaml-syck-perl libparams-util-perl
  83
  84 Then use the following command to install directly from CPAN the modules
  85 that aren't available as Ubuntu/Debian packages via C<apt-get>:
  86
  87     sudo cpan File::ShareDir Task::Weaken Config::Any HTML::FormFu \
  88     Catalyst::Controller::HTML::FormFu
  89
  90
  91 =head1 C<HTML::FormFu> FORM CREATION
  92
  93 This section looks at how L<HTML::FormFu|HTML::FormFu> can be used to
  94 add additional functionality to the manually created form from Part 4.
  95
  96
  97 =head2 Inherit From C<Catalyst::Controller::HTML::FormFu>
  98
  99 First, change your C<lib/MyApp/Controller/Books.pm> to inherit from
 100 L<Catalyst::Controller::HTML::FormFu|Catalyst::Controller::HTML::FormFu>
 101 by changing the C<use base> line from the default of:
 102
 103     use base 'Catalyst::Controller';
 104
 105 to use the FormFu base controller class:
 106
 107     use base 'Catalyst::Controller::HTML::FormFu';
 108
 109
 110 =head2 Add Action to Display and Save the Form
 111
 112 Open C<lib/MyApp/Controller/Books.pm> in your editor and add the
 113 following method:
 114
 115     =head2 fu_form_create
 116
 117     Build an HTML::FormFu form for book creation and updates
 118
 119     =cut
 120
 121     sub fu_form_create :Local :FormConfig {
 122         my ($self, $c) = @_;
 123
 124         # Get the form that the :FormConfig attribute saved in the stash
 125         my $form = $c->stash->{form};
 126
 127         # Check if the form as been submitted (vs. displaying the initial
 128         # form) and if the data based validation.  "submitted_and_valid"
 129         # is shorthand for "$form->submitted && !$form->has_errors"
 130         if ($form->submitted_and_valid) {
 131             # Create a new book
 132             my $book = $c->model('DB::Books')->new_result({});
 133             # Save the form data for the book
 134             $form->save_to_model($book);
 135             # Set a status message for the user
 136             $c->flash->{status_msg} = 'Book created';
 137             # Return to the books list
 138             $c->response->redirect($c->uri_for('list'));
 139             $c->detach;
 140         }
 141         # Set the template
 142         $c->stash->{template} = 'books/fu_form_create.tt2';
 143     }
 144
 145
 146 =head2 Create a Form Config File
 147
 148 Although C<HTML::FormFu> supports any configuration file handled by
 149 L<Config::Any|Config::Any>, most people tend to use YAML.  First
 150 create a directory to hold your form configuration files:
 151
 152     mkdir -p root/forms/books
 153
 154 Then create the file C<root/forms/books/fu_form_create.yml> and enter the
 155 following text:
 156
 157     ---
 158     indicator: submit
 159     elements:
 160         - type: Text
 161           name: title
 162           label: Title
 163           attributes:
 164             title: Enter a book title here
 165         - type: Text
 166           name: rating
 167           label: Rating
 168           attributes:
 169             title: Enter a rating between 1 and 5 here
 170         - type: Submit
 171           name: submit
 172           value: Submit
 173
 174
 175 =head2 Update the CSS
 176
 177 Edit C<root/src/ttsite.css> and add the following lines to the bottom of
 178 the file:
 179
 180     label {
 181         display: block;
 182     }
 183     .submit {
 184         display: block;
 185     }
 186     .error_messages {
 187         color: [% site.col.error %];
 188     }
 189
 190 These changes will display form elements vertically and also show error
 191 messages in red.  Note that we are pulling the color scheme settings
 192 from the C<root/lib/config/col> file that was created by the TTSite
 193 helper.  This allows us to change the color used by various error styles
 194 in the CSS from a single location.
 195
 196
 197 =head2 Create a Template Page To Display The Form
 198
 199 Open C<root/src/books/fu_form_create.tt2> in your editor and enter the following:
 200
 201     [% META title = 'Create/Update Book' %]
 202
 203     [%# Render the HTML::FormFu Form %]
 204     [% form %]
 205
 206     <p><a href="[% Catalyst.uri_for('list') %]">Return to book list</a></p>
 207
 208
 209 =head2 Add Links for Create and Update via C<HTML::FormFu>
 210
 211 Open C<root/src/books/list.tt2> in your editor and add the following to
 212 the bottom of the existing file:
 213
 214     <p>
 215       HTML::FormFu:
 216       <a href="[% Catalyst.uri_for('fu_form_create') %]">Create</a>
 217     </p>
 218
 219
 220 =head2 Test The <HTML::Widget> Create Form
 221
 222 Press C<Ctrl-C> to kill the previous server instance (if it's still
 223 running) and restart it:
 224
 225     $ script/myapp_server.pl
 226
 227 Login as C<test01>.  Once at the Book List page, click the HTML::FormFu
 228 "Create" link to display for form produced by C<make_book_widget>.  Fill
 229 out the form with the following values: Title = "Internetworking with
 230 TCP/IP Vol. II", Rating = "4", and Author = "Comer".  Click Submit, and
 231 you will be returned to the Book List page with a "Book created" status
 232 message displayed.
 233
 234 Also note that this implementation allows you to can create books with
 235 bogus information.  Although we have constrained the authors with the
 236 drop-down list, there are no restrictions on items such as the length of
 237 the title (for example, you can create a one-letter title) and value for
 238 the rating (you can use any number you want, and even non-numeric values
 239 with SQLite).  The next section will address this concern.
 240
 241 B<Note:> Depending on the database you are using and how you established
 242 the columns in your tables, the database could obviously provide various
 243 levels of "type enforcement" on your data.  The key point being made in
 244 the previous paragraph is that the I<web application> itself is not
 245 performing any validation.
 246
 247
 248 =head1 C<HTML::FormFu> VALIDATION AND FILTERING
 249
 250 Although the use of L<HTML::FormFu|HTML::FormFu> in the previous section
 251 did provide an automated mechanism to build the form, the real power of
 252 this module stems from functionality that can automatically validate and
 253 filter the user input.  Validation uses constraints to be sure that
 254 users input appropriate data (for example, that the email field of a
 255 form contains a valid email address).  Filtering can be used to remove
 256 extraneous whitespace from fields or to escape meta-characters in user
 257 input.
 258
 259 =head2 Add Constraints
 260
 261
 262 Open C<root/forms/books/fu_form_create.yml> in your editor and update it
 263 to match:
 264
 265     ---
 266     indicator: submit
 267     elements:
 268         - type: Text
 269           name: title
 270           label: Title
 271           attributes:
 272             title: Enter a book title here
 273           constraints:
 274             - Required
 275             - type: Length
 276               min: 2
 277               max: 30
 278               message: Length must be between 2 and 30 characters
 279         - type: Text
 280           name: rating
 281           label: Rating
 282           attributes:
 283             title: Enter a rating between 1 and 5 here
 284           constraints:
 285             - Required
 286             - Integer
 287         - type: Submit
 288           name: submit
 289           value: Submit
 290     constraints:
 291         - SingleValue
 292
 293 ...
 294
 295 =head1 AUTHOR
 296
 297 Kennedy Clark, C<hkclark@gmail.com>
 298
 299 Please report any errors, issues or suggestions to the author.  The
 300 most recent version of the Catalyst Tutorial can be found at
 301 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Manual/lib/Catalyst/Manual/Tutorial/>.
 302
 303 Copyright 2006, Kennedy Clark, under Creative Commons License
 304 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).
 305