[Catalyst-commits] r9415 - in Catalyst-Manual/5.70/trunk: .
lib/Catalyst/Manual lib/Catalyst/Manual/Tutorial
hkclark at dev.catalyst.perl.org
hkclark at dev.catalyst.perl.org
Tue Mar 3 01:19:04 GMT 2009
Author: hkclark
Date: 2009-03-03 01:19:03 +0000 (Tue, 03 Mar 2009)
New Revision: 9415
Modified:
Catalyst-Manual/5.70/trunk/Changes
Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial.pod
Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/Authentication.pod
Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/CatalystBasics.pod
Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/Intro.pod
Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
Log:
Suggestions and fixes with thanks to Murray Walker (along with a few other minor adjustments)
Modified: Catalyst-Manual/5.70/trunk/Changes
===================================================================
--- Catalyst-Manual/5.70/trunk/Changes 2009-03-02 22:37:50 UTC (rev 9414)
+++ Catalyst-Manual/5.70/trunk/Changes 2009-03-03 01:19:03 UTC (rev 9415)
@@ -1,5 +1,9 @@
Revision history for Catalyst-Manual
+5.7XXX
+ - Suggestions and fixes with thanks to Murray Walker
+ - Misc updates and fixes
+
5.7017 28 Feb 2009
- Main change = adding Chained dispatch starting in BasicCRUD (Part 4)
- Add some "getting started" links to the Catalyst::Manual page
Modified: Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/Authentication.pod
===================================================================
--- Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/Authentication.pod 2009-03-02 22:37:50 UTC (rev 9414)
+++ Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/Authentication.pod 2009-03-03 01:19:03 UTC (rev 9415)
@@ -158,7 +158,7 @@
# 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(map_user_role => 'MyApp::Schema::UserRoles', 'user_id');
# many_to_many():
@@ -180,7 +180,7 @@
# 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(map_user_role => 'MyApp::Schema::UserRoles', 'role_id');
Modified: Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/CatalystBasics.pod
===================================================================
--- Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/CatalystBasics.pod 2009-03-02 22:37:50 UTC (rev 9414)
+++ Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/CatalystBasics.pod 2009-03-03 01:19:03 UTC (rev 9415)
@@ -220,8 +220,7 @@
[info] Hello powered by Catalyst 5.7014
You can connect to your server at http://localhost:3000
-Point your web browser to
-L<http://localhost:3000|http://localhost:3000> (substituting a
+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
@@ -323,14 +322,29 @@
$ script/hello_create.pl view TT TT
This creates the C<lib/Hello/View/TT.pm> module, which is a subclass of
-C<Catalyst::View::TT>. The "view" keyword tells the create script that
-you are creating a view, the second "TT" tells it that you are creating
-a Template Toolkit view, and the first "TT" tells the script to name
-the View module "TT.pm", which is a commonly used name for TT views.
-(You can name it anything you want, such as "HTML.pm".) If you look at
-TT.pm, you will find that it only contains a config statement to set
-the TT extension to ".tt".
+C<Catalyst::View::TT>.
+=over 4
+
+=item *
+
+The "view" keyword tells the create script that you are creating a view.
+
+=item *
+
+The first "TT" tells the script to name the View module "TT.pm", which is a
+commonly used name for TT views. (You can name it anything you want, such as
+"HTML.pm".)
+
+=item *
+
+The final "TT" tells it that you are creating a Template Toolkit view.
+
+=back
+
+If you look at C<lib/Hello/View/TT.pm> you will find that it only contains a
+config statement to set the TT extension to ".tt".
+
Now that the TT.pm "View" exists, Catalyst will autodiscover it and be
able to use it to display the view templates, using the "process"
method that it inherits from the C<Catalyst::View::TT class>.
@@ -345,29 +359,31 @@
the C<Hello> directory that is the base of your application). Here is
a simple sample:
- [% META title = 'Hello, World!' %]
<p>
- This is a TT view template, located in the 'root/' directory.
+ This is a TT view template, called '[% template.name %]'.
</p>
[% and %] are markers for the TT parts of the template. Inside you can
-access Perl variables and classes, and use TT directives. The rest of
-the template is normal HTML. Change the hello method in
-C<lib/Hello/Controller/Root.pm> to the following:
+access Perl variables and classes, and use TT directives. In this
+case, we're using a special TT variable that defines the name of the
+template file (C<hello.tt>). The rest of the template is normal HTML.
+Change the hello method in C<lib/Hello/Controller/Root.pm> to the
+following:
+
sub hello : Global {
my ( $self, $c ) = @_;
$c->stash->{template} = 'hello.tt';
}
-This time, instead of doing C<$c-E<gt>response->body()>, you are setting
+This time, instead of doing C<$c-E<gt>response-E<gt>body()>, you are setting
the value of the "template" hash key in the Catalyst "stash", an area
for putting information to share with other parts of your application.
The "template" key determines which template will be displayed at the
end of the method. Catalyst controllers have a default "end" action
for all methods which causes the first (or default) view to be
-rendered (unless there's a C<$c-E<gt>response->body()> statement). So your
+rendered (unless there's a C<$c-E<gt>response-E<gt>body()> statement). So your
template will be magically displayed at the end of your method.
After saving the file, restart the development server, and look at
@@ -395,17 +411,24 @@
$c->stash->{template} = 'site/test.tt';
}
-Notice the "Local" attribute on the method. This will allow the action
-to be executed on the "controller/method" URL, or, in this case,
-"site/test", instead of at the root site URL, like "Global". It's not
-actually necessary to set the template value, since by default TT will
-attempt to render a template that follows the naming pattern
-"controller/method.tt", and we're following that pattern here, but in
-other situations you will need to specify the template (such as if
-you've "forwarded" to the method, or if it doesn't follow the default
-naming convention). We've also put the variable "name" into the stash,
-for use in the template.
+Notice the "Local" attribute on the C<test> method. This will cause
+the C<test> action (now that we have assigned an action type to the
+method it appears as a controller "action" to Catalyst) to be executed
+on the "controller/method" URL, or, in this case, "site/test". We
+will see additional information on controller actions throughout the
+rest of the tutorial, but if you are curious take a look at
+L<Catalyst::Manual::Intro/Actions>.
+It's not actually necessary to set the template value as we do here.
+By default TT will attempt to render a template that follows the
+naming pattern "controller/method.tt", and we're following that
+pattern here. However, in other situations you will need to specify
+the template (such as if you've "forwarded" to the method, or if it
+doesn't follow the default naming convention).
+
+We've also put the variable "username" into the stash, for use in the
+template.
+
Make a subdirectory "site" in the "root" directory. Copy the hello.tt
file into the directory as C<root/site/test.tt>, or create a new
template file at that location. Include a line like:
Modified: Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/Intro.pod
===================================================================
--- Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/Intro.pod 2009-03-02 22:37:50 UTC (rev 9414)
+++ Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/Intro.pod 2009-03-03 01:19:03 UTC (rev 9415)
@@ -383,7 +383,7 @@
The 2008 Advent Day 15 entry has more information on using C<pkgsrc> and
NetBSD packages on Solaris:
-L<http://www.catalystframework.org/calendar/2008/15|>.
+L<http://www.catalystframework.org/calendar/2008/15>.
=item *
Modified: Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod
===================================================================
--- Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod 2009-03-02 22:37:50 UTC (rev 9414)
+++ Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod 2009-03-03 01:19:03 UTC (rev 9415)
@@ -140,31 +140,28 @@
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.conf> 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:
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>
@@ -664,20 +661,38 @@
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
small applications. After this demonstration, you should almost always
@@ -712,8 +727,8 @@
$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
@@ -736,9 +751,10 @@
=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
@@ -1106,7 +1122,7 @@
# 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():
@@ -1148,7 +1164,7 @@
# 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():
Modified: Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial.pod
===================================================================
--- Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial.pod 2009-03-02 22:37:50 UTC (rev 9414)
+++ Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial.pod 2009-03-03 01:19:03 UTC (rev 9415)
@@ -11,7 +11,7 @@
The tutorial is divided into the following sections:
-B<NOTE:> CLICK THESE LINKS TO JUMP TO CHAPTERS (the index links above
+B<NOTE: CLICK THESE LINKS TO JUMP TO CHAPTERS> (the index links above
only navigate inside this page).
=over 4
@@ -604,13 +604,14 @@
=item *
People who have emailed me with corrections and suggestions on the
-tutorial. As of the most recent release, this include: Florian Ragwitz,
-Mauro Andreolini, Jim Howard, Giovanni Gigante, William Moreno, Bryan
-Roach, Ashley Berlin, David Kamholz, Kevin Old, Henning Sprang, Jeremy
-Jones, David Kurtz, Ingo Wichmann, and Shlomi Fish. Also, thanks to
-Devin Austin for coming up with an initial version of a non-TTSite
-wrapper page. I'm sure I am missing some names here... apologies for
-that (please let me know if you name should be here).
+tutorial. As of the most recent release, this include: Florian
+Ragwitz, Mauro Andreolini, Jim Howard, Giovanni Gigante, William
+Moreno, Bryan Roach, Ashley Berlin, David Kamholz, Kevin Old, Henning
+Sprang, Jeremy Jones, David Kurtz, Ingo Wichmann, Shlomi Fish, Murray
+Walker. Also, thanks to Devin Austin for coming up with an initial
+version of a non-TTSite wrapper page. I'm sure I am missing some
+names here... apologies for that (please let me know if you name
+should be here).
=back
More information about the Catalyst-commits
mailing list