[Jifty-commit] r7540 - Template-Declare/branches/mixmaster_shuffle/lib/Template

Jifty commits jifty-commit at lists.jifty.org
Sat Oct 10 08:53:41 EDT 2009


Author: ruz
Date: Sat Oct 10 08:53:41 2009
New Revision: 7540

Modified:
   Template-Declare/branches/mixmaster_shuffle/lib/Template/Declare.pm

Log:
* shuffle methods for better POD and cleanup POD

Modified: Template-Declare/branches/mixmaster_shuffle/lib/Template/Declare.pm
==============================================================================
--- Template-Declare/branches/mixmaster_shuffle/lib/Template/Declare.pm	(original)
+++ Template-Declare/branches/mixmaster_shuffle/lib/Template/Declare.pm	Sat Oct 10 08:53:41 2009
@@ -45,27 +45,6 @@
     return [ reverse @{ $class->dispatch_to } ];
 }
 
-# Removed methods that no longer work (and were never documented anyway).
-# Remove these no-ops after a few releases (added for 0.41).
-
-=begin comment
-
-=head3 aliases
-
-=head3 alias_metadata
-
-=cut
-
-sub aliases {
-    require Carp;
-    Carp::cluck( 'aliases() is a deprecated no-op' );
-}
-
-sub alias_metadata {
-    require Carp;
-    Carp::cluck( 'alias_metadata() is a deprecated no-op' );
-}
-
 =head1 NAME
 
 Template::Declare - Perlish declarative templates
@@ -147,7 +126,7 @@
 
 =head2 Basic usage
 
-A simple HTML example is in the L<SYNOPSIS/SYNOPSIS>. So let's do XUL!
+A simple HTML example is in the L</SYNOPSIS>. So let's do XUL!
 
     package MyApp::Templates;
     use base 'Template::Declare';
@@ -357,10 +336,6 @@
  <h1>Hello</h1>
  <div>first post</div>
 
-=head2 Aliasing and Mixins
-
-=head2 Class Search Dispatching
-
 =head1 METHODS
 
 =head2 init
@@ -424,109 +399,139 @@
 
 }
 
-=head2 buffer
+=head2 show TEMPLATE_NAME
 
-Gets or sets the L<String::BufferStack> object; this is a class method. You
-can use it to manipulate the output from tags as they are output. It's used
-internally to make the tags nest correctly, and be output to the right place.
-We're not sure if there's ever a need for you to frob it by hand, but it does
-enable things like the following:
+    Template::Declare->show( 'howdy', name => 'Larry' );
+    my $output = Template::Declare->show('index');
 
-    template simple => sub {
-       html {
-           head {}
-           body {
-               Template::Declare->buffer->set_filter( sub {uc shift} );
-               p { 'Whee!' }
-               p { 'Hello, world wide web!' }
-               Template::Declare->buffer->clear_top if rand() < 0.5;
-           }
-       }
-    };
+Call C<show> with a C<template_name> and C<Template::Declare> will render that
+template. Subsequent arguments will be passed to the template. Content
+generated by C<show()> can be accessed via the C<output()> method if the
+output method you've chosen returns content instead of outputting it directly.
 
-...which outputs, with equal regularity, either:
+If called in scalar context, this method will also just return the content
+when available.
 
- <html>
-  <head></head>
-  <body>
-   <P>WHEE!</P>
-   <P>HELLO, WORLD WIDE WEB!</P>
-  </body>
- </html>
+=cut
 
-...or:
+sub show {
+    my $class    = shift;
+    my $template = shift;
+    local %Template::Declare::Tags::ELEMENT_ID_CACHE = ();
+    return Template::Declare::Tags::show_page($template => @_);
+}
 
- <html>
-  <head></head>
-  <body></body>
- </html>
+=head2 Mixing templates
 
-We'll leave it to you to judge whether or not that's actually useful.
+Sometimes you want to mix templates from one class into another class;
+C<mix()> is your key to doing so.
 
