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