From: Tomas Doran Date: Mon, 10 Aug 2009 08:40:24 +0000 (+0000) Subject: Expand CatalystAndMoose somewhat, re-arrange the DevelopmentProcess docs some more... X-Git-Tag: v5.8005~112 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=commitdiff_plain;h=e91e320be26db95fc1bfdee31436cdbc09899cf7 Expand CatalystAndMoose somewhat, re-arrange the DevelopmentProcess docs some more, and start adding better info on contributing, other misc cleanups --- diff --git a/lib/Catalyst/Manual.pm b/lib/Catalyst/Manual.pm index da568d0..198f584 100644 --- a/lib/Catalyst/Manual.pm +++ b/lib/Catalyst/Manual.pm @@ -37,31 +37,31 @@ L =item * -L +L =item * -L +L =item * -L +L =item * -L +L =item * -L +L =item * -L +L =item * -L +L =item * @@ -69,12 +69,10 @@ L =back - =head2 Books For additional information on Catalyst, there are currently two books available: - =over 4 =item * diff --git a/lib/Catalyst/Manual/About.pod b/lib/Catalyst/Manual/About.pod index 65afb83..805bf8d 100644 --- a/lib/Catalyst/Manual/About.pod +++ b/lib/Catalyst/Manual/About.pod @@ -258,7 +258,7 @@ the record and ask the View to display it. In either case, the View will then generate an HTML page, which Catalyst will send to the user's browser, using whatever web server you've configured. -How does this help you? +=head3 How does this help you? In many ways. Suppose you have a small catalog now, and you're using a lightweight database such as SQLite, or maybe just a text file. But diff --git a/lib/Catalyst/Manual/Actions.pod b/lib/Catalyst/Manual/Actions.pod index 6cd5949..461945e 100644 --- a/lib/Catalyst/Manual/Actions.pod +++ b/lib/Catalyst/Manual/Actions.pod @@ -41,7 +41,7 @@ the Action class: my $self = shift; my ( $controller, $c, $test ) = @_; $c->stash->{what} = 'world'; - $self->NEXT::execute( @_ ); + $self->next::method( @_ ); }; 1; diff --git a/lib/Catalyst/Manual/CatalystAndMoose.pod b/lib/Catalyst/Manual/CatalystAndMoose.pod index a4a49fe..adcfaf3 100644 --- a/lib/Catalyst/Manual/CatalystAndMoose.pod +++ b/lib/Catalyst/Manual/CatalystAndMoose.pod @@ -12,13 +12,11 @@ to exploit the power of L in your Catalyst application. This document provides you with a short overview of common caveats and best practices to use L-based classes within Catalyst. - =head1 THE CONTEXT CLASS A Moose-ified version of the context class should look like this: package MyApp; - use Moose; use namespace::autoclean; use Catalyst ( @@ -35,12 +33,12 @@ A Moose-ified version of the context class should look like this: # method modifiers generally must be created after setup because otherwise they will # conflict with plugin overrides - after 'finalize' => sub{ + after 'finalize' => sub { my $c = shift; $c->log->info( 'done!' ); } -You should also be aware, that roles in C<< $c-Esetup >> are applied +You should also be aware that roles in C<< $c-Esetup >> are applied after the last plugin with all the benefits of using a single L statement in an ordinary L class. @@ -64,7 +62,6 @@ CAVEAT: Using roles in C<< $c-Esetup >> will not currently allow you to pass parameters to roles, or perform conflict resolution. Conflict detection still works as expected. - =head2 ACCESSORS Most of the request-specific attributes like C<$c-Estash>, @@ -75,10 +72,10 @@ compatible to applications using the published API of Catalyst 5.7 but slightly limits the gains that could be had by wielding the full power of L attributes. -Most of the accessors to information gathered during compile time is -managed by C, which is a L-aware version -of L but not compatible with -L. +Most of the accessors to information gathered during compile time (such +as configuration) are managed by C, which is a +L-aware version of L but not compatible +with L. =head2 ROLES AND METHOD MODIFIERS @@ -89,13 +86,15 @@ to applications still using version 5.7. If backward compatibility is of no concern to you, you could as easily rewrite your plugins as roles and enjoy all the benefits of automatic method re-dispatching of C<< before >> and C<< after >> method -modifiers, naming conflict detecting and generally cleaner code. +modifiers, naming conflict detection and generally cleaner code. + +=head3 NOTE Plugins and roles should never use after 'setup' => sub { ... } # wrong -but rely on +(or any other method of hooking the setup method) but rely on after 'setup_finalize' => sub { ... } # this will work @@ -108,7 +107,7 @@ consideration and as late as possible. =head1 CONTROLLERS To activate Catalyst's action attributes, Moose-ified controller -classes need to extend L at compile time before +classes need to extend L at compile time, before the actions themselves are declared: package Catalyst::Controller::Root; @@ -116,16 +115,27 @@ the actions themselves are declared: use namespace::autoclean; BEGIN { extends 'Catalyst::Controller'; } - with qw( - # your controller roles - ); - + =head2 Controller Roles It is possible to use roles to apply method modifiers on controller actions -from 5.80003 onwards, or use modifiers in actions in your controller classes -themselves. - +from 5.80003 onwards, or use modifiers in your controller classes +themselves. For example + + package MyApp::Controller::Foo; + use Moose; + use namespace::autoclean; + BEGIN { extends 'Catalyst::Controller' }; + + sub foo : Local { + my ($self, $c) = @_; + $c->res->body('Hello '); + } + after foo => sub { + my ($self, $c) = @_; + $c->res->body($c->res->body . 'World'); + }; + It is possible to have action methods with attributes inside Moose roles, using the trait introduced in L version 0.12, example: @@ -138,3 +148,18 @@ the trait introduced in L version 0.12, example: ... } + package MyApp::Controller::Foo; + use Moose; + use namespace::autoclean; + BEGIN { extends 'Catalyst::Controller' }; + + with 'MyApp::ControllerRole'; + +=head1 AUTHOR + +The Catalyst Core Team - see http://catalyst.perl.org/ + +=head1 COPYRIGHT + +This program is free software. You can redistribute it and/or modify it +under the same terms as Perl itself. diff --git a/lib/Catalyst/Manual/DevelopmentProcess.pod b/lib/Catalyst/Manual/DevelopmentProcess.pod index 36d04b1..df23c76 100644 --- a/lib/Catalyst/Manual/DevelopmentProcess.pod +++ b/lib/Catalyst/Manual/DevelopmentProcess.pod @@ -2,21 +2,25 @@ Catalyst::Manual::DevelopmentProcess - Administrative structure of the Catalyst Development Process -=head1 Aims of the Catalyst Core Team +=head1 Catalyst development -The main current goals of the Catalyst core development team continue to -be stability, performance, and a more paced addition of features, with a -focus on extensibility. +=head2 Schedule + +There is no dated release cycle for Catalyst. New releases will be made +when sufficient small fixes have accumalated, or an important bugfix, or +significant feature addition is completed. -The Catalyst Roadmap at +=head2 Roadmanp for features + +The Catalyst Roadmap is kept at L -will remain as is, -and continues to reflect the specific priorities and schedule for future -releases. -=head1 Charter for the Catalyst Core Team +=head2 Bug list + +The TODO list with known bugs / deficiences is kept at +L -=head2 Intention +=head1 The Catalyst Core Team The intention of the Catalyst Core Team is to maintain and support the Catalyst framework, in order for it to be a viable and stable framework @@ -24,16 +28,23 @@ for developing web-based MVC applications. This includes both technical decisions about the Catalyst core distribution, and public relations relating to the Catalyst framework as a whole. -The main priority for development is stability for the users of the -framework, while improving usability and extensibility, as well as -improving documentation and ease of deployment. +The current goals of the Catalyst core development team are +be stability, performance, and a paced addition of features, with a +focus on extensibility. + +The core team are concerned with the 'core' Catalyst distributions +(i.e. L, L and L), +and also tries to encourage best practices for extension authors and +cooperation and shared vision within the Catalyst community. =head2 Membership The Catalyst Core Team consists of the developers that have full commit -privileges to the entire Catalyst source tree. +privileges to the entire Catalyst source tree, who have made a significant +contribution to the core Catalyst distributions, and various extensions and +pugins. -In addition, the core team may accept members that have non-technical +In addition, the core team includes members that have non-technical roles such as marketing, legal, or economic responsibilities. Currently, the Core Team consists of the following people: @@ -96,4 +107,28 @@ The Core Team should strive to appear publicly as a group when answering questions or other correspondence. In cases where this is not possible, the same order as for CPAN Releases applies. +=head1 Contributing to Catalyst + +The main philosophy behind Catalyst development can be surimsed as: + + Patches welcome! + +Everyone is welcome (and will be encouraged) to contribute to Catalyst +in whatever capacity they're able to. People in #catalyst-dev will be +more than happy to talk newcomers through contributing their first patch, +or how best to go about their first CPAN extension module.. + +=head2 Repositories + +The Catalyst subversion repository can be found at: + + http://dev.catalyst.perl.org/repos/Catalyst + +and the git repository can be found at FIXME + +=head2 New Catalyst extensions + +As Catalyst is deliberately designed for extension, there is an ecosystem of +several hundred Catalyst extensions which can be found on CPAN. +FIXME