X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FCookbook.pod;h=75bae02494968e719d0d357caa1f8a8025305a8e;hp=2ce3a56f6b548b75af1e86fa636ca9e9425e6e5e;hb=ca7528dfa8625d0ed6688f2bb93372ab3d958881;hpb=c718cfb669a068d7cfebc8b155ea1aec7d5cc84e diff --git a/lib/Catalyst/Manual/Cookbook.pod b/lib/Catalyst/Manual/Cookbook.pod index 2ce3a56..75bae02 100644 --- a/lib/Catalyst/Manual/Cookbook.pod +++ b/lib/Catalyst/Manual/Cookbook.pod @@ -62,10 +62,11 @@ nifty statistics in your debug messages. =head2 Enable debug status in the environment Normally you enable the debugging info by adding the C<-Debug> flag to -your C 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 or -CMYAPPE_DEBUG> to a true value. +your C statement (or C<__PACKAGE__->setup(qw/-Debug/) +). 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 or CMYAPPE_DEBUG> to a +true value. =head2 Sessions @@ -112,11 +113,12 @@ reference. =head3 EXAMPLE - use Catalyst qw/ - Session - Session::Store::FastMmap - Session::State::Cookie - /; + use parent qw/Catalyst/; + __PACKAGE__->setup( qw/ + Session + Session::Store::FastMmap + Session::State::Cookie + /;) ## Write data into the session @@ -160,36 +162,27 @@ You configure your application with the C method in your application class. This can be hard-coded, or brought in from a separate configuration file. -=head3 Using YAML +=head3 Using Config::General -YAML is a method for creating flexible and readable configuration -files. It's a great way to keep your Catalyst application -configuration in one easy-to-understand location. +L is a method for creating flexible +and readable configuration files. It's a great way to keep your +Catalyst application configuration in one easy-to-understand location. -In your application class (e.g. C): +Now create C in your application home: - use YAML; - # application setup - __PACKAGE__->config( YAML::LoadFile(__PACKAGE__->config->{'home'} . '/myapp.yml') ); - __PACKAGE__->setup; - -Now create C in your application home: - - --- #YAML:1.0 - # DO NOT USE TABS FOR INDENTATION OR label/value SEPARATION!!! - name: MyApp + name MyApp # session; perldoc Catalyst::Plugin::Session::FastMmap - session: - expires: '3600' - rewrite: '0' - storage: '/tmp/myapp.session' + + expires 3600 + rewrite 0 + storage /tmp/myapp.session + # emails; perldoc Catalyst::Plugin::Email # this passes options as an array :( - email: - - SMTP - - localhost + Mail SMTP + Mail localhost This is equivalent to: @@ -208,7 +201,7 @@ This is equivalent to: # configure email sending __PACKAGE__->config->{email} = [qw/SMTP localhost/]; -See also L. +See also L. =head1 Skipping your VCS's directories @@ -275,12 +268,13 @@ in the previous example. The L plugin is required when implementing roles: - use Catalyst qw/ - Authentication - Authentication::Credential::Password - Authentication::Store::Htpasswd - Authorization::Roles - /; + use parent qw/Catalyst/; + __PACKAGE__->setup (qw/ + Authentication + Authentication::Credential::Password + Authentication::Store::Htpasswd + Authorization::Roles + /); Roles are implemented automatically when using L: @@ -409,10 +403,11 @@ the user is a member. =head3 EXAMPLE - use Catalyst qw/Authentication - Authentication::Credential::Password - Authentication::Store::Htpasswd - Authorization::Roles/; + use parent qw/Catalyst/; + __PACKAGE__->setup( qw/Authentication + Authentication::Credential::Password + Authentication::Store::Htpasswd + Authorization::Roles/); __PACKAGE__->config->{authentication}{htpasswd} = "passwdfile"; @@ -505,10 +500,11 @@ action, so that only a qualified moose feeder can perform that action. The Authorization::Roles plugin let's us perform role based access control checks. Let's load it: - use Catalyst qw/ + use parent qw/Catalyst/; + __PACKAGE__->setup(qw/ Authentication # yadda yadda Authorization::Roles - /; + /); And now our action should look like this: @@ -635,6 +631,38 @@ Cat app as C. See L. +=head2 Create accessors to preload static data once per server instance + +When you have data that you want to load just once from the model at +server load instead of for each request, use mk_group_accessors to +create accessors and tie them to resultsets in your package that +inherits from DBIx::Class::Schema + + package My::Schema; + use base qw/DBIx::Class::Schema/; + __PACKAGE__->register_class('RESULTSOURCEMONIKER', + 'My::Schema::RESULTSOURCE'); + __PACKAGE__->mk_group_accessors('simple' => + qw(ACCESSORNAME1 ACCESSORNAME2 ACCESSORNAMEn)); + + sub connection { + my ($self, @rest) = @_; + $self->next::method(@rest); + # $self is now a live My::Schema object, complete with DB connection + + $self->ACCESSORNAME1([ $self->resultset('RESULTSOURCEMONIKER')->all ]); + $self->ACCESSORNAME2([ $self->resultset('RESULTSOURCEMONIKER')->search({ COLUMN => { '<' => '30' } })->all ]); + $self->ACCESSORNAMEn([ $self->resultset('RESULTSOURCEMONIKER')->find(1) ]); + } + + 1; + +and now in the controller, you can now access any of these without a +per-request fetch: + + $c->stash->{something} = $c->model('My::Schema')->schema->ACCESSORNAMEn; + + =head2 XMLRPC Unlike SOAP, XMLRPC is a very simple (and imo elegant) web-services @@ -690,7 +718,7 @@ later) and SOAP::Lite (for XMLRPCsh.pl). 3. Add the XMLRPC plugin to MyApp.pm - use Catalyst qw/-Debug Static::Simple XMLRPC/; + __PACKAGE__->setup( qw/-Debug Static::Simple XMLRPC/); 4. Add an API controller @@ -699,7 +727,7 @@ later) and SOAP::Lite (for XMLRPCsh.pl). 5. Add a XMLRPC redispatch method and an add method with Remote attribute to lib/MyApp/Controller/API.pm - sub default : Private { + sub default :Path { my ( $self, $c ) = @_; $c->xmlrpc; } @@ -1250,7 +1278,7 @@ part of your namespace, you'll get an error page instead. If you want to find out where it was the user was trying to go, you can look in the request object using C<< $c->req->path >>. - sub default : Private { .. } + sub default :Path { .. } works for all unknown URLs, in this controller namespace, or every one if put directly into MyApp.pm. @@ -1262,7 +1290,7 @@ namespace of your controller. If index, default and matching Path actions are defined, then index will be used instead of default and Path. - sub index : Private { .. } + sub index :Path :Args(0) { .. } becomes @@ -1875,7 +1903,7 @@ B is found and served. Using the plugin is as simple as setting your use line in MyApp.pm to include: - use Catalyst qw/Static::Simple/; + __PACKAGE__->setup( qw/Static::Simple/); and already files will be served. @@ -1960,7 +1988,7 @@ using L. In your main application class (MyApp.pm), load the plugin: - use Catalyst qw/-Debug FormValidator Static OtherPlugin/; + __PACKAGE__->setup( qw/-Debug FormValidator Static OtherPlugin/); You will also need to make sure your end method does I forward static content to the view, perhaps like this: @@ -2070,12 +2098,12 @@ There are three wrapper plugins around common CPAN cache modules: Cache::FastMmap, Cache::FileCache, and Cache::Memcached. These can be used to cache the result of slow operations. -This very page you're viewing makes use of the FileCache plugin to cache the +The Catalyst Advent Calendar uses the FileCache plugin to cache the rendered XHTML version of the source POD document. This is an ideal -application for a cache because the source document changes infrequently but -may be viewed many times. +application for a cache because the source document changes +infrequently but may be viewed many times. - use Catalyst qw/Cache::FileCache/; + __PACKAGE__->setup( qw/Cache::FileCache/); ... @@ -2123,7 +2151,7 @@ thing for every single user who views the page. We can add the PageCache plugin to speed things up. - use Catalyst qw/Cache::FileCache PageCache/; + __PACKAGE__->setup( qw/Cache::FileCache PageCache/); sub front_page : Path ('/') { my ( $self, $c ) = @_;