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

   1 package Catalyst::View::Component::SubInclude::SubRequest;
   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::SubRequest - Sub-requests 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 application class:
  23
  24   package MyApp;
  25
  26   use Catalyst qw/
  27     ConfigLoader
  28     Static::Simple
  29     ...
  30     SubRequest
  31   /;
  32
  33 In your view class:
  34
  35   package MyApp::View::TT;
  36   use Moose;
  37
  38   extends 'Catalyst::View::TT';
  39   with 'Catalyst::View::Component::SubInclude';
  40
  41   __PACKAGE__->config( subinclude_plugin => 'SubRequest' );
  42
  43 Then, somewhere in your templates:
  44
  45   [% subinclude('/my/widget') %]
  46
  47 =head1 DESCRIPTION
  48
  49 C<Catalyst::View::Component::SubInclude::SubRequest> uses Catalyst sub-requests
  50 to render the subinclude contents.
  51
  52 It requires L<Catalyst::Plugin::SubRequest>.
  53
  54 =head1 CLASS METHODS
  55
  56 =head2 C<generate_subinclude( $c, $path, @args )>
  57
  58 This will make a sub-request call to the action specified by C<$path>. Note that
  59 C<$path> should be the private action path - translation to the public path is
  60 handled internally.
  61
  62 So, after path translation, the call will be (roughly) equivalent to:
  63
  64   $c->sub_request( $translated_path, {}, @args );
  65
  66 Notice that the stash will always be empty. This behavior could be configurable
  67 in the future through an additional switch - for now, this behavior guarantees a
  68 common interface for all plugins.
  69
  70 =cut
  71
  72 has keep_stash => (
  73     isa => Bool,
  74     is => 'ro',
  75     default => 0,
  76 );
  77
  78 sub generate_subinclude {
  79     my ($self, $c, $path, @params) = @_;
  80     my $stash = $self->keep_stash ? { %{ $c->stash } } : {};
  81
  82     croak "subincludes through subrequests require Catalyst::Plugin::SubRequest"
  83         unless $c->can('sub_request');
  84
  85     my $query = ref $params[-1] eq 'HASH' ? pop @params : {};
  86
  87     my $action = blessed($path)
  88           ? $path
  89           : $c->dispatcher->get_action_by_path($path);
  90
  91     my $uri = $c->uri_for( $action, @params );
  92
  93     $c->sub_request( $uri->path, $stash, $query );
  94 }
  95
  96 =head1 SEE ALSO
  97
  98 L<Catalyst::View::Component::SubInclude|Catalyst::View::Component::SubInclude>,
  99 L<Catalyst::Plugin::SubRequest|Catalyst::Plugin::SubRequest>
 100
 101 =head1 AUTHOR
 102
 103 Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >>
 104
 105 =head1 SPONSORSHIP
 106
 107 Development sponsored by Ionzero LLC L<http://www.ionzero.com/>.
 108
 109 =head1 COPYRIGHT & LICENSE
 110
 111 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
 112
 113 Copyright (C) 2009 Ionzero LLC.
 114
 115 This program is free software; you can redistribute it and/or modify it
 116 under the same terms as Perl itself.
 117
 118 =cut
 119
 120 __PACKAGE__->meta->make_immutable;
 121 1;