X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FView%2FComponent%2FSubInclude.pm;h=e4505e064b1e91c625aa61b732e86060578c8c82;hb=7c937cccd1caf12c59b11f07ee76144f770b3ad8;hp=a17a890bbb12017d542b823003013be168426be1;hpb=307266327522e574890b4c59074c0598d17e8cd2;p=catagits%2FCatalyst-View-Component-SubInclude.git diff --git a/lib/Catalyst/View/Component/SubInclude.pm b/lib/Catalyst/View/Component/SubInclude.pm index a17a890..e4505e0 100644 --- a/lib/Catalyst/View/Component/SubInclude.pm +++ b/lib/Catalyst/View/Component/SubInclude.pm @@ -4,10 +4,108 @@ use Moose::Role; use Carp qw/croak/; use namespace::clean qw/croak/; +=head1 NAME + +Catalyst::View::Component::SubInclude - Use subincludes in your Catalyst views + +=head1 VERSION + +Version 0.05 + +=cut + +our $VERSION = '0.05'; + +=head1 SYNOPSIS + + package MyApp::View::TT; + use Moose; + + extends 'Catalyst::View::TT'; + with 'Catalyst::View::Component::SubInclude'; + + __PACKAGE__->config( subinclude_plugin => 'SubRequest' ); + +Then, somewhere in your templates: + + [% subinclude('/my/widget') %] + [% subinclude_using('SubRequest', '/page/footer') %] + +=head1 DESCRIPTION + +C allows you to include content in your +templates (or, more generally, somewhere in your view's C processing) +which comes from another action in your application. It's implemented as a +L, so using L in your view is required. + +Simply put, it's a way to include the output of a Catalyst sub-request somewhere +in your page. + +It's built in an extensible way so that you're free to use sub-requests, Varnish +ESI (L) or any other +sub-include plugin you might want to implement. An LWP plugin seems useful and +might be developed in the future. + +=head1 STASH FUNCTIONS + +This component does its magic by exporting a C coderef entry to the +stash. This way, it's easily accessible by the templates (which is the most +common use-case). + +=head2 C + +This will render and return the body of the included resource (as specified by +C<$path>) using the default subinclude plugin. + +=head2 C + +This will render and return the body of the included resource (as specified by +C<$path>) using the specified subinclude plugin. + +The C function above is implemented basically as a shortcut which +calls this function using the default plugin as the first parameter. + +=head1 SUBINCLUDE PLUGINS + +The module comes with two subinclude plugins: +L, +L and +L. + +By default, the C plugin will be used. This can be changed in the +view's configuration options (either in the config file or in the view module +itself). + +Configuration file example: + + + subinclude_plugin ESI + + +=head2 C + +This method changes the current active subinclude plugin in runtime. It expects +the plugin suffix (e.g. C or C) or a fully-qualified class +name in the C namespace. + +=head2 Writing plugins + +If writing your own plugin, keep in kind plugins are required to implement a +class method C with the following signature: + + sub generate_subinclude { + my ($class, $c, @args) = @_; + } + +The default plugin is stored in the C which can be changed +in runtime. It expects a fully qualified class name. + +=cut + has 'subinclude_plugin' => ( is => 'rw', - isa => 'ClassName' -); + isa => 'Str' +); around 'new' => sub { my $next = shift; @@ -16,12 +114,7 @@ around 'new' => sub { my $self = $class->$next( @_ ); my $subinclude_plugin = $self->config->{subinclude_plugin} || 'SubRequest'; - my $subinclude_class = __PACKAGE__ . '::' . $subinclude_plugin; - - eval "require $subinclude_class"; - croak "Error requiring $subinclude_class: $@" if $@; - - $self->subinclude_plugin( $subinclude_class ); + $self->set_subinclude_plugin( $subinclude_plugin ); $self; }; @@ -30,11 +123,76 @@ around 'render' => sub { my $next = shift; my ($self, $c, @args) = @_; - $c->stash->{subinclude} = sub { - $self->subinclude_plugin->generate_subinclude( $c, @_ ); - }; + $c->stash->{subinclude} = sub { $self->_subinclude( $c, @_ ) }; + $c->stash->{subinclude_using} = sub { $self->_subinclude_using( $c, @_ ) }; $self->$next( $c, @args ); }; +sub set_subinclude_plugin { + my ($self, $plugin) = @_; + + my $subinclude_class = $self->_subinclude_plugin_class_name( $plugin ); + $self->subinclude_plugin( $subinclude_class ); +} + +sub _subinclude { + my ($self, $c, @args) = @_; + $self->_subinclude_using( $c, $self->subinclude_plugin, @args ); +} + +sub _subinclude_using { + my ($self, $c, $plugin, @args) = @_; + $plugin = $self->_subinclude_plugin_class_name($plugin); + $plugin->generate_subinclude( $c, @args ); +} + +sub _subinclude_plugin_class_name { + my ($self, $plugin) = @_; + + # check if name is already fully qualified + my $pkg = __PACKAGE__; + return $plugin if $plugin =~ /^$pkg/; + + my $class_name = __PACKAGE__ . '::' . $plugin; + + eval "require $class_name"; + croak "Error requiring $class_name: $@" if $@; + + $class_name; +} + +=head1 SEE ALSO + +L, +L, L, +L + +=head1 BUGS + +Please report any bugs or feature requests to +C, or through the web interface at +L. +I will be notified, and then you'll automatically be notified of progress on +your bug as I make changes. + +=head1 AUTHOR + +Nilson Santos Figueiredo Junior, C<< >> + +=head1 SPONSORSHIP + +Development sponsored by Ionzero LLC L. + +=head1 COPYRIGHT & LICENSE + +Copyright (C) 2009 Nilson Santos Figueiredo Junior. + +Copyright (C) 2009 Ionzero LLC. + +This program is free software; you can redistribute it and/or modify it +under the same terms as Perl itself. + +=cut + 1;