X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README;h=0cfd4b741bf905d4432de3f7efc9153a8ed9b54d;hb=HEAD;hp=4988a16b5732abecef99300b677806515ea18403;hpb=9399de67c73e690611087f7aa359537a7bef4b46;p=catagits%2FCatalyst-View-Component-SubInclude.git

diff --git a/README b/README
index 4988a16..0cfd4b7 100644
--- a/README
+++ b/README
@@ -3,7 +3,21 @@ NAME
     views
 
 VERSION
-    Version 0.07
+    Version 0.11
+
+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') %]
 
 DESCRIPTION
     "Catalyst::View::Component::SubInclude" allows you to include content in
@@ -16,23 +30,103 @@ DESCRIPTION
 
     It's built in an extensible way so that you're free to use sub-requests,
     Varnish ESI (<http://www.catalystframework.org/calendar/2008/17>) or any
-    other sub-include plugin you might want to implement. An LWP plugin
-    seems useful and might be developed in the future.
+    other sub-include plugin you might want to implement.
+
+STASH FUNCTIONS
+    This component does its magic by exporting a "subinclude" coderef entry
+    to the stash. This way, it's easily accessible by the templates (which
+    is the most common use-case).
+
+  "subinclude( $path, @args )"
+    This will render and return the body of the included resource (as
+    specified by $path) using the default subinclude plugin.
+
+  "subinclude_using( $plugin, $path, @args )"
+    This will render and return the body of the included resource (as
+    specified by $path) using the specified subinclude plugin.
+
+    The "subinclude" function above is implemented basically as a shortcut
+    which calls this function using the default plugin as the first
+    parameter.
+
+SUBINCLUDE PLUGINS
+    The module comes with two subinclude plugins: SubRequest, Visit and ESI.
+
+    By default, the "SubRequest" 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).
+
+        __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)
+
+  "set_subinclude_plugin( $plugin )"
+    This method changes the current active subinclude plugin in runtime. It
+    expects the plugin suffix (e.g. "ESI" or "SubRequest") or a
+    fully-qualified class name in the
+    "Catalyst::View::Component::SubInclude" namespace.
+
+  Writing plugins
+    If writing your own plugin, keep in kind plugins are required to
+    implement a class method "generate_subinclude" with the following
+    signature:
+
+      sub generate_subinclude {
+          my ($class, $c, @args) = @_;
+      }
+
+    The default plugin is stored in the "subinclude_plugin" which can be
+    changed in runtime. It expects a fully qualified class name.
 
 SEE ALSO
     Catalyst::Plugin::SubRequest, Moose::Role, Moose,
     <http://www.catalystframework.org/calendar/2008/17>
 
+BUGS
+    Please report any bugs or feature requests to
+    "bug-catalyst-view-component-subinclude at rt.cpan.org", or through the
+    web interface at
+    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-View-Component-
+    SubInclude>. I will be notified, and then you'll automatically be
+    notified of progress on your bug as I make changes.
+
 AUTHOR
     Nilson Santos Figueiredo Junior, "<nilsonsfj at cpan.org>"
 
+CONTRIBUTORS
+    Tomas Doran (t0m) "<bobtfish@bobtfish.net".
+
+    Vladimir Timofeev, "<vovkasm at gmail.com>".
+
+    Wallace Reis (wreis) "<wreis@cpan.org>".
+
 SPONSORSHIP
     Development sponsored by Ionzero LLC <http://www.ionzero.com/>.
 
 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.
 
     This program is free software; you can redistribute it and/or modify it
     under the same terms as Perl itself.
+