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

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