added cookbook example for localtime.

[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;


=head2 Easily working with datetime objects.

If you store datetime data in your tables, you can easily expand this column to
a L<Time::Piece> object which lets you call useful methods like ymd, mon and 
datetime on it.

In order to set it up, add something like the following to your CDBI Model Class,
if you are storing dates as ISO timestamps:

     __PACKAGE__->has_a(
         mycolumn => 'Time::Piece',
         inflate => sub { Time::Piece->strptime( shift, "%FT%H:%M:%S" ) },
         deflate => 'datetime'
     );

or if you prefer to store dates in unix epoch time you can do something like this:

     __PACKAGE__->has_a(
         mycolumn => 'Time::Piece',
         inflate => sub { Time::Piece->strptime( shift, "%s" ) },
         deflate => 'epoch'
     );

If you want to use another format in the database, you can change the strptime call 
to fit your format, and use strftime to return it with your custom format to the 
database during deflate. See the L<Time::Piece> and L<Class::DBI> docs for more info.

=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.