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