Read, Update, and Delete (CRUD) of C<Book> objects. Note that the
'list' function in Chapter 2 already implements the Read portion of
CRUD (although Read normally refers to reading a single object; you
-could implement full read functionality using the techniques
+could implement full Read functionality using the techniques
introduced below). This section will focus on the Create and Delete
aspects of CRUD. More advanced capabilities, including full Update
functionality, will be addressed in Chapter 9.
L<CatalystX::CRUD|CatalystX::CRUD>, and
L<CatalystX::CRUD::YUI|CatalystX::CRUD::YUI>.
-You can checkout the source code for this example from the catalyst
-subversion repository as per the instructions in
+You can check out the source code for this example from the Catalyst
+Subversion repository as per the instructions in
L<Catalyst::Manual::Tutorial::Intro|Catalyst::Manual::Tutorial::Intro>.
# Assign the Book object to the stash for display in the view
$c->stash->{book} = $book;
- # This is a hack to disable XSUB processing in Data::Dumper
- # (it's used in the view). This is a work-around for a bug in
- # the interaction of some versions or Perl, Data::Dumper & DBIC.
- # You won't need this if you aren't using Data::Dumper (or if
- # you are running DBIC 0.06001 or greater), but adding it doesn't
- # hurt anything either.
- $Data::Dumper::Useperl = 1;
-
# Set the TT template to use
$c->stash->{template} = 'books/create_done.tt2';
}
it then sets the template that should handle this request.
-=head2 Include a Template for the C<url_create> Action:
+=head2 Include a Template for the 'url_create' Action:
Edit C<root/src/books/create_done.tt2> and then enter:
[% # Set the page title. META can 'go back' and set values in templates -%]
[% # that have been processed 'before' this template (here it's for -%]
- [% # root/lib/site/html and root/lib/site/header). Note that META on -%]
- [% # simple strings (e.g., no variable interpolation). -%]
+ [% # root/lib/site/html and root/lib/site/header). Note that META only -%]
+ [% # works on simple/static strings (i.e. there is no variable -%]
+ [% # interpolation). -%]
[% META title = 'Book Created' %]
[% # Output information about the record that was added. First title. -%]
from the examples in Chapter 3.
-=head2 Try the C<url_create> Feature
+=head2 Try the 'url_create' Feature
If the application is still running from before, use C<Ctrl-C> to kill
it. Then restart the server:
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
+action/dispatch type. Chaining lets 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
+a beginning, a middle, and an end. The bullets below summarize the key
points behind each of these parts of a chain:
=back
-In our C<url_create> 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.
+In our C<url_create> method above, we have combined all three parts into
+a single method: C<:Chained('/')> to start the chain,
+C<:PathPart('books/url_create')> to specify the base URL to match, and
+C<:Args(3)> to capture exactly three arguments and to 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
is capable of far more. For additional information, see
L<Catalyst::Manual::Intro/Action types>,
L<Catalyst::DispatchType::Chained|Catalyst::DispatchType::Chained>,
-and the 2006 advent calendar entry on the subject:
+and the 2006 Advent calendar entry on the subject:
L<http://www.catalystframework.org/calendar/2006/10>.
C<url_create> 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
+section. And the "/*/*/*" portion clearly shows our requirement for
three arguments.
As with our non-chained version of C<url_create>, use your browser to
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).
+object. Click the "Return to list" link, and you should find that there
+are now seven books shown (two copies of I<TCPIP_Illustrated_Vol-2>).
-=head2 Refactor to Use a "Base" Method to Start the Chains
+=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
Here we print a log message and store the DBIC ResultSet in
C<$c-E<gt>stash-E<gt>{resultset}> so that it's automatically available
for other actions that chain off C<base>. If your controller always
-needs a book ID as it's first argument, you could have the base method
+needs a book ID as its 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<-E<gt>find($id)> and leave it in the stash for
later parts of your chains to then act upon. Because we have several
http://localhost:3000/books/url_create/TCPIP_Illustrated_Vol-2/5/4
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.
+rating of 5." message and a dump of the new book object should appear.
Also notice the extra debug message in the development server output
-from the C<base> method. Click the "Return to list" link, you should
-find that there are now eight books shown.
+from the C<base> method. Click the "Return to list" link, and you
+should find that there are now eight books shown.
=head1 MANUALLY BUILDING A CREATE FORM
$c->stash->{template} = 'books/form_create.tt2';
}
-This action simply invokes a view containing a book creation form.
+This action simply invokes a view containing a form to create a book.
=head2 Add a Template for the Form
=head1 A SIMPLE DELETE FEATURE
-Turning our attention to the delete portion of CRUD, this section
+Turning our attention to the Delete portion of CRUD, this section
illustrates some basic techniques that can be used to remove information
from the database.
Edit C<root/src/books/list.tt2> and update it to match the following (two
sections have changed: 1) the additional '<th>Links</th>' table header,
-and 2) the four lines for the Delete link near the bottom).
+and 2) the four lines for the Delete link near the bottom):
[% # This is a TT comment. The '-' at the end "chomps" the newline. You won't -%]
[% # see this "chomping" in your browser because HTML ignores blank lines, but -%]
</table>
The additional code is obviously designed to add a new column to the
-right side of the table with a C<Delete> "button" (for simplicity,
-links will be used instead of full HTML buttons).
+right side of the table with a C<Delete> "button" (for simplicity, links
+will be used instead of full HTML buttons; in practice, anything that
+modifies data should be handled with a form sending a PUT request).
Also notice that we are using a more advanced form of C<uri_for> than
we have seen before. Here we use
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 change ("delete" here), then your links will
+of your method does not change (here, "delete"), then your links will
still be correct. There are a few shortcuts and options when using
C<action_for()>:
have the appropriate book waiting for it in
C<$c-E<gt>stash-E<gt>{object}>.
-Also note that we are using different technique for setting
-C<$c-E<gt>stash>. The advantage of this style is that it let's you
-set multiple stash variables at a time. For example:
+Also note that we are using a different technique for setting
+C<$c-E<gt>stash>. The advantage of this style is that it lets you set
+multiple stash variables at a time. For example:
$c->stash(object => $c->stash->{resultset}->find($id),
another_thing => 1);
another_thing => 1});
Either format works, but the C<$c-E<gt>stash(name =E<gt> value);>
-style is growing in popularity -- you may which to use it all
+style is growing in popularity -- you may wish to use it all
the time (even when you are only setting a single value).
be displayed.
-=head2 Using C<uri_for> to Pass Query Parameters
+=head2 Using 'uri_for' to Pass Query Parameters
There are several ways to pass information across a redirect. One
option is to use the C<flash> technique that we will see in Chapter 5
-of the tutorial; however, here we will pass the information via query
+of this tutorial; however, here we will pass the information via query
parameters on the redirect itself. Open
C<lib/MyApp/Controller/Books.pm> and update the existing C<sub delete>
method to match the following:
server and doesn't "pollute" your URLs, B<it is important to note that
C<flash> 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
+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
of them in your applications.
-=head2 Convert to DBIC "load_namespaces"
-
-If you look back at
-L<Catalyst::Manual::Tutorial::MoreCatalystBasics/Create Static DBIC
-Schema Files> you will recall that we load our DBIC Result Classes
-(Books.pm, Authors.pm and BookAuthors.pm) with in
-C<lib/MyApp/Schema.pm> with the C<load_classes> feature. Although
-this method is perfectly valid, the DBIC community has migrated to a
-newer C<load_namespaces> 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<load_namespaces>.
-
-If you are following along in Debian 5, you will need to upgrade your
-version of
-L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> to 0.23
-or higher. To do this, we can install directly from CPAN via the
-following command:
-
- $ sudo 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.23 or higher.
-
-B<Note:> Debian 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<aptitude> command. If you are using a different
-environment, you will need to make sure you are using v0.23 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<lib/MyApp/Schema.pm> 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<load_namespaces> feature, DBIC automatically looks for
-your Result Class files in a subdirectory of the Schema directory
-called C<Result> (the files in C<lib/MyApp/Schema> were already there
-from Chapter 3 of the tutorial; the files in C<lib/MyApp/Schema/Result>
-are new).
-
-If you are using SQLite, you will need to manually re-enter the
-relationship configuration as we did in Chapter 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<lib/MyApp/Schema> (or from
-L<Catalyst::Manual::Tutorial::MoreCatalystBasics/Updating the Generated DBIC Schema Files>)
-to the corresponding files in C<lib/MyApp/Schema/Result>. If you take
-this approach, be sure to add C<::Result> to the end of
-C<MyApp::Schema> in all three files (for example, in C<Books.pm>, the
-"peer class" in the C<has_many> relationship needs to be changed from
-C<MyApp::Schema::BookAuthors> to C<MyApp::Schema::BookAuthors::Result>).
-
-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<script/myapp_server.pl> command to start the development server and
-point your browser to L<http://localhost:3000/books/list>. Make sure
-you see the existing list of books.
-
-
=head2 Add Datetime Columns to Our Existing Books Table
Let's add two columns to our existing C<books> table to track when
and populate those fields with the current time.
-=head2 Update DBIC to Automatically Handle the Datetime Columns
+=head2 Update DBIx::Class to Automatically Handle the Datetime Columns
Next, we should re-run the DBIC helper to update the Result Classes
with the new fields:
exists "/root/dev/MyApp/script/../lib/MyApp/Model/DB.pm"
Notice that we modified our use of the helper slightly: we told
-it to include the L<DBIx::Class::Timestamp|DBIx::Class::Timestamp>
+it to include the L<DBIx::Class::TimeStamp|DBIx::Class::TimeStamp>
in the C<load_components> line of the Result Classes.
If you open C<lib/MyApp/Schema/Result/Books.pm> in your editor you
should see that the C<created> and C<updated> fields are now included
-in the call to add_columns(), but our relationship information below
+in the call to C<add_columns()>, but our relationship information below
the "C<# DO NOT MODIFY...>" line was automatically preserved.
While we have this file open, let's update it with some additional
{ data_type => 'datetime', set_on_create => 1, set_on_update => 1 },
);
-This will override the definition for these fields that Schema::Loader
-placed at the top of the file. The C<set_on_create> and
-C<set_on_update> options will cause DBIC to automatically update the
-timestamps in these columns whenever a row is created or modified.
+This will override the definition for these fields that Schema::Loader
+placed at the top of the file. The C<set_on_create> and
+C<set_on_update> options will cause DBIx::Class to automatically
+update the timestamps in these columns whenever a row is created or
+modified.
To test this out, restart the development server using the
C<DBIC_TRACE=1> option:
To illustrate the concept with a fairly simple example, let's create a
method that returns books added in the last 10 minutes. Start by
-making a directory where DBIC will look for our ResultSet Class:
+making a directory where DBIx::Class will look for our ResultSet Class:
mkdir lib/MyApp/Schema/ResultSet
=head2 Chaining ResultSets
-One of the most helpful and powerful features in DBIC is that it
-allows you to "chain together" a series of queries (note that this has
-nothing to do with the "Chained Dispatch" for Catalyst that we were
-discussing above). Because each ResultSet returns another ResultSet,
-you can take an initial query and immediately feed that into a second
-query (and so on for as many queries you need). And, because this
-technique carries over to the ResultSet Class feature we implemented
-in the previous section for our "canned search", we can combine the
-two capabilities. For example, let's add an action to our C<Books>
-controller that lists books that are both recent I<and> have "TCP" in
-the title. Open up C<lib/MyApp/Controller/Books.pm> and add the
-following method:
+One of the most helpful and powerful features in DBIx::Class is that
+it allows you to "chain together" a series of queries (note that this
+has nothing to do with the "Chained Dispatch" for Catalyst that we
+were discussing above). Because each ResultSet returns another
+ResultSet, you can take an initial query and immediately feed that
+into a second query (and so on for as many queries you need). Note
+that no matter how many ResultSets you chain together, the database
+itself will not be hit until you use a method that attempts to access
+the data. And, because this technique carries over to the ResultSet
+Class feature we implemented in the previous section for our "canned
+search", we can combine the two capabilities. For example, let's add
+an action to our C<Books> controller that lists books that are both
+recent I<and> have "TCP" in the title. Open up
+C<lib/MyApp/Controller/Books.pm> and add the following method:
=head2 list_recent_tcp
=head2 Adding Methods to Result Classes
-In the previous two sections we saw a good example of how we could use
-DBIC ResultSet Classes to clean up our code for an entire query (for
-example, our "canned searches" that filtered the entire query). We
-can do a similar improvement when working with individual rows as
-well. Whereas the ResultSet construct is used in DBIC to correspond
-to an entire query, the Result Class construct is used to represent a
-row. Therefore, we can add row-specific "helper methods" to our Result
-Classes stored in C<lib/MyApp/Schema/Result/>. For example, open
-C<lib/MyApp/Schema/Result/Authors.pm> and add the following method
-(as always, it must be above the closing "C<1;>"):
+In the previous two sections we saw a good example of how we could use
+DBIx::Class ResultSet Classes to clean up our code for an entire query
+(for example, our "canned searches" that filtered the entire query).
+We can do a similar improvement when working with individual rows as
+well. Whereas the ResultSet construct is used in DBIC to correspond
+to an entire query, the Result Class construct is used to represent a
+row. Therefore, we can add row-specific "helper methods" to our Result
+Classes stored in C<lib/MyApp/Schema/Result/>. For example, open
+C<lib/MyApp/Schema/Result/Authors.pm> and add the following method (as
+always, it must be above the closing "C<1;>"):
#
# Helper methods
projects / catagits/Catalyst-Manual.git / blobdiff