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

=head1 NAME

Catalyst::Manual::Tutorial - Getting started with Catalyst

=head1 DESCRIPTION

This document aims to get you up and running with Catalyst.

NOTE: THIS DOCUMENT IS STILL VERY MUCH IN AN EARLY DRAFT STATE.  SEE THE NOTES
AT THE BOTTOM OF THE DOCUMENT.


=head2 Installation

The first step is to install Catalyst, and the simplest way to do this is to
install the Catalyst bundle from CPAN:

    $ perl -MCPAN -e 'install Bundle::Catalyst'

This will retrieve Catalyst and a number of useful extensions and install them
for you.


=head2 Setting up your application

Catalyst includes a helper script, C<catalyst.pl>, that will set up a skeleton
application for you:

    $ catalyst.pl My::App
    created "My-App"
    created "My-App/script"
    created "My-App/lib"
    created "My-App/root"
    created "My-App/t"
    created "My-App/t/m"
    created "My-App/t/v"
    created "My-App/t/c"
    created "My-App/lib/My/App"
    created "My-App/lib/My/App/M"
    created "My-App/lib/My/App/V"
    created "My-App/lib/My/App/C"
    created "My-App/lib/My/App.pm"
    created "My-App/Makefile.PL"
    created "My-App/README"
    created "My-App/Changes"
    created "My-App/t/01app.t"
    created "My-App/t/02podcoverage.t"
    created "My-App/script/cgi.pl"
    created "My-App/script/nph-cgi.pl"
    created "My-App/script/fcgi.pl"
    created "My-App/script/server.pl"
    created "My-App/script/test.pl"
    created "My-App/script/create.pl"

This creates the directory structure shown, populated with skeleton files.


=head2 Testing out the sample application

You can test out your new application by running the server script that
catalyst provides:

    $ cd My-App
    $ script/server.pl 
    [...] [catalyst] [debug] Debug messages enabled
    [...] [catalyst] [debug] Loaded engine "Catalyst::Engine::CGI"
    [...] [catalyst] [debug] Initialized components ""
    [...] [catalyst] [info] My::App powered by Catalyst 4.26
    [...] [catalyst] [debug] "My::App" defined "!default" as "CODE(0x83fd570)"
    You can connect to your server at http://localhost:3000

(Note that each line logged by Catalyst includes a timestamp, which has been
replaced here with "C<...>" so that the text fits onto the lines.)

The server is now waiting for you to make requests of it.  Try using telnet to
manually make a simple GET request of the server (when telnet responds with
"Escape character is '^]'.", type "GET / HTTP/1.0" and hit return twice):

    $ telnet localhost 3000
    Trying 127.0.0.1...
    Connected to localhost.
    Escape character is '^]'.
    GET / HTTP/1.0
    
    HTTP/1.0 200
    Server: Catalyst/4.26
    Status: 200
    Date: Sun, 20 Mar 2005 12:31:55 GMT
    X-catalyst: 4.26
    Content-length: 40
    Content-Type: text/html; charset=ISO-8859-1

    Congratulations, My::App is on Catalyst!
    Connection closed by foreign host.
    $

More trace messages will appear in the original terminal window:

    [...] [catalyst] [debug] ********************************
    [...] [catalyst] [debug] * Request 1 (0.027/s) [9818]
    [...] [catalyst] [debug] ********************************
    [...] [catalyst] [debug] "GET" request for ""
    [...] [catalyst] [debug] Using default action
    [...] [catalyst] [info] Processing "!default" took 0.000033s
    [...] [catalyst] [info] Request took 0.051399s (19.456/s)

The server will continue running until you interrupt it.

The application can also be tested from the command line using the generated
helper script, C<script/test.pl>.


=head2 Getting your application invoked

Catalyst applications are usually run from mod_perl, but can also be run as
CGI or FastCGI scripts.  Running under mod_perl gives better performance, but
for development purposes you may want to run your application as a CGI script,
especially as changes to your application code take effect under CGI without
having to restart the web server.

To run from mod_perl you need to add something like this to your Apache
configuration file:

    <Location /my-app>
        SetHandler  perl-script
        PerlHandler My::App
    </Location>

