X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Component-ACCEPT_CONTEXT.git;a=blobdiff_plain;f=README;h=ceb14367162576554862db44a36ee834648e2333;hp=ce6155fe5c1e3d9c08b407e05b95d840dbfad454;hb=HEAD;hpb=31cbbd3383b45ed2677ce1ddc9c51e58bbc24dbd

diff --git a/README b/README
index ce6155f..ceb1436 100644
--- a/README
+++ b/README
@@ -1,40 +1,143 @@
-Catalyst-Component-ACCEPT_CONTEXT
+NAME
+    Catalyst::Component::ACCEPT_CONTEXT - Make the current Catalyst request
+    context available in Models and Views.
 
-Make accessing the Catalyst context from a Model/View even easier.
+VERSION
+    Version 0.07
 
-INSTALLATION
+SYNOPSIS
+    Models and Views don't usually have access to the request object, since
+    they probably don't really need it. Sometimes, however, having the
+    request context available outside of Controllers makes your application
+    cleaner. If that's the case, just use this module as a base class:
 
-To install this module, run the following commands:
+        package MyApp::Model::Foobar;
+        use base qw|Catalyst::Component::ACCEPT_CONTEXT Catalyst::Model|;
 
-    perl Makefile.PL
-    make
-    make test
-    make install
+    Then, you'll be able to get the current request object from within your
+    model:
 
+        sub do_something {
+            my $self = shift;
+            print "The current URL is ". $self->context->req->uri->as_string;
+        }
 
-SUPPORT AND DOCUMENTATION
+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
+    Catalyst::Component::InstancePerContext.
 
-After installing, you can find documentation for this module with the perldoc command.
+    Instead of doing this on every request (which is basically what this
+    module does):
 
-    perldoc Catalyst::Component::ACCEPT_CONTEXT
+        $my_component->context($c);
 
-You can also look for information at:
+    It's better to do something like this:
 
-    Search CPAN
-        http://search.cpan.org/dist/Catalyst-Component-ACCEPT_CONTEXT
+        package FooApp::Controller::Root;
+        use base 'Catalyst::Controller';
+        use Moose;
 
-    CPAN Request Tracker:
-        http://rt.cpan.org/NoAuth/Bugs.html?Dist=Catalyst-Component-ACCEPT_CONTEXT
+        with 'Catalyst::Component::InstancePerContext';
+        has 'context' => (is => 'ro');
 
-    AnnoCPAN, annotated CPAN documentation:
-        http://annocpan.org/dist/Catalyst-Component-ACCEPT_CONTEXT
+        sub build_per_context_instance {
+            my ($self, $c, @args) = @_;
+            return $self->new({ context => $c, %$self, @args });
+        }
 
-    CPAN Ratings:
-        http://cpanratings.perl.org/d/Catalyst-Component-ACCEPT_CONTEXT
+        sub actions :Whatever {
+            my $self = shift;
+            my $c = $self->context; # this works now
+        }
 
-COPYRIGHT AND LICENCE
+        1;
 
-Copyright (C) 2007 Jonathan Rockway
+    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.
+
+METHODS
+  context
+    Returns the current request context.
+
+  ACCEPT_CONTEXT
+    Catalyst calls this method to give the current context to your model.
+    You should never call it directly.
+
+    Note that a new instance of your component isn't created. All we do here
+    is shove $c into your component. ACCEPT_CONTEXT allows for other
+    behavior that may be more useful; if you want something else to happen
+    just implement it yourself.
+
+    See Catalyst::Component for details.
+
+  COMPONENT
+    Overridden to use initial application object as context before a
+    request.
+
+AUTHOR
+    Jonathan Rockway, "<jrockway at cpan.org>"
+
+    Patches contributed and maintained by:
+
+    Rafael Kitover (Caelum)
+    Tomas Doran (t0m) "<bobtfish@bobtfish.net>"
+
+BUGS
+    Please report any bugs or feature requests to
+    "bug-catalyst-component-accept_context at rt.cpan.org", or through the
+    web interface at
+    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-Component-ACCEP
+    T_CONTEXT>. I will be notified, and then you'll automatically be
+    notified of progress on your bug as I make changes.
+
+SUPPORT
+    You can find documentation for this module with the perldoc command.
+
+        perldoc Catalyst::Component::ACCEPT_CONTEXT
+
+    You can also look for information at:
+
+    * Catalyst Website
+        <http://www.catalystframework.org/>
+
+    * AnnoCPAN: Annotated CPAN documentation
+        <http://annocpan.org/dist/Catalyst-Component-ACCEPT_CONTEXT>
+
+    * CPAN Ratings
+        <http://cpanratings.perl.org/d/Catalyst-Component-ACCEPT_CONTEXT>
+
+    * RT: CPAN's request tracker
+        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Catalyst-Component-ACCEPT_
+        CONTEXT>
+
+    * Search CPAN
+        <http://search.cpan.org/dist/Catalyst-Component-ACCEPT_CONTEXT>
+
+Source code
+    The source code for this project can be found at:
+
+        git://git.shadowcat.co.uk/catagits/Catalyst-Component-ACCEPT_CONTEXT
+
+COPYRIGHT & LICENSE
+    Copyright 2007 Jonathan Rockway.
+
+    This program is free software; you can redistribute it and/or modify it
+    under the same terms as Perl itself.
 
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.