Removed Catalyst::Plugin::Authorization::ACL from Authorization.pod in favor of a "chained and model-based" approach at the urging of MST
More conversion to Chained dispatch
Lots of other small adjustments
5.7XXX XXXXXX
- Add a new section to BasicCRUD covering more advanced features of
DBIC ("EXPLORING THE POWER OF DBIC")
+ - Convert from Ubuntu to Debian 5 live CD as the recommended way to do
+ the tutorial (all code and examples updated and tested to match)
+ - Removed Catalyst::Plugin::Authorization::ACL from Authorization.pod
+ in favor of a "chained and model-based" approach
+ - More conversion to Chained dispatch
+ - Lots of other small adjustments
5.7018 2 Mar 2009
- Suggestions and fixes with thanks to mintywalker@gmail.com
=head1 Install C<HTML::FormFu>
-If you are following along in Ubuntu, it turns out that C<HTML::FormFu>
-is not yet available as a package at the time this was written. To
-install it with a combination of C<apt-get> packages and traditional
-CPAN modules, first use C<apt-get> to install most of the modules
-required by C<HTML::FormFu>:
-
- sudo apt-get install libtest-nowarnings-perl libdatetime-format-builder-perl \
- libdatetime-format-strptime-perl libdatetime-locale-perl \
- libhtml-tokeparser-simple-perl liblist-moreutils-perl \
- libregexp-copy-perl libregexp-common-perl libyaml-syck-perl libparams-util-perl \
- libcrypt-des-perl libcaptcha-recaptcha-perl libcrypt-cbc-perl \
- libreadonly-xs-perl libmoose-perl libregexp-assemble-perl
-
- ...
-
- sudo apt-get clean
+If you are following along in Debian 5, it turns out that some of the
+modules we need are not yet available as Debian packages at the time
+this was written. To install it with a combination of Debian packages
+and traditional CPAN modules, first use C<aptitude> to install most of
+the modules:
-Then use the following command to install directly from CPAN the modules
-that aren't available as Ubuntu/Debian packages via C<apt-get>:
+we need to install the
+L<HTML::FormFu|HTML::FormFu> package:
- sudo cpan File::ShareDir Task::Weaken Config::Any Test::Harness Test::Aggregate \
- boolean Test::MockTime DateTime::Format::Natural HTML::FormFu \
- Catalyst::Component::InstancePerContext Catalyst::Controller::HTML::FormFu \
- HTML::FormFu::Model::DBIC
-
- ...
-
- Is it OK to try to connect to the Internet? [yes] yes
-
+ sudo aptitude -y install libhtml-formfu-perl libmoose-perl \
+ libregexp-assemble-perl libhtml-formfu-model-dbic-perl
+
...
+ sudo aptitude clean
+
+Then use the following command to install directly from CPAN the modules
+that aren't available as Debian packages:
-B<Note:> If you are following along with the Ubuntu LiveCD, you might
-want to make sure you still have adequate free disk space in the root
-partition with the C<df> command. You can free up some space with
-C<rm -rf /root/.cpan/*>.
+ sudo cpan Catalyst::Component::InstancePerContext Catalyst::Controller::HTML::FormFu
=head1 C<HTML::FormFu> FORM CREATION
=cut
- sub formfu_create :Local :FormConfig {
+ sub formfu_create :Chained('base) :PathPart('formfu_create') :Args(0) :FormConfig {
my ($self, $c) = @_;
# Get the form that the :FormConfig attribute saved in the stash
$c->detach;
} else {
# Get the authors from the DB
- my @authorObjs = $c->model("DB::Authors")->all();
+ my @author_objs = $c->model("DB::Authors")->all();
# Create an array of arrayrefs where each arrayref is an author
my @authors;
- foreach (sort {$a->last_name cmp $b->last_name} @authorObjs) {
+ foreach (sort {$a->last_name cmp $b->last_name} @author_objs) {
push(@authors, [$_->id, $_->last_name]);
}
# Get the select added by the config file
Edit C<root/static/css/main.css> and add the following lines to the bottom of
the file:
+ ...
input {
display: block;
}
Open C<root/src/books/list.tt2> in your editor and add the following to
the bottom of the existing file:
+ ...
<p>
HTML::FormFu:
<a href="[% c.uri_for(c.controller.action_for('formfu_create')) %]">Create</a>
=cut
- sub formfu_edit :Local :FormConfig('books/formfu_create.yml') {
+ sub formfu_edit :Chained('object') :PathPart('formfu_edit') :Args(0)
+ :FormConfig('books/formfu_create.yml') {
my ($self, $c, $id) = @_;
# Get the specified book
$c->detach;
} else {
# Get the authors from the DB
- my @authorObjs = $c->model("DB::Authors")->all();
+ my @author_objs = $c->model("DB::Authors")->all();
# Create an array of arrayrefs where each arrayref is an author
my @authors;
- foreach (sort {$a->last_name cmp $b->last_name} @authorObjs) {
+ foreach (sort {$a->last_name cmp $b->last_name} @author_bjs) {
push(@authors, [$_->id, $_->last_name]);
}
# Get the select added by the config file
...
<td>
[% # Add a link to delete a book %]
- <a href="[% c.uri_for(c.controller.action_for('delete', [book.id])) %]">Delete</a>
+ <a href="[% c.uri_for(c.controller.action_for('delete'), [book.id]) %]">Delete</a>
[% # Add a link to edit a book %]
- <a href="[% c.uri_for(c.controller.action_for('formfu_edit', [book.id])) %]">Edit</a>
+ <a href="[% c.uri_for(c.controller.action_for('formfu_edit'), [book.id]) %]">Edit</a>
</td>
...
=item *
-Add an appropriate ACL to the new Edit function.
+Add an appropriate authorization check to the new Edit function.
=item *
the new tables added in the previous step, let's use the C<create=static>
option on the DBIC model helper to do most of the work for us:
- $ script/myapp_create.pl model DB DBIC::Schema MyApp::Schema create=static dbi:SQLite:myapp.db
+ $ 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
+ $ ls lib/MyApp/Schema/Result
Authors.pm BookAuthors.pm Books.pm Roles.pm UserRoles.pm Users.pm
Notice how the helper has added three new table-specific result source
-files to the C<lib/MyApp/Schema/MyApp> directory. And, more
+files to the C<lib/MyApp/Schema/Result> directory. And, more
importantly, even if there were changes to the existing result source
files, those changes would have only been written above the C<# DO NOT
MODIFY THIS OR ANYTHING ABOVE!> comment and your hand-edited
each of these files and add the following information between the C<#
DO NOT MODIFY THIS OR ANYTHING ABOVE!> comment and the closing C<1;>:
-C<lib/MyApp/Schema/Users.pm>:
+C<lib/MyApp/Schema/Result/Users.pm>:
#
# Set relationships:
# 1) Name of relationship, DBIC will create accessor with this name
# 2) Name of the model class referenced by this relationship
# 3) Column name in *foreign* table (aka, foreign key in peer table)
- __PACKAGE__->has_many(map_user_role => 'MyApp::Schema::UserRoles', 'user_id');
+ __PACKAGE__->has_many(map_user_role => 'MyApp::Schema::Result::UserRoles', 'user_id');
# many_to_many():
# args:
__PACKAGE__->many_to_many(roles => 'map_user_role', 'role');
-C<lib/MyApp/Schema/Roles.pm>:
+C<lib/MyApp/Schema/Result/Roles.pm>:
#
# Set relationships:
# 1) Name of relationship, DBIC will create accessor with this name
# 2) Name of the model class referenced by this relationship
# 3) Column name in *foreign* table (aka, foreign key in peer table)
- __PACKAGE__->has_many(map_user_role => 'MyApp::Schema::UserRoles', 'role_id');
+ __PACKAGE__->has_many(map_user_role => 'MyApp::Schema::Result::UserRoles', 'role_id');
-C<lib/MyApp/Schema/UserRoles.pm>:
+C<lib/MyApp/Schema/Result/UserRoles.pm>:
#
# Set relationships:
# 1) Name of relationship, DBIC will create accessor with this name
# 2) Name of the model class referenced by this relationship
# 3) Column name in *this* table
- __PACKAGE__->belongs_to(user => 'MyApp::Schema::Users', 'user_id');
+ __PACKAGE__->belongs_to(user => 'MyApp::Schema::Result::Users', 'user_id');
# belongs_to():
# args:
# 1) Name of relationship, DBIC will create accessor with this name
# 2) Name of the model class referenced by this relationship
# 3) Column name in *this* table
- __PACKAGE__->belongs_to(role => 'MyApp::Schema::Roles', 'role_id');
+ __PACKAGE__->belongs_to(role => 'MyApp::Schema::Result::Roles', 'role_id');
The code for these three sets of updates is obviously very similar to
the edits we made to the C<Books>, C<Authors>, and C<BookAuthors>
classes created in Part 3.
-Note that we do not need to make any change to the
-C<lib/MyApp/Schema.pm> schema file. It simply tells DBIC to
-load all of the result class files it finds in below the
-C<lib/MyApp/Schema> directory, so it will automatically pick
-up our new table information.
+Note that we do not need to make any change to the
+C<lib/MyApp/Schema.pm> schema file. It simply tells DBIC to load all
+of the Result Class and ResultSet Class files it finds in below the
+C<lib/MyApp/Schema> directory, so it will automatically pick up our
+new table information.
=head2 Sanity-Check Reload of Development Server
'-------------------------------------------------------------------+----------'
...
-Again, notice that your "result class" classes have been "re-loaded"
+Again, notice that your "Result Class" classes have been "re-loaded"
by Catalyst under C<MyApp::Model>.
Edit C<lib/MyApp.pm> and update it as follows (everything below
C<StackTrace> is new):
- __PACKAGE__->setup(qw/
- -Debug
- ConfigLoader
- Static::Simple
-
- StackTrace
-
- Authentication
-
- Session
- Session::Store::FastMmap
- Session::State::Cookie
- /);
+ # Load plugins
+ use Catalyst qw/-Debug
+ ConfigLoader
+ Static::Simple
+
+ StackTrace
+
+ Authentication
+
+ Session
+ Session::Store::FastMmap
+ Session::State::Cookie
+ /;
B<Note:> As discussed in MoreCatalystBasics, different versions of
C<Catalyst::Devel> have used a variety of methods to load the plugins.
# Use DBIC to retrieve username, password & role information
class DBIx::Class
# This is the model object created by Catalyst::Model::DBIC
- # from your schema (you created 'MyApp::Schema::User' but as
- # the Catalyst startup debug messages show, it was loaded as
- # 'MyApp::Model::DB::Users').
+ # from your schema (you created 'MyApp::Schema::Result::User'
+ # but as the Catalyst startup debug messages show, it was
+ # loaded as 'MyApp::Model::DB::Users').
# NOTE: Omit 'MyApp::Model' here just as you would when using
# '$c->model("DB::Users)'
user_class DB::Users
this, open C<root/src/login.tt2> in your editor and add the following
lines to the bottom of the file:
+ ...
<p>
[%
# This code illustrates how certain parts of the TT
B<IMPORTANT NOTE:> If you are having issues with authentication on
Internet Explorer, be sure to check the system clocks on both your
server and client machines. Internet Explorer is very picky about
-timestamps for cookies. You can quickly sync an Ubuntu system with
-the following command:
+timestamps for cookies. You can quickly sync a Debian system by
+installing the "ntpdate" package:
+
+ sudo aptitude -y install ntpdate
+
+And then run the following command:
- sudo ntpdate ntp.ubuntu.com
+ sudo ntpdate-debian
-Or possibly try C<sudo ntpdate -u ntp.ubuntu.com> (to us an
-unpriviledged port) or C<sudo ntpdate pool.ntp.org> (to try a
-different server in case the Ubuntu NTP server is down).
+Or, depending on your firewall configuration:
+
+ sudo ntpdate-debian -u
+
+Note: NTP can be a little more finicky about firewalls because it uses
+UDP vs. the more common TCP that you see with most Internet protocols.
+Worse case, you might have to manually set the time on your development
+box instead of using NTP.
Now trying going to L<http://localhost:3000/books/list> and you should
be redirected to the login page, hitting Shift+Reload or Ctrl+Reload
$ perl -MDigest::SHA -e 'print Digest::SHA::sha1_hex("mypass"), "\n"'
e727d1464ae12436e899a726da5b2f11d8381b26
- $
-
-B<Note:> If you are following along in Ubuntu, you will need to install
-C<Digest::SHA> with the following command to run the example code above:
-
- sudo aptitude install libdigest-sha-perl
B<Note:> You should probably modify this code for production use to
not read the password from the command line. By having the script
# Use DBIC to retrieve username, password & role information
class DBIx::Class
# This is the model object created by Catalyst::Model::DBIC
- # from your schema (you created 'MyApp::Schema::User' but as
- # the Catalyst startup debug messages show, it was loaded as
- # 'MyApp::Model::DB::Users').
+ # from your schema (you created 'MyApp::Schema::Result::User'
+ # but as the Catalyst startup debug messages show, it was
+ # loaded as 'MyApp::Model::DB::Users').
# NOTE: Omit 'MyApp::Model' here just as you would when using
# '$c->model("DB::Users)'
user_class DB::Users
=head1 DESCRIPTION
-This part of the tutorial adds role-based authorization to the existing
-authentication implemented in Part 5. It provides simple examples of
-how to use roles in both TT templates and controller actions. The first
-half looks at manually configured authorization. The second half looks
-at how the ACL authorization plugin can simplify your code.
+This part of the tutorial adds role-based authorization to the
+existing authentication implemented in Part 5. It provides simple
+examples of how to use roles in both TT templates and controller
+actions. The first half looks at basic authorization concepts. The
+second half looks at how moving your authorization code to your model
+can simplify your code and make things easier to maintain.
You can checkout the source code for this example from the catalyst
subversion repository as per the instructions in
=head1 BASIC AUTHORIZATION
-In this section you learn how to manually configure authorization.
+In this section you learn the basics of how authorization works under
+Catalyst.
=head2 Update Plugins to Include Support for Authorization
Edit C<lib/MyApp.pm> and add C<Authorization::Roles> to the list:
- __PACKAGE__->setup(qw/
- -Debug
- ConfigLoader
- Static::Simple
-
- StackTrace
-
- Authentication
- Authorization::Roles
-
- Session
- Session::Store::FastMmap
- Session::State::Cookie
- /);
+ # Load plugins
+ use Catalyst qw/-Debug
+ ConfigLoader
+ Static::Simple
+
+ StackTrace
+
+ Authentication
+ Authorization::Roles
+
+ Session
+ Session::Store::FastMmap
+ Session::State::Cookie
+ /;
B<Note:> As discussed in MoreCatalystBasics, different versions of
C<Catalyst::Devel> have used a variety of methods to load the plugins.
-You can put the plugins in the C<use Catalyst> statement if you prefer.
+You can put the plugins in the C<use Catalyst> statement if you
+prefer.
=head2 Add Config Information for Authorization
# Use DBIC to retrieve username, password & role information
class DBIx::Class
# This is the model object created by Catalyst::Model::DBIC
- # from your schema (you created 'MyApp::Schema::User' but as
- # the Catalyst startup debug messages show, it was loaded as
- # 'MyApp::Model::DB::Users').
+ # from your schema (you created 'MyApp::Schema::Result::User'
+ # but as the Catalyst startup debug messages show, it was
+ # loaded as 'MyApp::Model::DB::Users').
# NOTE: Omit 'MyApp::Model' here just as you would when using
# '$c->model("DB::Users)'
user_class DB::Users
Open C<root/src/books/list.tt2> in your editor and add the following
lines to the bottom of the file:
+ ...
<p>Hello [% c.user.username %], you have the following roles:</p>
<ul>
done.
-=head1 ENABLE ACL-BASED AUTHORIZATION
-
-This section takes a brief look at how the
-L<Catalyst::Plugin::Authorization::ACL|Catalyst::Plugin::Authorization::ACL>
-plugin can automate much of the work required to perform role-based
-authorization in a Catalyst application.
-
-
-=head2 Add the C<Catalyst::Plugin::Authorization::ACL> Plugin
-
-Open C<lib/MyApp.pm> in your editor and add the following plugin to the
-C<__PACKAGE__-E<gt>setup> statement:
-
- Authorization::ACL
-
-Note that the remaining C<use Catalyst> plugins from earlier sections
-are not shown here, but they should still be included.
-
-
-=head2 Add ACL Rules to the Application Class
-
-Open C<lib/MyApp.pm> in your editor and add the following B<BELOW> the
-C<__PACKAGE__-E<gt>setup> statement:
-
- # Authorization::ACL Rules
- __PACKAGE__->deny_access_unless(
- "/books/form_create",
- [qw/admin/],
- );
- __PACKAGE__->deny_access_unless(
- "/books/form_create_do",
- [qw/admin/],
- );
- __PACKAGE__->allow_access_if(
- "/books/delete",
- [qw/user admin/],
- );
-
-Each of the three statements above comprises an ACL plugin "rule". The
-first two rules only allow admin-level users to create new books using
-the form (both the form itself and the data submission logic are
-protected). The third statement allows both users and admins to delete
-books; letting users delete but not create book entries may sound odd in
-the "real world", but this is just an example. The C</books/url_create>
-action will continue to be protected by the "manually configured"
-authorization created earlier in this part of the tutorial.
-
-The ACL plugin permits you to apply allow/deny logic in a variety of
-ways. The following provides a basic overview of the capabilities:
-
-=over 4
-
-=item *
-
-The ACL plugin only operates on the Catalyst "private namespace". You
-are using the private namespace when you use C<Local> actions. C<Path>,
-C<Regex>, and C<Global> allow you to specify actions where the path and
-the namespace differ -- the ACL plugin will not work in these cases.
-
-=item *
-
-Each rule is expressed in a separate
-C<__PACKAGE__-E<gt>deny_access_unless()> or
-C<__PACKAGE__-E<gt>allow_access_if()> line (there are several other
-methods that can be used for more complex policies, see the C<METHODS>
-portion of the
-L<Catalyst::Plugin::Authorization::ACL|Catalyst::Plugin::Authorization::ACL>
-documentation for more details).
-
-=item *
-
-Each rule can contain multiple roles but only a single path.
-
-=item *
-
-The rules are tried in order (with the "most specific" rules tested
-first), and processing stops at the first "match" where an allow or deny
-is specified. Rules "fall through" if there is not a "match" (where a
-"match" means the user has the specified role). If a "match" is found,
-then processing stops there and the appropriate allow/deny action is
-taken.
-
-=item *
+=head1 ENABLE MODEL-BASED AUTHORIZATION
-If none of the rules match, then access is allowed.
+Hopefully it's fairly obvious that adding detailed permission checking
+logic to our controllers and view templates isn't a very clean or
+scalable way to build role-based permissions into out application. As
+with many other aspects of MVC web development, the goal is to have
+your controllers and views be an "thin" as possible, with all of the
+"fancy business logic" built into your model.
-=item *
+For example, let's add a method to our C<Books.pm> Result Class to
+check if a user is allowed to delete a book. Open
+C<lib/MyApp/Schema/Result/Books.pm> and add the following method
+(be sure to add it below the "C<DO NOT MODIFY ...>" line):
-The rules currently need to be specified in the application class
-C<lib\MyApp.pm> B<after> the C<__PACKAGE__-E<gt>setup;> line.
+ =head2 delete_allowed_by
+
+ Can the specified user delete the current book?
+
+ =cut
+
+ sub delete_allowed_by {
+ my ($self, $user) = @_;
+
+ # Only allow delete if user has 'admin' role
+ return $user->has_role('admin');
+ }
-=back
+Here we call a C<has_role> method on our user object, so we should add
+this method to our Result Class. Open
+C<lib/MyApp/Schema/Result/Users.pm> and add this near the top:
+ use Perl6::Junction qw/any/;
-=head2 Add a Method to Handle Access Violations
+And then add the following method below the "C<DO NOT MODIFY ...>"
+line:
-By default,
-L<Catalyst::Plugin::Authorization::ACL|Catalyst::Plugin::Authorization::ACL>
-throws an exception when authorization fails. This will take the user
-to the Catalyst debug screen, or a "Please come back later" message if
-you are not using the C<-Debug> flag. This step uses the
-C<access_denied> method in order to provide more appropriate feedback to
-the user.
+ =head 2 has_role
+
+ Check if a user has the specified role
+
+ =cut
+
+ sub has_role {
+ my ($self, $role) = @_;
+
+ # Does this user posses the required role?
+ return any(map { $_->role } $self->roles) eq $role;
+ }
-Open C<lib/MyApp/Controller/Books.pm> in your editor and add the
-following method:
+Now we need to add some enforcement inside our controller. Open
+C<lib/MyApp/Controller/Books.pm> and update the C<delete> method to
+match the following code:
- =head2 access_denied
+ =head2 delete
- Handle Catalyst::Plugin::Authorization::ACL access denied exceptions
+ Delete a book
=cut
- sub access_denied : Private {
+ sub delete :Chained('object') :PathPart('delete') :Args(0) {
my ($self, $c) = @_;
- # Set the error message
- $c->stash->{error_msg} = 'Unauthorized!';
+ # Check permissions
+ $c->detach('/error_noperms')
+ unless $c->stash->{object}->delete_allowed_by($c->user->get_object);
+
+ # Use the book object saved by 'object' and delete it along
+ # with related 'book_authors' entries
+ $c->stash->{object}->delete;
- # Display the list
- $c->forward('list');
+ # Use 'flash' to save information across requests until it's read
+ $c->flash->{status_msg} = "Book deleted";
+
+ # Redirect the user back to the list page
+ $c->response->redirect($c->uri_for($self->action_for('list')));
+ }
+
+Here, we C<detach> to an error page if the user is lacking the
+appropriate permissions. For this to work, we need to make
+arrangements for the '/error_noperms' action to work. Open
+C<lib/MyApp/Controller/Root.pm> and add this method:
+
+ =head2 error_noperms
+
+ Permissions error screen
+
+ =cut
+
+ sub error_noperms :Chained('/') :PathPath('error_noperms') :Args(0) {
+ my ($self, $c) = @_;
+
+ $c->stash->{template} = 'error_noperms.tt2';
}
+And also add the template file by putting the following text into
+C<root/src/error_noperms.tt2>:
+
+ <span class="error">Permission Denied</span>
+
Then run the Catalyst development server script:
$ script/myapp_server.pl
-Log in as C<test02>. Once at the book list, click the "Create" link
-to try the C<form_create> action. You should receive a red
-"Unauthorized!" error message at the top of the list. (Note that in
-the example code the "Admin Create" link code in C<root/src/books/list.tt2>
-is inside an C<IF> statement that only displays the list to
-admin-level users.) If you log in as C<test01> you should be able to
-view the C<form_create> form and add a new book.
+Log in as C<test01> and create several new books using the C<url_create>
+feature:
+
+ http://localhost:3000/books/url_create/Test/1/4
+
+Then, while still logged in as C<test01>, click the "Delete" link next
+to one of these books. The book should be removed and you should see
+the usual green "Book deleted" message. Next, click the "User Logout"
+link and log back in as C<test02>. Now try deleting one of the books.
+You should be taken to the red "Permission Denied" message on our
+error page.
Use one of the 'Logout' links (or go to the
L<http://localhost:3000/logout> URL directly) when you are done.
links will be used instead of full HTML buttons).
Also notice that we are using a more advanced form of C<uri_for> than
-we have seen before. Here we use C<$c-E<gt>controller-
-E<gt>action_for> to automatically generate a URI appropriate for that
-action based on the method we want to link to while inserting the
-C<book.id> value into the appropriate place. Now, if you ever change
-C<:PathPart('delete')> in your controller method to
+we have seen before. Here we use
+C<$c-E<gt>controller-E<gt>action_for> to automatically generate a URI
+appropriate for that action based on the method we want to link to
+while inserting the C<book.id> 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
+still be correct. There are a few shortcuts and options when using
C<action_for()>:
=over 4
Now, any other method that chains off C<object> will automatically
have the appropriate book waiting for it in
-C<$c-E<gt>stash-Egt>{object}>.
+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
along with a list of the eight remaining books. You will also see the
cascading delete operation via the DBIC_TRACE output:
+ SELECT me.id, me.title, me.rating FROM books me WHERE ( ( me.id = ? ) ): '6'
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'
Note the URL in your browser once you have performed the deletion in the
prior step -- it is still referencing the delete action:
- http://localhost:3000/books/delete/6
+ http://localhost:3000/books/id/6/delete
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
features below, let's first migrate our configuration over to use
C<load_namespaces>.
-If you are following along in Ubuntu 8.10, 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:
+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:
- $ cpan Catalyst::Model::DBIC::Schema
+ $ sudo cpan Catalyst::Model::DBIC::Schema
Then make sure you are running an appropriate version:
Make sure you get version 0.23 or higher.
-B<Note:> Ubuntu will automatically "do the right thing" and use the
+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<apt-get> command. If you are using a different
+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.
sqlite> ALTER TABLE books ADD updated INTEGER;
sqlite> UPDATE books SET created = DATETIME('NOW'), updated = DATETIME('NOW');
sqlite> SELECT * FROM books;
- 1|CCSP SNRS Exam Certification Guide|5|2009-03-03 07:31:32|2009-03-03 07:31:32
- 2|TCP/IP Illustrated, Volume 1|5|2009-03-03 07:31:32|2009-03-03 07:31:32
- ...
+ 1|CCSP SNRS Exam Certification Guide|5|2009-03-08 16:26:35|2009-03-08 16:26:35
+ 2|TCP/IP Illustrated, Volume 1|5|2009-03-08 16:26:35|2009-03-08 16:26:35
+ 3|Internetworking with TCP/IP Vol.1|4|2009-03-08 16:26:35|2009-03-08 16:26:35
+ 4|Perl Cookbook|5|2009-03-08 16:26:35|2009-03-08 16:26:35
+ 5|Designing with Web Standards|5|2009-03-08 16:26:35|2009-03-08 16:26:35
+ 9|TCP/IP Illustrated, Vol 3|5|2009-03-08 16:26:35|2009-03-08 16:26:35
sqlite> .quit
$
This will modify the C<books> table to include the two new fields
and populate those fields with the current time.
+
=head2 Update DBIC to Automatically Handle the Datetime Columns
Next, we should re-run the DBIC helper to update the Result Classes
time entered for it (see the last line in the listing below):
sqlite3 myapp.db "select * from books"
- 1|CCSP SNRS Exam Certification Guide|5|2009-03-05 17:18:53|2009-03-05 17:18:53
- 2|TCP/IP Illustrated, Volume 1|5|2009-03-05 17:18:53|2009-03-05 17:18:53
- 3|Internetworking with TCP/IP Vol.1|4|2009-03-05 17:18:53|2009-03-05 17:18:53
- 4|Perl Cookbook|5|2009-03-05 17:18:53|2009-03-05 17:18:53
- 5|Designing with Web Standards|5|2009-03-05 17:18:53|2009-03-05 17:18:53
- 9|TCP/IP Illustrated, Vol 3|5|2009-03-05 17:18:53|2009-03-05 17:18:53
- 10|TCPIP_Illustrated_Vol-2|5|2009-03-05 17:24:18|2009-03-05 17:24:18
+ 1|CCSP SNRS Exam Certification Guide|5|2009-03-08 16:26:35|2009-03-08 16:26:35
+ 2|TCP/IP Illustrated, Volume 1|5|2009-03-08 16:26:35|2009-03-08 16:26:35
+ 3|Internetworking with TCP/IP Vol.1|4|2009-03-08 16:26:35|2009-03-08 16:26:35
+ 4|Perl Cookbook|5|2009-03-08 16:26:35|2009-03-08 16:26:35
+ 5|Designing with Web Standards|5|2009-03-08 16:26:35|2009-03-08 16:26:35
+ 9|TCP/IP Illustrated, Vol 3|5|2009-03-08 16:26:35|2009-03-08 16:26:35
+ 10|TCPIP_Illustrated_Vol-2|5|2009-03-08 16:29:08|2009-03-08 16:29:08
Notice in the debug log that the SQL DBIC generated has changed to
incorporate the datetime logic:
INSERT INTO books (created, rating, title, updated) VALUES (?, ?, ?, ?):
- '2009-03-05 17:24:18', '5', 'TCPIP_Illustrated_Vol-2', '2009-03-05 17:24:18'
+ '2009-03-08 16:29:08', '5', 'TCPIP_Illustrated_Vol-2', '2009-03-08 16:29:08'
INSERT INTO book_authors (author_id, book_id) VALUES (?, ?): '4', '10'
the title. Open up C<lib/MyApp/Controller/Books.pm> and add the
following method:
- =head2 list_recent
+ =head2 list_recent_tcp
List recently created books
the first URL and you should see something similar to the following:
SELECT me.id, me.title, me.rating, me.created, me.updated FROM books me
- WHERE ( ( ( title LIKE ? ) AND ( created > ? ) ) ): '%TCP%', '2009-03-05 15:52:57'
+ WHERE ( ( ( title LIKE ? ) AND ( created > ? ) ) ): '%TCP%', '2009-03-08 14:52:54'
However, let's not pollute our controller code with this raw "TCP"
query -- it would be cleaner to encapsulate that code in a method on
name for an author in one shot. Now open C<root/src/books/list.tt2>
and change the definition of C<tt_authors> from this:
+ ...
[% tt_authors = [ ];
tt_authors.push(author.last_name) FOREACH author = book.authors %]
+ ...
to:
+ ...
[% tt_authors = [ ];
tt_authors.push(author.full_name) FOREACH author = book.authors %]
+ ...
(Only C<author.last_name> was changed to C<author.full_name> -- the
rest of the file should remain the same.)
directory.
Run the following command to start up the built-in development web
-server:
+server (make sure you didn't forget the "C<cd Hello>" from the
+previous step):
$ script/hello_server.pl
[debug] Debug messages enabled
+----------------------+--------------------------------------+--------------+
| /default | Hello::Controller::Root | default |
| /end | Hello::Controller::Root | end |
+ | /index | Hello::Controller::Root | index |
'----------------------+--------------------------------------+--------------'
[debug] Loaded Path actions:
| / | /default |
| / | /index |
'-------------------------------------+--------------------------------------'
-
- [info] Hello powered by Catalyst 5.7014
- You can connect to your server at http://localhost:3000
+
+ [info] Hello powered by Catalyst 5.71000
+ You can connect to your server at http://debian:3000
Point your web browser to L<http://localhost:3000> (substituting a
different hostname or IP address as appropriate) and you should be
-greeted by the Catalyst welcome screen. Information similar to the
-following should be appended to the logging output of the development
-server:
-
- [info] *** Request 1 (1.000/s) [10301] [Sun Nov 23 10:11:36 2008] ***
- [debug] "GET" request for "/" from "127.0.0.1"
- [info] Request took 0.017964s (55.667/s)
+greeted by the Catalyst welcome screen (if you get some other welcome
+screen or an "Index" screen, you probably forgot to specify port 3000
+in your URL). Information similar to the following should be appended
+to the logging output of the development server:
+
+ [info] *** Request 1 (0.005/s) [20712] [Sun Mar 8 15:49:09 2009] ***
+ [debug] "GET" request for "/" from "1.1.1.98"
+ [info] Request took 0.007342s (136.203/s)
.----------------------------------------------------------------+-----------.
| Action | Time |
+----------------------------------------------------------------+-----------+
- | /default | 0.000540s |
- | /end | 0.001246s |
+ | /index | 0.000491s |
+ | /end | 0.000595s |
'----------------------------------------------------------------+-----------'
Press Ctrl-C to break out of the development server.
$c->response->body("Hello, World!");
}
+B<TIP>: See Appendix 1 for tips on removing the leading spaces when
+cutting and pasting example code from POD-based documents.
+
Here you're sending your own string to the webpage.
Save the file, start the server (stop and restart it if it's still
mkdir -p lib/Module; cp `perldoc -l Module::Name` lib/Module/
-Note: If you are following along in Ubuntu, you will need to install
+Note: If you are following along in Debian 5, you will need to install
the C<perl-doc> package to use the C<perldoc> command. Use
-C<sudo apt-get install perl-doc> to do that.
+C<sudo aptitude install perl-doc> to do that.
For example, you could make a copy of
L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication>
B<NOTE: You can use any Perl-supported OS and environment to run
Catalyst.> It should make little or no difference to Catalyst's
-operation, B<but this tutorial has been written using Ubuntu 8.10>
-because that represents a quick and easy for most people to try out
-Catalyst with virtually zero setup time and hassles. Also, the tutorial
-has been tested to work correctly with the versions of Catalyst and all
-the supporting modules in Ubuntu 8.10 (see "VERSIONS AND CONVENTIONS
-USED IN THIS TUTORIAL" below for the specific versions for some of the
-key modules), so B<if you think you might be running into an issue
-related to versions> (for example, a module changed its behavior in a
-newer version or a bug was introduced), B<it might be worth giving
-Ubuntu 8.10 a try>. See the "CATALYST INSTALLATION" section below for
-more information.
+operation, B<but this tutorial has been written using the Debian 5
+live CD> because that represents a quick and easy for most people to
+try out Catalyst with virtually zero setup time and hassles. Also,
+the tutorial has been tested to work correctly with the versions of
+Catalyst and all the supporting modules in Debian 5 (see "VERSIONS
+AND CONVENTIONS USED IN THIS TUTORIAL" below for the specific versions
+for some of the key modules), so B<if you think you might be running
+into an issue related to versions> (for example, a module changed its
+behavior in a newer version or a bug was introduced), B<it might be
+worth giving Debian 5 a try>. See the "CATALYST INSTALLATION"
+section below for more information.
If you're reading this manual online, you can download the example
program and all the necessary dependencies to your local machine by
=item *
-The use of L<DBIx::Class|DBIx::Class> (DBIC) for the model.
+The use of L<DBIx::Class|DBIx::Class> (DBIC) for the model (including
+some of the more advanced techniques you will probably want to use in
+your applications).
=item *
=item *
-Ubuntu 8.10 (Intrepid Ibex)
+Debian 5 (Lenny)
=item *
-Catalyst v5.7014
+Catalyst v5.71000
=item *
-Catalyst::Devel v1.07
+Catalyst::Devel v1.08
=item *
-DBIx::Class v0.08010
+DBIx::Class v0.08012
=item *
=item *
-Catalyst::Plugin::Authorization::ACL -- v0.08
-
-=item *
-
Catalyst::Plugin::Authorization::Roles -- v0.05
=item *
=head1 CATALYST INSTALLATION
-While the rough edges of Catalyst installation have been a problem in
-the past, this is now mostly solved. Nonetheless, installing Catalyst
-can be a little time consuming. Although a compelling strength of
-Catalyst is that it makes use of many of the modules in the vast
-repository that is CPAN, this can complicate the installation process.
-However, there are a growing number of methods that can dramatically
-ease this undertaking. Of these, the following are likely to be
-applicable to the largest number of potential new users:
+Although Catalyst installation has been a challenge in the past, the
+good news is that there are a growing number of options to eliminate
+(or at least dramatically simplify) this concern. Although a
+compelling strength of Catalyst is that it makes use of many of the
+modules in the vast repository that is CPAN, this can complicate the
+installation process if you approach it in the wrong way. Consider
+the following suggestions on the most common ways to get started with
+a Catalyst development environment:
=over 4
=item *
+Debian
+
+The Debian 5 live CD represents a great way for newcomers to
+experiment with Catalyst. As a "live CD," you can simple boot from
+the CD, run a few commands, and in a matter of minutes you should have
+a fully function environment in which do this tutorial. B<The tutorial
+was fully tested to work under Debian 5. Although it SHOULD work
+under any Catalyst installation method you might choose, it can be
+hard to guarantee this.>
+
+=over 4
+
+=item *
+
+Download one of the ISO files from
+L<http://cdimage.debian.org/cdimage/release/current-live/i386/iso-cd/>.
+You can pick any one of the live CD variations will work, but
+you may wish to consider the following points:
+
+=over 4
+
+=item *
+
+"C<debian-live-500-i386-rescue.iso>" is probably the best all-around
+option for most people because it includes many extra tools such as
+the GCC compiler, therefore saving RAM (every package you need to
+install when running from live CD consumes memory because RAM disk is
+being used in lieu of real disk space). When initially booting under
+this image, you may see some cryptic warning messages having to do
+with various diagnostic tools it tries to load or enable, but you
+should be able to safely ignore these.
+
+=item *
+
+"C<debian-live-500-i386-standard.iso>" is a great option because of
+its compact size, but you will probably need approximately 1 GB of RAM
+in the computer where you will run the tutorial. Because the
+"standard" live CD comes with with a minimal set of tools, we will
+have to install extra packages (such as the GCC compiler), all of
+which will require RAM when running from a live CD.
+
+=item *
+
+The other ISO images include different flavors of X-Windows desktop
+managers. You can select one of these if you don't mind the larger
+download size and prefer a graphical environment. Be aware that these
+disks do not come with the extra tools found on the "rescue" image, so
+you will need adequate RAM to be able to install them just as you
+would under the "standard" image. B<Use one of the "graphical" ISO
+images if you want a graphical web browser on the same machine as
+where you will run the tutorial.> (If you are using one of the non-
+graphical images discussed above, you can still use a graphical web
+browser from another machine and point it to your Catalyst development
+machine.)
+
+=back
+
+=item *
+
+Boot off the CD.
+
+=item *
+
+Select "C<Live>" from the initial boot menu.
+
+=item *
+
+Once the system has booted to a "C<user@debian:~$>" prompt, enter the
+following command to add the more current "unstable" package
+repository:
+
+ sudo vi /etc/apt/sources.list
+
+Add the following line to the bottom of this file:
+
+ deb http://ftp.us.debian.org/debian/ unstable main
+
+If you are not familiar with VI, you can move to the bottom of this
+file and press the "o" key to insert a new line and type the line
+above. Then press the "Esc" key followed by a colon (":"), the
+letters "wq" and then the "Enter" key. The rest of the tutorial will
+assume that you know how to use some editor that is available from the
+Linux command-line environment.
+
+=item *
+
+Install Catalyst:
+
+ sudo aptitude update
+ sudo aptitude -y install sqlite3 libdbd-sqlite3-perl libcatalyst-perl \
+ libcatalyst-modules-perl libconfig-general-perl libsql-translator-perl \
+ libdatetime-perl libdatetime-format-mysql-perl libio-all-perl \
+ libperl6-junction-perl
+
+Let it install (normally about a 30-second operaton) and you are
+done.
+
+If you are using an image other than the "rescue" ISO, you will also need
+to run the following command to install additional packages:
+
+ sudo aptitude -y install gcc make libc6-dev
+
+If you are running from the Live CD, you probably also want to free up
+some RAM disk space with the following:
+
+ sudo aptitude clean
+
+NOTE: While the instructions above mention the Live CD because that
+makes it easy for people new to Linux, you can obviously pick a
+different Debian ISO image and install it to your hard drive.
+Although there are many different ways to download and install Debian,
+the "netinst" ISO image (such as "C<debian-500-i386-netinst.iso>"
+represents a great option because it keeps your initial download small
+(but still let's you install anything you want "over the network").
+
+Here are some tips if you are running from a live CD and are running
+out of disk space (which really means you are running out of RAM):
+
+=over 4
+
+=item *
+
+Always run "C<aptitude clean>" after you install new packages to
+delete the original .deb files (the files installed B<by> the .deb
+package B<will> remain available, just the .deb package itself is
+deleted).
+
+=item *
+
+If you are installing modules from CPAN, you can free up some space
+with "C<rm -rf /root/.cpan/*>".
+
+=item *
+
+If necessary, you can remove the cached package information with the
+command "C<rm -f /var/lib/apt/lists/*>". You can later pull this
+information again via the command "C<aptitude update>".
+
+=item *
+
+You can save a small amount of space by commenting out the lines in
+C</etc/apt/sources.list> that reference "deb-src" and
+"security.debian.org". If you have already done an "C<aptitude
+update>" with these repositories enabled, you can use the tip in the
+previous bullet to free the space up (and then do another "C<aptitude
+update>").
+
+=item *
+
+Although you can free up space by removing packages you installed
+since you last booted (check out "C<aptitude remove _pkg_name>"),
+don't bother trying to remove packages already available at the time
+of boot. Instead of freeing up space, it will actual I<consume> some
+space. (The live CD uses these "burn in" packages right from the CD
+disk vs. first loading them on the virtual RAM disk. However, if you
+remove them, the system has to update various files, something that
+I<does> consume some space on the virtual RAM disk.)
+
+=back
+
+=back
+
+=item *
+
Ubuntu
-Given the popularity of Ubuntu and its ease of use, Ubuntu can be a
-great way for newcomers to experiment with Catalyst. Because it is a
-"live CD," you can simply boot from the CD, run a few commands, and you
-should have a fully functional environment in which to do this tutorial
-in a matter of minutes. B<The tutorial was fully tested to work under
-Ubuntu 8.10. Although it SHOULD work under any Catalyst installation
-method you might choose, it can be hard to guarantee this.>
+Ubuntu is an extremely popular offshoot of Debian. It provides
+cutting edge versions of many common tools, application and libraries
+in an easy-to-run live CD configuration (and because a single download
+option can be used for both live CD and install-to-disk usage, it
+keeps your download options nice and simple). As with Debian 5, you
+should be able to generate a fully function Catalyst environment in a
+matter of minutes. Here are quick instructions on how to use Ubuntu
+to prepare for the tutorial:
=over 4
=item *
-Download Ubuntu 8.10 (aka, Intrepid Ibex) Desktop edition and boot from
-the CD and/or image file, select your language, and then "Try Ubuntu
-without any changes to your computer."
+Download the Ubuntu Desktop edition and boot from the CD and/or image
+file, select your language, and then "Try Ubuntu without any changes
+to your computer."
=item *
Install Catalyst:
- sudo apt-get update
- sudo apt-get install libdbd-sqlite3-perl libcatalyst-perl libcatalyst-modules-perl libconfig-general-perl
+ sudo aptitude update
+ sudo aptitude install libdbd-sqlite3-perl libcatalyst-perl libcatalyst-modules-perl libconfig-general-perl
Accept all of the dependencies. Done.
If you are running from the Live CD, you probably also want to free up
some disk space with the following:
- sudo apt-get clean
+ sudo aptitude clean
-NOTE: While the instructions above mention the Live CD because that
+NOTE: While the instructions above mention the live CD because that
makes it easy for people new to Linux, you can obviously also use one
of the options to install Ubuntu on your drive.
L<http://www.catalystframework.org/calendar/2008/7>
or L<Perl::Dist::CatInABox|Perl::Dist::CatInABox>.
-
-=item *
-
-Pre-Built VMWare Images
-
-Under the VMWare community program, work is ongoing to develop a number
-of VMWare images where an entire Catalyst development environment has
-already been installed, complete with database engines and a full
-complement of Catalyst plugins.
-
=item *
Frank Speiser's Amazon EC2 Catalyst SDK
please refer to
L<Catalyst::Manual::Installation|Catalyst::Manual::Installation>.
-B<NOTE:> Step-by-step instructions to replicate the environment on
-which this tutorial was developed can be found at
-L<Catalyst::Manual::Installation::CentOS4|Catalyst::Manual::Installation::CentOS4>.
-Using these instructions, you should be able to build a complete CentOS
-4.X server with Catalyst and all the plugins required to run this
-tutorial.
-
=head1 DATABASES
This tutorial will primarily focus on SQLite because of its simplicity
of installation and use; however, modifications in the script required
-to support MySQL and PostgreSQL will be presented in Appendix 2.
+to support MySQL and PostgreSQL will be presented in Appendix.
B<Note:> One of the advantages of the MVC design patterns is that
applications become much more database independent. As such, you will
B<NOTE:> You can run the test cases for the final code through Part 8
with the following commands:
+ sudo cpan Catalyst::Model::DBIC::Schema Time::Warp DBICx::TestDatabase \
+ DBIx::Class::DynamicDefault DBIx::Class::TimeStamp
wget http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/MyApp_Part8.tgz
tar zxvf MyApp_Part8.tgz
cd MyApp
CATALYST_DEBUG=0 prove --lib lib t
+If you wish to include the L<HTML::FormFu|HTML::FormFu> section in
+your tests, substitute C<MyApp_Part9_FormFu.tgz> for
+C<MyApp_Part8.tgz> in the URL above. However, you will also need to
+run the following additional commands:
+
+ sudo aptitude -y install libhtml-formfu-perl libmoose-perl \
+ libregexp-assemble-perl libhtml-formfu-model-dbic-perl
+ sudo aptitude clean
+ sudo cpan Catalyst::Component::InstancePerContext Catalyst::Controller::HTML::FormFu
+
+You can also fire up the application under the development server that is conveniently
+built in to Catalyst. Just issue this command from the C<MyApp> directory where you
+ran the test suite above:
+
+ script/myapp_server.pl
+
+And the application will start. You can try out the application by
+pulling up C<http://localhost:3000> in your web browser (as mentioned
+earlier, change C<localhost> to a different IP address or DNS name if
+you are running your web browser and your Catalyst development on
+different boxes). We will obviously see more about how to use the
+application as we go through the remaining parts of the tutorial, but
+for now you can log in using the username "test01" and a password of
+"mypass".
+
=head1 AUTHOR
First use the Catalyst C<catalyst.pl> script to initialize the framework
for the C<MyApp> application (make sure you aren't still inside the
directory of the C<Hello> application from the previous part of the
-tutorial):
+tutorial or in a directory that already has a "MyApp" subdirectory):
$ catalyst.pl MyApp
created "MyApp"
For our application, we want to add one new plugin into the mix. To
do this, edit C<lib/MyApp.pm> (this file is generally referred to as
-your I<application class>) and delete the line with:
+your I<application class>) and delete the lines with:
- __PACKAGE__->setup(qw/-Debug ConfigLoader Static::Simple/);
+ use Catalyst qw/-Debug
+ ConfigLoader
+ Static::Simple/;
Then replace it with:
- __PACKAGE__->setup(qw/
- -Debug
- ConfigLoader
- Static::Simple
-
- StackTrace
- /);
+ # Load plugins
+ use Catalyst qw/-Debug
+ ConfigLoader
+ Static::Simple
+
+ StackTrace
+ /;
B<Note:> Recent versions of C<Catalyst::Devel> have used a variety of
-techniques to load these plugins/flags. If you are following along in
-Ubuntu 8.10, you should have C<Catalyst::Devel> v1.07 and see the
-default code shown above. If you are using v1.08, you should see the
-following by default:
+techniques to load these plugins/flags. For example, you might see
+the following:
- use Catalyst qw/-Debug
- ConfigLoader
- Static::Simple/;
- ...
- __PACKAGE__->setup();
+ __PACKAGE__->setup(qw/-Debug ConfigLoader Static::Simple/);
Don't let these variations confuse you -- they all accomplish the same
result.
to facilitate the application we're developing in this tutorial; as with
most things Perl, there's more than one way to do it...
+B<Note:> We will use C<root/src> as the base directory for our
+template files, which a full naming convention of
+C<root/src/_controller_name_/_action_name_.tt2>. Another popular option is to
+use C<root/> as the base (with a full filename pattern of
+C<root/_controller_name_/_action_name_.tt2>).
+
=head2 Create a TT Template Page
database contents:
$ sqlite3 myapp.db
- SQLite version 3.4.2
+ SQLite version 3.5.9
Enter ".help" for instructions
sqlite> select * from books;
1|CCSP SNRS Exam Certification Guide|5
For using other databases, such as PostgreSQL or MySQL, see
L<Appendix 2|Catalyst::Manual::Tutorial::Appendices>.
+
=head1 DATABASE ACCESS WITH C<DBIx::Class>
Catalyst can be used with virtually any form of persistent datastore
=head1 ENABLE THE MODEL IN THE CONTROLLER
-Open C<lib/MyApp/Controller/Books.pm> and un-comment the model code we
-left disabled earlier (un-comment the line containing
-C<[$c-E<gt>model('DB::Books')-E<gt>all]> and delete the next 2 lines):
+Open C<lib/MyApp/Controller/Books.pm> and un-comment the model code we
+left disabled earlier so that your version matches the following (un-
+comment the line containing C<[$c-E<gt>model('DB::Books')-E<gt>all]>
+and delete the next 2 lines):
=head2 list
=head2 Test Run The Application
First, let's enable an environment variable that causes DBIx::Class to
-dump the SQL statements usedß to access the database. This is a
+dump the SQL statements used to access the database. This is a
helpful trick when you are trying to debug your database-oriented
code:
Then launch the Catalyst development server. The log output should
display something like:
- $script/myapp_server.pl
+ $ script/myapp_server.pl
[debug] Debug messages enabled
[debug] Statistics enabled
[debug] Loaded plugins:
| /books/list | /books/list |
'-------------------------------------+--------------------------------------'
- [info] MyApp powered by Catalyst 5.7014
- You can connect to your server at http://localhost:3000
+ [info] MyApp powered by Catalyst 5.71000
+ You can connect to your server at http://debian:3000
B<NOTE:> Be sure you run the C<script/myapp_server.pl> command from
the 'base' directory of your application, not inside the C<script>
=head1 CREATE A WRAPPER FOR THE VIEW
-When using TT, you can (and should!) create a wrapper that will
+When using TT, you can (and should) create a wrapper that will
literally wrap content around each of your templates. This is
certainly useful as you have one main source for changing things that
will appear across your entire site/application instead of having to
<ul>
<li><a href="[% c.uri_for('/books/list') %]">Home</a></li>
<li><a href="[% c.uri_for('/') %]" title="Catalyst Welcome Page">Welcome</a></li>
- <li><a href="mailto:nobody@nowhere.com" title="Contact Us">Contact Us</a></li>
</ul>
</div><!-- end menu -->
Now regenerate the schema using the C<create=static> option:
$ script/myapp_create.pl model DB DBIC::Schema MyApp::Schema create=static dbi:SQLite:myapp.db
- exists "/home/kclark/dev/MyApp/script/../lib/MyApp/Model"
- exists "/home/kclark/dev/MyApp/script/../t"
- Dumping manual schema for MyApp::Schema to directory /home/kclark/dev/MyApp/script/../lib ...
+ exists "/home/me/MyApp/script/../lib/MyApp/Model"
+ exists "/home/me/MyApp/script/../t"
+ Dumping manual schema for MyApp::Schema to directory /home/me/MyApp/script/../lib ...
Schema dump completed.
- exists "/home/kclark/dev/MyApp/script/../lib/MyApp/Model/DB.pm"
+ exists "/home/me/MyApp/script/../lib/MyApp/Model/DB.pm"
We could have also deleted C<lib/MyApp/Model/DB.pm>, but it would
have regenerated the same file (note the C<exists> in the output above).
class (L<DBIx::Class::Schema::Loader|DBIx::Class::Schema::Loader> is
only being used by the helper to load the schema once and then create
the static files for us) and C<Schema.pm> only contains a call to the
-C<load_classes> method. You will also find that C<lib/MyApp>
-contains a C<Schema> subdirectory, with one file inside this directory
-for each of the tables in our simple database (C<Authors.pm>,
-C<BookAuthors.pm>, and C<Books.pm>). These three files were created
-based on the information found by
-L<DBIx::Class::Schema::Loader|DBIx::Class::Schema::Loader> as the
-helper ran.
-
-The idea with all of the files created under C<lib/MyApp/Schema> by
-the C<create=static> option is to only edit the files below the C<# DO
-NOT MODIFY THIS OR ANYTHING ABOVE!> warning. If you place all of your
-changes below that point in the file, you can regenerate the
-automatically created information at the top of each file should your
-database structure get updated.
+C<load_classes> method. You will also find that C<lib/MyApp> contains
+a C<Schema> subdirectory, with files inside this directory named
+according to each of the tables in our simple database (C<Authors.pm>,
+C<BookAuthors.pm>, and C<Books.pm>). These three files are called
+"Result Classes" in DBIC nomenclature. Although the Result Class files
+are named after tables in our database, the classes correspond to the
+I<row-level data> that is returned by DBIC (more on this later,
+especially in
+L<Catalyst::Manual::Tutorial::BasicCRUD/EXPLORING THE POWER OF DBIC>.
+
+The idea with the Result Source files created under
+C<lib/MyApp/Schema> by the C<create=static> option is to only edit the
+files below the C<# DO NOT MODIFY THIS OR ANYTHING ABOVE!> warning.
+If you place all of your changes below that point in the file, you can
+regenerate the automatically created information at the top of each
+file should your database structure get updated.
Also note the "flow" of the model information across the various files
and directories. Catalyst will initially load the model from
B<NOTE:> The version of
L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> in
-Ubuntu 8.10 uses the older DBIC C<load_classes> vs. the newer
+Debian 5 uses the older DBIC C<load_classes> vs. the newer
C<load_namspaces> technique. For new applications, please try to use
C<load_namespaces> since it more easily supports a very useful DBIC
technique called "ResultSet Classes." We will migrate to
=head2 Updating the Generated DBIC Schema Files
-Let's manually add some relationship information to the auto-generated
-schema files. First edit C<lib/MyApp/Schema/Books.pm> and
-add the following text below the C<# You can replace this text...>
-comment:
+Let's manually add some relationship information to the auto-generated
+Result Class files. (Note: if you are using a database other than
+SQLite, such as PostgreSQL, then the relationship could have been
+automatically placed in the Result Class files. If so, you can skip
+this step.) First edit C<lib/MyApp/Schema/Books.pm> and add the
+following text below the C<# You can replace this text...> comment:
#
# Set relationships:
a statement that evaluates to C<true>. This is customarily done with
C<1;> on a line by itself.
+C<Important Note:> Although this tutorial uses plural names for both
+the names of the SQL tables and therefore the Result Classes (after
+all, C<Schema::Loader> automatically named the Result Classes from the
+names of the SQL tables it found), DBIC users prefer singular names
+for these items. B<Please try to use singular table and DBIC
+model/Result Class names in your applications.> This tutorial will
+migrate to singular names as soon as possible (patches welcomed).
+B<Note that while singular is preferred for the DBIC model, plural is
+perfectly acceptable for the names of the controller classes.> After
+all, the C<Books.pm> controller operates on multiple books.
+
This code defines both a C<has_many> and a C<many_to_many> relationship.
The C<many_to_many> relationship is optional, but it makes it easier to
map a book to its collection of authors. Without it, we would have to
three dynamically created model class (one for each of the
table-specific schema classes we created).
-Then hit the URL L<http://localhost:3000/books/list> and be sure that
-the book list is displayed via the relationships established above. You
-can leave the development server running for the next step if you wish.
+Then hit the URL L<http://localhost:3000/books/list> with your browser
+and be sure that the book list is displayed via the relationships
+established above. You can leave the development server running for
+the next step if you wish.
B<Note:> You will not see the authors yet because the view does not yet
use the new relations. Read on to the next section where we update the
=head1 UPDATING THE VIEW
-Let's add a new column to our book list page that takes advantage of
-the relationship information we manually added to our schema files
-in the previous section. Edit C<root/src/books/list.tt2> add add the
-following code below the existing table cell that contains
-C<book.rating> (IOW, add a new table cell below the existing two
-C<td> cells):
+Let's add a new column to our book list page that takes advantage of
+the relationship information we manually added to our schema files in
+the previous section. Edit C<root/src/books/list.tt2> add add the
+following code below the existing table cell that contains
+C<book.rating> (IOW, add a new table cell below the existing two
+C<E<lt>tdE<gt>> tags but above the closing C<E<lt>/trE<gt>> and
+C<E<lt>/tableE<gt>> tags):
+ ...
<td>
[% # First initialize a TT variable to hold a list. Then use a TT FOREACH -%]
[% # loop in 'side effect notation' to load just the last names of the -%]
[% # Use another TT vmethod to join & print the names & comma separators -%]
[% tt_authors.join(', ') | html %]
</td>
+ ...
Then hit "Reload" in your browser (note that you don't need to reload
the development server or use the C<-r> option when updating TT
If you are still running the development server with C<DBIC_TRACE>
enabled, you should also now see five more C<SELECT> statements in the
debug output (one for each book as the authors are being retrieved by
-DBIC).
+DBIC):
SELECT me.id, me.title, me.rating FROM books me:
- SELECT me.book_id, me.author_id FROM book_authors me WHERE ( me.book_id = ? ): '1'
- SELECT me.book_id, me.author_id FROM book_authors me WHERE ( me.book_id = ? ): '2'
- SELECT me.book_id, me.author_id FROM book_authors me WHERE ( me.book_id = ? ): '3'
- SELECT me.book_id, me.author_id FROM book_authors me WHERE ( me.book_id = ? ): '4'
- SELECT me.book_id, me.author_id FROM book_authors me WHERE ( me.book_id = ? ): '5'
+ SELECT author.id, author.first_name, author.last_name FROM book_authors me
+ JOIN authors author ON ( author.id = me.author_id ) WHERE ( me.book_id = ? ): '1'
+ SELECT author.id, author.first_name, author.last_name FROM book_authors me
+ JOIN authors author ON ( author.id = me.author_id ) WHERE ( me.book_id = ? ): '2'
+ SELECT author.id, author.first_name, author.last_name FROM book_authors me
+ JOIN authors author ON ( author.id = me.author_id ) WHERE ( me.book_id = ? ): '3'
+ SELECT author.id, author.first_name, author.last_name FROM book_authors me
+ JOIN authors author ON ( author.id = me.author_id ) WHERE ( me.book_id = ? ): '4'
+ SELECT author.id, author.first_name, author.last_name FROM book_authors me
+ JOIN authors author ON ( author.id = me.author_id ) WHERE ( me.book_id = ? ): '5'
Also note in C<root/src/books/list.tt2> that we are using "| html", a
type of TT filter, to escape characters such as E<lt> and E<gt> to <
skip to Part 4, L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>,
if you wish.>
+
=head2 Using C<RenderView> for the Default View
Once your controller logic has processed the request from a user, it
failures in the default tests. You can fix this by making the following
changes:
-1) Change the line in C<t/01app.t> that read:
+1) Change the line in C<t/01app.t> that reads:
ok( request('/')->is_success, 'Request should succeed' );
$ CATALYST_DEBUG=0 prove --lib lib t
-B<Note:> Depending on the versions of various modules you have
-installed, you might get some C<used only once> warnings -- you can
-ignore these. If you are following along in Ubuntu 8.10, you can
-prevent them by adding C<no warnings;> above line 49 in
-C</usr/lib/perl5/Template/Base.pm> to match the following:
-
- ...
- { no strict qw( refs );
- no warnings;
- $argnames = \@{"$class\::BASEARGS"} || [ ];
- }
- ...
-
During the C<t/02pod> and C<t/03podcoverage> tests, you might notice the
C<all skipped: set TEST_POD to enable this test> warning message. To
execute the Pod-related tests, add C<TEST_POD=1> to the C<prove>
projects / catagits/Catalyst-Manual.git / commitdiff