Suggestions and fixes with thanks to Murray Walker (along with a few other minor...

[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / Tutorial / CatalystBasics.pod

=head1 NAME

Catalyst::Manual::Tutorial::CatalystBasics - Catalyst Tutorial - Part 2: Catalyst Application Development Basics


=head1 OVERVIEW

This is B<Part 2 of 10> for the Catalyst tutorial.

L<Tutorial Overview|Catalyst::Manual::Tutorial>

=over 4

=item 1

L<Introduction|Catalyst::Manual::Tutorial::Intro>

=item 2

B<Catalyst Basics>

=item 3

L<More Catalyst Basics|Catalyst::Manual::Tutorial::MoreCatalystBasics>

=item 4

L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>

=item 5

L<Authentication|Catalyst::Manual::Tutorial::Authentication>

=item 6

L<Authorization|Catalyst::Manual::Tutorial::Authorization>

=item 7

L<Debugging|Catalyst::Manual::Tutorial::Debugging>

=item 8

L<Testing|Catalyst::Manual::Tutorial::Testing>

=item 9

L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>

=item 10

L<Appendices|Catalyst::Manual::Tutorial::Appendices>

=back


=head1 DESCRIPTION

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

=over 4

=item * Helper Scripts

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

=item * 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
L<Catalyst::Manual::About|Catalyst::Manual::About>). In short:

=over 4

=item * 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.

=item * 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.

=item * Controller

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

=back

=item * 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.

=back

You can checkout the source code for this example from the catalyst
subversion repository as per the instructions in
L<Catalyst::Manual::Tutorial::Intro|Catalyst::Manual::Tutorial::Intro>.


=head1 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 C<catalyst.pl> helper (see 
L<Catalyst::Helper|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 L<Catalyst::Runtime|Catalyst::Runtime> 
and L<Catalyst::Devel|Catalyst::Devel>.

In this first part of the tutorial, use the Catalyst 
C<catalyst.pl> script to initialize the framework for an 
application called C<Hello>:

    $ catalyst.pl Hello
    created "Hello"
    created "Hello/script"
    created "Hello/lib"
    created "Hello/root"
    ...
    created "Hello/script/hello_create.pl"
    $ cd Hello

The C<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:

    $ script/hello_server.pl
    [debug] Debug messages enabled
    [debug] Statistics enabled
    [debug] Loaded plugins:
    .----------------------------------------------------------------------------.
    | Catalyst::Plugin::ConfigLoader  0.20                                       |
    | Catalyst::Plugin::Static::Simple  0.20                                     |
    '----------------------------------------------------------------------------'
    
    [debug] Loaded dispatcher "Catalyst::Dispatcher"
    [debug] Loaded engine "Catalyst::Engine::HTTP"
    [debug] Found home "/home/me/Hello"
    [debug] Loaded Config "/home/me/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          |
    '----------------------+--------------------------------------+--------------'
    
    [debug] Loaded Path actions:
    .-------------------------------------+--------------------------------------.
    | Path                                | Private                              |
    +-------------------------------------+--------------------------------------+
    | /                                   | /default                             |
    | /                                   | /index                               |
    '-------------------------------------+--------------------------------------'
        
    [info] Hello powered by Catalyst 5.7014
    You can connect to your server at http://localhost:3000

Point your web browser to L<http://localhost:3000> (substituting a 
different hostname or IP address as appropriate) and you should be 
greeted by the Catalyst welcome screen.  Information similar to the 
following should be appended to the logging output of the development 
server:

    [info] *** Request 1 (1.000/s) [10301] [Sun Nov 23 10:11:36 2008] ***
    [debug] "GET" request for "/" from "127.0.0.1"
    [info] Request took 0.017964s (55.667/s)
    .----------------------------------------------------------------+-----------.
    | Action                                                         | Time      |
    +----------------------------------------------------------------+-----------+
    | /default                                                       | 0.000540s |
    | /end                                                           | 0.001246s |
    '----------------------------------------------------------------+-----------'

Press Ctrl-C to break out of the development server.


=head1 HELLO WORLD

=head2 The Simplest Way

The Root.pm controller is a place to put global actions that usually 
execute on the root URL. Open the C<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. 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.

    sub index :Path :Args(0) {
        my ( $self, $c ) = @_;
        
        # Hello World
        $c->response->body( $c->welcome_message );
    }

The "C<$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 L<Catalyst|Catalyst>, 
L<Catalyst::Response|Catalyst::Response>, and 
L<Catalyst::Request|Catalyst::Request>) 

