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

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