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 B<WARNING: As of Catalyst version 5.71000, this plugin doesn't work for chained
  44 actions with captured arguments>. Apparently, C<visit> doesn't handle this type
  45 of actions yet.
  46
  47 =head1 CLASS METHODS
  48
  49 =head2 C<generate_subinclude( $c, $path, @args )>
  50
  51 This is (roughly) equivalent to the following call:
  52
  53   $c->visit( $path, @args );
  54
  55 But it will handle all the nasty details such as localizing the stash,
  56 parameters and response body. This is necessary to keep behavior consistent
  57 with the other plugins.
  58
  59 =cut
  60
  61 has keep_stash => (
  62     isa => Bool,
  63     is => 'ro',
  64     default => 0,
  65 );
  66
  67 sub generate_subinclude {
  68     my ($self, $c, $path, @params) = @_;
  69
  70     croak "subincludes through visit() require Catalyst version 5.71000 or newer"
  71         unless $c->can('visit');
  72
  73     {
  74         local $c->{stash} = $self->keep_stash ? $c->{stash} : {};
  75
  76         local $c->request->{parameters} =
  77             ref $params[-1] eq 'HASH' ? pop @params : {};
  78
  79         local $c->response->{body};
  80
  81         my $captures = ref $params[0] eq 'ARRAY' ? shift @params : [];
  82         $c->visit( $path, $captures, \@params );
  83
  84         return $c->response->{body};
  85     }
  86
  87 }
  88
  89 =head1 SEE ALSO
  90
  91 L<Catalyst::View::Component::SubInclude|Catalyst::View::Component::SubInclude>,
  92 L<Catalyst|Catalyst>
  93
  94 =head1 AUTHOR
  95
  96 Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >>
  97
  98 =head1 SPONSORSHIP
  99
 100 Development sponsored by Ionzero LLC L<http://www.ionzero.com/>.
 101
 102 =head1 COPYRIGHT & LICENSE
 103
 104 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
 105
 106 Copyright (C) 2009 Ionzero LLC.
 107
 108 This program is free software; you can redistribute it and/or modify it
 109 under the same terms as Perl itself.
 110
 111 =cut
 112
 113 __PACKAGE__->meta->make_immutable;
 114 1;