X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2FMoreCatalystBasics.pod;h=1c2086a074bd2da95a861df704a1977656a191cd;hp=edc0ddd1b2621c29d7efa4471875812a02bcabbc;hb=feb4555a077523ed0583fa59e9f4ff843d5ae026;hpb=de966eb4075222a38bf5954b9527ef89c90bbb2e

diff --git a/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod b/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
index edc0ddd..1c2086a 100644
--- a/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
+++ b/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
@@ -140,20 +140,21 @@ very similar to Apache configuration files.  We will see how to use
 this feature of Catalyst during the authentication and authorization
 sections (Part 5 and Part 6).
 
-B<IMPORTANT NOTE:> If you are using a version of
-L<Catalyst::Devel|Catalyst::Devel> prior to version 1.06, you need to
-be aware that Catalyst changed from a default format of YAML to the
-more straightforward C<Config::General> format.  This tutorial use the
-newer C<myapp.conf> configuration file for C<Config::General> instead
-of C<myapp.yml> for YAML. However, Catalyst has long supported both
-formats and Catalyst will automatically use either C<myapp.conf> or
-C<myapp.yml> (or any other format supported by
-L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader> and
-L<Config::Any|Config::Any>).  If you are using a versions of
-Catalyst::Devel prior to 1.06, you can convert to the newer format by
-simply creating the C<myapp.yml> file manually and deleting
-C<myapp.yml>.  The default contents of C<myapp.conf> should only
-consist of one line: C<name MyApp>.
+B<IMPORTANT NOTE:> If you are using a version of 
+L<Catalyst::Devel|Catalyst::Devel> prior to version 1.06, be aware 
+that Catalyst changed the default format from YAML to the more 
+straightforward C<Config::General> style.  This tutorial uses the 
+newer C<myapp.conf> file for C<Config::General>. However, Catalyst 
+supports both formats and will automatically use either C<myapp.conf> 
+or C<myapp.yml> (or any other format supported by 
+L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader> and 
+L<Config::Any|Config::Any>).  If you are using a version of 
+Catalyst::Devel prior to 1.06, you can convert to the newer format by 
+simply creating the C<myapp.conf> file manually and deleting 
+C<myapp.yml>.  The default contents of the C<myapp.conf> you create 
+should only consist of one line: 
+
+    name MyApp
 
 B<TIP>: This script can be useful for converting between configuration
 formats:
@@ -161,10 +162,6 @@ formats:
     perl -Ilib -e 'use MyApp; use Config::General;
         Config::General->new->save_file("myapp.conf", MyApp->config);'
 
-B<NOTE:> The default C<myapp.conf> should look like:
-
-    name   MyApp
-
 =item *
 
 L<Catalyst::Plugin::Static::Simple|Catalyst::Plugin::Static::Simple>
@@ -294,26 +291,89 @@ Context object is automatically passed to all Catalyst components.  It
 is used to pass information between components and provide access to 
 Catalyst and plugin functionality.
 
