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

   1 package Catalyst::View::Component::SubInclude::Visit;
   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::Visit - visit() 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 view class:
  23
  24   package MyApp::View::TT;
  25   use Moose;
  26
  27   extends 'Catalyst::View::TT';
  28   with 'Catalyst::View::Component::SubInclude';
  29
  30   __PACKAGE__->config( subinclude_plugin => 'Visit' );
  31
  32 Then, somewhere in your templates:
  33
  34   [% subinclude('/my/widget') %]
  35
  36 =head1 DESCRIPTION
  37
  38 C<Catalyst::View::Component::SubInclude::Visit> uses C<< $c->visit() >> to
  39 render subinclude contents.
  40
  41 This method is only supported when using L<Catalyst> version 5.71000 or newer.
  42
  43 =head1 METHODS
  44
  45 =head2 C<generate_subinclude( $c, $path, @args )>
  46
  47 This is (roughly) equivalent to the following call:
  48
  49   $c->visit( $path, @args );
  50
  51 But it will handle all the nasty details such as localizing the stash,
  52 parameters and response body. This is necessary to keep behavior consistent
  53 with the other plugins.
  54
  55 =head1 CONFIGURATION
  56
  57 =head2 keep_stash
  58
  59 You can choose to not localize the stash for Visits' subinclude calls. The subrequest
  60 will have the same stash as the request that spawned it. Configure the keep_stash key
  61 in your view:
  62
  63     __PACKAGE__->config(
  64         subinclude => {
  65             'Visit' => {
  66                 keep_stash => 1,
  67             },
  68         }
  69     );
  70
  71 Note: changes in the stash during a Visit subinclude will be visible after the include
  72 returns.
  73
  74 =cut
  75
  76 has keep_stash => (
  77     isa => Bool,
  78     is => 'ro',
  79     default => 0,
  80 );
  81
  82 sub generate_subinclude {
  83     my ($self, $c, $path, @params) = @_;
  84
  85     croak "subincludes through visit() require Catalyst version 5.71000 or newer"
  86         unless $c->can('visit');
  87
  88     {
  89         local $c->{stash} = $self->keep_stash ? $c->{stash} : {};
  90
  91         local $c->request->{parameters} =
  92             ref $params[-1] eq 'HASH' ? pop @params : {};
  93
  94         local $c->response->{body};
  95
  96         my $captures = ref $params[0] eq 'ARRAY' ? shift @params : [];
  97         $c->visit( $path, $captures, \@params );
  98
  99         return $c->response->{body};
 100     }
 101
 102 }
 103
 104 =head1 SEE ALSO
 105
 106 L<Catalyst::View::Component::SubInclude|Catalyst::View::Component::SubInclude>,
 107 L<Catalyst|Catalyst>
 108
 109 =head1 AUTHOR
 110
 111 Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >>
 112
 113 =head1 SPONSORSHIP
 114
 115 Development sponsored by Ionzero LLC L<http://www.ionzero.com/>.
 116
 117 =head1 COPYRIGHT & LICENSE
 118
 119 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
 120
 121 Copyright (C) 2009 Ionzero LLC.
 122
 123 This program is free software; you can redistribute it and/or modify it
 124 under the same terms as Perl itself.
 125
 126 =cut
 127
 128 __PACKAGE__->meta->make_immutable;
 129 1;