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

=head1 NAME

Catalyst::Manual::Tutorial::Intro - Catalyst Tutorial - Part 1: Introduction


=head1 OVERVIEW

This is B<Part 1 of 9> of the Catalyst Tutorial.

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

=over 4

=item 1

B<Introduction>

=item 2

L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>

=item 3

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

=item 4

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

=item 5

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

=item 6

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

=item 7

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

=item 8

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

=item 9

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

=back

=head1 DESCRIPTION

This tutorial provides a multipart introduction to the Catalyst web
framework. It seeks to provide a rapid overview of many of its most
commonly used features. The focus is on the real-world best practices
required in the construction of nearly all Catalyst applications.

Although the primary target of the tutorial is users new to the Catalyst
framework, experienced users may wish to review specific sections (for
example, how to use DBIC for their model classes or how to add
authentication and authorization to an existing application).

Subjects covered include:

=over 4

=item * 

A simple application that lists and adds books.

=item *

The use of L<DBIx::Class|DBIx::Class> (DBIC) for the model.

=item * 

How to write CRUD (Create, Read, Update, and Delete) operations in
Catalyst.

=item *

Authentication ("auth").

=item * 

Role-based authorization ("authz").

=item * 

Attempts to provide an example showing current (5.7000) Catalyst
practices. For example, the use of 
L<Catalyst::Plugin::DefaultEnd|Catalyst::Plugin::DefaultEnd>,
DBIC, L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader> 
with C<myapp.yml>, the use of C<lib/MyApp/Controller/Root.pm> 
vs. C<lib/MyApp.pm>, etc.

=item * 

The use of Template Toolkit (TT) and the
L<Catalyst::Helper::View::TTSite|Catalyst::Helper::View::TTSite> 
view helper.

=item * 

Useful techniques for troubleshooting and debugging Catalyst
applications.

=item * 

The use of SQLite as a database (with code also provided for MySQL and
PostgreSQL).

=item * 

The use of L<HTML::Widget|HTML::Widget> for automated form processing 
and validation.

=back

This tutorial makes the learning process its main priority.  For
example, the level of comments in the code found here would like be
considered excessive in a "normal project".  Because of their contextual
value, this tutorial will generally favor inline comments over a
separate discussion in the text.  It also deliberately tries to
demonstrate multiple approaches to various features (in general, you
should try to be as consistent as possible with your own production
code).

Furthermore, this tutorial tries to minimize the number of controllers,
models, TT templates, and database tables.  Although this does result in
things being a bit contrived at times, the concepts should be applicable
to more complex environments.  More complete and complicated example
applications can be found in the C<examples> area of the Catalyst
Subversion repository at
L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>.

B<Note:> There are a variety of other introductory materials available
through the Catalyst web site and at
L<http://dev.catalyst.perl.org/wiki/UserIntroductions> and
L<http://dev.catalyst.perl.org/>.

=head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL

This tutorial was built using the following resources. Please note that
you may need to make adjustments for different environments and
versions:

=over 4

=item * 

OS = CentOS 4 Linux (RHEL 4)

=item * 

Catalyst v5.6902

=item * 

DBIx::Class v0.06003

=item * 

Catalyst Plugins

The plugins used in this tutorial all have sufficiently stable APIs that
you shouldn't need to worry about versions. However, there could be
cases where the tutorial is affected by what version of plugins you
use. The plugins used for this tutorial are:

=over 4

=item * 

Catalyst::Plugin::Authentication -- 0.07

=item *

Catalyst::Plugin::Authentication::Credential::Password -- 0.07

=item *

Catalyst::Plugin::Authentication::Store::DBIC -- 0.06

=item *

Catalyst::Plugin::Authorization::ACL -- 0.06

=item *

Catalyst::Plugin::Authorization::Roles -- 0.04

=item *

Catalyst::Plugin::ConfigLoader -- 0.07

=item *

Catalyst::Plugin::DefaultEnd -- 0.06

=item *

Catalyst::Plugin::HTML::Widget -- 1.1

=item *

Catalyst::Plugin::Session -- 0.05

