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 namespace::clean qw/croak/;
   7
   8 =head1 NAME
   9
  10 Catalyst::View::Component::SubInclude::SubRequest - Sub-requests plugin for C::V::Component::SubInclude
  11
  12 =head1 VERSION
  13
  14 Version 0.03
  15
  16 =cut
  17
  18 our $VERSION = '0.03';
  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 sub generate_subinclude {
  73     my ($class, $c, $path, @params) = @_;
  74     my $stash = {};
  75
  76     croak "subincludes through subrequests require Catalyst::Plugin::SubRequest"
  77         unless $c->can('sub_request');
  78
  79     my $args = ref $params[0] eq 'ARRAY' ? shift @params : [];
  80
  81     my $dispatcher = $c->dispatcher;
  82     my ($action) = $dispatcher->_invoke_as_path( $c, $path, $args );
  83
  84     my $uri = $c->uri_for( $action, $args, @params );
  85
  86     $c->sub_request( $uri->path, $stash, @params );
  87 }
  88
  89 =head1 SEE ALSO
  90
  91 L<Catalyst::View::Component::SubInclude|Catalyst::View::Component::SubInclude>,
  92 L<Catalyst::Plugin::SubRequest|Catalyst::Plugin::SubRequest>
  93
  94 =head1 AUTHOR
  95
  96 Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >>
  97
  98 =head1 SPONSORSHIP
  99
 100 Development sponsored by Ionzero LLC L<http://www.ionzero.com/>.
 101
 102 =head1 COPYRIGHT & LICENSE
 103
 104 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
 105
 106 Copyright (C) 2009 Ionzero LLC.
 107
 108 This program is free software; you can redistribute it and/or modify it
 109 under the same terms as Perl itself.
 110
 111 =cut
 112
 113 1;