[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> for 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<AdvancedCRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>

=item 9

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

=back


=head1 DESCRIPTION

This tutorial provides a nine-part 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 C<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 Catalyst 5.70
practices. For example, the use of C<Catalyst::Plugin::DefaultEnd>,
DBIC, C<Catalyst::Plugin::ConfigLoader> with 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 C<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 * 

How to use HTML::Widget for automated form processing and validation.

=back

This tutorial intentionally seeks to make 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 will need to make adjustments for different environments and
versions:

=over 4

=item * 

OS = CentOS 4 Linux (RHEL 4)

=item * 

Catalyst v5.67

=item * 

DBIx::Class v0.06002

=item * 

Catalyst Plugins

You shouldn't be overly concerned about plugin version numbers, but
there could be cases where the tutorial is impacted by what version
plugins you use.  The plugins used in 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::Dumper -- 0.000002

=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.0

=item *

Catalyst::Plugin::StackTrace -- 0.0

=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 full use of CPAN, a vast repository
of Perl modules, 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

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

B<IMPORTANT:> Step-by-step instructions to replicate the environment on
which this tutorial was developed can be found at
L<Catalyst::Manual::Installation::CentOSTuorial|Catalyst::Manual::Installation::CentOSTuorial>.

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;
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
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/>).

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