Add comment for RT #31164

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

=head1 NAME

Catalyst::Manual::Tutorial::01_Intro - Catalyst Tutorial - Chapter 1: Introduction


=head1 OVERVIEW

This is B<Chapter 1 of 10> for the Catalyst tutorial.

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

=over 4

=item 1

B<01_Introduction>

=item 2

L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>

=item 3

L<More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>

=item 4

L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>

=item 5

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

=item 6

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

=item 7

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

=item 8

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

=item 9

L<Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>

=item 10

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

=back


=head1 DESCRIPTION

This tutorial provides a multi-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, how to add
authentication and authorization to an existing application, and/or
form management).

The most recent code for the tutorial is included on the Tutorial Virtual
Machine you can download from:

    svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/ CatalystTutorial

This will download the most recent code for each chapter of the
tutorial into the CatalystTutorial directory on your machine.

B<These reference implementations are provided so that when you follow
the tutorial, you can use the code to ensure that your system is set up
correctly (which shouldn't be an issue if you use the Tutorial Virtual
Machine), :-) and that you have not inadvertently made any typographic
errors, or accidentally skipped part of the tutorial.>

B<NOTE: You can use any Perl-supported OS and environment to run
Catalyst.> It should make little or no difference to Catalyst's
operation, B<but this tutorial has been written using the Debian-based
Tutorial Virtual Machine that you can download and use to work through
the full tutorial step by step.  B<WE STRONGLY RECOMMEND THAT YOU USE
THE VIRTUAL MACHINE IMAGE TO WORK THROUGH THE TUTORIAL> to avoid issues
that may crop up if you are working with a different configuration.  We
have tested the Tutorial Virtual Machine to make sure all of the
examples work correctly, but it is hard to guarantee this on other
platforms and versions.

If you would prefer to install directly from CPAN and not use the
Tutorial Virtual machine, you can download the example program and all
the necessary dependencies to your local machine by installing the
C<Task::Catalyst::Tutorial> distribution:

     cpan Task::Catalyst::Tutorial

This will also test to make sure the dependencies are working.  If you
have trouble installing these, please ask for help on the #catalyst
IRC channel, or the Catalyst mailing list.

Subjects covered by the tutorial include:

=over 4

=item * 

A simple application that lists and adds books.

=item *

The use of L<DBIx::Class> (DBIC) for the model (including
some of the more advanced techniques you will probably want to use in
your applications).

=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.9) Catalyst
practices.

=item * 

The use of Template Toolkit (TT).

=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).  (Note: Because we make use of the DBIx::Class Object
Relational Mapping [ORM] layer, out our application will be database
agnostic and can easily be used by any of the databases supported by
DBIx::Class.)

=item * 

The use of L<HTML::FormFu> or L<HTML::FormHandler>
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 likely 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 at
L<http://wiki.catalystframework.org/wiki/resources/catalystexamples> and
in the C<examples> area of the Catalyst Subversion repository at
L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>.
***Todo: update link above?



=head1 STARTING WITH THE TUTORIAL VIRTUAL MACHINE

=over 4

=item 1 

Download the C<debian-live-6.0.1-i386-rescue.iso> image from
L<http://cdimage.debian.org/cdimage/release/current-live/i386/iso-hybrid/>.

=item 2

Uncompress the image:

    tar zxvf CatalystTutorial.tgz

=item 3

Boot the virtual machine using a tool like VMWare Player
L<http://www.vmware.com/products/player> or VirtualBox
L<http://www.virtualbox.org/>.

=item 4

Once you get a login prompt, enter the username B<root> and a password
for C<catalyst>.  You should now be at a prompt that looks like:

    login: root
    password: catalyst
    root@catalyst:~#

=item 5

Type "C<ifconfig>" to get the IP address assigned to the virtual
machine.  You should get output along the lines of:

    eth0  Link encap:Ethernet  HWaddr 00:01:22:3b:45:69
          inet addr:192.168.245.128  Bcast:192.168.245.255  Mask:255.255.255.0
    ...

You want the IP address on the second line below the C<eth0> interface.
The image it design to automatically use a DHCP-assigned address.

If DHCP is not working or is not available in your location, most
virtual machine "host" environments let's you select between one of
several different types of networking between the "guest" and the "host"
machine.

    1) Bridged
    2) NAT
    3) Local host only

