X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2FBasicCRUD.pod;h=0aa7e2ce96f591088d783bb75291838e369d16b3;hp=e1b798a316431e5f5a96ac75aeec8be5a746cf5f;hb=994b66ad3ec2a66fb5d22957474229422b9ce110;hpb=45c7830fc2a9167e08203368ca11d6d13628c5fb diff --git a/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod b/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod index e1b798a..0aa7e2c 100644 --- a/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod +++ b/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod @@ -66,9 +66,17 @@ focus on the Create and Delete aspects of CRUD. More advanced capabilities, including full Update functionality, will be addressed in Part 9. +Although this part of the tutorial will show you how to build CRUD +functionality yourself, another option is to use a "CRUD builder" type +of tool to automate the process. You get less control, but it's quick +and easy. For example, see +L, +L, and +L. + You can checkout the source code for this example from the catalyst subversion repository as per the instructions in -L +L. =head1 FORMLESS SUBMISSION @@ -164,7 +172,7 @@ Edit C and then enter: [% # Provide a link back to the list page -%] [% # 'uri_for()' builds a full URI; e.g., 'http://localhost:3000/books/list' -%] -

Return to list

+

Return to list

[% # Try out the TT Dumper (for development only!) -%] 
@@ -172,22 +180,20 @@ Edit C and then enter:
     [% Dumper.dump(book) %]
-The TT C directive allows access to a variety of plugin modules (TT -plugins, that is, not Catalyst plugins) to add extra functionality to -the base TT capabilities. Here, the plugin allows L -"pretty printing" of objects and variables. Other than that, the rest -of the code should be familiar from the examples in Part 3. +The TT C directive allows access to a variety of plugin modules +(TT plugins, that is, not Catalyst plugins) to add extra functionality +to the base TT capabilities. Here, the plugin allows +L "pretty printing" of objects and +variables. Other than that, the rest of the code should be familiar +from the examples in Part 3. -B As mentioned earlier, the C view -class created by TTSite redefines the name used to access the Catalyst -context object in TT templates from the usual C to C. =head2 Try the C Feature If the application is still running from before, use C to kill it. Then restart the server: - $ script/myapp_server.pl + $ DBIC_TRACE=1 script/myapp_server.pl Note that new path for C appears in the startup debug output. @@ -203,7 +209,7 @@ Next, use your browser to enter the following URL: http://localhost:3000/books/url_create/TCPIP_Illustrated_Vol-2/5/4 -Your browser should display " Added book 'TCPIP_Illustrated_Vol-2' by +Your browser should display "Added book 'TCPIP_Illustrated_Vol-2' by 'Stevens' with a rating of 5." along with a dump of the new book model object. You should also see the following DBIC debug messages displayed in the development server log messages if you have DBIC_TRACE set: @@ -218,19 +224,236 @@ The C statements are obviously adding the book and linking it to the existing record for Richard Stevens. The C Rating: @@ -278,6 +502,7 @@ Open C in your editor and enter: Note that we have specified the target of the form data as C, the method created in the section that follows. + =head2 Add a Method to Process Form Values and Update Database Edit C and add the following method to @@ -289,7 +514,7 @@ save the form information to the database: =cut - sub form_create_do : Local { + sub form_create_do :Chained('base') :PathPart('form_create_do') :Args(0) { my ($self, $c) = @_; # Retrieve the values from the form @@ -324,9 +549,24 @@ it. Then restart the server: $ script/myapp_server.pl +Notice that the server startup log reflects the two new chained +methods that we added: + + [debug] Loaded Chained actions: + .-------------------------------------+--------------------------------------. + | Path Spec | Private | + +-------------------------------------+--------------------------------------+ + | /books/form_create | /books/base (0) | + | | => /books/form_create | + | /books/form_create_do | /books/base (0) | + | | => /books/form_create_do | + | /books/url_create/*/*/* | /books/base (0) | + | | => /books/url_create | + '-------------------------------------+--------------------------------------' + Point your browser to L and enter "TCP/IP Illustrated, Vol 3" for the title, a rating of 5, and an -author ID of 4. You should then be forwarded to the same +author ID of 4. You should then see the output of the same C template seen in earlier examples. Finally, click "Return to list" to view the full list of books. @@ -380,33 +620,92 @@ and 2) the four lines for the Delete link near the bottom). [% # Add a link to delete a book %] - Delete + Delete [% END -%] -The additional code is obviously designed to add a new column to the -right side of the table with a C "button" (for simplicity, links -will be used instead of full HTML buttons). +The additional code is obviously designed to add a new column to the +right side of the table with a C "button" (for simplicity, +links will be used instead of full HTML buttons). + +B You should use more than just a simple link with your +applications. Consider using some sort of of confirmation page +(typically with unique actions in your controller for both the +confirmation and the actual delete operation). Also, you should try +to use an HTTP POST operation (versus the GET used here) for +operations that change the state of your application (e.g., the +database). + + +=head2 Add a Common Method to Retrieve a Book for the Chain + +As mentioned earlier, since we have a mixture of actions that operate on +a single book ID and others that do no, we should not have C +capture the book ID, find the corresponding book in the database and +save it in the stash for later links in the chain. However, just +because that logic does not belong in C doesn't mean that we can't +create another location to centralize that logic. In our case, we will +create a method called C that will store the specific book in +the stash. Chains that always operate on a single existing book can +chain off this method, but methods such as C that don't +operate on an existing book can chain directly off base. + +To add the C method, edit C +and add the following code: + + sub object :Chained('base') :PathPart('id') :CaptureArgs(1) { + my ($self, $c, $id) = @_; + + # Find the book object and store it in the stash + $c->stash(object => $c->stash->{resultset}->find($id)); + + # Make sure the lookup was successful. You would probably + # want to do something like this in a real app: + # $c->detach('/error_404') if !$c->stash->{object}; + die "Book $id not found!" if !$c->stash->{object}; + } + +Now, any other method that chains off C will automatically +have the appropriate book waiting for it in +C<$c-Estash-Egt>{object}>. + +Also note that we are using different technique for setting +C<$c-Estash>. The advantage of this style is that it let's you +set multiple stash variables at a time. For example: + + $c->stash(object => $c->stash->{resultset}->find($id), + another_thing => 1); + +or as a hashref: + + $c->stash({object => $c->stash->{resultset}->find($id), + another_thing => 1}); + +Either format works, but the C<$c-Estash(name => value);> +style is growing in popularity -- you may which to use it all +the time (even when you are only setting a single value). + =head2 Add a Delete Action to the Controller Open C in your editor and add the following method: - =head2 delete + =head2 delete Delete a book =cut - sub delete : Local { + sub delete :Chained('object') :PathPart('delete') :Args(0) { # $id = primary key of book to delete - my ($self, $c, $id) = @_; + my ($self, $c) = @_; - # Search for the book and then delete it - $c->model('DB::Books')->search({id => $id})->delete_all; + # Use the book object saved by 'object' and delete it along + # with related 'book_authors' entries + $c->stash->{object}->delete; # Set a status message to be displayed at the top of the view $c->stash->{status_msg} = "Book deleted."; @@ -415,12 +714,10 @@ following method: $c->forward('list'); } -This method first deletes the book with the specified primary key ID. -However, it also removes the corresponding entry from the -C table. Note that C was used instead of -C: whereas C also removes the join table entries in -C, C does not (only use C if you -really need the cascading deletes... otherwise you are wasting resources). +This method first deletes the book object saved by the C method. +However, it also removes the corresponding entry from the +C table. Note that C will cascade to also delete +the related join table entries in C. Then, rather than forwarding to a "delete done" page as we did with the earlier create example, it simply sets the C to display a @@ -438,12 +735,35 @@ equivalent. If the application is still running from before, use C to kill it. Then restart the server: - $ script/myapp_server.pl + $ DBIC_TRACE=1 script/myapp_server.pl + +The C method now appears in the "Loaded Chained actions" section +of the startup debug output: + + [debug] Loaded Chained actions: + .-------------------------------------+--------------------------------------. + | Path Spec | Private | + +-------------------------------------+--------------------------------------+ + | /books/id/*/delete | /books/base (0) | + | | -> /books/object (1) | + | | => /books/delete | + | /books/form_create | /books/base (0) | + | | => /books/form_create | + | /books/form_create_do | /books/base (0) | + | | => /books/form_create_do | + | /books/url_create/*/*/* | /books/base (0) | + | | => /books/url_create | + '-------------------------------------+--------------------------------------' Then point your browser to L and click the "Delete" link next to the first "TCPIP_Illustrated_Vol-2". A green "Book deleted" status message should display at the top of the page, -along with a list of the eight remaining books. +along with a list of the eight remaining books. You will also see the +cascading delete operation via the DBIC_TRACE output: + + DELETE FROM books WHERE ( id = ? ): '6' + SELECT me.book_id, me.author_id FROM book_authors me WHERE ( me.book_id = ? ): '6' + DELETE FROM book_authors WHERE ( author_id = ? AND book_id = ? ): '4', '6' =head2 Fixing a Dangerous URL @@ -468,18 +788,19 @@ To convert the forward used in the previous section to a redirect, open C and edit the existing C method to match: - =head2 delete + =head2 delete Delete a book - + =cut - sub delete : Local { + sub delete :Chained('object') :PathPart('delete') :Args(0) { # $id = primary key of book to delete my ($self, $c, $id) = @_; - # Search for the book and then delete it - $c->model('DB::Books')->search({id => $id})->delete_all; + # Use the book object saved by 'object' and delete it along + # with related 'book_authors' entries + $c->stash->{object}->delete; # Set a status message to be displayed at the top of the view $c->stash->{status_msg} = "Book deleted."; @@ -492,23 +813,25 @@ C method to match: =head2 Try the Delete and Redirect Logic Restart the development server and point your browser to -L and delete the first copy of -"TCPIP_Illustrated_Vol-2". The URL in your browser should return to -the L URL, so that is an -improvement, but notice that I. Because the stash is reset on every request (and a -redirect involves a second request), the C is cleared -before it can be displayed. +L (don't just hit "Refresh" in your +browser since we left the URL in an invalid state in the previous +section!) and delete the first copy of the remaining two +"TCPIP_Illustrated_Vol-2" books. The URL in your browser should return +to the L URL, so that is an +improvement, but notice that I. Because the stash is reset on every request (and a redirect +involves a second request), the C is cleared before it can +be displayed. =head2 Using C to Pass Query Parameters -There are several ways to pass information across a redirect. -In general, the best option is to use the C technique that we -will see in Part 5 of the tutorial; however, here we will pass the -information via query parameters on the redirect itself. Open -C and update the existing -C method to match the following: +There are several ways to pass information across a redirect. One +option is to use the C technique that we will see in Part 5 of +the tutorial; however, here we will pass the information via query +parameters on the redirect itself. Open +C and update the existing C +method to match the following: =head2 delete @@ -516,12 +839,13 @@ C method to match the following: =cut - sub delete : Local { + sub delete :Chained('object') :PathPart('delete') :Args(0) { # $id = primary key of book to delete my ($self, $c, $id) = @_; - # Search for the book and then delete it - $c->model('DB::Books')->search({id => $id})->delete_all; + # Use the book object saved by 'object' and delete it along + # with related 'book_authors' entries + $c->stash->{object}->delete; # Redirect the user back to the list page with status msg as an arg $c->response->redirect($c->uri_for('/books/list', @@ -530,35 +854,46 @@ C method to match the following: This modification simply leverages the ability of C to include an arbitrary number of name/value pairs in a hash reference. Next, we -need to update C to handle C as a +need to update C to handle C as a query parameter: - - + ...
- [% status_msg || Catalyst.request.params.status_msg %] - [% error_msg %] - [% content %] -
- - + [%# Status and error messages %] + [% status_msg || c.request.params.status_msg %] + [% error_msg %] + [%# This is where TT will stick all of your template's contents. -%] + [% content %] + + ... + +Although the sample above only shows the C div, leave the +rest of the file intact -- the only change we made to the C +was to add "C<|| c.request.params.status_msg>" to the +Cspan class="message"E> line. =head2 Try the Delete and Redirect With Query Param Logic Restart the development server and point your browser to -L. Then delete the remaining copy -of "TCPIP_Illustrated_Vol-2". The green "Book deleted" status message +L (you should now be able to safely +hit "refresh" in your browser). Then delete the remaining copy of +"TCPIP_Illustrated_Vol-2". The green "Book deleted" status message should return. -B Although this did present an opportunity to show a handy -capability of C, it would be much better to use Catalyst's -C feature in this situation. Although the technique here is -less dangerous than leaving the delete URL in the client's browser, -we have still exposed the status message to the user. With C, -this message returns to its rightful place as a service-side -mechanism (we will migrate this code to C in the next part -of the tutorial). +B Another popular method for maintaining server-side +information across a redirect is to use the C technique we +discuss in the next part of the tutorial, +L. While +C is a "slicker" mechanism in that it's all handled by the +server and doesn't "pollute" your URLs, B can lead to situations where the wrong information shows up +in the wrong browser window if the user has multiple windows or +browser tabs open.> For example, Window A causes something to be +placed in the stash, but before that window performs a redirect, +Window B makes a request to the server and gets the status information +that should really go to Window A. For this reason, you may wish +to use the "query param" technique shown here in your applications. =head1 AUTHOR @@ -567,8 +902,7 @@ Kennedy Clark, C Please report any errors, issues or suggestions to the author. The most recent version of the Catalyst Tutorial can be found at -L. +L. Copyright 2006-2008, Kennedy Clark, under Creative Commons License -(L). - +(L).