=item *

Catalyst::Plugin::Session::FastMmap -- 0.12

=item *

Catalyst::Plugin::Session::State::Cookie -- 0.02

=item *

Catalyst::Plugin::Session::Store::FastMmap -- 0.02

=item *

Catalyst::Plugin::StackTrace -- 0.04

=item *

Catalyst::Plugin::Static::Simple -- 0.14

=back

=item * 

Since the web browser is being used on the same box where Perl and the
Catalyst development server is running, the URL of
C<http://localhost:3000> will be used (the Catalyst development server
defaults to port 3000).  If you are running Perl on a different box than
where your web browser is located (or using a different port number via
the C<-p> I<port_number> option to the development server), then you
will need to update the URL you use accordingly.

=item * 

Depending on the web browser you are using, you might need to hit
C<Shift+Reload> to pull a fresh page when testing your application at
various points.  Also, the C<-k> keepalive option to the development
server can be necessary with some browsers (especially Internet
Explorer).

=back

=head1 CATALYST INSTALLATION

Unfortunately, one of the most daunting tasks faced by newcomers to
Catalyst is getting it installed.  Although a compelling strength of
Catalyst is that it can easily make use of many of the modules in the
vast repository that is CPAN, this can result in initial installations
that are both time consuming and frustrating.  However, there are a
growing number of methods that can dramatically ease this undertaking.
Of these, the following are likely to be applicable to the largest
number of potential new users:

=over 4

=item * 

Matt Trout's C<cat-install>

Available at L<http://www.shadowcatsystems.co.uk/static/cat-install>,
C<cat-install> can be a quick and painless way to get Catalyst up and
running.  Just download the script from the link above and type C<perl
cat-install>.

=item * 

Chris Laco's CatInABox

Download the tarball from
L<http://handelframework.com/downloads/CatInABox.tar.gz> and unpack it
on your machine.  Depending on your OS platform, either run C<start.bat>
or C<start.sh>.

=item * 

Pre-Built VMWare Images

Under the VMWare community program, work is ongoing to develop a number
of VMWare images where an entire Catalyst development environment has
already been installed, complete with database engines and a full
complement of Catalyst plugins.

=back

For additional information and recommendations on Catalyst installation,
please refer to 
L<Catalyst::Manual::Installation|Catalyst::Manual::Installation>.

B<NOTE:> Step-by-step instructions to replicate the environment on
which this tutorial was developed can be found at
L<Catalyst::Manual::Installation::CentOS4|Catalyst::Manual::Installation::CentOS4>. 
Using these instructions, you should be able to build a complete CentOS
4.X server with Catalyst and all the plugins required to run this
tutorial.

=head1 DATABASES

This tutorial will primarily focus on SQLite because of its simplicity
of installation and use; however, modifications in the script required
to support MySQL and PostgreSQL will be presented in Appendix 2.

B<Note:> One of the advantages of the MVC design patterns is that
applications become much more database independent.  As such, you will
notice that only the C<.sql> files used to initialize the database
change between database systems: the Catalyst code generally remains the
same.

=head1 WHERE TO GET WORKING CODE

Each part of the tutorial has complete code available in the main
Catalyst Subversion repository (see the note at the beginning of each
part for the appropriate svn command to use).  Additionally, the final
code is available as a ready-to-run tarball at
I<TO_BE_ADDED_TO_FINAL_VERSION>.


=head1 AUTHOR

Kennedy Clark, C<hkclark@gmail.com>

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

Copyright 2006, Kennedy Clark, under Creative Commons License
(L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).
Commit	Line	Data
4d583dd8	1	=head1 NAME
4d583dd8	2
64ccd8a8	3	Catalyst::Manual::Tutorial::Intro - Catalyst Tutorial - Part 1: Introduction
4d583dd8	4
4d583dd8	5
4d583dd8	6	=head1 OVERVIEW
4d583dd8	7
653f4595	8	This is B<Part 1 of 9> of the Catalyst Tutorial.
4d583dd8	9
64ccd8a8	10	L<Tutorial Overview\|Catalyst::Manual::Tutorial>
4d583dd8	11
	12	=over 4
	13
	14	=item 1
	15
	16	B<Introduction>
	17
	18	=item 2
	19
	20	L<Catalyst Basics\|Catalyst::Manual::Tutorial::CatalystBasics>
	21
	22	=item 3
	23