-=head2 new_buffer_frame
+=head3 mix
 
-  $td->new_buffer_frame();
+    mix Some::Clever::Mixin      under '/mixin';
+    mix Some::Other::Mixin       under '/otmix', setting { name => 'Larry' };
+    mix My::Mixin into My::View, under '/mymix';
 
-Creates a new buffer frame, using L<String::BufferStack/push> with C<private>.
-This use is deprecated in favor of dealing with L</buffer> directly.
+In the first example, if Some::Clever::Mixin
+creates templates named C<foo> and C<bar>, they will be mixed into the calling
+template class as C<mixin/foo> and C<mixin/bar>.
 
-=cut
+The second example mixes in the templates defined in Some::Other::Mixin into
+into the calling class under the C</mymix> path. Furthermore, those mixed-in
+templates have package variables set for them that are accessible only from
+their mixed-in paths. For example, if this template was defined in
+Some::Other::Mixin:
 
-sub new_buffer_frame {
-    __PACKAGE__->buffer->push( private => 1 );
-}
+    template howdy => sub {
+        my $self = shift;
+        outs "Howdy, " . $self->package_variable('name') || 'Jesse';
+    };
+
+Then C<show('mymixin/howdy')> will output "Howdy, Larry", while the output
+from C<show('howdy')> will output "Howdy, Jesse". In other words, package
+variables defined for the mixed-in templates are available only to the mixins
+and not to the original.
+
+In either case, ineritance continues to work. A template package that inherits
+from Some::Other::Mixin, for example, will be able to access both
+C<mymixin/howdy> and C<howdy>.
+
+By default, C<mix()> will mix templates into the class from which it's called.
+But sometimes you might want to mix templates into some other template class.
+Such might be useful for end users to compose template structures from
+collections of template classes. In such a case, use the C<into> keyword to
+specify into what class the templates should be mixed in. The third example
+demonstrates this, where My::Mixin templates are mixed into My::View. Of
+course, you can still specify variables to set for those mixins.
 
-=head2 end_buffer_frame
+If you should happen to forget to pass the C<into> argument before C<under>,
+worry not, C<mix()> will figure it out and do the right thing.
 
-  my $buf = $td->end_buffer_frame();
+For those who prefer a direct OO syntax for mixins, just call C<mix()> as a
+method on the class to be mixed in. To replicate the above three exmaples
+without the use of the sugar:
 
-Deletes and returns the topmost buffer, using L<String::BufferStack/pop>. This
-use is deprecated in favor of dealing with L</buffer> directly..
+    Some::Clver::Mixin->mix( '/mixin' );
+    Some::Other::Mixin->mix( '/otmix', { name => 'Larry' } );
+    My::Mixin->mix('My::View', '/mymix');
 
 =cut
 