To run as a CGI script you need a wrapper script like:

    #!/usr/bin/perl -w

    use strict;
    use lib '/path/to/My/App/lib';
    use My::App;

    My::App->run;

Catalyst outputs a complete HTTP response, which is not what is expected of a
CGI script.  You need to configure the script as a so-called "Non-parsed
Headers" script for it to function properly.  To do this in Apache just name
the script starting with C<nph->.

CHECK: is this statement still valid for Cat5?


=head2 Examining the generated code

The generated application code is quite simple and looks something like this:

    package My::App;

    use strict;
    use Catalyst qw/-Debug/;

    our $VERSION = '0.01';

    My::App->config(
	name => 'My::App',
	root => '/home/andrew/My-App/root',
    );

    My::App->action(
	'!default' => sub {
	    my ( $self, $c ) = @_;
	    $c->res->output('Congratulations, My::App is on Catalyst!');
	},
    );

    1;


When the C<Catalyst> module is imported by the application code, Catalyst
performs the first stage of its initialization.  This includes loading the
appropriate Engine module for the environment in which the application is
running, loading any plugins and ensuring that the calling module (the
application module) inherits from C<Catalyst> (which makes the Catalyst
methods C<config> and C<action> available to the application module).

The call to C<config> sets up configuration data for the application.  The
C<name> and C<root> items are the minimum required, and specify the name of
the application and the path to the root directory where documents, images and
templates can be found.

Catalyst associates I<actions> with URLs and on receiving a request dispatches
to the action that matches to request URL.  The call to C<action> in the code
above registers a default action.  With just this action registered the
application will respond to all requests with the same message
"Congratulations, My::App is on Catalyst!".

TODO: mention private actions and attributes


The first call to the C<action> method triggers the second stage of Catalyst's
initialization process.  In this phase Catalyst searches for any component
modules, locating and registering any actions it finds in those modules.
Component modules have names prefixed with the application module name,
followed by C<Model>, C<View> or C<Controller> (or the alternative short
forms: C<M>, C<V> or C<C>) followed by the component name, for example:

    My::App::Controller::ShoppingCart


=head2 Extending the generated code

NOTE: this section is outdated by Cat5.

You can start extending the application by adding new actions:

    My::App->action(
        'test1' => sub {
	    my ( $self, $c ) = @_;
	    $c->res->output('In a new test action #1');
	},
        'test1' => sub {
	    my ( $self, $c ) = @_;
	    $c->res->output('In a new test action #1');
	},
	'!default' => sub {
	    my ( $self, $c ) = @_;
	    $c->res->output('Congratulations, My::App is on Catalyst!');
	},
    );


TODO: explain briefly about plugins, actions and components

regex actions passed subexpression matches in $c->req->snippets (array ref).


=head2 Hooking in to Template Toolkit

One of the first things you will probably want to add to your application is a
templating system for generating your output.  Catalyst works well with
Template Toolkit.  If you are unfamiliar with Template Toolkit then I suggest
you look at L<http://tt2.org>, install C<Template>, read the documentation and
play around with it, and have a look at the I<Badger Book> (I<Template
Toolkit> by Darren Chamberlain, Dave Cross and Andy Wardly, O'Reilly &
Associates, 2004).

You can create a stub Template Toolkit view component using the create script
that Catalyst set up as part of the skeleton application:

    $ script/create.pl view TT TT

this generates a view component named C<My::App::View::TT>, which you might
use by forwarding from your C<end> action:

    # In My::App or My::App::Controller::SomeController

    sub end : Private {
        my($self, $c) = @_;
        $c->forward('My::App::View::TT');
    }

The generated TT view component simply subclasses the C<Catalyst::View::TT>
class.  It looks like this (with the POD stripped out):

    package My::App::V::TT;

    use strict;
    use base 'Catalyst::View::TT';

    1;

C<Catalyst::View::TT> initializes a Template Toolkit object with an options
hash initialized with built-in default settings followed by the contents of
the hash C<<%{__PACKAGE__->config()}>>.  You can configure TT more to your
needs by adding a C<new> method to the generated TT component:

    sub new {
	my $self = shift;
	$self->config->{PRE_PROCESS} = 'config/main';
	$self->config->{WRAPPER}     = 'site/wrapper';
	return $self->SUPER::new(@_);
    }