-B<Note:> Catalyst actions are regular Perl methods, but they make use 
-of Nicholas Clark's C<attributes> module (that's the "C<: Local>" next 
-to the C<sub list> in the code above) to provide additional 
-information to the Catalyst dispatcher logic.  Many newer Catalyst 
-applications are switching to the use of "Literal" C<:Path> actions 
-and C<Args> attribute in lieu of C<: Local> and C<: Private>.  For 
-example, C<sub any_method :Path :Args(0)> can be used instead of C<sub 
-index :Private> (because no path was supplied to C<Path> it matches 
-the "empty" URL in the namespace of that module... the same thing 
-C<sub index> would do) or C<sub list :Path('list') :Args(0)> could be 
-used instead of the C<sub list : Local> above (the C<list> argument to 
-C<Path> would make it match on the URL C<list> under C<books>, the 
-namespace of the current module).  See "Action Types" in 
-L<Catalyst::Manual::Intro|Catalyst::Manual::Intro> as well as Part 5 
-of this tutorial (Authentication) for additional information.  Another 
-popular but more advanced feature is C<Chained> actions that allow a 
-single URL to "chain together" multiple action method calls, each with 
-an appropriate number of arguments (see 
-L<Catalyst::DispatchType::Chained|Catalyst::DispatchType::Chained> for 
-details).
+Catalyst actions are regular Perl methods, but they make use of 
+attributes (the "C<: Local>" next to the "C<sub list>" in the code 
+above) to provide additional information to the Catalyst dispatcher 
+logic (note that the space between the colon and the attribute name is 
+optional... you will see attributes written both ways).  Most Catalyst 
+Controllers use one of five action types:
+
+=over 4
+
+=item *
+
+B<:Private> -- Use C<:Private> for methods that you want to make into 
+an action, but you do not want Catalyst to directly expose the action 
+to your users.  Catalyst will not map C<:Private> methods to a URI. 
+Use them for various sorts of "special" methods (the C<begin>, 
+C<auto>, etc. discussed below) or for methods you want to be able to 
+C<forward> or C<detach> to.  (If the method is a plain old "helper 
+method" that you don't want to be an action at all, then just define 
+the method without any attribute -- you can call it in your code, but 
+the Catalyst dispatcher will ignore it.)
+
+There are five types of "special" build-in C<:Private> actions: 
+C<begin>, C<end>, C<default>, C<index>, and C<auto>.
+
+=over 4
+
+=item *
+
+With C<begin>, C<end>, C<default>, C<index> private actions, only the
+most specific action of each type will be called.  For example, if you
+define a C<begin> action in your controller it will I<override> a
+C<begin> action in your application/root controller -- I<only> the
+action in your controller will be called.
+
+=item *
+
+Unlike the other actions where only a single method is called for each
+request, I<every> auto action along the chain of namespaces will be
+called.  Each C<auto> action will be called I<from the application/root
+controller down through the most specific class>.
+
+=back
+
+=item *
+
+B<:Path> -- C<:Path> actions let you map a method to an explicit URI 
+path.  For example, "C<:Path('list')>" in 
+C<lib/MyApp/Controller/Books.pm> would match on the URL 
+C<http://localhost:3000/books/list> but "C<:Path('/list')>" would match 
+on C<http://localhost:3000/list>.  You can use C<:Args()> to specify 
+how many arguments an action should except.  See 
+L<Catalyst::Manual::Intro/Action_types> for more information and a few 
+examples.
+
+=item *
+
+B<:Local> -- C<:Local> is merely a shorthand for 
+"C<:Path('_name_of_method_')>".  For example, these are equivalent:
+"C<sub create_book :Local {...}>" and 
+"C<sub create_book :Path('create_book') {...}>".
+
+=item *
+
+B<:Global> -- C<:Global> is merely a shorthand for 
+"C<:Path('/_name_of_method_')>".  For example, these are equivalent:
+"C<sub create_book :Global {...}>" and 
+"C<sub create_book :Path('/create_book') {...}>".
+
+=item *
+
+B<:Chained> -- Newer Catalyst applications tend to use the Chained 
+dispatch form of action types because of its power and flexibility.  
+It allows a series of controller methods to automatically be dispatched
+to service a single user request.  See 
+L<Catalyst::Manual::Tutorial::BasicCRUD|Catalyst::Manual::Tutorial::BasicCRUD> 
+and L<Catalyst::DispatchType::Chained|Catalyst::DispatchType::Chained> 
+for more information on chained actions.
+
+=back
+
+You should refer to L<Catalyst::Manual::Intro/Action_types> for 
+additional information and for coverage of some lesser-used action 
+types not discussed here (C<Regex> and C<LocalRegex>).
 
 
 =head1 CATALYST VIEWS
@@ -569,6 +629,8 @@ required if you do a single SQL statement on the command line).  Use
 ".q" to exit from SQLite from the SQLite interactive mode and return to
 your OS command prompt.
 
+For using other databases, such as PostgreSQL or MySQL, see 
+L<Appendix 2|Catalyst::Manual::Tutorial::Appendices>.
 
 =head1 DATABASE ACCESS WITH C<DBIx::Class>
 
@@ -599,19 +661,37 @@ starts:
     created "/home/me/MyApp/script/../t/model_DB.t"
 
 
+The C<script/myapp_create.pl> command breaks down like this:
+
+=over 4
+
+=item *
+
 C<DB> is the name of the model class to be created by the helper in 
-C<lib/MyApp/Model>.  C<DBIC::Schema> is the type of the model to 
-create. C<MyApp::Schema> is the name of the DBIC schema file written 
-to C<lib/MyApp/Schema.pm>.  Because we specified C<create=dynamic> to 
-the helper, it use 
+C<lib/MyApp/Model>.
+
+=item *
+
+C<DBIC::Schema> is the type of the model to create.
+
+=item *
+
+C<MyApp::Schema> is the name of the DBIC schema file written to
+C<lib/MyApp/Schema.pm>.
+
+=item *
+
+Because we specified C<create=dynamic> to the helper, it use 
 L<DBIx::Class::Schema::Loader|DBIx::Class::Schema::Loader> to 
 dynamically load the schema information from the database every time 
