[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