Commit | Line | Data |
d442cc9f |
1 | =head1 NAME |
2 | |
3533daff |
3 | Catalyst::Manual::Tutorial::BasicCRUD - Catalyst Tutorial - Part 4: Basic CRUD |
d442cc9f |
4 | |
5 | |
6 | =head1 OVERVIEW |
7 | |
3533daff |
8 | This is B<Part 4 of 10> for the Catalyst tutorial. |
d442cc9f |
9 | |
10 | L<Tutorial Overview|Catalyst::Manual::Tutorial> |
11 | |
12 | =over 4 |
13 | |
14 | =item 1 |
15 | |
16 | L<Introduction|Catalyst::Manual::Tutorial::Intro> |
17 | |
18 | =item 2 |
19 | |
20 | L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics> |
21 | |
22 | =item 3 |
23 | |
3533daff |
24 | L<More Catalyst Basics|Catalyst::Manual::Tutorial::MoreCatalystBasics> |
d442cc9f |
25 | |
26 | =item 4 |
27 | |
3533daff |
28 | B<Basic CRUD> |
d442cc9f |
29 | |
30 | =item 5 |
31 | |
3533daff |
32 | L<Authentication|Catalyst::Manual::Tutorial::Authentication> |
d442cc9f |
33 | |
34 | =item 6 |
35 | |
3533daff |
36 | L<Authorization|Catalyst::Manual::Tutorial::Authorization> |
d442cc9f |
37 | |
38 | =item 7 |
39 | |
3533daff |
40 | L<Debugging|Catalyst::Manual::Tutorial::Debugging> |
d442cc9f |
41 | |
42 | =item 8 |
43 | |
3533daff |
44 | L<Testing|Catalyst::Manual::Tutorial::Testing> |
d442cc9f |
45 | |
46 | =item 9 |
47 | |
3533daff |
48 | L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD> |
49 | |
50 | =item 10 |
51 | |
d442cc9f |
52 | L<Appendices|Catalyst::Manual::Tutorial::Appendices> |
53 | |
54 | =back |
55 | |
56 | |
d442cc9f |
57 | =head1 DESCRIPTION |
58 | |
59 | This part of the tutorial builds on the fairly primitive application |
3533daff |
60 | created in Part 3 to add basic support for Create, Read, Update, and |
d442cc9f |
61 | Delete (CRUD) of C<Book> objects. Note that the 'list' function in Part |
62 | 2 already implements the Read portion of CRUD (although Read normally |
63 | refers to reading a single object; you could implement full read |
64 | functionality using the techniques introduced below). This section will |
65 | focus on the Create and Delete aspects of CRUD. More advanced |
66 | capabilities, including full Update functionality, will be addressed in |
3533daff |
67 | Part 9. |
d442cc9f |
68 | |
1390ef0e |
69 | Although this part of the tutorial will show you how to build CRUD |
70 | functionality yourself, another option is to use a "CRUD builder" type |
71 | of tool to automate the process. You get less control, but it's quick |
72 | and easy. For example, see |
73 | L<CatalystX::ListFramework::Builder|CatalystX::ListFramework::Builder>, |
74 | L<CatalystX::CRUD|CatalystX::CRUD>, and |
7edc5484 |
75 | L<CatalystX::CRUD::YUI|CatalystX::CRUD::YUI>. |
1390ef0e |
76 | |
d442cc9f |
77 | You can checkout the source code for this example from the catalyst |
78 | subversion repository as per the instructions in |
1390ef0e |
79 | L<Catalyst::Manual::Tutorial::Intro|Catalyst::Manual::Tutorial::Intro>. |
d442cc9f |
80 | |
3533daff |
81 | |
d442cc9f |
82 | =head1 FORMLESS SUBMISSION |
83 | |
3533daff |
84 | Our initial attempt at object creation will utilize the "URL |
85 | arguments" feature of Catalyst (we will employ the more common form- |
86 | based submission in the sections that follow). |
d442cc9f |
87 | |
88 | |
89 | =head2 Include a Create Action in the Books Controller |
90 | |
91 | Edit C<lib/MyApp/Controller/Books.pm> and enter the following method: |
92 | |
93 | =head2 url_create |
94 | |
95 | Create a book with the supplied title, rating, and author |
96 | |
97 | =cut |
98 | |
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 @_ |
104 | my ($self, $c, $title, $rating, $author_id) = @_; |
105 | |
106 | # Call create() on the book model object. Pass the table |
107 | # columns/field values we want to set as hash values |
d0496197 |
108 | my $book = $c->model('DB::Books')->create({ |
d442cc9f |
109 | title => $title, |
110 | rating => $rating |
111 | }); |
112 | |
113 | # Add a record to the join table for this book, mapping to |
114 | # appropriate author |
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}); |
118 | |
119 | # Assign the Book object to the stash for display in the view |
120 | $c->stash->{book} = $book; |
121 | |
122 | # This is a hack to disable XSUB processing in Data::Dumper |
123 | # (it's used in the view). This is a work-around for a bug in |
124 | # the interaction of some versions or Perl, Data::Dumper & DBIC. |
125 | # You won't need this if you aren't using Data::Dumper (or if |
126 | # you are running DBIC 0.06001 or greater), but adding it doesn't |
127 | # hurt anything either. |
128 | $Data::Dumper::Useperl = 1; |
129 | |
130 | # Set the TT template to use |
131 | $c->stash->{template} = 'books/create_done.tt2'; |
132 | } |
133 | |
134 | Notice that Catalyst takes "extra slash-separated information" from the |
135 | URL and passes it as arguments in C<@_>. The C<url_create> action then |
136 | uses a simple call to the DBIC C<create> method to add the requested |
137 | information to the database (with a separate call to |
138 | C<add_to_book_authors> to update the join table). As do virtually all |
139 | controller methods (at least the ones that directly handle user input), |
140 | it then sets the template that should handle this request. |
141 | |
142 | |
143 | =head2 Include a Template for the C<url_create> Action: |
144 | |
145 | Edit C<root/src/books/create_done.tt2> and then enter: |
146 | |
147 | [% # Use the TT Dumper plugin to Data::Dumper variables to the browser -%] |
148 | [% # Not a good idea for production use, though. :-) 'Indent=1' is -%] |
149 | [% # optional, but prevents "massive indenting" of deeply nested objects -%] |
150 | [% USE Dumper(Indent=1) -%] |
151 | |
152 | [% # Set the page title. META can 'go back' and set values in templates -%] |
153 | [% # that have been processed 'before' this template (here it's for -%] |
154 | [% # root/lib/site/html and root/lib/site/header). Note that META on -%] |
155 | [% # simple strings (e.g., no variable interpolation). -%] |
156 | [% META title = 'Book Created' %] |
157 | |
158 | [% # Output information about the record that was added. First title. -%] |
159 | <p>Added book '[% book.title %]' |
160 | |
161 | [% # Output the last name of the first author. This is complicated by an -%] |
162 | [% # issue in TT 2.15 where blessed hash objects are not handled right. -%] |
163 | [% # First, fetch 'book.authors' from the DB once. -%] |
164 | [% authors = book.authors %] |
165 | [% # Now use IF statements to test if 'authors.first' is "working". If so, -%] |
166 | [% # we use it. Otherwise we use a hack that seems to keep TT 2.15 happy. -%] |
167 | by '[% authors.first.last_name IF authors.first; |
168 | authors.list.first.value.last_name IF ! authors.first %]' |
169 | |
170 | [% # Output the rating for the book that was added -%] |
171 | with a rating of [% book.rating %].</p> |
172 | |
173 | [% # Provide a link back to the list page -%] |
174 | [% # 'uri_for()' builds a full URI; e.g., 'http://localhost:3000/books/list' -%] |
8a7c5151 |
175 | <p><a href="[% c.uri_for('/books/list') %]">Return to list</a></p> |
d442cc9f |
176 | |
177 | [% # Try out the TT Dumper (for development only!) -%] |
178 | <pre> |
179 | Dump of the 'book' variable: |
180 | [% Dumper.dump(book) %] |
181 | </pre> |
182 | |
1390ef0e |
183 | The TT C<USE> directive allows access to a variety of plugin modules |
184 | (TT plugins, that is, not Catalyst plugins) to add extra functionality |
185 | to the base TT capabilities. Here, the plugin allows |
186 | L<Data::Dumper|Data::Dumper> "pretty printing" of objects and |
187 | variables. Other than that, the rest of the code should be familiar |
188 | from the examples in Part 3. |
d442cc9f |
189 | |
d442cc9f |
190 | |
191 | =head2 Try the C<url_create> Feature |
192 | |
193 | If the application is still running from before, use C<Ctrl-C> to kill |
194 | it. Then restart the server: |
195 | |
1390ef0e |
196 | $ DBIC_TRACE=1 script/myapp_server.pl |
d442cc9f |
197 | |
198 | Note that new path for C</books/url_create> appears in the startup debug |
199 | output. |
200 | |
201 | B<TIP>: You can use C<script/myapp_server.pl -r> to have the development |
202 | server auto-detect changed files and reload itself (if your browser acts |
203 | odd, you should also try throwing in a C<-k>). If you make changes to |
204 | the TT templates only, you do not need to reload the development server |
205 | (only changes to "compiled code" such as Controller and Model C<.pm> |
206 | files require a reload). |
207 | |
208 | Next, use your browser to enter the following URL: |
209 | |
210 | http://localhost:3000/books/url_create/TCPIP_Illustrated_Vol-2/5/4 |
211 | |
89d3dae9 |
212 | Your browser should display "Added book 'TCPIP_Illustrated_Vol-2' by |
d442cc9f |
213 | 'Stevens' with a rating of 5." along with a dump of the new book model |
214 | object. You should also see the following DBIC debug messages displayed |
3533daff |
215 | in the development server log messages if you have DBIC_TRACE set: |
d442cc9f |
216 | |
217 | INSERT INTO books (rating, title) VALUES (?, ?): `5', `TCPIP_Illustrated_Vol-2' |
218 | INSERT INTO book_authors (author_id, book_id) VALUES (?, ?): `4', `6' |
219 | SELECT author.id, author.first_name, author.last_name |
220 | FROM book_authors me JOIN authors author |
221 | ON ( author.id = me.author_id ) WHERE ( me.book_id = ? ): '6' |
222 | |
223 | The C<INSERT> statements are obviously adding the book and linking it to |
224 | the existing record for Richard Stevens. The C<SELECT> statement results |
225 | from DBIC automatically fetching the book for the C<Dumper.dump(book)>. |
226 | |
1390ef0e |
227 | If you then click the "Return to list" link, you should find that |
228 | there are now six books shown (if necessary, Shift+Reload or |
229 | Ctrl+Reload your browser at the C</books/list> page). |
d442cc9f |
230 | |
d442cc9f |
231 | |
89d3dae9 |
232 | =head1 CONVERT TO A CHAINED ACTION |
233 | |
234 | Although the example above uses the same C<Local> action type for the |
235 | method that we saw in the previous part of the tutorial, there is an |
236 | alternate approach that allows us to be more specific while also |
237 | paving the way for more advanced capabilities. Change the method |
238 | declaration for C<url_create> in C<lib/MyApp/Controller/Books.pm> you |
239 | entered above to match the following: |
240 | |
241 | sub url_create :Chained('/') :PathPart('books/url_create') :Args(3) { |
242 | |
243 | This converts the method to take advantage of the Chained |
244 | action/dispatch type. Chaining let's you have a single URL |
245 | automatically dispatch to several controller methods, each of which |
246 | can have precise control over the number of arguments that it will |
247 | receive. A chain can essentially be thought of having three parts -- |
248 | a beginning, a middle and an end. The bullets below summarize the key |
249 | points behind each of these parts of a chain: |
250 | |
251 | |
252 | =over 4 |
253 | |
254 | |
255 | =item * |
256 | |
257 | Beginning |
258 | |
259 | =over 4 |
260 | |
261 | =item * |
262 | |
263 | B<Use "C<:Chained('/')>" to start a chain> |
264 | |
265 | =item * |
266 | |
267 | Get arguments through C<CaptureArgs()> |
268 | |
269 | =item * |
270 | |
271 | Specify the path to match with C<PathPart()> |
272 | |
273 | =back |
274 | |
275 | |
276 | =item * |
277 | |
278 | Middle |
279 | |
280 | =over 4 |
281 | |
282 | =item * |
d442cc9f |
283 | |
89d3dae9 |
284 | Link to previous part of the chain with C<:Chained('_name_')> |
285 | |
286 | =item * |
287 | |
288 | Get arguments through C<CaptureArgs()> |
289 | |
290 | =item * |
291 | |
292 | Specify the path to match with C<PathPart()> |
293 | |
294 | =back |
295 | |
296 | |
297 | =item * |
298 | |
299 | End |
300 | |
301 | =over 4 |
302 | |
303 | =item * |
304 | |
305 | Link to previous part of the chain with C<:Chained('_name_')> |
306 | |
307 | =item * |
308 | |
309 | B<Do NOT get arguments through "C<CaptureArgs()>," use "C<Args()>" instead to end a chain> |
310 | |
311 | =item * |
312 | |
313 | Specify the path to match with C<PathPart()> |
314 | |
315 | =back |
316 | |
317 | |
318 | =back |
319 | |
320 | In our C<url_create> method above, we have combined all 3 parts into a |
321 | single method: C<:Chained('/')> to start the chain, |
322 | C<:PathPart('books/url_create')> to specify the base URL to match, |
323 | along with C<:Args(3)> to capture exactly 3 arguments and also end the |
324 | chain. |
325 | |
326 | As we will see shortly, a chain can consist of as many "links" as you |
327 | wish, with each part capturing some arguments and doing some work |
328 | along the way. We will continue to use the Chained action type in this |
329 | part of the tutorial and explore slightly more advanced capabilities |
330 | with the base method and delete feature below. But Chained dispatch |
331 | is capable of far more. For additional information, see |
332 | L<Catalyst::Manual::Intro/Action types>, |
333 | L<Catalyst::DispatchType::Chained|Catalyst::DispatchType::Chained>, |
334 | and the 2006 advent calendar entry on the subject: |
335 | L<http://www.catalystframework.org/calendar/2006/10>. |
336 | |
337 | |
338 | =head2 Try the Chained Action |
339 | |
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 |
342 | C<:Local> attribute), you will notice that it produced output similar |
343 | to the following: |
344 | |
345 | [debug] Loaded Path actions: |
346 | .-------------------------------------+--------------------------------------. |
347 | | Path | Private | |
348 | +-------------------------------------+--------------------------------------+ |
349 | | / | /default | |
350 | | / | /index | |
351 | | /books | /books/index | |
352 | | /books/list | /books/list | |
353 | | /books/url_create | /books/url_create | |
354 | '-------------------------------------+--------------------------------------' |
355 | |
356 | Now start the development server with our basic chained method in |
357 | place and the startup debug output should change to something along |
358 | the lines of the following: |
359 | |
360 | [debug] Loaded Path actions: |
361 | .-------------------------------------+--------------------------------------. |
362 | | Path | Private | |
363 | +-------------------------------------+--------------------------------------+ |
364 | | / | /default | |
365 | | / | /index | |
366 | | /books | /books/index | |
367 | | /books/list | /books/list | |
368 | '-------------------------------------+--------------------------------------' |
369 | |
370 | [debug] Loaded Chained actions: |
371 | .-------------------------------------+--------------------------------------. |
372 | | Path Spec | Private | |
373 | +-------------------------------------+--------------------------------------+ |
374 | | /books/url_create/*/*/* | /books/url_create | |
375 | '-------------------------------------+--------------------------------------' |
376 | |
377 | C<url_create> has disappeared form the "Loaded Path actions" section |
378 | but it now shows up under the newly created "Loaded Chained actions" |
379 | section. And, the "/*/*/*" portion clearly shows that we have |
380 | specified that 3 arguments are required. |
381 | |
382 | As with our non-chained version of C<url_create>, use your browser to |
383 | enter the following URL: |
384 | |
385 | http://localhost:3000/books/url_create/TCPIP_Illustrated_Vol-2/5/4 |
386 | |
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, you should find that there |
390 | are now seven books shown (two copies of TCPIP_Illustrated_Vol-2). |
391 | |
392 | |
393 | =head2 Refactor to Use a "Base" Method to Start The Chains |
394 | |
395 | Let's make a quick update to our initial Chained action to show a |
396 | little more of the power of chaining. First, open |
397 | C<lib/MyApp/Controller/Books.pm> in your editor and add the following |
398 | method: |
399 | |
400 | =head2 base |
401 | |
402 | Can place common logic to start chained dispatch here |
403 | |
404 | =cut |
405 | |
406 | sub base :Chained('/') :PathPart('books') :CaptureArgs(0) { |
407 | my ($self, $c) = @_; |
408 | |
409 | $c->log->debug('*** INSIDE BASE METHOD ***'); |
410 | } |
411 | |
412 | Although we only use the C<base> method to create a log message, we |
413 | could obviously do any number of things here. For example, if your |
414 | controller always needs a book ID as it's first argument, you could |
415 | have the base method capture that argument (with C<:CaptureArgs(1)>) |
416 | and use it to pull the book object with that ID from the database and |
417 | leave it in the stash for later parts of your chains to then act upon. |
418 | |
419 | In our case, let's modify our C<url_create> method to first call |
420 | C<base>. Open up C<lib/MyApp/Controller/Books.pm> and edit the |
421 | declaration for C<url_create> to match the following: |
422 | |
423 | sub url_create :Chained('base') :PathPart('url_create') :Args(3) { |
424 | |
425 | Next, let's try out our refactored chain. Restart the development |
426 | server and notice that our "Loaded Chained actions" section has |
427 | changed slightly: |
428 | |
429 | [debug] Loaded Chained actions: |
430 | .-------------------------------------+--------------------------------------. |
431 | | Path Spec | Private | |
432 | +-------------------------------------+--------------------------------------+ |
433 | | /books/url_create/*/*/* | /books/base (0) | |
434 | | | => /books/url_create | |
435 | '-------------------------------------+--------------------------------------' |
436 | |
437 | The "Path Spec" is the same, but now it maps to two Private actions as |
438 | we would expect. |
439 | |
440 | Once again, enter the following URL into your browser: |
441 | |
442 | http://localhost:3000/books/url_create/TCPIP_Illustrated_Vol-2/5/4 |
443 | |
444 | The same "Added book 'TCPIP_Illustrated_Vol-2' by 'Stevens' with a |
445 | rating of 5." and dump of the new book object should appear. Also |
446 | notice the extra debug message in the development server output from |
447 | the C<base> method. Click the "Return to list" link, you should find |
448 | that there are now eight books shown. |
d442cc9f |
449 | |
450 | |
451 | =head1 MANUALLY BUILDING A CREATE FORM |
452 | |
453 | Although the C<url_create> action in the previous step does begin to |
454 | reveal the power and flexibility of both Catalyst and DBIC, it's |
455 | obviously not a very realistic example of how users should be expected |
456 | to enter data. This section begins to address that concern. |
457 | |
458 | |
459 | =head2 Add Method to Display The Form |
460 | |
461 | Edit C<lib/MyApp/Controller/Books.pm> and add the following method: |
462 | |
463 | =head2 form_create |
464 | |
465 | Display form to collect information for book to create |
466 | |
467 | =cut |
468 | |
89d3dae9 |
469 | sub form_create :Chained('base') :PathPart('form_create') :Args(0) { |
d442cc9f |
470 | my ($self, $c) = @_; |
471 | |
472 | # Set the TT template to use |
473 | $c->stash->{template} = 'books/form_create.tt2'; |
474 | } |
475 | |
476 | This action simply invokes a view containing a book creation form. |
477 | |
1390ef0e |
478 | |
d442cc9f |
479 | =head2 Add a Template for the Form |
480 | |
481 | Open C<root/src/books/form_create.tt2> in your editor and enter: |
482 | |
483 | [% META title = 'Manual Form Book Create' -%] |
484 | |
8a7c5151 |
485 | <form method="post" action="[% c.uri_for('form_create_do') %]"> |
d442cc9f |
486 | <table> |
487 | <tr><td>Title:</td><td><input type="text" name="title"></td></tr> |
488 | <tr><td>Rating:</td><td><input type="text" name="rating"></td></tr> |
489 | <tr><td>Author ID:</td><td><input type="text" name="author_id"></td></tr> |
490 | </table> |
491 | <input type="submit" name="Submit" value="Submit"> |
492 | </form> |
493 | |
494 | Note that we have specified the target of the form data as |
495 | C<form_create_do>, the method created in the section that follows. |
496 | |
1390ef0e |
497 | |
d442cc9f |
498 | =head2 Add a Method to Process Form Values and Update Database |
499 | |
500 | Edit C<lib/MyApp/Controller/Books.pm> and add the following method to |
501 | save the form information to the database: |
502 | |
503 | =head2 form_create_do |
504 | |
505 | Take information from form and add to database |
506 | |
507 | =cut |
508 | |
89d3dae9 |
509 | sub form_create_do :Chained('base') :PathPart('form_create_do') :Args(0) { |
d442cc9f |
510 | my ($self, $c) = @_; |
511 | |
512 | # Retrieve the values from the form |
513 | my $title = $c->request->params->{title} || 'N/A'; |
514 | my $rating = $c->request->params->{rating} || 'N/A'; |
515 | my $author_id = $c->request->params->{author_id} || '1'; |
516 | |
517 | # Create the book |
d0496197 |
518 | my $book = $c->model('DB::Books')->create({ |
d442cc9f |
519 | title => $title, |
520 | rating => $rating, |
521 | }); |
522 | # Handle relationship with author |
523 | $book->add_to_book_authors({author_id => $author_id}); |
524 | |
525 | # Store new model object in stash |
526 | $c->stash->{book} = $book; |
527 | |
528 | # Avoid Data::Dumper issue mentioned earlier |
529 | # You can probably omit this |
530 | $Data::Dumper::Useperl = 1; |
531 | |
532 | # Set the TT template to use |
533 | $c->stash->{template} = 'books/create_done.tt2'; |
534 | } |
535 | |
536 | |
537 | =head2 Test Out The Form |
538 | |
539 | If the application is still running from before, use C<Ctrl-C> to kill |
540 | it. Then restart the server: |
541 | |
542 | $ script/myapp_server.pl |
543 | |
89d3dae9 |
544 | Notice that the server startup log reflects the two new chained |
545 | methods that we added: |
546 | |
547 | [debug] Loaded Chained actions: |
548 | .-------------------------------------+--------------------------------------. |
549 | | Path Spec | Private | |
550 | +-------------------------------------+--------------------------------------+ |
551 | | /books/form_create | /books/base (0) | |
552 | | | => /books/form_create | |
553 | | /books/form_create_do | /books/base (0) | |
554 | | | => /books/form_create_do | |
555 | | /books/url_create/*/*/* | /books/base (0) | |
556 | | | => /books/url_create | |
557 | '-------------------------------------+--------------------------------------' |
558 | |
d442cc9f |
559 | Point your browser to L<http://localhost:3000/books/form_create> and |
560 | enter "TCP/IP Illustrated, Vol 3" for the title, a rating of 5, and an |
1390ef0e |
561 | author ID of 4. You should then see the output of the same |
d442cc9f |
562 | C<create_done.tt2> template seen in earlier examples. Finally, click |
563 | "Return to list" to view the full list of books. |
564 | |
565 | B<Note:> Having the user enter the primary key ID for the author is |
566 | obviously crude; we will address this concern with a drop-down list in |
3533daff |
567 | Part 9. |
d442cc9f |
568 | |
569 | |
570 | =head1 A SIMPLE DELETE FEATURE |
571 | |
572 | Turning our attention to the delete portion of CRUD, this section |
573 | illustrates some basic techniques that can be used to remove information |
574 | from the database. |
575 | |
576 | |
577 | =head2 Include a Delete Link in the List |
578 | |
579 | Edit C<root/src/books/list.tt2> and update it to the following (two |
580 | sections have changed: 1) the additional '<th>Links</th>' table header, |
581 | and 2) the four lines for the Delete link near the bottom). |
582 | |
583 | [% # This is a TT comment. The '-' at the end "chomps" the newline. You won't -%] |
584 | [% # see this "chomping" in your browser because HTML ignores blank lines, but -%] |
585 | [% # it WILL eliminate a blank line if you view the HTML source. It's purely -%] |
586 | [%- # optional, but both the beginning and the ending TT tags support chomping. -%] |
587 | |
588 | [% # Provide a title to root/lib/site/header -%] |
589 | [% META title = 'Book List' -%] |
590 | |
591 | <table> |
592 | <tr><th>Title</th><th>Rating</th><th>Author(s)</th><th>Links</th></tr> |
593 | [% # Display each book in a table row %] |
594 | [% FOREACH book IN books -%] |
595 | <tr> |
596 | <td>[% book.title %]</td> |
597 | <td>[% book.rating %]</td> |
598 | <td> |
599 | [% # First initialize a TT variable to hold a list. Then use a TT FOREACH -%] |
600 | [% # loop in 'side effect notation' to load just the last names of the -%] |
601 | [% # authors into the list. Note that the 'push' TT vmethod does not -%] |
602 | [% # a value, so nothing will be printed here. But, if you have something -%] |
603 | [% # in TT that does return a method and you don't want it printed, you -%] |
604 | [% # can: 1) assign it to a bogus value, or 2) use the CALL keyword to -%] |
605 | [% # call it and discard the return value. -%] |
606 | [% tt_authors = [ ]; |
607 | tt_authors.push(author.last_name) FOREACH author = book.authors %] |
608 | [% # Now use a TT 'virtual method' to display the author count in parens -%] |
609 | ([% tt_authors.size %]) |
610 | [% # Use another TT vmethod to join & print the names & comma separators -%] |
611 | [% tt_authors.join(', ') %] |
612 | </td> |
613 | <td> |
614 | [% # Add a link to delete a book %] |
8a7c5151 |
615 | <a href="[% c.uri_for('delete', book.id) %]">Delete</a> |
d442cc9f |
616 | </td> |
617 | </tr> |
618 | [% END -%] |
619 | </table> |
620 | |
fe01b24f |
621 | The additional code is obviously designed to add a new column to the |
622 | right side of the table with a C<Delete> "button" (for simplicity, |
623 | links will be used instead of full HTML buttons). |
624 | |
625 | B<Note:> You should use more than just a simple link with your |
626 | applications. Consider using some sort of of confirmation page |
627 | (typically with unique actions in your controller for both the |
628 | confirmation and the actual delete operation). Also, you should try |
629 | to use an HTTP POST operation (versus the GET used here) for |
630 | operations that change the state of your application (e.g., the |
631 | database). |
d442cc9f |
632 | |
1390ef0e |
633 | |
d442cc9f |
634 | =head2 Add a Delete Action to the Controller |
635 | |
636 | Open C<lib/MyApp/Controller/Books.pm> in your editor and add the |
637 | following method: |
638 | |
1390ef0e |
639 | =head2 delete |
d442cc9f |
640 | |
641 | Delete a book |
642 | |
643 | =cut |
644 | |
89d3dae9 |
645 | sub delete :Chained('base') :PathPart('delete') :Args(1) { |
d442cc9f |
646 | # $id = primary key of book to delete |
647 | my ($self, $c, $id) = @_; |
648 | |
649 | # Search for the book and then delete it |
d0496197 |
650 | $c->model('DB::Books')->search({id => $id})->delete_all; |
d442cc9f |
651 | |
652 | # Set a status message to be displayed at the top of the view |
653 | $c->stash->{status_msg} = "Book deleted."; |
654 | |
655 | # Forward to the list action/method in this controller |
656 | $c->forward('list'); |
657 | } |
658 | |
659 | This method first deletes the book with the specified primary key ID. |
660 | However, it also removes the corresponding entry from the |
661 | C<book_authors> table. Note that C<delete_all> was used instead of |
662 | C<delete>: whereas C<delete_all> also removes the join table entries in |
663 | C<book_authors>, C<delete> does not (only use C<delete_all> if you |
664 | really need the cascading deletes... otherwise you are wasting resources). |
665 | |
666 | Then, rather than forwarding to a "delete done" page as we did with the |
667 | earlier create example, it simply sets the C<status_msg> to display a |
668 | notification to the user as the normal list view is rendered. |
669 | |
670 | The C<delete> action uses the context C<forward> method to return the |
671 | user to the book list. The C<detach> method could have also been used. |
672 | Whereas C<forward> I<returns> to the original action once it is |
673 | completed, C<detach> does I<not> return. Other than that, the two are |
674 | equivalent. |
675 | |
676 | |
677 | =head2 Try the Delete Feature |
678 | |
679 | If the application is still running from before, use C<Ctrl-C> to kill |
680 | it. Then restart the server: |
681 | |
682 | $ script/myapp_server.pl |
683 | |
89d3dae9 |
684 | The C<delete> method now appears in the "Loaded Chained actions" section |
685 | of the startup debug output: |
686 | |
687 | [debug] Loaded Chained actions: |
688 | .-------------------------------------+--------------------------------------. |
689 | | Path Spec | Private | |
690 | +-------------------------------------+--------------------------------------+ |
691 | | /books/delete/* | /books/base (0) | |
692 | | | => /books/delete | |
693 | | /books/form_create | /books/base (0) | |
694 | | | => /books/form_create | |
695 | | /books/form_create_do | /books/base (0) | |
696 | | | => /books/form_create_do | |
697 | | /books/url_create/*/*/* | /books/base (0) | |
698 | | | => /books/url_create | |
699 | '-------------------------------------+--------------------------------------' |
700 | |
d442cc9f |
701 | Then point your browser to L<http://localhost:3000/books/list> and click |
702 | the "Delete" link next to the first "TCPIP_Illustrated_Vol-2". A green |
703 | "Book deleted" status message should display at the top of the page, |
704 | along with a list of the eight remaining books. |
705 | |
706 | |
707 | =head2 Fixing a Dangerous URL |
708 | |
5edc2aae |
709 | Note the URL in your browser once you have performed the deletion in the |
d442cc9f |
710 | prior step -- it is still referencing the delete action: |
711 | |
712 | http://localhost:3000/books/delete/6 |
713 | |
714 | What if the user were to press reload with this URL still active? In |
715 | this case the redundant delete is harmless, but in other cases this |
716 | could clearly be extremely dangerous. |
717 | |
718 | We can improve the logic by converting to a redirect. Unlike |
719 | C<$c-E<gt>forward('list'))> or C<$c-E<gt>detach('list'))> that perform |
720 | a server-side alteration in the flow of processing, a redirect is a |
3533daff |
721 | client-side mechanism that causes the browser to issue an entirely |
d442cc9f |
722 | new request. As a result, the URL in the browser is updated to match |
723 | the destination of the redirection URL. |
724 | |
725 | To convert the forward used in the previous section to a redirect, |
726 | open C<lib/MyApp/Controller/Books.pm> and edit the existing |
727 | C<sub delete> method to match: |
728 | |
729 | =head2 delete |
730 | |
731 | Delete a book |
732 | |
733 | =cut |
734 | |
89d3dae9 |
735 | sub delete :Chained('base') :PathPart('delete') :Args(1) { |
d442cc9f |
736 | # $id = primary key of book to delete |
737 | my ($self, $c, $id) = @_; |
738 | |
739 | # Search for the book and then delete it |
d0496197 |
740 | $c->model('DB::Books')->search({id => $id})->delete_all; |
d442cc9f |
741 | |
742 | # Set a status message to be displayed at the top of the view |
743 | $c->stash->{status_msg} = "Book deleted."; |
744 | |
745 | # Redirect the user back to the list page |
746 | $c->response->redirect($c->uri_for('/books/list')); |
747 | } |
748 | |
749 | |
750 | =head2 Try the Delete and Redirect Logic |
751 | |
752 | Restart the development server and point your browser to |
89d3dae9 |
753 | L<http://localhost:3000/books/list> and delete the first copy of the |
754 | remaining two "TCPIP_Illustrated_Vol-2" books. The URL in your |
755 | browser should return to the L<http://localhost:3000/books/list> URL, |
756 | so that is an improvement, but notice that I<no green "Book deleted" |
757 | status message is displayed>. Because the stash is reset on every |
758 | request (and a redirect involves a second request), the C<status_msg> |
759 | is cleared before it can be displayed. |
d442cc9f |
760 | |
761 | |
762 | =head2 Using C<uri_for> to Pass Query Parameters |
763 | |
89d3dae9 |
764 | There are several ways to pass information across a redirect. One |
765 | option is to use the C<flash> technique that we will see in Part 5 of |
766 | the tutorial; however, here we will pass the information via query |
767 | parameters on the redirect itself. Open |
768 | C<lib/MyApp/Controller/Books.pm> and update the existing C<sub delete> |
769 | method to match the following: |
d442cc9f |
770 | |
771 | =head2 delete |
772 | |
773 | Delete a book |
774 | |
775 | =cut |
776 | |
89d3dae9 |
777 | sub delete :Chained('base') :PathPart('delete') :Args(1) { |
d442cc9f |
778 | # $id = primary key of book to delete |
779 | my ($self, $c, $id) = @_; |
780 | |
781 | # Search for the book and then delete it |
d0496197 |
782 | $c->model('DB::Books')->search({id => $id})->delete_all; |
d442cc9f |
783 | |
784 | # Redirect the user back to the list page with status msg as an arg |
785 | $c->response->redirect($c->uri_for('/books/list', |
786 | {status_msg => "Book deleted."})); |
787 | } |
788 | |
789 | This modification simply leverages the ability of C<uri_for> to include |
790 | an arbitrary number of name/value pairs in a hash reference. Next, we |
89d3dae9 |
791 | need to update C<root/src/wrapper.tt2> to handle C<status_msg> as a |
d442cc9f |
792 | query parameter: |
793 | |
1390ef0e |
794 | ... |
d442cc9f |
795 | <div id="content"> |
1390ef0e |
796 | [%# Status and error messages %] |
797 | <span class="message">[% status_msg || c.request.params.status_msg %]</span> |
798 | <span class="error">[% error_msg %]</span> |
799 | [%# This is where TT will stick all of your template's contents. -%] |
800 | [% content %] |
801 | </div><!-- end content --> |
802 | ... |
803 | |
804 | Although the sample above only shows the C<content> div, leave the |
805 | rest of the file intact -- the only change we made to the C<wrapper.tt2> |
806 | was to add "C<|| c.request.params.status_msg>" to the |
807 | C<E<lt>span class="message"E<gt>> line. |
d442cc9f |
808 | |
809 | |
810 | =head2 Try the Delete and Redirect With Query Param Logic |
811 | |
812 | Restart the development server and point your browser to |
813 | L<http://localhost:3000/books/list>. Then delete the remaining copy |
814 | of "TCPIP_Illustrated_Vol-2". The green "Book deleted" status message |
815 | should return. |
816 | |
89d3dae9 |
817 | B<NOTE:> Another popular method for maintaining server-side |
818 | information across a redirect is to use the C<flash> technique we |
819 | discuss in the next part of the tutorial, |
820 | L<Authentication|Catalyst::Manual::Tutorial::Authentication>. While |
821 | C<flash> is a "slicker" mechanism in that it's all handled by the |
822 | server and doesn't "pollute" your URLs, B<it is important to note that |
823 | C<flash> can lead to situations where the wrong information shows up |
824 | in the wrong browser window if the user has multiple windows or |
825 | browser tabs open.> (For example, Window A causes something to be |
826 | placed in the stash, but before that window performs a redirect, |
827 | Window B makes a request to the server and gets the status information |
828 | that should really go to Window A.) For this reason, you may wish |
829 | to use the "query param" technique shown here in your applications. |
d442cc9f |
830 | |
831 | |
832 | =head1 AUTHOR |
833 | |
834 | Kennedy Clark, C<hkclark@gmail.com> |
835 | |
836 | Please report any errors, issues or suggestions to the author. The |
837 | most recent version of the Catalyst Tutorial can be found at |
82ab4bbf |
838 | L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/>. |
d442cc9f |
839 | |
45c7830f |
840 | Copyright 2006-2008, Kennedy Clark, under Creative Commons License |
95674086 |
841 | (L<http://creativecommons.org/licenses/by-sa/3.0/us/>). |