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 If writing your own plugin, keep in kind plugins are required to implement a
  76 class method C<generate_subinclude> with the following signature:
  77
  78   sub generate_subinclude {
  79       my ($class, $c, @args) = @_;
  80   }
  81
  82 =cut
  83
  84 has 'subinclude_plugin' => (
  85     is => 'rw',
  86     isa => 'ClassName'
  87 );
  88
  89 around 'new' => sub {
  90     my $next = shift;
  91     my $class = shift;
  92
  93     my $self = $class->$next( @_ );
  94
  95     my $subinclude_plugin = $self->config->{subinclude_plugin} || 'SubRequest';
  96     my $subinclude_class  = __PACKAGE__ . '::' . $subinclude_plugin;
  97
  98     eval "require $subinclude_class";
  99     croak "Error requiring $subinclude_class: $@" if $@;
 100
 101     $self->subinclude_plugin( $subinclude_class );
 102
 103     $self;
 104 };
 105
 106 around 'render' => sub {
 107     my $next = shift;
 108     my ($self, $c, @args) = @_;
 109
 110     $c->stash->{subinclude} = sub {
 111         $self->subinclude_plugin->generate_subinclude( $c, @_ );
 112     };
 113
 114     $self->$next( $c, @args );
 115 };
 116
 117 =head1 SEE ALSO
 118
 119 L<Catalyst::Plugin::SubRequest|Catalyst::Plugin::SubRequest>,
 120 L<Moose::Role|Moose::Role>, L<Moose|Moose>,
 121 L<http://www.catalystframework.org/calendar/2008/17>
 122
 123 =head1 BUGS
 124
 125 Please report any bugs or feature requests to
 126 C<bug-catalyst-view-component-subinclude at rt.cpan.org>, or through the web interface at
 127 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-View-Component-SubInclude>.
 128 I will be notified, and then you'll automatically be notified of progress on
 129 your bug as I make changes.
 130
 131 =head1 AUTHOR
 132
 133 Nilson Santos Figueiredo Junior, C<< <nilsonsfj at cpan.org> >>
 134
 135 =head1 SPONSORSHIP
 136
 137 Development sponsored by Ionzero LLC L<http://www.ionzero.com/>.
 138
 139 =head1 COPYRIGHT & LICENSE
 140
 141 Copyright (C) 2009 Nilson Santos Figueiredo Junior.
 142
 143 Copyright (C) 2009 Ionzero LLC.
 144
 145 This program is free software; you can redistribute it and/or modify it
 146 under the same terms as Perl itself.
 147
 148 =cut
 149
 150 1;