your C<use Catalyst> statement . However, you can also enable it using
environment variable, so you can (for example) get debug info without
modifying your application scripts. Just set C<CATALYST_DEBUG> or
-C<E<lt>MYAPPE<gt>_DEBUG> to a true value.
+C<< <MYAPP>_DEBUG >> to a true value.
=head2 Sessions
=head3 Using a session
Once the session modules are loaded, the session is available as C<<
-$c->session >>, and can be writen to and read from as a simple hash
+$c->session >>, and can be written to and read from as a simple hash
reference.
=head3 EXAMPLE
=head3 More information
-L<http://search.cpan.org/dist/Catalyst-Plugin-Session>
+L<Catalyst::Plugin::Session>
-L<http://search.cpan.org/dist/Catalyst-Plugin-Session-State-Cookie>
+L<Catalyst::Plugin::Session::State::Cookie>
-L<http://search.cpan.org/dist/Catalyst-Plugin-Session-State-URI>
+L<Catalyst::Plugin::Session::State::URI>
-L<http://search.cpan.org/dist/Catalyst-Plugin-Session-Store-FastMmap>
+L<Catalyst::Plugin::Session::Store::FastMmap>
-L<http://search.cpan.org/dist/Catalyst-Plugin-Session-Store-File>
+L<Catalyst::Plugin::Session::Store::File>
-L<http://search.cpan.org/dist/Catalyst-Plugin-Session-Store-DBI>
+L<Catalyst::Plugin::Session::Store::DBI>
=head2 Configure your application
and readable configuration files. It's a great way to keep your
Catalyst application configuration in one easy-to-understand location.
-Now create C<myapp.conf> in your application home:
+Now create F<myapp.conf> in your application home:
name MyApp
=over
-=item
+=item *
INCLUDE_PATH defines the directories that Template Toolkit should search
for the template files.
-=item
+=item *
PRE_PROCESS is used to process configuration options which are common to
every template file.
-=item
+=item *
WRAPPER is a file which is processed with each template, usually used to
easily provide a common header and footer for every page.
changes when they are (inevitably) needed.
The template files that you will create for your application will go
-into root/src, and you don't need to worry about putting the the <html>
+into root/src, and you don't need to worry about putting the <html>
or <head> sections; just put in the content. The WRAPPER will the rest
of the page around your template for you.
-=head3 $c->stash
+=head3 C<< $c->stash >>
Of course, having the template system include the header and footer for
you isn't all that we want our templates to do. We need to be able to
and allows you to truly keep your presentation logic separate from the
rest of your application.
-=head3 $c->uri_for()
+=head3 C<< $c->uri_for() >>
One of my favorite things about Catalyst is the ability to move an
application around without having to worry that everything is going to
the application to be at http://www.mydomain.com/Tools/Calendar, then
all of those links will suddenly break.
-That's where $c->uri_for() comes in. This function will merge its
+That's where C<< $c->uri_for() >> comes in. This function will merge its
parameters with either the base location for the app, or its current
namespace. Let's take a look at a couple of examples.
The first parameter does NOT have a forward slash, and so it will be
relative to the current namespace. If the application is installed at
http://www.domain.com/Calendar. and if the template is called from
-MyApp::Controller::Display, then the link would become
+C<MyApp::Controller::Display>, then the link would become
http://www.domain.com/Calendar/Display/2005/10/24.
If you want to link to a parent uri of your current namespace you can
Further Reading:
-L<http://search.cpan.org/perldoc?Catalyst>
+L<Catalyst>
-L<http://search.cpan.org/perldoc?Catalyst%3A%3AView%3A%3ATT>
+L<Catalyst::View::TT>
-L<http://search.cpan.org/perldoc?Template>
+L<Template>
=head2 Adding RSS feeds
spaces in the filename are handled by the browser.
Put this right before calling C<< $c->res->body >> and your browser
-will download a file named C<Important Orders.csv> instead of
+will download a file named F<Important Orders.csv> instead of
C<export>.
You can also use this to have the browser download content which it
$c->stash->{template} = 'file_upload.html';
}
-C<for my $field ($c-E<gt>req->upload)> loops automatically over all file
+C<< for my $field ($c->req->upload) >> loops automatically over all file
input fields and gets input names. After that is basic file saving code,
just like in single file upload.
Notice: C<die>ing might not be what you want to do, when an error
occurs, but it works as an example. A better idea would be to store
-error C<$!> in $c->stash->{error} and show a custom error template
+error C<$!> in C<< $c->stash->{error} >> and show a custom error template
displaying this message.
For more information about uploads and usable methods look at
Static::Simple is a plugin that will help to serve static content for your
application. By default, it will serve most types of files, excluding some
standard Template Toolkit extensions, out of your B<root> file directory. All
-files are served by path, so if B<images/me.jpg> is requested, then
-B<root/images/me.jpg> is found and served.
+files are served by path, so if F<images/me.jpg> is requested, then
+F<root/images/me.jpg> is found and served.
=head3 Usage
=head3 Configuring
Static content is best served from a single directory within your root
-directory. Having many different directories such as C<root/css> and
-C<root/images> requires more code to manage, because you must separately
-identify each static directory--if you decide to add a C<root/js>
+directory. Having many different directories such as F<root/css> and
+F<root/images> requires more code to manage, because you must separately
+identify each static directory--if you decide to add a F<root/js>
directory, you'll need to change your code to account for it. In
contrast, keeping all static directories as subdirectories of a main
-C<root/static> directory makes things much easier to manage. Here's an
+F<root/static> directory makes things much easier to manage. Here's an
example of a typical root directory structure:
root/
root/static/js/code.js
-All static content lives under C<root/static>, with everything else being
+All static content lives under F<root/static>, with everything else being
Template Toolkit files.
=over 4
=head3 More information
-L<http://search.cpan.org/dist/Catalyst-Plugin-Static-Simple/>
+L<Catalyst::Plugin::Static::Simple>
=head3 Serving manually with the Static plugin with HTTP::Daemon (myapp_server.pl)
This code will only forward to the view if a template has been
previously defined by a controller and if there is not already data in
-C<$c-E<gt>res-E<gt>body>.
+C<< $c->res->body >>.
Next, create a controller to handle requests for the /static path. Use
the Helper to save time. This command will create a stub controller as
-C<lib/MyApp/Controller/Static.pm>.
+F<lib/MyApp/Controller/Static.pm>.
$ script/myapp_create.pl controller Static
When using Apache, you can bypass Catalyst and any Static
plugins/controllers controller by intercepting requests for the
-C<root/static> path at the server level. All that is required is to
+F<root/static> path at the server level. All that is required is to
define a DocumentRoot and add a separate Location block for your static
content. Here is a complete config for this application under mod_perl
1.x:
Catalyst provides a convenient way of testing your application during
development and before deployment in a real environment.
-C<Catalyst::Test> makes it possible to run the same tests both locally
+L<Catalyst::Test> makes it possible to run the same tests both locally
(without an external daemon) and against a remote server via HTTP.
=head3 Tests
-Let's examine a skeleton application's C<t/> directory:
+Let's examine a skeleton application's F<t/> directory:
mundus:~/MyApp chansen$ ls -l t/
total 24
=over 4
-=item C<01app.t>
+=item F<01app.t>
Verifies that the application loads, compiles, and returns a successful
response.
-=item C<02pod.t>
+=item F<02pod.t>
Verifies that all POD is free from errors. Only executed if the C<TEST_POD>
environment variable is true.
-=item C<03podcoverage.t>
+=item F<03podcoverage.t>
Verifies that all methods/functions have POD coverage. Only executed if the
C<TEST_POD> environment variable is true.
two. The second line tests and loads our application in test mode. The
fourth line verifies that our application returns a successful response.
-C<Catalyst::Test> exports two functions, C<request> and C<get>. Each can
+L<Catalyst::Test> exports two functions, C<request> and C<get>. Each can
take three different arguments:
=over 4
request('/my/path');
request('http://www.host.com/my/path');
-=item An instance of C<URI>.
+=item An instance of L<URI>.
request( URI->new('http://www.host.com/my/path') );
-=item An instance of C<HTTP::Request>.
+=item An instance of L<HTTP::Request>.
request( HTTP::Request->new( GET => 'http://www.host.com/my/path') );
=back
-C<request> returns an instance of C<HTTP::Response> and C<get> returns the
+C<request> returns an instance of L<HTTP::Response> and C<get> returns the
content (body) of the response.
=head3 Running tests locally
your application. In C<CGI> or C<FastCGI> it should be the host and path
to the script.
-=head3 C<Test::WWW::Mechanize> and Catalyst
+=head3 L<Test::WWW::Mechanize> and Catalyst
-Be sure to check out C<Test::WWW::Mechanize::Catalyst>. It makes it easy to
+Be sure to check out L<Test::WWW::Mechanize::Catalyst>. It makes it easy to
test HTML, forms and links. A short example of usage:
use Test::More tests => 6;
=over 4
-=item Catalyst::Test
-
-L<Catalyst::Test>
-
-=item Test::WWW::Mechanize::Catalyst
-
-L<http://search.cpan.org/dist/Test-WWW-Mechanize-Catalyst/lib/Test/WWW/Mechanize/Catalyst.pm>
-
-=item Test::WWW::Mechanize
-
-L<http://search.cpan.org/dist/Test-WWW-Mechanize/Mechanize.pm>
-
-=item WWW::Mechanize
-
-L<http://search.cpan.org/dist/WWW-Mechanize/lib/WWW/Mechanize.pm>
+=item * L<Catalyst::Test>
-=item LWP::UserAgent
+=item * L<Test::WWW::Mechanize::Catalyst>
-L<http://search.cpan.org/dist/libwww-perl/lib/LWP/UserAgent.pm>
+=item * L<Test::WWW::Mechanize>
-=item HTML::Form
+=item * L<WWW::Mechanize>
-L<http://search.cpan.org/dist/libwww-perl/lib/HTML/Form.pm>
+=item * L<LWP::UserAgent>
-=item HTTP::Message
+=item * L<HTML::Form>
-L<http://search.cpan.org/dist/libwww-perl/lib/HTTP/Message.pm>
+=item * L<HTTP::Message>
-=item HTTP::Request
+=item * L<HTTP::Request>
-L<http://search.cpan.org/dist/libwww-perl/lib/HTTP/Request.pm>
+=item * L<HTTP::Request::Common>
-=item HTTP::Request::Common
+=item * L<HTTP::Response>
-L<http://search.cpan.org/dist/libwww-perl/lib/HTTP/Request/Common.pm>
+=item * L<HTTP::Status>
-=item HTTP::Response
+=item * L<URI>
-L<http://search.cpan.org/dist/libwww-perl/lib/HTTP/Response.pm>
+=item * L<Test::More>
-=item HTTP::Status
+=item * L<Test::Pod>
-L<http://search.cpan.org/dist/libwww-perl/lib/HTTP/Status.pm>
+=item * L<Test::Pod::Coverage>
-=item URI
+=item * L<prove> (L<Test::Harness>)
-L<http://search.cpan.org/dist/URI/URI.pm>
-
-=item Test::More
-
-L<http://search.cpan.org/dist/Test-Simple/lib/Test/More.pm>
-
-=item Test::Pod
-
-L<http://search.cpan.org/dist/Test-Pod/Pod.pm>
+=back
-=item Test::Pod::Coverage
+=head3 More Information
-L<http://search.cpan.org/dist/Test-Pod-Coverage/Coverage.pm>
+=over 4
-=item prove (Test::Harness)
+=item * L<Catalyst::Plugin::Authorization::Roles>
-L<http://search.cpan.org/dist/Test-Harness/bin/prove>
+=item * L<Catalyst::Plugin::Authorization::ACL>
=back
-=head3 More Information
-
-L<http://search.cpan.org/perldoc?Catalyst::Plugin::Authorization::Roles>
-L<http://search.cpan.org/perldoc?Catalyst::Plugin::Authorization::ACL>
-
=head1 AUTHORS
Catalyst Contributors, see Catalyst.pm