fixed docs

[catagits/Catalyst-Runtime.git] / lib / Catalyst / Manual / Cookbook.pod

=head1 NAME

Catalyst::Manual::Cookbook - Cooking with Catalyst

=head1 DESCRIPTION

Yummy code like your mum used to bake!

=head1 RECIPES

=head2 Force debug screen

You can force Catalyst to display the debug screen at the end of the request by
placing a die() call in the _end action.

    __PACKAGE__->action(
        '!end' => sub {
            my ( $self, $c ) = @_;
            die "testing";
        }
    );

=head2 Disable statistics

Just add this line to your application class if you don't want those nifty
statistics in your debug messages.

    sub Catalyst::Log::info { }

=head2 Scaffolding

Scaffolding is very simple with Catalyst.
Just use Catalyst::Model::CDBI::CRUD as baseclass.

    # lib/MyApp/Model/CDBI.pm
    package MyApp::Model::CDBI;

    use strict;
    use base 'Catalyst::Model::CDBI::CRUD';

    __PACKAGE__->config(
        dsn           => 'dbi:SQLite:/tmp/myapp.db',
        relationships => 1
    );

    1;

    # lib/MyApp.pm
    package MyApp;

    use Catalyst 'FormValidator';

    __PACKAGE__->config(
        name => 'My Application',
        root => '/home/joeuser/myapp/root'
    );

    __PACKAGE__->action(
        'table' => sub {
            my ( $self, $c ) = @_;
            $c->form( optional => [ MyApp::Model::CDBI::Table->columns ] );
            $c->forward('MyApp::Model::CDBI::Table');
        }
    );

    1;

Modify the $c->form() parameters to match your needs, and don't forget to copy
the templates. ;)

==head2 Serving static files and CSS as text/css

If you want to serve static content (like images, txt or CSS) via Catalyst,
then all you need is the plugin Catalyst::Plugin::Static as well as a small
regex to set the MIME type for CSS to text/css.

    # lib/MyApp.pm
    package MyApp;

    use strict;
    use Catalyst qw/-Debug Static/;
    
    __PACKAGE__->action(

        '!default' => sub {
            my ( $self, $c ) = @_;
	    $c->serve_static;
	},
	    
        '/^.*\.css$/' => sub {
            my ( $self, $c ) = @_;
            $c->serve_static('text/css');
        },
    );

==head2 Uploads with Catalyst

To implement uploads in Catalyst you need to have a HTML form similiar to
this:

    <form action="/upload" method="post" enctype="multipart/form-data">
      <input type="hidden" name="form_submit" value="yes">
      <input type="file" name="my_file">
      <input type="submit" value="Send">
    </form>

It's very important not to forget enctype="multipart/form-data" in form, 
if it's not there, uploads just don't work.

Catalyst Controller module 'upload' action:

    MyApp->action(
    
        'upload' => sub {
            my ($self, $c) = @_;
            if ($c->req->parameters->{form_submit} eq 'yes') {
                my $filename = $c->req->parameters->{my_file};
                if ($filename) {
                    my $fh = $c->req->uploads->{$filename}->{fh};
                    open(NEW_FILE, ">/tmp/$filename") or die
                        "Can't open file for writing: $!";
                    while ($fh->read(my $buf, 32768)) {
                        print NEW_FILE $buf;
                    }
                    close(NEW_FILE);
                }
            }
            $c->stash->{template} = 'upload_form.tt';
            $c->forward('MyApp::V::View');
        },
    );

If you want to upload bigger files than 1MB, then just add to your Controller 
module:

    $CGI::Simple::POST_MAX = 1048576000;

=head1 AUTHOR

Sebastian Riedel, C<sri@oook.de>

=head1 COPYRIGHT

This program is free software, you can redistribute it and/or modify it under
the same terms as Perl itself.