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

   1 package Catalyst::View::Component::SubInclude::Visit;
   2 use warnings;
   3 use strict;
   4
   5 use Carp qw/croak/;
   6 use namespace::clean qw/croak/;
   7
   8 =head1 NAME
   9
  10 Catalyst::View::Component::SubInclude::Visit - visit() plugin for C::V::Component::SubInclude
  11
  12 =head1 VERSION
  13
  14 Version 0.04
  15
  16 =cut
  17
  18 our $VERSION = '0.04';
  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 sub generate_subinclude {
  62     my ($class, $c, $path, @params) = @_;
  63
  64     croak "subincludes through visit() require Catalyst version 5.71000 or newer"
  65         unless $c->can('visit');
  66
  67     $c->log->debug("generate subinclude: $path @params");
  68
  69     {
  70         local $c->{stash} = {};
  71
  72         local $c->request->{parameters} =
  73             ref $params[-1] eq 'HASH' ? pop @params : {};
  74
  75         local $c->response->{body};
  76
  77         $c->visit( $path, ( ref $params[0] eq 'ARRAY' ? shift @params : () ) );
  78
  79         return $c->response->{body};
  80     }
  81
  82 }
  83
  84 =head1 SEE ALSO
  85
  86 L<Catalyst::View::Component::SubInclude|Catalyst::View::Component::SubInclude>,
  87 L<Catalyst|Catalyst>
  88
  89 =head1 AUTHOR
  90
  91 Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >>
  92
  93 =head1 SPONSORSHIP
  94
  95 Development sponsored by Ionzero LLC L<http://www.ionzero.com/>.
  96
  97 =head1 COPYRIGHT & LICENSE
  98
  99 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
 100
 101 Copyright (C) 2009 Ionzero LLC.
 102
 103 This program is free software; you can redistribute it and/or modify it
 104 under the same terms as Perl itself.
 105
 106 =cut
 107
 108 1;