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=ac5261dfbdd4d00f118c9607312dcb369285c241;hp=fa5a5a9c0293b82e6edeaa5032ac13e401df1930;hb=c16b23ababd7cc92688183b0c72480966a7876b4;hpb=1390ef0ecd30a0dcfe59f212353ed81094fdf64a diff --git a/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod b/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod index fa5a5a9..ac5261d 100644 --- a/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod +++ b/lib/Catalyst/Manual/Tutorial/BasicCRUD.pod @@ -72,7 +72,7 @@ of tool to automate the process. You get less control, but it's quick and easy. For example, see L, L, and -L. +L. You can checkout the source code for this example from the catalyst subversion repository as per the instructions in @@ -209,10 +209,11 @@ 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 -'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: +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 as it was returned by DBIC. You should also see the following +DBIC debug messages displayed in the development server log messages +if you have DBIC_TRACE set: INSERT INTO books (rating, title) VALUES (?, ?): `5', `TCPIP_Illustrated_Vol-2' INSERT INTO book_authors (author_id, book_id) VALUES (?, ?): `4', `6' @@ -228,15 +229,232 @@ If you then click the "Return to list" link, you should find that there are now six books shown (if necessary, Shift+Reload or Ctrl+Reload your browser at the C page). -Then I so that we have some extras for -our delete logic that will be coming up soon. Enter the same URL above -two more times (or refresh your browser twice if it still contains this -URL): + +=head1 CONVERT TO A CHAINED ACTION + +Although the example above uses the same C action type for the +method that we saw in the previous part of the tutorial, there is an +alternate approach that allows us to be more specific while also +paving the way for more advanced capabilities. Change the method +declaration for C in C you +entered above to match the following: + + sub url_create :Chained('/') :PathPart('books/url_create') :Args(3) { + +This converts the method to take advantage of the Chained +action/dispatch type. Chaining let's you have a single URL +automatically dispatch to several controller methods, each of which +can have precise control over the number of arguments that it will +receive. A chain can essentially be thought of having three parts -- +a beginning, a middle and an end. The bullets below summarize the key +points behind each of these parts of a chain: + + +=over 4 + + +=item * + +Beginning + +=over 4 + +=item * + +B" to start a chain> + +=item * + +Get arguments through C + +=item * + +Specify the path to match with C + +=back + + +=item * + +Middle + +=over 4 + +=item * + +Link to previous part of the chain with C<:Chained('_name_')> + +=item * + +Get arguments through C + +=item * + +Specify the path to match with C + +=back + + +=item * + +End + +=over 4 + +=item * + +Link to previous part of the chain with C<:Chained('_name_')> + +=item * + +B," use "C" instead to end a chain> + +=item * + +Specify the path to match with C + +=back + + +=back + +In our C method above, we have combined all 3 parts into a +single method: C<:Chained('/')> to start the chain, +C<:PathPart('books/url_create')> to specify the base URL to match, +along with C<:Args(3)> to capture exactly 3 arguments and also end the +chain. + +As we will see shortly, a chain can consist of as many "links" as you +wish, with each part capturing some arguments and doing some work +along the way. We will continue to use the Chained action type in this +part of the tutorial and explore slightly more advanced capabilities +with the base method and delete feature below. But Chained dispatch +is capable of far more. For additional information, see +L, +L, +and the 2006 advent calendar entry on the subject: +L. + + +=head2 Try the Chained Action + +If you look back at the development server startup logs from your +initial version of the C method (the one using the +C<:Local> attribute), you will notice that it produced output similar +to the following: + + [debug] Loaded Path actions: + .-------------------------------------+--------------------------------------. + | Path | Private | + +-------------------------------------+--------------------------------------+ + | / | /default | + | / | /index | + | /books | /books/index | + | /books/list | /books/list | + | /books/url_create | /books/url_create | + '-------------------------------------+--------------------------------------' + +Now start the development server with our basic chained method in +place and the startup debug output should change to something along +the lines of the following: + + [debug] Loaded Path actions: + .-------------------------------------+--------------------------------------. + | Path | Private | + +-------------------------------------+--------------------------------------+ + | / | /default | + | / | /index | + | /books | /books/index | + | /books/list | /books/list | + '-------------------------------------+--------------------------------------' + + [debug] Loaded Chained actions: + .-------------------------------------+--------------------------------------. + | Path Spec | Private | + +-------------------------------------+--------------------------------------+ + | /books/url_create/*/*/* | /books/url_create | + '-------------------------------------+--------------------------------------' + +C has disappeared form the "Loaded Path actions" section +but it now shows up under the newly created "Loaded Chained actions" +section. And, the "/*/*/*" portion clearly shows our requirement for +three arguments. + +As with our non-chained version of C, use your browser to +enter the following URL: + + http://localhost:3000/books/url_create/TCPIP_Illustrated_Vol-2/5/4 + +You should see the same "Added book 'TCPIP_Illustrated_Vol-2' by +'Stevens' with a rating of 5." along with a dump of the new book model +object. Click the "Return to list" link, you should find that there +are now seven books shown (two copies of TCPIP_Illustrated_Vol-2). + + +=head2 Refactor to Use a "Base" Method to Start the Chains + +Let's make a quick update to our initial Chained action to show a +little more of the power of chaining. First, open +C in your editor and add the following +method: + + =head2 base + + Can place common logic to start chained dispatch here + + =cut + + sub base :Chained('/') :PathPart('books') :CaptureArgs(0) { + my ($self, $c) = @_; + + # Store the ResultSet in stash so it's available for other methods + $c->stash->{resultset} = $c->model('DB::Books'); + + # Print a message to the debug log + $c->log->debug('*** INSIDE BASE METHOD ***'); + } + +Here we print a log message and store the DBIC ResultSet in +C<$c-Estash-E{resultset}> so that it's automatically available +for other actions that chain off C. If your controller always +needs a book ID as it's first argument, you could have the base method +capture that argument (with C<:CaptureArgs(1)>) and use it to pull the +book object with C<-Efind($id)> and leave it in the stash for +later parts of your chains to then act upon. Because we have several +actions that don't need to retrieve a book (such as the C +we are working with now), we will instead add that functionality +to a common C action shortly. + +As for C, let's modify it to first dispatch to C. +Open up C and edit the declaration for +C to match the following: + + sub url_create :Chained('base') :PathPart('url_create') :Args(3) { + +Next, try out the refactored chain by restarting the development +server. Notice that our "Loaded Chained actions" section has changed +slightly: + + [debug] Loaded Chained actions: + .-------------------------------------+--------------------------------------. + | Path Spec | Private | + +-------------------------------------+--------------------------------------+ + | /books/url_create/*/*/* | /books/base (0) | + | | => /books/url_create | + '-------------------------------------+--------------------------------------' + +The "Path Spec" is the same, but now it maps to two Private actions as +we would expect. + +Once again, enter the following URL into your browser: http://localhost:3000/books/url_create/TCPIP_Illustrated_Vol-2/5/4 -You should be able to click "Return to list" and now see 3 copies of -"TCP_Illustrated_Vol-2". +The same "Added book 'TCPIP_Illustrated_Vol-2' by 'Stevens' with a +rating of 5" message and dump of the new book object should appear. +Also notice the extra debug message in the development server output +from the C method. Click the "Return to list" link, you should +find that there are now eight books shown. =head1 MANUALLY BUILDING A CREATE FORM @@ -257,7 +475,7 @@ Edit C and add the following method: =cut - sub form_create : Local { + sub form_create :Chained('base') :PathPart('form_create') :Args(0) { my ($self, $c) = @_; # Set the TT template to use @@ -297,7 +515,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 @@ -332,6 +550,21 @@ 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 see the output of the same @@ -352,7 +585,7 @@ from the database. =head2 Include a Delete Link in the List -Edit C and update it to the following (two +Edit C and update it to match the following (two sections have changed: 1) the additional 'Links' table header, and 2) the four lines for the Delete link near the bottom). @@ -388,15 +621,104 @@ 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). + +Also notice that we are using a more advanced form of C than +we have seen before. Here we use C<$c-Econtroller- +Eaction_for> to automatically generate a URI appropriate for that +action based on the method we want to link to while inserting the +C value into the appropriate place. Now, if you ever change +C<:PathPart('delete')> in your controller method to +C<:PathPart('kill')>, then your links will automatically update +without any changes to your .tt2 template file. As long as the name +of your method does not changed ("delete" here), then your links will +still be correct. There are a few shortcuts and options when using +C: + +=over 4 + +=item * + +If you are referring to a method in the current controller, you can +use C<$self-Eaction_for('_method_name_')>. + +=item * + +If you are referring to a method in a different controller, you need +to include that controller's name as an argument to C, as in +C<$c-Econtroller('_controller_name_')-Eaction_for('_method_name_')>. + +=back + +B In practice you should B use a GET request to delete a +record -- always use POST for actions that will modify data. We are +doing it here for illustrative and simplicity purposes only. + + +=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 the book lookup code. 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: + + =head2 object + + Fetch the specified book object based on the book ID and store + it in the stash + + =cut + + sub object :Chained('base') :PathPart('id') :CaptureArgs(1) { + # $id = primary key of book to delete + 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 =E 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 @@ -410,12 +732,12 @@ following method: =cut - sub delete : Local { - # $id = primary key of book to delete - my ($self, $c, $id) = @_; + sub delete :Chained('object') :PathPart('delete') :Args(0) { + 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."; @@ -424,12 +746,9 @@ 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 with a cascading delete. 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 @@ -447,12 +766,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 @@ -462,9 +804,11 @@ prior step -- it is still referencing the delete action: http://localhost:3000/books/delete/6 -What if the user were to press reload with this URL still active? In -this case the redundant delete is harmless, but in other cases this -could clearly be extremely dangerous. +What if the user were to press reload with this URL still active? In +this case the redundant delete is harmless (although it does generate +an exception screen, it doesn't perform any undesirable actions on the +application or database), but in other cases this could clearly be +extremely dangerous. We can improve the logic by converting to a redirect. Unlike C<$c-Eforward('list'))> or C<$c-Edetach('list'))> that perform @@ -477,47 +821,50 @@ 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 { - # $id = primary key of book to delete - my ($self, $c, $id) = @_; + sub delete :Chained('object') :PathPart('delete') :Args(0) { + 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."; - # Redirect the user back to the list page - $c->response->redirect($c->uri_for('/books/list')); + # Redirect the user back to the list page. Note the use + # of $self->action_for as earlier in this section (BasicCRUD) + $c->response->redirect($c->uri_for($self->action_for('list'))); } =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 @@ -525,21 +872,21 @@ C method to match the following: =cut - sub delete : Local { - # $id = primary key of book to delete - my ($self, $c, $id) = @_; + sub delete :Chained('object') :PathPart('delete') :Args(0) { + 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; # Redirect the user back to the list page with status msg as an arg - $c->response->redirect($c->uri_for('/books/list', + $c->response->redirect($c->uri_for($self->action_for('list'), {status_msg => "Book deleted."})); } 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: ... @@ -561,18 +908,479 @@ 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 EXPLORING THE POWER OF DBIC + +In this section we will explore some additional capabilities offered +by DBIx::Class. Although these features have relatively little to do +with Catalyst per se, you will almost certainly want to take advantage +of them in your applications. + + +=head2 Convert to DBIC "load_namespaces" + +If you look back at +L you will recall that we load our DBIC Result Classes +(Books.pm, Authors.pm and BookAuthors.pm) with in +C with the C feature. Although +this method is perfectly valid, the DBIC community has migrated to a +newer C technique because it more easily supports a +variety of advanced features. Since we want to explore some of these +features below, let's first migrate our configuration over to use +C. + +If you are following along in Ubuntu 8.10, you will need to +upgrade your version of +L +to 0.23 or higher. To do this, we can install directly from CPAN: + + $ cpan Catalyst::Model::DBIC::Schema + +Then make sure you are running an appropriate version: + + $ perl -MCatalyst::Model::DBIC::Schema -e \ + 'print "$Catalyst::Model::DBIC::Schema::VERSION\n"' + 0.23 + +Make sure you get version 0.22 or higher. + +B Ubuntu will automatically "do the right thing" and use the +module we installed from CPAN and ignore the older version we picked +up via the C command. If you are using a different +environment, you will need to make sure you are using v0.22 or higher +with the command above. + +While we are at it, let's install a few other modules from CPAN for +some of the other work we will be doing below: + + $ cpan Time::Warp DBICx::TestDatabase \ + DBIx::Class::DynamicDefault DBIx::Class::TimeStamp + +Next, we need to delete the existing C so that +the Catalyst DBIC helper will recreate it. Then we re-generate +the model and schema information: + + $ rm lib/MyApp/Schema.pm + $ script/myapp_create.pl model DB DBIC::Schema MyApp::Schema \ + create=static components=TimeStamp dbi:SQLite:myapp.db + exists "/root/dev/MyApp/script/../lib/MyApp/Model" + exists "/root/dev/MyApp/script/../t" + Dumping manual schema for MyApp::Schema to directory /root/dev/MyApp/script/../lib ... + Schema dump completed. + exists "/root/dev/MyApp/script/../lib/MyApp/Model/DB.pm" + $ + $ ls lib/MyApp/Schema + Authors.pm BookAuthors.pm Books.pm Result + $ ls lib/MyApp/Schema/Result + Authors.pm BookAuthors.pm Books.pm + +Notice that we now have a duplicate set of Result Class files. With +the newer C feature, DBIC automatically looks for +your Result Class files in a subdirectory of the Schema directory +called C (the files in C were already there +from Part 3 of the tutorial; the files in C +are new). + +If you are using SQLite, you will need to manually re-enter the +relationship configuration as we did in Part 3 of the tutorial (if you +are using different database, the relationships might have been auto- +generated by Schema::Loader). One option is to use the following +command-line perl script to migrate the information across +automatically: + + $ cd lib/MyApp/Schema + $ perl -MIO::All -e 'for (@ARGV) { my $s < io($_); $s =~ s/.*\n\# You can replace.*?\n//s; + $s =~ s/'MyApp::Schema::/'MyApp::Schema::Result::/g; my $d < io("Result/$_"); + $d =~ s/1;\n?//; "$d$s" > io("Result/$_"); }' *.pm + $ cd ../../.. + +If you prefer, you can do the migration by hand using "cut and paste" +from the files in C (or from +L) +to the corresponding files in C. If you take +this approach, be sure to add C<::Result> to the end of +C in all three files (for example, in C, the +"peer class" in the C relationship needs to be changed from +C to C). + +Now we can remove the original set of Result Class files that we no +longer need: + + $ rm lib/MyApp/Schema/*.pm + $ ls lib/MyApp/Schema + Result + +Finally, test the application to be sure everything is still +working under our new configuration. Use the +C