+=encoding utf8
+
=head1 NAME
Catalyst::Manual::Cookbook - Cooking with Catalyst
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
# configure email sending
__PACKAGE__->config( email => [qw/SMTP localhost/] );
+L<Catalyst> explains precedence of multiple sources for configuration
+values, how to access the values in your components, and many 'base'
+config variables used internally.
+
See also L<Config::General|Config::General>.
=head1 Skipping your VCS's directories
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.
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 LWP::UserAgent
+=item * L<Catalyst::Test>
-L<http://search.cpan.org/dist/libwww-perl/lib/LWP/UserAgent.pm>
+=item * L<Test::WWW::Mechanize::Catalyst>
-=item HTML::Form
+=item * L<Test::WWW::Mechanize>
-L<http://search.cpan.org/dist/libwww-perl/lib/HTML/Form.pm>
+=item * L<WWW::Mechanize>
-=item HTTP::Message
+=item * L<LWP::UserAgent>
-L<http://search.cpan.org/dist/libwww-perl/lib/HTTP/Message.pm>
+=item * L<HTML::Form>
-=item HTTP::Request
+=item * L<HTTP::Message>
-L<http://search.cpan.org/dist/libwww-perl/lib/HTTP/Request.pm>
+=item * L<HTTP::Request>
-=item HTTP::Request::Common
+=item * L<HTTP::Request::Common>
-L<http://search.cpan.org/dist/libwww-perl/lib/HTTP/Request/Common.pm>
+=item * L<HTTP::Response>
-=item HTTP::Response
+=item * L<HTTP::Status>
-L<http://search.cpan.org/dist/libwww-perl/lib/HTTP/Response.pm>
+=item * L<URI>
-=item HTTP::Status
+=item * L<Test::More>
-L<http://search.cpan.org/dist/libwww-perl/lib/HTTP/Status.pm>
+=item * L<Test::Pod>
-=item URI
+=item * L<Test::Pod::Coverage>
-L<http://search.cpan.org/dist/URI/URI.pm>
+=item * L<prove> (L<Test::Harness>)
-=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