[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.7X) Catalyst
practices. For example, the use of 
L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>,
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::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
d645910d	91	Attempts to provide an example showing current (5.7X) Catalyst
14e6feb0	92	practices. For example, the use of
33aee7ed	93	L<Catalyst::Action::RenderView\|Catalyst::Action::RenderView>,
14e6feb0	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
4d583dd8	200	Catalyst::Plugin::HTML::Widget -- 1.1
	201
	202	=item *
	203
	204	Catalyst::Plugin::Session -- 0.05
	205
	206	=item *
	207
	208	Catalyst::Plugin::Session::FastMmap -- 0.12
	209
	210	=item *
	211
	212	Catalyst::Plugin::Session::State::Cookie -- 0.02
	213
	214	=item *
	215
14e6feb0	216	Catalyst::Plugin::Session::Store::FastMmap -- 0.02
4d583dd8	217
	218	=item *
	219
14e6feb0	220	Catalyst::Plugin::StackTrace -- 0.04
4d583dd8	221
	222	=item *
	223
	224	Catalyst::Plugin::Static::Simple -- 0.14
	225
	226	=back
	227
	228	=item *
	229
64ccd8a8	230	Since the web browser is being used on the same box where Perl and the
	231	Catalyst development server is running, the URL of
	232	C<http://localhost:3000> will be used (the Catalyst development server
	233	defaults to port 3000). If you are running Perl on a different box than
	234	where your web browser is located (or using a different port number via
	235	the C<-p> I<port_number> option to the development server), then you
	236	will need to update the URL you use accordingly.
4d583dd8	237
	238	=item *
	239
64ccd8a8	240	Depending on the web browser you are using, you might need to hit
	241	C<Shift+Reload> to pull a fresh page when testing your application at
	242	various points. Also, the C<-k> keepalive option to the development
	243	server can be necessary with some browsers (especially Internet
	244	Explorer).
4d583dd8	245
	246	=back
	247
4d583dd8	248	=head1 CATALYST INSTALLATION
4d583dd8	249
64ccd8a8	250	Unfortunately, one of the most daunting tasks faced by newcomers to
64ccd8a8	251	Catalyst is getting it installed. Although a compelling strength of
653f4595	252	Catalyst is that it can easily make use of many of the modules in the
	253	vast repository that is CPAN, this can result in initial installations
	254	that are both time consuming and frustrating. However, there are a
	255	growing number of methods that can dramatically ease this undertaking.
	256	Of these, the following are likely to be applicable to the largest
	257	number of potential new users:
4d583dd8	258
	259	=over 4
	260
	261	=item *
	262
64ccd8a8	263	Matt Trout's C<cat-install>
4d583dd8	264
64ccd8a8	265	Available at L<http://www.shadowcatsystems.co.uk/static/cat-install>,
	266	C<cat-install> can be a quick and painless way to get Catalyst up and
	267	running. Just download the script from the link above and type C<perl
	268	cat-install>.
4d583dd8	269
	270	=item *
	271
	272	Chris Laco's CatInABox
	273
64ccd8a8	274	Download the tarball from
	275	L<http://handelframework.com/downloads/CatInABox.tar.gz> and unpack it
	276	on your machine. Depending on your OS platform, either run C<start.bat>
	277	or C<start.sh>.
4d583dd8	278
	279	=item *
	280
	281	Pre-Built VMWare Images
	282
64ccd8a8	283	Under the VMWare community program, work is ongoing to develop a number
	284	of VMWare images where an entire Catalyst development environment has
	285	already been installed, complete with database engines and a full
	286	complement of Catalyst plugins.
4d583dd8	287
	288	=back
	289
653f4595	290	For additional information and recommendations on Catalyst installation,
14e6feb0	291	please refer to
14e6feb0	292	L<Catalyst::Manual::Installation\|Catalyst::Manual::Installation>.
4d583dd8	293
14e6feb0	294	B<NOTE:> Step-by-step instructions to replicate the environment on
64ccd8a8	295	which this tutorial was developed can be found at
14e6feb0	296	L<Catalyst::Manual::Installation::CentOS4\|Catalyst::Manual::Installation::CentOS4>.
64ccd8a8	297	Using these instructions, you should be able to build a complete CentOS
	298	4.X server with Catalyst and all the plugins required to run this
	299	tutorial.
4d583dd8	300
4d583dd8	301	=head1 DATABASES
4d583dd8	302
653f4595	303	This tutorial will primarily focus on SQLite because of its simplicity
	304	of installation and use; however, modifications in the script required
	305	to support MySQL and PostgreSQL will be presented in Appendix 2.
4d583dd8	306
64ccd8a8	307	B<Note:> One of the advantages of the MVC design patterns is that
	308	applications become much more database independent. As such, you will
	309	notice that only the C<.sql> files used to initialize the database
653f4595	310	change between database systems: the Catalyst code generally remains the
653f4595	311	same.
4d583dd8	312
	313	=head1 WHERE TO GET WORKING CODE
	314
64ccd8a8	315	Each part of the tutorial has complete code available in the main
	316	Catalyst Subversion repository (see the note at the beginning of each
	317	part for the appropriate svn command to use). Additionally, the final
	318	code is available as a ready-to-run tarball at
14e6feb0	319	I<TO_BE_ADDED_TO_FINAL_VERSION>.
4d583dd8	320
a63e6e67	321
4d583dd8	322	=head1 AUTHOR
	323
	324	Kennedy Clark, C<hkclark@gmail.com>
	325
eed93301	326	Please report any errors, issues or suggestions to the author. The
	327	most recent version of the Catlayst Tutorial can be found at
	328	L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/>.
4d583dd8	329
64ccd8a8	330	Copyright 2006, Kennedy Clark, under Creative Commons License
64ccd8a8	331	(L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).
4d583dd8	332
4d583dd8	333