server (make sure you didn't forget the "C<cd Hello>" from the
previous step):
-B<Note>: the -r 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 for
-more useful options.
+B<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
+C<perldoc script/hello_server.pl> or C<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 C<Ctrl-C> to
+breakout of the dev server) if you prefer.
$ script/hello_server.pl -r
[debug] Debug messages enabled
| / | /default |
'-------------------------------------+--------------------------------------'
- [info] Hello powered by Catalyst 5.80018
+ [info] Hello powered by Catalyst 5.80020
You can connect to your server at http://debian:3000
Point your web browser to L<http://localhost:3000> (substituting a
| /end | 0.000425s |
'------------------------------------------------------------+-----------'
-B<Note>: Press Ctrl-C to break out of the development server if necessary.
+B<Note>: Press C<Ctrl-C> to break out of the development server if
+necessary.
=head1 HELLO WORLD
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.
+your browser.
sub index :Path :Args(0) {
my ( $self, $c ) = @_;
$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<$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"
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.
+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. (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
+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,
$c->response->body("Hello, World!");
}
+Once you restart the server, you will need to use the new address
+L<http://localhost:3000/hello> instead of L<http://localhost:3000/> to see the
+changes.
+
B<TIP>: See Appendix 1 for tips on removing the leading spaces when
cutting and pasting example code from POD-based documents.
Save the file, and you should notice the following in your server output:
Saw changes to the following files:
- - /srv/http/xenoterracide/Catalyst/Hello/lib/Hello/Controller/Root.pm (modify)
+ - /home/me/Hello/lib/Hello/Controller/Root.pm (modify)
Attempting to restart the server
- ...
+ ...
[debug] Loaded Private actions:
.----------------------+--------------------------------------+--------------.
| Private | Class | Method |
'-------------------------------------+--------------------------------------'
...
-Go to L<http://localhost:3000/hello> to see "Hello, World!".
+Go to L<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.
+
=head2 Hello, World! Using a View and a Template
To create a TT view, run:
- $ script/hello_create.pl view TT TT
+ $ script/hello_create.pl view HTML TT
-This creates the C<lib/Hello/View/TT.pm> module, which is a subclass of
+This creates the C<lib/Hello/View/HTML.pm> module, which is a subclass of
C<Catalyst::View::TT>.
=over 4
=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".)
+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 L<Catalyst::View::TT|Catalyst::View::TT> for more
+details on setting this).
=item *
=back
-If you look at C<lib/Hello/View/TT.pm> you will find that it only
+If you look at C<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 TT.pm "View" exists, Catalyst will autodiscover it and be
+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 C<Catalyst::View::TT class>.
+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/>,
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>
sub hello :Global {
my ( $self, $c ) = @_;
- $c->stash->{template} = 'hello.tt';
+ $c->stash(template => 'hello.tt');
}
This time, instead of doing C<$c-E<gt>response-E<gt>body()>, you are
E<gt>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 L<http://localhost:3000/hello> in your again. You
+should see the template that you just made.
+
+B<TIP:> If you keep the server running with "-r" in a "background
+window," don't let that window get totally hidden... if you have an
+syntax error in your code, the debug server output will contain the
+error information.
+
+B<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<$c-E<gt>stash(name =E<gt> value);>
+style is growing in popularity -- you may wish to use it all the
+time (even when you are only setting a single value).
+
+
=head1 CREATE A SIMPLE CONTROLLER AND AN ACTION
Create a controller named "Site" by executing the create script:
sub test :Local {
my ( $self, $c ) = @_;
- $c->stash->{username} = "John";
- $c->stash->{template} = 'site/test.tt';
+ $c->stash(username => 'John',
+ template => 'site/test.tt');
}
Notice the "Local" attribute on the C<test> method. This will cause
You should see your test.tt file displayed, including the name "John"
that you set in the controller.
+Once the server automatically restarts, 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.
+
=head1 AUTHORS
most recent version of the Catalyst Tutorial can be found at
L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.80/trunk/lib/Catalyst/Manual/Tutorial/>.
-Copyright 2006-2008, Kennedy Clark & Gerda Shank, under Creative Commons License
+Copyright 2006-2010, Kennedy Clark, under the
+Creative Commons Attribution Share-Alike License Version 3.0
(L<http://creativecommons.org/licenses/by-sa/3.0/us/>).