The Tutorial Virtual Machine defaults to "Bridged" -- this should result
in the VM acting like another device on your network that will get a
different DHCP IP address than the host machine.  The advantage of this
approach, is that you can easily SSH and web browse to the guest virtual
machine.

In some environments, you might have better luck with "NAT" (Network
Address Translation) mode.  With this configuration, the guest VM shares
the same IP address as the host machine.  The downside of the approach
is that special configuration is required if you want to be able to SSH
or web browse to the guest VM (some virtual machine host environments
let you configure a "static NAT" or "port forwarding" to reach the guest
OS).

"Local host only" mode let's the guest VM and the host machine talk on a
"private subnet" that other devices in your network cannot reach.

Consult the documentation on your virtual machine host environment for
help configuring the options above.

=item 6

B<From your main desktop machine>, open an SSH client and connect to
the IP address found in the previous step.  You should get a login
prompt (accept the SSH key).  Login with the same username and password:
B<root> / B<catalyst>

=item 7

B<Using the SSH session>, change to the sample code directory for
Chapter 3 included with the Tutorial Virtual Machine and start the
Catalyst Development Server:

    $ cd Final/Chapter03
    $ perl scripts/myapp_server -r

=item 8

B<From your main desktop machine>, open a web browser and go to
B<http://A.B.C.D:3000/>, where C<A.B.C.D> is the IP address to your
virtual machine that you looked up in Step 5.  For example, if your
virtual machine is using the IP address C<192.168.0.21>, you would put
the following URL into your web browser:

    http://192.168.0.21:3000/

Make sure you don't forget the B<:3000> to use port 3000 instead of the
usual port 80 that is used by HTTP by default.

You should get a Catalyst Welcome Screen.  If you do, feel free to jump
right in to L<Chapter 2|Catalyst::Manual::Tutorial::02_CatalystBasics>
of the tutorial.  If you don't go get the Catalyst Welcome Screen, go
back and carefully check each of the steps above.

=item 9

B<Optional:> The VI/VIM editor is already installed on the Tutorial
Virtual Machine.  In order to reduce the size of the download, Emacs is
not pre-installed.  Since people obviously have very strong opinions
about which editor is best, :-) Debian fortunately make it very easy to
install Emacs:

    $ aptitude install emacs

=back


=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
(note that trailing zeros in version numbers are not significant and may
get dropped with some techniques for viewing them; for example, Catalyst
v5.80020 might show up as 5.8002):

=over 4

=item * 

Debian 6 (Squeeze)

=item * 

Catalyst v5.90002

=item *

Catalyst::Devel v1.34

=item * 

DBIx::Class v0.08195

=item *

Catalyst::Model::DBIC::Schema v0.54

=item *

Template Toolkit v2.22


=item *

HTML::FormFu -- v0.09004

=item * 

B<NOTE:> You can check the versions you have installed with the
following command (note the slash before the space):

    perl -M<_mod_name_>\ 999

or:

    perl -M<_mod_name_> -e 'print "$<_mod_name_>::VERSION\n"'

For example:

    perl -MCatalyst::Devel\ 999

or:

    perl -MCatalyst::Devel -e 'print "$Catalyst::Devel::VERSION\n";'

=item * 

This tutorial will show URLs in the format of C<http://localhost:3000>,
but if you are running your web browser from outside the Tutorial
Virtual Machine, you will want to substitute the IP address of your VM
for the C<localhost> in the URLs (again, you can get the IP address for
eth0 from the C<ifconfig> command).  For example, if your VM has an
IP address of 192.168.245.128, you will want to use a base URL of
C<http://192.168.245.128:3000>.  Note that the development server
defaults to port 3000 (you can change with with the "-p" option on the
command line.

B<Please Note:> Depending on the web browser you are using, you might need
to hit C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page when
testing your application at various points (see
L<http://en.wikipedia.org/wiki/Bypass_your_cache> for a comprehensive
list of options for each browser).  Also, the C<-k> keepalive option to
the development server can be necessary with some browsers (especially
Internet Explorer).

=back


=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 the Appendix.

B<Note:> One of the advantages of using tools like Catalyst and DBIC 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: most of the code generally remains the
same.


You can jump to the next chapter of the tutorial here:
L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>


=head1 AUTHOR

Kennedy Clark, C<hkclark@gmail.com>

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

Copyright 2006-2010, Kennedy Clark, under the
Creative Commons Attribution Share-Alike License Version 3.0
(L<http://creativecommons.org/licenses/by-sa/3.0/us/>).