README

   1 NAME
   2     Catalyst::View::Component::SubInclude - Use subincludes in your Catalyst
   3     views
   4
   5 VERSION
   6     Version 0.09
   7
   8 SYNOPSIS
   9       package MyApp::View::TT;
  10       use Moose;
  11
  12       extends 'Catalyst::View::TT';
  13       with 'Catalyst::View::Component::SubInclude';
  14
  15       __PACKAGE__->config( subinclude_plugin => 'SubRequest' );
  16
  17     Then, somewhere in your templates:
  18
  19       [% subinclude('/my/widget') %]
  20       [% subinclude_using('SubRequest', '/page/footer') %]
  21
  22 DESCRIPTION
  23     "Catalyst::View::Component::SubInclude" allows you to include content in
  24     your templates (or, more generally, somewhere in your view's "render"
  25     processing) which comes from another action in your application. It's
  26     implemented as a Moose::Role, so using Moose in your view is required.
  27
  28     Simply put, it's a way to include the output of a Catalyst sub-request
  29     somewhere in your page.
  30
  31     It's built in an extensible way so that you're free to use sub-requests,
  32     Varnish ESI (<http://www.catalystframework.org/calendar/2008/17>) or any
  33     other sub-include plugin you might want to implement. An LWP plugin
  34     seems useful and might be developed in the future. If you need to
  35     address a resource by it's public path (i.e. the path part trailing
  36     "http://example.com/myapp" then you will need to use
  37     Catalyst::Plugin::SubRequest directly, and not this component.
  38
  39 STASH FUNCTIONS
  40     This component does its magic by exporting a "subinclude" coderef entry
  41     to the stash. This way, it's easily accessible by the templates (which
  42     is the most common use-case).
  43
  44   "subinclude( $path, @args )"
  45     This will render and return the body of the included resource (as
  46     specified by $path) using the default subinclude plugin.
  47
  48   "subinclude_using( $plugin, $path, @args )"
  49     This will render and return the body of the included resource (as
  50     specified by $path) using the specified subinclude plugin.
  51
  52     The "subinclude" function above is implemented basically as a shortcut
  53     which calls this function using the default plugin as the first
  54     parameter.
  55
  56 SUBINCLUDE PLUGINS
  57     The module comes with two subinclude plugins: SubRequest, Visit and ESI.
  58
  59     By default, the "SubRequest" plugin will be used. This can be changed in
  60     the view's configuration options (either in the config file or in the
  61     view module itself).
  62
  63     Configuration file example:
  64
  65       <View::TT>
  66           subinclude_plugin   ESI
  67       </View::TT>
  68
  69   "set_subinclude_plugin( $plugin )"
  70     This method changes the current active subinclude plugin in runtime. It
  71     expects the plugin suffix (e.g. "ESI" or "SubRequest") or a
  72     fully-qualified class name in the
  73     "Catalyst::View::Component::SubInclude" namespace.
  74
  75   Writing plugins
  76     If writing your own plugin, keep in kind plugins are required to
  77     implement a class method "generate_subinclude" with the following
  78     signature:
  79
  80       sub generate_subinclude {
  81           my ($class, $c, @args) = @_;
  82       }
  83
  84     The default plugin is stored in the "subinclude_plugin" which can be
  85     changed in runtime. It expects a fully qualified class name.
  86
  87 SEE ALSO
  88     Catalyst::Plugin::SubRequest, Moose::Role, Moose,
  89     <http://www.catalystframework.org/calendar/2008/17>
  90
  91 BUGS
  92     Please report any bugs or feature requests to
  93     "bug-catalyst-view-component-subinclude at rt.cpan.org", or through the
  94     web interface at
  95     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-View-Component-
  96     SubInclude>. I will be notified, and then you'll automatically be
  97     notified of progress on your bug as I make changes.
  98
  99 AUTHOR
 100     Nilson Santos Figueiredo Junior, "<nilsonsfj at cpan.org>"
 101
 102 CONTRIBUTORS
 103     Tomas Doran (t0m) "<bobtfish@bobtfish.net".
 104
 105 SPONSORSHIP
 106     Development sponsored by Ionzero LLC <http://www.ionzero.com/>.
 107
 108 COPYRIGHT & LICENSE
 109     Copyright (C) 2010 Nilson Santos Figueiredo Junior and the above
 110     contributors.
 111
 112     Copyright (C) 2009 Nilson Santos Figueiredo Junior.
 113
 114     Copyright (C) 2009 Ionzero LLC.
 115
 116     This program is free software; you can redistribute it and/or modify it
 117     under the same terms as Perl itself.
 118