Provided by: libcatalyst-manual-perl_5.9007-1_all bug

NAME

       Catalyst::Manual::Tutorial::02_CatalystBasics - Catalyst Tutorial - Chapter 2: Catalyst
       Application Development Basics

OVERVIEW

       This is Chapter 2 of 10 for the Catalyst tutorial.

       Tutorial Overview

       1.  Introduction

       2.  02_Catalyst Basics

       3.  More Catalyst Basics

       4.  Basic CRUD

       5.  Authentication

       6.  Authorization

       7.  Debugging

       8.  Testing

       9.  Advanced CRUD

       10. Appendices

DESCRIPTION

       In this chapter of the tutorial, we will create a very basic Catalyst web application,
       demonstrating a number of powerful capabilities, such as:

       •   Helper Scripts

           Catalyst helper scripts that can be used to rapidly bootstrap the skeletal structure
           of an application.

       •   MVC

           Model/View/Controller (MVC) provides an architecture that facilitates a clean
           "separation of control" between the different portions of your application. Given that
           many other documents cover this subject in detail, MVC will not be discussed in depth
           here (for an excellent introduction to MVC and general Catalyst concepts, please see
           Catalyst::Manual::About). In short:

           •   Model

               The model usually represents a data store. In most applications, the model equates
               to the objects that are created from and saved to your SQL database.

           •   View

               The view takes model objects and renders them into something for the end user to
               look at. Normally this involves a template-generation tool that creates HTML for
               the user's web browser, but it could easily be code that generates other forms
               such as PDF documents, e-mails, spreadsheets, or even "behind the scenes" formats
               such as XML and JSON.

           •   Controller

               As suggested by its name, the controller takes user requests and routes them to
               the necessary model and view.

       •   ORM

           The use of Object-Relational Mapping (ORM) technology for database access.
           Specifically, ORM provides an automated and standardized means to persist and restore
           objects to/from a relational database and will automatically create our Catalyst model
           for use with a database.

       You can checkout the source code for this example from the catalyst subversion repository
       as per the instructions in Catalyst::Manual::Tutorial::01_Intro.

