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>, so using L<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 return the body of the requested resource (as specified by C<$path>).
  57
  58 =head1 SUBINCLUDE PLUGINS
  59
  60 The module comes with two subinclude plugins:
  61 L<SubRequest|Catalyst::Plugin::View::Component::SubRequest> and
  62 L<ESI|Catalyst::Plugin::View::Component::ESI>.
  63
  64 By default, the SubRequest plugin will be used. This can be changed in the
  65 view's configuration options (either in the config file or in the view module
  66 itself).
  67
  68 Configuration file example:
  69
  70   <View::TT>
  71       subinclude_plugin   ESI
  72   </View::TT>
  73
  74 =cut
  75
  76 has 'subinclude_plugin' => (
  77     is => 'rw',
  78     isa => 'ClassName'
  79 );
  80
  81 around 'new' => sub {
  82     my $next = shift;
  83     my $class = shift;
  84
  85     my $self = $class->$next( @_ );
  86
  87     my $subinclude_plugin = $self->config->{subinclude_plugin} || 'SubRequest';
  88     my $subinclude_class  = __PACKAGE__ . '::' . $subinclude_plugin;
  89
  90     eval "require $subinclude_class";
  91     croak "Error requiring $subinclude_class: $@" if $@;
  92
  93     $self->subinclude_plugin( $subinclude_class );
  94
  95     $self;
  96 };
  97
  98 around 'render' => sub {
  99     my $next = shift;
 100     my ($self, $c, @args) = @_;
 101
 102     $c->stash->{subinclude} = sub {
 103         $self->subinclude_plugin->generate_subinclude( $c, @_ );
 104     };
 105
 106     $self->$next( $c, @args );
 107 };
 108
 109 =head1 SEE ALSO
 110
 111 L<Catalyst::Plugin::SubRequest>, L<Moose::Role>, L<Moose>,
 112 L<http://www.catalystframework.org/calendar/2008/17>
 113
 114 =head1 BUGS
 115
 116 Please report any bugs or feature requests to
 117 C<bug-catalyst-view-component-subinclude at rt.cpan.org>, or through the web interface at
 118 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-View-Component-SubInclude>.
 119 I will be notified, and then you'll automatically be notified of progress on
 120 your bug as I make changes.
 121
 122 =head1 AUTHOR
 123
 124 Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >>
 125
 126 =head1 SPONSORSHIP
 127
 128 Development sponsored by Ionzero LLC L<http://www.ionzero.com/>.
 129
 130 =head1 COPYRIGHT & LICENSE
 131
 132 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
 133
 134 Copyright (C) 2009 Ionzero LLC.
 135
 136 This program is free software; you can redistribute it and/or modify it
 137 under the same terms as Perl itself.
 138
 139 =cut
 140
 141 1;