=head1 NAME

Catalyst::Manual::Intro - Introduction to Catalyst

=head1 DESCRIPTION

This should be enough to get you started.

=head2 Quickstart

Everything begins with a small application controller.

    # lib/MyApp.pm
    package MyApp;

    use strict;
    use Catalyst '-Debug';

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

    __PACKAGE__->action( '!default' => sub {
        my ( $self, $c ) = @_;
        $c->response->output('Catalyst rockz!');
    });

    1;

C<name> and C<root> are the only options used by Catalyst itself, C<name> is
the name of your application and C<root> is the root directory for additional
files like templates.

C<!default> is a built in private action that gets called when no other action
matches the requested path.
Private actions (prefixed by !) are normally not addressable from the outside
world, but C<!default> is an exception from this rule.

This should be enough to get you started.

=head1 Testing

Catalyst has a built in http server for testing! (You can later easily use
mod_perl in a production environment)

    perl -I/home/joeuser/myapp/lib -MCatalyst::Test=MyApp -e1 3000

You can also test you application directly from the command line.

    perl -I/home/joeuser/myapp/lib -MCatalyst::Test=MyApp -e1 http://localhost/

=head2 Components

The application controller is everything you need for a simple Catalyst
application, but that would very soon result in a ball of mud,
and thats why we have components (Model/View/Controller).

Catalyst will automatically search for components in lib/MyApp/Model,
lib/MyApp/View and lib/MyApp/Controller.

You normally start a component by inheriting everything from a blueprint,
like Catalyst::Model::CDBI or Catalyst::View::TT.

    # lib/MyApp/View/TT.pm
    package MyApp::View::TT;

    use strict;
    use base 'Catalyst::View::TT';

    1;

Thats all, you can now use $c->forward('MyApp::View::TT') from your actions.

Components without a blueprint should inherit everything they need from
L<Catalyst::Base>.

Add the component to the process chain.

    # lib/MyApp.pm
    package MyApp;

    use strict;
    use Catalyst '-Debug';

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

    __PACKAGE__->action(
        '!default' => sub {
            my ( $self, $c ) = @_;
            $c->stash->{template} = 'index.tt';
        },
        '!end' => sub {
            my ( $self, $c ) = @_;
            $c->forward('MyApp::View::TT') unless $c->response->output;
        }
    );

    1;

C<!end> is another built in private action that gets called at the end of a
request. (C<!begin> is the opposite of C<!end>...suprise...)
So it's mostly used for the View components, to process templates and stuff.

In the example you forwarded processing to MyApp::View::TT, which will render
the template defined in $c->stash->{template} to $c->response->output.

Note that if you forward to a class, Catalyst will automatically call the
process() method of that class, which MyApp::View::TT  inherited from
Catalyst::View::TT.

The stash is a universal hash that you should use to store and pass around all
kind of data during the requests lifetime.

And don't forget the template or you'll get the chance to look at our eyecandy
debug screen. ;)

    [%# root/index.tt #%]
    Hello Catalyst!

A CDBI Model class is equally simple, first create a database.

    -- myapp.sql
    CREATE TABLE foo (
        id INTEGER PRIMARY KEY,
        data TEXT
    );

    CREATE TABLE bar (
        id INTEGER PRIMARY KEY,
        foo INTEGER REFERENCES foo,
        data TEXT
    );

    INSERT INTO foo (data) VALUES ('TEST!');


    % sqlite /tmp/myapp.db < myapp.sql

Then create a CDBI component.

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

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

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

    1;

Thats all, table layouts and relationships are automatically loaded for you.
Use $c->stash to pass data to your templates.

    # lib/MyApp.pm
    package MyApp;

    use strict;
    use Catalyst '-Debug';

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

    __PACKAGE__->action(
        '!end' => sub {
            my ( $self, $c ) = @_;
            $c->stash->{template} ||= 'index.tt';
            $c->forward('MyApp::View::TT') unless $c->response->output;
        },
        'view' => sub {
            my ( $self, $c, $id ) = @_;
            $c->stash->{item} = MyApp::Model::CDBI::Foo->retrieve($id);
        }
    );

    1;

    [%# root/index.tt #%]
    The id is [% item.data %]

Have fun!

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