CREATE A CATALYST PROJECT

       Catalyst provides a number of helper scripts that can be used to quickly flesh out the
       basic structure of your application. All Catalyst projects begin with the "catalyst.pl"
       helper (see Catalyst::Helper for more information on helpers).  Also note that as of
       Catalyst 5.7000, you will not have the helper scripts unless you install both
       Catalyst::Runtime and Catalyst::Devel.

       In this first chapter of the tutorial, use the Catalyst "catalyst.pl" script to initialize
       the framework for an application called "Hello":

           $ catalyst.pl Hello
           created "Hello"
           created "Hello/script"
           created "Hello/lib"
           created "Hello/root"
           ...
           created "Hello/script/hello_create.pl"
           Change to application directory and Run "perl Makefile.PL" to make sure your install is complete
           $ cd Hello

       Note: If you are using Strawberry Perl on Win32, drop the ".pl" from the end of the
       "catalyst.pl" command and simply use "catalyst Hello".

       The "catalyst.pl" helper script will display the names of the directories and files it
       creates:

           Changes               # Record of application changes
           lib                   # Lib directory for your app's Perl modules
               Hello             # Application main code directory
                   Controller    # Directory for Controller modules
                   Model         # Directory for Models
                   View          # Directory for Views
               Hello.pm          # Base application module
           Makefile.PL           # Makefile to build application
           hello.conf            # Application configuration file
           README                # README file
           root                  # Equiv of htdocs, dir for templates, css, javascript
               favicon.ico
               static            # Directory for static files
                   images        # Directory for image files used in welcome screen
           script                # Directory for Perl scripts
               hello_cgi.pl      # To run your app as a cgi (not recommended)
               hello_create.pl   # To create models, views, controllers
               hello_fastcgi.pl  # To run app as a fastcgi program
               hello_server.pl   # The normal development server
               hello_test.pl     # Test your app from the command line
           t                     # Directory for tests
               01app.t           # Test scaffold
               02pod.t
               03podcoverage.t

       Catalyst will "auto-discover" modules in the Controller, Model, and View directories. When
       you use the "hello_create.pl" script it will create Perl module scaffolds in those
       directories, plus test files in the "t" directory. The default location for templates is
       in the "root" directory. The scripts in the script directory will always start with the
       lowercased version of your application name. If your app is MaiTai, then the create script
       would be "maitai_create.pl".

       Though it's too early for any significant celebration, we already have a functioning
       application. We can use the Catalyst supplied script to start up a development server and
       view the default Catalyst page in your browser. All scripts in the script directory should
       be run from the base directory of your application, so change to the Hello directory.

       Run the following command to start up the built-in development web server (make sure you
       didn't forget the ""cd Hello"" from the previous step):

       Note: The "-r" argument enables reloading on code changes so you don't have to stop and
       start the server when you update code. See "perldoc script/hello_server.pl" or
       "script/hello_server.pl --help" for additional options you might find helpful. Most of the
       rest of the tutorial will assume that you are using "-r" when you start the development
       server, but feel free to manually start and stop it (use "Ctrl-C" to breakout of the dev
       server) if you prefer.

           $ script/hello_server.pl -r
           [debug] Debug messages enabled
           [debug] Statistics enabled
           [debug] Loaded plugins:
           .----------------------------------------------------------------------------.
           | Catalyst::Plugin::ConfigLoader  0.30                                       |
           '----------------------------------------------------------------------------'

           [debug] Loaded dispatcher "Catalyst::Dispatcher"
           [debug] Loaded engine "Catalyst::Engine"
           [debug] Found home "/home/catalyst/Hello"
           [debug] Loaded Config "/home/catalyst/Hello/hello.conf"
           [debug] Loaded components:
           .-----------------------------------------------------------------+----------.
           | Class                                                           | Type     |
           +-----------------------------------------------------------------+----------+
           | Hello::Controller::Root                                         | instance |
           '-----------------------------------------------------------------+----------'

           [debug] Loaded Private actions:
           .----------------------+--------------------------------------+--------------.
           | Private              | Class                                | Method       |
           +----------------------+--------------------------------------+--------------+
           | /default             | Hello::Controller::Root              | default      |
           | /end                 | Hello::Controller::Root              | end          |
           | /index               | Hello::Controller::Root              | index        |
           '----------------------+--------------------------------------+--------------'

           [debug] Loaded Path actions:
           .-------------------------------------+--------------------------------------.
           | Path                                | Private                              |
           +-------------------------------------+--------------------------------------+
           | /                                   | /index                               |
           | /                                   | /default                             |
           '-------------------------------------+--------------------------------------'

           [info] Hello powered by Catalyst 5.90002
           HTTP::Server::PSGI: Accepting connections at http://0:3000/

       Point your web browser to <http://localhost:3000> (substituting a different hostname or IP
       address as appropriate) and you should be greeted by the Catalyst welcome screen (if you
       get some other welcome screen or an "Index" screen, you probably forgot to specify port
       3000 in your URL).  Information similar to the following should be appended to the logging
       output of the development server:

           [info] Hello powered by Catalyst 5.90002
           HTTP::Server::PSGI: Accepting connections at http://0:3000/
           [info] *** Request 1 (0.067/s) [19026] [Tue Aug 30 17:24:32 2011] ***
           [debug] "GET" request for "/" from "192.168.245.2"
           [debug] Path is "/"
           [debug] Response Code: 200; Content-Type: text/html; charset=utf-8; Content-Length: 5613
           [info] Request took 0.040895s (24.453/s)
           .------------------------------------------------------------+-----------.
           | Action                                                     | Time      |
           +------------------------------------------------------------+-----------+
           | /index                                                     | 0.000916s |
           | /end                                                       | 0.000877s |
           '------------------------------------------------------------+-----------'

       Note: Press "Ctrl-C" to break out of the development server if necessary.

