lib/Catalyst/View/Component/SubInclude.pm

   1 package Catalyst::View::Component::SubInclude;
   2 use Moose::Role;
   3
   4 use Carp qw/croak/;
   5 use namespace::clean qw/croak/;
   6
   7 =head1 NAME
   8
   9 Catalyst::View::Component::SubInclude - Use subincludes in your Catalyst views
  10
  11 =head1 VERSION
  12
  13 Version 0.01
  14
  15 =cut
  16
  17 our $VERSION = '0.01';
  18
  19 =head1 SYNOPSIS
  20
  21   package MyApp::View::TT;
  22   use Moose;
  23
  24   extends 'Catalyst::View::TT';
  25   with 'Catalyst::View::Component::SubInclude';
  26
  27   __PACKAGE__->config( subinclude_plugin => 'SubRequest' );
  28
  29 Then, somewhere in your templates:
  30
  31   [% subinclude('/my/widget') %]
  32
  33 =head1 DESCRIPTION
  34
  35 C<Catalyst::View::Component::SubInclude> allows you to include content in your
  36 templates (or, more generally, somewhere in your view's C<render> processing)
  37 which comes from another action in your application. It's implemented as a
  38 L<Moose::Role|Moose::Role>, so using L<Moose|Moose> in your view is required.
  39
  40 Simply put, it's a way to include the output of a Catalyst sub-request somewhere
  41 in your page.
  42
  43 It's built in an extensible way so that you're free to use sub-requests, Varnish
  44 ESI (L<http://www.catalystframework.org/calendar/2008/17>) or any other
  45 sub-include plugin you might want to implement. An LWP plugin seems useful and
  46 might be developed in the future.
  47
  48 =head1 STASH FUNCTION
  49
  50 This component does its magic by exporting a C<subinclude> coderef entry to the
  51 stash. This way, it's easily accessible by the templates (which is the most
  52 common use-case).
  53
  54 =head2 C<subinclude( $path, @args )>
  55
  56 This will render and return the body of the included resource (as specified by
  57 C<$path>).
  58
  59 =head1 SUBINCLUDE PLUGINS
  60
  61 The module comes with two subinclude plugins:
  62 L<SubRequest|Catalyst::Plugin::View::Component::SubRequest> and
  63 L<ESI|Catalyst::Plugin::View::Component::ESI>.
  64
  65 By default, the SubRequest plugin will be used. This can be changed in the
  66 view's configuration options (either in the config file or in the view module
  67 itself).
  68
  69 Configuration file example:
  70
  71   <View::TT>
  72       subinclude_plugin   ESI
  73   </View::TT>
  74
  75 =cut
  76
  77 has 'subinclude_plugin' => (
  78     is => 'rw',
  79     isa => 'ClassName'
  80 );
  81
  82 around 'new' => sub {
  83     my $next = shift;
  84     my $class = shift;
  85
  86     my $self = $class->$next( @_ );
  87
  88     my $subinclude_plugin = $self->config->{subinclude_plugin} || 'SubRequest';
  89     my $subinclude_class  = __PACKAGE__ . '::' . $subinclude_plugin;
  90
  91     eval "require $subinclude_class";
  92     croak "Error requiring $subinclude_class: $@" if $@;
  93
  94     $self->subinclude_plugin( $subinclude_class );
  95
  96     $self;
  97 };
  98
  99 around 'render' => sub {
 100     my $next = shift;
 101     my ($self, $c, @args) = @_;
 102
 103     $c->stash->{subinclude} = sub {
 104         $self->subinclude_plugin->generate_subinclude( $c, @_ );
 105     };
 106
 107     $self->$next( $c, @args );
 108 };
 109
 110 =head1 SEE ALSO
 111
 112 L<Catalyst::Plugin::SubRequest|Catalyst::Plugin::SubRequest>,
 113 L<Moose::Role|Moose::Role>, L<Moose|Moose>,
 114 L<http://www.catalystframework.org/calendar/2008/17>
 115
 116 =head1 BUGS
 117
 118 Please report any bugs or feature requests to
 119 C<bug-catalyst-view-component-subinclude at rt.cpan.org>, or through the web interface at
 120 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-View-Component-SubInclude>.
 121 I will be notified, and then you'll automatically be notified of progress on
 122 your bug as I make changes.
 123
 124 =head1 AUTHOR
 125
 126 Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >>
 127
 128 =head1 SPONSORSHIP
 129
 130 Development sponsored by Ionzero LLC L<http://www.ionzero.com/>.
 131
 132 =head1 COPYRIGHT & LICENSE
 133
 134 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
 135
 136 Copyright (C) 2009 Ionzero LLC.
 137
 138 This program is free software; you can redistribute it and/or modify it
 139 under the same terms as Perl itself.
 140
 141 =cut
 142
 143 1;