README

   1 NAME
   2     Catalyst::View::Component::SubInclude - Use subincludes in your Catalyst
   3     views
   4
   5 VERSION
   6     Version 0.11
   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.
  34
  35 STASH FUNCTIONS
  36     This component does its magic by exporting a "subinclude" coderef entry
  37     to the stash. This way, it's easily accessible by the templates (which
  38     is the most common use-case).
  39
  40   "subinclude( $path, @args )"
  41     This will render and return the body of the included resource (as
  42     specified by $path) using the default subinclude plugin.
  43
  44   "subinclude_using( $plugin, $path, @args )"
  45     This will render and return the body of the included resource (as
  46     specified by $path) using the specified subinclude plugin.
  47
  48     The "subinclude" function above is implemented basically as a shortcut
  49     which calls this function using the default plugin as the first
  50     parameter.
  51
  52 SUBINCLUDE PLUGINS
  53     The module comes with two subinclude plugins: SubRequest, Visit and ESI.
  54
  55     By default, the "SubRequest" plugin will be used. This can be changed in
  56     the view's configuration options (either in the config file or in the
  57     view module itself).
  58
  59         __PACKAGE__->config(
  60             subinclude_plugin => 'ESI',
  61             subinclude => {
  62                 'SubRequest' => {
  63                     keep_stash => 1,
  64                 },
  65                 'HTTP::POST' => {
  66                     class => 'HTTP',
  67                     http_method => 'POST',
  68                     ua_timeout => '10',
  69                     uri_map => {
  70                         '/foo/' => 'http://www.foo.com/',
  71                     },
  72                 },
  73             },
  74         );
  75
  76     You can change each plugins' configuration through the keys in the
  77     'subinclude' config key (example above)
  78
  79   "set_subinclude_plugin( $plugin )"
  80     This method changes the current active subinclude plugin in runtime. It
  81     expects the plugin suffix (e.g. "ESI" or "SubRequest") or a
  82     fully-qualified class name in the
  83     "Catalyst::View::Component::SubInclude" namespace.
  84
  85   Writing plugins
  86     If writing your own plugin, keep in kind plugins are required to
  87     implement a class method "generate_subinclude" with the following
  88     signature:
  89
  90       sub generate_subinclude {
  91           my ($class, $c, @args) = @_;
  92       }
  93
  94     The default plugin is stored in the "subinclude_plugin" which can be
  95     changed in runtime. It expects a fully qualified class name.
  96
  97 SEE ALSO
  98     Catalyst::Plugin::SubRequest, Moose::Role, Moose,
  99     <http://www.catalystframework.org/calendar/2008/17>
 100
 101 BUGS
 102     Please report any bugs or feature requests to
 103     "bug-catalyst-view-component-subinclude at rt.cpan.org", or through the
 104     web interface at
 105     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-View-Component-
 106     SubInclude>. I will be notified, and then you'll automatically be
 107     notified of progress on your bug as I make changes.
 108
 109 AUTHOR
 110     Nilson Santos Figueiredo Junior, "<nilsonsfj at cpan.org>"
 111
 112 CONTRIBUTORS
 113     Tomas Doran (t0m) "<bobtfish@bobtfish.net".
 114
 115     Vladimir Timofeev, "<vovkasm at gmail.com>".
 116
 117     Wallace Reis (wreis) "<wreis@cpan.org>".
 118
 119 SPONSORSHIP
 120     Development sponsored by Ionzero LLC <http://www.ionzero.com/>.
 121
 122 COPYRIGHT & LICENSE
 123     Copyright (C) 2010 Nilson Santos Figueiredo Junior and the above
 124     contributors.
 125
 126     Copyright (C) 2009 Nilson Santos Figueiredo Junior.
 127
 128     Copyright (C) 2009 Ionzero LLC.
 129
 130     This program is free software; you can redistribute it and/or modify it
 131     under the same terms as Perl itself.
 132