=head1 AUTHOR

Andrew Ford, C<A.Ford@ford-mason.co.uk>

As noted above, this document is at an alpha stage.  My plan for this document
is as follows:

=over 4

=item 1

expand this document fairly rapidly to cover topics relevant to
a newcomer to Catalyst in an order that can be read sequentially

=item 2

incorporate feedback 

=item 3

revise the text 

=back

Placeholders are indicated by the words: TODO or CHECK 

Please send comments, corrections and suggestions for improvements to
A.Ford@ford-mason.co.uk


=head1 COPYRIGHT

This program is free software, you can redistribute it and/or modify it under
the same terms as Perl itself.
Commit	Line	Data
83cea649	1	=head1 NAME
	2
	3	Catalyst::Manual::Tutorial - Getting started with Catalyst
	4
	5	=head1 DESCRIPTION
	6
	7	This document aims to get you up and running with Catalyst.
	8
b460ad78	9	NOTE: THIS DOCUMENT IS STILL VERY MUCH IN AN EARLY DRAFT STATE. SEE THE NOTES
b460ad78	10	AT THE BOTTOM OF THE DOCUMENT.
83cea649	11
83cea649	12
	13
	14	=head2 Installation
	15
	16	The first step is to install Catalyst, and the simplest way to do this is to
	17	install the Catalyst bundle from CPAN:
	18
	19	$ perl -MCPAN -e 'install Bundle::Catalyst'
	20
	21	This will retrieve Catalyst and a number of useful extensions and install them
	22	for you.
	23
	24
	25	=head2 Setting up your application
	26
	27	Catalyst includes a helper script, C<catalyst.pl>, that will set up a skeleton
	28	application for you:
	29
	30	$ catalyst.pl My::App
	31	created "My-App"
	32	created "My-App/script"
	33	created "My-App/lib"
	34	created "My-App/root"
	35	created "My-App/t"
	36	created "My-App/t/m"
	37	created "My-App/t/v"
	38	created "My-App/t/c"
	39	created "My-App/lib/My/App"
	40	created "My-App/lib/My/App/M"
	41	created "My-App/lib/My/App/V"
	42	created "My-App/lib/My/App/C"
	43	created "My-App/lib/My/App.pm"
	44	created "My-App/Makefile.PL"
	45	created "My-App/README"
	46	created "My-App/Changes"
	47	created "My-App/t/01app.t"
	48	created "My-App/t/02podcoverage.t"
501b6190	49	created "My-App/script/cgi.pl"
	50	created "My-App/script/nph-cgi.pl"
	51	created "My-App/script/fcgi.pl"
83cea649	52	created "My-App/script/server.pl"
	53	created "My-App/script/test.pl"
	54	created "My-App/script/create.pl"
	55
b460ad78	56	This creates the directory structure shown, populated with skeleton files.
83cea649	57
	58
	59
	60	=head2 Testing out the sample application
	61
	62	You can test out your new application by running the server script that
	63	catalyst provides:
	64
	65	$ cd My-App
	66	$ script/server.pl
b460ad78	67	[...] [catalyst] [debug] Debug messages enabled
	68	[...] [catalyst] [debug] Loaded engine "Catalyst::Engine::CGI"
	69	[...] [catalyst] [debug] Initialized components ""
	70	[...] [catalyst] [info] My::App powered by Catalyst 4.26
	71	[...] [catalyst] [debug] "My::App" defined "!default" as "CODE(0x83fd570)"
83cea649	72	You can connect to your server at http://localhost:3000
83cea649	73
b460ad78	74	(Note that each line logged by Catalyst includes a timestamp, which has been
	75	replaced here with "C<...>" so that the text fits onto the lines.)
	76
