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.07
  15
  16 =cut
  17
  18 our $VERSION = '0.07';
  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     {
  68         local $c->{stash} = {};
  69
  70         local $c->request->{parameters} =
  71             ref $params[-1] eq 'HASH' ? pop @params : {};
  72
  73         local $c->response->{body};
  74
  75         my $captures = ref $params[0] eq 'ARRAY' ? shift @params : [];
  76         $c->visit( $path, $captures, \@params );
  77
  78         return $c->response->{body};
  79     }
  80
  81 }
  82
  83 =head1 SEE ALSO
  84
  85 L<Catalyst::View::Component::SubInclude|Catalyst::View::Component::SubInclude>,
  86 L<Catalyst|Catalyst>
  87
  88 =head1 AUTHOR
  89
  90 Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >>
  91
  92 =head1 SPONSORSHIP
  93
  94 Development sponsored by Ionzero LLC L<http://www.ionzero.com/>.
  95
  96 =head1 COPYRIGHT & LICENSE
  97
  98 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
  99
 100 Copyright (C) 2009 Ionzero LLC.
 101
 102 This program is free software; you can redistribute it and/or modify it
 103 under the same terms as Perl itself.
 104
 105 =cut
 106
 107 1;