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 =cut
  56
  57 has keep_stash => (
  58     isa => Bool,
  59     is => 'ro',
  60     default => 0,
  61 );
  62
  63 sub generate_subinclude {
  64     my ($self, $c, $path, @params) = @_;
  65
  66     croak "subincludes through visit() require Catalyst version 5.71000 or newer"
  67         unless $c->can('visit');
  68
  69     {
  70         local $c->{stash} = $self->keep_stash ? $c->{stash} : {};
  71
  72         local $c->request->{parameters} =
  73             ref $params[-1] eq 'HASH' ? pop @params : {};
  74
  75         local $c->response->{body};
  76
  77         my $captures = ref $params[0] eq 'ARRAY' ? shift @params : [];
  78         $c->visit( $path, $captures, \@params );
  79
  80         return $c->response->{body};
  81     }
  82
  83 }
  84
  85 =head1 SEE ALSO
  86
  87 L<Catalyst::View::Component::SubInclude|Catalyst::View::Component::SubInclude>,
  88 L<Catalyst|Catalyst>
  89
  90 =head1 AUTHOR
  91
  92 Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >>
  93
  94 =head1 SPONSORSHIP
  95
  96 Development sponsored by Ionzero LLC L<http://www.ionzero.com/>.
  97
  98 =head1 COPYRIGHT & LICENSE
  99
 100 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
 101
 102 Copyright (C) 2009 Ionzero LLC.
 103
 104 This program is free software; you can redistribute it and/or modify it
 105 under the same terms as Perl itself.
 106
 107 =cut
 108
 109 __PACKAGE__->meta->make_immutable;
 110 1;