83cea649	77	The server is now waiting for you to make requests of it. Try using telnet to
	78	manually make a simple GET request of the server (when telnet responds with
	79	"Escape character is '^]'.", type "GET / HTTP/1.0" and hit return twice):
	80
	81	$ telnet localhost 3000
	82	Trying 127.0.0.1...
	83	Connected to localhost.
	84	Escape character is '^]'.
	85	GET / HTTP/1.0
	86
	87	HTTP/1.0 200
	88	Server: Catalyst/4.26
	89	Status: 200
	90	Date: Sun, 20 Mar 2005 12:31:55 GMT
	91	X-catalyst: 4.26
	92	Content-length: 40
	93	Content-Type: text/html; charset=ISO-8859-1
	94
	95	Congratulations, My::App is on Catalyst!
	96	Connection closed by foreign host.
	97	$
	98
	99	More trace messages will appear in the original terminal window:
	100
b460ad78	101	[...] [catalyst] [debug] ********************************
	102	[...] [catalyst] [debug] * Request 1 (0.027/s) [9818]
	103	[...] [catalyst] [debug] ********************************
	104	[...] [catalyst] [debug] "GET" request for ""
	105	[...] [catalyst] [debug] Using default action
	106	[...] [catalyst] [info] Processing "!default" took 0.000033s
	107	[...] [catalyst] [info] Request took 0.051399s (19.456/s)
83cea649	108
	109	The server will continue running until you interrupt it.
	110
	111	The application can also be tested from the command line using the generated
	112	helper script, C<script/test.pl>.
	113
	114
	115	=head2 Getting your application invoked
	116
b460ad78	117	Catalyst applications are usually run from mod_perl, but can also be run as
	118	CGI or FastCGI scripts. Running under mod_perl gives better performance, but
	119	for development purposes you may want to run your application as a CGI script,
	120	especially as changes to your application code take effect under CGI without
	121	having to restart the web server.
83cea649	122
	123	To run from mod_perl you need to add something like this to your Apache
	124	configuration file:
	125
b460ad78	126	<Location /my-app>
83cea649	127	SetHandler perl-script
b460ad78	128	PerlHandler My::App
83cea649	129	</Location>
	130
	131	To run as a CGI script you need a wrapper script like:
	132
	133	#!/usr/bin/perl -w
	134
	135	use strict;
b460ad78	136	use lib '/path/to/My/App/lib';
b460ad78	137	use My::App;
83cea649	138
b460ad78	139	My::App->run;
83cea649	140
	141	Catalyst outputs a complete HTTP response, which is not what is expected of a
	142	CGI script. You need to configure the script as a so-called "Non-parsed
	143	Headers" script for it to function properly. To do this in Apache just name
	144	the script starting with C<nph->.
	145
b460ad78	146	CHECK: is this statement still valid for Cat5?
83cea649	147
83cea649	148
b460ad78	149	=head2 Examining the generated code
83cea649	150
b460ad78	151	The generated application code is quite simple and looks something like this:
83cea649	152
	153	package My::App;
	154
	155	use strict;
	156	use Catalyst qw/-Debug/;
	157
	158	our $VERSION = '0.01';
	159
	160	My::App->config(
	161	name => 'My::App',
	162	root => '/home/andrew/My-App/root',
	163	);
	164
	165	My::App->action(
	166	'!default' => sub {
	167	my ( $self, $c ) = @_;
	168	$c->res->output('Congratulations, My::App is on Catalyst!');
	169	},
	170	);
	171
	172	1;
	173
	174
b460ad78	175	When the C<Catalyst> module is imported by the application code, Catalyst
	176	performs the first stage of its initialization. This includes loading the
	177	appropriate Engine module for the environment in which the application is
	178	running, loading any plugins and ensuring that the calling module (the
	179	application module) inherits from C<Catalyst> (which makes the Catalyst
	180	methods C<config> and C<action> available to the application module).
	181
	182	The call to C<config> sets up configuration data for the application. The
	183	C<name> and C<root> items are the minimum required, and specify the name of
	184	the application and the path to the root directory where documents, images and
	185	templates can be found.
	186
	187	Catalyst associates I<actions> with URLs and on receiving a request dispatches
	188	to the action that matches to request URL. The call to C<action> in the code
	189	above registers a default action. With just this action registered the
	190	application will respond to all requests with the same message
	191	"Congratulations, My::App is on Catalyst!".
	192
	193	TODO: mention private actions and attributes
	194
	195
	196	The first call to the C<action> method triggers the second stage of Catalyst's
	197	initialization process. In this phase Catalyst searches for any component
	198	modules, locating and registering any actions it finds in those modules.
	199	Component modules have names prefixed with the application module name,
	200	followed by C<Model>, C<View> or C<Controller> (or the alternative short
	201	forms: C<M>, C<V> or C<C>) followed by the component name, for example:
	202
	203	My::App::Controller::ShoppingCart
	204
	205
	206
	207
	208	=head2 Extending the generated code
	209
	210	NOTE: this section is outdated by Cat5.
	211
