X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FIntro.pod;h=182b14a94fab2352c304e928967500a6c6154b57;hp=b63d0517b9aefb214ce69cc17a427c64081f8020;hb=709ea2fce465890b806df6320bb96b0f1a7d27ca;hpb=09f13e1dbbb6a0cb830c64e563ede91903addcb5 diff --git a/lib/Catalyst/Manual/Intro.pod b/lib/Catalyst/Manual/Intro.pod index b63d051..182b14a 100644 --- a/lib/Catalyst/Manual/Intro.pod +++ b/lib/Catalyst/Manual/Intro.pod @@ -14,17 +14,17 @@ with Catalyst, see L. =head2 What is Catalyst? Catalyst is an elegant web application framework, extremely flexible -yet extremely simple. It's similar to Ruby on Rails, Spring (Java), -and L, upon which it was originally based. Its most important -design philosphy is to provide easy access to all the tools you need -to develop web applications, with few restrictions on how you need to -use these tools. However, this does mean that it is always possible to -do things in a different way. Other web frameworks are B -simpler to use, but achieve this by locking the programmer into a -single set of tools. Catalyst's emphasis on flexibility means that you -have to think more to use it. We view this as a feature. For example, -this leads to Catalyst being more suited to system integration tasks -than other web frameworks. +yet extremely simple. It's similar to Ruby on Rails, Spring (Java), and +L, upon which it was originally based. Its most +important design philosphy is to provide easy access to all the tools +you need to develop web applications, with few restrictions on how you +need to use these tools. However, this does mean that it is always +possible to do things in a different way. Other web frameworks are +I simpler to use, but achieve this by locking the programmer +into a single set of tools. Catalyst's emphasis on flexibility means +that you have to think more to use it. We view this as a feature. For +example, this leads to Catalyst being more suited to system integration +tasks than other web frameworks. =head3 MVC @@ -97,17 +97,30 @@ doesn't require mod_rewrite or class and method names in URLs. With Catalyst you register your actions and address them directly. For example: - sub hello : Global { + sub hello : Local { my ( $self, $context ) = @_; $context->response->body('Hello World!'); } Now http://localhost:3000/hello prints "Hello World!". +Note that actions with the C< :Global > attribute are equivalent to +using a C<:Path('action_name') > attribute, so our action could be +equivalently: + + sub hi : Path('hello') { + my ( $self, $context ) = @_; + $context->response->body('Hello World!'); + } + + =item * B -Use L or L. Other -engines are also available. +Use L or L. Another +interesting engine is L - available from CPAN +separately - which will turn the built server into a fully fledged production +ready server (although you'll probably want to run it behind a front end proxy +if you end up using it). =back @@ -158,11 +171,14 @@ running, using the helper scripts described above. =head3 Install -Installation of Catalyst can be a time-consuming and frustrating -effort, due to its large number of dependencies. The easiest way -to get up and running is to use Matt Trout's C -script, from L, -and then install L. +Installation of Catalyst can be a time-consuming effort, due to its +large number of dependencies. Although most of the frustrations +associated with this are now ironed out and a simple C or C are now usually +straightforward, if you still have problems, you can use use Matt +Trout's C script, from +L, and then +install L. # perl cat-install # perl -MCPAN -e 'install Catalyst::Devel' @@ -174,6 +190,16 @@ and then install L. $ cd MyApp $ script/myapp_create.pl controller Library::Login +=head4 Frank Speiser's Amazon EC2 Catalyst SDK + +There are currently two flavors of publicly available Amazon Machine +Images (AMI) that include all the elements you'd need to begin +developing in a fully functional Catalyst environment within +minutes. See +L for +more details. + + =head3 Run $ script/myapp_server.pl @@ -216,14 +242,15 @@ means that this decision is entirely up to you, the programmer; Catalyst doesn't enforce anything. See L for a general discussion of these issues. -All components must inherit from L, which provides a -simple class structure and some common class methods like C and -C (constructor). +Model, View and Controller components must inherit from L, +L and L, respectively. These, in turn, inherit +from L which provides a simple class structure and some +common class methods like C and C (constructor). package MyApp::Controller::Catalog; use strict; - use base 'Catalyst::Base'; + use base 'Catalyst::Controller'; __PACKAGE__->config( foo => 'bar' ); @@ -330,15 +357,15 @@ But first, we need a database. INSERT INTO foo (data) VALUES ('TEST!'); - % sqlite /tmp/myapp.db < myapp.sql + % sqlite3 /tmp/myapp.db < myapp.sql Now we can create a DBIC::Schema model for this database. script/myapp_create.pl model MyModel DBIC::Schema MySchema create=static 'dbi:SQLite:/tmp/myapp.db' -L automatically loads table layouts and -relationships, and converts them into a static schema definition C, -which you can edit later. +L can automaticall load table layouts and +relationships, and convert them into a static schema definition +C, which you can edit later. Use the stash to pass data to your templates. @@ -502,27 +529,54 @@ instance of the model. If the component supports the C method instead of returning the model itself, the return value of C<< $model->ACCEPT_CONTEXT( $c ) >> will be used. -This means that whenever your model/view/controller needs to talk to C<$c> it -gets a chance to do this when it's needed. +This means that whenever your model/view/controller needs to talk to +C<$c> it gets a chance to do this when it's needed. A typical C method will either clone the model and return one with the context object set, or it will return a thin wrapper that contains C<$c> and delegates to the per-application model object. -A typical C method could look like this: - - sub ACCEPT_CONTEXT { - my ( $self, $c, @extra_arguments ) = @_; - bless { %$self, c => $c }, ref($self); - } - -effectively treating $self as a B that gets a new parameter. -C<@extra_arguments> comes from any trailing arguments to -C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...) >>, -C<< $c->view(...) >> etc). - -The life time of this value is B, and not per request. To make this -per request you can use the following technique: +Generally it's a bad idea to expose the context object (C<$c>) in your +model or view code. Instead you use the C subroutine +to grab the bits of the context object that you need, and provide +accessors to them in the model. This ensures that C<$c> is only in +scope where it is neaded which reduces maintenance and debugging +headaches. So, if for example you needed two +L models in the same Catalyst model +code, you might do something like this: + + __PACKAGE__->mk_accessors(qw(model1_schema model2_schema)); + sub ACCEPT_CONTEXT { + my ( $self, $c, @extra_arguments ) = @_; + $self = bless({ %$self, + model1_schema => $c->model('Model1')->schema, + model2_schema => $c->model('Model2')->schema + }, ref($self)); + return $self; + } + +This effectively treats $self as a B that gets a new +parameter. C<@extra_arguments> comes from any trailing arguments to +C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...) +>>, C<< $c->view(...) >> etc). + +In a subroutine in the model code, we can then do this: + + sub whatever { + my ($self) = @_; + my $schema1 = $self->model1_schema; + my $schema2 = $self->model2_schema; + ... + } + +Note that we still want the Catalyst models to be a thin wrapper +around classes that will work independently of the Catalyst +application to promote reusability of code. Here we might just want +to grab the $c->model('DB')->schema so as to get the connection +information from the Catalyst application's configuration for example. + +The life time of this value is B, and not per request. To +make this per request you can use the following technique: Add a field to C<$c>, like C. Then write your C method to look like this: @@ -540,6 +594,9 @@ C method to look like this: } } +For a similar technique to grab a new component instance on each +request, see L. + =head3 Application Class In addition to the Model, View, and Controller components, there's a @@ -549,9 +606,8 @@ configure your application, load plugins, and extend Catalyst. package MyApp; use strict; - use Catalyst qw/-Debug/; # Add other plugins here, e.g. - # for session support - + use parent qw/Catalyst/; + use Catalyst qw/-Debug ConfigLoader Static::Simple/; MyApp->config( name => 'My Application', @@ -629,7 +685,7 @@ information. $c->res->status(404); $c->res->redirect('http://oook.de'); -=item * L +=item * config $c->config $c->config->{root}; @@ -695,9 +751,10 @@ this: # Sets the actions in this controller to be registered with no prefix # so they function identically to actions created in MyApp.pm __PACKAGE__->config->{namespace} = ''; - sub default : Private { + sub default : Path { my ( $self, $context ) = @_; - $context->response->body('Catalyst rocks!'); + $context->response->status(404); + $context->response->body('404 not found'); } 1; @@ -796,6 +853,11 @@ Catalyst ("MyApp::Controller" in the above example), replaces "::" with explanation of the pre-defined meaning of Catalyst component class names. +Note that actions with the C< :Local > attribute are equivalent to the +<:Path('action_name') > so sub foo : Local { } is equivalent to - + + sub foo : Path('foo') { } + =item * B Catalyst also provides a method to build and dispatch chains of actions, @@ -866,26 +928,24 @@ call these built-in private actions in your application class: =over 4 -=item * B +=item * B Called when no other action matches. Could be used, for example, for displaying a generic frontpage for the main app, or an error page for -individual controllers. +individual controllers. B: in older Catalyst applications you +will see C which is roughly speaking equivalent. -If C isn't acting how you would expect, look at using a -L C action (with an empty path string). The difference -is that C takes arguments relative from the namespace and -C I takes arguments relative from the root, regardless -of what controller it's in. Indeed, this is now the recommended way of -handling default situations; the C private controller should -be considered deprecated. -=item * B +=item * B -C is much like C except that it takes no arguments -and it is weighted slightly higher in the matching process. It is -useful as a static entry point to a controller, e.g. to have a static -welcome page. Note that it's also weighted higher than Path. +C is much like C except that it takes no arguments and +it is weighted slightly higher in the matching process. It is useful +as a static entry point to a controller, e.g. to have a static welcome +page. Note that it's also weighted higher than Path. Actually the sub +name C can be called anything you want. The sub attributes are +what determines the behaviour of the action. B: in older +Catalyst applications, you will see C used, which is +roughly speaking equivalent. =item * B @@ -900,9 +960,9 @@ Called at the end of a request, after all matching actions are called. =head4 Built-in actions in controllers/autochaining - Package MyApp::Controller::Foo; + package MyApp::Controller::Foo; sub begin : Private { } - sub default : Private { } + sub default : Path { } sub auto : Private { } You can define built-in private actions within your controllers as @@ -935,15 +995,13 @@ would be called: =item for a request for C - MyApp::begin - MyApp::auto + MyApp::Controller::Foo::auto MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo - MyApp::end + MyApp::Controller::Foo::end =item for a request for C MyApp::Controller::Foo::Bar::begin - MyApp::auto MyApp::Controller::Foo::auto MyApp::Controller::Foo::Bar::auto MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo @@ -963,7 +1021,6 @@ like this: false MyApp::Controller::Foo::Bar::begin - MyApp::auto MyApp::Controller::Foo::Bar::end =back @@ -1164,8 +1221,16 @@ IRC: Mailing lists: - http://lists.rawmode.org/mailman/listinfo/catalyst - http://lists.rawmode.org/mailman/listinfo/catalyst-dev + http://lists.scsys.co.uk/mailman/listinfo/catalyst + http://lists.scsys.co.uk/mailman/listinfo/catalyst-dev + +Wiki: + + http://dev.catalystframework.org/wiki + +FAQ: + + http://dev.catalystframework.org/wiki/faq =head1 AUTHOR