3 Catalyst::Manual::Tutorial::04_BasicCRUD - Catalyst Tutorial - Chapter 4: Basic CRUD
8 This is B<Chapter 4 of 10> for the Catalyst tutorial.
10 L<Tutorial Overview|Catalyst::Manual::Tutorial>
16 L<Introduction|Catalyst::Manual::Tutorial::01_Intro>
20 L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
24 L<More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>
32 L<Authentication|Catalyst::Manual::Tutorial::05_Authentication>
36 L<Authorization|Catalyst::Manual::Tutorial::06_Authorization>
40 L<Debugging|Catalyst::Manual::Tutorial::07_Debugging>
44 L<Testing|Catalyst::Manual::Tutorial::08_Testing>
48 L<Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
52 L<Appendices|Catalyst::Manual::Tutorial::10_Appendices>
59 This chapter of the tutorial builds on the fairly primitive application
61 L<Chapter 3|Catalyst::Manual::Tutorial::03_MoreCatalystBasics> to add
62 basic support for Create, Read, Update, and Delete (CRUD) of C<Book>
63 objects. Note that the 'list' function in Chapter 3 already implements
64 the Read portion of CRUD (although Read normally refers to reading a
65 single object; you could implement full Read functionality using the
66 techniques introduced below). This section will focus on the Create and
67 Delete aspects of CRUD. More advanced capabilities, including full
68 Update functionality, will be addressed in
69 L<Chapter 9|Catalyst::Manual::Tutorial::09_AdvancedCRUD>.
71 Although this chapter of the tutorial will show you how to build CRUD
72 functionality yourself, another option is to use a "CRUD builder" type
73 of tool to automate the process. You get less control, but it can be
74 quick and easy. For example, see L<Catalyst::Plugin::AutoCRUD>,
75 L<CatalystX::CRUD>, and L<CatalystX::CRUD::YUI>.
77 You can check out the source code for this example from the Catalyst
78 Subversion repository as per the instructions in
79 L<Catalyst::Manual::Tutorial::01_Intro>.
82 =head1 FORMLESS SUBMISSION
84 Our initial attempt at object creation will utilize the "URL arguments"
85 feature of Catalyst (we will employ the more common form-based
86 submission in the sections that follow).
89 =head2 Include a Create Action in the Books Controller
91 Edit C<lib/MyApp/Controller/Books.pm> and enter the following method:
95 Create a book with the supplied title, rating, and author
99 sub url_create :Local {
100 # In addition to self & context, get the title, rating, &
101 # author_id args from the URL. Note that Catalyst automatically
102 # puts extra information after the "/<controller_name>/<action_name/"
103 # into @_. The args are separated by the '/' char on the URL.
104 my ($self, $c, $title, $rating, $author_id) = @_;
106 # Call create() on the book model object. Pass the table
107 # columns/field values we want to set as hash values
108 my $book = $c->model('DB::Book')->create({
113 # Add a record to the join table for this book, mapping to
115 $book->add_to_book_authors({author_id => $author_id});
116 # Note: Above is a shortcut for this:
117 # $book->create_related('book_authors', {author_id => $author_id});
119 # Assign the Book object to the stash for display and set template
120 $c->stash(book => $book,
121 template => 'books/create_done.tt2');
123 # Disable caching for this page
124 $c->response->header('Cache-Control' => 'no-cache');
127 Notice that Catalyst takes "extra slash-separated information" from the
128 URL and passes it as arguments in C<@_> (as long as the number of
129 arguments is not "fixed" using an attribute like C<:Args(0)>). The
130 C<url_create> action then uses a simple call to the DBIC C<create>
131 method to add the requested information to the database (with a separate
132 call to C<add_to_book_authors> to update the join table). As do
133 virtually all controller methods (at least the ones that directly handle
134 user input), it then sets the template that should handle this request.
136 Also note that we are explicitly setting a C<no-cache> "Cache-Control"
137 header to force browsers using the page to get a fresh copy every time.
138 You could even move this to a C<auto> method in
139 C<lib/MyApp/Controller/Root.pm> and it would automatically get applied
140 to every page in the whole application via a single line of code
141 (remember from Chapter 3, that every C<auto> method gets run in the
142 Controller hierarchy).
145 =head2 Include a Template for the 'url_create' Action:
147 Edit C<root/src/books/create_done.tt2> and then enter:
149 [% # Use the TT Dumper plugin to Data::Dumper variables to the browser -%]
150 [% # Not a good idea for production use, though. :-) 'Indent=1' is -%]
151 [% # optional, but prevents "massive indenting" of deeply nested objects -%]
152 [% USE Dumper(Indent=1) -%]
154 [% # Set the page title. META can 'go back' and set values in templates -%]
155 [% # that have been processed 'before' this template (here it's updating -%]
156 [% # the title in the root/src/wrapper.tt2 wrapper template). Note that -%]
157 [% # META only works on simple/static strings (i.e. there is no variable -%]
158 [% # interpolation -- if you need dynamic/interpolated content in your -%]
159 [% # title, set "$c->stash(title => $something)" in the controller). -%]
160 [% META title = 'Book Created' %]
162 [% # Output information about the record that was added. First title. -%]
163 <p>Added book '[% book.title %]'
165 [% # Then, output the last name of the first author -%]
166 by '[% book.authors.first.last_name %]'
168 [% # Then, output the rating for the book that was added -%]
169 with a rating of [% book.rating %].</p>
171 [% # Provide a link back to the list page. 'c.uri_for' builds -%]
172 [% # a full URI; e.g., 'http://localhost:3000/books/list' -%]
173 <p><a href="[% c.uri_for('/books/list') %]">Return to list</a></p>
175 [% # Try out the TT Dumper (for development only!) -%]
177 Dump of the 'book' variable:
178 [% Dumper.dump(book) %]
181 The TT C<USE> directive allows access to a variety of plugin modules (TT
182 plugins, that is, not Catalyst plugins) to add extra functionality to
183 the base TT capabilities. Here, the plugin allows L<Data::Dumper>
184 "pretty printing" of objects and variables. Other than that, the rest
185 of the code should be familiar from the examples in Chapter 3.
188 =head2 Try the 'url_create' Feature
190 Make sure the development server is running with the "-r" restart
193 $ DBIC_TRACE=1 script/myapp_server.pl -r
195 Note that new path for C</books/url_create> appears in the startup debug
198 Next, use your browser to enter the following URL:
200 http://localhost:3000/books/url_create/TCPIP_Illustrated_Vol-2/5/4
202 Your browser should display "Added book 'TCPIP_Illustrated_Vol-2' by
203 'Stevens' with a rating of 5." along with a dump of the new book model
204 object as it was returned by DBIC. You should also see the following
205 DBIC debug messages displayed in the development server log messages if
206 you have DBIC_TRACE set:
208 INSERT INTO book (rating, title) VALUES (?, ?): `5', `TCPIP_Illustrated_Vol-2'
209 INSERT INTO book_author (author_id, book_id) VALUES (?, ?): `4', `6'
211 The C<INSERT> statements are obviously adding the book and linking it to
212 the existing record for Richard Stevens. The C<SELECT> statement
213 results from DBIC automatically fetching the book for the
214 C<Dumper.dump(book)>.
216 If you then click the "Return to list" link, you should find that there
217 are now six books shown (if necessary, Shift+Reload or Ctrl+Reload your
218 browser at the C</books/list> page). You should now see the six DBIC
219 debug messages similar to the following (where N=1-6):
221 SELECT author.id, author.first_name, author.last_name
222 FROM book_author me JOIN author author
223 ON author.id = me.author_id WHERE ( me.book_id = ? ): 'N'
226 =head1 CONVERT TO A CHAINED ACTION
228 Although the example above uses the same C<Local> action type for the
229 method that we saw in the previous chapter of the tutorial, there is an
230 alternate approach that allows us to be more specific while also paving
231 the way for more advanced capabilities. Change the method declaration
232 for C<url_create> in C<lib/MyApp/Controller/Books.pm> you entered above
233 to match the following:
235 sub url_create :Chained('/') :PathPart('books/url_create') :Args(3) {
236 # In addition to self & context, get the title, rating, &
237 # author_id args from the URL. Note that Catalyst automatically
238 # puts the first 3 arguments worth of extra information after the
239 # "/<controller_name>/<action_name/" into @_ because we specified
240 # "Args(3)". The args are separated by the '/' char on the URL.
241 my ($self, $c, $title, $rating, $author_id) = @_;
245 This converts the method to take advantage of the Chained
246 action/dispatch type. Chaining lets you have a single URL automatically
247 dispatch to several controller methods, each of which can have precise
248 control over the number of arguments that it will receive. A chain can
249 essentially be thought of having three parts -- a beginning, a middle,
250 and an end. The bullets below summarize the key points behind each of
251 these parts of a chain:
265 B<Use "C<:Chained('/')>" to start a chain>
269 Get arguments through C<CaptureArgs()>
273 Specify the path to match with C<PathPart()>
286 Link to previous part of the chain with C<:Chained('_name_')>
290 Get arguments through C<CaptureArgs()>
294 Specify the path to match with C<PathPart()>
307 Link to previous part of the chain with C<:Chained('_name_')>
311 B<Do NOT get arguments through "C<CaptureArgs()>," use "C<Args()>" instead to end a chain>
315 Specify the path to match with C<PathPart()>
322 In our C<url_create> method above, we have combined all three parts into
323 a single method: C<:Chained('/')> to start the chain,
324 C<:PathPart('books/url_create')> to specify the base URL to match, and
325 C<:Args(3)> to capture exactly three arguments and to end the chain.
327 As we will see shortly, a chain can consist of as many "links" as you
328 wish, with each part capturing some arguments and doing some work along
329 the way. We will continue to use the Chained action type in this
330 chapter of the tutorial and explore slightly more advanced capabilities
331 with the base method and delete feature below. But Chained dispatch is
332 capable of far more. For additional information, see
333 L<Catalyst::Manual::Intro/Action types>,
334 L<Catalyst::DispatchType::Chained>, and the 2006 Advent calendar entry
335 on the subject: L<http://www.catalystframework.org/calendar/2006/10>.
338 =head2 Try the Chained Action
340 If you look back at the development server startup logs from your
341 initial version of the C<url_create> method (the one using the C<:Local>
342 attribute), you will notice that it produced output similar to the
345 [debug] Loaded Path actions:
346 .-------------------------------------+--------------------------------------.
348 +-------------------------------------+--------------------------------------+
351 | /books | /books/index |
352 | /books/list | /books/list |
353 | /books/url_create | /books/url_create |
354 '-------------------------------------+--------------------------------------'
356 When the development server restarts after our conversion to Chained
357 dispatch, the debug output should change to something along the lines of
360 [debug] Loaded Path actions:
361 .-------------------------------------+--------------------------------------.
363 +-------------------------------------+--------------------------------------+
366 | /books | /books/index |
367 | /books/list | /books/list |
368 '-------------------------------------+--------------------------------------'
370 [debug] Loaded Chained actions:
371 .-------------------------------------+--------------------------------------.
372 | Path Spec | Private |
373 +-------------------------------------+--------------------------------------+
374 | /books/url_create/*/*/* | /books/url_create |
375 '-------------------------------------+--------------------------------------'
377 C<url_create> has disappeared from the "Loaded Path actions" section but
378 it now shows up under the newly created "Loaded Chained actions"
379 section. And the "/*/*/*" portion clearly shows our requirement for
382 As with our non-chained version of C<url_create>, use your browser to
383 enter the following URL:
385 http://localhost:3000/books/url_create/TCPIP_Illustrated_Vol-2/5/4
387 You should see the same "Added book 'TCPIP_Illustrated_Vol-2' by
388 'Stevens' with a rating of 5." along with a dump of the new book model
389 object. Click the "Return to list" link, and you should find that there
390 are now seven books shown (two copies of I<TCPIP_Illustrated_Vol-2>).
393 =head2 Refactor to Use a 'base' Method to Start the Chains
395 Let's make a quick update to our initial Chained action to show a little
396 more of the power of chaining. First, open
397 C<lib/MyApp/Controller/Books.pm> in your editor and add the following
402 Can place common logic to start chained dispatch here
406 sub base :Chained('/') :PathPart('books') :CaptureArgs(0) {
409 # Store the ResultSet in stash so it's available for other methods
410 $c->stash(resultset => $c->model('DB::Book'));
412 # Print a message to the debug log
413 $c->log->debug('*** INSIDE BASE METHOD ***');
416 Here we print a log message and store the DBIC ResultSet in
417 C<$c-E<gt>stash-E<gt>{resultset}> so that it's automatically available
418 for other actions that chain off C<base>. If your controller always
419 needs a book ID as its first argument, you could have the base method
420 capture that argument (with C<:CaptureArgs(1)>) and use it to pull the
421 book object with C<-E<gt>find($id)> and leave it in the stash for later
422 parts of your chains to then act upon. Because we have several actions
423 that don't need to retrieve a book (such as the C<url_create> we are
424 working with now), we will instead add that functionality to a common
425 C<object> action shortly.
427 As for C<url_create>, let's modify it to first dispatch to C<base>.
428 Open up C<lib/MyApp/Controller/Books.pm> and edit the declaration for
429 C<url_create> to match the following:
431 sub url_create :Chained('base') :PathPart('url_create') :Args(3) {
433 Once you save C<lib/MyApp/Controller/Books.pm>, notice that the
434 development server will restart and our "Loaded Chained actions" section
435 will changed slightly:
437 [debug] Loaded Chained actions:
438 .-------------------------------------+--------------------------------------.
439 | Path Spec | Private |
440 +-------------------------------------+--------------------------------------+
441 | /books/url_create/*/*/* | /books/base (0) |
442 | | => /books/url_create |
443 '-------------------------------------+--------------------------------------'
445 The "Path Spec" is the same, but now it maps to two Private actions as
446 we would expect. The C<base> method is being triggered by the C</books>
447 part of the URL. However, the processing then continues to the
448 C<url_create> method because this method "chained" off C<base> and
449 specified C<:PathPart('url_create')> (note that we could have omitted
450 the "PathPart" here because it matches the name of the method, but we
451 will include it to make the logic as explicit as possible).
453 Once again, enter the following URL into your browser:
455 http://localhost:3000/books/url_create/TCPIP_Illustrated_Vol-2/5/4
457 The same "Added book 'TCPIP_Illustrated_Vol-2' by 'Stevens' with a
458 rating of 5." message and a dump of the new book object should appear.
459 Also notice the extra "INSIDE BASE METHOD" debug message in the
460 development server output from the C<base> method. Click the "Return to
461 list" link, and you should find that there are now eight books shown.
462 (You may have a larger number of books if you repeated any of the
463 "create" actions more than once. Don't worry about it as long as the
464 number of books is appropriate for the number of times you added new
465 books... there should be the original five books added via
466 C<myapp01.sql> plus one additional book for each time you ran one of the
467 url_create variations above.)
470 =head1 MANUALLY BUILDING A CREATE FORM
472 Although the C<url_create> action in the previous step does begin to
473 reveal the power and flexibility of both Catalyst and DBIC, it's
474 obviously not a very realistic example of how users should be expected
475 to enter data. This section begins to address that concern (but just
476 barely, see L<Chapter 9|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
477 for better options for handling web-based forms).
480 =head2 Add Method to Display The Form
482 Edit C<lib/MyApp/Controller/Books.pm> and add the following method:
486 Display form to collect information for book to create
490 sub form_create :Chained('base') :PathPart('form_create') :Args(0) {
493 # Set the TT template to use
494 $c->stash(template => 'books/form_create.tt2');
497 This action simply invokes a view containing a form to create a book.
500 =head2 Add a Template for the Form
502 Open C<root/src/books/form_create.tt2> in your editor and enter:
504 [% META title = 'Manual Form Book Create' -%]
506 <form method="post" action="[% c.uri_for('form_create_do') %]">
508 <tr><td>Title:</td><td><input type="text" name="title"></td></tr>
509 <tr><td>Rating:</td><td><input type="text" name="rating"></td></tr>
510 <tr><td>Author ID:</td><td><input type="text" name="author_id"></td></tr>
512 <input type="submit" name="Submit" value="Submit">
515 Note that we have specified the target of the form data as
516 C<form_create_do>, the method created in the section that follows.
519 =head2 Add a Method to Process Form Values and Update Database
521 Edit C<lib/MyApp/Controller/Books.pm> and add the following method to
522 save the form information to the database:
524 =head2 form_create_do
526 Take information from form and add to database
530 sub form_create_do :Chained('base') :PathPart('form_create_do') :Args(0) {
533 # Retrieve the values from the form
534 my $title = $c->request->params->{title} || 'N/A';
535 my $rating = $c->request->params->{rating} || 'N/A';
536 my $author_id = $c->request->params->{author_id} || '1';
539 my $book = $c->model('DB::Book')->create({
543 # Handle relationship with author
544 $book->add_to_book_authors({author_id => $author_id});
545 # Note: Above is a shortcut for this:
546 # $book->create_related('book_authors', {author_id => $author_id});
548 # Store new model object in stash and set template
549 $c->stash(book => $book,
550 template => 'books/create_done.tt2');
554 =head2 Test Out The Form
556 Notice that the server startup log reflects the two new chained methods
559 [debug] Loaded Chained actions:
560 .-------------------------------------+--------------------------------------.
561 | Path Spec | Private |
562 +-------------------------------------+--------------------------------------+
563 | /books/form_create | /books/base (0) |
564 | | => /books/form_create |
565 | /books/form_create_do | /books/base (0) |
566 | | => /books/form_create_do |
567 | /books/url_create/*/*/* | /books/base (0) |
568 | | => /books/url_create |
569 '-------------------------------------+--------------------------------------'
571 Point your browser to L<http://localhost:3000/books/form_create> and
572 enter "TCP/IP Illustrated, Vol 3" for the title, a rating of 5, and an
573 author ID of 4. You should then see the output of the same
574 C<create_done.tt2> template seen in earlier examples. Finally, click
575 "Return to list" to view the full list of books.
577 B<Note:> Having the user enter the primary key ID for the author is
578 obviously crude; we will address this concern with a drop-down list and
579 add validation to our forms in
580 L<Chapter 9|Catalyst::Manual::Tutorial::09_AdvancedCRUD>.
583 =head1 A SIMPLE DELETE FEATURE
585 Turning our attention to the Delete portion of CRUD, this section
586 illustrates some basic techniques that can be used to remove information
590 =head2 Include a Delete Link in the List
592 Edit C<root/src/books/list.tt2> and update it to match the following
593 (two sections have changed: 1) the additional '<th>Links</th>' table
594 header, and 2) the five lines for the Delete link near the bottom):
596 [% # This is a TT comment. -%]
598 [%- # Provide a title -%]
599 [% META title = 'Book List' -%]
601 [% # Note That the '-' at the beginning or end of TT code -%]
602 [% # "chomps" the whitespace/newline at that end of the -%]
603 [% # output (use View Source in browser to see the effect) -%]
605 [% # Some basic HTML with a loop to display books -%]
607 <tr><th>Title</th><th>Rating</th><th>Author(s)</th><th>Links</th></tr>
608 [% # Display each book in a table row %]
609 [% FOREACH book IN books -%]
611 <td>[% book.title %]</td>
612 <td>[% book.rating %]</td>
614 [% # NOTE: See Chapter 4 for a better way to do this! -%]
615 [% # First initialize a TT variable to hold a list. Then use a TT FOREACH -%]
616 [% # loop in 'side effect notation' to load just the last names of the -%]
617 [% # authors into the list. Note that the 'push' TT vmethod doesn't return -%]
618 [% # a value, so nothing will be printed here. But, if you have something -%]
619 [% # in TT that does return a value and you don't want it printed, you -%]
620 [% # 1) assign it to a bogus value, or -%]
621 [% # 2) use the CALL keyword to call it and discard the return value. -%]
623 tt_authors.push(author.last_name) FOREACH author = book.authors %]
624 [% # Now use a TT 'virtual method' to display the author count in parens -%]
625 [% # Note the use of the TT filter "| html" to escape dangerous characters -%]
626 ([% tt_authors.size | html %])
627 [% # Use another TT vmethod to join & print the names & comma separators -%]
628 [% tt_authors.join(', ') | html %]
631 [% # Add a link to delete a book %]
633 c.uri_for(c.controller.action_for('delete'), [book.id]) %]">Delete</a>
639 The additional code is obviously designed to add a new column to the
640 right side of the table with a C<Delete> "button" (for simplicity, links
641 will be used instead of full HTML buttons; but, in practice, anything
642 that modifies data should be handled with a form sending a POST
645 Also notice that we are using a more advanced form of C<uri_for> than we
646 have seen before. Here we use C<$c-E<gt>controller-E<gt>action_for> to
647 automatically generate a URI appropriate for that action based on the
648 method we want to link to while inserting the C<book.id> value into the
649 appropriate place. Now, if you ever change C<:PathPart('delete')> in
650 your controller method to something like C<:PathPart('kill')>, then your
651 links will automatically update without any changes to your .tt2
652 template file. As long as the name of your method does not change
653 (here, "delete"), then your links will still be correct. There are a
654 few shortcuts and options when using C<action_for()>:
660 If you are referring to a method in the current controller, you can use
661 C<$self-E<gt>action_for('_method_name_')>.
665 If you are referring to a method in a different controller, you need to
666 include that controller's name as an argument to C<controller()>, as in
667 C<$c-E<gt>controller('_controller_name_')-E<gt>action_for('_method_name_')>.
671 B<Note:> In practice you should B<never> use a GET request to delete a
672 record -- always use POST for actions that will modify data. We are
673 doing it here for illustrative and simplicity purposes only.
676 =head2 Add a Common Method to Retrieve a Book for the Chain
678 As mentioned earlier, since we have a mixture of actions that operate on
679 a single book ID and others that do not, we should not have C<base>
680 capture the book ID, find the corresponding book in the database and
681 save it in the stash for later links in the chain. However, just
682 because that logic does not belong in C<base> doesn't mean that we can't
683 create another location to centralize the book lookup code. In our
684 case, we will create a method called C<object> that will store the
685 specific book in the stash. Chains that always operate on a single
686 existing book can chain off this method, but methods such as
687 C<url_create> that don't operate on an existing book can chain directly
690 To add the C<object> method, edit C<lib/MyApp/Controller/Books.pm> and
691 add the following code:
695 Fetch the specified book object based on the book ID and store
700 sub object :Chained('base') :PathPart('id') :CaptureArgs(1) {
701 # $id = primary key of book to delete
702 my ($self, $c, $id) = @_;
704 # Find the book object and store it in the stash
705 $c->stash(object => $c->stash->{resultset}->find($id));
707 # Make sure the lookup was successful. You would probably
708 # want to do something like this in a real app:
709 # $c->detach('/error_404') if !$c->stash->{object};
710 die "Book $id not found!" if !$c->stash->{object};
712 # Print a message to the debug log
713 $c->log->debug("*** INSIDE OBJECT METHOD for obj id=$id ***");
716 Now, any other method that chains off C<object> will automatically have
717 the appropriate book waiting for it in C<$c-E<gt>stash-E<gt>{object}>.
720 =head2 Add a Delete Action to the Controller
722 Open C<lib/MyApp/Controller/Books.pm> in your editor and add the
731 sub delete :Chained('object') :PathPart('delete') :Args(0) {
734 # Use the book object saved by 'object' and delete it along
735 # with related 'book_author' entries
736 $c->stash->{object}->delete;
738 # Set a status message to be displayed at the top of the view
739 $c->stash->{status_msg} = "Book deleted.";
741 # Forward to the list action/method in this controller
745 This method first deletes the book object saved by the C<object> method.
746 However, it also removes the corresponding entry from the C<book_author>
747 table with a cascading delete.
749 Then, rather than forwarding to a "delete done" page as we did with the
750 earlier create example, it simply sets the C<status_msg> to display a
751 notification to the user as the normal list view is rendered.
753 The C<delete> action uses the context C<forward> method to return the
754 user to the book list. The C<detach> method could have also been used.
755 Whereas C<forward> I<returns> to the original action once it is
756 completed, C<detach> does I<not> return. Other than that, the two are
760 =head2 Try the Delete Feature
762 Once you save the Books controller, the server should automatically
763 restart. The C<delete> method should now appear in the "Loaded Chained
764 actions" section of the startup debug output:
766 [debug] Loaded Chained actions:
767 .-------------------------------------+--------------------------------------.
768 | Path Spec | Private |
769 +-------------------------------------+--------------------------------------+
770 | /books/id/*/delete | /books/base (0) |
771 | | -> /books/object (1) |
772 | | => /books/delete |
773 | /books/form_create | /books/base (0) |
774 | | => /books/form_create |
775 | /books/form_create_do | /books/base (0) |
776 | | => /books/form_create_do |
777 | /books/url_create/*/*/* | /books/base (0) |
778 | | => /books/url_create |
779 '-------------------------------------+--------------------------------------'
781 Then point your browser to L<http://localhost:3000/books/list> and click
782 the "Delete" link next to the first "TCPIP_Illustrated_Vol-2". A green
783 "Book deleted" status message should display at the top of the page,
784 along with a list of the eight remaining books. You will also see the
785 cascading delete operation via the DBIC_TRACE output:
787 SELECT me.id, me.title, me.rating FROM book me WHERE ( ( me.id = ? ) ): '6'
788 DELETE FROM book WHERE ( id = ? ): '6'
789 SELECT me.book_id, me.author_id FROM book_author me WHERE ( me.book_id = ? ): '6'
790 DELETE FROM book_author WHERE ( author_id = ? AND book_id = ? ): '4', '6'
793 =head2 Fixing a Dangerous URL
795 Note the URL in your browser once you have performed the deletion in the
796 prior step -- it is still referencing the delete action:
798 http://localhost:3000/books/id/6/delete
800 What if the user were to press reload with this URL still active? In
801 this case the redundant delete is harmless (although it does generate an
802 exception screen, it doesn't perform any undesirable actions on the
803 application or database), but in other cases this could clearly lead to
806 We can improve the logic by converting to a redirect. Unlike
807 C<$c-E<gt>forward('list'))> or C<$c-E<gt>detach('list'))> that perform a
808 server-side alteration in the flow of processing, a redirect is a
809 client-side mechanism that causes the browser to issue an entirely new
810 request. As a result, the URL in the browser is updated to match the
811 destination of the redirection URL.
813 To convert the forward used in the previous section to a redirect, open
814 C<lib/MyApp/Controller/Books.pm> and edit the existing C<sub delete>
823 sub delete :Chained('object') :PathPart('delete') :Args(0) {
826 # Use the book object saved by 'object' and delete it along
827 # with related 'book_author' entries
828 $c->stash->{object}->delete;
830 # Set a status message to be displayed at the top of the view
831 $c->stash->{status_msg} = "Book deleted.";
833 # Redirect the user back to the list page. Note the use
834 # of $self->action_for as earlier in this section (BasicCRUD)
835 $c->response->redirect($c->uri_for($self->action_for('list')));
839 =head2 Try the Delete and Redirect Logic
841 Point your browser to L<http://localhost:3000/books/list> (don't just
842 hit "Refresh" in your browser since we left the URL in an invalid state
843 in the previous section!) and delete the first copy of the remaining two
844 "TCPIP_Illustrated_Vol-2" books. The URL in your browser should return
845 to the L<http://localhost:3000/books/list> URL, so that is an
846 improvement, but notice that I<no green "Book deleted" status message is
847 displayed>. Because the stash is reset on every request (and a redirect
848 involves a second request), the C<status_msg> is cleared before it can
852 =head2 Using 'uri_for' to Pass Query Parameters
854 There are several ways to pass information across a redirect. One option
855 is to use the C<flash> technique that we will see in
856 L<Chapter 5|Catalyst::Manual::Tutorial::05_Authentication> of this
857 tutorial; however, here we will pass the information via query
858 parameters on the redirect itself. Open
859 C<lib/MyApp/Controller/Books.pm> and update the existing C<sub delete>
860 method to match the following:
868 sub delete :Chained('object') :PathPart('delete') :Args(0) {
871 # Use the book object saved by 'object' and delete it along
872 # with related 'book_author' entries
873 $c->stash->{object}->delete;
875 # Redirect the user back to the list page with status msg as an arg
876 $c->response->redirect($c->uri_for($self->action_for('list'),
877 {status_msg => "Book deleted."}));
880 This modification simply leverages the ability of C<uri_for> to include
881 an arbitrary number of name/value pairs in a hash reference. Next, we
882 need to update C<root/src/wrapper.tt2> to handle C<status_msg> as a
887 [%# Status and error messages %]
888 <span class="message">[%
889 status_msg || c.request.params.status_msg | html %]</span>
890 <span class="error">[% error_msg %]</span>
891 [%# This is where TT will stick all of your template's contents. -%]
893 </div><!-- end content -->
896 Although the sample above only shows the C<content> div, leave the rest
897 of the file intact -- the only change we made to the C<wrapper.tt2> was
898 to add "C<|| c.request.params.status_msg>" to the
899 C<E<lt>span class="message"E<gt>> line.
902 =head2 Try the Delete and Redirect With Query Param Logic
904 Point your browser to L<http://localhost:3000/books/list> (you should
905 now be able to safely hit "refresh" in your browser). Then delete the
906 remaining copy of "TCPIP_Illustrated_Vol-2". The green "Book deleted"
907 status message should return. But notice that you can now hit the
908 "Reload" button in your browser and it just redisplays the book list
909 (and it correctly shows it without the "Book deleted" message on
912 B<NOTE:> Be sure to check out
913 L<Authentication|Catalyst::Manual::Tutorial::05_Authentication> where we
914 use an improved technique that is better suited to your real world
918 =head1 EXPLORING THE POWER OF DBIC
920 In this section we will explore some additional capabilities offered by
921 L<DBIx::Class>. Although these features have relatively little to do
922 with Catalyst per se, you will almost certainly want to take advantage
923 of them in your applications.
926 =head2 Add Datetime Columns to Our Existing Books Table
928 Let's add two columns to our existing C<books> table to track when each
929 book was added and when each book is updated:
932 sqlite> ALTER TABLE book ADD created TIMESTAMP;
933 sqlite> ALTER TABLE book ADD updated TIMESTAMP;
934 sqlite> UPDATE book SET created = DATETIME('NOW'), updated = DATETIME('NOW');
935 sqlite> SELECT * FROM book;
936 1|CCSP SNRS Exam Certification Guide|5|2010-02-16 04:15:45|2010-02-16 04:15:45
937 2|TCP/IP Illustrated, Volume 1|5|2010-02-16 04:15:45|2010-02-16 04:15:45
938 3|Internetworking with TCP/IP Vol.1|4|2010-02-16 04:15:45|2010-02-16 04:15:45
939 4|Perl Cookbook|5|2010-02-16 04:15:45|2010-02-16 04:15:45
940 5|Designing with Web Standards|5|2010-02-16 04:15:45|2010-02-16 04:15:45
941 9|TCP/IP Illustrated, Vol 3|5|2010-02-16 04:15:45|2010-02-16 04:15:45
945 This will modify the C<books> table to include the two new fields and
946 populate those fields with the current time.
949 =head2 Update DBIx::Class to Automatically Handle the Datetime Columns
951 Next, we should re-run the DBIC helper to update the Result Classes with
954 $ script/myapp_create.pl model DB DBIC::Schema MyApp::Schema \
955 create=static components=TimeStamp dbi:SQLite:myapp.db \
956 on_connect_do="PRAGMA foreign_keys = ON"
957 exists "/root/dev/MyApp/script/../lib/MyApp/Model"
958 exists "/root/dev/MyApp/script/../t"
959 Dumping manual schema for MyApp::Schema to directory /root/dev/MyApp/script/../lib ...
960 Schema dump completed.
961 exists "/root/dev/MyApp/script/../lib/MyApp/Model/DB.pm"
963 Notice that we modified our use of the helper slightly: we told it to
964 include the L<DBIx::Class::TimeStamp> in the C<load_components> line of
967 If you open C<lib/MyApp/Schema/Result/Book.pm> in your editor you should
968 see that the C<created> and C<updated> fields are now included in the
969 call to C<add_columns()>. However, also notice that the C<many_to_many>
970 relationships we manually added below the "C<# DO NOT MODIFY...>" line
971 were automatically preserved.
973 While we have this file open, let's update it with some additional
974 information to have DBIC automatically handle the updating of these two
975 fields for us. Insert the following code at the bottom of the file (it
976 B<must> be B<below> the "C<# DO NOT MODIFY...>" line and B<above> the
977 C<1;> on the last line):
980 # Enable automatic date handling
982 __PACKAGE__->add_columns(
984 { data_type => 'timestamp', set_on_create => 1 },
986 { data_type => 'timestamp', set_on_create => 1, set_on_update => 1 },
989 This will override the definition for these fields that Schema::Loader
990 placed at the top of the file. The C<set_on_create> and
991 C<set_on_update> options will cause DBIx::Class to automatically update
992 the timestamps in these columns whenever a row is created or modified.
994 B<Note> that adding the lines above will cause the development server to
995 automatically restart if you are running it with the "-r" option. In
996 other words, the development server is smart enough to restart not only
997 for code under the C<MyApp/Controller/>, C<MyApp/Model/>, and
998 C<MyApp/View/> directories, but also under other directions such as our
999 "external DBIC model" in C<MyApp/Schema/>. However, also note that it's
1000 smart enough to B<not> restart when you edit your C<.tt2> files under
1003 Then enter the following URL into your web browser:
1005 http://localhost:3000/books/url_create/TCPIP_Illustrated_Vol-2/5/4
1007 You should get the same "Book Created" screen we saw earlier. However, if
1008 you now use the sqlite3 command-line tool to dump the C<books> table,
1009 you will see that the new book we added has an appropriate date and time
1010 entered for it (see the last line in the listing below):
1012 $ sqlite3 myapp.db "select * from book"
1013 1|CCSP SNRS Exam Certification Guide|5|2010-02-16 04:15:45|2010-02-16 04:15:45
1014 2|TCP/IP Illustrated, Volume 1|5|2010-02-16 04:15:45|2010-02-16 04:15:45
1015 3|Internetworking with TCP/IP Vol.1|4|2010-02-16 04:15:45|2010-02-16 04:15:45
1016 4|Perl Cookbook|5|2010-02-16 04:15:45|2010-02-16 04:15:45
1017 5|Designing with Web Standards|5|2010-02-16 04:15:45|2010-02-16 04:15:45
1018 9|TCP/IP Illustrated, Vol 3|5|2010-02-16 04:15:45|2010-02-16 04:15:45
1019 10|TCPIP_Illustrated_Vol-2|5|2010-02-16 04:18:42|2010-02-16 04:18:42
1021 Notice in the debug log that the SQL DBIC generated has changed to
1022 incorporate the datetime logic:
1024 INSERT INTO book ( created, rating, title, updated ) VALUES ( ?, ?, ?, ? ):
1025 '2010-02-16 04:18:42', '5', 'TCPIP_Illustrated_Vol-2', '2010-02-16 04:18:42'
1026 INSERT INTO book_author ( author_id, book_id ) VALUES ( ?, ? ): '4', '10'
1029 =head2 Create a ResultSet Class
1031 An often overlooked but extremely powerful features of DBIC is that it
1032 allows you to supply your own subclasses of C<DBIx::Class::ResultSet>.
1033 This can be used to pull complex and unsightly "query code" out of your
1034 controllers and encapsulate it in a method of your ResultSet Class.
1035 These "canned queries" in your ResultSet Class can then be invoked via a
1036 single call, resulting in much cleaner and easier to read controller
1037 code (or View code, if that's where you want to call it).
1039 To illustrate the concept with a fairly simple example, let's create a
1040 method that returns books added in the last 10 minutes. Start by making
1041 a directory where DBIx::Class will look for our ResultSet Class:
1043 $ mkdir lib/MyApp/Schema/ResultSet
1045 Then open C<lib/MyApp/Schema/ResultSet/Book.pm> and enter the following:
1047 package MyApp::Schema::ResultSet::Book;
1051 use base 'DBIx::Class::ResultSet';
1053 =head2 created_after
1055 A predefined search for recently added books
1060 my ($self, $datetime) = @_;
1062 my $date_str = $self->result_source->schema->storage
1063 ->datetime_parser->format_datetime($datetime);
1065 return $self->search({
1066 created => { '>' => $date_str }
1072 Then add the following method to the C<lib/MyApp/Controller/Books.pm>:
1076 List recently created books
1080 sub list_recent :Chained('base') :PathPart('list_recent') :Args(1) {
1081 my ($self, $c, $mins) = @_;
1083 # Retrieve all of the book records as book model objects and store in the
1084 # stash where they can be accessed by the TT template, but only
1085 # retrieve books created within the last $min number of minutes
1086 $c->stash(books => [$c->model('DB::Book')
1087 ->created_after(DateTime->now->subtract(minutes => $mins))]);
1089 # Set the TT template to use. You will almost always want to do this
1090 # in your action methods (action methods respond to user input in
1091 # your controllers).
1092 $c->stash(template => 'books/list.tt2');
1095 Now try different values for the "minutes" argument (the final number
1096 value) using the URL C<http://localhost:3000/books/list_recent/_#_> in
1097 your browser. For example, this would list all books added in the last
1100 http://localhost:3000/books/list_recent/15
1102 Depending on how recently you added books, you might want to try a
1103 higher or lower value for the minutes.
1106 =head2 Chaining ResultSets
1108 One of the most helpful and powerful features in C<DBIx::Class> is that
1109 it allows you to "chain together" a series of queries (note that this
1110 has nothing to do with the "Chained Dispatch" for Catalyst that we were
1111 discussing earlier). Because each ResultSet method returns another
1112 ResultSet, you can take an initial query and immediately feed that into
1113 a second query (and so on for as many queries you need). Note that no
1114 matter how many ResultSets you chain together, the database itself will
1115 not be hit until you use a method that attempts to access the data. And,
1116 because this technique carries over to the ResultSet Class feature we
1117 implemented in the previous section for our "canned search", we can
1118 combine the two capabilities. For example, let's add an action to our
1119 C<Books> controller that lists books that are both recent I<and> have
1120 "TCP" in the title. Open up C<lib/MyApp/Controller/Books.pm> and add
1121 the following method:
1123 =head2 list_recent_tcp
1125 List recently created books
1129 sub list_recent_tcp :Chained('base') :PathPart('list_recent_tcp') :Args(1) {
1130 my ($self, $c, $mins) = @_;
1132 # Retrieve all of the book records as book model objects and store in the
1133 # stash where they can be accessed by the TT template, but only
1134 # retrieve books created within the last $min number of minutes
1135 # AND that have 'TCP' in the title
1136 $c->stash(books => [
1137 $c->model('DB::Book')
1138 ->created_after(DateTime->now->subtract(minutes => $mins))
1139 ->search({title => {'like', '%TCP%'}})
1142 # Set the TT template to use. You will almost always want to do this
1143 # in your action methods (action methods respond to user input in
1144 # your controllers).
1145 $c->stash(template => 'books/list.tt2');
1148 To try this out, enter the following URL into your browser:
1150 http://localhost:3000/books/list_recent_tcp/100
1152 And you should get a list of books added in the last 100 minutes that
1153 contain the string "TCP" in the title. However, if you look at all
1154 books within the last 100 minutes, you should get a longer list (again,
1155 you might have to adjust the number of minutes depending on how recently
1156 you added books to your database):
1158 http://localhost:3000/books/list_recent/100
1160 Take a look at the DBIC_TRACE output in the development server log for
1161 the first URL and you should see something similar to the following:
1163 SELECT me.id, me.title, me.rating, me.created, me.updated FROM book me
1164 WHERE ( ( title LIKE ? AND created > ? ) ): '%TCP%', '2010-02-16 02:49:32'
1166 However, let's not pollute our controller code with this raw "TCP" query
1167 -- it would be cleaner to encapsulate that code in a method on our
1168 ResultSet Class. To do this, open C<lib/MyApp/Schema/ResultSet/Book.pm>
1169 and add the following method:
1173 A predefined search for books with a 'LIKE' search in the string
1178 my ($self, $title_str) = @_;
1180 return $self->search({
1181 title => { 'like' => "%$title_str%" }
1185 We defined the search string as C<$title_str> to make the method more
1186 flexible. Now update the C<list_recent_tcp> method in
1187 C<lib/MyApp/Controller/Books.pm> to match the following (we have
1188 replaced the C<-E<gt>search> line with the C<-E<gt>title_like> line
1189 shown here -- the rest of the method should be the same):
1191 =head2 list_recent_tcp
1193 List recently created books
1197 sub list_recent_tcp :Chained('base') :PathPart('list_recent_tcp') :Args(1) {
1198 my ($self, $c, $mins) = @_;
1200 # Retrieve all of the book records as book model objects and store in the
1201 # stash where they can be accessed by the TT template, but only
1202 # retrieve books created within the last $min number of minutes
1203 # AND that have 'TCP' in the title
1204 $c->stash(books => [
1205 $c->model('DB::Book')
1206 ->created_after(DateTime->now->subtract(minutes => $mins))
1210 # Set the TT template to use. You will almost always want to do this
1211 # in your action methods (action methods respond to user input in
1212 # your controllers).
1213 $c->stash(template => 'books/list.tt2');
1216 Try out the C<list_recent_tcp> and C<list_recent> URLs as we did above.
1217 They should work just the same, but our code is obviously cleaner and
1218 more modular, while also being more flexible at the same time.
1221 =head2 Adding Methods to Result Classes
1223 In the previous two sections we saw a good example of how we could use
1224 DBIx::Class ResultSet Classes to clean up our code for an entire query
1225 (for example, our "canned searches" that filtered the entire query). We
1226 can do a similar improvement when working with individual rows as well.
1227 Whereas the ResultSet construct is used in DBIC to correspond to an
1228 entire query, the Result Class construct is used to represent a row.
1229 Therefore, we can add row-specific "helper methods" to our Result
1230 Classes stored in C<lib/MyApp/Schema/Result/>. For example, open
1231 C<lib/MyApp/Schema/Result/Author.pm> and add the following method (as
1232 always, it must be above the closing "C<1;>"):
1235 # Row-level helper methods
1240 return $self->first_name . ' ' . $self->last_name;
1243 This will allow us to conveniently retrieve both the first and last name
1244 for an author in one shot. Now open C<root/src/books/list.tt2> and
1245 change the definition of C<tt_authors> from this:
1248 [% tt_authors = [ ];
1249 tt_authors.push(author.last_name) FOREACH author = book.authors %]
1255 [% tt_authors = [ ];
1256 tt_authors.push(author.full_name) FOREACH author = book.authors %]
1259 (Only C<author.last_name> was changed to C<author.full_name> -- the rest
1260 of the file should remain the same.)
1262 Now go to the standard book list URL:
1264 http://localhost:3000/books/list
1266 The "Author(s)" column will now contain both the first and last name.
1267 And, because the concatenation logic was encapsulated inside our Result
1268 Class, it keeps the code inside our TT template nice and clean
1269 (remember, we want the templates to be as close to pure HTML markup as
1270 possible). Obviously, this capability becomes even more useful as you
1271 use it to remove even more complicated row-specific logic from your
1275 =head2 Moving Complicated View Code to the Model
1277 The previous section illustrated how we could use a Result Class method
1278 to print the full names of the authors without adding any extra code to
1279 our view, but it still left us with a fairly ugly mess (see
1280 C<root/src/books/list.tt2>):
1284 [% # NOTE: See Chapter 4 for a better way to do this! -%]
1285 [% # First initialize a TT variable to hold a list. Then use a TT FOREACH -%]
1286 [% # loop in 'side effect notation' to load just the last names of the -%]
1287 [% # authors into the list. Note that the 'push' TT vmethod does not print -%]
1288 [% # a value, so nothing will be printed here. But, if you have something -%]
1289 [% # in TT that does return a method and you don't want it printed, you -%]
1290 [% # can: 1) assign it to a bogus value, or 2) use the CALL keyword to -%]
1291 [% # call it and discard the return value. -%]
1292 [% tt_authors = [ ];
1293 tt_authors.push(author.full_name) FOREACH author = book.authors %]
1294 [% # Now use a TT 'virtual method' to display the author count in parens -%]
1295 [% # Note the use of the TT filter "| html" to escape dangerous characters -%]
1296 ([% tt_authors.size | html %])
1297 [% # Use another TT vmethod to join & print the names & comma separators -%]
1298 [% tt_authors.join(', ') | html %]
1302 Let's combine some of the techniques used earlier in this section to
1303 clean this up. First, let's add a method to our Book Result Class to
1304 return the number of authors for a book. Open
1305 C<lib/MyApp/Schema/Result/Book.pm> and add the following method:
1309 Return the number of authors for the current book
1316 # Use the 'many_to_many' relationship to fetch all of the authors for the current
1317 # and the 'count' method in DBIx::Class::ResultSet to get a SQL COUNT
1318 return $self->authors->count;
1321 Next, let's add a method to return a list of authors for a book to the
1322 same C<lib/MyApp/Schema/Result/Book.pm> file:
1326 Return a comma-separated list of authors for the current book
1333 # Loop through all authors for the current book, calling all the 'full_name'
1334 # Result Class method for each
1336 foreach my $author ($self->authors) {
1337 push(@names, $author->full_name);
1340 return join(', ', @names);
1343 This method loops through each author, using the C<full_name> Result
1344 Class method we added to C<lib/MyApp/Schema/Result/Author.pm> in the
1347 Using these two methods, we can simplify our TT code. Open
1348 C<root/src/books/list.tt2> and update the "Author(s)" table cell to
1349 match the following:
1353 [% # Print count and author list using Result Class methods -%]
1354 ([% book.author_count | html %]) [% book.author_list | html %]
1358 Although most of the code we removed comprised comments, the overall
1359 effect is dramatic... because our view code is so simple, we don't need
1360 huge comments to clue people in to the gist of our code. The view code
1361 is now self-documenting and readable enough that you could probably get
1362 by with no comments at all. All of the "complex" work is being done in
1363 our Result Class methods (and, because we have broken the code into
1364 nice, modular chunks, the Result Class code is hardly something you
1365 would call complex).
1367 As we saw in this section, always strive to keep your view AND
1368 controller code as simple as possible by pulling code out into your
1369 model objects. Because L<DBIx::Class> can be easily extended in so many
1370 ways, it's an excellent to way accomplish this objective. It will make
1371 your code cleaner, easier to write, less error-prone, and easier to
1374 Before you conclude this section, hit Refresh in your browser... the
1375 output should be the same even though the backend code has been trimmed
1381 Kennedy Clark, C<hkclark@gmail.com>
1383 Feel free to contact the author for any errors or suggestions, but the
1384 best way to report issues is via the CPAN RT Bug system at
1385 <https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
1387 The most recent version of the Catalyst Tutorial can be found at
1388 L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.80/trunk/lib/Catalyst/Manual/Tutorial/>.
1390 Copyright 2006-2010, Kennedy Clark, under the
1391 Creative Commons Attribution Share-Alike License Version 3.0
1392 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).