-sub end_buffer_frame {
-    __PACKAGE__->buffer->pop;
+sub mix {
+    my $mixin = shift;
+    my ($into, $under);
+    if ( eval { $_[0]->isa(__PACKAGE__) } ) {
+        ($into, $under) = (shift, shift);
+    } elsif ( eval { $_[1]->isa(__PACKAGE__) } ) {
+        ($under, $into) = (shift, shift);
+    } else {
+        $into  = caller(0);
+        $under = shift;
+    }
+    $mixin->_import($into, $under, @_);
 }
 
-=head2 show TEMPLATE_NAME
-
-    Template::Declare->show( 'howdy', name => 'Larry' );
-    my $output = Template::Declare->show('index');
+=head3 package_variable( VARIABLE )
 
-Call C<show> with a C<template_name> and C<Template::Declare> will render that
-template. Subsequent arguments will be passed to the template. Content
-generated by C<show()> can be accessed via the C<output()> method if the
-output method you've chosen returns content instead of outputting it directly.
+  $td->package_variable( $varname => $value );
+  $value = $td->package_variable( $varname );
 
-If called in scalar context, this method will also just return the content
-when available.
+Returns a value set for a mixed-in template's variable, if any were specified
+when the template was mixed-in. See L</mix> for details.
 
 =cut
 
-sub show {
-    my $class    = shift;
-    my $template = shift;
-    local %Template::Declare::Tags::ELEMENT_ID_CACHE = ();
-    return Template::Declare::Tags::show_page($template => @_);
+sub package_variable {
+    my $self = shift;
+    my $var  = shift;
+    if (@_) {
+        $TEMPLATE_VARS->{$self}->{$var} = shift;
+    }
+    return $TEMPLATE_VARS->{$self}->{$var};
 }
 
-=head2 path_for $template
+=head3 package_variables( VARIABLE )
 
-    my $path = Template::Declare->path_for('index');
+    $td->package_variables( $variables );
+    $variables = $td->package_variables;
 
-Returns the path for the template name to be used for show, adjusted with
-paths used in C<mix>.
+Get or set a hash reference of variables for a mixed-in template. See
+L</mix> for details.
 
 =cut
 
-sub path_for {
-    my $class = shift;
-    my $template = shift;
-    return ($class->imported_into ||'') . '/' . $template;
+sub package_variables {
+    my $self = shift;
+    if (@_) {
+        %{ $TEMPLATE_VARS->{$self} } = shift;
+    }
+    return $TEMPLATE_VARS->{$self};
 }
 
-=head2 resolve_template TEMPLATE_PATH INCLUDE_PRIVATE_TEMPLATES
+
+=head2 Templates registration and lookup
+
+=head3 resolve_template TEMPLATE_PATH INCLUDE_PRIVATE_TEMPLATES
 
     my $code = Template::Declare->resolve_template($template);
     my $code = Template::Declare->has_template($template, 1);
@@ -539,10 +544,6 @@
 C<dispatch_to>. For each class, it looks to see if it has a template called
 $template_name directly (or via a mixin).
 
-=head2 has_template TEMPLATE_PATH INCLUDE_PRIVATE_TEMPLATES
-
-An alias for C<resolve_template>.
-
 =cut
 
 sub resolve_template {
@@ -568,9 +569,15 @@
     }
 }
 
+=head3 has_template TEMPLATE_PATH INCLUDE_PRIVATE_TEMPLATES
+
+An alias for C<resolve_template>.
+
+=cut
+
 sub has_template { resolve_template(@_) }
 
-=head2 register_template( TEMPLATE_NAME, CODEREF )
+=head3 register_template( TEMPLATE_NAME, CODEREF )
 
     MyApp::Templates->register_template( howdy => sub { ... } );
 
@@ -589,7 +596,7 @@
     _register_template( $class, _template_name_to_sub($template_name), $code )
 }
 
-=head2 register_private_template( TEMPLATE_NAME, CODEREF )
+=head3 register_private_template( TEMPLATE_NAME, CODEREF )
 
     MyApp::Templates->register_private_template( howdy => sub { ... } );
 
@@ -613,142 +620,161 @@
 
 }
 
-=head2 mix
-
-    mix Some::Clever::Mixin      under '/mixin';
-    mix Some::Other::Mixin       under '/otmix', setting { name => 'Larry' };
-    mix My::Mixin into My::View, under '/mymix';
+=head3 buffer
 
-Sometimes you want to mix templates from one class into another class;
-C<mix()> is your key to doing so. In the first example, if Some::Clever::Mixin
-creates templates named C<foo> and C<bar>, they will be mixed into the calling
-template class as C<mixin/foo> and C<mixin/bar>.
+Gets or sets the L<String::BufferStack> object; this is a class method.
 
-The second example mixes in the templates defined in Some::Other::Mixin into
-into the calling class under the C</mymix> path. Furthermore, those mixed-in
-templates have package variables set for them that are accessible only from
-their mixed-in paths. For example, if this template was defined in
-Some::Other::Mixin:
+You can use it to manipulate the output from tags as they are output. It's used
+internally to make the tags nest correctly, and be output to the right place.
+We're not sure if there's ever a need for you to frob it by hand, but it does
+enable things like the following:
 
