INSERT INTO book_authors VALUES (5, 8);
B<TIP>: See Appendix 1 for tips on removing the leading spaces when
-cutting and pasting example code from POD documents.
+cutting and pasting example code from POD-based documents.
Then use the following command to build a C<myapp.db> SQLite database:
As you may have noticed, C<-Debug> is not a plugin, but a I<flag>.
Although most of the items specified on the C<use Catalyst> line of your
application class will be plugins, Catalyst supports a limited number of
-flag options (of these, C<-Debug> is the most common).
+flag options (of these, C<-Debug> is the most common). See the
+documentation for C<Catalyst.pm> to get details on other flags
+(currently C<-Engine>, C<-Home>, and C<-Log>).
If you prefer, you can use the C<$c-E<gt>debug> method to enable debug
messages.
=item *
-L<Catalyst::Plugin::Static::Simple>
+L<Catalyst::Plugin::Static::Simple|Catalyst::Plugin::Static::Simple>
C<Static::Simple> provides an easy method of serving static content such
as images and CSS files under the development server.
ConfigLoader
Static::Simple
- Dumper
StackTrace
- DefaultEnd
/;
-This tells Catalyst to start using three new plugins:
+This tells Catalyst to start using one new plugin:
=over 4
=item *
-L<Catalyst::Plugin::Dumper>
-
-Allows you to easily use L<Data::Dumper> to dump variables
-to the logs, for example:
-
- $c->log->dumper($myvar);
-
-When running your application under the development server, the logs
-will be printed to your screen along with the other debug information
-generated by the C<-Debug> flag.
-
-=item *
-
L<Catalyst::Plugin::StackTrace|Catalyst::Plugin::StackTrace>
Adds a stack trace to the standard Catalyst "debug screen" (this is the
screen Catalyst sends to your browser when an error occurs).
-Note: L<Dumper|Catalyst::Plugin::Dumper> output appears on the console
-window where you issue the C<script/myapp_server.pl> command.
-L<StackTrace|Catalyst::Plugin::StackTrace> output appears in your
-browser.
-
-=item *
-
-L<Catalyst::Plugin::DefaultEnd|Catalyst::Plugin::DefaultEnd>
-
-Automatically provides a Catalyst "end action" that invokes your view at
-the end of each request. Also allows you to add "dump_info=1" (precede
-with "?" or "&" depending on where it is in the URL) to I<force> the
-debug screen at the end of the Catalyst request processing cycle.
-
-B<TIP>: Many Catalyst-related documents predate
-L<DefaultEnd|Catalyst::Plugin::DefaultEnd> and suggest that you add an
-C<end> action to your application class (C<MyApp.pm>) or Root.pm
-(C<MyApp/Controller/Root.pm>). In most of these cases, you can convert
-to L<DefaultEnd|Catalyst::Plugin::DefaultEnd> by deleting the C<end>
-action and using the plugin instead.
+Note: L<StackTrace|Catalyst::Plugin::StackTrace> output appears in your
+browser, not in the console window from which you're running your
+application, which is where logging output usually goes.
=back
Note that when specifying plugins on the C<use Catalyst> line, you can
-omit C<Catalyst::Plugin> from the name. Additionally, you can spread
+omit C<Catalyst::Plugin::> from the name. Additionally, you can spread
the plugin names across multiple lines as shown here, or place them all
on one (or more) lines as with the default configuration.
+B<TIP:> You may see examples that include the
+L<Catalyst::Plugin::DefaultEnd|Catalyst::Plugin::DefaultEnd>
+plugins. As of Catalyst 5.7000, C<DefaultEnd> has been
+deprecated in favor of
+L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>
+(as the name of the package suggests, C<RenderView> is not
+a plugin, but an action). The purpose of both is essentially the same:
+forward processing to the view to be rendered. For more information
+on C<RenderView> and the various options for forwarding to your view
+logic, please refer to the "Enable RenderView for the Default View"
+section under "CATALYST VIEWS" below.
+
+
+
=head1 DATABASE ACCESS WITH C<DBIx::Class>
Catalyst can be used with virtually any form of persistent datastore
-available via Perl. For example,
-L<Catalyst::Model::DBI|Catalyst::Model::DBI> can be used to easily
-access databases through the traditional Perl DBI interface. However,
-most Catalyst applications use some form of ORM technology to
+available via Perl. For example,
+L<Catalyst::Model::DBI|Catalyst::Model::DBI> can be used to
+easily access databases through the traditional Perl C<DBI> interface.
+However, most Catalyst applications use some form of ORM technology to
automatically create and save model objects as they are used. Although
-Tony Bowden's L<Class::DBI|Class::DBI> has been the traditional Perl ORM
-engine, Matt Trout's L<DBIx::Class|DBIx::Class> (abbreviated as "DBIC")
-has rapidly emerged as the Perl-based ORM technology of choice. Most
-new Catalyst applications rely on DBIC, as will this tutorial.
-
-Note: See L<Catalyst::Model::CDBI| Catalyst:: Model::CDBI > for more
-information on using Catalyst with L<Class::DBI|Class::DBI>. Catalyst
-can also be used with "plain old DBI"; see L<Catalyst::Model::DBI|
-Catalyst::Model::DBI>.
+Tony Bowden's L<Class::DBI|Class::DBI> has been the traditional
+Perl ORM engine, Matt Trout's L<DBIx::Class|DBIx::Class> (abbreviated
+as "DBIC") has rapidly emerged as the Perl-based ORM technology of choice.
+Most new Catalyst applications rely on DBIC, as will this tutorial.
+Note: See L<Catalyst:: Model::CDBI> for more information on using
+Catalyst with L<Class::DBI|Class::DBI>.
=head2 Create a DBIC Schema File
DBIx::Class uses a schema file 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>).
-In this case, we want to load the model object for the C<books>,
-C<book_authors>, and C<authors> tables created in the previous step.
+sources"; see L<DBIx::Class::ResultSource>). In this case, we want to
+load the model object for the C<books>, C<book_authors>, and C<authors>
+tables created in the previous step.
Open C<lib/MyAppDB.pm> in your editor and insert:
=head1 NAME
- MyAppDB -- DBIC Schema Class
+ MyAppDB - DBIC Schema Class
=cut
B<Note:> C<__PACKAGE__> is just a shorthand way of referencing the name
of the package where it is used. Therefore, in C<MyAppDB.pm>,
-C<__PACKAGE> is equivalent to C<MyAppDB>
+C<__PACKAGE__> is equivalent to C<MyAppDB>.
=head2 Create the DBIC "Result Source" Files
In this step, we create "table classes" (again, these are called a
-"result source" classes in DBIC) that acts as model objects for the
+"result source" classes in DBIC) that act as model objects for the
C<books>, C<book_authors>, and C<authors> tables in our database.
First, create a directory to hold the class:
C<$book-E<gt>book_authors-E<gt>first-E<gt>author-E<gt>last_name> (we
will see examples on how to use DBIC objects in your code soon, but note
that because C<$book-E<gt>book_authors> 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-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.
+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-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.
Next, open C<lib/MyAppDB/Author.pm> in your editor and enter:
objects (e.g., C<Book> and C<Author>); however, Catalyst places no
restrictions on the naming conventions you wish to use.
-
=head2 Use C<Catalyst::Model::DBIC::Schema> To Load The Model Class
When L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> is
model and creates a new set of objects under C<MyApp::Model> for use
inside of Catalyst.
-B<Note:> With
-L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> you
-essentially end up with two sets of model classes (only one of which you
-write... the other set is created automatically in memory when your
-Catalyst application initializes). For this tutorial application, the
-important points to remember are: you write the I<result source> files
-in C<MyAppDB>, but I<within Catalyst> you use the I<automatically
+B<Note:> With
+L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> you
+essentially end up with two sets of model classes (only one of which
+you write... the other set is created automatically in memory when
+your Catalyst application initializes). For this tutorial application,
+the important points to remember are: you write the I<result source>
+files in C<MyAppDB>, but I<within Catalyst> you use the I<automatically
created model classes> in C<MyApp::Model>.
-Use the L<Catalyst::Helper::Model::DBIC::Schema|
-Catalyst::Helper::Model::DBIC::Schema > helper script to create the
-model class that loads up the model we created in the previous step:
+Use the
+L<Catalyst::Helper::Model::DBIC::Schema|Catalyst::Helper::Model::DBIC::Schema>
+helper script to create the model class that loads up the model we
+created in the previous step:
$ script/myapp_create.pl model MyAppDB DBIC::Schema MyAppDB dbi:SQLite:myapp.db '' '' '{ AutoCommit => 1 }'
applications often use the directories C<M>, C<V>, and C<C>]).
-
=head1 CREATE A CATALYST CONTROLLER
-Controllers are where you write methods that respond to C<GET> and C<POST> messages from the user's web browser.
+Controllers are where you write methods that interact with user
+input--typically, controller methods respond to C<GET> and C<POST>
+messages from the user's web browser.
-Use the Catalyst C<create> script to add a controller for book-related actions:
+Use the Catalyst C<create> script to add a controller for book-related
+actions:
$ script/myapp_create.pl controller Books
are equivalent.
B<Note:> Catalyst actions are regular Perl methods, but they make use of
-Nicholas Clark's C<attributes> module to provide additional information
-to the Catalyst dispatcher logic.
-
+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.
=head1 CATALYST VIEWS
-Views are where you render output for display in the user's web browser
-(or possibly using other display technology). As with virtually every
-aspect of Catalyst, options abound when it comes to the specific view
-technology you adopt inside your application. However, most Catalyst
-applications use the Template Toolkit, known as TT (for more information
-on TT, see L<http://www.template-toolkit.org>). Other popular View
-technologies include Mason (L<http://www.masonhq.com> and
+Views are where you render output, typically for display in the user's
+web browser, but also possibly using other display output-generation
+systems. As with virtually every aspect of Catalyst, options abound
+when it comes to the specific view technology you adopt inside your
+application. However, most Catalyst applications use the Template
+Toolkit, known as TT (for more information on TT, see
+L<http://www.template-toolkit.org>). Other popular View technologies
+include Mason (L<http://www.masonhq.com> and
L<http://www.masonbook.com>) and L<HTML::Template|HTML::Template>
(L<http://html-template.sourceforge.net>).
-
=head2 Create a Catalyst View Using C<TTSITE>
When using TT for the Catalyst view, there are two main helper scripts:
Both are similar, but C<TT> merely creates the C<lib/MyApp/View/TT.pm>
file and leaves the creation of any hierarchical template organization
-entirely up to you (it also creates a C<t/view_TT.t> file for testing;
-test cases will be discussed in Part 7). Conversely, the C<TTSite>
-helper creates a modular and hierarchical view layout with separate
-Template Toolkit (TT) files for common header and footer information,
-configuration values, a CSS stylesheet, etc.
+entirely up to you. (It also creates a C<t/view_TT.t> file for testing;
+test cases will be discussed in Part 7). The C<TTSite> helper creates a
+modular and hierarchical view layout with separate Template Toolkit (TT)
+files for common header and footer information, configuration values, a
+CSS stylesheet, and more.
Enter the following command to enable the C<TTSite> style of view
-rendering for the tutorial:
+rendering for this tutorial:
$ script/myapp_create.pl view TT TTSite
B<TIP>: Note that TTSite does one thing that could confuse people who
are used to the normal C<TT> Catalyst View: it redefines the Catalyst
-context object in templates from its usual C<c> to C<Catalyst>. Also
-keep this in mind when looking at other Catalyst examples (they almost
-always use C<c>). Note that Catalyst and TT I<do not complain> when you
-use the wrong name to access the context... it simply outputs blanks for
-that bogus logic. Finally, be aware that this change in name I<only>
-applies to how the context object is accessed inside your TT templates,
+context object in templates from its usual C<c> to C<Catalyst>. When
+looking at other Catalyst examples, remember that they almost always use
+C<c>. Note that Catalyst and TT I<do not complain> when you use the
+wrong name to access the context object...TT simply outputs blanks for
+that bogus logic (see next tip to change this behavior with TT C<DEBUG>
+options). Finally, be aware that this change in name I<only>
+applies to how the context object is accessed inside your TT templates;
your controllers will continue to use C<$c> (or whatever name you use
-when fetching the reference from C<@_> inside your methods). (You can
+when fetching the reference from C<@_> inside your methods). (You can
change back to the "default" behavior be removing the C<CATALYST_VAR>
line from C<lib/MyApp/View/TT.pm>, but you will also have to edit
C<root/lib/config/main> and C<root/lib/config/url>. If you do this, be
careful not to have a collision between your own C<c> variable and the
Catalyst C<c> variable.)
+B<TIP>: When troubleshooting TT it can be helpful to enable variable
+C<DEBUG> options. You can do this in a Catalyst environment by adding
+a C<DEBUG> line to the C<__PACKAGE__->config> declaration in
+C<MyApp/View/TT.pm>:
+
+ __PACKAGE__->config({
+ CATALYST_VAR => 'Catalyst',
+ ...
+ DEBUG => 'undef',
+ ...
+ });
+
+There are a variety of options you can use, such as 'undef', 'all',
+'service', 'context', 'parser', 'provider', and 'service'. See
+L<Template::Constants> for more information (remove the C<DEBUG_>
+portion of the name shown in the TT docs and convert to lower case
+for use inside Catalyst).
+
+
+=head2 Enable C<RenderView> for the Default View
+
+In keeping with Catalyst's goal of providing an extremely flexible
+development platform, a single Catalyst application can simultaneously
+use multiple view rendering technologies. While it's nice to know that
+you are using a deveopment framework with this sort of adaptability, it
+also makes sense that we want to define a default view mechanism for our
+application. Depending on the age of the code, you will likely run into
+one of three different solutions to this issue:
+
+=over 4
+
+=item *
+
+Private C<end> Action in Application Class
+
+Older Catalyst-related documents often suggest that you add a "private
+end action" to your application class (C<MyApp.pm>) or Root.pm
+(C<MyApp/Controller/Root.pm>). These examples should be easily
+converted to L<Catalyst|Catalyst::Action::RenderView> using the example
+code shown below.
+
+=item *
+
+L<Catalyst::Plugin::DefaultEnd|Catalyst::Plugin::DefaultEnd>
+
+C<DefaultEnd> automatically provides a Catalyst "end action" that
+invokes your view at the end of each request. Also allows you to add
+"dump_info=1" (precede with "?" or "&" depending on where it is in the
+URL) to I<force> the debug screen at the end of the Catalyst request
+processing cycle. Although it was easier to implement than the earlier
+C<end> action approach, it was also less extensible than the newer
+L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>.
+
+=item *
+
+L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>
+
+The current recommended approach to handling your view logic relies on
+L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>. Although
+similar to the "private end action" approach, it utilizes Catalyst's
+"ActionClass" mechanism to provide easy extensibility. As with
+C<DefaultEnd>, it allows you to add "dump_info=1" (precede with "?" or
+"&" depending on where it is in the URL) to I<force> the debug screen at
+the end of the Catalyst request processing cycle.
+
+=back
+
+To enable C<RenderView>, edit C<lib/MyApp/Controller/Root.pm> and insert
+the following method:
+
+ =head 2 end
+
+ Forward to a default view.
+
+ =cut
+
+ sub end :ActionClass('RenderView') {
+ my ($self, $c) = @_;
+ $c->forward('MyApp::View::TT') unless $c->res->body;
+ }
=head2 Globally Customize Every View
When using TTSite, files in the subdirectories of C<root/lib> can be
used to make changes that will appear in every view. For example, to
display optional status and error messages in every view, edit
-C<root/lib/site/layout> update it to match the following (the two HTML
+C<root/lib/site/layout>, updating it to match the following (the two HTML
C<span> elements are new):
<div id="header">[% PROCESS site/header %]</div>
<div id="footer">[% PROCESS site/footer %]</div>
If we set either message in the Catalyst stash (e.g.,
-C<$c-E<gt>stash-E<gt>{status_msg} = 'Hello world'>) it will be displayed
-whenever any view used by that request is rendered. The C<message> and
-C<error> CSS styles are automatically defined in C<root/src/ttsite.css>
-and can be customized to suit your needs.
+C<$c-E<gt>stash-E<gt>{status_msg} = 'Request was successful!'>) it will
+be displayed whenever any view used by that request is rendered. The
+C<message> and C<error> CSS styles are automatically defined in
+C<root/src/ttsite.css> and can be customized to suit your needs.
B<Note:> The Catalyst stash only lasts for a single HTTP request. If
you need to retain information across requests you can use
L<Catalyst::Plugin::Session|Catalyst::Plugin::Session> (we will use
-Catalyst sessions in the Authentication part).
+Catalyst sessions in the Authentication part of the tutorial).
=head2 Create a TT Template Page
<td>[% book.title %]</td>
<td>[% book.rating %]</td>
<td>
- [% # Print author count in parens. 'book.authors' uses the 'many_to_many' -%]
- [% # relationship to retrieve all of the authors of a book. 'size' is a -%]
- [% # TT VMethod to get the number of elements in a list. -%]
- ([% book.authors.size %])
- [% # Use an alternate form of a FOREACH loop to display authors. -%]
- [% # _ below is the TT string concatenation operator. -%]
- [% author.last_name _' ' FOREACH author = book.authors %]
- [% # Note: if many_to_many relationship not used in Authors.pm, you could -%]
- [% # have used the following to 'walk' through the 'join table objects' -%]
- [% # bk_author.author.last_name _' ' FOREACH bk_author = book.book_authors %]
+ [% # 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 -%]
+ [% # authors into the list. Note that we make a bogus assignment to the -%]
+ [% # 'unused' vbl to avoid printing the size of the list after each push. -%]
+ [% tt_authors = [ ];
+ unused = tt_authors.push(author.last_name) FOREACH author = book.authors %]
+ [% # Now use a TT 'virtual method' to display the author count in parens -%]
+ ([% tt_authors.size %])
+ [% # Use another vmethod to join & print the names with comma separators -%]
+ [% tt_authors.join(', ') %]
</td>
</tr>
[% END -%]
TT's META feature to provide a title to C<root/lib/site/header>.
Meanwhile, the outer C<FOREACH> loop iterates through each C<book> model
object and prints the C<title> and C<rating> fields. An inner
-C<FOREACH> loop prints the last name of each author in a single table
-cell (a simple space is used between the names; in reality you would
-probably want to modify the code to use a comma as a separator).
+C<FOREACH> loop prints the last name of each author in a comma-separated
+list within a single table cell.
-If you are new to TT, the [% and %] tags are used to delimit "variable
-text". TT supports a wide variety of directives for "calling" other
+If you are new to TT, the C<[%> and C<%]> tags are used to delimit TT
+code. TT supports a wide variety of directives for "calling" other
files, looping, conditional logic, etc. In general, TT simplifies the
usual range of Perl operators down to the single dot (C<.>) operator.
This applies to operations as diverse as method calls, hash lookups, and
consistency with the files already created by the C<TTSite> helper.
-
=head1 RUN THE APPLICATION
First, let's enable an environment variable option that causes
$ export DBIX_CLASS_STORAGE_DBI_DEBUG=1
+This assumes you are using BASH as your shell -- adjust accordingly if
+you are using a different shell (for example, under tcsh, use
+C<setenv DBIX_CLASS_STORAGE_DBI_DEBUG 1>).
+
B<NOTE>: You can also set this in your code using
C<$class-E<gt>storage-E<gt>debug(1);>. See
-L<DBIx::Class::Manual::Troubleshooting|DBIx::Class::Manual::Troubleshooting>
-for details (including options to log to file vs. the Catalyst
-development server log.
+L<DBIx::Class::Manual::Troubleshooting> for details (including options
+to log to file instead of displaying to the Catalyst development server
+log).
Then run the Catalyst "demo server" script:
[Tue May 16 12:51:33 2006] [catalyst] [debug] Debug messages enabled
[Tue May 16 12:51:33 2006] [catalyst] [debug] Loaded plugins:
.------------------------------------------------------------------------------.
- | Catalyst::Plugin::ConfigLoader 0.07 |
+ | Catalyst::Plugin::ConfigLoader 0.09 |
| Catalyst::Plugin::Static::Simple 0.14 |
- | Catalyst::Plugin::Dumper 0.000002 |
| Catalyst::Plugin::StackTrace 0.04 |
| Catalyst::Plugin::DefaultEnd 0.06 |
'------------------------------------------------------------------------------'
=back
-
Point your browser to L<http://localhost:3000> and you should still get
the Catalyst welcome page.
Kennedy Clark, C<hkclark@gmail.com>
-Please report any errors, issues or suggestions to the author.
-
-Copyright 2006, Kennedy Clark, under Creative Commons License (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).
+Please report any errors, issues or suggestions to the author. The
+most recent version of the Catlayst Tutorial can be found at
+L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/>.
-Version: .94
+Copyright 2006, Kennedy Clark, under Creative Commons License
+(L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).
projects / catagits/Catalyst-Runtime.git / blobdiff