3 Catalyst::Manual::Tutorial::CatalystBasics - Catalyst Tutorial - Part 2: Catalyst Application Development Basics
8 This is B<Part 2 of 9> for the Catalyst tutorial.
10 L<Tutorial Overview|Catalyst::Manual::Tutorial>
16 L<Introduction|Catalyst::Manual::Tutorial::Intro>
24 L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
28 L<Authentication|Catalyst::Manual::Tutorial::Authentication>
32 L<Authorization|Catalyst::Manual::Tutorial::Authorization>
36 L<Debugging|Catalyst::Manual::Tutorial::Debugging>
40 L<Testing|Catalyst::Manual::Tutorial::Testing>
44 L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
48 L<Appendices|Catalyst::Manual::Tutorial::Appendicies>
54 In this part of the tutorial, we will create a very basic Catalyst web
55 application. Though simple in many respects, this section will already
56 demonstrate a number of powerful capabilities such as:
60 =item * Helper Scripts
62 Catalyst helper scripts that can be used to rapidly bootstrap the
63 skeletal structure of an application.
67 Model/View/Controller (MVC) provides an architecture that facilitates a
68 clean "separation of control" between the different portions of your
69 application. Given that many other documents cover this subject in
70 detail, MVC will not be discussed in depth here (for an excellent
71 introduction to MVC and general Catalyst concepts, please see
72 L<Catalyst::Manual::About>. In short:
78 The model usually represents a data store. In most applications, the
79 model equates to the objects that are created from and saved to your SQL
84 The view takes model objects and renders them into something for the end
85 user to look at. Normally this involves a template-generation tool that
86 creates HTML for the user's web browser, but it could easily be code
87 that generates other forms such as PDF documents, e-mails, or Excel
92 As suggested by its name, the controller takes user requests and routes
93 them to the necessary model and view.
99 The use of Object-Relational Mapping (ORM) technology for database
100 access. Specifically, ORM provides an automated and standardized means
101 to persist and restore objects to/from a relational database.
105 B<TIP>: Note that all of the code for this part of the tutorial can be
106 pulled from the Catalyst Subversion repository in one step with the
109 svn checkout http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial@###
110 IMPORTANT: Does not work yet. Will be completed for final version.
113 =head1 CREATE A CATALYST PROJECT
115 Catalyst provides a number of helper scripts that can be used to quickly
116 flesh out the basic structure of your application. All Catalyst projects
117 begin with the C<catalyst.pl> helper.
119 In the case of this tutorial, use the Catalyst C<catalyst.pl> script to
120 initialize the framework for an application called C<MyApp>:
125 The C<catalyst.pl> helper script will display the names of the
126 directories and files it creates.
128 Though it's too early for any significant celebration, we already have a
129 functioning application. Run the following command to run this
130 application with the built-in development web server:
132 $ script/myapp_server.pl
134 Point your web browser to L<http://localhost:3000> (substituting a
135 different hostname or IP address as appropriate) and you should be
136 greeted by the Catalyst welcome screen. Press Ctrl-C to break out of
137 the development server.
139 =head1 CREATE A SQLITE DATABASE
141 In this step, we make a text file with the required SQL commands to
142 create a database table and load some sample data. Open C<myapp01.sql>
143 in your editor and enter:
146 -- Create a very simple database to hold book and author information
149 id INTEGER PRIMARY KEY,
153 -- 'book_authors' is a many-to-many join table between books & authors
154 CREATE TABLE book_authors (
157 PRIMARY KEY (book_id, author_id)
159 CREATE TABLE authors (
160 id INTEGER PRIMARY KEY,
165 --- Load some sample data
167 INSERT INTO books VALUES (1, 'CCSP SNRS Exam Certification Guide', 5);
168 INSERT INTO books VALUES (2, 'TCP/IP Illustrated, Volume 1', 5);
169 INSERT INTO books VALUES (3, 'Internetworking with TCP/IP Vol.1', 4);
170 INSERT INTO books VALUES (4, 'Perl Cookbook', 5);
171 INSERT INTO books VALUES (5, 'Designing with Web Standards', 5);
172 INSERT INTO authors VALUES (1, 'Greg', 'Bastien');
173 INSERT INTO authors VALUES (2, 'Sara', 'Nasseh');
174 INSERT INTO authors VALUES (3, 'Christian', 'Degu');
175 INSERT INTO authors VALUES (4, 'Richard', 'Stevens');
176 INSERT INTO authors VALUES (5, 'Douglas', 'Comer');
177 INSERT INTO authors VALUES (6, 'Tom', 'Christiansen');
178 INSERT INTO authors VALUES (7, ' Nathan', 'Torkington');
179 INSERT INTO authors VALUES (8, 'Jeffrey', 'Zeldman');
180 INSERT INTO book_authors VALUES (1, 1);
181 INSERT INTO book_authors VALUES (1, 2);
182 INSERT INTO book_authors VALUES (1, 3);
183 INSERT INTO book_authors VALUES (2, 4);
184 INSERT INTO book_authors VALUES (3, 5);
185 INSERT INTO book_authors VALUES (4, 6);
186 INSERT INTO book_authors VALUES (4, 7);
187 INSERT INTO book_authors VALUES (5, 8);
189 B<TIP>: See Appendix 1 for tips on removing the leading spaces when
190 cutting and pasting example code from POD-based documents.
192 Then use the following command to build a C<myapp.db> SQLite database:
194 $ sqlite3 myapp.db < myapp01.sql
196 If you need to create the database more than once, you probably want to
197 issue the C<rm myapp.db> command to delete the database before you use
198 the C<sqlite3 myapp.db < myapp01.sql> command.
200 Once the C<myapp.db> database file has been created and initialized, you
201 can use the SQLite command line environment to do a quick dump of the
206 Enter ".help" for instructions
207 sqlite> select * from books;
208 1|CCSP SNRS Exam Certification Guide|5
209 2|TCP/IP Illustrated, Volume 1|5
210 3|Internetworking with TCP/IP Vol.1|4
212 5|Designing with Web Standards|5
218 $ sqlite3 myapp.db "select * from books"
219 1|CCSP SNRS Exam Certification Guide|5
220 2|TCP/IP Illustrated, Volume 1|5
221 3|Internetworking with TCP/IP Vol.1|4
223 5|Designing with Web Standards|5
225 As with most other SQL tools, if you are using the full "interactive"
226 environment you need to terminate your SQL commands with a ";" (it's not
227 required if you do a single SQL statement on the command line). Use
228 ".q" to exit from SQLite from the SQLite interactive mode and return to
229 your OS command prompt.
232 =head1 EDIT THE LIST OF CATALYST PLUGINS
234 One of the greatest benefits of Catalyst is that it has such a large
235 library of plugins available. Plugins are used to seamlessly integrate
236 existing Perl modules into the overall Catalyst framework. In general,
237 they do this by adding additional methods to the C<context> object
238 (generally written as C<$c>) that Catalyst passes to every component
239 throughout the framework.
241 By default, Catalyst enables three plugins/flags:
249 Enables the Catalyst debug output you saw when we started the
250 C<script/myapp_server.pl> development server earlier. You can remove
251 this plugin when you place your application into production.
253 As you may have noticed, C<-Debug> is not a plugin, but a I<flag>.
254 Although most of the items specified on the C<use Catalyst> line of your
255 application class will be plugins, Catalyst supports a limited number of
256 flag options (of these, C<-Debug> is the most common). See the
257 documentation for C<Catalyst.pm> to get details on other flags
258 (currently C<-Engine>, C<-Home>, and C<-Log>).
260 If you prefer, you can use the C<$c-E<gt>debug> method to enable debug
265 L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
267 C<ConfigLoader> provides an automatic way to load configurable
268 parameters for your application from a central YAML file (versus having
269 the values hard-coded inside your Perl modules). If you have not been
270 exposed to YAML before, it is a human-readable data serialization format
271 that can be used to read (and write) values to/from text files. We will
272 see how to use this feature of Catalyst during the authentication and
273 authorization sections (Part 4 and Part 5).
277 L<Catalyst::Plugin::Static::Simple|Catalyst::Plugin::Static::Simple>
279 C<Static::Simple> provides an easy method of serving static content such
280 as images and CSS files under the development server.
284 To modify the list of plugins, edit C<lib/MyApp.pm> (this file is
285 generally referred to as your I<application class>) and delete the line
288 use Catalyst qw/-Debug ConfigLoader Static::Simple/;
300 This tells Catalyst to start using one new plugin:
306 L<Catalyst::Plugin::StackTrace|Catalyst::Plugin::StackTrace>
308 Adds a stack trace to the standard Catalyst "debug screen" (this is the
309 screen Catalyst sends to your browser when an error occurs).
311 Note: L<StackTrace|Catalyst::Plugin::StackTrace> output appears in your
312 browser, not in the console window from which you're running your
313 application, which is where logging output usually goes.
317 Note that when specifying plugins on the C<use Catalyst> line, you can
318 omit C<Catalyst::Plugin::> from the name. Additionally, you can spread
319 the plugin names across multiple lines as shown here, or place them all
320 on one (or more) lines as with the default configuration.
322 B<TIP:> You may see examples that include the
323 L<Catalyst::Plugin::DefaultEnd|Catalyst::Plugin::DefaultEnd>
324 plugins. As of Catalyst 5.7000, C<DefaultEnd> has been
325 deprecated in favor of
326 L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>
327 (as the name of the package suggests, C<RenderView> is not
328 a plugin, but an action). The purpose of both is essentially the same:
329 forward processing to the view to be rendered. For more information
330 on C<RenderView> and the various options for forwarding to your view
331 logic, please refer to the "Enable RenderView for the Default View"
332 section under "CATALYST VIEWS" below.
336 =head1 DATABASE ACCESS WITH C<DBIx::Class>
338 Catalyst can be used with virtually any form of persistent datastore
339 available via Perl. For example,
340 L<Catalyst::Model::DBI|Catalyst::Model::DBI> can be used to
341 easily access databases through the traditional Perl C<DBI> interface.
342 However, most Catalyst applications use some form of ORM technology to
343 automatically create and save model objects as they are used. Although
344 Tony Bowden's L<Class::DBI|Class::DBI> has been the traditional
345 Perl ORM engine, Matt Trout's L<DBIx::Class|DBIx::Class> (abbreviated
346 as "DBIC") has rapidly emerged as the Perl-based ORM technology of choice.
347 Most new Catalyst applications rely on DBIC, as will this tutorial.
349 Note: See L<Catalyst:: Model::CDBI> for more information on using
350 Catalyst with L<Class::DBI|Class::DBI>.
352 =head2 Create a DBIC Schema File
354 DBIx::Class uses a schema file to load other classes that represent the
355 tables in your database (DBIC refers to these "table objects" as "result
356 sources"; see L<DBIx::Class::ResultSource>). In this case, we want to
357 load the model object for the C<books>, C<book_authors>, and C<authors>
358 tables created in the previous step.
360 Open C<lib/MyAppDB.pm> in your editor and insert:
366 MyAppDB - DBIC Schema Class
370 # Our schema needs to inherit from 'DBIx::Class::Schema'
371 use base qw/DBIx::Class::Schema/;
373 # Need to load the DB Model classes here.
374 # You can use this syntax if you want:
375 # __PACKAGE__->load_classes(qw/Book BookAuthor Author/);
376 # Also, if you simply want to load all of the classes in a directory
377 # of the same name as your schema class (as we do here) you can use:
378 # __PACKAGE__->load_classes(qw//);
379 # But the variation below is more flexible in that it can be used to
380 # load from multiple namespaces.
381 __PACKAGE__->load_classes({
382 MyAppDB => [qw/Book BookAuthor Author/]
387 B<Note:> C<__PACKAGE__> is just a shorthand way of referencing the name
388 of the package where it is used. Therefore, in C<MyAppDB.pm>,
389 C<__PACKAGE__> is equivalent to C<MyAppDB>.
392 =head2 Create the DBIC "Result Source" Files
394 In this step, we create "table classes" (again, these are called a
395 "result source" classes in DBIC) that act as model objects for the
396 C<books>, C<book_authors>, and C<authors> tables in our database.
398 First, create a directory to hold the class:
402 Then open C<lib/MyAppDB/Book.pm> in your editor and enter:
404 package MyAppDB::Book;
406 use base qw/DBIx::Class/;
408 # Load required DBIC stuff
409 __PACKAGE__->load_components(qw/PK::Auto Core/);
411 __PACKAGE__->table('books');
412 # Set columns in table
413 __PACKAGE__->add_columns(qw/id title rating/);
414 # Set the primary key for the table
415 __PACKAGE__->set_primary_key(qw/id/);
423 # 1) Name of relationship, DBIC will create accessor with this name
424 # 2) Name of the model class referenced by this relationship
425 # 3) Column name in *foreign* table
426 __PACKAGE__->has_many(book_authors => 'MyAppDB::BookAuthor', 'book_id');
430 # 1) Name of relationship, DBIC will create accessor with this name
431 # 2) Name of has_many() relationship this many_to_many() is shortcut for
432 # 3) Name of belongs_to() relationship in model class of has_many() above
433 # You must already have the has_many() defined to use a many_to_many().
434 __PACKAGE__->many_to_many(authors => 'book_authors', 'author');
439 MyAppDB::Book - A model object representing a book.
443 This is an object that represents a row in the 'books' table of your application
444 database. It uses DBIx::Class (aka, DBIC) to do ORM.
446 For Catalyst, this is designed to be used through MyApp::Model::MyAppDB.
447 Offline utilities may wish to use this class directly.
453 This defines both a C<has_many> and a C<many_to_many> relationship. The
454 C<many_to_many> relationship is optional, but it makes it easier to map
455 a book to its collection of authors. Without it, we would have to
456 "walk" though the C<book_authors> table as in
457 C<$book-E<gt>book_authors-E<gt>first-E<gt>author-E<gt>last_name> (we
458 will see examples on how to use DBIC objects in your code soon, but note
459 that because C<$book-E<gt>book_authors> can return multiple authors, we
460 have to use C<first> to display a single author). C<many_to_many> allows
461 us to use the shorter C<$book-E<gt>authors-E<gt>first-E<gt>last_name>.
462 Note that you cannot define a C<many_to_many> relationship without also
463 having the C<has_many> relationship in place.
465 Next, open C<lib/MyAppDB/Author.pm> in your editor and enter:
467 package MyAppDB::Author;
469 use base qw/DBIx::Class/;
471 # Load required DBIC stuff
472 __PACKAGE__->load_components(qw/PK::Auto Core/);
474 __PACKAGE__->table('authors');
475 # Set columns in table
476 __PACKAGE__->add_columns(qw/id first_name last_name/);
477 # Set the primary key for the table
478 __PACKAGE__->set_primary_key(qw/id/);
486 # 1) Name of relationship, DBIC will create accessor with this name
487 # 2) Name of the model class referenced by this relationship
488 # 3) Column name in *foreign* table
489 __PACKAGE__->has_many(book_author => 'MyAppDB::BookAuthor', 'author_id');
493 # 1) Name of relationship, DBIC will create accessor with this name
494 # 2) Name of has_many() relationship this many_to_many() is shortcut for
495 # 3) Name of belongs_to() relationship in model class of has_many() above
496 # You must already have the has_many() defined to use a many_to_many().
497 __PACKAGE__->many_to_many(books => 'book_author', 'book');
502 MyAppDB::Author - A model object representing an author of a book (if a book has
503 multiple authors, each will be represented be separate Author object).
507 This is an object that represents a row in the 'authors' table of your application
508 database. It uses DBIx::Class (aka, DBIC) to do ORM.
510 For Catalyst, this is designed to be used through MyApp::Model::MyAppDB.
511 Offline utilities may wish to use this class directly.
517 Finally, open C<lib/MyAppDB/BookAuthor.pm> in your editor and enter:
519 package MyAppDB::BookAuthor;
521 use base qw/DBIx::Class/;
523 # Load required DBIC stuff
524 __PACKAGE__->load_components(qw/PK::Auto Core/);
526 __PACKAGE__->table('book_authors');
527 # Set columns in table
528 __PACKAGE__->add_columns(qw/book_id author_id/);
529 # Set the primary key for the table
530 __PACKAGE__->set_primary_key(qw/book_id author_id/);
538 # 1) Name of relationship, DBIC will create accessor with this name
539 # 2) Name of the model class referenced by this relationship
540 # 3) Column name in *this* table
541 __PACKAGE__->belongs_to(book => 'MyAppDB::Book', 'book_id');
545 # 1) Name of relationship, DBIC will create accessor with this name
546 # 2) Name of the model class referenced by this relationship
547 # 3) Column name in *this* table
548 __PACKAGE__->belongs_to(author => 'MyAppDB::Author', 'author_id');
553 MyAppDB::BookAuthor - A model object representing the JOIN between an author and
558 This is an object that represents a row in the 'book_authors' table of your
559 application database. It uses DBIx::Class (aka, DBIC) to do ORM.
561 You probably won't need to use this class directly -- it will be automatically
562 used by DBIC where joins are needed.
564 For Catalyst, this is designed to be used through MyApp::Model::MyAppDB.
565 Offline utilities may wish to use this class directly.
571 B<Note:> This sample application uses a plural form for the database
572 tables (e.g., C<books> and C<authors>) and a singular form for the model
573 objects (e.g., C<Book> and C<Author>); however, Catalyst places no
574 restrictions on the naming conventions you wish to use.
576 =head2 Use C<Catalyst::Model::DBIC::Schema> To Load The Model Class
578 When L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> is
579 in use, Catalyst essentially reads an existing copy of your database
580 model and creates a new set of objects under C<MyApp::Model> for use
584 L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> you
585 essentially end up with two sets of model classes (only one of which
586 you write... the other set is created automatically in memory when
587 your Catalyst application initializes). For this tutorial application,
588 the important points to remember are: you write the I<result source>
589 files in C<MyAppDB>, but I<within Catalyst> you use the I<automatically
590 created model classes> in C<MyApp::Model>.
593 L<Catalyst::Helper::Model::DBIC::Schema|Catalyst::Helper::Model::DBIC::Schema>
594 helper script to create the model class that loads up the model we
595 created in the previous step:
597 $ script/myapp_create.pl model MyAppDB DBIC::Schema MyAppDB dbi:SQLite:myapp.db '' '' '{ AutoCommit => 1 }'
599 Where the first C<MyAppDB> is the name of the class to be created by the
600 helper in C<lib/MyApp/Model> and the second C<MyAppDB> is the name of
601 existing schema file we created (in C<lib/MyAppDB.pm>). You can see
602 that the helper creates a model file under C<lib/MyApp/Model> (Catalyst
603 has a separate directory under C<lib/MyApp> for each of the three parts
604 of MVC: C<Model>, C<View>, and C<Controller> [although older Catalyst
605 applications often use the directories C<M>, C<V>, and C<C>]).
608 =head1 CREATE A CATALYST CONTROLLER
610 Controllers are where you write methods that interact with user
611 input--typically, controller methods respond to C<GET> and C<POST>
612 messages from the user's web browser.
614 Use the Catalyst C<create> script to add a controller for book-related
617 $ script/myapp_create.pl controller Books
619 Then edit C<lib/MyApp/Controller/Books.pm> and add the following method
624 Fetch all book objects and pass to books/list.tt2 in stash to be displayed
629 # Retrieve the usual perl OO '$self' for this object. $c is the Catalyst
630 # 'Context' that's used to 'glue together' the various components
631 # that make up the application
634 # Retrieve all of the book records as book model objects and store in the
635 # stash where they can be accessed by the TT template
636 $c->stash->{books} = [$c->model('MyAppDB::Book')->all];
638 # Set the TT template to use. You will almost always want to do this
639 # in your action methods.
640 $c->stash->{template} = 'books/list.tt2';
643 B<Note:> Programmers experienced with object-oriented Perl should
644 recognize C<$self> as a reference to the object where this method was
645 called. On the other hand, C<$c> will be new to many Perl programmers
646 who have not used Catalyst before (it's sometimes written as
647 C<$context>). The Context object is automatically passed to all
648 Catalyst components. It is used to pass information between components
649 and provide access to Catalyst and plugin functionality.
651 B<TIP>: You may see the C<$c-E<gt>model('MyAppDB::Book')> used above
652 written as C<$c-E<gt>model('MyAppDB')-E<gt>resultset('Book)>. The two
655 B<Note:> Catalyst actions are regular Perl methods, but they make use of
656 Nicholas Clark's C<attributes> module (that's the C<: Local> next to the
657 C<sub list> in the code above) to provide additional information to the
658 Catalyst dispatcher logic.
660 =head1 CATALYST VIEWS
662 Views are where you render output, typically for display in the user's
663 web browser, but also possibly using other display output-generation
664 systems. As with virtually every aspect of Catalyst, options abound
665 when it comes to the specific view technology you adopt inside your
666 application. However, most Catalyst applications use the Template
667 Toolkit, known as TT (for more information on TT, see
668 L<http://www.template-toolkit.org>). Other popular View technologies
669 include Mason (L<http://www.masonhq.com> and
670 L<http://www.masonbook.com>) and L<HTML::Template|HTML::Template>
671 (L<http://html-template.sourceforge.net>).
673 =head2 Create a Catalyst View Using C<TTSITE>
675 When using TT for the Catalyst view, there are two main helper scripts:
681 L<Catalyst::Helper::View::TT|Catalyst::Helper::View::TT>
685 L<Catalyst::Helper::View::TTSite|Catalyst::Helper::View::TTSite>
689 Both are similar, but C<TT> merely creates the C<lib/MyApp/View/TT.pm>
690 file and leaves the creation of any hierarchical template organization
691 entirely up to you. (It also creates a C<t/view_TT.t> file for testing;
692 test cases will be discussed in Part 7). The C<TTSite> helper creates a
693 modular and hierarchical view layout with separate Template Toolkit (TT)
694 files for common header and footer information, configuration values, a
695 CSS stylesheet, and more.
697 Enter the following command to enable the C<TTSite> style of view
698 rendering for this tutorial:
700 $ script/myapp_create.pl view TT TTSite
702 This puts a number of files in the C<root/lib> and C<root/src>
703 directories that can be used to customize the look and feel of your
704 application. Also take a look at C<lib/MyApp/View/TT.pm> for config
705 values set by the C<TTSite> helper.
707 B<TIP>: Note that TTSite does one thing that could confuse people who
708 are used to the normal C<TT> Catalyst View: it redefines the Catalyst
709 context object in templates from its usual C<c> to C<Catalyst>. When
710 looking at other Catalyst examples, remember that they almost always use
711 C<c>. Note that Catalyst and TT I<do not complain> when you use the
712 wrong name to access the context object...TT simply outputs blanks for
713 that bogus logic (see next tip to change this behavior with TT C<DEBUG>
714 options). Finally, be aware that this change in name I<only>
715 applies to how the context object is accessed inside your TT templates;
716 your controllers will continue to use C<$c> (or whatever name you use
717 when fetching the reference from C<@_> inside your methods). (You can
718 change back to the "default" behavior be removing the C<CATALYST_VAR>
719 line from C<lib/MyApp/View/TT.pm>, but you will also have to edit
720 C<root/lib/config/main> and C<root/lib/config/url>. If you do this, be
721 careful not to have a collision between your own C<c> variable and the
722 Catalyst C<c> variable.)
724 B<TIP>: When troubleshooting TT it can be helpful to enable variable
725 C<DEBUG> options. You can do this in a Catalyst environment by adding
726 a C<DEBUG> line to the C<__PACKAGE__->config> declaration in
729 __PACKAGE__->config({
730 CATALYST_VAR => 'Catalyst',
736 There are a variety of options you can use, such as 'undef', 'all',
737 'service', 'context', 'parser', 'provider', and 'service'. See
738 L<Template::Constants> for more information (remove the C<DEBUG_>
739 portion of the name shown in the TT docs and convert to lower case
740 for use inside Catalyst).
743 =head2 Enable C<RenderView> for the Default View
745 In keeping with Catalyst's goal of providing an extremely flexible
746 development platform, a single Catalyst application can simultaneously
747 use multiple view rendering technologies. While it's nice to know that
748 you are using a deveopment framework with this sort of adaptability, it
749 also makes sense that we want to define a default view mechanism for our
750 application. Depending on the age of the code, you will likely run into
751 one of three different solutions to this issue:
757 Private C<end> Action in Application Class
759 Older Catalyst-related documents often suggest that you add a "private
760 end action" to your application class (C<MyApp.pm>) or Root.pm
761 (C<MyApp/Controller/Root.pm>). These examples should be easily
762 converted to L<Catalyst|Catalyst::Action::RenderView> using the example
767 L<Catalyst::Plugin::DefaultEnd|Catalyst::Plugin::DefaultEnd>
769 C<DefaultEnd> automatically provides a Catalyst "end action" that
770 invokes your view at the end of each request. Also allows you to add
771 "dump_info=1" (precede with "?" or "&" depending on where it is in the
772 URL) to I<force> the debug screen at the end of the Catalyst request
773 processing cycle. Although it was easier to implement than the earlier
774 C<end> action approach, it was also less extensible than the newer
775 L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>.
779 L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>
781 The current recommended approach to handling your view logic relies on
782 L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>. Although
783 similar to the "private end action" approach, it utilizes Catalyst's
784 "ActionClass" mechanism to provide easy extensibility. As with
785 C<DefaultEnd>, it allows you to add "dump_info=1" (precede with "?" or
786 "&" depending on where it is in the URL) to I<force> the debug screen at
787 the end of the Catalyst request processing cycle.
791 To enable C<RenderView>, edit C<lib/MyApp/Controller/Root.pm> and insert
792 the following method:
796 Forward to a default view.
800 sub end :ActionClass('RenderView') {
802 $c->forward('MyApp::View::TT') unless $c->res->body;
806 =head2 Globally Customize Every View
808 When using TTSite, files in the subdirectories of C<root/lib> can be
809 used to make changes that will appear in every view. For example, to
810 display optional status and error messages in every view, edit
811 C<root/lib/site/layout>, updating it to match the following (the two HTML
812 C<span> elements are new):
814 <div id="header">[% PROCESS site/header %]</div>
817 <span class="message">[% status_msg %]</span>
818 <span class="error">[% error_msg %]</span>
822 <div id="footer">[% PROCESS site/footer %]</div>
824 If we set either message in the Catalyst stash (e.g.,
825 C<$c-E<gt>stash-E<gt>{status_msg} = 'Request was successful!'>) it will
826 be displayed whenever any view used by that request is rendered. The
827 C<message> and C<error> CSS styles are automatically defined in
828 C<root/src/ttsite.css> and can be customized to suit your needs.
830 B<Note:> The Catalyst stash only lasts for a single HTTP request. If
831 you need to retain information across requests you can use
832 L<Catalyst::Plugin::Session|Catalyst::Plugin::Session> (we will use
833 Catalyst sessions in the Authentication part of the tutorial).
836 =head2 Create a TT Template Page
838 To add a new page of content to the TTSite view hierarchy, just create a
839 new C<.tt2> file in C<root/src>. Only include HTML markup that goes
840 inside the HTML <body> and </body> tags, TTSite will use the contents of
841 C<root/lib/site> to add the top and bottom.
843 First create a directory for book-related TT templates:
845 $ mkdir root/src/books
847 Then open C<root/src/books/list.tt2> in your editor and enter:
849 [% # This is a TT comment. The '-' at the end "chomps" the newline. You won't -%]
850 [% # see this "chomping" in your browser because HTML ignores blank lines, but -%]
851 [% # it WILL eliminate a blank line if you view the HTML source. It's purely -%]
852 [%- # optional, but both the beginning and the ending TT tags support chomping. -%]
854 [% # Provide a title to root/lib/site/header -%]
855 [% META title = 'Book List' -%]
858 <tr><th>Title</th><th>Rating</th><th>Author(s)</th></tr>
859 [% # Display each book in a table row %]
860 [% FOREACH book IN books -%]
862 <td>[% book.title %]</td>
863 <td>[% book.rating %]</td>
865 [% # First initialize a TT variable to hold a list. Then use a TT FOREACH -%]
866 [% # loop in 'side effect notation' to load just the last names of the -%]
867 [% # authors into the list. Note that we make a bogus assignment to the -%]
868 [% # 'unused' vbl to avoid printing the size of the list after each push. -%]
870 unused = tt_authors.push(author.last_name) FOREACH author = book.authors %]
871 [% # Now use a TT 'virtual method' to display the author count in parens -%]
872 ([% tt_authors.size %])
873 [% # Use another vmethod to join & print the names with comma separators -%]
874 [% tt_authors.join(', ') %]
880 As indicated by the inline comments above, the C<META title> line uses
881 TT's META feature to provide a title to C<root/lib/site/header>.
882 Meanwhile, the outer C<FOREACH> loop iterates through each C<book> model
883 object and prints the C<title> and C<rating> fields. An inner
884 C<FOREACH> loop prints the last name of each author in a comma-separated
885 list within a single table cell.
887 If you are new to TT, the C<[%> and C<%]> tags are used to delimit TT
888 code. TT supports a wide variety of directives for "calling" other
889 files, looping, conditional logic, etc. In general, TT simplifies the
890 usual range of Perl operators down to the single dot (C<.>) operator.
891 This applies to operations as diverse as method calls, hash lookups, and
892 list index values (see
893 L<http://www.template-toolkit.org/docs/default/Manual/Variables.html>
894 for details and examples). In addition to the usual C<Template> module
895 Pod documentation, you can access the TT manual at
896 L<http://www.template-toolkit.org/docs/default/>.
898 B<NOTE>: The C<TTSite> helper creates several TT files using an
899 extension of C<.tt2>. Most other Catalyst and TT examples use an
900 extension of C<.tt>. You can use either extension (or no extension at
901 all) with TTSite and TT, just be sure to use the appropriate extension
902 for both the file itself I<and> the C<$c-E<gt>stash-E<gt>{template} =
903 ...> line in your controller. This document will use C<.tt2> for
904 consistency with the files already created by the C<TTSite> helper.
907 =head1 RUN THE APPLICATION
909 First, let's enable an environment variable option that causes
910 DBIx::Class to dump the SQL statements it's using to access the database
911 (this option can provide extremely helpful troubleshooting information):
913 $ export DBIX_CLASS_STORAGE_DBI_DEBUG=1
915 This assumes you are using BASH as your shell -- adjust accordingly if
916 you are using a different shell (for example, under tcsh, use
917 C<setenv DBIX_CLASS_STORAGE_DBI_DEBUG 1>).
919 B<NOTE>: You can also set this in your code using
920 C<$class-E<gt>storage-E<gt>debug(1);>. See
921 L<DBIx::Class::Manual::Troubleshooting> for details (including options
922 to log to file instead of displaying to the Catalyst development server
925 Then run the Catalyst "demo server" script:
927 $ script/myapp_server.pl
929 You should get something like this:
931 $ script/myapp_server.pl
932 [Tue May 16 12:51:33 2006] [catalyst] [debug] Debug messages enabled
933 [Tue May 16 12:51:33 2006] [catalyst] [debug] Loaded plugins:
934 .------------------------------------------------------------------------------.
935 | Catalyst::Plugin::ConfigLoader 0.09 |
936 | Catalyst::Plugin::Static::Simple 0.14 |
937 | Catalyst::Plugin::StackTrace 0.04 |
938 | Catalyst::Plugin::DefaultEnd 0.06 |
939 '------------------------------------------------------------------------------'
941 [Tue May 16 12:51:33 2006] [catalyst] [debug] Loaded dispatcher "Catalyst::Dispatcher"
942 [Tue May 16 12:51:33 2006] [catalyst] [debug] Loaded engine "Catalyst::Engine::HTTP"
943 [Tue May 16 12:51:33 2006] [catalyst] [debug] Found home "/home/me/MyApp"
944 [Tue May 16 12:51:37 2006] [catalyst] [debug] Loaded components:
945 .-------------------------------------------------------------------+----------.
947 +-------------------------------------------------------------------+----------+
948 | MyApp::Controller::Books | instance |
949 | MyApp::Controller::Root | instance |
950 | MyApp::Model::MyAppDB | instance |
951 | MyApp::Model::MyAppDB::Author | class |
952 | MyApp::Model::MyAppDB::Book | class |
953 | MyApp::Model::MyAppDB::BookAuthor | class |
954 | MyApp::View::TT | instance |
955 '-------------------------------------------------------------------+----------'
957 [Tue May 16 12:51:37 2006] [catalyst] [debug] Loaded Private actions:
958 .----------------------+----------------------------------------+--------------.
959 | Private | Class | Method |
960 +----------------------+----------------------------------------+--------------+
961 | /default | MyApp::Controller::Root | default |
962 | /end | MyApp | end |
963 | /books/list | MyApp::Controller::Books | list |
964 '----------------------+----------------------------------------+--------------'
966 [Tue May 16 12:51:37 2006] [catalyst] [debug] Loaded Path actions:
967 .--------------------------------------+---------------------------------------.
969 +--------------------------------------+---------------------------------------+
970 | /books/list | /books/list |
971 '--------------------------------------+---------------------------------------'
973 [Tue May 16 12:51:37 2006] [catalyst] [info] MyApp powered by Catalyst 5.6902
974 You can connect to your server at http://localhost:3000
976 Some things you should note in the output above:
982 Catalyst::Model::DBIC::Schema took our C<MyAppDB::Book> and made it
983 C<MyApp::Model::MyAppDB::Book> (and similar actions were performed on
984 C<MyAppDB::Author> and C<MyAppDB::BookAuthor>).
988 The "list" action in our Books controller showed up with a path of
993 Point your browser to L<http://localhost:3000> and you should still get
994 the Catalyst welcome page.
996 Next, to view the book list, change the URL in your browser to
997 L<http://localhost:3000/books/list>. You should get a list of the five
998 books loaded by the C<myapp01.sql> script above, with TTSite providing
999 the formatting for the very simple output we generated in our template.
1000 The count and space-separated list of author last names appear on the
1003 Also notice in the output of the C<script/myapp_server.pl> that DBIC
1004 used the following SQL to retrieve the data:
1006 SELECT me.id, me.title, me.rating FROM books me
1008 Along with a list of the following commands to retrieve the authors for
1009 each book (the lines have been "word wrapped" here to improve
1012 SELECT author.id, author.first_name, author.last_name
1013 FROM book_authors me
1014 JOIN authors author ON ( author.id = me.author_id )
1015 WHERE ( me.book_id = ? ): `1'
1017 You should see 10 such lines of debug output, two for each of the five
1018 author_id values (it pulls the data once for the count logic and another
1019 time to actually display the list).
1024 Kennedy Clark, C<hkclark@gmail.com>
1026 Please report any errors, issues or suggestions to the author. The
1027 most recent version of the Catlayst Tutorial can be found at
1028 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/>.
1030 Copyright 2006, Kennedy Clark, under Creative Commons License
1031 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).