Catalyst::Manual::Tutorial - Catalyst Tutorial: Overview
-
-
=head1 DESCRIPTION
The Catalyst framework is a flexible and comprehensive environment for
quickly building high-functionality web applications. This tutorial is
-design to provide a rapid introduction to its basics and most commonly
-used features while focusing on real-world best practices.
+designed to provide a rapid introduction to its basics and its most
+commonly used features while focusing on real-world best practices.
-The tutorial is broken down into the following sections:
+The tutorial is divided into the following sections:
=over 4
=item *
-L<Introduction|Catalyst::Manual::Tutorial_Intro>
-
-=item *
-
-L<Catalyst Basics|Catalyst::Manual::Tutorial_CatalystBasics>
+L<Introduction|Catalyst::Manual::Tutorial::Intro>
=item *
-L<CRUD|Catalyst::Manual::Tutorial_BasicCRUD>
+L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
=item *
-L<Authentication|Catalyst::Manual::Tutorial_Authentication>
+L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
=item *
-L<Authorization|Catalyst::Manual::Tutorial_Authorization>
+L<Authentication|Catalyst::Manual::Tutorial::Authentication>
=item *
-L<Debugging|Catalyst::Manual::Tutorial_Debugging>
+L<Authorization|Catalyst::Manual::Tutorial::Authorization>
=item *
-L<Testing|Catalyst::Manual::Tutorial_Testing>
+L<Testing|Catalyst::Manual::Tutorial::Testing>
=item *
-L<CRUD|Catalyst::Manual::Tutorial_AdvancedCRUD>
+L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
=item *
-L<Appendicies|Catalyst::Manual::Tutorial_Appendicies>
+L<Appendices|Catalyst::Manual::Tutorial::Appendices>
=back
-
-Full source code is available for each section via the main Catalyst
-Subversion repository at
-L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>. See the
-end of each section for the specifics on retrieving code for that
-section.
-
A tarball of the final application is available at
C<to_be_compled_in_final_version>.
DATABASE ACCESS WITH DBIx::Class
-=over 4
-
=item *
Create a DBIC Schema File
=item *
-Use Catalyst::Model::DBIC::Schema To Load The Model Class
+Use Catalyst::Model::DBIC::Schema to Load the Model Class
=back
=item *
-Create a Catalyst View Using TTSITE
+Create a Catalyst View Using TTSite
=item *
=back
-
=head2 Part 3: Basic CRUD
=over 4
=item *
-Add Method to Display The Form
+Add a Method to Display the Form
=item *
=item *
-Test Out The Form
+Test Out the Form
=back
=back
-
=head2 Part 4: Authentication
=over 4
=back
-
=head2 Part 5: Authorization
=over 4
=item *
-Update Plugins to Include Support for Authorization
+Update Plugins to Include Support for Authorization
=item *
=back
-
=head2 Part 6: Debugging
=over 4
=back
-
=head2 Part 7: Testing
=over 4
=back
-
=head2 Part 8: Advanced CRUD
=over 4
=back
-
=head2 Part 9: Appendices
=over 4
Catalyst::Manual::Tutorial::CatalystBasics - Catalyst Tutorial - Part 2: Catalyst Application Development Basics
-
=head1 OVERVIEW
This is B<Part 2 of 9> for the Catalyst tutorial.
=item 3
-L<Basic CRUD|Catalyst::Manual::Tutorial_BasicCRUD>
+L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
=item 4
=item 8
-L<AdvancedCRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
+L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
=item 9
-L<Appendicies|Catalyst::Manual::Tutorial::Appendicies>
+L<Appendices|Catalyst::Manual::Tutorial::Appendicies>
=back
-
-
=head1 DESCRIPTION
In this part of the tutorial, we will create a very basic Catalyst web
Model/View/Controller (MVC) provides an architecture that facilitates a
clean "separation of control" between the different portions of your
-application. Given that many other documents cover this subject in
+application. Given that many other documents cover this subject in
detail, MVC will not be discussed in depth here (for an excellent
introduction to MVC and general Catalyst concepts, please see
-L<Catalyst::Manual::About|Catalyst::Manual::About>. In short:
+L<Catalyst::Manual::About>. In short:
=over 4
=item * Model
-In most applications, the model equates to the objects that are created
-from and saved to your SQL database.
+The model usually represents a data store. In most applications, the
+model equates to the objects that are created from and saved to your SQL
+database.
=item * View
The view takes model objects and renders them into something for the end
-user to look at. Normally this involves a template-generation tool that
+user to look at. Normally this involves a template-generation tool that
creates HTML for the user's web browser, but it could easily be code
-that generates other forms such as PDF documents or Excel spreadsheets.
+that generates other forms such as PDF documents, e-mails, or Excel
+spreadsheets.
=item * Controller
=item * ORM
-The use Object-Relational Mapping (ORM) technology for database access
-(specifically, ORM provides an automated means to persist and restore
-objects to/from a relational database).
+The use of Object-Relational Mapping (ORM) technology for database
+access. Specifically, ORM provides an automated and standardized means
+to persist and restore objects to/from a relational database.
=back
IMPORTANT: Does not work yet. Will be completed for final version.
-
=head1 CREATE A CATALYST PROJECT
Catalyst provides a number of helper scripts that can be used to quickly
-flesh out the basic structure of your application. All Catalyst
-projects begin with the C<catalyst.pl> helper.
+flesh out the basic structure of your application. All Catalyst projects
+begin with the C<catalyst.pl> helper.
In the case of this tutorial, use the Catalyst C<catalyst.pl> script to
initialize the framework for an application called C<MyApp>:
The C<catalyst.pl> helper script will display the names of the
directories and files it creates.
-Though it's obviously too early for any significant celebration, we
-already have a functioning application. Run the following command to
-run this application with the built-in development web server:
+Though it's too early for any significant celebration, we already have a
+functioning application. Run the following command to run this
+application with the built-in development web server:
$ script/myapp_server.pl
greeted by the Catalyst welcome screen. Press Ctrl-C to break out of
the development server.
-
-
=head1 CREATE A SQLITE DATABASE
In this step, we make a text file with the required SQL commands to
INSERT INTO book_authors VALUES (5, 8);
B<TIP>: See Appendix 1 for tips on removing the leading spaces when
-cutting and pasting example code from Pod documents.
+cutting and pasting example code from POD documents.
Then use the following command to build a C<myapp.db> SQLite database:
your OS command prompt.
-
=head1 EDIT THE LIST OF CATALYST PLUGINS
One of the greatest benefits of Catalyst is that it has such a large
L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
-C<ConfigLoader> provides an automatic way to load your configurable
+C<ConfigLoader> provides an automatic way to load configurable
parameters for your application from a central YAML file (versus having
the values hard-coded inside your Perl modules). If you have not been
exposed to YAML before, it is a human-readable data serialization format
see how to use this feature of Catalyst during the authentication and
authorization sections (Part 4 and Part 5).
-
=item *
-L<Catalyst::Plugin::Static::Simple|Catalyst::Plugin::Static::Simple>
+L<Catalyst::Plugin::Static::Simple>
C<Static::Simple> provides an easy method of serving static content such
as images and CSS files under the development server.
=item *
-L<Catalyst::Plugin::Dumper|Catalyst::Plugin::Dumper>
+L<Catalyst::Plugin::Dumper>
-Allows you to easily use L<Data::Dumper|Data::Dumper> to dump variables
+Allows you to easily use L<Data::Dumper> to dump variables
to the logs, for example:
$c->log->dumper($myvar);
Adds a stack trace to the standard Catalyst "debug screen" (this is the
screen Catalyst sends to your browser when an error occurs).
-Note: L<Dumper|Catalyst::Plugin::Dumper> output appears on the
-console/telnet/SSH window where you issue the C<script/myapp_server.pl>
-command. L<StackTrace|Catalyst::Plugin::StackTrace> output appears in
-your browser.
+Note: L<Dumper|Catalyst::Plugin::Dumper> output appears on the console
+window where you issue the C<script/myapp_server.pl> command.
+L<StackTrace|Catalyst::Plugin::StackTrace> output appears in your
+browser.
=item *
with "?" or "&" depending on where it is in the URL) to I<force> the
debug screen at the end of the Catalyst request processing cycle.
-TIP: Many Catalyst-related documents predate
+B<TIP>: Many Catalyst-related documents predate
L<DefaultEnd|Catalyst::Plugin::DefaultEnd> and suggest that you add an
C<end> action to your application class (C<MyApp.pm>) or Root.pm
(C<MyApp/Controller/Root.pm>). In most of these cases, you can convert
the plugin names across multiple lines as shown here, or place them all
on one (or more) lines as with the default configuration.
-
-
=head1 DATABASE ACCESS WITH C<DBIx::Class>
Catalyst can be used with virtually any form of persistent datastore
Catalyst::Manual::Tutorial::Intro - Catalyst Tutorial - Part 1: Introduction
-
=head1 OVERVIEW
-This is B<Part 1 of 9> for the Catalyst tutorial.
+This is B<Part 1 of 9> of the Catalyst Tutorial.
L<Tutorial Overview|Catalyst::Manual::Tutorial>
=item 3
-L<Basic CRUD|Catalyst::Manual::Tutorial_BasicCRUD>
+L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
=item 4
=item 8
-L<AdvancedCRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
+L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
=item 9
-L<Appendicies|Catalyst::Manual::Tutorial::Appendicies>
+L<Appendices|Catalyst::Manual::Tutorial::Appendices>
=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
+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
=item *
-The use of C<DBIx::Class> (DBIC) for the model.
+The use of L<DBIx::Class> (DBIC) for the model.
=item *
-How to write CRUD (Create, Read, Update and Delete) operations in Catalyst.
+How to write CRUD (Create, Read, Update, and Delete) operations in
+Catalyst.
=item *
=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
+Attempts to provide an example showing current (5.70) Catalyst
+practices. For example, the use of L<Catalyst::Plugin::DefaultEnd>,
+DBIC, L<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 C<Catalyst::Helper::View::TTSite> view helper.
+The use of Template Toolkit (TT) and the
+L<Catalyst::Helper::View::TTSite> view helper.
=item *
-Useful techniques for troubleshooting and debugging Catalyst applications.
+Useful techniques for troubleshooting and debugging Catalyst
+applications.
=item *
-The use of SQLite as a database (with code also provided for MySQL and PostgreSQL).
+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.
+The use of 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).
+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
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
+This tutorial was built using the following resources. Please note that
+you may need to make adjustments for different environments and
versions:
=over 4
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:
+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
=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:
+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
=back
-B<IMPORTANT:> For additional information and recommendations on Catalyst
-installation, please refer to
-L<Catalyst::Manual::Installation|Catalyst::Manual::Installation>.
+For additional information and recommendations on Catalyst installation,
+please refer to L<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>.
+L<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;
-however, modifications in the script required to support MySQL and
-PostgreSQL will be presented in Appendix 2.
+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.
-
-
+change between database systems: the Catalyst code generally remains the
+same.
=head1 WHERE TO GET WORKING CODE
code is available as a ready-to-run tarball at
TO_BE_ADDED_TO_FINAL_VERSION.
-
=head1 AUTHOR
Kennedy Clark, C<hkclark@gmail.com>
projects / catagits/Catalyst-Runtime.git / commitdiff