[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.70) 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 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 *

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.

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
653f4595	91	Attempts to provide an example showing current (5.70) 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
653f4595	116	The use of HTML::Widget for automated form processing and validation.
4d583dd8	117
	118	=back
	119
653f4595	120	This tutorial makes the learning process its main priority. For
	121	example, the level of comments in the code found here would like be
	122	considered excessive in a "normal project". Because of their contextual
	123	value, this tutorial will generally favor inline comments over a
	124	separate discussion in the text. It also deliberately tries to
	125	demonstrate multiple approaches to various features (in general, you
	126	should try to be as consistent as possible with your own production
	127	code).
4d583dd8	128
64ccd8a8	129	Furthermore, this tutorial tries to minimize the number of controllers,
	130	models, TT templates, and database tables. Although this does result in
	131	things being a bit contrived at times, the concepts should be applicable
	132	to more complex environments. More complete and complicated example
	133	applications can be found in the C<examples> area of the Catalyst
	134	Subversion repository at
	135	L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>.
4d583dd8	136
64ccd8a8	137	B<Note:> There are a variety of other introductory materials available
	138	through the Catalyst web site and at
	139	L<http://dev.catalyst.perl.org/wiki/UserIntroductions> and
	140	L<http://dev.catalyst.perl.org/>.
4d583dd8	141
4d583dd8	142	=head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
4d583dd8	143
653f4595	144	This tutorial was built using the following resources. Please note that
653f4595	145	you may need to make adjustments for different environments and
64ccd8a8	146	versions:
4d583dd8	147
	148	=over 4
	149
	150	=item *
	151
	152	OS = CentOS 4 Linux (RHEL 4)
	153
	154	=item *
	155
14e6feb0	156	Catalyst v5.6902
4d583dd8	157
	158	=item *
	159
14e6feb0	160	DBIx::Class v0.06003
4d583dd8	161
	162	=item *
	163
	164	Catalyst Plugins
	165
653f4595	166	The plugins used in this tutorial all have sufficiently stable APIs that
	167	you shouldn't need to worry about versions. However, there could be
	168	cases where the tutorial is affected by what version of plugins you
	169	use. The plugins used for this tutorial are:
4d583dd8	170
	171	=over 4
	172
	173	=item *
	174
	175	Catalyst::Plugin::Authentication -- 0.07
	176
	177	=item *
	178
	179	Authentication::Credential::Password -- 0.07
	180
	181	=item *
	182
	183	Catalyst::Plugin::Authentication::Store::DBIC -- 0.06
	184
	185	=item *
	186
	187	Catalyst::Plugin::Authorization::ACL -- 0.06
	188
	189	=item *
	190
	191	Catalyst::Plugin::Authorization::Roles -- 0.04
	192
	193	=item *
	194
	195	Catalyst::Plugin::ConfigLoader -- 0.07
	196
	197	=item *
	198
	199	Catalyst::Plugin::DefaultEnd -- 0.06
	200
	201	=item *
	202
4d583dd8	203	Catalyst::Plugin::HTML::Widget -- 1.1
	204
	205	=item *
	206
	207	Catalyst::Plugin::Session -- 0.05
	208
	209	=item *
	210
	211	Catalyst::Plugin::Session::FastMmap -- 0.12
	212
	213	=item *
	214
	215	Catalyst::Plugin::Session::State::Cookie -- 0.02
	216
	217	=item *
	218
14e6feb0	219	Catalyst::Plugin::Session::Store::FastMmap -- 0.02
4d583dd8	220
	221	=item *
	222
14e6feb0	223	Catalyst::Plugin::StackTrace -- 0.04
4d583dd8	224
	225	=item *
	226
	227	Catalyst::Plugin::Static::Simple -- 0.14
	228
	229	=back
	230
	231	=item *
	232
64ccd8a8	233	Since the web browser is being used on the same box where Perl and the
	234	Catalyst development server is running, the URL of
	235	C<http://localhost:3000> will be used (the Catalyst development server
	236	defaults to port 3000). If you are running Perl on a different box than
	237	where your web browser is located (or using a different port number via
	238	the C<-p> I<port_number> option to the development server), then you
	239	will need to update the URL you use accordingly.
