[Jifty-commit] r3888 - in Template-Declare/lib/Template: . Declare

[jifty-commit at lists.jifty.org]

Author: agentz
Date: Mon Aug 13 22:44:55 2007
New Revision: 3888

Modified:
   Template-Declare/lib/Template/Declare.pm
   Template-Declare/lib/Template/Declare/TagSet/HTML.pm
   Template-Declare/lib/Template/Declare/Tags.pm

Log:
[TD]
* added a PITFALLS section to T::D's POD.
* added a global sub append_attr to provide friendly diagnostics and the infamous "Undefined subroutine &Template::Declare::Tags::append_attr called at ..." is now gone.

Modified: Template-Declare/lib/Template/Declare.pm
==============================================================================
--- Template-Declare/lib/Template/Declare.pm	(original)
+++ Template-Declare/lib/Template/Declare.pm	Mon Aug 13 22:44:55 2007
@@ -211,7 +211,7 @@
  package MyApp::Templates;
  use Template::Declare::Tags;
  use base 'Template::Declare';
-                        
+
  template before => sub {
      h1 {
          outs "Welcome to ";
@@ -232,7 +232,7 @@
  Template::Declare->init( roots => ['MyApp::Templates'], postprocessor => \&emphasize);
  print Template::Declare->show( 'before');
  print Template::Declare->show( 'after');
-               
+
  sub emphasize {
      my $text = shift;
      $text =~ s{_(.+?)_}{<em>$1</em>}g;
@@ -267,7 +267,73 @@
 
 =back
 
-=cut 
+=head2 PITFALLS
+
+We're reusing the perl interpreter to for our templating langauge, but Perl was not designed perfectly for our purpose here. Here are some known pitfalls while you're scripting your templates with this module.
+
+=over
+
+=item *
+
+It's quite common to see tag sub calling statements without trailing semi-colons right after C<}> in code that uses this module. For example,
+
+    template foo => {
+        p {
+            a { attr { src => '1.png' } }
+            a { attr { src => '2.png' } }
+            a { attr { src => '3.png' } }
+        }
+    };
+
+is equivalent to
+
+    template foo => {
+        p {
+            a { attr { src => '1.png' } };
+            a { attr { src => '2.png' } };
+            a { attr { src => '3.png' } };
+        };
+    };
+
+But C<xml_decl> is a notable exception. Please always put a trailing semicolon after C<xml_decl { ... }>, or the outputs will be messed up.
+
+=item *
+
+Another place that requires trailing semicolon is the statements before a Perl looping and branching statements, for example:
+
+    p { "My links:" };
+    for (@links) {
+        with( src => $_ ), a {}
+    }
+
+the C<;> after C< p { ... } > is required here, or Perl will croak for syntax errors.
+
+=item *
+
+Literal strings that are not in the last statement in a code block won't be captured. So the following template
+
+    p { 'hello'; em { 'world' } }
+
+produces
+
+  <p>
+   <em>world</em>
+  </p>
+
+instead of the desired output
+
+  <p>
+   hello
+   <em>world</em>
+  </p>
+
+You can use C<outs> here to solve this problem:
+
+    p { outs 'hello'; em { 'world' } }
+
+=back
+
+=cut
 
 sub init {
     my $class = shift;

Modified: Template-Declare/lib/Template/Declare/TagSet/HTML.pm
==============================================================================
--- Template-Declare/lib/Template/Declare/TagSet/HTML.pm	(original)
+++ Template-Declare/lib/Template/Declare/TagSet/HTML.pm	Mon Aug 13 22:44:55 2007
@@ -28,8 +28,8 @@
 
 sub can_combine_empty_tags {
     my ($self, $tag) = @_;
-    return $tag
-        =~ m{^ (?: base | meta | link | hr | br | param | img | area | input | col ) $}x ? 1 : 0;
+    $tag
+        =~ m{^ (?: base | meta | link | hr | br | param | img | area | input | col ) $}x;
 }
 
 1;

Modified: Template-Declare/lib/Template/Declare/Tags.pm
==============================================================================
--- Template-Declare/lib/Template/Declare/Tags.pm	(original)
+++ Template-Declare/lib/Template/Declare/Tags.pm	Mon Aug 13 22:44:55 2007
@@ -303,6 +303,11 @@
     return @_;
 }
 
+sub append_attr {
+    die "Subroutine attr failed: $_[0] => '$_[1]'\n\t".
+        "(Perhaps you're using an unknown tag in the outer container?)";
+}
+
 =head2 xml_decl HASH
 
 Emits XML declarators.