no need to set resultset_class with load_namespaces, and a couple other minor changes
[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / Tutorial / 02_CatalystBasics.pod
d442cc9f 1=head1 NAME
3ab6187c 3Catalyst::Manual::Tutorial::02_CatalystBasics - Catalyst Tutorial - Chapter 2: Catalyst Application Development Basics
d442cc9f 4
6=head1 OVERVIEW
4b4d3884 8This is B<Chapter 2 of 10> for the Catalyst tutorial.
d442cc9f 9
10L<Tutorial Overview|Catalyst::Manual::Tutorial>
12=over 4
14=item 1
3ab6187c 16L<Introduction|Catalyst::Manual::Tutorial::01_Intro>
d442cc9f 17
18=item 2
3ab6187c 20B<02_Catalyst Basics>
d442cc9f 21
22=item 3
3ab6187c 24L<More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>
d442cc9f 25
26=item 4
3ab6187c 28L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>
d442cc9f 29
30=item 5
3ab6187c 32L<Authentication|Catalyst::Manual::Tutorial::05_Authentication>
d442cc9f 33
34=item 6
3ab6187c 36L<Authorization|Catalyst::Manual::Tutorial::06_Authorization>
d442cc9f 37
38=item 7
3ab6187c 40L<Debugging|Catalyst::Manual::Tutorial::07_Debugging>
d442cc9f 41
42=item 8
3ab6187c 44L<Testing|Catalyst::Manual::Tutorial::08_Testing>
d442cc9f 45
46=item 9
3ab6187c 48L<Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
3533daff 49
50=item 10
3ab6187c 52L<Appendices|Catalyst::Manual::Tutorial::10_Appendices>
d442cc9f 53
4b4d3884 59In this chapter of the tutorial, we will create a very basic Catalyst
60web application, demonstrating a number of powerful capabilities, such
d442cc9f 62
63=over 4
65=item * Helper Scripts
67Catalyst helper scripts that can be used to rapidly bootstrap the
68skeletal structure of an application.
70=item * MVC
72Model/View/Controller (MVC) provides an architecture that facilitates a
73clean "separation of control" between the different portions of your
74application. Given that many other documents cover this subject in
75detail, MVC will not be discussed in depth here (for an excellent
76introduction to MVC and general Catalyst concepts, please see
865d3efb 77L<Catalyst::Manual::About|Catalyst::Manual::About>). In short:
d442cc9f 78
79=over 4
81=item * Model
83The model usually represents a data store. In most applications, the
84model equates to the objects that are created from and saved to your SQL
87=item * View
89The view takes model objects and renders them into something for the end
90user to look at. Normally this involves a template-generation tool that
91creates HTML for the user's web browser, but it could easily be code
865d3efb 92that generates other forms such as PDF documents, e-mails, spreadsheets,
93or even "behind the scenes" formats such as XML and JSON.
d442cc9f 94
95=item * Controller
97As suggested by its name, the controller takes user requests and routes
98them to the necessary model and view.
102=item * ORM
104The use of Object-Relational Mapping (ORM) technology for database
105access. Specifically, ORM provides an automated and standardized means
444d6b27 106to persist and restore objects to/from a relational database and will
107automatically create our Catalyst model for use with a database.
d442cc9f 108
111You can checkout the source code for this example from the catalyst
112subversion repository as per the instructions in
3ab6187c 113L<Catalyst::Manual::Tutorial::01_Intro|Catalyst::Manual::Tutorial::01_Intro>.
d442cc9f 114
3533daff 115
d442cc9f 116=head1 CREATE A CATALYST PROJECT
3533daff 118Catalyst provides a number of helper scripts that can be used to
119quickly flesh out the basic structure of your application. All
120Catalyst projects begin with the C<> helper (see
121L<Catalyst::Helper|Catalyst::Helper> for more information on helpers).
122Also note that as of Catalyst 5.7000, you will not have the helper
123scripts unless you install both L<Catalyst::Runtime|Catalyst::Runtime>
124and L<Catalyst::Devel|Catalyst::Devel>.
4b4d3884 126In this first chapter of the tutorial, use the Catalyst C<>
127script to initialize the framework for an application called C<Hello>:
3533daff 128
129 $ Hello
130 created "Hello"
131 created "Hello/script"
132 created "Hello/lib"
133 created "Hello/root"
d442cc9f 134 ...
3533daff 135 created "Hello/script/"
444d6b27 136 Change to application directory and Run "perl Makefile.PL" to make sure your install is complete
3533daff 137 $ cd Hello
d442cc9f 138
444d6b27 139Note: If you are using Strawberry Perl on Win32, drop the ".pl"
140from the end of the "" command and simply use
141"catalyst Hello".
d442cc9f 143The C<> helper script will display the names of the
3533daff 144directories and files it creates:
146 Changes # Record of application changes
865d3efb 147 lib # Lib directory for your app's Perl modules
148 Hello # Application main code directory
3533daff 149 Controller # Directory for Controller modules
150 Model # Directory for Models
151 View # Directory for Views
152 # Base application module
153 Makefile.PL # Makefile to build application
45d511e0 154 hello.conf # Application configuration file
3533daff 155 README # README file
156 root # Equiv of htdocs, dir for templates, css, javascript
157 favicon.ico
158 static # Directory for static files
159 images # Directory for image files used in welcome screen
160 script # Directory for Perl scripts
161 # To run your app as a cgi (not recommended)
162 # To create models, views, controllers
163 # To run app as a fastcgi program
164 # The normal development server
165 # Test your app from the command line
166 t # Directory for tests
167 01app.t # Test scaffold
168 02pod.t
169 03podcoverage.t
172Catalyst will "auto-discover" modules in the Controller, Model, and
173View directories. When you use the script it will
174create Perl module scaffolds in those directories, plus test files in
175the "t" directory. The default location for templates is in the "root"
176directory. The scripts in the script directory will always start with
177the lowercased version of your application name. If your app is
178MaiTai, then the create script would be "".
180Though it's too early for any significant celebration, we already have
181a functioning application. We can use the Catalyst supplied script to
182start up a development server and view the default Catalyst page in
183your browser. All scripts in the script directory should be run from
184the base directory of your application, so change to the Hello
187Run the following command to start up the built-in development web
acbd7bdd 188server (make sure you didn't forget the "C<cd Hello>" from the
189previous step):
d442cc9f 190
0f1ac65e 191B<Note>: the -r enables reloading on code changes so you don't have to stop and
192start the server when you update code. see perldoc script/ for
193more useful options.
195 $ script/ -r
d442cc9f 196 [debug] Debug messages enabled
865d3efb 197 [debug] Statistics enabled
d442cc9f 198 [debug] Loaded plugins:
199 .----------------------------------------------------------------------------.
f34d7f62 200 | Catalyst::Plugin::ConfigLoader 0.27 |
d442cc9f 201 '----------------------------------------------------------------------------'
203 [debug] Loaded dispatcher "Catalyst::Dispatcher"
204 [debug] Loaded engine "Catalyst::Engine::HTTP"
3533daff 205 [debug] Found home "/home/me/Hello"
e13f83cc 206 [debug] Loaded Config "/home/me/Hello/hello.conf"
d442cc9f 207 [debug] Loaded components:
208 .-----------------------------------------------------------------+----------.
209 | Class | Type |
210 +-----------------------------------------------------------------+----------+
3533daff 211 | Hello::Controller::Root | instance |
d442cc9f 212 '-----------------------------------------------------------------+----------'
214 [debug] Loaded Private actions:
215 .----------------------+--------------------------------------+--------------.
216 | Private | Class | Method |
217 +----------------------+--------------------------------------+--------------+
3533daff 218 | /default | Hello::Controller::Root | default |
219 | /end | Hello::Controller::Root | end |
acbd7bdd 220 | /index | Hello::Controller::Root | index |
d442cc9f 221 '----------------------+--------------------------------------+--------------'
865d3efb 223 [debug] Loaded Path actions:
224 .-------------------------------------+--------------------------------------.
225 | Path | Private |
226 +-------------------------------------+--------------------------------------+
865d3efb 227 | / | /index |
08ae25e9 228 | / | /default |
865d3efb 229 '-------------------------------------+--------------------------------------'
acbd7bdd 230
08ae25e9 231 [info] Hello powered by Catalyst 5.80018
acbd7bdd 232 You can connect to your server at http://debian:3000
d442cc9f 233
1435672d 234Point your web browser to L<http://localhost:3000> (substituting a
d442cc9f 235different hostname or IP address as appropriate) and you should be
acbd7bdd 236greeted by the Catalyst welcome screen (if you get some other welcome
237screen or an "Index" screen, you probably forgot to specify port 3000
238in your URL). Information similar to the following should be appended
239to the logging output of the development server:
3dfcf16a 241 [info] *** Request 1 (0.001/s) [23194] [Sat Jan 16 11:09:18 2010] ***
242 [debug] "GET" request for "/" from ""
243 [debug] Path is "/"
244 [info] Request took 0.004851s (206.143/s)
245 .------------------------------------------------------------+-----------.
246 | Action | Time |
247 +------------------------------------------------------------+-----------+
248 | /index | 0.000395s |
249 | /end | 0.000425s |
250 '------------------------------------------------------------+-----------'
d442cc9f 251
9b531c13 252B<Note>: Press Ctrl-C to break out of the development server if necessary.
d442cc9f 253
3533daff 255=head1 HELLO WORLD
d442cc9f 256
3533daff 257=head2 The Simplest Way
d442cc9f 258
3533daff 259The controller is a place to put global actions that usually
260execute on the root URL. Open the C<lib/Hello/Controller/> file in
865d3efb 261your editor. You will see the "index" subroutine, which is
3533daff 262responsible for displaying the welcome screen that you just saw in
263your browser. Later on you'll want to change that to something more
865d3efb 264reasonable, such as a "404" message or a redirect, but for now just
265leave it alone.
d442cc9f 266
865d3efb 267 sub index :Path :Args(0) {
3533daff 268 my ( $self, $c ) = @_;
865d3efb 269
270 # Hello World
3533daff 271 $c->response->body( $c->welcome_message );
d442cc9f 272 }
3533daff 274The "C<$c>" here refers to the Catalyst context, which is used to
275access the Catalyst application. In addition to many other things,
276the Catalyst context provides access to "response" and "request"
d0496197 277objects. (See L<Catalyst|Catalyst>,
278L<Catalyst::Response|Catalyst::Response>, and
d442cc9f 280
14e5ed66 281C<$c-E<gt>response-E<gt>body> sets the HTTP response (see
282L<Catalyst::Response|Catalyst::Response>), while C<$c-E<gt>welcome_message>
d0496197 283is a special method that returns the welcome message that you saw in
284your browser.
d442cc9f 285
444d6b27 286The ":Path :Args(0)" after the method name are attributes which
287determine which URLs will be dispatched to this method. (You might see
288":Private" if you are using an older version of Catalyst, but using
289that with 'default' or 'index' is currently deprecated. If so, you
290should also probably upgrade before continuing the tutorial.)
d442cc9f 291
3533daff 292Some MVC frameworks handle dispatching in a central place. Catalyst,
293by policy, prefers to handle URL dispatching with attributes on
294controller methods. There is a lot of flexibility in specifying which
295URLs to match. This particular method will match all URLs, because it
865d3efb 296doesn't specify the path (nothing comes after "Path"), but will only
444d6b27 297accept a URL without any args because of the ":Args(0)".
d442cc9f 298
444d6b27 299The default is to map URLs to controller names, and because of the way
300that Perl handles namespaces through package names, it is simple to
301create hierarchical structures in Catalyst. This means that you can
302create controllers with deeply nested actions in a clean and logical
303way. For example, the URL C<>
304maps to the package C<Hello::Controller::Admin::Articles>, and the
305C<create> method.
d442cc9f 306
d0496197 307Add the following subroutine to your C<lib/Hello/Controller/>
d442cc9f 309
3d0b2e0b 310 sub hello :Global {
3533daff 311 my ( $self, $c ) = @_;
d0496197 312
3533daff 313 $c->response->body("Hello, World!");
314 }
d442cc9f 315
acbd7bdd 316B<TIP>: See Appendix 1 for tips on removing the leading spaces when
317cutting and pasting example code from POD-based documents.
3533daff 319Here you're sending your own string to the webpage.
e7cfb0cc 321Save the file, and you should notice the following in your server output:
3533daff 322
e7cfb0cc 323 Saw changes to the following files:
324 - /srv/http/xenoterracide/Catalyst/Hello/lib/Hello/Controller/ (modify)
326 Attempting to restart the server
327 ...
328 [debug] Loaded Private actions:
329 .----------------------+--------------------------------------+--------------.
330 | Private | Class | Method |
331 +----------------------+--------------------------------------+--------------+
332 | /default | Hello::Controller::Root | default |
333 | /end | Hello::Controller::Root | end |
334 | /index | Hello::Controller::Root | index |
335 | /hello | Hello::Controller::Root | hello |
336 '----------------------+--------------------------------------+--------------'
338 [debug] Loaded Path actions:
339 .-------------------------------------+--------------------------------------.
340 | Path | Private |
341 +-------------------------------------+--------------------------------------+
342 | / | /index |
343 | / | /default |
344 | /hello | /hello |
345 '-------------------------------------+--------------------------------------'
346 ...
348Go to L<http://localhost:3000/hello> to see "Hello, World!".
865d3efb 349
3533daff 350=head2 Hello, World! Using a View and a Template
444d6b27 352In the Catalyst world a "View" itself is not a page of XHTML or a
353template designed to present a page to a browser. Rather, it is the
354module that determines the I<type> of view -- HTML, pdf, XML, etc. For
355the thing that generates the I<content> of that view (such as the a
356Toolkit Template template file), the actual templates go under the
865d3efb 357"root" directory.
3533daff 358
359To create a TT view, run:
361 $ script/ view TT TT
363This creates the C<lib/Hello/View/> module, which is a subclass of
1435672d 364C<Catalyst::View::TT>.
366=over 4
368=item *
370The "view" keyword tells the create script that you are creating a view.
372=item *
374The first "TT" tells the script to name the View module "", which is a
375commonly used name for TT views. (You can name it anything you want, such as
378=item *
444d6b27 380The final "TT" tells Catalyst the I<type> of the view, with "TT"
381indicating that you want to a Template Toolkit view.
1435672d 382
444d6b27 385If you look at C<lib/Hello/View/> you will find that it only
386contains a config statement to set the TT extension to ".tt".
3533daff 387
388Now that the "View" exists, Catalyst will autodiscover it and be
444d6b27 389able to use it to display the view templates using the "process"
3533daff 390method that it inherits from the C<Catalyst::View::TT class>.
c010ae0d 392Template Toolkit is a very full featured template facility, with
865d3efb 393excellent documentation at L<>,
3533daff 394but since this is not a TT tutorial, we'll stick to only basic TT
395usage here (and explore some of the more common TT features in later
4b4d3884 396chapters of the tutorial).
3533daff 397
398Create a C<root/> template file (put it in the C<root> under
399the C<Hello> directory that is the base of your application). Here is
400a simple sample:
3533daff 402 <p>
1435672d 403 This is a TT view template, called '[% %]'.
3533daff 404 </p>
406[% and %] are markers for the TT parts of the template. Inside you can
1435672d 407access Perl variables and classes, and use TT directives. In this
408case, we're using a special TT variable that defines the name of the
409template file (C<>). The rest of the template is normal HTML.
411Change the hello method in C<lib/Hello/Controller/> to the
3533daff 413
3d0b2e0b 414 sub hello :Global {
3533daff 415 my ( $self, $c ) = @_;
d0496197 416
61cb69fd 417 $c->stash(template => '');
3533daff 418 }
d442cc9f 419
444d6b27 420This time, instead of doing C<$c-E<gt>response-E<gt>body()>, you are
421setting the value of the "template" hash key in the Catalyst "stash",
422an area for putting information to share with other parts of your
423application. The "template" key determines which template will be
424displayed at the end of the request cycle. Catalyst controllers have a
425default "end" action for all methods which causes the first (or
426default) view to be rendered (unless there's a C<$c-E<gt>response-
427E<gt>body()> statement). So your template will be magically displayed
428at the end of your method.
d442cc9f 429
d442cc9f 431
3533daff 432Create a controller named "Site" by executing the create script:
d442cc9f 433
3533daff 434 $ script/ controller Site
d442cc9f 435
3533daff 436This will create a C<lib/Hello/Controller/> file (and a test
437file). Bring up in your editor, and you can see that there's
444d6b27 438not much there.
d442cc9f 439
d0496197 440In C<lib/Hello/Controller/>, add the following method:
d442cc9f 441
3d0b2e0b 442 sub test :Local {
3533daff 443 my ( $self, $c ) = @_;
d0496197 444
3533daff 445 $c->stash->{username} = "John";
446 $c->stash->{template} = 'site/';
d442cc9f 447 }
1435672d 449Notice the "Local" attribute on the C<test> method. This will cause
444d6b27 450the C<test> action (now that we have assigned an "action type" to the
451method it appears as a "controller action" to Catalyst) to be executed
1435672d 452on the "controller/method" URL, or, in this case, "site/test". We
453will see additional information on controller actions throughout the
454rest of the tutorial, but if you are curious take a look at
457It's not actually necessary to set the template value as we do here.
458By default TT will attempt to render a template that follows the
459naming pattern "controller/", and we're following that
460pattern here. However, in other situations you will need to specify
461the template (such as if you've "forwarded" to the method, or if it
462doesn't follow the default naming convention).
464We've also put the variable "username" into the stash, for use in the
d442cc9f 466
3533daff 467Make a subdirectory "site" in the "root" directory. Copy the
d0496197 468file into the directory as C<root/site/>, or create a new
469template file at that location. Include a line like:
d442cc9f 470
d0496197 471 <p>Hello, [% username %]!</p>
d442cc9f 472
3533daff 473You should see your file displayed, including the name "John"
474that you set in the controller.
d442cc9f 475
d442cc9f 476
3533daff 477=head1 AUTHORS
d442cc9f 478
3533daff 479Gerda Shank, C<>
d442cc9f 480Kennedy Clark, C<>
482Please report any errors, issues or suggestions to the author. The
483most recent version of the Catalyst Tutorial can be found at
59884771 484L<>.
d442cc9f 485
45c7830f 486Copyright 2006-2008, Kennedy Clark & Gerda Shank, under Creative Commons License
865d3efb 487(L<>).