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>
55 In this part of the tutorial, we will create a very basic Catalyst web
56 application. Though simple in many respects, this section will already
57 demonstrate a number of powerful capabilities such as:
61 =item * Helper Scripts
63 Catalyst helper scripts that can be used to rapidly bootstrap the
64 skeletal structure of an application.
68 Model/View/Controller (MVC) provides an architecture that facilitates a
69 clean "separation of control" between the different portions of your
70 application. Given that many other documents cover this subject in
71 detail, MVC will not be discussed in depth here (for an excellent
72 introduction to MVC and general Catalyst concepts, please see
73 L<Catalyst::Manual::About>. In short:
79 The model usually represents a data store. In most applications, the
80 model equates to the objects that are created from and saved to your SQL
85 The view takes model objects and renders them into something for the end
86 user to look at. Normally this involves a template-generation tool that
87 creates HTML for the user's web browser, but it could easily be code
88 that generates other forms such as PDF documents, e-mails, or Excel
93 As suggested by its name, the controller takes user requests and routes
94 them to the necessary model and view.
100 The use of Object-Relational Mapping (ORM) technology for database
101 access. Specifically, ORM provides an automated and standardized means
102 to persist and restore objects to/from a relational database.
106 B<TIP>: Note that all of the code for this part of the tutorial can be
107 pulled from the Catalyst Subversion repository in one step with the
110 svn checkout http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial@###
111 IMPORTANT: Does not work yet. Will be completed for final version.
114 =head1 CREATE A CATALYST PROJECT
116 Catalyst provides a number of helper scripts that can be used to quickly
117 flesh out the basic structure of your application. All Catalyst projects
118 begin with the C<catalyst.pl> helper.
120 In the case of this tutorial, use the Catalyst C<catalyst.pl> script to
121 initialize the framework for an application called C<MyApp>:
125 created "MyApp/script"
129 created "MyApp/script/myapp_create.pl"
132 The C<catalyst.pl> helper script will display the names of the
133 directories and files it creates.
135 Though it's too early for any significant celebration, we already have a
136 functioning application. Run the following command to run this
137 application with the built-in development web server:
139 $ script/myapp_server.pl
140 [debug] Debug messages enabled
141 [debug] Loaded plugins:
142 .----------------------------------------------------------------------------.
143 | Catalyst::Plugin::ConfigLoader 0.06 |
144 | Catalyst::Plugin::Static::Simple 0.14 |
145 '----------------------------------------------------------------------------'
147 [debug] Loaded dispatcher "Catalyst::Dispatcher"
148 [debug] Loaded engine "Catalyst::Engine::HTTP"
149 [debug] Found home "/root/dev/MyApp"
150 [debug] Loaded components:
151 .-----------------------------------------------------------------+----------.
153 +-----------------------------------------------------------------+----------+
154 | MyApp::Controller::Root | instance |
155 '-----------------------------------------------------------------+----------'
157 [debug] Loaded Private actions:
158 .----------------------+--------------------------------------+--------------.
159 | Private | Class | Method |
160 +----------------------+--------------------------------------+--------------+
161 | /default | MyApp::Controller::Root | default |
162 | /end | MyApp::Controller::Root | end |
163 '----------------------+--------------------------------------+--------------'
165 [info] MyApp powered by Catalyst 5.70_03
166 You can connect to your server at http://localhost.localdomain:3000
168 Point your web browser to L<http://localhost:3000> (substituting a
169 different hostname or IP address as appropriate) and you should be
170 greeted by the Catalyst welcome screen. Information similar to the
171 following should be appended to the logging output of the development
174 [info] *** Request 1 (0.008/s) [2822] [Mon Jul 3 12:42:43 2006] ***
175 [debug] "GET" request for "/" from "127.0.0.1"
176 [info] Request took 0.154781s (6.461/s)
177 .----------------------------------------------------------------+-----------.
179 +----------------------------------------------------------------+-----------+
180 | /default | 0.000006s |
182 '----------------------------------------------------------------+-----------'
184 Press Ctrl-C to break out of the development server.
187 =head1 CREATE A SQLITE DATABASE
189 In this step, we make a text file with the required SQL commands to
190 create a database table and load some sample data. Open C<myapp01.sql>
191 in your editor and enter:
194 -- Create a very simple database to hold book and author information
197 id INTEGER PRIMARY KEY,
201 -- 'book_authors' is a many-to-many join table between books & authors
202 CREATE TABLE book_authors (
205 PRIMARY KEY (book_id, author_id)
207 CREATE TABLE authors (
208 id INTEGER PRIMARY KEY,
213 --- Load some sample data
215 INSERT INTO books VALUES (1, 'CCSP SNRS Exam Certification Guide', 5);
216 INSERT INTO books VALUES (2, 'TCP/IP Illustrated, Volume 1', 5);
217 INSERT INTO books VALUES (3, 'Internetworking with TCP/IP Vol.1', 4);
218 INSERT INTO books VALUES (4, 'Perl Cookbook', 5);
219 INSERT INTO books VALUES (5, 'Designing with Web Standards', 5);
220 INSERT INTO authors VALUES (1, 'Greg', 'Bastien');
221 INSERT INTO authors VALUES (2, 'Sara', 'Nasseh');
222 INSERT INTO authors VALUES (3, 'Christian', 'Degu');
223 INSERT INTO authors VALUES (4, 'Richard', 'Stevens');
224 INSERT INTO authors VALUES (5, 'Douglas', 'Comer');
225 INSERT INTO authors VALUES (6, 'Tom', 'Christiansen');
226 INSERT INTO authors VALUES (7, ' Nathan', 'Torkington');
227 INSERT INTO authors VALUES (8, 'Jeffrey', 'Zeldman');
228 INSERT INTO book_authors VALUES (1, 1);
229 INSERT INTO book_authors VALUES (1, 2);
230 INSERT INTO book_authors VALUES (1, 3);
231 INSERT INTO book_authors VALUES (2, 4);
232 INSERT INTO book_authors VALUES (3, 5);
233 INSERT INTO book_authors VALUES (4, 6);
234 INSERT INTO book_authors VALUES (4, 7);
235 INSERT INTO book_authors VALUES (5, 8);
237 B<TIP>: See Appendix 1 for tips on removing the leading spaces when
238 cutting and pasting example code from POD-based documents.
240 Then use the following command to build a C<myapp.db> SQLite database:
242 $ sqlite3 myapp.db < myapp01.sql
244 If you need to create the database more than once, you probably want to
245 issue the C<rm myapp.db> command to delete the database before you use
246 the C<sqlite3 myapp.db < myapp01.sql> command.
248 Once the C<myapp.db> database file has been created and initialized, you
249 can use the SQLite command line environment to do a quick dump of the
254 Enter ".help" for instructions
255 sqlite> select * from books;
256 1|CCSP SNRS Exam Certification Guide|5
257 2|TCP/IP Illustrated, Volume 1|5
258 3|Internetworking with TCP/IP Vol.1|4
260 5|Designing with Web Standards|5
266 $ sqlite3 myapp.db "select * from books"
267 1|CCSP SNRS Exam Certification Guide|5
268 2|TCP/IP Illustrated, Volume 1|5
269 3|Internetworking with TCP/IP Vol.1|4
271 5|Designing with Web Standards|5
273 As with most other SQL tools, if you are using the full "interactive"
274 environment you need to terminate your SQL commands with a ";" (it's not
275 required if you do a single SQL statement on the command line). Use
276 ".q" to exit from SQLite from the SQLite interactive mode and return to
277 your OS command prompt.
280 =head1 EDIT THE LIST OF CATALYST PLUGINS
282 One of the greatest benefits of Catalyst is that it has such a large
283 library of plugins available. Plugins are used to seamlessly integrate
284 existing Perl modules into the overall Catalyst framework. In general,
285 they do this by adding additional methods to the C<context> object
286 (generally written as C<$c>) that Catalyst passes to every component
287 throughout the framework.
289 By default, Catalyst enables three plugins/flags:
297 Enables the Catalyst debug output you saw when we started the
298 C<script/myapp_server.pl> development server earlier. You can remove
299 this plugin when you place your application into production.
301 As you may have noticed, C<-Debug> is not a plugin, but a I<flag>.
302 Although most of the items specified on the C<use Catalyst> line of your
303 application class will be plugins, Catalyst supports a limited number of
304 flag options (of these, C<-Debug> is the most common). See the
305 documentation for C<Catalyst.pm> to get details on other flags
306 (currently C<-Engine>, C<-Home>, and C<-Log>).
308 If you prefer, you can use the C<$c-E<gt>debug> method to enable debug
313 L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
315 C<ConfigLoader> provides an automatic way to load configurable
316 parameters for your application from a central YAML file (versus having
317 the values hard-coded inside your Perl modules). If you have not been
318 exposed to YAML before, it is a human-readable data serialization format
319 that can be used to read (and write) values to/from text files. We will
320 see how to use this feature of Catalyst during the authentication and
321 authorization sections (Part 4 and Part 5).
325 L<Catalyst::Plugin::Static::Simple|Catalyst::Plugin::Static::Simple>
327 C<Static::Simple> provides an easy method of serving static content such
328 as images and CSS files under the development server.
332 To modify the list of plugins, edit C<lib/MyApp.pm> (this file is
333 generally referred to as your I<application class>) and delete the line
336 use Catalyst qw/-Debug ConfigLoader Static::Simple/;
348 This tells Catalyst to start using one new plugin:
354 L<Catalyst::Plugin::StackTrace|Catalyst::Plugin::StackTrace>
356 Adds a stack trace to the standard Catalyst "debug screen" (this is the
357 screen Catalyst sends to your browser when an error occurs).
359 Note: L<StackTrace|Catalyst::Plugin::StackTrace> output appears in your
360 browser, not in the console window from which you're running your
361 application, which is where logging output usually goes.
365 Note that when specifying plugins on the C<use Catalyst> line, you can
366 omit C<Catalyst::Plugin::> from the name. Additionally, you can spread
367 the plugin names across multiple lines as shown here, or place them all
368 on one (or more) lines as with the default configuration.
370 B<TIP:> You may see examples that include the
371 L<Catalyst::Plugin::DefaultEnd|Catalyst::Plugin::DefaultEnd>
372 plugins. As of Catalyst 5.7000, C<DefaultEnd> has been
373 deprecated in favor of
374 L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>
375 (as the name of the package suggests, C<RenderView> is not
376 a plugin, but an action). The purpose of both is essentially the same:
377 forward processing to the view to be rendered. Applications generated
378 under 5.7000 should automatically use C<RenderView> and "just work"
379 for most applications. For more information on C<RenderView> and
380 the various options for forwarding to your view logic, please refer
381 to the "Using RenderView for the Default View" section under
382 "CATALYST VIEWS" below.
385 =head1 DATABASE ACCESS WITH C<DBIx::Class>
387 Catalyst can be used with virtually any form of persistent datastore
388 available via Perl. For example,
389 L<Catalyst::Model::DBI|Catalyst::Model::DBI> can be used to
390 easily access databases through the traditional Perl C<DBI> interface.
391 However, most Catalyst applications use some form of ORM technology to
392 automatically create and save model objects as they are used. Although
393 Tony Bowden's L<Class::DBI|Class::DBI> has been the traditional
394 Perl ORM engine, Matt Trout's L<DBIx::Class|DBIx::Class> (abbreviated
395 as "DBIC") has rapidly emerged as the Perl-based ORM technology of choice.
396 Most new Catalyst applications rely on DBIC, as will this tutorial.
398 Note: See L<Catalyst:: Model::CDBI> for more information on using
399 Catalyst with L<Class::DBI|Class::DBI>.
401 =head2 Create a DBIC Schema File
403 DBIx::Class uses a schema file to load other classes that represent the
404 tables in your database (DBIC refers to these "table objects" as "result
405 sources"; see L<DBIx::Class::ResultSource>). In this case, we want to
406 load the model object for the C<books>, C<book_authors>, and C<authors>
407 tables created in the previous step.
409 Open C<lib/MyAppDB.pm> in your editor and insert:
415 MyAppDB - DBIC Schema Class
419 # Our schema needs to inherit from 'DBIx::Class::Schema'
420 use base qw/DBIx::Class::Schema/;
422 # Need to load the DB Model classes here.
423 # You can use this syntax if you want:
424 # __PACKAGE__->load_classes(qw/Book BookAuthor Author/);
425 # Also, if you simply want to load all of the classes in a directory
426 # of the same name as your schema class (as we do here) you can use:
427 # __PACKAGE__->load_classes(qw//);
428 # But the variation below is more flexible in that it can be used to
429 # load from multiple namespaces.
430 __PACKAGE__->load_classes({
431 MyAppDB => [qw/Book BookAuthor Author/]
436 B<Note:> C<__PACKAGE__> is just a shorthand way of referencing the name
437 of the package where it is used. Therefore, in C<MyAppDB.pm>,
438 C<__PACKAGE__> is equivalent to C<MyAppDB>.
441 =head2 Create the DBIC "Result Source" Files
443 In this step, we create "table classes" (again, these are called a
444 "result source" classes in DBIC) that act as model objects for the
445 C<books>, C<book_authors>, and C<authors> tables in our database.
447 First, create a directory to hold the class:
451 Then open C<lib/MyAppDB/Book.pm> in your editor and enter:
453 package MyAppDB::Book;
455 use base qw/DBIx::Class/;
457 # Load required DBIC stuff
458 __PACKAGE__->load_components(qw/PK::Auto Core/);
460 __PACKAGE__->table('books');
461 # Set columns in table
462 __PACKAGE__->add_columns(qw/id title rating/);
463 # Set the primary key for the table
464 __PACKAGE__->set_primary_key(qw/id/);
472 # 1) Name of relationship, DBIC will create accessor with this name
473 # 2) Name of the model class referenced by this relationship
474 # 3) Column name in *foreign* table
475 __PACKAGE__->has_many(book_authors => 'MyAppDB::BookAuthor', 'book_id');
479 # 1) Name of relationship, DBIC will create accessor with this name
480 # 2) Name of has_many() relationship this many_to_many() is shortcut for
481 # 3) Name of belongs_to() relationship in model class of has_many() above
482 # You must already have the has_many() defined to use a many_to_many().
483 __PACKAGE__->many_to_many(authors => 'book_authors', 'author');
488 MyAppDB::Book - A model object representing a book.
492 This is an object that represents a row in the 'books' table of your application
493 database. It uses DBIx::Class (aka, DBIC) to do ORM.
495 For Catalyst, this is designed to be used through MyApp::Model::MyAppDB.
496 Offline utilities may wish to use this class directly.
502 This defines both a C<has_many> and a C<many_to_many> relationship. The
503 C<many_to_many> relationship is optional, but it makes it easier to map
504 a book to its collection of authors. Without it, we would have to
505 "walk" though the C<book_authors> table as in
506 C<$book-E<gt>book_authors-E<gt>first-E<gt>author-E<gt>last_name> (we
507 will see examples on how to use DBIC objects in your code soon, but note
508 that because C<$book-E<gt>book_authors> can return multiple authors, we
509 have to use C<first> to display a single author). C<many_to_many> allows
510 us to use the shorter C<$book-E<gt>authors-E<gt>first-E<gt>last_name>.
511 Note that you cannot define a C<many_to_many> relationship without also
512 having the C<has_many> relationship in place.
514 Next, open C<lib/MyAppDB/Author.pm> in your editor and enter:
516 package MyAppDB::Author;
518 use base qw/DBIx::Class/;
520 # Load required DBIC stuff
521 __PACKAGE__->load_components(qw/PK::Auto Core/);
523 __PACKAGE__->table('authors');
524 # Set columns in table
525 __PACKAGE__->add_columns(qw/id first_name last_name/);
526 # Set the primary key for the table
527 __PACKAGE__->set_primary_key(qw/id/);
535 # 1) Name of relationship, DBIC will create accessor with this name
536 # 2) Name of the model class referenced by this relationship
537 # 3) Column name in *foreign* table
538 __PACKAGE__->has_many(book_author => 'MyAppDB::BookAuthor', 'author_id');
542 # 1) Name of relationship, DBIC will create accessor with this name
543 # 2) Name of has_many() relationship this many_to_many() is shortcut for
544 # 3) Name of belongs_to() relationship in model class of has_many() above
545 # You must already have the has_many() defined to use a many_to_many().
546 __PACKAGE__->many_to_many(books => 'book_author', 'book');
551 MyAppDB::Author - A model object representing an author of a book (if a book has
552 multiple authors, each will be represented be separate Author object).
556 This is an object that represents a row in the 'authors' table of your application
557 database. It uses DBIx::Class (aka, DBIC) to do ORM.
559 For Catalyst, this is designed to be used through MyApp::Model::MyAppDB.
560 Offline utilities may wish to use this class directly.
566 Finally, open C<lib/MyAppDB/BookAuthor.pm> in your editor and enter:
568 package MyAppDB::BookAuthor;
570 use base qw/DBIx::Class/;
572 # Load required DBIC stuff
573 __PACKAGE__->load_components(qw/PK::Auto Core/);
575 __PACKAGE__->table('book_authors');
576 # Set columns in table
577 __PACKAGE__->add_columns(qw/book_id author_id/);
578 # Set the primary key for the table
579 __PACKAGE__->set_primary_key(qw/book_id author_id/);
587 # 1) Name of relationship, DBIC will create accessor with this name
588 # 2) Name of the model class referenced by this relationship
589 # 3) Column name in *this* table
590 __PACKAGE__->belongs_to(book => 'MyAppDB::Book', 'book_id');
594 # 1) Name of relationship, DBIC will create accessor with this name
595 # 2) Name of the model class referenced by this relationship
596 # 3) Column name in *this* table
597 __PACKAGE__->belongs_to(author => 'MyAppDB::Author', 'author_id');
602 MyAppDB::BookAuthor - A model object representing the JOIN between an author and
607 This is an object that represents a row in the 'book_authors' table of your
608 application database. It uses DBIx::Class (aka, DBIC) to do ORM.
610 You probably won't need to use this class directly -- it will be automatically
611 used by DBIC where joins are needed.
613 For Catalyst, this is designed to be used through MyApp::Model::MyAppDB.
614 Offline utilities may wish to use this class directly.
620 B<Note:> This sample application uses a plural form for the database
621 tables (e.g., C<books> and C<authors>) and a singular form for the model
622 objects (e.g., C<Book> and C<Author>); however, Catalyst places no
623 restrictions on the naming conventions you wish to use.
625 =head2 Use C<Catalyst::Model::DBIC::Schema> To Load The Model Class
627 When L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> is
628 in use, Catalyst essentially reads an existing copy of your database
629 model and creates a new set of objects under C<MyApp::Model> for use
633 L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> you
634 essentially end up with two sets of model classes (only one of which
635 you write... the other set is created automatically in memory when
636 your Catalyst application initializes). For this tutorial application,
637 the important points to remember are: you write the I<result source>
638 files in C<MyAppDB>, but I<within Catalyst> you use the I<automatically
639 created model classes> in C<MyApp::Model>.
642 L<Catalyst::Helper::Model::DBIC::Schema|Catalyst::Helper::Model::DBIC::Schema>
643 helper script to create the model class that loads up the model we
644 created in the previous step:
646 $ script/myapp_create.pl model MyAppDB DBIC::Schema MyAppDB dbi:SQLite:myapp.db '' '' '{ AutoCommit => 1 }'
647 exists "/root/dev/MyApp/script/../lib/MyApp/Model"
648 exists "/root/dev/MyApp/script/../t"
649 created "/root/dev/MyApp/script/../lib/MyApp/Model/MyAppDB.pm"
650 created "/root/dev/MyApp/script/../t/model_MyAppDB.t"
653 Where the first C<MyAppDB> is the name of the class to be created by the
654 helper in C<lib/MyApp/Model> and the second C<MyAppDB> is the name of
655 existing schema file we created (in C<lib/MyAppDB.pm>). You can see
656 that the helper creates a model file under C<lib/MyApp/Model> (Catalyst
657 has a separate directory under C<lib/MyApp> for each of the three parts
658 of MVC: C<Model>, C<View>, and C<Controller> [although older Catalyst
659 applications often use the directories C<M>, C<V>, and C<C>]).
662 =head1 CREATE A CATALYST CONTROLLER
664 Controllers are where you write methods that interact with user
665 input--typically, controller methods respond to C<GET> and C<POST>
666 messages from the user's web browser.
668 Use the Catalyst C<create> script to add a controller for book-related
671 $ script/myapp_create.pl controller Books
672 exists "/root/dev/MyApp/script/../lib/MyApp/Controller"
673 exists "/root/dev/MyApp/script/../t"
674 created "/root/dev/MyApp/script/../lib/MyApp/Controller/Books.pm"
675 created "/root/dev/MyApp/script/../t/controller_Books.t"
677 Then edit C<lib/MyApp/Controller/Books.pm> and add the following method
682 Fetch all book objects and pass to books/list.tt2 in stash to be displayed
687 # Retrieve the usual perl OO '$self' for this object. $c is the Catalyst
688 # 'Context' that's used to 'glue together' the various components
689 # that make up the application
692 # Retrieve all of the book records as book model objects and store in the
693 # stash where they can be accessed by the TT template
694 $c->stash->{books} = [$c->model('MyAppDB::Book')->all];
696 # Set the TT template to use. You will almost always want to do this
697 # in your action methods.
698 $c->stash->{template} = 'books/list.tt2';
701 B<Note:> Programmers experienced with object-oriented Perl should
702 recognize C<$self> as a reference to the object where this method was
703 called. On the other hand, C<$c> will be new to many Perl programmers
704 who have not used Catalyst before (it's sometimes written as
705 C<$context>). The Context object is automatically passed to all
706 Catalyst components. It is used to pass information between components
707 and provide access to Catalyst and plugin functionality.
709 B<TIP>: You may see the C<$c-E<gt>model('MyAppDB::Book')> used above
710 written as C<$c-E<gt>model('MyAppDB')-E<gt>resultset('Book)>. The two
713 B<Note:> Catalyst actions are regular Perl methods, but they make use of
714 Nicholas Clark's C<attributes> module (that's the C<: Local> next to the
715 C<sub list> in the code above) to provide additional information to the
716 Catalyst dispatcher logic.
719 =head1 CATALYST VIEWS
721 Views are where you render output, typically for display in the user's
722 web browser, but also possibly using other display output-generation
723 systems. As with virtually every aspect of Catalyst, options abound
724 when it comes to the specific view technology you adopt inside your
725 application. However, most Catalyst applications use the Template
726 Toolkit, known as TT (for more information on TT, see
727 L<http://www.template-toolkit.org>). Other popular view technologies
728 include Mason (L<http://www.masonhq.com> and
729 L<http://www.masonbook.com>) and L<HTML::Template|HTML::Template>
730 (L<http://html-template.sourceforge.net>).
732 =head2 Create a Catalyst View Using C<TTSITE>
734 When using TT for the Catalyst view, there are two main helper scripts:
740 L<Catalyst::Helper::View::TT|Catalyst::Helper::View::TT>
744 L<Catalyst::Helper::View::TTSite|Catalyst::Helper::View::TTSite>
748 Both are similar, but C<TT> merely creates the C<lib/MyApp/View/TT.pm>
749 file and leaves the creation of any hierarchical template organization
750 entirely up to you. (It also creates a C<t/view_TT.t> file for testing;
751 test cases will be discussed in Part 7). The C<TTSite> helper creates a
752 modular and hierarchical view layout with separate Template Toolkit (TT)
753 files for common header and footer information, configuration values, a
754 CSS stylesheet, and more.
756 Enter the following command to enable the C<TTSite> style of view
757 rendering for this tutorial:
759 $ script/myapp_create.pl view TT TTSite
760 exists "/root/dev/MyApp/script/../lib/MyApp/View"
761 exists "/root/dev/MyApp/script/../t"
762 created "/root/dev/MyApp/script/../lib/MyApp/View/TT.pm"
763 created "/root/dev/MyApp/script/../root/lib"
765 created "/root/dev/MyApp/script/../root/src/ttsite.css"
767 This puts a number of files in the C<root/lib> and C<root/src>
768 directories that can be used to customize the look and feel of your
769 application. Also take a look at C<lib/MyApp/View/TT.pm> for config
770 values set by the C<TTSite> helper.
772 B<TIP>: Note that TTSite does one thing that could confuse people who
773 are used to the normal C<TT> Catalyst view: it redefines the Catalyst
774 context object in templates from its usual C<c> to C<Catalyst>. When
775 looking at other Catalyst examples, remember that they almost always use
776 C<c>. Note that Catalyst and TT I<do not complain> when you use the
777 wrong name to access the context object...TT simply outputs blanks for
778 that bogus logic (see next tip to change this behavior with TT C<DEBUG>
779 options). Finally, be aware that this change in name I<only>
780 applies to how the context object is accessed inside your TT templates;
781 your controllers will continue to use C<$c> (or whatever name you use
782 when fetching the reference from C<@_> inside your methods). (You can
783 change back to the "default" behavior be removing the C<CATALYST_VAR>
784 line from C<lib/MyApp/View/TT.pm>, but you will also have to edit
785 C<root/lib/config/main> and C<root/lib/config/url>. If you do this, be
786 careful not to have a collision between your own C<c> variable and the
787 Catalyst C<c> variable.)
789 B<TIP>: When troubleshooting TT it can be helpful to enable variable
790 C<DEBUG> options. You can do this in a Catalyst environment by adding
791 a C<DEBUG> line to the C<__PACKAGE__->config> declaration in
794 __PACKAGE__->config({
795 CATALYST_VAR => 'Catalyst',
801 There are a variety of options you can use, such as 'undef', 'all',
802 'service', 'context', 'parser', 'provider', and 'service'. See
803 L<Template::Constants> for more information (remove the C<DEBUG_>
804 portion of the name shown in the TT docs and convert to lower case
805 for use inside Catalyst).
808 =head2 Using C<RenderView> for the Default View
810 Once your controller logic has processed the request from a user, it
811 forwards processing to your view in order to generate the appropriate
812 response output. Catalyst v5.7000 ships with a new mechanism,
813 L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>, that
814 automatically performs this operation. If you look in
815 C<lib/MyApp/Controller/Root.pm>, you should see the this empty
816 definition for the C<sub end> method:
818 sub end : ActionClass('RenderView') {}
820 The following bullet points provide a quick overview of the
821 C<RenderView> process:
827 C<Root.pm> is designed to hold application-wide logic.
831 At the end of a given user request, Catalyst will call the most specific
832 C<end> method that's appropriate. For example, if the controller for a
833 request has an C<end> method defined, it will be called. However, if
834 the controller does not define a controller-specific C<end> method, the
835 "global" C<end> method in C<Root.pm> will be called.
839 Because the definition includes an C<ActionClass> attribute, the
840 L<Catalyst::Action::RenderView|Catalyst::Action::RenderView> logic
841 will be called before any code inside the definition of C<sub end>
842 is run. See L<Catalyst::Manual::Actions|Catalyst::Manual::Actions>
843 for more information on C<ActionClass>.
847 Because C<sub end> is empty, this effectively just runs the default
848 logic in C<RenderView>. However, you can easily extend the
849 C<RenderView> logic by adding your own code inside the empty method body
850 (C<{}>) created by the Catalyst Helpers when we first ran the
851 C<catalyst.pl> to initialize our application. See
852 L<Catalyst::Action::RenderView|Catalyst::Action::RenderView> for more
853 detailed information on how to extended C<RenderView> in C<sub end>.
858 =head3 The History Leading Up To C<RenderView>
860 Although C<RenderView> strikes a nice balance between default
861 behavior and easy extensibility, it is a new feature that won't
862 appear in most existing Catalyst examples. This section provides
863 some brief background on the evolution of default view rendering
864 logic with an eye to how they can be migrated to C<RenderView>:
870 Private C<end> Action in Application Class
872 Older Catalyst-related documents often suggest that you add a "private
873 end action" to your application class (C<MyApp.pm>) or Root.pm
874 (C<MyApp/Controller/Root.pm>). These examples should be easily
875 converted to L<RenderView|Catalyst::Action::RenderView> by simply adding
876 C<ActionClass('RenderView')> to the C<sub end> definition. If end sub is
877 defined in your application class (C<MyApp.pm>), you should also migrate
878 it to C<MyApp/Controller/Root.pm>.
882 L<Catalyst::Plugin::DefaultEnd|Catalyst::Plugin::DefaultEnd>
884 C<DefaultEnd> represented the "next step" in passing processing from
885 your controller to your view. It has the advantage of only requiring
886 that C<DefaultEnd> be added to the list of plugins in C<lib/MyApp.pm>.
887 It also allowed you to add "dump_info=1" (precede with "?" or "&"
888 depending on where it is in the URL) to I<force> the debug screen at the
889 end of the Catalyst request processing cycle. However, it was more
890 difficult to extend the C<RenderView> mechanism, and is now deprecated.
894 L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>
896 As discussed above, the current recommended approach to handling your
898 L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>. Although
899 similar in first appearance to the "private end action" approach, it
900 utilizes Catalyst's "ActionClass" mechanism to provide both automatic
901 default behavior (you don't have to include a plugin as with
902 C<DefaultEnd>) and easy extensibility. As with C<DefaultEnd>, it allows
903 you to add "dump_info=1" (precede with "?" or "&" depending on where it
904 is in the URL) to I<force> the debug screen at the end of the Catalyst
905 request processing cycle.
909 It is recommended that all Catalyst applications use or migrate to
910 the C<RenderView> approach.
913 =head2 Globally Customize Every View
915 When using TTSite, files in the subdirectories of C<root/lib> can be
916 used to make changes that will appear in every view. For example, to
917 display optional status and error messages in every view, edit
918 C<root/lib/site/layout>, updating it to match the following (the two HTML
919 C<span> elements are new):
921 <div id="header">[% PROCESS site/header %]</div>
924 <span class="message">[% status_msg %]</span>
925 <span class="error">[% error_msg %]</span>
929 <div id="footer">[% PROCESS site/footer %]</div>
931 If we set either message in the Catalyst stash (e.g.,
932 C<$c-E<gt>stash-E<gt>{status_msg} = 'Request was successful!'>) it will
933 be displayed whenever any view used by that request is rendered. The
934 C<message> and C<error> CSS styles are automatically defined in
935 C<root/src/ttsite.css> and can be customized to suit your needs.
937 B<Note:> The Catalyst stash only lasts for a single HTTP request. If
938 you need to retain information across requests you can use
939 L<Catalyst::Plugin::Session|Catalyst::Plugin::Session> (we will use
940 Catalyst sessions in the Authentication part of the tutorial).
943 =head2 Create a TT Template Page
945 To add a new page of content to the TTSite view hierarchy, just create a
946 new C<.tt2> file in C<root/src>. Only include HTML markup that goes
947 inside the HTML <body> and </body> tags, TTSite will use the contents of
948 C<root/lib/site> to add the top and bottom.
950 First create a directory for book-related TT templates:
952 $ mkdir root/src/books
954 Then open C<root/src/books/list.tt2> in your editor and enter:
956 [% # This is a TT comment. The '-' at the end "chomps" the newline. You won't -%]
957 [% # see this "chomping" in your browser because HTML ignores blank lines, but -%]
958 [% # it WILL eliminate a blank line if you view the HTML source. It's purely -%]
959 [%- # optional, but both the beginning and the ending TT tags support chomping. -%]
961 [% # Provide a title to root/lib/site/header -%]
962 [% META title = 'Book List' -%]
965 <tr><th>Title</th><th>Rating</th><th>Author(s)</th></tr>
966 [% # Display each book in a table row %]
967 [% FOREACH book IN books -%]
969 <td>[% book.title %]</td>
970 <td>[% book.rating %]</td>
972 [% # First initialize a TT variable to hold a list. Then use a TT FOREACH -%]
973 [% # loop in 'side effect notation' to load just the last names of the -%]
974 [% # authors into the list. Note that we make a bogus assignment to the -%]
975 [% # 'unused' vbl to avoid printing the size of the list after each push. -%]
977 unused = tt_authors.push(author.last_name) FOREACH author = book.authors %]
978 [% # Now use a TT 'virtual method' to display the author count in parens -%]
979 ([% tt_authors.size %])
980 [% # Use another vmethod to join & print the names with comma separators -%]
981 [% tt_authors.join(', ') %]
987 As indicated by the inline comments above, the C<META title> line uses
988 TT's META feature to provide a title to C<root/lib/site/header>.
989 Meanwhile, the outer C<FOREACH> loop iterates through each C<book> model
990 object and prints the C<title> and C<rating> fields. An inner
991 C<FOREACH> loop prints the last name of each author in a comma-separated
992 list within a single table cell.
994 If you are new to TT, the C<[%> and C<%]> tags are used to delimit TT
995 code. TT supports a wide variety of directives for "calling" other
996 files, looping, conditional logic, etc. In general, TT simplifies the
997 usual range of Perl operators down to the single dot (C<.>) operator.
998 This applies to operations as diverse as method calls, hash lookups, and
999 list index values (see
1000 L<http://www.template-toolkit.org/docs/default/Manual/Variables.html>
1001 for details and examples). In addition to the usual C<Template> module
1002 Pod documentation, you can access the TT manual at
1003 L<http://www.template-toolkit.org/docs/default/>.
1005 B<NOTE>: The C<TTSite> helper creates several TT files using an
1006 extension of C<.tt2>. Most other Catalyst and TT examples use an
1007 extension of C<.tt>. You can use either extension (or no extension at
1008 all) with TTSite and TT, just be sure to use the appropriate extension
1009 for both the file itself I<and> the C<$c-E<gt>stash-E<gt>{template} =
1010 ...> line in your controller. This document will use C<.tt2> for
1011 consistency with the files already created by the C<TTSite> helper.
1014 =head1 RUN THE APPLICATION
1016 First, let's enable an environment variable option that causes
1017 DBIx::Class to dump the SQL statements it's using to access the database
1018 (this option can provide extremely helpful troubleshooting information):
1020 $ export DBIX_CLASS_STORAGE_DBI_DEBUG=1
1022 This assumes you are using BASH as your shell -- adjust accordingly if
1023 you are using a different shell (for example, under tcsh, use
1024 C<setenv DBIX_CLASS_STORAGE_DBI_DEBUG 1>).
1026 B<NOTE>: You can also set this in your code using
1027 C<$class-E<gt>storage-E<gt>debug(1);>. See
1028 L<DBIx::Class::Manual::Troubleshooting> for details (including options
1029 to log to file instead of displaying to the Catalyst development server
1032 Then run the Catalyst "demo server" script:
1034 $ script/myapp_server.pl
1036 Your development server log output should display something like:
1038 $ script/myapp_server.pl
1039 [debug] Debug messages enabled
1040 [debug] Loaded plugins:
1041 .----------------------------------------------------------------------------.
1042 | Catalyst::Plugin::ConfigLoader 0.06 |
1043 | Catalyst::Plugin::StackTrace 0.04 |
1044 | Catalyst::Plugin::Static::Simple 0.14 |
1045 '----------------------------------------------------------------------------'
1047 [debug] Loaded dispatcher "Catalyst::Dispatcher"
1048 [debug] Loaded engine "Catalyst::Engine::HTTP"
1049 [debug] Found home "/home/me/MyApp"
1050 [debug] Loaded components:
1051 .-----------------------------------------------------------------+----------.
1053 +-----------------------------------------------------------------+----------+
1054 | MyApp::Controller::Books | instance |
1055 | MyApp::Controller::Root | instance |
1056 | MyApp::Model::MyAppDB | instance |
1057 | MyApp::Model::MyAppDB::Author | class |
1058 | MyApp::Model::MyAppDB::Book | class |
1059 | MyApp::Model::MyAppDB::BookAuthor | class |
1060 | MyApp::View::TT | instance |
1061 '-----------------------------------------------------------------+----------'
1063 [debug] Loaded Private actions:
1064 .----------------------+--------------------------------------+--------------.
1065 | Private | Class | Method |
1066 +----------------------+--------------------------------------+--------------+
1067 | /default | MyApp::Controller::Root | default |
1068 | /end | MyApp::Controller::Root | end |
1069 | /books/index | MyApp::Controller::Books | index |
1070 | /books/list | MyApp::Controller::Books | list |
1071 '----------------------+--------------------------------------+--------------'
1073 [debug] Loaded Path actions:
1074 .-------------------------------------+--------------------------------------.
1076 +-------------------------------------+--------------------------------------+
1077 | /books/list | /books/list |
1078 '-------------------------------------+--------------------------------------'
1080 [info] MyApp powered by Catalyst 5.7000
1081 You can connect to your server at http://localhost.localdomain:3000
1083 Some things you should note in the output above:
1089 Catalyst::Model::DBIC::Schema took our C<MyAppDB::Book> and made it
1090 C<MyApp::Model::MyAppDB::Book> (and similar actions were performed on
1091 C<MyAppDB::Author> and C<MyAppDB::BookAuthor>).
1095 The "list" action in our Books controller showed up with a path of
1100 Point your browser to L<http://localhost:3000> and you should still get
1101 the Catalyst welcome page.
1103 Next, to view the book list, change the URL in your browser to
1104 L<http://localhost:3000/books/list>. You should get a list of the five
1105 books loaded by the C<myapp01.sql> script above, with TTSite providing
1106 the formatting for the very simple output we generated in our template.
1107 The count and space-separated list of author last names appear on the
1110 Also notice in the output of the C<script/myapp_server.pl> that DBIC
1111 used the following SQL to retrieve the data:
1113 SELECT me.id, me.title, me.rating FROM books me
1115 Along with a list of the following commands to retrieve the authors for
1116 each book (the lines have been "word wrapped" here to improve
1119 SELECT author.id, author.first_name, author.last_name
1120 FROM book_authors me
1121 JOIN authors author ON ( author.id = me.author_id )
1122 WHERE ( me.book_id = ? ): `1'
1124 You should see 5 such lines of debug output as DBIC fetches the author
1125 information for each book.
1130 Kennedy Clark, C<hkclark@gmail.com>
1132 Please report any errors, issues or suggestions to the author. The
1133 most recent version of the Catlayst Tutorial can be found at
1134 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/>.
1136 Copyright 2006, Kennedy Clark, under Creative Commons License
1137 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).