updated instructions to only give checkout instructions for reference impl of tutoria...

[catagits/Catalyst-Runtime.git] / lib / Catalyst / Manual / Tutorial / AdvancedCRUD.pod

diff --git a/lib/Catalyst/Manual/Tutorial/AdvancedCRUD.pod b/lib/Catalyst/Manual/Tutorial/AdvancedCRUD.pod
index 4fa2d31..96fb811 100644 (file)
--- a/lib/Catalyst/Manual/Tutorial/AdvancedCRUD.pod
+++ b/lib/Catalyst/Manual/Tutorial/AdvancedCRUD.pod
@@ -70,7 +70,7 @@ L<HTML::FillInForm|HTML::FillInForm>.
 
 Here, we will make use of the L<HTML::Widget|HTML::Widget> to not only 
 ease form creation, but to also provide validation of the submitted 
-data.  The approached used by the part of the tutorial is to slowly 
+data.  The approached used by this part of the tutorial is to slowly 
 incorporate additional L<HTML::Widget|HTML::Widget> functionality in a 
 step-wise fashion (we start with fairly simple form creation and then 
 move on to more complex and "magical" features such as validation and 
@@ -79,12 +79,7 @@ auto-population/auto-saving).
 B<Note:> Part 8 of the tutorial is optional.  Users who do not wish to
 use L<HTML::Widget|HTML::Widget> may skip this part.
 
-B<TIP>: Note that all of the code for this part of the tutorial can be
-pulled from the Catalyst Subversion repository in one step with the
-following command:
-
-    svn checkout http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial@4627 .
-    IMPORTANT: Does not work yet.  Will be completed for final version.
+You can checkout the source code for this example from the catalyst subversion repository as per the instructions in L<Catalyst::Manual::Tutorial::Intro>
 
 =head1 C<HTML::WIDGET> FORM CREATION
 
@@ -131,11 +126,11 @@ following method:
         return $w;
     }
 
-This method provides a central location that builds an HTML::Widget-
-based form with the appropriate fields.  The "Get Authors" code uses 
-DBIC to retrieve a list of model objects and then uses C<map> to create 
-a hash where the hash keys are the database primary keys from the 
-authors table and the associated values are the last names of the 
+This method provides a central location that builds an 
+HTML::Widget-based form with the appropriate fields.  The "Get authors" 
+code uses DBIC to retrieve a list of model objects and then uses C<map> 
+to create a hash where the hash keys are the database primary keys from 
+the authors table and the associated values are the last names of the 
 authors.
 
 =head2 Add Actions to Display and Save the Form
@@ -192,7 +187,8 @@ following methods:
         # Set a status message for the user
         $c->stash->{status_msg} = 'Book created';
     
-        # Use 'hw_create' to redisplay the form
+        # Use 'hw_create' to redisplay the form.  As discussed in 
+        # Part 3, 'detach' is like 'forward', but it does not return
         $c->detach('hw_create');
     }
 
@@ -545,6 +541,9 @@ match the following code:
     
             # Set a status message for the user
             $c->stash->{status_msg} = 'Book created';
+            
+            # Redisplay an empty form for another
+            $c->stash->{widget_result} = $w->result;
         }
     
         # Set the template
@@ -557,7 +556,12 @@ C<$c-E<gt>model('MyAppDB::Book')-E<gt>create> and replaced it with a
 single call to C<$book-E<gt>populate_from_widget>.  Note that we still
 have to call C<$book-E<gt>add_to_book_authors> once per author because
 C<populate_from_widget> does not currently handle the relationships
-between tables.
+between tables.  Also, we reset the form to an empty fields by adding
+another call to C<$w-E<gt>result> and storing the output in the stash 
+(if we don't override the output from C<$w-E<gt>process($c-E<gt>req)>,
+the form values already entered will be retained on redisplay --
+although this could be desirable for some applications, we avoid it
+here to help avoid the creation of duplicate records).
 
 
 =head2 Try Out the Form
@@ -576,7 +580,9 @@ you added should be visible.
 
 Some developers my wish to use the "old-fashioned" table style of 
 rendering a form in lieu of the default C<HTML::Widget> rendering that 
-assumes you will use CSS for formatting.
+assumes you will use CSS for formatting.  This section demonstrates
+some techniques that can override the default rendering with a 
+custom class.
 
 
 =head2 Add a New "Element Container"
@@ -595,7 +601,6 @@ Open C<lib/FormElementContainer.pm> in your editor and enter:
             return map { $self->_build_element($_) } @{$element};
         }
         my $e = $element->clone;
-        my $class = $e->attr('class') || '';
         $e = new HTML::Element('span', class => 'fields_with_errors')->push_content($e)
             if $self->error && $e->tag eq 'input';
     
@@ -615,6 +620,10 @@ C<use> for your element container class:
 
     use FormElementContainer;
 
+B<Note:> If you forget to C<use> your container class in your 
+controller, then your form will not be displayed and no error messages 
+will be generated. Don't forget this important step!
+
 Then tell C<HTML::Widget> to use that class during rendering by updating
 C<make_book_widget> to match the following:
 
@@ -717,7 +726,7 @@ the second field.
 
 =item *
 
-JavaScript to position the user's curson in the first field of the form.
+JavaScript to position the user's cursor in the first field of the form.
 
 =back
 
@@ -738,7 +747,7 @@ you added should be visible.
 Kennedy Clark, C<hkclark@gmail.com>
 
 Please report any errors, issues or suggestions to the author.  The
-most recent version of the Catlayst Tutorial can be found at
+most recent version of the Catalyst Tutorial can be found at
 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/>.
 
 Copyright 2006, Kennedy Clark, under Creative Commons License