C<$c-E<gt>response-E<gt>body> sets the HTTP response (see 
L<Catalyst::Response|Catalyst::Response>), while C<$c-E<gt>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. (Depending on your version of 
Catalyst, it used to say "Private" but using that with 'default' or 'index' 
is currently deprecated.)

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 single 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 C<http://hello.com/admin/articles/create> maps 
to the package C<Hello::Controller::Admin::Articles>, and the C<create>
method. 

Add the following subroutine to your C<lib/Hello/Controller/Root.pm> 
file:

    sub hello : Global {
        my ( $self, $c ) = @_;
        
        $c->response->body("Hello, World!");
    }

Here you're sending your own string to the webpage.

Save the file, start the server (stop and restart it if it's still 
up), and go to L<http://localhost:3000/hello> to 
see "Hello, World!"


=head2 Hello, World! Using a View and a Template

In the Catalyst world  a "View" is not a page of XHTML or a template 
designed to present a page to a browser. It is the module that 
determines the I<type> of view -- HTML, pdf, XML, etc. For the 
thing that generates the I<content> of that view, (such as the 
default Toolkit Template) the actual templates go under the 
"root" directory.

To create a TT view, run:

    $ script/hello_create.pl view TT TT

This creates the C<lib/Hello/View/TT.pm> module, which is a subclass of 
C<Catalyst::View::TT>. 

=over 4

=item *

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

=item *

The first "TT" tells the script to name the View module "TT.pm", which is a
commonly used name for TT views.  (You can name it anything you want, such as
"HTML.pm".)

=item *

The final "TT" tells it that you are creating a Template Toolkit view.

=back

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

Now that the TT.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 C<Catalyst::View::TT class>.

Template Toolkit is a very full featured template facility, with 
excellent documentation at L<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 
parts of the tutorial).

Create a C<root/hello.tt> template file (put it in the C<root> under 
the C<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 (C<hello.tt>).  The rest of the template is normal HTML. 

Change the hello method in C<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<$c-E<gt>response-E<gt>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 method. 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<$c-E<gt>response-E<gt>body()> statement). So your 
template will be magically displayed at the end of your method.

After saving the file, restart the development server, and look at 
L<http://localhost:3000/hello> again. You should 
see the template that you just made.


=head1 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 C<lib/Hello/Controller/Site.pm> file (and a test 
file). Bring Site.pm up in your editor, and you can see that there's 
not much there. Most people probably don't bother to use the create 
script to make controllers after they're used to using Catalyst.

In C<lib/Hello/Controller/Site.pm>, add the following method:

    sub test : Local {
        my ( $self, $c ) = @_;
    
        $c->stash->{username} = "John";
        $c->stash->{template} = 'site/test.tt';
    }

Notice the "Local" attribute on the C<test> method. This will cause 
the C<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 
L<Catalyst::Manual::Intro/Actions>.

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. Copy the hello.tt 
file into the directory as C<root/site/test.tt>, or create a new 
template file at that location. Include a line like: 

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

Bring up or restart the server.  Notice in the server output that 
C</site/test> is listed in the Loaded Path actions. Go to 
L<http://localhost:3000/site/test> in your browser.

You should see your test.tt file displayed, including the name "John"
that you set in the controller.


=head1 AUTHORS

Gerda Shank, C<gerda.shank@gmail.com>
Kennedy Clark, C<hkclark@gmail.com>

Please report any errors, issues or suggestions to the author.  The
most recent version of the Catalyst Tutorial can be found at
L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/>.

Copyright 2006-2008, Kennedy Clark & Gerda Shank, under Creative Commons License
(L<http://creativecommons.org/licenses/by-sa/3.0/us/>).