[Catalyst-commits] r10024 -
Catalyst-Manual/5.70/branches/depluralise/lib/Catalyst/Manual/Tutorial
kiffin at dev.catalyst.perl.org
kiffin at dev.catalyst.perl.org
Wed May 6 14:28:45 GMT 2009
Author: kiffin
Date: 2009-05-06 14:28:45 +0000 (Wed, 06 May 2009)
New Revision: 10024
Modified:
Catalyst-Manual/5.70/branches/depluralise/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
Log:
Finished off the rest of the depluralization stuff for the 2nd half of this pod including create=static. Now completed and verified.
Modified: Catalyst-Manual/5.70/branches/depluralise/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
===================================================================
--- Catalyst-Manual/5.70/branches/depluralise/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod 2009-05-06 00:38:34 UTC (rev 10023)
+++ Catalyst-Manual/5.70/branches/depluralise/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod 2009-05-06 14:28:45 UTC (rev 10024)
@@ -559,18 +559,18 @@
--
-- Create a very simple database to hold book and author information
--
- CREATE TABLE books (
+ CREATE TABLE book (
id INTEGER PRIMARY KEY,
title TEXT ,
rating INTEGER
);
- -- 'book_authors' is a many-to-many join table between books & authors
- CREATE TABLE book_authors (
+ -- 'book_author' is a many-to-many join table between books & authors
+ CREATE TABLE book_author (
book_id INTEGER,
author_id INTEGER,
PRIMARY KEY (book_id, author_id)
);
- CREATE TABLE authors (
+ CREATE TABLE author (
id INTEGER PRIMARY KEY,
first_name TEXT,
last_name TEXT
@@ -578,27 +578,27 @@
---
--- Load some sample data
---
- INSERT INTO books VALUES (1, 'CCSP SNRS Exam Certification Guide', 5);
- INSERT INTO books VALUES (2, 'TCP/IP Illustrated, Volume 1', 5);
- INSERT INTO books VALUES (3, 'Internetworking with TCP/IP Vol.1', 4);
- INSERT INTO books VALUES (4, 'Perl Cookbook', 5);
- INSERT INTO books VALUES (5, 'Designing with Web Standards', 5);
- INSERT INTO authors VALUES (1, 'Greg', 'Bastien');
- INSERT INTO authors VALUES (2, 'Sara', 'Nasseh');
- INSERT INTO authors VALUES (3, 'Christian', 'Degu');
- INSERT INTO authors VALUES (4, 'Richard', 'Stevens');
- INSERT INTO authors VALUES (5, 'Douglas', 'Comer');
- INSERT INTO authors VALUES (6, 'Tom', 'Christiansen');
- INSERT INTO authors VALUES (7, 'Nathan', 'Torkington');
- INSERT INTO authors VALUES (8, 'Jeffrey', 'Zeldman');
- INSERT INTO book_authors VALUES (1, 1);
- INSERT INTO book_authors VALUES (1, 2);
- INSERT INTO book_authors VALUES (1, 3);
- INSERT INTO book_authors VALUES (2, 4);
- INSERT INTO book_authors VALUES (3, 5);
- INSERT INTO book_authors VALUES (4, 6);
- INSERT INTO book_authors VALUES (4, 7);
- INSERT INTO book_authors VALUES (5, 8);
+ INSERT INTO book VALUES (1, 'CCSP SNRS Exam Certification Guide', 5);
+ INSERT INTO book VALUES (2, 'TCP/IP Illustrated, Volume 1', 5);
+ INSERT INTO book VALUES (3, 'Internetworking with TCP/IP Vol.1', 4);
+ INSERT INTO book VALUES (4, 'Perl Cookbook', 5);
+ INSERT INTO book VALUES (5, 'Designing with Web Standards', 5);
+ INSERT INTO author VALUES (1, 'Greg', 'Bastien');
+ INSERT INTO author VALUES (2, 'Sara', 'Nasseh');
+ INSERT INTO author VALUES (3, 'Christian', 'Degu');
+ INSERT INTO author VALUES (4, 'Richard', 'Stevens');
+ INSERT INTO author VALUES (5, 'Douglas', 'Comer');
+ INSERT INTO author VALUES (6, 'Tom', 'Christiansen');
+ INSERT INTO author VALUES (7, 'Nathan', 'Torkington');
+ INSERT INTO author VALUES (8, 'Jeffrey', 'Zeldman');
+ INSERT INTO book_author VALUES (1, 1);
+ INSERT INTO book_author VALUES (1, 2);
+ INSERT INTO book_author VALUES (1, 3);
+ INSERT INTO book_author VALUES (2, 4);
+ INSERT INTO book_author VALUES (3, 5);
+ INSERT INTO book_author VALUES (4, 6);
+ INSERT INTO book_author VALUES (4, 7);
+ INSERT INTO book_author VALUES (5, 8);
Then use the following command to build a C<myapp.db> SQLite database:
@@ -615,7 +615,7 @@
$ sqlite3 myapp.db
SQLite version 3.5.9
Enter ".help" for instructions
- sqlite> select * from books;
+ sqlite> select * from book;
1|CCSP SNRS Exam Certification Guide|5
2|TCP/IP Illustrated, Volume 1|5
3|Internetworking with TCP/IP Vol.1|4
@@ -626,7 +626,7 @@
Or:
- $ sqlite3 myapp.db "select * from books"
+ $ sqlite3 myapp.db "select * from book"
1|CCSP SNRS Exam Certification Guide|5
2|TCP/IP Illustrated, Volume 1|5
3|Internetworking with TCP/IP Vol.1|4
@@ -639,6 +639,15 @@
".q" to exit from SQLite from the SQLite interactive mode and return to
your OS command prompt.
+Please note that here we have chosen to use 'singular' table names. This
+is because the default inflection code for L<DBIx::Class:Schema::Loader>
+does NOT handle plurals. There has been much philosophical discussion
+on whether table names should be plural or singular. There is no one
+correct answer, as long as one makes a choice and remains consistent
+with it. If you prefer plural table names (e.g. they are easier and
+more natural to read) then you will need to pass it an inflect_map
+option. See L<DBIx::Class:Schema::Loader> for more information.
+
For using other databases, such as PostgreSQL or MySQL, see
L<Appendix 2|Catalyst::Manual::Tutorial::Appendices>.
@@ -675,6 +684,9 @@
'print "$Catalyst::Model::DBIC::Schema::VERSION\n"'
0.23
+(please note that the '\' above is a line continuation marker and
+should NOT be included as part of the command)
+
If you don't have version 0.23 or higher, please run this command
to install it directly from CPAN:
@@ -700,6 +712,9 @@
created "/home/me/MyApp/script/../lib/MyApp/Model/DB.pm"
created "/home/me/MyApp/script/../t/model_DB.t"
+(please note that the '\' above is a line continuation marker and
+should NOT be included as part of the command)
+
The C<script/myapp_create.pl> command breaks down like this:
=over 4
@@ -742,7 +757,7 @@
find that C<lib/MyApp> contains a C<Schema> subdirectory, which then
has a subdirectory called "Result". This "Result" subdirectory then
has files named according to each of the tables in our simple database
-(C<Authors.pm>, C<BookAuthors.pm>, and C<Books.pm>). These three
+(C<Author.pm>, C<BookAuthor.pm>, and C<Book.pm>). These three
files are called "Result Classes" in DBIx::Class 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
@@ -784,6 +799,10 @@
$ script/myapp_create.pl model DB DBIC::Schema MyApp::Schema \
create=static components=TimeStamp dbi:SQLite:myapp.db
$
+ $ # Note that the '\' above is a line continuation marker and
+ $ # should NOT be included as part of the command
+
+ $
$ # Now convert the existing files over
$ cd lib/MyApp/Schema
$ perl -MIO::All -e 'for (@ARGV) { my $s < io($_); $s =~ s/.*\n\# You can replace.*?\n//s;
@@ -863,7 +882,7 @@
}
B<TIP>: You may see the C<$c-E<gt>model('DB::Book')> un-commented
-above written as C<$c-E<gt>model('DB')-E<gt>resultset('Books')>. The
+above written as C<$c-E<gt>model('DB')-E<gt>resultset('Book')>. The
two are equivalent. Either way, C<$c-E<gt>model> returns a
L<DBIx::Class::ResultSet|DBIx::Class::ResultSet> which handles queries
against the database and iterating over the set of results that is
@@ -911,9 +930,9 @@
[debug] Statistics enabled
[debug] Loaded plugins:
.----------------------------------------------------------------------------.
- | Catalyst::Plugin::ConfigLoader 0.20 |
- | Catalyst::Plugin::StackTrace 0.08 |
- | Catalyst::Plugin::Static::Simple 0.20 |
+ | Catalyst::Plugin::ConfigLoader 0.23 |
+ | Catalyst::Plugin::StackTrace 0.10 |
+ | Catalyst::Plugin::Static::Simple 0.21 |
'----------------------------------------------------------------------------'
[debug] Loaded dispatcher "Catalyst::Dispatcher"
@@ -928,8 +947,8 @@
| MyApp::Controller::Root | instance |
| MyApp::Model::DB | instance |
| MyApp::Model::DB::Author | class |
+ | MyApp::Model::DB::Book | class |
| MyApp::Model::DB::BookAuthor | class |
- | MyApp::Model::DB::Book | class |
| MyApp::View::TT | instance |
'-----------------------------------------------------------------+----------'
@@ -954,7 +973,6 @@
| /books/list | /books/list |
'-------------------------------------+--------------------------------------'
- [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
@@ -1182,7 +1200,7 @@
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/Result/Books.pm> and add the
+this step.) First edit C<lib/MyApp/Schema/Result/Book.pm> and add the
following text below the C<# You can replace this text...> comment:
#
@@ -1194,7 +1212,7 @@
# 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(book_authors => 'MyApp::Schema::Result::BookAuthor', 'book_id');
+ __PACKAGE__->has_many(book_author => 'MyApp::Schema::Result::BookAuthor', 'book_id');
# many_to_many():
# args:
@@ -1202,7 +1220,7 @@
# 2) Name of has_many() relationship this many_to_many() is shortcut for
# 3) Name of belongs_to() relationship in model class of has_many() above
# You must already have the has_many() defined to use a many_to_many().
- __PACKAGE__->many_to_many(authors => 'book_authors', 'author');
+ __PACKAGE__->many_to_many(author => 'book_author', 'author');
B<Note:> Be careful to put this code I<above> the C<1;> at the end of the
@@ -1210,31 +1228,20 @@
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), DBIx::Class 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 "walk" though the C<book_authors> table as in
-C<$book-E<gt>book_authors-E<gt>first-E<gt>author-E<gt>last_name> (we
+it, we would have to "walk" though the C<book_author> table as in
+C<$book-E<gt>book_author-E<gt>first-E<gt>author-E<gt>last_name> (we
will see examples on how to use DBIx::Class objects in your code soon,
-but note that because C<$book-E<gt>book_authors> can return multiple
+but note that because C<$book-E<gt>book_author> can return multiple
authors, we have to use C<first> to display a single author).
-C<many_to_many> allows us to use the shorter C<$book-E<gt>authors-
+C<many_to_many> allows us to use the shorter C<$book-E<gt>author-
E<gt>first-E<gt>last_name>. Note that you cannot define a
C<many_to_many> relationship without also having the C<has_many>
relationship in place.
-Then edit C<lib/MyApp/Schema/Result/Authors.pm> and add relationship
+Then edit C<lib/MyApp/Schema/Result/Author.pm> and add relationship
information as follows (again, be careful to put in above the C<1;> but
below the C<# DO NOT MODIFY THIS OR ANYTHING ABOVE!> comment):
@@ -1255,10 +1262,10 @@
# 2) Name of has_many() relationship this many_to_many() is shortcut for
# 3) Name of belongs_to() relationship in model class of has_many() above
# You must already have the has_many() defined to use a many_to_many().
- __PACKAGE__->many_to_many(books => 'book_author', 'book');
+ __PACKAGE__->many_to_many(book => 'book_author', 'book');
Finally, do the same for the "join table,"
-C<lib/MyApp/Schema/Result/BookAuthors.pm>:
+C<lib/MyApp/Schema/Result/BookAuthor.pm>:
#
# Set relationships:
@@ -1306,7 +1313,7 @@
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> and replace
-the "empty" tabase cell with the following:
+the "empty" table cell "<td></td>" with the following:
...
<td>
@@ -1341,16 +1348,16 @@
DBIx::Class):
SELECT me.id, me.title, me.rating FROM books me:
- 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'
+ SELECT author.id, author.first_name, author.last_name FROM book_author me
+ JOIN author author ON ( author.id = me.author_id ) WHERE ( me.book_id = ? ): '1'
+ SELECT author.id, author.first_name, author.last_name FROM book_author me
+ JOIN author author ON ( author.id = me.author_id ) WHERE ( me.book_id = ? ): '2'
+ SELECT author.id, author.first_name, author.last_name FROM book_author me
+ JOIN author author ON ( author.id = me.author_id ) WHERE ( me.book_id = ? ): '3'
+ SELECT author.id, author.first_name, author.last_name FROM book_author me
+ JOIN author author ON ( author.id = me.author_id ) WHERE ( me.book_id = ? ): '4'
+ SELECT author.id, author.first_name, author.last_name FROM book_author me
+ JOIN author 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 <
More information about the Catalyst-commits
mailing list