-the application starts. DBIC uses the schema to load other classes 
-that represent the tables in your database (DBIC refers to these 
-"table objects" as "result sources," see 
-L<DBIx::Class::ResultSource|DBIx::Class::ResultSource>). And finally, 
-C<dbi:SQLite:myapp.db> is the standard DBI connect string for use with 
-SQLite.
+the application starts.
+
+=item *
+
+And finally, C<dbi:SQLite:myapp.db> is the standard DBI connect string 
+for use with SQLite.
+
+=back
 
 B<NOTE:> Although the C<create=dynamic> option to the DBIC helper
 makes for a nifty demonstration, is only really suitable for very
@@ -647,8 +727,8 @@ C<[$c-E<gt>model('DB::Books')-E<gt>all]> and delete the next 2 lines):
         $c->stash->{template} = 'books/list.tt2';
     }
 
-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('Book')>.  The 
+B<TIP>: You may see the C<$c-E<gt>model('DB::Books')> un-commented 
+above written as C<$c-E<gt>model('DB')-E<gt>resultset('Books')>.  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 are 
@@ -671,9 +751,10 @@ and L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema>.
 
 =head2 Test Run The Application
 
-First, let's enable an environment variable option that causes
-DBIx::Class to dump the SQL statements it's using to access the database
-(this option can provide extremely helpful troubleshooting information):
+First, let's enable an environment variable that causes DBIx::Class to 
+dump the SQL statements usedß to access the database.  This is a 
+helpful trick when you are trying to debug your database-oriented 
+code:
 
     $ export DBIC_TRACE=1
 
@@ -1014,16 +1095,46 @@ 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
-C<lib/MyApp/Model/DB.pm>.  This file contains a reference to
-C<lib/MyApp/Schema.pm>, so that file is loaded next.  Finally,
-the call to C<load_classes> in C<Schema.pm> will load each of the
-table-specific "results source" files from the C<lib/MyApp/Schema>
-subdirectory.  These three table-specific DBIC schema files will then be
-used to create three table-specific Catalyst models every time the
-application starts (you can see these three model files listed in
-the debug output generated when you launch the application).
+Also note the "flow" of the model information across the various files 
+and directories.  Catalyst will initially load the model from 
+C<lib/MyApp/Model/DB.pm>.  This file contains a reference to 
+C<lib/MyApp/Schema.pm>, so that file is loaded next.  Finally, the 
+call to C<load_classes> in C<Schema.pm> will load each of the "result 
+class" files from the C<lib/MyApp/Schema> subdirectory.  The end 
+result is that Catalyst will dynamically create three table-specific 
+Catalyst models every time the application starts (you can see these 
+three model files listed in the debug output generated when you launch 
+the application).
+
+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 
+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."  This tutorial expects to migrate to 
+C<load_namespaces> when the next release of Ubuntu comes out.
+
+If you wish to try C<load_namespaces> now, you can manually do the
+equivalent of the C<create=static> operation outside of the Catalyst
+helper:
+
+    perl -MDBIx::Class::Schema::Loader=make_schema_at,dump_to_dir:./lib -e \
+        'make_schema_at("MyApp::Schema", { debug => 1, use_namespaces => 1, \
+        components => ["InflateColumn::DateTime"] },["dbi:SQLite:myapp.db", "", "" ])'
+
+And then use the helper to only create the Catalyst model class:
+
+    script/myapp_create.pl model DB DBIC::Schema MyApp::Schema dbi:SQLite:myapp.db
+
+B<However>, it is important to note that C<load_namespaces> will look 
+for your C<Books.pm>, <Authors.pm>, etc. files in 
+C<lib/MyApp/Schema/Result> (it adds the subdirection "Result" so that 
+there can also be a "ResultSet" directory next to it in the 
+hierarchy).  Therefore, if you switch to C<load_namespaces>, you will 
+need to modify the path to these "result class" files throughout the 
+rest of the tutorial.  Our recommendation for now would be to complete 
+the tutorial using C<load_classes> and the try converting to 
+C<load_namespaces> after you are done.
 
 
 =head2 Updating the Generated DBIC Schema Files
@@ -1041,7 +1152,7 @@ comment:
     #   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 *foreign* table
+    #     3) Column name in *foreign* table (aka, foreign key in peer table)
     __PACKAGE__->has_many(book_authors => 'MyApp::Schema::BookAuthors', 'book_id');
     
     # many_to_many():
@@ -1083,7 +1194,7 @@ below the C<# DO NOT MODIFY THIS OR ANYTHING ABOVE!> comment):
     #   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 *foreign* table
+    #     3) Column name in *foreign* table (aka, foreign key in peer table)
     __PACKAGE__->has_many(book_author => 'MyApp::Schema::BookAuthors', 'author_id');
     
     # many_to_many():