4d583dd8	240
	241	=item *
	242
64ccd8a8	243	Depending on the web browser you are using, you might need to hit
	244	C<Shift+Reload> to pull a fresh page when testing your application at
	245	various points. Also, the C<-k> keepalive option to the development
	246	server can be necessary with some browsers (especially Internet
	247	Explorer).
4d583dd8	248
	249	=back
	250
4d583dd8	251	=head1 CATALYST INSTALLATION
4d583dd8	252
64ccd8a8	253	Unfortunately, one of the most daunting tasks faced by newcomers to
64ccd8a8	254	Catalyst is getting it installed. Although a compelling strength of
653f4595	255	Catalyst is that it can easily make use of many of the modules in the
	256	vast repository that is CPAN, this can result in initial installations
	257	that are both time consuming and frustrating. However, there are a
	258	growing number of methods that can dramatically ease this undertaking.
	259	Of these, the following are likely to be applicable to the largest
	260	number of potential new users:
4d583dd8	261
	262	=over 4
	263
	264	=item *
	265
64ccd8a8	266	Matt Trout's C<cat-install>
4d583dd8	267
64ccd8a8	268	Available at L<http://www.shadowcatsystems.co.uk/static/cat-install>,
	269	C<cat-install> can be a quick and painless way to get Catalyst up and
	270	running. Just download the script from the link above and type C<perl
	271	cat-install>.
4d583dd8	272
	273	=item *
	274
	275	Chris Laco's CatInABox
	276
64ccd8a8	277	Download the tarball from
	278	L<http://handelframework.com/downloads/CatInABox.tar.gz> and unpack it
	279	on your machine. Depending on your OS platform, either run C<start.bat>
	280	or C<start.sh>.
4d583dd8	281
	282	=item *
	283
	284	Pre-Built VMWare Images
	285
64ccd8a8	286	Under the VMWare community program, work is ongoing to develop a number
	287	of VMWare images where an entire Catalyst development environment has
	288	already been installed, complete with database engines and a full
	289	complement of Catalyst plugins.
4d583dd8	290
	291	=back
	292
653f4595	293	For additional information and recommendations on Catalyst installation,
14e6feb0	294	please refer to
14e6feb0	295	L<Catalyst::Manual::Installation\|Catalyst::Manual::Installation>.
4d583dd8	296
14e6feb0	297	B<NOTE:> Step-by-step instructions to replicate the environment on
64ccd8a8	298	which this tutorial was developed can be found at
14e6feb0	299	L<Catalyst::Manual::Installation::CentOS4\|Catalyst::Manual::Installation::CentOS4>.
64ccd8a8	300	Using these instructions, you should be able to build a complete CentOS
	301	4.X server with Catalyst and all the plugins required to run this
	302	tutorial.
4d583dd8	303
4d583dd8	304	=head1 DATABASES
4d583dd8	305
653f4595	306	This tutorial will primarily focus on SQLite because of its simplicity
	307	of installation and use; however, modifications in the script required
	308	to support MySQL and PostgreSQL will be presented in Appendix 2.
4d583dd8	309
64ccd8a8	310	B<Note:> One of the advantages of the MVC design patterns is that
	311	applications become much more database independent. As such, you will
	312	notice that only the C<.sql> files used to initialize the database
653f4595	313	change between database systems: the Catalyst code generally remains the
653f4595	314	same.
4d583dd8	315
	316	=head1 WHERE TO GET WORKING CODE
	317
64ccd8a8	318	Each part of the tutorial has complete code available in the main
	319	Catalyst Subversion repository (see the note at the beginning of each
	320	part for the appropriate svn command to use). Additionally, the final
	321	code is available as a ready-to-run tarball at
14e6feb0	322	I<TO_BE_ADDED_TO_FINAL_VERSION>.
4d583dd8	323
a63e6e67	324
4d583dd8	325	=head1 AUTHOR
	326
	327	Kennedy Clark, C<hkclark@gmail.com>
	328
	329	Please report any errors, issues or suggestions to the author.
	330
64ccd8a8	331	Copyright 2006, Kennedy Clark, under Creative Commons License
64ccd8a8	332	(L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).
4d583dd8	333
4d583dd8	334