=head1 NAME
-Catalyst::Manual::Tutorial::CatalystBasics - Catalyst Tutorial - Part 2: Catalyst Application Development Basics
+Catalyst::Manual::Tutorial::CatalystBasics - Catalyst Tutorial - Chapter 2: Catalyst Application Development Basics
=head1 OVERVIEW
-This is B<Part 2 of 10> for the Catalyst tutorial.
+This is B<Chapter 2 of 10> for the Catalyst tutorial.
L<Tutorial Overview|Catalyst::Manual::Tutorial>
=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:
+In this chapter of the tutorial, we will create a very basic Catalyst
+web application, demonstrating a number of powerful capabilities, such
+as:
=over 4
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:
+L<Catalyst::Manual::About|Catalyst::Manual::About>). In short:
=over 4
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, or Excel
-spreadsheets.
+that generates other forms such as PDF documents, e-mails, spreadsheets,
+or even "behind the scenes" formats such as XML and JSON.
=item * Controller
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>
+L<Catalyst::Manual::Tutorial::Intro|Catalyst::Manual::Tutorial::Intro>.
=head1 CREATE A CATALYST PROJECT
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>:
+In this first chapter 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"
directories and files it creates:
Changes # Record of application changes
- lib # Lib directory for Perl modules
- Hello # Application code directory
+ 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
directory.
Run the following command to start up the built-in development web
-server:
+server (make sure you didn't forget the "C<cd Hello>" from the
+previous step):
$ script/hello_server.pl
[debug] Debug messages enabled
+ [debug] Statistics enabled
[debug] Loaded plugins:
.----------------------------------------------------------------------------.
- | Catalyst::Plugin::ConfigLoader 0.17 |
+ | Catalyst::Plugin::ConfigLoader 0.20 |
| Catalyst::Plugin::Static::Simple 0.20 |
'----------------------------------------------------------------------------'
+----------------------+--------------------------------------+--------------+
| /default | Hello::Controller::Root | default |
| /end | Hello::Controller::Root | end |
+ | /index | Hello::Controller::Root | index |
'----------------------+--------------------------------------+--------------'
- [info] Hello powered by Catalyst 5.7011
- You can connect to your server at http://localhost:3000
+ [debug] Loaded Path actions:
+ .-------------------------------------+--------------------------------------.
+ | Path | Private |
+ +-------------------------------------+--------------------------------------+
+ | / | /default |
+ | / | /index |
+ '-------------------------------------+--------------------------------------'
+
+ [info] Hello powered by Catalyst 5.80003
+ You can connect to your server at http://debian:3000
-Point your web browser to
-L<http://localhost:3000|http://localhost:3000> (substituting a
+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 May 18 10:11:36 2008] ***
- [debug] "GET" request for "/" from "127.0.0.1"
- [info] Request took 0.017964s (55.667/s)
+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] *** Request 1 (0.005/s) [20712] [Sun Mar 8 15:49:09 2009] ***
+ [debug] "GET" request for "/" from "1.1.1.98"
+ [info] Request took 0.007342s (136.203/s)
.----------------------------------------------------------------+-----------.
| Action | Time |
+----------------------------------------------------------------+-----------+
- | /default | 0.000540s |
- | /end | 0.001246s |
+ | /index | 0.000491s |
+ | /end | 0.000595s |
'----------------------------------------------------------------+-----------'
Press Ctrl-C to break out of the development server.
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 "default" subroutine, which is
+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 but for now just leave it alone.
+reasonable, such as a "404" message or a redirect, but for now just
+leave it alone.
- sub default :Path :Args {
+ sub index :Path :Args(0) {
my ( $self, $c ) = @_;
-
+
+ # Hello World
$c->response->body( $c->welcome_message );
}
L<Catalyst::Response|Catalyst::Response>, and
L<Catalyst::Request|Catalyst::Request>)
-C<$c->response->body> sets the HTTP response (see
-L<Catalyst::Response|Catalyst::Response>), while C<$c->welcome_message>
+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" after the method name are attributes which determine
+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 is
-currently deprecated.)
+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"), and will accept
-any number of args (nothing after args).
+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,
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:
$c->response->body("Hello, World!");
}
+B<TIP>: See Appendix 1 for tips on removing the leading spaces when
+cutting and pasting example code from POD-based documents.
+
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 type of view--HTML, pdf, XML. For the case of a
-template view (such as the default Toolkit Template) the actual
-templates go under the "root" directory.
+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>. The "view" keyword tells the create script that
-you are creating a view, the first "TT" tells it that you are creating
-a Template Toolkit view, and the second "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".) If you look at
-TT.pm, you will find that it only contains a config statement to set
-the TT extension to ".tt".
+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-tookit.org/>,
+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).
+chapters 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:
- [% META title = 'Hello, World!' %]
<p>
- This is a TT view template, located in the 'root/' directory.
+ 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. The rest of
-the template is normal HTML. Change the hello method in
-C<lib/Hello/Controller/Root.pm> to the following:
+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->response->body()>, you are setting
+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->response->body()> statement). So your
+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
$c->stash->{template} = 'site/test.tt';
}
-Notice the "Local" attribute on the method. This will allow the action
-to be executed on the "controller/method" URL, or, in this case,
-"site/test", instead of at the root site URL, like "Global". It's not
-actually necessary to set the template value, since by default TT will
-attempt to render a template that follows the naming pattern
-"controller/method.tt", and we're following that pattern here, but 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 "name" into the stash,
-for use in the template.
+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
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>
+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.
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/trunk/Catalyst-Manual/lib/Catalyst/Manual/Tutorial/>.
+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-nc-sa/2.5/>).
+(L<http://creativecommons.org/licenses/by-sa/3.0/us/>).
projects / catagits/Catalyst-Manual.git / blobdiff