653f4595	24	L<Basic CRUD\|Catalyst::Manual::Tutorial::BasicCRUD>
4d583dd8	25
	26	=item 4
	27
	28	L<Authentication\|Catalyst::Manual::Tutorial::Authentication>
	29
	30	=item 5
	31
	32	L<Authorization\|Catalyst::Manual::Tutorial::Authorization>
	33
	34	=item 6
	35
	36	L<Debugging\|Catalyst::Manual::Tutorial::Debugging>
	37
	38	=item 7
	39
	40	L<Testing\|Catalyst::Manual::Tutorial::Testing>
	41
	42	=item 8
	43
653f4595	44	L<Advanced CRUD\|Catalyst::Manual::Tutorial::AdvancedCRUD>
4d583dd8	45
	46	=item 9
	47
653f4595	48	L<Appendices\|Catalyst::Manual::Tutorial::Appendices>
4d583dd8	49
	50	=back
	51
4d583dd8	52	=head1 DESCRIPTION
4d583dd8	53
653f4595	54	This tutorial provides a multipart introduction to the Catalyst web
	55	framework. It seeks to provide a rapid overview of many of its most
	56	commonly used features. The focus is on the real-world best practices
64ccd8a8	57	required in the construction of nearly all Catalyst applications.
4d583dd8	58
64ccd8a8	59	Although the primary target of the tutorial is users new to the Catalyst
	60	framework, experienced users may wish to review specific sections (for
	61	example, how to use DBIC for their model classes or how to add
	62	authentication and authorization to an existing application).
4d583dd8	63
	64	Subjects covered include:
	65
	66	=over 4
	67
	68	=item *
	69
	70	A simple application that lists and adds books.
	71
	72	=item *
	73
14e6feb0	74	The use of L<DBIx::Class\|DBIx::Class> (DBIC) for the model.
4d583dd8	75
	76	=item *
	77
653f4595	78	How to write CRUD (Create, Read, Update, and Delete) operations in
653f4595	79	Catalyst.
4d583dd8	80
	81	=item *
	82
	83	Authentication ("auth").
	84
	85	=item *
	86
	87	Role-based authorization ("authz").
	88
	89	=item *
	90
eed93301	91	Attempts to provide an example showing current (5.7000) Catalyst
14e6feb0	92	practices. For example, the use of
	93	L<Catalyst::Plugin::DefaultEnd\|Catalyst::Plugin::DefaultEnd>,
	94	DBIC, L<Catalyst::Plugin::ConfigLoader\|Catalyst::Plugin::ConfigLoader>
	95	with C<myapp.yml>, the use of C<lib/MyApp/Controller/Root.pm>
	96	vs. C<lib/MyApp.pm>, etc.
4d583dd8	97
	98	=item *
	99
653f4595	100	The use of Template Toolkit (TT) and the
14e6feb0	101	L<Catalyst::Helper::View::TTSite\|Catalyst::Helper::View::TTSite>
14e6feb0	102	view helper.
4d583dd8	103
	104	=item *
	105
653f4595	106	Useful techniques for troubleshooting and debugging Catalyst
653f4595	107	applications.
4d583dd8	108
	109	=item *
	110
653f4595	111	The use of SQLite as a database (with code also provided for MySQL and
653f4595	112	PostgreSQL).
4d583dd8	113
	114	=item *
	115
cc548726	116	The use of L<HTML::Widget\|HTML::Widget> for automated form processing
cc548726	117	and validation.
4d583dd8	118
	119	=back
	120
653f4595	121	This tutorial makes the learning process its main priority. For
	122	example, the level of comments in the code found here would like be
	123	considered excessive in a "normal project". Because of their contextual
	124	value, this tutorial will generally favor inline comments over a
	125	separate discussion in the text. It also deliberately tries to
	126	demonstrate multiple approaches to various features (in general, you
	127	should try to be as consistent as possible with your own production
	128	code).
