X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FView%2FComponent%2FSubInclude.pm;h=33c2b063e4e8606ae31b15cd24c775b2cf44b144;hb=4162256ab5c7c2446154a05e8c5dfdf1bd9a9a53;hp=97023c61746499819a4b46352efae512d192b088;hpb=4e3277560cc20740e2cdb58f4f9cf8eda74c9d73;p=catagits%2FCatalyst-View-Component-SubInclude.git diff --git a/lib/Catalyst/View/Component/SubInclude.pm b/lib/Catalyst/View/Component/SubInclude.pm index 97023c6..33c2b06 100644 --- a/lib/Catalyst/View/Component/SubInclude.pm +++ b/lib/Catalyst/View/Component/SubInclude.pm @@ -2,7 +2,12 @@ package Catalyst::View::Component::SubInclude; use Moose::Role; use Carp qw/croak/; -use namespace::clean qw/croak/; +use Catalyst::Utils (); +use Class::MOP (); +use MooseX::Types::Moose qw/Str HashRef/; +use namespace::clean -except => 'meta'; + +with 'Catalyst::Component::ContextClosure'; =head1 NAME @@ -10,11 +15,12 @@ Catalyst::View::Component::SubInclude - Use subincludes in your Catalyst views =head1 VERSION -Version 0.01 +Version 0.11 =cut -our $VERSION = '0.01'; +our $VERSION = '0.11'; +$VERSION = eval $VERSION; =head1 SYNOPSIS @@ -29,87 +35,171 @@ our $VERSION = '0.01'; 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 +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. +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. +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. -=head1 STASH FUNCTION +=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 +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>). +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 and +The module comes with two subinclude plugins: +L, +L and L. -By default, the SubRequest plugin will be used. This can be changed in the +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 - +itself). + + __PACKAGE__->config( + subinclude_plugin => 'ESI', + subinclude => { + 'SubRequest' => { + keep_stash => 1, + }, + 'HTTP::POST' => { + class => 'HTTP', + http_method => 'POST', + ua_timeout => '10', + uri_map => { + '/foo/' => 'http://www.foo.com/', + }, + }, + }, + ); + +You can change each plugins' configuration through the keys in the 'subinclude' +config key (example above) + +=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, +); + +has subinclude => ( + is => 'ro', + isa => HashRef, + default => sub { {} }, +); around 'new' => sub { my $next = shift; my $class = shift; - + 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->set_subinclude_plugin( $subinclude_plugin ); - $self->subinclude_plugin( $subinclude_class ); - $self; }; -around 'render' => sub { - my $next = shift; +before 'render' => sub { my ($self, $c, @args) = @_; - - $c->stash->{subinclude} = sub { - $self->subinclude_plugin->generate_subinclude( $c, @_ ); - }; - $self->$next( $c, @args ); + $c->stash->{subinclude} = $self->make_context_closure(sub { $self->_subinclude( @_ ) }, $c); + $c->stash->{subinclude_using} = $self->make_context_closure(sub { $self->_subinclude_using( @_ ) }, $c); }; +sub set_subinclude_plugin { + my ($self, $plugin) = @_; + + my $subinclude_class = blessed $self->_subinclude_plugin_class_instance( $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_instance($plugin); + $plugin->generate_subinclude( $c, @args ); +} + +has _subinclude_plugin_class_instance_cache => ( + isa => HashRef, + is => 'ro', + default => sub { {} }, +); + +sub _subinclude_plugin_class_instance { + my ($self, $plugin) = @_; + + my $cache = $self->_subinclude_plugin_class_instance_cache; + return $cache->{$plugin} if exists $cache->{$plugin}; + + my $plugin_config = Catalyst::Utils::merge_hashes( + $self->subinclude->{ALL}||{}, + $self->subinclude->{$plugin}||{} + ); + my $short_class = $plugin_config->{'class'} ? + delete $plugin_config->{'class'} + : $plugin; + my $class = $short_class =~ /::/ ? + $short_class + : __PACKAGE__ . '::' . $short_class; + + Class::MOP::load_class($class); + + return $cache->{$class} = $class->new($plugin_config); +} + =head1 SEE ALSO -L, +L, L, L, L @@ -125,12 +215,22 @@ your bug as I make changes. Nilson Santos Figueiredo Junior, C<< >> +=head1 CONTRIBUTORS + +Tomas Doran (t0m) C<< >. + +Vladimir Timofeev, C<< >>. + +Wallace Reis (wreis) C<< >>. + =head1 SPONSORSHIP Development sponsored by Ionzero LLC L. =head1 COPYRIGHT & LICENSE +Copyright (C) 2010 Nilson Santos Figueiredo Junior and the above contributors. + Copyright (C) 2009 Nilson Santos Figueiredo Junior. Copyright (C) 2009 Ionzero LLC.