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
  14
  15 =cut
  16
  17 our $VERSION = '0.07';
  18
  19 =head1 SYNOPSIS
  20
  21 In your view class:
  22
  23   package MyApp::View::TT;
  24   use Moose;
  25
  26   extends 'Catalyst::View::TT';
  27   with 'Catalyst::View::Component::SubInclude';
  28
  29   __PACKAGE__->config( subinclude_plugin => 'Visit' );
  30
  31 Then, somewhere in your templates:
  32
  33   [% subinclude('/my/widget') %]
  34
  35 =head1 DESCRIPTION
  36
  37 C<Catalyst::View::Component::SubInclude::Visit> uses C<< $c->visit() >> to
  38 render subinclude contents.
  39
  40 This method is only supported when using L<Catalyst> version 5.71000 or newer.
  41
  42 B<WARNING: As of Catalyst version 5.71000, this plugin doesn't work for chained
  43 actions with captured arguments>. Apparently, C<visit> doesn't handle this type
  44 of actions yet.
  45
  46 =head1 CLASS METHODS
  47
  48 =head2 C<generate_subinclude( $c, $path, @args )>
  49
  50 This is (roughly) equivalent to the following call:
  51
  52   $c->visit( $path, @args );
  53
  54 But it will handle all the nasty details such as localizing the stash,
  55 parameters and response body. This is necessary to keep behavior consistent
  56 with the other plugins.
  57
  58 =cut
  59
  60 has keep_stash => (
  61     isa => Bool,
  62     is => 'ro',
  63     default => 0,
  64 );
  65
  66 sub generate_subinclude {
  67     my ($self, $c, $path, @params) = @_;
  68
  69     croak "subincludes through visit() require Catalyst version 5.71000 or newer"
  70         unless $c->can('visit');
  71
  72     {
  73         local $c->{stash} = $self->keep_stash ? $c->{stash} : {};
  74
  75         local $c->request->{parameters} =
  76             ref $params[-1] eq 'HASH' ? pop @params : {};
  77
  78         local $c->response->{body};
  79
  80         my $captures = ref $params[0] eq 'ARRAY' ? shift @params : [];
  81         $c->visit( $path, $captures, \@params );
  82
  83         return $c->response->{body};
  84     }
  85
  86 }
  87
  88 =head1 SEE ALSO
  89
  90 L<Catalyst::View::Component::SubInclude|Catalyst::View::Component::SubInclude>,
  91 L<Catalyst|Catalyst>
  92
  93 =head1 AUTHOR
  94
  95 Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >>
  96
  97 =head1 SPONSORSHIP
  98
  99 Development sponsored by Ionzero LLC L<http://www.ionzero.com/>.
 100
 101 =head1 COPYRIGHT & LICENSE
 102
 103 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
 104
 105 Copyright (C) 2009 Ionzero LLC.
 106
 107 This program is free software; you can redistribute it and/or modify it
 108 under the same terms as Perl itself.
 109
 110 =cut
 111
 112 __PACKAGE__->meta->make_immutable;
 113 1;