Tweaks

[catagits/Catalyst-Component-ACCEPT_CONTEXT.git] / README

NAME
    Catalyst::Component::ACCEPT_CONTEXT - Make the current Catalyst request
    context available in Models and Views.

VERSION
    Version 0.07

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:

        package MyApp::Model::Foobar;
        use base qw|Catalyst::Component::ACCEPT_CONTEXT Catalyst::Model|;

    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;
        }

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.

    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.

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.