=item *
-The use of L<DBIx::Class|DBIx::Class> (DBIC) for the model (including
+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 *
-The use of L<HTML::FormFu|HTML::FormFu> or L<HTML::FormHandler|HTML::FormHandler>
+The use of L<HTML::FormFu> or L<HTML::FormHandler>
for automated form processing and validation.
=back
You can get more information at
L<http://www.catalystframework.org/calendar/2008/7> or
-L<Perl::Dist::CatInABox|Perl::Dist::CatInABox>.
+L<Perl::Dist::CatInABox>.
=item *
There are currently two flavors of publicly available Amazon Machine
Images (AMI) that include all the elements you'd need to begin
developing in a fully functional Catalyst environment within minutes.
-See L<Catalyst::Manual::Installation|Catalyst::Manual::Installation>
+See L<Catalyst::Manual::Installation>
for more details.
=back
For additional information and recommendations on Catalyst installation,
please refer to
-L<Catalyst::Manual::Installation|Catalyst::Manual::Installation>.
+L<Catalyst::Manual::Installation>.
=head1 DATABASES
cd MyApp_Chapter8/MyApp
CATALYST_DEBUG=0 prove -wl t
-If you wish to include the L<HTML::FormFu|HTML::FormFu> section in your tests,
+If you wish to include the L<HTML::FormFu> section in your tests,
substitute C<MyApp_Chapter9_FormFu> for C<MyApp_Chapter8> in the URL
above (don't forget to "cd" out of the Ch8 directory if you ran the code above).
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
You can checkout the source code for this example from the catalyst
subversion repository as per the instructions in
-L<Catalyst::Manual::Tutorial::01_Intro|Catalyst::Manual::Tutorial::01_Intro>.
+L<Catalyst::Manual::Tutorial::01_Intro>.
=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 (see
-L<Catalyst::Helper|Catalyst::Helper> for more information on helpers).
+L<Catalyst::Helper> for more information on helpers).
Also note that as of Catalyst 5.7000, you will not have the helper
-scripts unless you install both L<Catalyst::Runtime|Catalyst::Runtime>
-and L<Catalyst::Devel|Catalyst::Devel>.
+scripts unless you install both L<Catalyst::Runtime>
+and L<Catalyst::Devel>.
In this first chapter of the tutorial, use the Catalyst C<catalyst.pl>
script to initialize the framework for an application called C<Hello>:
The "C<$c>" here refers to the Catalyst context, which is used to access
the Catalyst application. In addition to many other things, the Catalyst
context provides access to "response" and "request" objects. (See
-L<Catalyst|Catalyst>, L<Catalyst::Response|Catalyst::Response>, and
-L<Catalyst::Request|Catalyst::Request>)
+L<Catalyst>, L<Catalyst::Response>, and
+L<Catalyst::Request>)
C<$c-E<gt>response-E<gt>body> sets the HTTP response (see
-L<Catalyst::Response|Catalyst::Response>), while
+L<Catalyst::Response>), while
C<$c-E<gt>welcome_message> is a special method that returns the welcome
message that you saw in your browser.
The first argument "HTML" tells the script to name the View module "HTML.pm",
which is a commonly used name for TT views. You can name it anything you want,
such as "MyView.pm". If you have more than one view, be sure to set the
-default_view in Hello.pm (See L<Catalyst::View::TT|Catalyst::View::TT> for more
+default_view in Hello.pm (See L<Catalyst::View::TT> for more
details on setting this).
=item *
You can check out the source code for this example from the Catalyst
Subversion repository as per the instructions in
-L<Catalyst::Manual::Tutorial::01_Intro|Catalyst::Manual::Tutorial::01_Intro>.
+L<Catalyst::Manual::Tutorial::01_Intro>.
Please take a look at
L<Catalyst::Manual::Tutorial::01_Intro/CATALYST INSTALLATION> before
=item *
-L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
+L<Catalyst::Plugin::ConfigLoader>
C<ConfigLoader> provides an automatic way to load configurable
parameters for your application from a central
-L<Config::General|Config::General> file (versus having the values
+L<Config::General> file (versus having the values
hard-coded inside your Perl modules). Config::General uses syntax very
similar to Apache configuration files. We will see how to use this
feature of Catalyst during the authentication and authorization sections
(Chapter 5 and Chapter 6).
B<IMPORTANT NOTE:> If you are using a version of
-L<Catalyst::Devel|Catalyst::Devel> prior to version 1.06, be aware that
+L<Catalyst::Devel> prior to version 1.06, be aware that
Catalyst changed the default format from YAML to the more
straightforward C<Config::General> style. This tutorial uses the newer
C<myapp.conf> file for C<Config::General>. However, Catalyst supports
both formats and will automatically use either C<myapp.conf> or
C<myapp.yml> (or any other format supported by
-L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader> and
-L<Config::Any|Config::Any>). If you are using a version of
+L<Catalyst::Plugin::ConfigLoader> and
+L<Config::Any>). If you are using a version of
Catalyst::Devel prior to 1.06, you can convert to the newer format by
simply creating the C<myapp.conf> file manually and deleting
C<myapp.yml>. The default contents of the C<myapp.conf> you create
=item *
-L<Catalyst::Plugin::Static::Simple|Catalyst::Plugin::Static::Simple>
+L<Catalyst::Plugin::Static::Simple>
C<Static::Simple> provides an easy way to serve static content, such as
images and CSS files, from the development server.
dispatch form of action types because of its power and flexibility. It
allows a series of controller methods to be automatically dispatched to
service a single user request. See
-L<Catalyst::Manual::Tutorial::04_BasicCRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>
-and L<Catalyst::DispatchType::Chained|Catalyst::DispatchType::Chained>
+L<Catalyst::Manual::Tutorial::04_BasicCRUD>
+and L<Catalyst::DispatchType::Chained>
for more information on chained actions.
=back
=head2 Create a Catalyst View
When using TT for the Catalyst view, the main helper script is
-L<Catalyst::Helper::View::TT|Catalyst::Helper::View::TT>. You may also
+L<Catalyst::Helper::View::TT>. You may also
come across references to
-L<Catalyst::Helper::View::TTSite|Catalyst::Helper::View::TTSite>, but
+L<Catalyst::Helper::View::TTSite>, but
its use is now deprecated.
Enter the following command to enable the C<TT> style of view rendering
=head1 DATABASE ACCESS WITH DBIx::Class
Catalyst can be used with virtually any form of datastore available via
-Perl. For example, L<Catalyst::Model::DBI|Catalyst::Model::DBI> can be
+Perl. For example, L<Catalyst::Model::DBI> can be
used to access databases through the traditional Perl L<DBI> interface
or you can use a model to access files of any type on the filesystem.
However, most Catalyst applications use some form of object-relational
mapping (ORM) technology to create objects associated with tables in a
-relational database. Matt Trout's L<DBIx::Class|DBIx::Class>
+relational database. Matt Trout's L<DBIx::Class>
(abbreviated as "DBIC") has rapidly emerged as the Perl-based ORM
technology of choice. Most new Catalyst applications rely on
DBIx::Class, as will this tutorial.
Before you continue, make sure your C<myapp.db> database file is in the
application's topmost directory. Now use the model helper with the
C<create=static> option to read the database with
-L<DBIx::Class::Schema::Loader|DBIx::Class::Schema::Loader> and
+L<DBIx::Class::Schema::Loader> and
automatically build the required files for us:
$ script/myapp_create.pl model DB DBIC::Schema MyApp::Schema \
=item *
C<create=static> causes
-L<DBIx::Class::Schema::Loader|DBIx::Class::Schema::Loader> to load the
+L<DBIx::Class::Schema::Loader> to load the
schema as it runs and then write that information out into files.
=item *
=item *
And finally, the C<on_connect_do> string requests that
-L<DBIx::Class::Schema::Loader|DBIx::Class::Schema::Loader> create
+L<DBIx::Class::Schema::Loader> create
foreign key relationships for us (this is not needed for databases such
as PostgreSQL and MySQL, but is required for SQLite). If you take a look
at C<lib/MyApp/Model/DB.pm>, you will see that the SQLite pragma is
when you launch the application).
B<NOTE:> Older versions of
-L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> use the
+L<Catalyst::Model::DBIC::Schema> use the
deprecated DBIx::Class C<load_classes> technique instead of the newer
C<load_namespaces>. For new applications, please try to use
C<load_namespaces> since it more easily supports a very useful DBIC
B<TIP>: You may see the C<$c-E<gt>model('DB::Book')> un-commented above
written as C<$c-E<gt>model('DB')-E<gt>resultset('Book')>. The two are
equivalent. Either way, C<$c-E<gt>model> returns a
-L<DBIx::Class::ResultSet|DBIx::Class::ResultSet> which handles queries
+L<DBIx::Class::ResultSet> which handles queries
against the database and iterating over the set of results that is
returned.
L<DBIx::Class::Manual::Cookbook/Complex WHERE clauses>, with additional
information found at L<DBIx::Class::ResultSet/search>,
L<DBIx::Class::Manual::FAQ/Searching>,
-L<DBIx::Class::Manual::Intro|DBIx::Class::Manual::Intro> and
-L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema>.
+L<DBIx::Class::Manual::Intro> and
+L<Catalyst::Model::DBIC::Schema>.
=head2 Test Run The Application
The Catalyst stash only lasts for a single HTTP request. If you need to
retain information across requests you can use
-L<Catalyst::Plugin::Session|Catalyst::Plugin::Session> (we will use
+L<Catalyst::Plugin::Session> (we will use
Catalyst sessions in the Authentication chapter of the tutorial).
=item *
markup or code if you don't "neutralize" those fields). In addition to
"| html", Template Toolkit has a variety of other useful filters that
can found in the documentation for
-L<Template::Filters|Template::Filters>.
+L<Template::Filters>.
=head1 RUNNING THE APPLICATION FROM THE COMMAND LINE
Once your controller logic has processed the request from a user, it
forwards processing to your view in order to generate the appropriate
response output. Catalyst uses
-L<Catalyst::Action::RenderView|Catalyst::Action::RenderView> by default
+L<Catalyst::Action::RenderView> by default
to automatically perform this operation. If you look in
C<lib/MyApp/Controller/Root.pm>, you should see the empty definition for
the C<sub end> method:
=item *
Because the definition includes an C<ActionClass> attribute, the
-L<Catalyst::Action::RenderView|Catalyst::Action::RenderView> logic will
+L<Catalyst::Action::RenderView> logic will
be executed B<after> any code inside the definition of C<sub end> is
-run. See L<Catalyst::Manual::Actions|Catalyst::Manual::Actions> for
+run. See L<Catalyst::Manual::Actions> for
more information on C<ActionClass>.
=item *
C<RenderView> logic by adding your own code inside the empty method body
(C<{}>) created by the Catalyst Helpers when we first ran the
C<catalyst.pl> to initialize our application. See
-L<Catalyst::Action::RenderView|Catalyst::Action::RenderView> for more
+L<Catalyst::Action::RenderView> for more
detailed information on how to extend C<RenderView> in C<sub end>.
=back
processing for that request. The "Stash" section should show a
summarized version of the DBIC book model objects. If desired, you can
adjust the summarization logic (called "scrubbing" logic) -- see
-L<Catalyst::Action::RenderView|Catalyst::Action::RenderView> for
+L<Catalyst::Action::RenderView> for
details.
Note that you shouldn't need to worry about "normal clients" using this
functionality yourself, another option is to use a "CRUD builder" type
of tool to automate the process. You get less control, but it can be
quick and easy. For example, see
-L<Catalyst::Plugin::AutoCRUD|Catalyst::Plugin::AutoCRUD>,
-L<CatalystX::CRUD|CatalystX::CRUD>, and
-L<CatalystX::CRUD::YUI|CatalystX::CRUD::YUI>.
+L<Catalyst::Plugin::AutoCRUD>,
+L<CatalystX::CRUD>, and
+L<CatalystX::CRUD::YUI>.
You can check out the source code for this example from the Catalyst
Subversion repository as per the instructions in
-L<Catalyst::Manual::Tutorial::01_Intro|Catalyst::Manual::Tutorial::01_Intro>.
+L<Catalyst::Manual::Tutorial::01_Intro>.
=head1 FORMLESS SUBMISSION
The TT C<USE> directive allows access to a variety of plugin modules
(TT plugins, that is, not Catalyst plugins) to add extra functionality
to the base TT capabilities. Here, the plugin allows
-L<Data::Dumper|Data::Dumper> "pretty printing" of objects and
+L<Data::Dumper> "pretty printing" of objects and
variables. Other than that, the rest of the code should be familiar
from the examples in Chapter 3.
with the base method and delete feature below. But Chained dispatch
is capable of far more. For additional information, see
L<Catalyst::Manual::Intro/Action types>,
-L<Catalyst::DispatchType::Chained|Catalyst::DispatchType::Chained>,
+L<Catalyst::DispatchType::Chained>,
and the 2006 Advent calendar entry on the subject:
L<http://www.catalystframework.org/calendar/2006/10>.
exists "/root/dev/MyApp/script/../lib/MyApp/Model/DB.pm"
Notice that we modified our use of the helper slightly: we told
-it to include the L<DBIx::Class::TimeStamp|DBIx::Class::TimeStamp>
+it to include the L<DBIx::Class::TimeStamp>
in the C<load_components> line of the Result Classes.
If you open C<lib/MyApp/Schema/Result/Book.pm> in your editor you should
You can checkout the source code for this example from the catalyst
subversion repository as per the instructions in
-L<Catalyst::Manual::Tutorial::01_Intro|Catalyst::Manual::Tutorial::01_Intro>.
+L<Catalyst::Manual::Tutorial::01_Intro>.
=head1 BASIC AUTHENTICATION
C<many_to_many> relationship information to the User Result Source file.
As with the Book, BookAuthor, and Author files in
L<Chapter 3|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>,
-L<DBIx::Class::Schema::Loader|DBIx::Class::Schema::Loader> has
+L<DBIx::Class::Schema::Loader> has
automatically created the C<has_many> and C<belongs_to> relationships
for the new User, UserRole, and Role tables. However, as a convenience
for mapping Users to their assigned roles (see
=head2 Configure Authentication
There are a variety of ways to provide configuration information to
-L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication>.
+L<Catalyst::Plugin::Authentication>.
Here we will use
-L<Catalyst::Authentication::Realm::SimpleDB|Catalyst::Authentication::Realm::SimpleDB>
+L<Catalyst::Authentication::Realm::SimpleDB>
because it automatically sets a reasonable set of defaults for us. Open
C<lib/MyApp.pm> and place the following text above the call to
C<__PACKAGE__-E<gt>setup();>:
</Plugin::Authentication>
B<TIP:> Here is a short script that will dump the contents of
-C<MyApp->config> to L<Config::General|Config::General> format in
+C<MyApp->config> to L<Config::General> format in
C<myapp.conf>:
$ CATALYST_DEBUG=0 perl -Ilib -e 'use MyApp; use Config::General;
exactly what you want -- the C<flash> message will get displayed on
the next screen where it's appropriate, but it won't "keep showing up"
after that first time (unless you reset it). Please refer to
-L<Catalyst::Plugin::Session|Catalyst::Plugin::Session> for additional
+L<Catalyst::Plugin::Session> for additional
information.
You can checkout the source code for this example from the catalyst
subversion repository as per the instructions in
-L<Catalyst::Manual::Tutorial::01_Intro|Catalyst::Manual::Tutorial::01_Intro>.
+L<Catalyst::Manual::Tutorial::01_Intro>.
=head1 BASIC AUTHORIZATION
=head1 LOG STATEMENTS
Folks in the former group can use Catalyst's C<$c-E<gt>log> facility.
-(See L<Catalyst::Log|Catalyst::Log> for more detail.) For example, if
+(See L<Catalyst::Log> for more detail.) For example, if
you add the following code to a controller action method:
$c->log->info("Starting the foreach loop here");
$c->log->error
$c->log->fatal
-You can also use L<Data::Dumper|Data::Dumper> in both Catalyst code
+You can also use L<Data::Dumper> in both Catalyst code
(C<use Data::Dumper; $c-E<gt>log-E<gt>debug("\$var is: ".Dumper($var));)>)
and TT templates (C<[% Dumper.dump(book) %]>.
Use C<sudo aptitude install perl-doc> to do that.
For example, you could make a copy of
-L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication>
+L<Catalyst::Plugin::Authentication>
with the following command:
mkdir -p lib/Catalyst/Plugin; cp \
There are a variety of options you can use, such as 'undef', 'all',
'service', 'context', 'parser' and 'provider'. See
-L<Template::Constants|Template::Constants> for more information
+L<Template::Constants> for more information
(remove the C<DEBUG_> portion of the name shown in the TT docs and
convert to lower case for use inside Catalyst).
You can check out the source code for this example from the Catalyst
Subversion repository as per the instructions in
-L<Catalyst::Manual::Tutorial::01_Intro|Catalyst::Manual::Tutorial::01_Intro>.
+L<Catalyst::Manual::Tutorial::01_Intro>.
For an excellent introduction to learning the many benefits of testing
your Perl applications and modules, you might want to read 'Perl Testing:
Although the Catalyst helper scripts provide a basic level of checks
"for free," testing can become significantly more helpful when you write
your own script to exercise the various parts of your application. The
-L<Test::WWW::Mechanize::Catalyst|Test::WWW::Mechanize::Catalyst> module
+L<Test::WWW::Mechanize::Catalyst> module
is very popular for writing these sorts of test cases. This module
-extends L<Test::WWW::Mechanize|Test::WWW::Mechanize> (and therefore
-L<WWW::Mechanize|WWW::Mechanize>) to allow you to automate the action of
+extends L<Test::WWW::Mechanize> (and therefore
+L<WWW::Mechanize>) to allow you to automate the action of
a user "clicking around" inside your application. It gives you all the
benefits of testing on a live system without the messiness of having to
use an actual web server, and a real person to do the clicking.
The C<live_app.t> test cases uses copious comments to explain each step
of the process. In addition to the techniques shown here, there are a
variety of other methods available in
-L<Test::WWW::Mechanize::Catalyst|Test::WWW::Mechanize::Catalyst> (for
+L<Test::WWW::Mechanize::Catalyst> (for
example, regex-based matching). Consult the documentation for more
detail.
B<TIP>: For I<unit tests> vs. the "full application tests" approach used
-by L<Test::WWW::Mechanize::Catalyst|Test::WWW::Mechanize::Catalyst>, see
-L<Catalyst::Test|Catalyst::Test>.
+by L<Test::WWW::Mechanize::Catalyst>, see
+L<Catalyst::Test>.
B<Note:> The test script does not test the C<form_create> and
C<form_create_do> actions. That is left as an exercise for the reader
You may wish to leverage the techniques discussed in this tutorial to
maintain both a "production database" for your live application and a
"testing database" for your test cases. One advantage to
-L<Test::WWW::Mechanize::Catalyst|Test::WWW::Mechanize::Catalyst> is that
+L<Test::WWW::Mechanize::Catalyst> is that
it runs your full application; however, this can complicate things when
you want to support multiple databases.
=head1 DESCRIPTION
-This portion of the tutorial explores L<HTML::FormFu|HTML::FormFu> and
+This portion of the tutorial explores L<HTML::FormFu> and
how it can be used to manage forms, perform validation of form input,
as well as save and restore data to/from the database. This was written
using HTML::FormFu version 0.05001.
See
-L<Catalyst::Manual::Tutorial::09_AdvancedCRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
+L<Catalyst::Manual::Tutorial::09_AdvancedCRUD>
for additional form management options other than
-L<HTML::FormFu|HTML::FormFu>.
+L<HTML::FormFu>.
=head1 HTML::FormFu FORM CREATION
-This section looks at how L<HTML::FormFu|HTML::FormFu> can be used to
+This section looks at how L<HTML::FormFu> can be used to
add additional functionality to the manually created form from Chapter 4.
=head2 Inherit From Catalyst::Controller::HTML::FormFu
First, change your C<lib/MyApp/Controller/Books.pm> to inherit from
-L<Catalyst::Controller::HTML::FormFu|Catalyst::Controller::HTML::FormFu>
+L<Catalyst::Controller::HTML::FormFu>
by changing the C<extends> line from the default of:
BEGIN {extends 'Catalyst::Controller'; }
=head2 Create a Form Config File
Although C<HTML::FormFu> supports any configuration file handled by
-L<Config::Any|Config::Any>, most people tend to use YAML. First
+L<Config::Any>, most people tend to use YAML. First
create a directory to hold your form configuration files:
mkdir -p root/forms/books
=head1 HTML::FormFu VALIDATION AND FILTERING
-Although the use of L<HTML::FormFu|HTML::FormFu> in the previous section
+Although the use of L<HTML::FormFu> in the previous section
did provide an automated mechanism to build the form, the real power of
this module stems from functionality that can automatically validate and
filter the user input. Validation uses constraints to be sure that
=item *
Constraints are added to provide validation of the user input. See
-L<HTML::FormFu::Constraint|HTML::FormFu::Constraint> for other
+L<HTML::FormFu::Constraint> for other
constraints that are available.
=item *
A variety of filters are run on every field to remove and escape
-unwanted input. See L<HTML::FormFu::Filter|HTML::FormFu::Filter>
+unwanted input. See L<HTML::FormFu::Filter>
for more filter options.
=back
If you are having difficulty with YAML config above, please save the
below into the file C<formfu_create.conf> and delete the
C<formfu_create.yml> file. The below is in
-L<Config::General|Config::General> format which follows the syntax of
+L<Config::General> format which follows the syntax of
Apache config files.
constraints Required
=head1 DESCRIPTION
This portion of the tutorial explores
-L<HTML::FormHandler|HTML::FormHandler> and how it can be used to manage
+L<HTML::FormHandler> and how it can be used to manage
forms, perform validation of form input, and save and restore data
to or from the database. This was written using HTML::FormHandler version
0.28001.
See
-L<Catalyst::Manual::Tutorial::09_AdvancedCRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
+L<Catalyst::Manual::Tutorial::09_AdvancedCRUD>
for additional form management options other than
-L<HTML::FormHandler|HTML::FormHandler>.
+L<HTML::FormHandler>.
=head1 Install HTML::FormHandler
=head1 HTML::FormHandler FORM CREATION
-This section looks at how L<HTML::FormHandler|HTML::FormHandler> can be used to
+This section looks at how L<HTML::FormHandler> can be used to
add additional functionality to the manually created form from Chapter 4.
=back
For CentOS users (see
-L<Catalyst::Manual::Installation::CentOS4|Catalyst::Manual::Installation::CentOS4>),
+L<Catalyst::Manual::Installation::CentOS4>),
you can use the following commands to install the software and start the MySQL
daemon:
projects / catagits/Catalyst-Manual.git / commitdiff