lib/Catalyst/View/Component/SubInclude/SubRequest.pm

   1 package Catalyst::View::Component::SubInclude::SubRequest;
   2 use Moose;
   3 use Carp qw/croak/;
   4 use MooseX::Types::Moose qw/ Bool /;
   5 use namespace::clean -except => 'meta';
   6
   7 =head1 NAME
   8
   9 Catalyst::View::Component::SubInclude::SubRequest - Sub-requests plugin for C::V::Component::SubInclude
  10
  11 =head1 VERSION
  12
  13 Version 0.07_03
  14
  15 =cut
  16
  17 our $VERSION = '0.07_03';
  18 $VERSION = eval $VERSION;
  19
  20 =head1 SYNOPSIS
  21
  22 In your application class:
  23
  24   package MyApp;
  25
  26   use Catalyst qw/
  27     ConfigLoader
  28     Static::Simple
  29     ...
  30     SubRequest
  31   /;
  32
  33 In your view class:
  34
  35   package MyApp::View::TT;
  36   use Moose;
  37
  38   extends 'Catalyst::View::TT';
  39   with 'Catalyst::View::Component::SubInclude';
  40
  41   __PACKAGE__->config( subinclude_plugin => 'SubRequest' );
  42
  43 Then, somewhere in your templates:
  44
  45   [% subinclude('/my/widget') %]
  46
  47 =head1 DESCRIPTION
  48
  49 C<Catalyst::View::Component::SubInclude::SubRequest> uses Catalyst sub-requests
  50 to render the subinclude contents.
  51
  52 It requires L<Catalyst::Plugin::SubRequest>.
  53
  54 =head1 METHODS
  55
  56 =head2 C<generate_subinclude( $c, $path, @args )>
  57
  58 This will make a sub-request call to the action specified by C<$path>. Note that
  59 C<$path> should be the private action path - translation to the public path is
  60 handled internally.
  61
  62 So, after path translation, the call will be (roughly) equivalent to:
  63
  64   $c->sub_request( $translated_path, {}, @args );
  65
  66 Notice that the stash will be empty by default. This behavior is configurable
  67 (see below).
  68
  69 =head1 CONFIGURATION
  70
  71 =head2 keep_stash
  72
  73 You can choose to not localize the stash for SubRequests' subinclude calls. The subrequest
  74 will have the same stash as the request that spawned it. Configure the keep_stash key
  75 in your view:
  76
  77     __PACKAGE__->config(
  78         subinclude => {
  79             'SubRequest' => {
  80                 keep_stash => 1,
  81             },
  82         }
  83     );
  84
  85 Note: the stash that the subrequest recieves is a shallow copy of the original stash. That
  86 means that changes to values of keys on the first level of the stash will be lost when the
  87 subrequest call returns. Don't count on this behaviour, as it may change in the future.
  88
  89 =cut
  90
  91 has keep_stash => (
  92     isa => Bool,
  93     is => 'ro',
  94     default => 0,
  95 );
  96
  97 sub generate_subinclude {
  98     my ($self, $c, $path, @params) = @_;
  99     my $stash = $self->keep_stash ? $c->stash : {};
 100
 101     croak "subincludes through subrequests require Catalyst::Plugin::SubRequest"
 102         unless $c->can('sub_request');
 103
 104     my $query = ref $params[-1] eq 'HASH' ? pop @params : {};
 105
 106     my $action = blessed($path)
 107           ? $path
 108           : $c->dispatcher->get_action_by_path($path);
 109
 110     my $uri = $c->uri_for( $action, @params );
 111
 112     $c->sub_request( $uri->path, $stash, $query );
 113 }
 114
 115 =head1 SEE ALSO
 116
 117 L<Catalyst::View::Component::SubInclude|Catalyst::View::Component::SubInclude>,
 118 L<Catalyst::Plugin::SubRequest|Catalyst::Plugin::SubRequest>
 119
 120 =head1 AUTHOR
 121
 122 Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >>
 123
 124 =head1 SPONSORSHIP
 125
 126 Development sponsored by Ionzero LLC L<http://www.ionzero.com/>.
 127
 128 =head1 COPYRIGHT & LICENSE
 129
 130 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
 131
 132 Copyright (C) 2009 Ionzero LLC.
 133
 134 This program is free software; you can redistribute it and/or modify it
 135 under the same terms as Perl itself.
 136
 137 =cut
 138
 139 __PACKAGE__->meta->make_immutable;
 140 1;