Bump versions, changelog for release

[catagits/Catalyst-Component-ACCEPT_CONTEXT.git] / lib / Catalyst / Component / ACCEPT_CONTEXT.pm

diff --git a/lib/Catalyst/Component/ACCEPT_CONTEXT.pm b/lib/Catalyst/Component/ACCEPT_CONTEXT.pm
index 7526c77..5fd529f 100644 (file)
--- a/lib/Catalyst/Component/ACCEPT_CONTEXT.pm
+++ b/lib/Catalyst/Component/ACCEPT_CONTEXT.pm
@@ -2,7 +2,7 @@ package Catalyst::Component::ACCEPT_CONTEXT;
 
 use warnings;
 use strict;
-use NEXT;
+use MRO::Compat;
 use Scalar::Util qw(weaken);
 
 =head1 NAME
@@ -12,11 +12,11 @@ request context available in Models and Views.
 
 =head1 VERSION
 
-Version 0.05
+Version 0.07
 
 =cut
 
-our $VERSION = '0.05';
+our $VERSION = '0.07';
 
 =head1 SYNOPSIS
 
@@ -37,6 +37,57 @@ your model:
         print "The current URL is ". $self->context->req->uri->as_string;
     }
 
+=head1 WARNING WARNING WARNING
+
+Using this module is somewhat of a hack.  Changing the state of your
+objects on every request is a pretty braindead way of doing OO.  If
+you want your application to be brain-live, then you should use
+L<Catalyst::Component::InstancePerContext>.
+
+Instead of doing this on every request (which is basically
+what this module does):
+
+    $my_component->context($c);
+
+It's better to do something like this:
+
+    package FooApp::Controller::Root;
+    use base 'Catalyst::Controller';
+    use Moose;
+
+    with 'Catalyst::Component::InstancePerContext';
+    has 'context' => (is => 'ro');
+
+    sub build_per_context_instance {
+        my ($self, $c, @args) = @_;
+        return $self->new({ context => $c, %$self, @args });
+    }
+
+    sub actions :Whatever {
+        my $self = shift;
+        my $c = $self->context; # this works now
+    }
+
+    1;
+
+Now you get a brand new object that lasts for a single request instead
+of changing the state of an existing one on each request.  This is
+much cleaner OO design.
+
+The best strategy, though, is not to use the context inside your
+model.  It's best for your Controller to pull the necessary data from
+the context, and pass it as arguments:
+
+   sub action :Local {
+       my ($self, $c) = @_;
+       my $foo  = $c->model('Foo');
+       my $quux = $foo->frobnicate(baz => $c->request->params->{baz});
+       $c->stash->{quux} = $quux;
+   }
+
+This will make it Really Easy to test your components outside of
+Catalyst, which is always good.
+
 =head1 METHODS
 
 =head2 context
@@ -69,8 +120,8 @@ sub ACCEPT_CONTEXT {
 
     $self->{context} = $context;
     weaken($self->{context});
-    
-    return $self->NEXT::ACCEPT_CONTEXT($context, @_) || $self;
+
+    return $self->maybe::next::method($context, @_) || $self;
 }
 
 =head2 COMPONENT
@@ -85,13 +136,23 @@ sub COMPONENT {
     my $args  = shift;
     $args->{context} = $app;
     weaken($args->{context}) if ref $args->{context};
-    return $class->NEXT::COMPONENT($app, $args, @_);
+    return $class->maybe::next::method($app, $args, @_);
 }
 
 =head1 AUTHOR
 
 Jonathan Rockway, C<< <jrockway at cpan.org> >>
 
+Patches contributed and maintained by:
+
+=over
+
+=item Rafael Kitover (Caelum)
+
+=item Tomas Doran (t0m) C<< <bobtfish@bobtfish.net> >>
+
+=back
+
 =head1 BUGS
 
 Please report any bugs or feature requests to
@@ -132,6 +193,12 @@ L<http://search.cpan.org/dist/Catalyst-Component-ACCEPT_CONTEXT>
 
 =back
 
+=head1 Source code
+
+The source code for this project can be found at:
+
+    git://git.shadowcat.co.uk/catagits/Catalyst-Component-ACCEPT_CONTEXT
+
 =head1 COPYRIGHT & LICENSE
 
 Copyright 2007 Jonathan Rockway.