Update flow to assume using 0.39+ C::M::DBIC::Schema now that debian pkg available.
[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / Tutorial / 03_MoreCatalystBasics.pod
1 =head1 NAME
2
3 Catalyst::Manual::Tutorial::03_MoreCatalystBasics - Catalyst Tutorial - Chapter 3: More Catalyst Application Development Basics
4
5
6 =head1 OVERVIEW
7
8 This is B<Chapter 3 of 10> for the Catalyst tutorial.
9
10 L<Tutorial Overview|Catalyst::Manual::Tutorial>
11
12 =over 4
13
14 =item 1
15
16 L<Introduction|Catalyst::Manual::Tutorial::01_Intro>
17
18 =item 2
19
20 L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
21
22 =item 3
23
24 B<03_More Catalyst Basics>
25
26 =item 4
27
28 L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>
29
30 =item 5
31
32 L<Authentication|Catalyst::Manual::Tutorial::05_Authentication>
33
34 =item 6
35
36 L<Authorization|Catalyst::Manual::Tutorial::06_Authorization>
37
38 =item 7
39
40 L<Debugging|Catalyst::Manual::Tutorial::07_Debugging>
41
42 =item 8
43
44 L<Testing|Catalyst::Manual::Tutorial::08_Testing>
45
46 =item 9
47
48 L<Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
49
50 =item 10
51
52 L<Appendices|Catalyst::Manual::Tutorial::10_Appendices>
53
54 =back
55
56
57 =head1 DESCRIPTION
58
59 This chapter of the tutorial builds on the work done in Chapter 2 to 
60 explore some features that are more typical of "real world" web 
61 applications. From this chapter of the tutorial onward, we will be 
62 building a simple book database application.  Although the application 
63 will be too limited to be of use to anyone, it should provide a basic 
64 environment where we can explore a variety of features used in 
65 virtually all web applications.
66
67 You can check out the source code for this example from the Catalyst
68 Subversion repository as per the instructions in
69 L<Catalyst::Manual::Tutorial::01_Intro|Catalyst::Manual::Tutorial::01_Intro>.
70
71 Please take a look at 
72 L<Catalyst::Manual::Tutorial::01_Intro/CATALYST INSTALLATION> before 
73 doing the rest of this tutorial.  Although the tutorial should work 
74 correctly under most any recent version of Perl running on any 
75 operating system, the tutorial has been written using Debian 5 and 
76 tested to be sure it runs correctly in this environment.  
77
78
79 =head1 CREATE A NEW APPLICATION
80
81 The remainder of the tutorial will build an application called C<MyApp>.
82 First use the Catalyst C<catalyst.pl> script to initialize the framework
83 for the C<MyApp> application (make sure you aren't still inside the
84 directory of the C<Hello> application from the previous chapter of the
85 tutorial or in a directory that already has a "MyApp" subdirectory):
86
87     $ catalyst.pl MyApp
88     created "MyApp"
89     created "MyApp/script"
90     created "MyApp/lib"
91     created "MyApp/root"
92     ...
93     created "MyApp/script/myapp_create.pl"
94     Change to application directory and Run "perl Makefile.PL" to make sure your install is complete
95     $ cd MyApp
96
97 This creates a similar skeletal structure to what we saw in Chapter 2 of
98 the tutorial, except with C<MyApp> and C<myapp> substituted for
99 C<Hello> and C<hello>.  (As noted in Chapter 2, omit the ".pl" from 
100 the command if you are using Strawberry Perl.)
101
102
103 =head1 EDIT THE LIST OF CATALYST PLUGINS
104
105 One of the greatest benefits of Catalyst is that it has such a large 
106 library of bases classes and plugins available that you can use easily 
107 add functionality to your application. Plugins are used to seamlessly 
108 integrate existing Perl modules into the overall Catalyst framework. In 
109 general, they do this by adding additional methods to the C<context> 
110 object (generally written as C<$c>) that Catalyst passes to every 
111 component throughout the framework. 
112
113
114 By default, Catalyst enables three plugins/flags:
115
116 =over 4
117
118 =item *
119
120 C<-Debug> Flag
121
122 Enables the Catalyst debug output you saw when we started the
123 C<script/myapp_server.pl> development server earlier.  You can remove
124 this item when you place your application into production.
125
126 To be technically correct, it turns out that C<-Debug> is not a plugin, but a I<flag>. 
127 Although most of the items specified on the C<__PACKAGE__-E<gt>setup> 
128 line of your application class will be plugins, Catalyst supports a 
129 limited number of flag options (of these, C<-Debug> is the most 
130 common).  See the documentation for C<Catalyst.pm> to get details on 
131 other flags (currently C<-Engine>, C<-Home>, and C<-Log>).
132
133 If you prefer, there are several other ways to enable debug output:
134
135 =over 4
136
137 =item *
138
139 Use the C<$c-E<gt>debug> method
140
141 =item *
142
143 The C<-d> option to C<script/myapp_server.pl>
144
145 =item *
146
147 The C<CATALYST_DEBUG=1> environment variable (or set it to
148 zero to templorarily disable debug output).
149
150 =back
151
152 B<TIP>: Depending on your needs, it can be helpful to permanently
153 remove C<-Debug> from C<lib/MyApp.pm> and then use the C<-d> option
154 to C<script/myapp_server.pl> to re-enable it just for the development
155 server.  We will not be using that approach in the tutorial, but feel
156 free to make use of it in your own projects.
157
158 =item *
159
160 L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
161
162 C<ConfigLoader> provides an automatic way to load configurable
163 parameters for your application from a central
164 L<Config::General|Config::General> file (versus having the values
165 hard-coded inside your Perl modules).  Config::General uses syntax
166 very similar to Apache configuration files.  We will see how to use
167 this feature of Catalyst during the authentication and authorization
168 sections (Chapter 5 and Chapter 6).
169
170 B<IMPORTANT NOTE:> If you are using a version of 
171 L<Catalyst::Devel|Catalyst::Devel> prior to version 1.06, be aware 
172 that Catalyst changed the default format from YAML to the more 
173 straightforward C<Config::General> style.  This tutorial uses the 
174 newer C<myapp.conf> file for C<Config::General>. However, Catalyst 
175 supports both formats and will automatically use either C<myapp.conf> 
176 or C<myapp.yml> (or any other format supported by 
177 L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader> and 
178 L<Config::Any|Config::Any>).  If you are using a version of 
179 Catalyst::Devel prior to 1.06, you can convert to the newer format by 
180 simply creating the C<myapp.conf> file manually and deleting 
181 C<myapp.yml>.  The default contents of the C<myapp.conf> you create 
182 should only consist of one line: 
183
184     name MyApp
185
186 B<TIP>: This script can be useful for converting between configuration
187 formats:
188
189     perl -Ilib -e 'use MyApp; use Config::General;
190         Config::General->new->save_file("myapp.conf", MyApp->config);'
191
192 =item *
193
194 L<Catalyst::Plugin::Static::Simple|Catalyst::Plugin::Static::Simple>
195
196 C<Static::Simple> provides an easy way to serve static content, such
197 as images and CSS files, from the development server.
198
199 =back
200
201 For our application, we want to add one new plugin into the mix.  To 
202 do this, edit C<lib/MyApp.pm> (this file is generally referred to as 
203 your I<application class>) and delete the lines with:
204
205     use Catalyst qw/
206         -Debug
207         ConfigLoader
208         Static::Simple
209     /;
210
211 Then replace it with:
212
213     # Load plugins
214     use Catalyst qw/
215         -Debug
216         ConfigLoader
217         Static::Simple
218     
219         StackTrace
220     /;
221
222 B<Note:> Recent versions of C<Catalyst::Devel> have used a variety of 
223 techniques to load these plugins/flags.  For example, you might see
224 the following:
225
226     __PACKAGE__->setup(qw/-Debug ConfigLoader Static::Simple/);
227
228 Don't let these variations confuse you -- they all accomplish the same 
229 result.
230
231 This tells Catalyst to start using one additional plugin, 
232 L<Catalyst::Plugin::StackTrace|Catalyst::Plugin::StackTrace>, to add a 
233 stack trace to the standard Catalyst "debug screen" (the screen 
234 Catalyst sends to your browser when an error occurs). Be aware that 
235 L<StackTrace|Catalyst::Plugin::StackTrace> output appears in your 
236 browser, not in the console window from which you're running your 
237 application, which is where logging output usually goes.
238
239 Make sure when adding new plugins you also include them as a new
240 dependency within the Makefile.PL file. For example, after adding
241 the StackTrace plugin the Makefile.PL should include the following
242 line:
243
244     requires 'Catalyst::Plugin::StackTrace';
245
246
247 B<Notes:> 
248
249 =over 4
250
251 =item *
252
253 C<__PACKAGE__> is just a shorthand way of referencing the name of the 
254 package where it is used.  Therefore, in C<MyApp.pm>, C<__PACKAGE__> 
255 is equivalent to C<MyApp>.
256
257 =item *
258
259 You will want to disable L<StackTrace|Catalyst::Plugin::StackTrace> 
260 before you put your application into production, but it can be helpful 
261 during development.
262
263 =item *
264
265 When specifying plugins, you can omit C<Catalyst::Plugin::> from the 
266 name.  Additionally, you can spread the plugin names across multiple 
267 lines as shown here or place them all on one line.
268
269 =back
270
271
272 =head1 CREATE A CATALYST CONTROLLER
273
274 As discussed earlier, controllers are where you write methods that
275 interact with user input.  Typically, controller methods respond to
276 C<GET> and C<POST> requests from the user's web browser.
277
278 Use the Catalyst C<create> script to add a controller for book-related
279 actions:
280
281     $ script/myapp_create.pl controller Books
282      exists "/home/me/MyApp/script/../lib/MyApp/Controller"
283      exists "/home/me/MyApp/script/../t"
284     created "/home/me/MyApp/script/../lib/MyApp/Controller/Books.pm"
285     created "/home/me/MyApp/script/../t/controller_Books.t"
286
287 Then edit C<lib/MyApp/Controller/Books.pm> (as discussed in Chapter 2 of
288 the Tutorial, Catalyst has a separate directory under C<lib/MyApp> for
289 each of the three parts of MVC: C<Model>, C<View>, and C<Controller>)
290 and add the following method to the controller:
291
292     =head2 list
293     
294     Fetch all book objects and pass to books/list.tt2 in stash to be displayed
295     
296     =cut
297     
298     sub list :Local {
299         # Retrieve the usual Perl OO '$self' for this object. $c is the Catalyst
300         # 'Context' that's used to 'glue together' the various components
301         # that make up the application
302         my ($self, $c) = @_;
303     
304         # Retrieve all of the book records as book model objects and store in the
305         # stash where they can be accessed by the TT template
306         # $c->stash(books => [$c->model('DB::Book')->all]);
307         # But, for now, use this code until we create the model later
308         $c->stash(books => '');
309     
310         # Set the TT template to use.  You will almost always want to do this
311         # in your action methods (action methods respond to user input in
312         # your controllers).
313         $c->stash(template => 'books/list.tt2');
314     }
315
316 B<TIP>: See Appendix 1 for tips on removing the leading spaces when
317 cutting and pasting example code from POD-based documents.
318
319 Programmers experienced with object-oriented Perl should recognize 
320 C<$self> as a reference to the object where this method was called. 
321 On the other hand, C<$c> will be new to many Perl programmers who have 
322 not used Catalyst before (it's sometimes written as C<$context>).  The 
323 Context object is automatically passed to all Catalyst components.  It 
324 is used to pass information between components and provide access to 
325 Catalyst and plugin functionality.
326
327 Catalyst actions are regular Perl methods, but they make use of 
328 attributes (the "C<:Local>" next to the "C<sub list>" in the code 
329 above) to provide additional information to the Catalyst dispatcher 
330 logic (note that the space between the colon and the attribute name is 
331 optional; you will see attributes written both ways).  Most Catalyst 
332 Controllers use one of five action types:
333
334 =over 4
335
336 =item *
337
338 B<:Private> -- Use C<:Private> for methods that you want to make into 
339 an action, but you do not want Catalyst to directly expose  the method 
340 to your users.  Catalyst will not map C<:Private> methods to a URI. 
341 Use them for various sorts of "special" methods (the C<begin>, 
342 C<auto>, etc. discussed below) or for methods you want to be able to 
343 C<forward> or C<detach> to.  (If the method is a plain old "helper 
344 method" that you don't want to be an action at all, then just define 
345 the method without any attribute -- you can call it in your code, but 
346 the Catalyst dispatcher will ignore it.)
347
348 There are five types of "special" build-in C<:Private> actions: 
349 C<begin>, C<end>, C<default>, C<index>, and C<auto>.
350
351 =over 4
352
353 =item *
354
355 With C<begin>, C<end>, C<default>, C<index> private actions, only the
356 most specific action of each type will be called.  For example, if you
357 define a C<begin> action in your controller it will I<override> a
358 C<begin> action in your application/root controller -- I<only> the
359 action in your controller will be called.
360
361 =item *
362
363 Unlike the other actions where only a single method is called for each
364 request, I<every> auto action along the chain of namespaces will be
365 called.  Each C<auto> action will be called I<from the application/root
366 controller down through the most specific class>.
367
368 =back
369
370 =item *
371
372 B<:Path> -- C<:Path> actions let you map a method to an explicit URI 
373 path.  For example, "C<:Path('list')>" in 
374 C<lib/MyApp/Controller/Books.pm> would match on the URL 
375 C<http://localhost:3000/books/list>, but "C<:Path('/list')>" would 
376 match on C<http://localhost:3000/list> (because of the leading slash). 
377 You can use C<:Args()> to specify how many arguments an action should 
378 accept.  See L<Catalyst::Manual::Intro/Action_types> for more 
379 information and examples.
380
381 =item *
382
383 B<:Local> -- C<:Local> is merely a shorthand for 
384 "C<:Path('_name_of_method_')>".  For example, these are equivalent:
385 "C<sub create_book :Local {...}>" and 
386 "C<sub create_book :Path('create_book') {...}>".
387
388 =item *
389
390 B<:Global> -- C<:Global> is merely a shorthand for 
391 "C<:Path('/_name_of_method_')>".  For example, these are equivalent:
392 "C<sub create_book :Global {...}>" and 
393 "C<sub create_book :Path('/create_book') {...}>".
394
395 =item *
396
397 B<:Chained> -- Newer Catalyst applications tend to use the Chained 
398 dispatch form of action types because of its power and flexibility.  
399 It allows a series of controller methods to be automatically dispatched
400 to service a single user request.  See 
401 L<Catalyst::Manual::Tutorial::04_BasicCRUD|Catalyst::Manual::Tutorial::04_BasicCRUD> 
402 and L<Catalyst::DispatchType::Chained|Catalyst::DispatchType::Chained> 
403 for more information on chained actions.
404
405 =back
406
407 You should refer to L<Catalyst::Manual::Intro/Action_types> for 
408 additional information and for coverage of some lesser-used action 
409 types not discussed here (C<Regex> and C<LocalRegex>).
410
411
412 =head1 CATALYST VIEWS
413
414 As mentioned in Chapter 2 of the tutorial, views are where you render
415 output, typically for display in the user's web browser (but also
416 possibly using into output-generation systems, such as PDF or JSON).
417 The code in C<lib/MyApp/View> selects the I<type> of view to use, with
418 the actual rendering template found in the C<root> directory.  As with
419 virtually every aspect of Catalyst, options abound when it comes to the
420 specific view technology you adopt inside your application. However,
421 most Catalyst applications use the Template Toolkit, known as TT (for
422 more information on TT, see L<http://www.template-toolkit.org>). Other
423 somewhat popular view technologies include Mason
424 (L<http://www.masonhq.com> and L<http://www.masonbook.com>) and
425 L<HTML::Template> (L<http://html-template.sourceforge.net>).
426
427
428 =head2 Create a Catalyst View
429
430 When using TT for the Catalyst view, the main helper script
431 is L<Catalyst::Helper::View::TT|Catalyst::Helper::View::TT>.
432 You may also come across references to 
433 L<Catalyst::Helper::View::TTSite|Catalyst::Helper::View::TTSite>,
434 but its use is now deprecated.
435
436 Enter the following command to enable the C<TT> style of view
437 rendering for this tutorial:
438
439     $ script/myapp_create.pl view TT TT
440      exists "/home/me/MyApp/script/../lib/MyApp/View"
441      exists "/home/me/MyApp/script/../t"
442      created "/home/me/MyApp/script/../lib/MyApp/View/TT.pm"
443      created "/home/me/MyApp/script/../t/view_TT.t"
444
445 This simply creates a view called C<TT> (the second 'TT' argument) in 
446 a file called C<TT.pm> (the first 'TT' argument). It is now up to you 
447 to decide how you want to structure your view layout.  For the 
448 tutorial, we will start with a very simple TT template to initially 
449 demonstrate the concepts, but quickly migrate to a more typical 
450 "wrapper page" type of configuration (where the "wrapper" controls the 
451 overall "look and feel" of your site from a single file or set of 
452 files).
453
454 Edit C<lib/MyApp/View/TT.pm> and you should see that the default
455 contents contains something similar to the following:
456
457     __PACKAGE__->config(TEMPLATE_EXTENSION => '.tt');
458
459 And update it to match:
460
461     __PACKAGE__->config(
462         # Change default TT extension
463         TEMPLATE_EXTENSION => '.tt2',
464         # Set the location for TT files
465         INCLUDE_PATH => [
466                 MyApp->path_to( 'root', 'src' ),
467             ],
468     );
469
470 B<NOTE:> Make sure to add a comma after '.tt2' outside the single
471 quote.
472
473 This changes the default extension for Template Toolkit from '.tt' to 
474 '.tt2' and changes the base directory for your template files from 
475 C<root> to C<root/src>.  Stick with these conventions for the 
476 tutorial, but feel free to use whatever options you desire in your 
477 applications (as with most things Perl, there's more than one way to 
478 do it...).
479
480 B<Note:> We will use C<root/src> as the base directory for our 
481 template files, with a full naming convention of 
482 C<root/src/_controller_name_/_action_name_.tt2>.  Another popular option is to
483 use C<root/> as the base (with a full filename pattern of 
484 C<root/_controller_name_/_action_name_.tt2>).
485
486
487 =head2 Create a TT Template Page
488
489 First create a directory for book-related TT templates:
490
491     $ mkdir -p root/src/books
492
493 Then create C<root/src/books/list.tt2> in your editor and enter:
494
495     [% # This is a TT comment.  The '-' at the end "chomps" the newline.  You won't -%]
496     [% # see this "chomping" in your browser because HTML ignores blank lines, but  -%]
497     [% # it WILL eliminate a blank line if you view the HTML source.  It's purely   -%]
498     [%- # optional, but both the beginning and the ending TT tags support chomping. -%]
499     
500     [% # Provide a title -%]
501     [% META title = 'Book List' -%]
502     
503     <table>
504     <tr><th>Title</th><th>Rating</th><th>Author(s)</th></tr>
505     [% # Display each book in a table row %]
506     [% FOREACH book IN books -%]
507       <tr>
508         <td>[% book.title %]</td>
509         <td>[% book.rating %]</td>
510         <td></td>
511       </tr>
512     [% END -%]
513     </table>
514
515 As indicated by the inline comments above, the C<META title> line uses
516 TT's META feature to provide a title to the "wrapper" that we will
517 create later. Meanwhile, the C<FOREACH> loop iterates through each
518 C<book> model object and prints the C<title> and C<rating> fields.
519
520 The C<[%> and C<%]> tags are used to delimit Template Toolkit code.  TT
521 supports a wide variety of directives for "calling" other files,
522 looping, conditional logic, etc.  In general, TT simplifies the usual
523 range of Perl operators down to the single dot (".") operator.  This
524 applies to operations as diverse as method calls, hash lookups, and list
525 index values (see
526 L<http://search.cpan.org/perldoc?Template::Manual::Variables> for
527 details and examples).  In addition to the usual L<Template> module Pod
528 documentation, you can access the TT manual at
529 L<http://search.cpan.org/perldoc?Template::Manual>.
530
531 B<TIP:> While you can build all sorts of complex logic into your TT 
532 templates, you should in general keep the "code" part of your 
533 templates as simple as possible.  If you need more complex logic, 
534 create helper methods in your model that abstract out a set of code 
535 into a single call from your TT template.  (Note that the same is true 
536 of your controller logic as well -- complex sections of code in your 
537 controllers should often be pulled out and placed into your model 
538 objects.)  In Chapter 4 of the tutorial we will explore some extremely 
539 helpful and powerful features of L<DBIx::Class> that allow you to pull 
540 code out of your views and controllers and place it where it 
541 rightfully belongs in a model class.
542
543
544 =head2 Test Run The Application
545
546 To test your work so far, first start the development server:
547
548     $ script/myapp_server.pl -r
549
550 Then point your browser to L<http://localhost:3000> and you should
551 still get the Catalyst welcome page.  Next, change the URL in your
552 browser to L<http://localhost:3000/books/list>.  If you have
553 everything working so far, you should see a web page that displays
554 nothing other than our column headers for "Title", "Rating", and
555 "Author(s)" -- we will not see any books until we get the database and
556 model working below.
557
558 If you run into problems getting your application to run correctly, it
559 might be helpful to refer to some of the debugging techniques covered in
560 the L<Debugging|Catalyst::Manual::Tutorial::07_Debugging> chapter of the
561 tutorial.
562
563
564 =head1 CREATE A SQLITE DATABASE
565
566 In this step, we make a text file with the required SQL commands to
567 create a database table and load some sample data.  We will use 
568 SQLite (L<http://www.sqlite.org>), a popular database that is
569 lightweight and easy to use. Be sure to get at least version 3. Open
570 C<myapp01.sql> in your editor and enter:
571
572     --
573     -- Create a very simple database to hold book and author information
574     --
575     PRAGMA foreign_keys = ON;
576     CREATE TABLE book (
577             id          INTEGER PRIMARY KEY,
578             title       TEXT ,
579             rating      INTEGER
580     );
581     -- 'book_author' is a many-to-many join table between books & authors
582     CREATE TABLE book_author (
583             book_id     INTEGER REFERENCES book(id) ON DELETE CASCADE ON UPDATE CASCADE,
584             author_id   INTEGER REFERENCES author(id) ON DELETE CASCADE ON UPDATE CASCADE,
585             PRIMARY KEY (book_id, author_id)
586     );
587     CREATE TABLE author (
588             id          INTEGER PRIMARY KEY,
589             first_name  TEXT,
590             last_name   TEXT
591     );
592     ---
593     --- Load some sample data
594     ---
595     INSERT INTO book VALUES (1, 'CCSP SNRS Exam Certification Guide', 5);
596     INSERT INTO book VALUES (2, 'TCP/IP Illustrated, Volume 1', 5);
597     INSERT INTO book VALUES (3, 'Internetworking with TCP/IP Vol.1', 4);
598     INSERT INTO book VALUES (4, 'Perl Cookbook', 5);
599     INSERT INTO book VALUES (5, 'Designing with Web Standards', 5);
600     INSERT INTO author VALUES (1, 'Greg', 'Bastien');
601     INSERT INTO author VALUES (2, 'Sara', 'Nasseh');
602     INSERT INTO author VALUES (3, 'Christian', 'Degu');
603     INSERT INTO author VALUES (4, 'Richard', 'Stevens');
604     INSERT INTO author VALUES (5, 'Douglas', 'Comer');
605     INSERT INTO author VALUES (6, 'Tom', 'Christiansen');
606     INSERT INTO author VALUES (7, 'Nathan', 'Torkington');
607     INSERT INTO author VALUES (8, 'Jeffrey', 'Zeldman');
608     INSERT INTO book_author VALUES (1, 1);
609     INSERT INTO book_author VALUES (1, 2);
610     INSERT INTO book_author VALUES (1, 3);
611     INSERT INTO book_author VALUES (2, 4);
612     INSERT INTO book_author VALUES (3, 5);
613     INSERT INTO book_author VALUES (4, 6);
614     INSERT INTO book_author VALUES (4, 7);
615     INSERT INTO book_author VALUES (5, 8);
616
617 Then use the following command to build a C<myapp.db> SQLite database:
618
619     $ sqlite3 myapp.db < myapp01.sql
620
621 If you need to create the database more than once, you probably want to
622 issue the C<rm myapp.db> command to delete the database before you use
623 the C<sqlite3 myapp.db E<lt> myapp01.sql> command.
624
625 Once the C<myapp.db> database file has been created and initialized, you
626 can use the SQLite command line environment to do a quick dump of the
627 database contents:
628
629     $ sqlite3 myapp.db
630     SQLite version 3.6.22
631     Enter ".help" for instructions
632     Enter SQL statements terminated with a ";"
633     sqlite> select * from book;
634     1|CCSP SNRS Exam Certification Guide|5
635     2|TCP/IP Illustrated, Volume 1|5
636     3|Internetworking with TCP/IP Vol.1|4
637     4|Perl Cookbook|5
638     5|Designing with Web Standards|5
639     sqlite> .q
640     $
641
642 Or:
643
644     $ sqlite3 myapp.db "select * from book"
645     1|CCSP SNRS Exam Certification Guide|5
646     2|TCP/IP Illustrated, Volume 1|5
647     3|Internetworking with TCP/IP Vol.1|4
648     4|Perl Cookbook|5
649     5|Designing with Web Standards|5
650
651 As with most other SQL tools, if you are using the full "interactive"
652 environment you need to terminate your SQL commands with a ";" (it's not
653 required if you do a single SQL statement on the command line).  Use
654 ".q" to exit from SQLite from the SQLite interactive mode and return to
655 your OS command prompt.
656
657 Please note that here we have chosen to use 'singular' table names. This is
658 because the default inflection code for older versions of
659 L<DBIx::Class::Schema::Loader> does NOT handle plurals. There has been much
660 philosophical discussion on whether table names should be plural or singular.
661 There is no one correct answer, as long as one makes a choice and remains
662 consistent with it. If you prefer plural table names (e.g. you think that they
663 are easier to read) then see the documentation in
664 L<DBIx::Class::Schema::Loader::Base/naming> (version 0.05 or greater).
665
666 For using other databases, such as PostgreSQL or MySQL, see 
667 L<Appendix 2|Catalyst::Manual::Tutorial::10_Appendices>.
668
669
670 =head1 DATABASE ACCESS WITH DBIx::Class
671
672 Catalyst can be used with virtually any form of datastore available 
673 via Perl.  For example, L<Catalyst::Model::DBI|Catalyst::Model::DBI> 
674 can be used to access databases through the traditional Perl L<DBI> 
675 interface or you can use a model to access files of any type on the 
676 filesystem.  However, most Catalyst applications use some form of 
677 object-relational mapping (ORM) technology to create objects 
678 associated with tables in a relational database.  Matt Trout's 
679 L<DBIx::Class|DBIx::Class> (abbreviated as "DBIC") has rapidly emerged 
680 as the Perl-based ORM technology of choice. Most new Catalyst 
681 applications rely on DBIx::Class, as will this tutorial.
682
683 Although DBIx::Class has included support for a C<create=dynamic> mode 
684 to automatically read the database structure every time the 
685 application starts, it's use is no longer recommended.  While it can 
686 make for "flashy" demos, the use of the C<create=static> mode we use 
687 below can be implemented just as quickly and provides many advantages 
688 (such as the ability to add your own methods to the overall DBIC 
689 framework, a technique that we see in Chapter 4).
690
691
692 =head2 Make Sure You Have a Recent Version of the DBIx::Class Model
693
694 First, let's be sure we have a recent version of the DBIC helper,
695 L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema>, so
696 that we can take advantage of some recent enhancements in how
697 foreign keys are handled with SQLite.  To check your version, 
698 run this command:
699
700     $ perl -MCatalyst::Model::DBIC::Schema -e \
701         'print "$Catalyst::Model::DBIC::Schema::VERSION\n"'
702     0.4
703
704 Please note the '\' above.  Depending on your environment, you might 
705 be able to cut and paste the text as shown or need to remove the '\' 
706 character to that the command is all on a single line.
707
708 If you are following along in Debian 5, you should have version 0.40 or 
709 higher (shown above as "0.4" with the tailing zero removed). If you have 
710 less than v0.39, you will need to run this command to install it 
711 directly from CPAN: 
712
713     $ sudo cpan Catalyst::Model::DBIC::Schema
714
715 And re-run the version print command to verify that you are now at 
716 0.39 or higher.
717
718 In addition, since we are using SQLite's foreign key support here,
719 please be sure that you use version C<1.27> of L<DBD::SQLite> or later:
720
721     $ perl -MDBD::SQLite -e 'print "$DBD::SQLite::VERSION\n"'
722     1.29
723
724 Upgrade if you are not at version C<1.27> or higher.
725
726
727 =head2 Create Static DBIx::Class Schema Files
728
729 Before you continue, make sure your C<myapp.db> database file is in 
730 the application's topmost directory. Now use the model helper with 
731 the C<create=static> option to read the database with 
732 L<DBIx::Class::Schema::Loader|DBIx::Class::Schema::Loader> and 
733 automatically build the required files for us:
734
735     $ script/myapp_create.pl model DB DBIC::Schema MyApp::Schema \
736         create=static dbi:SQLite:myapp.db \
737         on_connect_do="PRAGMA foreign_keys = ON"
738      exists "/home/me/MyApp/script/../lib/MyApp/Model"
739      exists "/home/me/MyApp/script/../t"
740     Dumping manual schema for MyApp::Schema to directory /home/me/MyApp/script/../lib ...
741     Schema dump completed.
742     created "/home/me/MyApp/script/../lib/MyApp/Model/DB.pm"
743     created "/home/me/MyApp/script/../t/model_DB.t"
744
745 Please note the '\' above.  Depending on your environment, you might 
746 be able to cut and paste the text as shown or need to remove the '\' 
747 character to that the command is all on a single line.
748
749 The C<script/myapp_create.pl> command breaks down like this:
750
751 =over 4
752
753 =item *
754
755 C<DB> is the name of the model class to be created by the helper in 
756 C<lib/MyApp/Model>.
757
758 =item *
759
760 C<DBIC::Schema> is the type of the model to create.
761
762 =item *
763
764 C<MyApp::Schema> is the name of the DBIC schema file written to
765 C<lib/MyApp/Schema.pm>.
766
767 =item *
768
769 C<create=static> causes 
770 L<DBIx::Class::Schema::Loader|DBIx::Class::Schema::Loader> to 
771 load the schema as it runs and then write that information out
772 into files.
773
774 =item *
775
776 C<dbi:SQLite:myapp.db> is the standard DBI connect string 
777 for use with SQLite.
778
779 =item *
780
781 And finally, the C<on_connect_do> string requests that 
782 L<DBIx::Class::Schema::Loader|DBIx::Class::Schema::Loader> create 
783 foreign key relationships for us (this is not needed for databases such 
784 as PostgreSQL and MySQL, but is required for SQLite). If you take a look 
785 at C<lib/MyApp/Model/DB.pm>, you will see that the SQLite pragma is 
786 propogated to the Model, so that SQLite's recent (and optional) foreign 
787 key enforcement is enabled at the start of every database connection. 
788
789
790
791 =back
792
793 If you look in the C<lib/MyApp/Schema.pm> file, you will find that it 
794 only contains a call to the C<load_namespaces> method.  You will also 
795 find that C<lib/MyApp> contains a C<Schema> subdirectory, which then 
796 has a subdirectory called "Result".  This "Result" subdirectory then 
797 has files named according to each of the tables in our simple database 
798 (C<Author.pm>, C<BookAuthor.pm>, and C<Book.pm>).  These three 
799 files are called "Result Classes" in DBIx::Class nomenclature. Although the 
800 Result Class files are named after tables in our database, the classes 
801 correspond to the I<row-level data> that is returned by DBIC (more on 
802 this later, especially in 
803 L<Catalyst::Manual::Tutorial::04_BasicCRUD/EXPLORING THE POWER OF DBIC>).
804
805 The idea with the Result Source files created under 
806 C<lib/MyApp/Schema/Result> by the C<create=static> option is to only 
807 edit the files below the C<# DO NOT MODIFY THIS OR ANYTHING ABOVE!> 
808 warning. If you place all of your changes below that point in the 
809 file, you can regenerate the automatically created information at the 
810 top of each file should your database structure get updated.
811
812 Also note the "flow" of the model information across the various files 
813 and directories.  Catalyst will initially load the model from 
814 C<lib/MyApp/Model/DB.pm>.  This file contains a reference to 
815 C<lib/MyApp/Schema.pm>, so that file is loaded next.  Finally, the 
816 call to C<load_namespaces> in C<Schema.pm> will load each of the 
817 "Result Class" files from the C<lib/MyApp/Schema/Result> subdirectory. 
818 The final outcome is that Catalyst will dynamically create three 
819 table-specific Catalyst models every time the application starts (you 
820 can see these three model files listed in the debug output generated 
821 when you launch the application).
822
823 B<NOTE:> Older versions of 
824 L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> use the 
825 deprecated DBIx::Class C<load_classes> technique instead of the newer 
826 C<load_namspaces>.  For new applications, please try to use 
827 C<load_namespaces> since it more easily supports a very useful DBIC 
828 technique called "ResultSet Classes."  If you need to convert an 
829 existing application from "load_classes" to "load_namespaces," you can 
830 use this process to automate the migration, but first make sure you have
831 version C<0.39> of L<Catalyst::Model::DBIC::Schema> and
832 L<DBIx::Class::Schema::Loader> version C<0.05000> or later.
833
834     $ # Re-run the helper to upgrade for you
835     $ script/myapp_create.pl model DB DBIC::Schema MyApp::Schema \
836         create=static naming=current use_namespaces=1 \
837         dbi:SQLite:myapp.db \
838         on_connect_do="PRAGMA foreign_keys = ON"
839
840
841 =head1 ENABLE THE MODEL IN THE CONTROLLER
842
843 Open C<lib/MyApp/Controller/Books.pm> and un-comment the model code we 
844 left disabled earlier so that your version matches the following (un-
845 comment the line containing C<[$c-E<gt>model('DB::Book')-E<gt>all]> 
846 and delete the next 2 lines):
847
848     =head2 list
849     
850     Fetch all book objects and pass to books/list.tt2 in stash to be displayed
851     
852     =cut
853     
854     sub list :Local {
855         # Retrieve the usual Perl OO '$self' for this object. $c is the Catalyst
856         # 'Context' that's used to 'glue together' the various components
857         # that make up the application
858         my ($self, $c) = @_;
859     
860         # Retrieve all of the book records as book model objects and store
861         # in the stash where they can be accessed by the TT template
862         $c->stash(books => [$c->model('DB::Book')->all]);
863     
864         # Set the TT template to use.  You will almost always want to do this
865         # in your action methods (action methods respond to user input in
866         # your controllers).
867         $c->stash(template => 'books/list.tt2');
868     }
869
870 B<TIP>: You may see the C<$c-E<gt>model('DB::Book')> un-commented 
871 above written as C<$c-E<gt>model('DB')-E<gt>resultset('Book')>.  The 
872 two are equivalent.  Either way, C<$c-E<gt>model> returns a 
873 L<DBIx::Class::ResultSet|DBIx::Class::ResultSet> which handles queries 
874 against the database and iterating over the set of results that is 
875 returned.
876
877 We are using the C<-E<gt>all> to fetch all of the books.  DBIC 
878 supports a wide variety of more advanced operations to easily do 
879 things like filtering and sorting the results.  For example, the 
880 following could be used to sort the results by descending title:
881
882     $c->model('DB::Book')->search({}, {order_by => 'title DESC'});
883
884 Some other examples are provided in 
885 L<DBIx::Class::Manual::Cookbook/Complex WHERE clauses>, with 
886 additional information found at L<DBIx::Class::ResultSet/search>, 
887 L<DBIx::Class::Manual::FAQ/Searching>, 
888 L<DBIx::Class::Manual::Intro|DBIx::Class::Manual::Intro> 
889 and L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema>.
890
891
892 =head2 Test Run The Application
893
894 First, let's enable an environment variable that causes DBIx::Class to 
895 dump the SQL statements used to access the database.  This is a 
896 helpful trick when you are trying to debug your database-oriented 
897 code.  Press C<Ctrl-C> to break out of the development server and
898 enter:
899
900     $ export DBIC_TRACE=1
901     $ script/myapp_server.pl -r 
902
903 This assumes you are using bash as your shell -- adjust accordingly if
904 you are using a different shell (for example, under tcsh, use
905 C<setenv DBIC_TRACE 1>).
906
907 B<NOTE:> You can also set this in your code using
908 C<$class-E<gt>storage-E<gt>debug(1);>.  See
909 L<DBIx::Class::Manual::Troubleshooting> for details (including options
910 to log to a file instead of displaying to the Catalyst development server
911 log).
912
913 Then launch the Catalyst development server.  The log output should
914 display something like:
915
916     $ script/myapp_server.pl -r
917     [debug] Debug messages enabled
918     [debug] Statistics enabled
919     [debug] Loaded plugins:
920     .----------------------------------------------------------------------------.
921     | Catalyst::Plugin::ConfigLoader  0.27                                       |
922     | Catalyst::Plugin::StackTrace  0.11                                         |
923     '----------------------------------------------------------------------------'
924     
925     [debug] Loaded dispatcher "Catalyst::Dispatcher"
926     [debug] Loaded engine "Catalyst::Engine::HTTP"
927     [debug] Found home "/home/me/MyApp"
928     [debug] Loaded Config "/home/me/MyApp/myapp.conf"
929     [debug] Loaded components:
930     .-----------------------------------------------------------------+----------.
931     | Class                                                           | Type     |
932     +-----------------------------------------------------------------+----------+
933     | MyApp::Controller::Books                                        | instance |
934     | MyApp::Controller::Root                                         | instance |
935     | MyApp::Model::DB                                                | instance |
936     | MyApp::Model::DB::Author                                        | class    |
937     | MyApp::Model::DB::Book                                          | class    |
938     | MyApp::Model::DB::BookAuthor                                    | class    |
939     | MyApp::View::TT                                                 | instance |
940     '-----------------------------------------------------------------+----------'
941     
942     [debug] Loaded Private actions:
943     .----------------------+--------------------------------------+--------------.
944     | Private              | Class                                | Method       |
945     +----------------------+--------------------------------------+--------------+
946     | /default             | MyApp::Controller::Root              | default      |
947     | /end                 | MyApp::Controller::Root              | end          |
948     | /index               | MyApp::Controller::Root              | index        |
949     | /books/index         | MyApp::Controller::Books             | index        |
950     | /books/list          | MyApp::Controller::Books             | list         |
951     '----------------------+--------------------------------------+--------------'
952     
953     [debug] Loaded Path actions:
954     .-------------------------------------+--------------------------------------.
955     | Path                                | Private                              |
956     +-------------------------------------+--------------------------------------+
957     | /                                   | /default                             |
958     | /                                   | /index                               |
959     | /books                              | /books/index                         |
960     | /books/list                         | /books/list                          |
961     '-------------------------------------+--------------------------------------'
962     
963     [info] MyApp powered by Catalyst 5.80020
964     You can connect to your server at http://debian:3000
965
966 B<NOTE:> Be sure you run the C<script/myapp_server.pl> command from
967 the 'base' directory of your application, not inside the C<script>
968 directory itself or it will not be able to locate the C<myapp.db>
969 database file.  You can use a fully qualified or a relative path to
970 locate the database file, but we did not specify that when we ran the
971 model helper earlier.
972
973 Some things you should note in the output above:
974
975 =over 4
976
977 =item *
978
979 Catalyst::Model::DBIC::Schema dynamically created three model classes,
980 one to represent each of the three tables in our database
981 (C<MyApp::Model::DB::Author>, C<MyApp::Model::DB::BookAuthor>,
982 and C<MyApp::Model::DB::Book>).
983
984 =item *
985
986 The "list" action in our Books controller showed up with a path of
987 C</books/list>.
988
989 =back
990
991 Point your browser to L<http://localhost:3000> and you should still get
992 the Catalyst welcome page.
993
994 Next, to view the book list, change the URL in your browser to
995 L<http://localhost:3000/books/list>. You should get a list of the five
996 books loaded by the C<myapp01.sql> script above without any formatting.
997 The rating for each book should appear on each row, but the "Author(s)"
998 column will still be blank (we will fill that in later).
999
1000 Also notice in the output of the C<script/myapp_server.pl> that 
1001 DBIx::Class used the following SQL to retrieve the data:
1002
1003     SELECT me.id, me.title, me.rating FROM book me
1004
1005 because we enabled DBIC_TRACE.
1006
1007 You now have the beginnings of a simple but workable web application.
1008 Continue on to future sections and we will develop the application
1009 more fully.
1010
1011
1012 =head1 CREATE A WRAPPER FOR THE VIEW
1013
1014 When using TT, you can (and should) create a wrapper that will
1015 literally wrap content around each of your templates.  This is
1016 certainly useful as you have one main source for changing things that
1017 will appear across your entire site/application instead of having to
1018 edit many individual files.
1019
1020
1021 =head2 Configure TT.pm For The Wrapper
1022
1023 In order to create a wrapper, you must first edit your TT view and
1024 tell it where to find your wrapper file. 
1025
1026 Edit you TT view in C<lib/MyApp/View/TT.pm> and change it to match the 
1027 following:
1028
1029     __PACKAGE__->config(
1030         # Change default TT extension
1031         TEMPLATE_EXTENSION => '.tt2',
1032         # Set the location for TT files
1033         INCLUDE_PATH => [
1034                 MyApp->path_to( 'root', 'src' ),
1035             ],
1036         # Set to 1 for detailed timer stats in your HTML as comments
1037         TIMER              => 0,
1038         # This is your wrapper template located in the 'root/src'
1039         WRAPPER => 'wrapper.tt2',
1040     );
1041
1042
1043 =head2 Create the Wrapper Template File and Stylesheet
1044
1045 Next you need to set up your wrapper template.  Basically, you'll want
1046 to take the overall layout of your site and put it into this file.
1047 For the tutorial, open C<root/src/wrapper.tt2> and input the following:
1048
1049     <?xml version="1.0" encoding="UTF-8"?>
1050     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
1051     <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
1052     <head>
1053     <title>[% template.title or "My Catalyst App!" %]</title>
1054     <link rel="stylesheet" href="[% c.uri_for('/static/css/main.css') %]" />
1055     </head>
1056     
1057     <body>
1058     <div id="outer">
1059     <div id="header">
1060         [%# Your logo could go here -%]
1061         <img src="[% c.uri_for('/static/images/btn_88x31_powered.png') %]" />
1062         [%# Insert the page title -%]
1063         <h1>[% template.title or site.title %]</h1>
1064     </div>
1065     
1066     <div id="bodyblock">
1067     <div id="menu">
1068         Navigation:
1069         <ul>
1070             <li><a href="[% c.uri_for('/books/list') %]">Home</a></li>
1071             <li><a href="[% c.uri_for('/') %]" title="Catalyst Welcome Page">Welcome</a></li>
1072         </ul>
1073     </div><!-- end menu -->
1074     
1075     <div id="content">
1076         [%# Status and error messages %]
1077         <span class="message">[% status_msg %]</span>
1078         <span class="error">[% error_msg %]</span>
1079         [%# This is where TT will stick all of your template's contents. -%]
1080         [% content %]
1081     </div><!-- end content -->
1082     </div><!-- end bodyblock -->
1083     
1084     <div id="footer">Copyright (c) your name goes here</div>
1085     </div><!-- end outer -->
1086     
1087     </body>
1088     </html>
1089
1090 Notice the status and error message sections in the code above:
1091
1092     <span class="status">[% status_msg %]</span>
1093     <span class="error">[% error_msg %]</span>
1094
1095 If we set either message in the Catalyst stash (e.g.,
1096 C<$c-E<gt>stash-E<gt>{status_msg} = 'Request was successful!'>) it
1097 will be displayed whenever any view used by that request is rendered.
1098 The C<message> and C<error> CSS styles can be customized to suit your
1099 needs in the C<root/static/css/main.css> file we create below.
1100
1101 B<Notes:> 
1102
1103 =over 4
1104
1105 =item *
1106
1107 The Catalyst stash only lasts for a single HTTP request.  If
1108 you need to retain information across requests you can use
1109 L<Catalyst::Plugin::Session|Catalyst::Plugin::Session> (we will use
1110 Catalyst sessions in the Authentication chapter of the tutorial).
1111
1112 =item *
1113
1114 Although it is beyond the scope of this tutorial, you may wish to use
1115 a JavaScript or AJAX tool such as jQuery (L<http://www.jquery.com>) or
1116 Dojo (L<http://www.dojotoolkit.org>).
1117
1118 =back
1119
1120
1121 =head3 Create A Basic Stylesheet
1122
1123 First create a central location for stylesheets under the static
1124 directory:
1125
1126     $ mkdir root/static/css
1127
1128 Then open the file C<root/static/css/main.css> (the file referenced in
1129 the stylesheet href link of our wrapper above) and add the following
1130 content:
1131
1132     #header {
1133         text-align: center;
1134     }
1135     #header h1 {
1136         margin: 0;
1137     }
1138     #header img {
1139         float: right;
1140     }
1141     #footer {
1142         text-align: center;
1143         font-style: italic;
1144         padding-top: 20px;
1145     }
1146     #menu {
1147         font-weight: bold;
1148         background-color: #ddd;
1149     }
1150     #menu ul {
1151         list-style: none;
1152         float: left;
1153         margin: 0;
1154         padding: 0 0 50% 5px;
1155         font-weight: normal;
1156         background-color: #ddd;
1157         width: 100px;
1158     }
1159     #content {
1160         margin-left: 120px;
1161     }
1162     .message {
1163         color: #390;
1164     }
1165     .error {
1166         color: #f00;
1167     }
1168
1169 You may wish to check out a "CSS Framework" like Emastic
1170 (L<http://code.google.com/p/emastic/>) as a way to quickly
1171 provide lots of high-quality CSS functionality.
1172
1173
1174 =head2 Test Run The Application
1175
1176 Hit "Reload" in your web browser and you should now see a formatted 
1177 version of our basic book list. (Again, the development server should 
1178 have automatically restarted when you made changes to 
1179 C<lib/MyApp/View/TT.pm>. If you are not using the "-r" option, you will 
1180 need to hit C<Ctrl-C> and manually restart it. Also note that the 
1181 development server does I<NOT> need to restart for changes to the TT and 
1182 static files we created and edited in the C<root> directory -- those 
1183 updates are handled on a per-request basis.) 
1184
1185 Although our wrapper and stylesheet are obviously very simple, you 
1186 should see how it allows us to control the overall look of an entire 
1187 website from two central files. To add new pages to the site, just 
1188 provide a template that fills in the C<content> section of our wrapper 
1189 template -- the wrapper will provide the overall feel of the page. 
1190
1191
1192 =head2 Updating the Generated DBIx::Class Result Class Files
1193
1194 If you take a look at the Schema files automatically generated by 
1195 L<DBIx::Class::Schema::Loader>, you will see that it has already defined 
1196 C<has_many> and C<belongs_to> relationships on each side of our foreign 
1197 keys. For example, take a look at C<lib/MyApp/Schema/Result/Book.pm> and 
1198 notice the following code: 
1199
1200     =head1 RELATIONS
1201
1202     =head2 book_authors
1203
1204     Type: has_many
1205
1206     Related object: L<MyApp::Schema::Result::BookAuthor>
1207
1208     =cut
1209
1210     __PACKAGE__->has_many(
1211       "book_authors",
1212       "MyApp::Schema::Result::BookAuthor",
1213       { "foreign.book_id" => "self.id" },
1214     );
1215
1216 Each C<Book> "has_many" C<book_authors>, where C<BookAuthor> is
1217 the many-to-many table that allows each Book to have multiple
1218 Authors, and each Author to have mulitple books.  The arguments
1219 to C<has_many> are:
1220
1221 =over 4
1222
1223 =item *
1224
1225 C<book_authors> - The name for this relationship.  DBIC will create
1226 an accessor on the C<Books> DBIC Row object with this name.
1227
1228 =item *
1229
1230 C<MyApp::Schema::Result::BookAuthor> - The name of the DBIC model
1231 class referenced by this C<has_many> relationship.
1232
1233 =item *
1234
1235 C<foreign.book_id> - C<book_id> is the name of the foreign key 
1236 column in the I<foreign> table that points back to this table.
1237
1238 =item *
1239
1240 C<self.id> - C<id> is the name of the column in I<this> table
1241 that is referenced by the foreign key.
1242
1243 =back
1244
1245 See L<DBIx::Class::Relationship/has_many> for
1246 additional information.  Note that you might see a "hand coded"
1247 version of the C<has_many> relationship above expressed as:
1248
1249     __PACKAGE__->has_many(
1250       "book_authors",
1251       "MyApp::Schema::Result::BookAuthor",
1252       "book_id",
1253     );
1254
1255 Where the third argument is simply the name of the column in
1256 the foreign table.  However, the hashref syntax used by 
1257 L<DBIx::Class::Schema::Loader> is more flexible (for example,
1258 it can handle "multi-column" foreign keys).
1259
1260 B<Note:> If you are using older versions of SQLite and related DBIC 
1261 tools, you will need to manually define your C<has_many> and 
1262 C<belongs_to> relationships. We recommend upgrading to the versions 
1263 specified above. :-) 
1264
1265 Have a look at C<lib/MyApp/Schema/Result/BookAuthor.pm> and notice
1266 that there is a C<belongs_to> relationship defined that acts as the
1267 "mirror image" to the C<has_many> relationship we just looked at
1268 above:
1269
1270     =head1 RELATIONS
1271
1272     =head2 book
1273
1274     Type: belongs_to
1275
1276     Related object: L<MyApp::Schema::Result::Book>
1277
1278     =cut
1279
1280     __PACKAGE__->belongs_to(
1281       "book",
1282       "MyApp::Schema::Result::Book",
1283       { id => "book_id" },
1284       { join_type => "LEFT" },
1285     );
1286
1287 The arguments are similar, but see 
1288 L<DBIx::Class::Relationship/belongs_to> for the details.
1289
1290 Although recent versions of SQLite and L<DBIx::Class::Schema::Loader> 
1291 automatically handle the C<has_many> and C<belongs_to> relationships, 
1292 C<many_to_many> relationships currently need to be manually inserted. 
1293 To add a C<many_to_many> relationship, first edit 
1294 C<lib/MyApp/Schema/Result/Book.pm> and add the following text below 
1295 the C<# You can replace this text...> comment:
1296
1297     # many_to_many():
1298     #   args:
1299     #     1) Name of relationship, DBIC will create accessor with this name
1300     #     2) Name of has_many() relationship this many_to_many() is shortcut for
1301     #     3) Name of belongs_to() relationship in model class of has_many() above
1302     #   You must already have the has_many() defined to use a many_to_many().
1303     __PACKAGE__->many_to_many(authors => 'book_authors', 'author');
1304
1305 B<Note:> Be careful to put this code I<above> the C<1;> at the end of the
1306 file.  As with any Perl package, we need to end the last line with
1307 a statement that evaluates to C<true>.  This is customarily done with
1308 C<1;> on a line by itself.
1309
1310 The C<many_to_many> relationship is optional, but it makes it
1311 easier to map a book to its collection of authors.  Without 
1312 it, we would have to "walk" though the C<book_author> table as in 
1313 C<$book-E<gt>book_author-E<gt>first-E<gt>author-E<gt>last_name> (we 
1314 will see examples on how to use DBIx::Class objects in your code soon, 
1315 but note that because C<$book-E<gt>book_author> can return multiple 
1316 authors, we have to use C<first> to display a single author). 
1317 C<many_to_many> allows us to use the shorter 
1318 C<$book-E<gt>author-E<gt>first-E<gt>last_name>. Note that you cannot 
1319 define a C<many_to_many> relationship without also having the 
1320 C<has_many> relationship in place.
1321
1322 Then edit C<lib/MyApp/Schema/Result/Author.pm> and add the reverse 
1323 C<many_to_many> relationship for C<Author> as follows (again, be careful 
1324 to put in above the C<1;> but below the C<# DO NOT MODIFY THIS OR 
1325 ANYTHING ABOVE!> comment): 
1326
1327     # many_to_many():
1328     #   args:
1329     #     1) Name of relationship, DBIC will create accessor with this name
1330     #     2) Name of has_many() relationship this many_to_many() is shortcut for
1331     #     3) Name of belongs_to() relationship in model class of has_many() above
1332     #   You must already have the has_many() defined to use a many_to_many().
1333     __PACKAGE__->many_to_many(books => 'book_authors', 'book');
1334
1335
1336 =head2 Run The Application
1337
1338 Run the Catalyst development server script with the C<DBIC_TRACE> option
1339 (it might still be enabled from earlier in the tutorial, but here is an
1340 alternate way to specify the trace option just in case):
1341
1342     $ DBIC_TRACE=1 script/myapp_server.pl -r
1343
1344 Make sure that the application loads correctly and that you see the
1345 three dynamically created model class (one for each of the
1346 Result Classes we created).
1347
1348 Then hit the URL L<http://localhost:3000/books/list> with your browser 
1349 and be sure that the book list still displays correctly.
1350
1351 B<Note:> You will not see the authors yet because the view does not yet 
1352 use the new relations. Read on to the next section where we update the 
1353 template to do that.
1354
1355
1356 =head1 UPDATING THE VIEW
1357
1358 Let's add a new column to our book list page that takes advantage of 
1359 the relationship information we manually added to our schema files in 
1360 the previous section.  Edit C<root/src/books/list.tt2> and replace
1361 the "empty" table cell "<td></td>" with the following:
1362
1363     ...
1364     <td>
1365       [% # NOTE: See Chapter 4 for a better way to do this!                      -%]
1366       [% # First initialize a TT variable to hold a list.  Then use a TT FOREACH -%]
1367       [% # loop in 'side effect notation' to load just the last names of the     -%]
1368       [% # authors into the list. Note that the 'push' TT vmethod doesn't return -%]
1369       [% # a value, so nothing will be printed here.  But, if you have something -%]
1370       [% # in TT that does return a value and you don't want it printed, you     -%]
1371       [% # 1) assign it to a bogus value, or                                     -%]
1372       [% # 2) use the CALL keyword to call it and discard the return value.      -%]
1373       [% tt_authors = [ ];
1374          tt_authors.push(author.last_name) FOREACH author = book.authors %]
1375       [% # Now use a TT 'virtual method' to display the author count in parens   -%]
1376       [% # Note the use of the TT filter "| html" to escape dangerous characters -%]
1377       ([% tt_authors.size | html %])
1378       [% # Use another TT vmethod to join & print the names & comma separators   -%]
1379       [% tt_authors.join(', ') | html %]
1380     </td>
1381     ...
1382
1383 B<IMPORTANT NOTE:> Again, you should keep as much "logic code" as 
1384 possible out of your views.  This kind of logic belongs in your model 
1385 (the same goes for controllers -- keep them as "thin" as possible and 
1386 push all of the "complicated code" out to your model objects).  Avoid 
1387 code like you see in the previous example -- we are only using it here 
1388 to show some extra features in TT until we get to the more advanced 
1389 model features we will see in Chapter 4 (see 
1390 L<Catalyst::Manual::Tutorial::04_BasicCRUD/EXPLORING THE POWER OF DBIC>).
1391
1392 Then hit "Reload" in your browser (note that you don't need to reload 
1393 the development server or use the C<-r> option when updating TT 
1394 templates) and you should now see the number of authors each book has 
1395 along with a comma-separated list of the authors' last names.  (If you 
1396 didn't leave the development server running from the previous step, 
1397 you will obviously need to start it before you can refresh your 
1398 browser window.)
1399
1400 If you are still running the development server with C<DBIC_TRACE>
1401 enabled, you should also now see five more C<SELECT> statements in the
1402 debug output (one for each book as the authors are being retrieved by
1403 DBIx::Class):
1404
1405     SELECT me.id, me.title, me.rating FROM book me:
1406     SELECT author.id, author.first_name, author.last_name FROM book_author me  
1407     JOIN author author ON author.id = me.author_id WHERE ( me.book_id = ? ): '1'
1408     SELECT author.id, author.first_name, author.last_name FROM book_author me  
1409     JOIN author author ON author.id = me.author_id WHERE ( me.book_id = ? ): '2'
1410     SELECT author.id, author.first_name, author.last_name FROM book_author me  
1411     JOIN author author ON author.id = me.author_id WHERE ( me.book_id = ? ): '3'
1412     SELECT author.id, author.first_name, author.last_name FROM book_author me  
1413     JOIN author author ON author.id = me.author_id WHERE ( me.book_id = ? ): '4'
1414     SELECT author.id, author.first_name, author.last_name FROM book_author me  
1415     JOIN author author ON author.id = me.author_id WHERE ( me.book_id = ? ): '5'
1416
1417 Also note in C<root/src/books/list.tt2> that we are using "| html", a 
1418 type of TT filter, to escape characters such as E<lt> and E<gt> to &lt; 
1419 and &gt; and avoid various types of dangerous hacks against your 
1420 application.  In a real application, you would probably want to put 
1421 "| html" at the end of every field where a user has control over the 
1422 information that can appear in that field (and can therefore inject 
1423 markup or code if you don't "neutralize" those fields).  In addition to 
1424 "| html", Template Toolkit has a variety of other useful filters that 
1425 can found in the documentation for 
1426 L<Template::Filters|Template::Filters>.
1427
1428
1429 =head1 RUNNING THE APPLICATION FROM THE COMMAND LINE
1430
1431 In some situations, it can be useful to run your application and
1432 display a page without using a browser.  Catalyst lets you do this
1433 using the C<scripts/myapp_test.pl> script.  Just supply the URL you
1434 wish to display and it will run that request through the normal
1435 controller dispatch logic and use the appropriate view to render the
1436 output (obviously, complex pages may dump a lot of text to your
1437 terminal window).  For example, if you type:
1438
1439     $ script/myapp_test.pl "/books/list"
1440
1441 You should get the same text as if you visited
1442 L<http://localhost:3000/books/list> with the normal development server
1443 and asked your browser to view the page source.
1444
1445
1446 =head1 OPTIONAL INFORMATION
1447
1448 B<NOTE: The rest of this chapter of the tutorial is optional.  You can
1449 skip to Chapter 4, L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>,
1450 if you wish.>
1451
1452
1453 =head2 Using 'RenderView' for the Default View
1454
1455 Once your controller logic has processed the request from a user, it
1456 forwards processing to your view in order to generate the appropriate
1457 response output.  Catalyst uses
1458 L<Catalyst::Action::RenderView|Catalyst::Action::RenderView> by
1459 default to automatically perform this operation.  If you look in
1460 C<lib/MyApp/Controller/Root.pm>, you should see the empty
1461 definition for the C<sub end> method:
1462
1463     sub end : ActionClass('RenderView') {}
1464
1465 The following bullet points provide a quick overview of the
1466 C<RenderView> process:
1467
1468 =over 4
1469
1470 =item *
1471
1472 C<Root.pm> is designed to hold application-wide logic.
1473
1474 =item *
1475
1476 At the end of a given user request, Catalyst will call the most specific
1477 C<end> method that's appropriate.  For example, if the controller for a
1478 request has an C<end> method defined, it will be called.  However, if
1479 the controller does not define a controller-specific C<end> method, the
1480 "global" C<end> method in C<Root.pm> will be called.
1481
1482 =item *
1483
1484 Because the definition includes an C<ActionClass> attribute, the
1485 L<Catalyst::Action::RenderView|Catalyst::Action::RenderView> logic
1486 will be executed B<after> any code inside the definition of C<sub end>
1487 is run.  See L<Catalyst::Manual::Actions|Catalyst::Manual::Actions>
1488 for more information on C<ActionClass>.
1489
1490 =item *
1491
1492 Because C<sub end> is empty, this effectively just runs the default
1493 logic in C<RenderView>.  However, you can easily extend the
1494 C<RenderView> logic by adding your own code inside the empty method body
1495 (C<{}>) created by the Catalyst Helpers when we first ran the
1496 C<catalyst.pl> to initialize our application.  See
1497 L<Catalyst::Action::RenderView|Catalyst::Action::RenderView> for more
1498 detailed information on how to extend C<RenderView> in C<sub end>.
1499
1500 =back
1501
1502
1503 =head2 RenderView's "dump_info" Feature
1504
1505 One of the nice features of C<RenderView> is that it automatically 
1506 allows you to add C<dump_info=1> to the end of any URL for your 
1507 application and it will force the display of the "exception dump" 
1508 screen to the client browser.  You can try this out by pointing 
1509 your browser to this URL: 
1510
1511     http://localhost:3000/books/list?dump_info=1
1512
1513 You should get a page with the following message at the top:
1514
1515     Caught exception in MyApp::Controller::Root->end "Forced debug - 
1516     Scrubbed output at /usr/share/perl5/Catalyst/Action/RenderView.pm line 46."
1517
1518 Along with a summary of your application's state at the end of the 
1519 processing for that request.  The "Stash" section should show a 
1520 summarized version of the DBIC book model objects.  If desired, you 
1521 can adjust the summarization logic (called "scrubbing" logic) -- see 
1522 L<Catalyst::Action::RenderView|Catalyst::Action::RenderView> for 
1523 details.
1524
1525 Note that you shouldn't need to worry about "normal clients" using 
1526 this technique to "reverse engineer" your application -- C<RenderView> 
1527 only supports the C<dump_info=1> feature when your application is 
1528 running in C<-Debug> mode (something you won't do once you have your 
1529 application deployed in production).
1530
1531
1532 =head2 Using The Default Template Name
1533
1534 By default, C<Catalyst::View::TT> will look for a template that uses the
1535 same name as your controller action, allowing you to save the step of
1536 manually specifying the template name in each action.  For example, this
1537 would allow us to remove the
1538 C<$c-E<gt>stash-E<gt>{template} = 'books/list.tt2';> line of our
1539 C<list> action in the Books controller.  Open
1540 C<lib/MyApp/Controller/Books.pm> in your editor and comment out this line
1541 to match the following (only the C<$c-E<gt>stash-E<gt>{template}> line
1542 has changed):
1543
1544     =head2 list
1545     
1546     Fetch all book objects and pass to books/list.tt2 in stash to be displayed
1547     
1548     =cut
1549     
1550     sub list :Local {
1551         # Retrieve the usual Perl OO '$self' for this object. $c is the Catalyst
1552         # 'Context' that's used to 'glue together' the various components
1553         # that make up the application
1554         my ($self, $c) = @_;
1555     
1556         # Retrieve all of the book records as book model objects and store in the
1557         # stash where they can be accessed by the TT template
1558         $c->stash(books => [$c->model('DB::Book')->all]);
1559     
1560         # Set the TT template to use.  You will almost always want to do this
1561         # in your action methods (actions methods respond to user input in
1562         # your controllers).
1563         #$c->stash(template => 'books/list.tt2');
1564     }
1565
1566
1567 You should now be able to access the L<http://localhost:3000/books/list>
1568 URL as before.
1569
1570 B<NOTE:> Please note that if you use the default template technique,
1571 you will B<not> be able to use either the C<$c-E<gt>forward> or
1572 the C<$c-E<gt>detach> mechanisms (these are discussed in Chapter 2 and
1573 Chapter 9 of the Tutorial).
1574
1575 B<IMPORTANT:> Make sure that you do NOT skip the following section
1576 before continuing to the next chapter 4 Basic CRUD.
1577
1578
1579 =head2 Return To A Manually Specified Template
1580
1581 In order to be able to use C<$c-E<gt>forward> and C<$c-E<gt>detach>
1582 later in the tutorial, you should remove the comment from the
1583 statement in C<sub list> in C<lib/MyApp/Controller/Books.pm>:
1584
1585     $c->stash(template => 'books/list.tt2');
1586
1587 Then delete the C<TEMPLATE_EXTENSION> line in
1588 C<lib/MyApp/View/TT.pm>.
1589
1590 Check the L<http://localhost:3000/books/list> URL in your browser.
1591 It should look the same manner as with earlier sections.
1592
1593
1594 =head1 AUTHOR
1595
1596 Kennedy Clark, C<hkclark@gmail.com>
1597
1598 Please report any errors, issues or suggestions to the author.  The
1599 most recent version of the Catalyst Tutorial can be found at
1600 L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.80/trunk/lib/Catalyst/Manual/Tutorial/>.
1601
1602 Copyright 2006-2008, Kennedy Clark, under Creative Commons License
1603 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).