added documentation for nested helpers

mojolicious · Aug 10, 2014 · 9ed50ab · 9ed50ab
1 parent 2d05439
commit 9ed50ab
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 3 deletions.
diff --git a/lib/Mojolicious/Guides/Rendering.pod b/lib/Mojolicious/Guides/Rendering.pod
@@ -868,7 +868,9 @@ everything.
   % debug 'Hello from a template!';
 
 Helpers can also accept template blocks as last argument, this for example
-allows very pleasant to use tag helpers and filters.
+allows very pleasant to use tag helpers and filters. Wrapping the helper
+result into a L<Mojo::ByteStream> object can prevent accidental double
+escaping.
 
   use Mojolicious::Lite;
   use Mojo::ByteStream;
@@ -892,8 +894,36 @@ allows very pleasant to use tag helpers and filters.
     More text.
   % end
 
-Wrapping the helper result into a L<Mojo::ByteStream> object can prevent
-accidental double escaping.
+Similar to stash values you can use a prefix like C<myapp.*> to hide helpers
+from templates and organize them into namespaces when your application grows.
+Every prefix automatically becomes a helper that returns a proxy object on
+which you can call the nested helpers.
+
+  use Mojolicious::Lite;
+
+  helper 'cache_control.no_caching' => sub {
+    my $c = shift;
+    $c->res->header->cache_control('private, max-age=0, no-cache');
+  };
+
+  helper 'cache_control.five_mins' => sub {
+    my $c = shift;
+    $c->res->header->cache_control('public, max-age=300');
+  };
+
+  get '/news' => sub {
+    my $c = shift;
+    $c->cache_control->no_caching;
+    $c->render(text => 'Always up to date.');
+  };
+
+  get '/some_older_story' => sub {
+    my $c = shift;
+    $c->cache_control->five_mins;
+    $c->render(text => 'This one can be cached for a bit.');
+  };
+
+  app->start;
 
 =head2 Helper plugins
 

diff --git a/lib/Mojolicious/Renderer.pm b/lib/Mojolicious/Renderer.pm
@@ -403,6 +403,13 @@ Register a new helper.
 
 Get a C<DATA> section template by name, usually used by handlers.
 
+=head2 get_helper
+
+  my $helper = $renderer->get_helper('url_for');
+
+Get helper without prefix or generate a helper dynamically for a prefix,
+generated helpers return a proxy object on which nested helpers can be called.
+
 =head2 render
 
   my ($output, $format) = $renderer->render(Mojolicious::Controller->new);