make attribute list syntax consistant
[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
3533daff 191 $ script/
d442cc9f 192 [debug] Debug messages enabled
865d3efb 193 [debug] Statistics enabled
d442cc9f 194 [debug] Loaded plugins:
195 .----------------------------------------------------------------------------.
f34d7f62 196 | Catalyst::Plugin::ConfigLoader 0.27 |
197 | Catalyst::Plugin::Static::Simple 0.25 |
d442cc9f 198 '----------------------------------------------------------------------------'
200 [debug] Loaded dispatcher "Catalyst::Dispatcher"
201 [debug] Loaded engine "Catalyst::Engine::HTTP"
3533daff 202 [debug] Found home "/home/me/Hello"
e13f83cc 203 [debug] Loaded Config "/home/me/Hello/hello.conf"
d442cc9f 204 [debug] Loaded components:
205 .-----------------------------------------------------------------+----------.
206 | Class | Type |
207 +-----------------------------------------------------------------+----------+
3533daff 208 | Hello::Controller::Root | instance |
d442cc9f 209 '-----------------------------------------------------------------+----------'
211 [debug] Loaded Private actions:
212 .----------------------+--------------------------------------+--------------.
213 | Private | Class | Method |
214 +----------------------+--------------------------------------+--------------+
3533daff 215 | /default | Hello::Controller::Root | default |
216 | /end | Hello::Controller::Root | end |
acbd7bdd 217 | /index | Hello::Controller::Root | index |
d442cc9f 218 '----------------------+--------------------------------------+--------------'
865d3efb 220 [debug] Loaded Path actions:
221 .-------------------------------------+--------------------------------------.
222 | Path | Private |
223 +-------------------------------------+--------------------------------------+
224 | / | /default |
225 | / | /index |
226 '-------------------------------------+--------------------------------------'
acbd7bdd 227
444d6b27 228 [info] Hello powered by Catalyst 5.80013
acbd7bdd 229 You can connect to your server at http://debian:3000
d442cc9f 230
1435672d 231Point your web browser to L<http://localhost:3000> (substituting a
d442cc9f 232different hostname or IP address as appropriate) and you should be
acbd7bdd 233greeted by the Catalyst welcome screen (if you get some other welcome
234screen or an "Index" screen, you probably forgot to specify port 3000
235in your URL). Information similar to the following should be appended
236to the logging output of the development server:
444d6b27 238 [info] *** Request 1 (0.005/s) [20712] [Sun Oct 11 11:58:51 2009] ***
239 [debug] "GET" request for "/" from ""
acbd7bdd 240 [info] Request took 0.007342s (136.203/s)
d442cc9f 241 .----------------------------------------------------------------+-----------.
242 | Action | Time |
243 +----------------------------------------------------------------+-----------+
acbd7bdd 244 | /index | 0.000491s |
245 | /end | 0.000595s |
d442cc9f 246 '----------------------------------------------------------------+-----------'
248Press Ctrl-C to break out of the development server.
3533daff 251=head1 HELLO WORLD
d442cc9f 252
3533daff 253=head2 The Simplest Way
d442cc9f 254
3533daff 255The controller is a place to put global actions that usually
256execute on the root URL. Open the C<lib/Hello/Controller/> file in
865d3efb 257your editor. You will see the "index" subroutine, which is
3533daff 258responsible for displaying the welcome screen that you just saw in
259your browser. Later on you'll want to change that to something more
865d3efb 260reasonable, such as a "404" message or a redirect, but for now just
261leave it alone.
d442cc9f 262
865d3efb 263 sub index :Path :Args(0) {
3533daff 264 my ( $self, $c ) = @_;
865d3efb 265
266 # Hello World
3533daff 267 $c->response->body( $c->welcome_message );
d442cc9f 268 }
3533daff 270The "C<$c>" here refers to the Catalyst context, which is used to
271access the Catalyst application. In addition to many other things,
272the Catalyst context provides access to "response" and "request"
d0496197 273objects. (See L<Catalyst|Catalyst>,
274L<Catalyst::Response|Catalyst::Response>, and
d442cc9f 276
14e5ed66 277C<$c-E<gt>response-E<gt>body> sets the HTTP response (see
278L<Catalyst::Response|Catalyst::Response>), while C<$c-E<gt>welcome_message>
d0496197 279is a special method that returns the welcome message that you saw in
280your browser.
d442cc9f 281
444d6b27 282The ":Path :Args(0)" after the method name are attributes which
283determine which URLs will be dispatched to this method. (You might see
284":Private" if you are using an older version of Catalyst, but using
285that with 'default' or 'index' is currently deprecated. If so, you
286should also probably upgrade before continuing the tutorial.)
d442cc9f 287
3533daff 288Some MVC frameworks handle dispatching in a central place. Catalyst,
289by policy, prefers to handle URL dispatching with attributes on
290controller methods. There is a lot of flexibility in specifying which
291URLs to match. This particular method will match all URLs, because it
865d3efb 292doesn't specify the path (nothing comes after "Path"), but will only
444d6b27 293accept a URL without any args because of the ":Args(0)".
d442cc9f 294
444d6b27 295The default is to map URLs to controller names, and because of the way
296that Perl handles namespaces through package names, it is simple to
297create hierarchical structures in Catalyst. This means that you can
298create controllers with deeply nested actions in a clean and logical
299way. For example, the URL C<>
300maps to the package C<Hello::Controller::Admin::Articles>, and the
301C<create> method.
d442cc9f 302
d0496197 303Add the following subroutine to your C<lib/Hello/Controller/>
d442cc9f 305
3d0b2e0b 306 sub hello :Global {
3533daff 307 my ( $self, $c ) = @_;
d0496197 308
3533daff 309 $c->response->body("Hello, World!");
310 }
d442cc9f 311
acbd7bdd 312B<TIP>: See Appendix 1 for tips on removing the leading spaces when
313cutting and pasting example code from POD-based documents.
3533daff 315Here you're sending your own string to the webpage.
317Save the file, start the server (stop and restart it if it's still
444d6b27 318running), and go to L<http://localhost:3000/hello> to
319see "Hello, World!" Also notice that a new action is listed under
320"Loaded Private actions" in the development server debug output.
3533daff 321
865d3efb 322
3533daff 323=head2 Hello, World! Using a View and a Template
444d6b27 325In the Catalyst world a "View" itself is not a page of XHTML or a
326template designed to present a page to a browser. Rather, it is the
327module that determines the I<type> of view -- HTML, pdf, XML, etc. For
328the thing that generates the I<content> of that view (such as the a
329Toolkit Template template file), the actual templates go under the
865d3efb 330"root" directory.
3533daff 331
332To create a TT view, run:
334 $ script/ view TT TT
336This creates the C<lib/Hello/View/> module, which is a subclass of
1435672d 337C<Catalyst::View::TT>.
339=over 4
341=item *
343The "view" keyword tells the create script that you are creating a view.
345=item *
347The first "TT" tells the script to name the View module "", which is a
348commonly used name for TT views. (You can name it anything you want, such as
351=item *
444d6b27 353The final "TT" tells Catalyst the I<type> of the view, with "TT"
354indicating that you want to a Template Toolkit view.
1435672d 355
444d6b27 358If you look at C<lib/Hello/View/> you will find that it only
359contains a config statement to set the TT extension to ".tt".
3533daff 360
361Now that the "View" exists, Catalyst will autodiscover it and be
444d6b27 362able to use it to display the view templates using the "process"
3533daff 363method that it inherits from the C<Catalyst::View::TT class>.
c010ae0d 365Template Toolkit is a very full featured template facility, with
865d3efb 366excellent documentation at L<>,
3533daff 367but since this is not a TT tutorial, we'll stick to only basic TT
368usage here (and explore some of the more common TT features in later
4b4d3884 369chapters of the tutorial).
3533daff 370
371Create a C<root/> template file (put it in the C<root> under
372the C<Hello> directory that is the base of your application). Here is
373a simple sample:
3533daff 375 <p>
1435672d 376 This is a TT view template, called '[% %]'.
3533daff 377 </p>
379[% and %] are markers for the TT parts of the template. Inside you can
1435672d 380access Perl variables and classes, and use TT directives. In this
381case, we're using a special TT variable that defines the name of the
382template file (C<>). The rest of the template is normal HTML.
384Change the hello method in C<lib/Hello/Controller/> to the
3533daff 386
3d0b2e0b 387 sub hello :Global {
3533daff 388 my ( $self, $c ) = @_;
d0496197 389
3533daff 390 $c->stash->{template} = '';
391 }
d442cc9f 392
444d6b27 393This time, instead of doing C<$c-E<gt>response-E<gt>body()>, you are
394setting the value of the "template" hash key in the Catalyst "stash",
395an area for putting information to share with other parts of your
396application. The "template" key determines which template will be
397displayed at the end of the request cycle. Catalyst controllers have a
398default "end" action for all methods which causes the first (or
399default) view to be rendered (unless there's a C<$c-E<gt>response-
400E<gt>body()> statement). So your template will be magically displayed
401at the end of your method.
d442cc9f 402
3533daff 403After saving the file, restart the development server, and look at
d0496197 404L<http://localhost:3000/hello> again. You should
3533daff 405see the template that you just made.
d442cc9f 406
d442cc9f 407
d442cc9f 409
3533daff 410Create a controller named "Site" by executing the create script:
d442cc9f 411
3533daff 412 $ script/ controller Site
d442cc9f 413
3533daff 414This will create a C<lib/Hello/Controller/> file (and a test
415file). Bring up in your editor, and you can see that there's
444d6b27 416not much there.
d442cc9f 417
d0496197 418In C<lib/Hello/Controller/>, add the following method:
d442cc9f 419
3d0b2e0b 420 sub test :Local {
3533daff 421 my ( $self, $c ) = @_;
d0496197 422
3533daff 423 $c->stash->{username} = "John";
424 $c->stash->{template} = 'site/';
d442cc9f 425 }
1435672d 427Notice the "Local" attribute on the C<test> method. This will cause
444d6b27 428the C<test> action (now that we have assigned an "action type" to the
429method it appears as a "controller action" to Catalyst) to be executed
1435672d 430on the "controller/method" URL, or, in this case, "site/test". We
431will see additional information on controller actions throughout the
432rest of the tutorial, but if you are curious take a look at
435It's not actually necessary to set the template value as we do here.
436By default TT will attempt to render a template that follows the
437naming pattern "controller/", and we're following that
438pattern here. However, in other situations you will need to specify
439the template (such as if you've "forwarded" to the method, or if it
440doesn't follow the default naming convention).
442We've also put the variable "username" into the stash, for use in the
d442cc9f 444
3533daff 445Make a subdirectory "site" in the "root" directory. Copy the
d0496197 446file into the directory as C<root/site/>, or create a new
447template file at that location. Include a line like:
d442cc9f 448
d0496197 449 <p>Hello, [% username %]!</p>
d442cc9f 450
3533daff 451Bring up or restart the server. Notice in the server output that
452C</site/test> is listed in the Loaded Path actions. Go to
865d3efb 453L<http://localhost:3000/site/test> in your browser.
d442cc9f 454
3533daff 455You should see your file displayed, including the name "John"
456that you set in the controller.
d442cc9f 457
d442cc9f 458
3533daff 459=head1 AUTHORS
d442cc9f 460
3533daff 461Gerda Shank, C<>
d442cc9f 462Kennedy Clark, C<>
464Please report any errors, issues or suggestions to the author. The
465most recent version of the Catalyst Tutorial can be found at
59884771 466L<>.
d442cc9f 467
45c7830f 468Copyright 2006-2008, Kennedy Clark & Gerda Shank, under Creative Commons License
865d3efb 469(L<>).