HELLO WORLD

   The Simplest Way
       The Root.pm controller is a place to put global actions that usually execute on the root
       URL. Open the "lib/Hello/Controller/Root.pm" file in your editor. You will see the "index"
       subroutine, which is responsible for displaying the welcome screen that you just saw in
       your browser.

           sub index :Path :Args(0) {
               my ( $self, $c ) = @_;

               # Hello World
               $c->response->body( $c->welcome_message );
           }

       Later on you'll want to change that to something more reasonable, such as a "404" message
       or a redirect, but for now just leave it alone.

       The "$c" here refers to the Catalyst context, which is used to access the Catalyst
       application. In addition to many other things, the Catalyst context provides access to
       "response" and "request" objects. (See Catalyst::Runtime, Catalyst::Response, and
       Catalyst::Request)

       "$c->response->body" sets the HTTP response (see Catalyst::Response), while
       "$c->welcome_message" is a special method that returns the welcome message that you saw in
       your browser.

       The ":Path :Args(0)" after the method name are attributes which determine which URLs will
       be dispatched to this method. (You might see ":Private" if you are using an older version
       of Catalyst, but using that with "default" or "index" is currently deprecated.  If so, you
       should also probably upgrade before continuing the tutorial.)

       Some MVC frameworks handle dispatching in a central place. Catalyst, by policy, prefers to
       handle URL dispatching with attributes on controller methods. There is a lot of
       flexibility in specifying which URLs to match.  This particular method will match all
       URLs, because it doesn't specify the path (nothing comes after "Path"), but will only
       accept a URL without any args because of the ":Args(0)".

       The default is to map URLs to controller names, and because of the way that Perl handles
       namespaces through package names, it is simple to create hierarchical structures in
       Catalyst. This means that you can create controllers with deeply nested actions in a clean
       and logical way. For example, the URL "http://hello.com/admin/articles/create" maps to the
       package "Hello::Controller::Admin::Articles", and the "create" method.

       While you leave the "script/hello_server.pl -r" command running the development server in
       one window (don't forget the "-r" at the end!), open another window and add the following
       subroutine to your "lib/Hello/Controller/Root.pm" file:

           sub hello :Global {
               my ( $self, $c ) = @_;

               $c->response->body("Hello, World!");
           }

       TIP: See Appendix 1 for tips on removing the leading spaces when cutting and pasting
       example code from POD-based documents.

       Notice in the window running the Development Server that you should get output similar to
       the following:

           Saw changes to the following files:
            - /home/catalyst/Hello/lib/Hello/Controller/Root.pm (modify)

           Attempting to restart the server
           ...
           [debug] Loaded Private actions:
           .----------------------+--------------------------------------+--------------.
           | Private              | Class                                | Method       |
           +----------------------+--------------------------------------+--------------+
           | /default             | Hello::Controller::Root              | default      |
           | /end                 | Hello::Controller::Root              | end          |
           | /index               | Hello::Controller::Root              | index        |
           | /hello               | Hello::Controller::Root              | hello        |
           '----------------------+--------------------------------------+--------------'
           ...

       The development server noticed the change in "Hello::Controller::Root" and automatically
       restarted itself.

       Go to <http://localhost:3000/hello> to see "Hello, World!".   Also notice that the newly
       defined 'hello' action is listed under "Loaded Private actions" in the development server
       debug output.

   Hello, World! Using a View and a Template
       In the Catalyst world a "View" itself is not a page of XHTML or a template designed to
       present a page to a browser. Rather, it is the module that determines the type of view --
       HTML, PDF, XML, etc. For the thing that generates the content of that view (such as a
       Template Toolkit template file), the actual templates go under the "root" directory.

       To create a TT view, run:

           $ script/hello_create.pl view HTML TT

       This creates the "lib/Hello/View/HTML.pm" module, which is a subclass of
       "Catalyst::View::TT".

       •   The "view" keyword tells the create script that you are creating a view.

       •   The first argument "HTML" tells the script to name the View module "HTML.pm", which is
           a commonly used name for TT views.  You can name it anything you want, such as
           "MyView.pm". If you have more than one view, be sure to set the default_view in
           Hello.pm (See Catalyst::View::TT for more details on setting this).

       •   The final "TT" tells Catalyst the type of the view, with "TT" indicating that you want
           to use a Template Toolkit view.

       If you look at "lib/Hello/View/HTML.pm" you will find that it only contains a config
       statement to set the TT extension to ".tt".

       Now that the HTML.pm "View" exists, Catalyst will autodiscover it and be able to use it to
       display the view templates using the "process" method that it inherits from the
       "Catalyst::View::TT" class.

       Template Toolkit is a very full-featured template facility, with excellent documentation
       at http://template-toolkit.org/ <http://template-toolkit.org/>, but since this is not a TT
       tutorial, we'll stick to only basic TT usage here (and explore some of the more common TT
       features in later chapters of the tutorial).

       Create a "root/hello.tt" template file (put it in the "root" under the "Hello" directory
       that is the base of your application). Here is a simple sample:

           <p>
               This is a TT view template, called '[% template.name %]'.
           </p>

       [% and %] are markers for the TT parts of the template. Inside you can access Perl
       variables and classes, and use TT directives. In this case, we're using a special TT
       variable that defines the name of the template file ("hello.tt").  The rest of the
       template is normal HTML.

       Change the hello method in "lib/Hello/Controller/Root.pm" to the following:

           sub hello :Global {
               my ( $self, $c ) = @_;

               $c->stash(template => 'hello.tt');
           }

       This time, instead of doing "$c->response->body()", you are setting the value of the
       "template" hash key in the Catalyst "stash", an area for putting information to share with
       other parts of your application. The "template" key determines which template will be
       displayed at the end of the request cycle. Catalyst controllers have a default "end"
       action for all methods which causes the first (or default) view to be rendered (unless
       there's a "$c->response->body()" statement). So your template will be magically displayed
       at the end of your method.

       After saving the file, the development server should automatically restart (again, the
       tutorial is written to assume that you are using the "-r" option -- manually restart it if
       you aren't), and look at <http://localhost:3000/hello> in your web browser again. You
       should see the template that you just created.

       TIP: If you keep the server running with "-r" in a "background window," don't let that
       window get totally hidden... if you have a syntax error in your code, the debug server
       output will contain the error information.

       Note: You will probably run into a variation of the "stash" statement above that looks
       like:

           $c->stash->{template} = 'hello.tt';

       Although this style is still relatively common, the approach we used previous is becoming
       more common because it allows you to set multiple stash variables in one line.  For
       example:

           $c->stash(template => 'hello.tt', foo => 'bar',
                     another_thing => 1);

       You can also set multiple stash values with a hashref:

           $c->stash({template => 'hello.tt', foo => 'bar',
                     another_thing => 1});

       Any of these formats work, but the "$c->stash(name => value);" style is growing in
       popularity -- you may wish to use it all the time (even when you are only setting a single
       value).

CREATE A SIMPLE CONTROLLER AND AN ACTION

       Create a controller named "Site" by executing the create script:

           $ script/hello_create.pl controller Site

       This will create a "lib/Hello/Controller/Site.pm" file (and a test file). If you bring
       Site.pm up in your editor, you can see that there's not much there to see.

       In "lib/Hello/Controller/Site.pm", add the following method:

           sub test :Local {
               my ( $self, $c ) = @_;

               $c->stash(username => 'John',
                         template => 'site/test.tt');
           }

       Notice the "Local" attribute on the "test" method. This will cause the "test" action (now
       that we have assigned an "action type" to the method it appears as a "controller action"
       to Catalyst) to be executed on the "controller/method" URL, or, in this case, "site/test".
       We will see additional information on controller actions throughout the rest of the
       tutorial, but if you are curious take a look at "Actions" in Catalyst::Manual::Intro.

       It's not actually necessary to set the template value as we do here.  By default TT will
       attempt to render a template that follows the naming pattern "controller/method.tt", and
       we're following that pattern here.  However, in other situations you will need to specify
       the template (such as if you've "forwarded" to the method, or if it doesn't follow the
       default naming convention).

       We've also put the variable "username" into the stash, for use in the template.

       Make a subdirectory "site" in the "root" directory.

           $ mkdir root/site

       Create a new template file in that direction named "root/site/test.tt" and include a line
       like:

           <p>Hello, [% username %]!</p>

       Once the server automatically restarts, notice in the server output that "/site/test" is
       listed in the Loaded Path actions.  Go to <http://localhost:3000/site/test> in your
       browser and you should see your test.tt file displayed, including the name "John" that you
       set in the controller.

       You can jump to the next chapter of the tutorial here: More Catalyst Basics

AUTHORS

       Gerda Shank, "gerda.shank@gmail.com" Kennedy Clark, "hkclark@gmail.com"

       Feel free to contact the author for any errors or suggestions, but the best way to report
       issues is via the CPAN RT Bug system at
       https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual
       <https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.

       Copyright 2006-2011, Kennedy Clark, under the Creative Commons Attribution Share-Alike
       License Version 3.0 (http://creativecommons.org/licenses/by-sa/3.0/us/
       <http://creativecommons.org/licenses/by-sa/3.0/us/>).

perl v5.14.2                                201Catalyst::Manual::Tutorial::02_CatalystBasics(3pm)