lib/Catalyst/Manual/Tutorial/CatalystBasics.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::Tutorial::CatalystBasics - Catalyst Tutorial - Part 2: Catalyst Application Development Basics
   4
   5
   6 =head1 OVERVIEW
   7
   8 This is B<Part 2 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::Intro>
  17
  18 =item 2
  19
  20 B<Catalyst Basics>
  21
  22 =item 3
  23
  24 L<More Catalyst Basics|Catalyst::Manual::Tutorial::MoreCatalystBasics>
  25
  26 =item 4
  27
  28 L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
  29
  30 =item 5
  31
  32 L<Authentication|Catalyst::Manual::Tutorial::Authentication>
  33
  34 =item 6
  35
  36 L<Authorization|Catalyst::Manual::Tutorial::Authorization>
  37
  38 =item 7
  39
  40 L<Debugging|Catalyst::Manual::Tutorial::Debugging>
  41
  42 =item 8
  43
  44 L<Testing|Catalyst::Manual::Tutorial::Testing>
  45
  46 =item 9
  47
  48 L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
  49
  50 =item 10
  51
  52 L<Appendices|Catalyst::Manual::Tutorial::Appendices>
  53
  54 =back
  55
  56
  57 =head1 DESCRIPTION
  58
  59 In this part of the tutorial, we will create a very basic Catalyst web
  60 application, demonstrating a number of powerful capabilities, such as:
  61
  62 =over 4
  63
  64 =item * Helper Scripts
  65
  66 Catalyst helper scripts that can be used to rapidly bootstrap the
  67 skeletal structure of an application.
  68
  69 =item * MVC
  70
  71 Model/View/Controller (MVC) provides an architecture that facilitates a
  72 clean "separation of control" between the different portions of your
  73 application. Given that many other documents cover this subject in
  74 detail, MVC will not be discussed in depth here (for an excellent
  75 introduction to MVC and general Catalyst concepts, please see
  76 L<Catalyst::Manual::About|Catalyst::Manual::About>). In short:
  77
  78 =over 4
  79
  80 =item * Model
  81
  82 The model usually represents a data store. In most applications, the
  83 model equates to the objects that are created from and saved to your SQL
  84 database.
  85
  86 =item * View
  87
  88 The view takes model objects and renders them into something for the end
  89 user to look at. Normally this involves a template-generation tool that
  90 creates HTML for the user's web browser, but it could easily be code
  91 that generates other forms such as PDF documents, e-mails, spreadsheets,
  92 or even "behind the scenes" formats such as XML and JSON.
  93
  94 =item * Controller
  95
  96 As suggested by its name, the controller takes user requests and routes
  97 them to the necessary model and view.
  98
  99 =back
 100
 101 =item * ORM
 102
 103 The use of Object-Relational Mapping (ORM) technology for database
 104 access. Specifically, ORM provides an automated and standardized means
 105 to persist and restore objects to/from a relational database.
 106
 107 =back
 108
 109 You can checkout the source code for this example from the catalyst
 110 subversion repository as per the instructions in
 111 L<Catalyst::Manual::Tutorial::Intro|Catalyst::Manual::Tutorial::Intro>.
 112
 113
 114 =head1 CREATE A CATALYST PROJECT
 115
 116 Catalyst provides a number of helper scripts that can be used to
 117 quickly flesh out the basic structure of your application. All
 118 Catalyst projects begin with the C<catalyst.pl> helper (see
 119 L<Catalyst::Helper|Catalyst::Helper> for more information on helpers).
 120 Also note that as of Catalyst 5.7000, you will not have the helper
 121 scripts unless you install both L<Catalyst::Runtime|Catalyst::Runtime>
 122 and L<Catalyst::Devel|Catalyst::Devel>.
 123
 124 In this first part of the tutorial, use the Catalyst
 125 C<catalyst.pl> script to initialize the framework for an
 126 application called C<Hello>:
 127
 128     $ catalyst.pl Hello
 129     created "Hello"
 130     created "Hello/script"
 131     created "Hello/lib"
 132     created "Hello/root"
 133     ...
 134     created "Hello/script/hello_create.pl"
 135     $ cd Hello
 136
 137 The C<catalyst.pl> helper script will display the names of the
 138 directories and files it creates:
 139
 140     Changes               # Record of application changes
 141     lib                   # Lib directory for your app's Perl modules
 142         Hello             # Application main code directory
 143             Controller    # Directory for Controller modules
 144             Model         # Directory for Models
 145             View          # Directory for Views
 146         Hello.pm          # Base application module
 147     Makefile.PL           # Makefile to build application
 148     hello.conf            # Application configuration file
 149     README                # README file
 150     root                  # Equiv of htdocs, dir for templates, css, javascript
 151         favicon.ico
 152         static            # Directory for static files
 153             images        # Directory for image files used in welcome screen
 154     script                # Directory for Perl scripts
 155         hello_cgi.pl      # To run your app as a cgi (not recommended)
 156         hello_create.pl   # To create models, views, controllers
 157         hello_fastcgi.pl  # To run app as a fastcgi program
 158         hello_server.pl   # The normal development server
 159         hello_test.pl     # Test your app from the command line
 160     t                     # Directory for tests
 161         01app.t           # Test scaffold
 162         02pod.t
 163         03podcoverage.t
 164
 165
 166 Catalyst will "auto-discover" modules in the Controller, Model, and
 167 View directories. When you use the hello_create.pl script it will
 168 create Perl module scaffolds in those directories, plus test files in
 169 the "t" directory. The default location for templates is in the "root"
 170 directory. The scripts in the script directory will always start with
 171 the lowercased version of your application name. If your app is
 172 MaiTai, then the create script would be "maitai_create.pl".
 173
 174 Though it's too early for any significant celebration, we already have
 175 a functioning application. We can use the Catalyst supplied script to
 176 start up a development server and view the default Catalyst page in
 177 your browser. All scripts in the script directory should be run from
 178 the base directory of your application, so change to the Hello
 179 directory.
 180
 181 Run the following command to start up the built-in development web
 182 server:
 183
 184     $ script/hello_server.pl
 185     [debug] Debug messages enabled
 186     [debug] Statistics enabled
 187     [debug] Loaded plugins:
 188     .----------------------------------------------------------------------------.
 189     | Catalyst::Plugin::ConfigLoader  0.20                                       |
 190     | Catalyst::Plugin::Static::Simple  0.20                                     |
 191     '----------------------------------------------------------------------------'
 192
 193     [debug] Loaded dispatcher "Catalyst::Dispatcher"
 194     [debug] Loaded engine "Catalyst::Engine::HTTP"
 195     [debug] Found home "/home/me/Hello"
 196     [debug] Loaded Config "/home/me/Hello/hello.conf"
 197     [debug] Loaded components:
 198     .-----------------------------------------------------------------+----------.
 199     | Class                                                           | Type     |
 200     +-----------------------------------------------------------------+----------+
 201     | Hello::Controller::Root                                         | instance |
 202     '-----------------------------------------------------------------+----------'
 203
 204     [debug] Loaded Private actions:
 205     .----------------------+--------------------------------------+--------------.
 206     | Private              | Class                                | Method       |
 207     +----------------------+--------------------------------------+--------------+
 208     | /default             | Hello::Controller::Root              | default      |
 209     | /end                 | Hello::Controller::Root              | end          |
 210     '----------------------+--------------------------------------+--------------'
 211
 212     [debug] Loaded Path actions:
 213     .-------------------------------------+--------------------------------------.
 214     | Path                                | Private                              |
 215     +-------------------------------------+--------------------------------------+
 216     | /                                   | /default                             |
 217     | /                                   | /index                               |
 218     '-------------------------------------+--------------------------------------'
 219
 220     [info] Hello powered by Catalyst 5.7014
 221     You can connect to your server at http://localhost:3000
 222
 223 Point your web browser to
 224 L<http://localhost:3000|http://localhost:3000> (substituting a
 225 different hostname or IP address as appropriate) and you should be
 226 greeted by the Catalyst welcome screen.  Information similar to the
 227 following should be appended to the logging output of the development
 228 server:
 229
 230     [info] *** Request 1 (1.000/s) [10301] [Sun Nov 23 10:11:36 2008] ***
 231     [debug] "GET" request for "/" from "127.0.0.1"
 232     [info] Request took 0.017964s (55.667/s)
 233     .----------------------------------------------------------------+-----------.
 234     | Action                                                         | Time      |
 235     +----------------------------------------------------------------+-----------+
 236     | /default                                                       | 0.000540s |
 237     | /end                                                           | 0.001246s |
 238     '----------------------------------------------------------------+-----------'
 239
 240 Press Ctrl-C to break out of the development server.
 241
 242
 243 =head1 HELLO WORLD
 244
 245 =head2 The Simplest Way
 246
 247 The Root.pm controller is a place to put global actions that usually
 248 execute on the root URL. Open the C<lib/Hello/Controller/Root.pm> file in
 249 your editor. You will see the "index" subroutine, which is
 250 responsible for displaying the welcome screen that you just saw in
 251 your browser. Later on you'll want to change that to something more
 252 reasonable, such as a "404" message or a redirect, but for now just
 253 leave it alone.
 254
 255     sub index :Path :Args(0) {
 256         my ( $self, $c ) = @_;
 257
 258         # Hello World
 259         $c->response->body( $c->welcome_message );
 260     }
 261
 262 The "C<$c>" here refers to the Catalyst context, which is used to
 263 access the Catalyst application. In addition to many other things,
 264 the Catalyst context provides access to "response" and "request"
 265 objects. (See L<Catalyst|Catalyst>,
 266 L<Catalyst::Response|Catalyst::Response>, and
 267 L<Catalyst::Request|Catalyst::Request>)
 268
 269 C<$c-E<gt>response-E<gt>body> sets the HTTP response (see
 270 L<Catalyst::Response|Catalyst::Response>), while C<$c-E<gt>welcome_message>
 271 is a special method that returns the welcome message that you saw in
 272 your browser.
 273
 274 The ":Path :Args(0)" after the method name are attributes which determine
 275 which URLs will be dispatched to this method. (Depending on your version of
 276 Catalyst, it used to say "Private" but using that with 'default' or 'index'
 277 is currently deprecated.)
 278
 279 Some MVC frameworks handle dispatching in a central place. Catalyst,
 280 by policy, prefers to handle URL dispatching with attributes on
 281 controller methods. There is a lot of flexibility in specifying which
 282 URLs to match.  This particular method will match all URLs, because it
 283 doesn't specify the path (nothing comes after "Path"), but will only
 284 accept a single args because of the ":Args(0)".
 285
 286 The default is to map URLs to controller names, and because of
 287 the way that Perl handles namespaces through package names,
 288 it is simple to create hierarchical structures in
 289 Catalyst. This means that you can create controllers with deeply
 290 nested actions in a clean and logical way.
 291
 292 For example, the URL C<http://hello.com/admin/articles/create> maps
 293 to the package C<Hello::Controller::Admin::Articles>, and the C<create>
 294 method.
 295
 296 Add the following subroutine to your C<lib/Hello/Controller/Root.pm>
 297 file:
 298
 299     sub hello : Global {
 300         my ( $self, $c ) = @_;
 301
 302         $c->response->body("Hello, World!");
 303     }
 304
 305 Here you're sending your own string to the webpage.
 306
 307 Save the file, start the server (stop and restart it if it's still
 308 up), and go to L<http://localhost:3000/hello> to
 309 see "Hello, World!"
 310
 311
 312 =head2 Hello, World! Using a View and a Template
 313
 314 In the Catalyst world  a "View" is not a page of XHTML or a template
 315 designed to present a page to a browser. It is the module that
 316 determines the I<type> of view -- HTML, pdf, XML, etc. For the
 317 thing that generates the I<content> of that view, (such as the
 318 default Toolkit Template) the actual templates go under the
 319 "root" directory.
 320
 321 To create a TT view, run:
 322
 323     $ script/hello_create.pl view TT TT
 324
 325 This creates the C<lib/Hello/View/TT.pm> module, which is a subclass of
 326 C<Catalyst::View::TT>. The "view" keyword tells the create script that
 327 you are creating a view, the second "TT" tells it that you are creating
 328 a Template Toolkit view, and the first "TT" tells the script to name
 329 the View module "TT.pm", which is a commonly used name for TT views.
 330 (You can name it anything you want, such as "HTML.pm".) If you look at
 331 TT.pm, you will find that it only contains a config statement to set
 332 the TT extension to ".tt".
 333
 334 Now that the TT.pm "View" exists, Catalyst will autodiscover it and be
 335 able to use it to display the view templates, using the "process"
 336 method that it inherits from the C<Catalyst::View::TT class>.
 337
 338 Template Toolkit is a very full featured template facility, with
 339 excellent documentation at L<http://template-toolkit.org/>,
 340 but since this is not a TT tutorial, we'll stick to only basic TT
 341 usage here (and explore some of the more common TT features in later
 342 parts of the tutorial).
 343
 344 Create a C<root/hello.tt> template file (put it in the C<root> under
 345 the C<Hello> directory that is the base of your application). Here is
 346 a simple sample:
 347
 348     [% META title = 'Hello, World!' %]
 349     <p>
 350         This is a TT view template, located in the 'root/' directory.
 351     </p>
 352
 353 [% and %] are markers for the TT parts of the template. Inside you can
 354 access Perl variables and classes, and use TT directives. The rest of
 355 the template is normal HTML. Change the hello method in
 356 C<lib/Hello/Controller/Root.pm> to the following:
 357
 358     sub hello : Global {
 359         my ( $self, $c ) = @_;
 360
 361         $c->stash->{template} = 'hello.tt';
 362     }
 363
 364 This time, instead of doing C<$c-E<gt>response->body()>, you are setting
 365 the value of the "template" hash key in the Catalyst "stash", an area
 366 for putting information to share with other parts of your application.
 367 The "template" key determines which template will be displayed at the
 368 end of the method. Catalyst controllers have a default "end" action
 369 for all methods which causes the first (or default) view to be
 370 rendered (unless there's a C<$c-E<gt>response->body()> statement). So your
 371 template will be magically displayed at the end of your method.
 372
 373 After saving the file, restart the development server, and look at
 374 L<http://localhost:3000/hello> again. You should
 375 see the template that you just made.
 376
 377
 378 =head1 CREATE A SIMPLE CONTROLLER AND AN ACTION
 379
 380 Create a controller named "Site" by executing the create script:
 381
 382     $ script/hello_create.pl controller Site
 383
 384 This will create a C<lib/Hello/Controller/Site.pm> file (and a test
 385 file). Bring Site.pm up in your editor, and you can see that there's
 386 not much there. Most people probably don't bother to use the create
 387 script to make controllers after they're used to using Catalyst.
 388
 389 In C<lib/Hello/Controller/Site.pm>, add the following method:
 390
 391     sub test : Local {
 392         my ( $self, $c ) = @_;
 393
 394         $c->stash->{username} = "John";
 395         $c->stash->{template} = 'site/test.tt';
 396     }
 397
 398 Notice the "Local" attribute on the method. This will allow the action
 399 to be executed on the "controller/method" URL, or, in this case,
 400 "site/test", instead of at the root site URL, like "Global". It's not
 401 actually necessary to set the template value, since by default TT will
 402 attempt to render a template that follows the naming pattern
 403 "controller/method.tt", and we're following that pattern here, but in
 404 other situations you will need to specify the template (such as if
 405 you've "forwarded" to the method, or if it doesn't follow the default
 406 naming convention). We've also put the variable "name" into the stash,
 407 for use in the template.
 408
 409 Make a subdirectory "site" in the "root" directory. Copy the hello.tt
 410 file into the directory as C<root/site/test.tt>, or create a new
 411 template file at that location. Include a line like:
 412
 413     <p>Hello, [% username %]!</p>
 414
 415 Bring up or restart the server.  Notice in the server output that
 416 C</site/test> is listed in the Loaded Path actions. Go to
 417 L<http://localhost:3000/site/test> in your browser.
 418
 419 You should see your test.tt file displayed, including the name "John"
 420 that you set in the controller.
 421
 422
 423 =head1 AUTHORS
 424
 425 Gerda Shank, C<gerda.shank@gmail.com>
 426 Kennedy Clark, C<hkclark@gmail.com>
 427
 428 Please report any errors, issues or suggestions to the author.  The
 429 most recent version of the Catalyst Tutorial can be found at
 430 L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/>.
 431
 432 Copyright 2006-2008, Kennedy Clark & Gerda Shank, under Creative Commons License
 433 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).