-    template howdy => sub {
-        my $self = shift;
-        outs "Howdy, " . $self->package_variable('name') || 'Jesse';
+    template simple => sub {
+       html {
+           head {}
+           body {
+               Template::Declare->buffer->set_filter( sub {uc shift} );
+               p { 'Whee!' }
+               p { 'Hello, world wide web!' }
+               Template::Declare->buffer->clear_top if rand() < 0.5;
+           }
+       }
     };
 
-Then C<show('mymixin/howdy')> will output "Howdy, Larry", while the output
-from C<show('howdy')> will output "Howdy, Jesse". In other words, package
-variables defined for the mixed-in templates are available only to the mixins
-and not to the original.
-
-In either case, ineritance continues to work. A template package that inherits
-from Some::Other::Mixin, for example, will be able to access both
-C<mymixin/howdy> and C<howdy>.
+...which outputs, with equal regularity, either:
 
-By default, C<mix()> will mix templates into the class from which it's called.
-But sometimes you might want to mix templates into some other template class.
-Such might be useful for end users to compose template structures from
-collections of template classes. In such a case, use the C<into> keyword to
-specify into what class the templates should be mixed in. The third example
-demonstrates this, where My::Mixin templates are mixed into My::View. Of
-course, you can still specify variables to set for those mixins.
+ <html>
+  <head></head>
+  <body>
+   <P>WHEE!</P>
+   <P>HELLO, WORLD WIDE WEB!</P>
+  </body>
+ </html>
 
-If you should happen to forget to pass the C<into> argument before C<under>,
-worry not, C<mix()> will figure it out and do the right thing.
+...or:
 
-For those who prefer a direct OO syntax for mixins, just call C<mix()> as a
-method on the class to be mixed in. To replicate the above three exmaples
-without the use of the sugar:
+ <html>
+  <head></head>
+  <body></body>
+ </html>
 
-    Some::Clver::Mixin->mix( '/mixin' );
-    Some::Other::Mixin->mix( '/otmix', { name => 'Larry' } );
-    My::Mixin->mix('My::View', '/mymix');
+We'll leave it to you to judge whether or not that's actually useful.
 
-=cut
+=head2 Helpers
 
-sub mix {
-    my $mixin = shift;
-    my ($into, $under);
-    if ( eval { $_[0]->isa(__PACKAGE__) } ) {
-        ($into, $under) = (shift, shift);
-    } elsif ( eval { $_[1]->isa(__PACKAGE__) } ) {
-        ($under, $into) = (shift, shift);
-    } else {
-        $into  = caller(0);
-        $under = shift;
-    }
-    $mixin->_import($into, $under, @_);
-}
+You don't need to call any of this directly.
 
-=head2 into
+=head3 into
 
-  $class = into $class;
+    $class = into $class;
 
-C<into> is a helper method providing semantic sugar for the C<mix()> method.
+C<into> is a helper method providing semantic sugar for the L</mix> method.
 All it does is return the name of the class on which it was called.
 
 =cut
 
 sub into { shift }
 
-=head2 alias
+=head2 Old, deprecated or just better to avoid
+
+=head3 alias
 
     alias Some::Clever::Mixin under '/mixin';
     alias Some::Other::Mixin  under '/mymix', { name => 'Larry' };
 
 Like C<mix()>, but without support for the C<into> keyword. That is, it mixes
-templates into the calling template class. Deprecated in favor of C<mix()>.
+templates into the calling template class.
+
+B<Deprecated> in favor of L</mix>. Will be supported for a long time, but
+new code should use C<mix()>.
 
 =cut
 
 sub alias { shift->_import(scalar caller(0), @_) }
 
-=head2 import_templates
+=head3 import_templates
 
     import_templates MyApp::Templates under '/something';
 
 Like C<mix()>, but without support for the C<into> or C<setting> keywords.
 That is, it mixes templates into the calling template class and does not
-support package variables for those mixins. Deprecated in favor of C<mix()>.
+support package variables for those mixins.
+
+B<Deprecated> in favor of L</mix>. Will be supported for a long time, but
+new code should use C<mix()>.
 
 =cut
 
 sub import_templates { shift->_import(scalar caller(0), @_) }
 
-=head2 package_variable( VARIABLE )
+=head3 new_buffer_frame
 
-  $td->package_variable( $varname => $value );
-  $value = $td->package_variable( $varname );
+    $td->new_buffer_frame;
+    # same as 
+    $td->buffer->push( private => 1 );
 
-Returns a value set for a mixed-in template's variable, if any were specified
-when the template was mixed-in. See L<mix/mix> for details.
+Creates a new buffer frame, using L<String::BufferStack/push> with C<private>.
+
+B<Deprecated> in favor of dealing with L</buffer> directly.
 
 =cut
 
-sub package_variable {
-    my $self = shift;
-    my $var  = shift;
-    if (@_) {
-        $TEMPLATE_VARS->{$self}->{$var} = shift;
-    }
-    return $TEMPLATE_VARS->{$self}->{$var};
+sub new_buffer_frame {
+    __PACKAGE__->buffer->push( private => 1 );
 }
 
-=head2 package_variables( VARIABLE )
+=head3 end_buffer_frame
 
-  $td->package_variables( $variables );
-  $variables = $td->package_variables( );
+    my $buf = $td->end_buffer_frame;
+    # same as
+    my $buf = $td->buffer->pop;
 
-Get or set a hash reference of variables for a mixed-in template. See
-L<mix/mix> for details.
+Deletes and returns the topmost buffer, using L<String::BufferStack/pop>.
+
+B<Deprecated> in favor of dealing with L</buffer> directly.
 
 =cut
 
-sub package_variables {
-    my $self = shift;
-    if (@_) {
-        %{ $TEMPLATE_VARS->{$self} } = shift;
-    }
-    return $TEMPLATE_VARS->{$self};
+sub end_buffer_frame {
+    __PACKAGE__->buffer->pop;
+}
+
+=head3 path_for $template
+
+    my $path = Template::Declare->path_for('index');
+
+Returns the path for the template name to be used for show, adjusted with
+paths used in C<mix>.
+
+=cut
+
+# Removed methods that no longer work (and were never documented anyway).
+# Remove these no-ops after a few releases (added for 0.41).
+
+=begin comment
+
+=head3 aliases
+
+=head3 alias_metadata
+
+=end comment
+
+=cut
+
+sub aliases {
+    require Carp;
+    Carp::cluck( 'aliases() is a deprecated no-op' );
+}
+
+sub alias_metadata {
+    require Carp;
+    Carp::cluck( 'alias_metadata() is a deprecated no-op' );
+}
+
+sub path_for {
+    my $class = shift;
+    my $template = shift;
+    return ($class->imported_into ||'') . '/' . $template;
 }
 
 sub _templates_for {
@@ -845,7 +871,8 @@
 sub _import_code {
     my ($tname, $from, $to, $vars) = @_;
     my $code = $from->_find_template_sub( _template_name_to_sub($tname) );
-    return $to eq $from ? $code : sub { $code->($to, @_) } unless $vars;
+    return $to eq $from ? $code : sub { $code->($to, @_) }
+        unless $vars;
     return sub {
         # XXX This does not seem to be needed.
         # shift @_;  # Get rid of the passed-in "$self" class.
@@ -971,7 +998,7 @@
 
 Crawling all over, baby. Be very, very careful. This code is so cutting edge,
 it can only be fashioned from carbon nanotubes. But we're already using this
-thing in production :) Make sure you have read the L<PITFALLS/PITFALLS>
+thing in production :) Make sure you have read the L</PITFALLS>
 section above :)
 
 Some specific bugs and design flaws that we'd love to see fixed.


More information about the Jifty-commit mailing list