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.07
  15
  16 =cut
  17
  18 our $VERSION = '0.07';
  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     my $query = ref $params[-1] eq 'HASH'  ?   pop @params : {};
  81
  82     my $dispatcher = $c->dispatcher;
  83     my ($action) = $dispatcher->_invoke_as_path( $c, $path, $args );
  84
  85     my $uri = $c->uri_for( $action, $args, @params );
  86
  87     $c->sub_request( $uri->path, $stash, $query );
  88 }
  89
  90 =head1 SEE ALSO
  91
  92 L<Catalyst::View::Component::SubInclude|Catalyst::View::Component::SubInclude>,
  93 L<Catalyst::Plugin::SubRequest|Catalyst::Plugin::SubRequest>
  94
  95 =head1 AUTHOR
  96
  97 Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >>
  98
  99 =head1 SPONSORSHIP
 100
 101 Development sponsored by Ionzero LLC L<http://www.ionzero.com/>.
 102
 103 =head1 COPYRIGHT & LICENSE
 104
 105 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
 106
 107 Copyright (C) 2009 Ionzero LLC.
 108
 109 This program is free software; you can redistribute it and/or modify it
 110 under the same terms as Perl itself.
 111
 112 =cut
 113
 114 1;