83cea649	212	You can start extending the application by adding new actions:
	213
	214	My::App->action(
	215	'test1' => sub {
	216	my ( $self, $c ) = @_;
	217	$c->res->output('In a new test action #1');
	218	},
	219	'test1' => sub {
	220	my ( $self, $c ) = @_;
	221	$c->res->output('In a new test action #1');
	222	},
	223	'!default' => sub {
	224	my ( $self, $c ) = @_;
	225	$c->res->output('Congratulations, My::App is on Catalyst!');
	226	},
	227	);
	228
	229
b460ad78	230	TODO: explain briefly about plugins, actions and components
	231
	232	regex actions passed subexpression matches in $c->req->snippets (array ref).
	233
	234
	235	=head2 Hooking in to Template Toolkit
	236
	237	One of the first things you will probably want to add to your application is a
	238	templating system for generating your output. Catalyst works well with
	239	Template Toolkit. If you are unfamiliar with Template Toolkit then I suggest
	240	you look at L<http://tt2.org>, install C<Template>, read the documentation and
	241	play around with it, and have a look at the I<Badger Book> (I<Template
	242	Toolkit> by Darren Chamberlain, Dave Cross and Andy Wardly, O'Reilly &
	243	Associates, 2004).
	244
	245	You can create a stub Template Toolkit view component using the create script
	246	that Catalyst set up as part of the skeleton application:
	247
	248	$ script/create.pl view TT TT
	249
	250	this generates a view component named C<My::App::View::TT>, which you might
	251	use by forwarding from your C<end> action:
	252
	253	# In My::App or My::App::Controller::SomeController
	254
	255	sub end : Private {
	256	my($self, $c) = @_;
	257	$c->forward('My::App::View::TT');
	258	}
	259
	260	The generated TT view component simply subclasses the C<Catalyst::View::TT>
	261	class. It looks like this (with the POD stripped out):
	262
	263	package My::App::V::TT;
	264
	265	use strict;
	266	use base 'Catalyst::View::TT';
	267
	268	1;
	269
	270	C<Catalyst::View::TT> initializes a Template Toolkit object with an options
	271	hash initialized with built-in default settings followed by the contents of
	272	the hash C<<%{__PACKAGE__->config()}>>. You can configure TT more to your
	273	needs by adding a C<new> method to the generated TT component:
	274
	275	sub new {
	276	my $self = shift;
	277	$self->config->{PRE_PROCESS} = 'config/main';
	278	$self->config->{WRAPPER} = 'site/wrapper';
	279	return $self->SUPER::new(@_);
	280	}
	281
83cea649	282
	283
	284	=head1 AUTHOR
	285
	286	Andrew Ford, C<A.Ford@ford-mason.co.uk>
	287
b460ad78	288	As noted above, this document is at an alpha stage. My plan for this document
	289	is as follows:
	290
	291	=over 4
	292
	293	=item 1
	294
	295	expand this document fairly rapidly to cover topics relevant to
	296	a newcomer to Catalyst in an order that can be read sequentially
	297
	298	=item 2
	299
	300	incorporate feedback
	301
	302	=item 3
	303
	304	revise the text
	305
	306	=back
	307
	308	Placeholders are indicated by the words: TODO or CHECK
	309
	310	Please send comments, corrections and suggestions for improvements to
	311	A.Ford@ford-mason.co.uk
	312
	313
83cea649	314	=head1 COPYRIGHT
	315
	316	This program is free software, you can redistribute it and/or modify it under
	317	the same terms as Perl itself.