4d583dd8	129
64ccd8a8	130	Furthermore, this tutorial tries to minimize the number of controllers,
	131	models, TT templates, and database tables. Although this does result in
	132	things being a bit contrived at times, the concepts should be applicable
	133	to more complex environments. More complete and complicated example
	134	applications can be found in the C<examples> area of the Catalyst
	135	Subversion repository at
	136	L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>.
4d583dd8	137
64ccd8a8	138	B<Note:> There are a variety of other introductory materials available
	139	through the Catalyst web site and at
	140	L<http://dev.catalyst.perl.org/wiki/UserIntroductions> and
	141	L<http://dev.catalyst.perl.org/>.
4d583dd8	142
4d583dd8	143	=head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
4d583dd8	144
653f4595	145	This tutorial was built using the following resources. Please note that
653f4595	146	you may need to make adjustments for different environments and
64ccd8a8	147	versions:
4d583dd8	148
	149	=over 4
	150
	151	=item *
	152
	153	OS = CentOS 4 Linux (RHEL 4)
	154
	155	=item *
	156
14e6feb0	157	Catalyst v5.6902
4d583dd8	158
	159	=item *
	160
14e6feb0	161	DBIx::Class v0.06003
4d583dd8	162
	163	=item *
	164
	165	Catalyst Plugins
	166
653f4595	167	The plugins used in this tutorial all have sufficiently stable APIs that
	168	you shouldn't need to worry about versions. However, there could be
	169	cases where the tutorial is affected by what version of plugins you
	170	use. The plugins used for this tutorial are:
4d583dd8	171
	172	=over 4
	173
	174	=item *
	175
	176	Catalyst::Plugin::Authentication -- 0.07
	177
	178	=item *
	179
cc548726	180	Catalyst::Plugin::Authentication::Credential::Password -- 0.07
4d583dd8	181
	182	=item *
	183
	184	Catalyst::Plugin::Authentication::Store::DBIC -- 0.06
	185
	186	=item *
	187
	188	Catalyst::Plugin::Authorization::ACL -- 0.06
	189
	190	=item *
	191
	192	Catalyst::Plugin::Authorization::Roles -- 0.04
	193
	194	=item *
	195
	196	Catalyst::Plugin::ConfigLoader -- 0.07
	197
	198	=item *
	199
	200	Catalyst::Plugin::DefaultEnd -- 0.06
	201
	202	=item *
	203
4d583dd8	204	Catalyst::Plugin::HTML::Widget -- 1.1
	205
	206	=item *
	207
	208	Catalyst::Plugin::Session -- 0.05
	209
	210	=item *
	211
	212	Catalyst::Plugin::Session::FastMmap -- 0.12
	213
	214	=item *
	215
	216	Catalyst::Plugin::Session::State::Cookie -- 0.02
	217
	218	=item *
	219
14e6feb0	220	Catalyst::Plugin::Session::Store::FastMmap -- 0.02
4d583dd8	221
	222	=item *
	223
14e6feb0	224	Catalyst::Plugin::StackTrace -- 0.04
4d583dd8	225
	226	=item *
	227
	228	Catalyst::Plugin::Static::Simple -- 0.14
	229
	230	=back
	231
	232	=item *
	233
64ccd8a8	234	Since the web browser is being used on the same box where Perl and the
	235	Catalyst development server is running, the URL of
	236	C<http://localhost:3000> will be used (the Catalyst development server
	237	defaults to port 3000). If you are running Perl on a different box than
	238	where your web browser is located (or using a different port number via
	239	the C<-p> I<port_number> option to the development server), then you
	240	will need to update the URL you use accordingly.
4d583dd8	241
	242	=item *
	243
64ccd8a8	244	Depending on the web browser you are using, you might need to hit
	245	C<Shift+Reload> to pull a fresh page when testing your application at
	246	various points. Also, the C<-k> keepalive option to the development
	247	server can be necessary with some browsers (especially Internet
	248	Explorer).
