[Jifty-commit] r7474 - in Template-Declare/trunk: . lib/Template t

[Jifty commits]

Author: theory
Date: Thu Sep  3 16:43:27 2009
New Revision: 7474

Modified:
   Template-Declare/trunk/Changes
   Template-Declare/trunk/lib/Template/Declare.pm
   Template-Declare/trunk/lib/Template/Declare/Tags.pm
   Template-Declare/trunk/t/aliasing.t

Log:
Document `alias` and tweak a few other things.

* Updated comments on the `t/aliasing.t` tests, adding a couple more assertions so that diagnostics are more useful. Did this as reading through the tests so that I could understand the point of aliasing (more or less).
* Documented the `alias` function. Please let me know if I got it wrong.
* Fixed the documentation in Template::Declare::Tags to document `import_templates` rather than `import`. The latter does something completely different.


Modified: Template-Declare/trunk/Changes
==============================================================================
--- Template-Declare/trunk/Changes	(original)
+++ Template-Declare/trunk/Changes	Thu Sep  3 16:43:27 2009
@@ -2,6 +2,7 @@
 
 * Support for inline tagset definitions. Thanks to Olivier 'dolmen' Mengué
 	[rt.cpan.org #48642]
+* Documented aliasing.
 
 0.40 - 2009-07-08
 * Fix subname issue with the debugger and specifically Devel::NYTProf

Modified: Template-Declare/trunk/lib/Template/Declare.pm
==============================================================================
--- Template-Declare/trunk/lib/Template/Declare.pm	(original)
+++ Template-Declare/trunk/lib/Template/Declare.pm	Thu Sep  3 16:43:27 2009
@@ -387,9 +387,29 @@
     return Template::Declare::Tags::show_page($template => @_);
 }
 
-=head2 alias
+=head2 alias TEMPLATE_ROOT under PATH
 
  alias Some::Clever::Mixin under '/mixin';
+ alias Some::Other::Mixin  under '/mymix', { name => 'Larry' };
+
+Sometimes you want to alias templates to a subpath, or mix them into an
+existing template path. Use C<alias> to do so. In the first example, if
+Some::Clever::Mixin creates templates named "foo" and "bar", they will be
+aliased to "mixin/foo" and "mixin/bar".
+
+The second example mixes in the templates defined in Some::Other::Mixin into
+the "/mymix" path and defines a package variable for use only by the alias.
+If this template was defined in Some::Other::Mixin:
+
+  template 'howdy' => sub {
+      my $self = shift;
+      outs "Howdy, " . $self->package_variable('name') || 'Jesse';
+  };
+
+Then use of the "mymixin/howdy" template will output "Howdy, Lary", while use
+of the original template, "howdy", will output "Howdy, Jesse". In other words,
+package variables defined for the alias are available only to the alias, and
+not to the original.
 
 =cut
 

Modified: Template-Declare/trunk/lib/Template/Declare/Tags.pm
==============================================================================
--- Template-Declare/trunk/lib/Template/Declare/Tags.pm	(original)
+++ Template-Declare/trunk/lib/Template/Declare/Tags.pm	Thu Sep  3 16:43:27 2009
@@ -816,10 +816,11 @@
     return $val;
 }
 
-=head2 import 'Package' under 'path'
+=head2 import_templates 'Package' under 'path'
 
-Import the templates from C<Package> into the subpath 'path' of the current package, clobbering any
-of your own package's templates that you'd already defined.
+Import the templates from C<Package> into the subpath 'path' of the current
+package, clobbering any of your own package's templates that you'd already
+defined.
 
 =cut
 

Modified: Template-Declare/trunk/t/aliasing.t
==============================================================================
--- Template-Declare/trunk/t/aliasing.t	(original)
+++ Template-Declare/trunk/t/aliasing.t	Thu Sep  3 16:43:27 2009
@@ -44,21 +44,23 @@
 use Template::Declare::Tags;
 Template::Declare->init( roots => ['Wifty::UI'] );
 
-use Test::More tests => 16;
+use Test::More tests => 19;
 require "t/utils.pl";
 
-ok( Wifty::UI::aliased_pkg->has_template('aliased') );
-ok( !  Wifty::UI->has_template('aliased') );
-ok( Wifty::UI::aliased_subclass_pkg->has_template('aliased') );
+ok( Wifty::UI::aliased_pkg->has_template('aliased'), 'Aliased package should have template' );
+ok( !  Wifty::UI->has_template('aliased'), 'Unrelated package should not' );
+ok( Wifty::UI::aliased_subclass_pkg->has_template('aliased'), 'Subclass should' );
 
-ok( Template::Declare->has_template('aliased_pkg/aliased') );
+ok( Template::Declare->has_template('aliased_pkg/aliased'), 'TD should find alias' );
 
 
-ok( Template::Declare->has_template('aliased_subclass_pkg/aliased'), "When you subclass and then alias, the superclass's aliass are there" );
+ok( Template::Declare->has_template('aliased_subclass_pkg/aliased'),
+    'Alias should be visible in a subclass, too' );
 
 {
-    my $simple = ( show('aliased_pkg/aliased') );
-    like( $simple, qr'This is aliased' );
+    # Try the first alias with a variable set.
+    ok my $simple = ( show('aliased_pkg/aliased') ), 'Should get output from alias template';
+    like( $simple, qr'This is aliased', 'Its output should be right' );
     like( $simple, qr'Variable SET' , "The variable was set");
     like( $simple, qr'Wifty::UI::aliased_pkg',
         '$self is correct in template block' );
@@ -66,22 +68,22 @@
 }
 
 {
-    my $simple = ( show('aliased_pkg2/aliased') );
-    like( $simple, qr'This is aliased' );
-    unlike( $simple, qr'Varialble SET' , "The variable was  not set on second aliasing");
+    # Try the second alias with no variable.
+    ok my $simple = ( show('aliased_pkg2/aliased') ), 'Should get output from second alias';
+    like( $simple, qr'This is aliased', 'Its output should be right' );
+    unlike( $simple, qr'Varialble SET' , 'But the variable should not be set');
     like( $simple, qr'Wifty::UI::aliased_pkg',
         '$self is correct in template block' );
     ok_lint($simple);
 }
 
-
-
 {
-    my $simple = ( show('aliased_subclass_pkg/aliased') );
+    ok my $simple = ( show('aliased_subclass_pkg/aliased') ),
+        'Should get output from superclass template';
     like(
         $simple,
         qr'This is aliased',
-        "We got the aliased version in the subclass"
+        "We should get the aliased version in the subclass"
     );
     like(
         $simple,