4d583dd8	249
	250	=back
	251
4d583dd8	252	=head1 CATALYST INSTALLATION
4d583dd8	253
64ccd8a8	254	Unfortunately, one of the most daunting tasks faced by newcomers to
64ccd8a8	255	Catalyst is getting it installed. Although a compelling strength of
653f4595	256	Catalyst is that it can easily make use of many of the modules in the
	257	vast repository that is CPAN, this can result in initial installations
	258	that are both time consuming and frustrating. However, there are a
	259	growing number of methods that can dramatically ease this undertaking.
	260	Of these, the following are likely to be applicable to the largest
	261	number of potential new users:
4d583dd8	262
	263	=over 4
	264
	265	=item *
	266
64ccd8a8	267	Matt Trout's C<cat-install>
4d583dd8	268
64ccd8a8	269	Available at L<http://www.shadowcatsystems.co.uk/static/cat-install>,
	270	C<cat-install> can be a quick and painless way to get Catalyst up and
	271	running. Just download the script from the link above and type C<perl
	272	cat-install>.
4d583dd8	273
	274	=item *
	275
	276	Chris Laco's CatInABox
	277
64ccd8a8	278	Download the tarball from
	279	L<http://handelframework.com/downloads/CatInABox.tar.gz> and unpack it
	280	on your machine. Depending on your OS platform, either run C<start.bat>
	281	or C<start.sh>.
4d583dd8	282
	283	=item *
	284
	285	Pre-Built VMWare Images
	286
64ccd8a8	287	Under the VMWare community program, work is ongoing to develop a number
	288	of VMWare images where an entire Catalyst development environment has
	289	already been installed, complete with database engines and a full
	290	complement of Catalyst plugins.
4d583dd8	291
	292	=back
	293
653f4595	294	For additional information and recommendations on Catalyst installation,
14e6feb0	295	please refer to
14e6feb0	296	L<Catalyst::Manual::Installation\|Catalyst::Manual::Installation>.
4d583dd8	297
14e6feb0	298	B<NOTE:> Step-by-step instructions to replicate the environment on
64ccd8a8	299	which this tutorial was developed can be found at
14e6feb0	300	L<Catalyst::Manual::Installation::CentOS4\|Catalyst::Manual::Installation::CentOS4>.
64ccd8a8	301	Using these instructions, you should be able to build a complete CentOS
	302	4.X server with Catalyst and all the plugins required to run this
	303	tutorial.
4d583dd8	304
4d583dd8	305	=head1 DATABASES
4d583dd8	306
653f4595	307	This tutorial will primarily focus on SQLite because of its simplicity
	308	of installation and use; however, modifications in the script required
	309	to support MySQL and PostgreSQL will be presented in Appendix 2.
4d583dd8	310
64ccd8a8	311	B<Note:> One of the advantages of the MVC design patterns is that
	312	applications become much more database independent. As such, you will
	313	notice that only the C<.sql> files used to initialize the database
653f4595	314	change between database systems: the Catalyst code generally remains the
653f4595	315	same.
4d583dd8	316
	317	=head1 WHERE TO GET WORKING CODE
	318
64ccd8a8	319	Each part of the tutorial has complete code available in the main
	320	Catalyst Subversion repository (see the note at the beginning of each
	321	part for the appropriate svn command to use). Additionally, the final
	322	code is available as a ready-to-run tarball at
14e6feb0	323	I<TO_BE_ADDED_TO_FINAL_VERSION>.
4d583dd8	324
a63e6e67	325
4d583dd8	326	=head1 AUTHOR
	327
	328	Kennedy Clark, C<hkclark@gmail.com>
	329
eed93301	330	Please report any errors, issues or suggestions to the author. The
	331	most recent version of the Catlayst Tutorial can be found at
	332	L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/>.
4d583dd8	333
64ccd8a8	334	Copyright 2006, Kennedy Clark, under Creative Commons License
64ccd8a8	335	(L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).
4d583dd8	336
4d583dd8	337