[Jifty-commit] r7481 - in Template-Declare/trunk/lib/Template: .
Jifty commits
jifty-commit at lists.jifty.org
Mon Sep 7 00:11:45 EDT 2009
Author: theory
Date: Mon Sep 7 00:11:44 2009
New Revision: 7481
Modified:
Template-Declare/trunk/lib/Template/Declare.pm
Template-Declare/trunk/lib/Template/Declare/Tags.pm
Log:
A few more doc tweaks.
* Remove TAP-style comment prefixes in some example output in the docs in
Template::Declare::Tags.
* Wrap a few things to 78 chars or less.
* Eliminated some superfluous words from the docs.
* Changed example output indentation to 1 space, to minimize the indentation
when displayed as HTML on search.cpan.org.
* Changed some instances of "perl" to "Perl".
* Removed the "FUNCTIONS" header; I realized that they weren't functions, but
class methods where the examples are using indirect object notation. Still
thinking about whether we really want to encourage that.
* Added a couple of missing `sub` keywords to examples.
* A few other minor things.
Modified: Template-Declare/trunk/lib/Template/Declare.pm
==============================================================================
--- Template-Declare/trunk/lib/Template/Declare.pm (original)
+++ Template-Declare/trunk/lib/Template/Declare.pm Mon Sep 7 00:11:44 2009
@@ -47,9 +47,10 @@
=head1 SYNOPSIS
-C<Template::Declare> is a pure-perl declarative HTML/XUL/RDF/XML templating system.
+C<Template::Declare> is a pure-Perl Peclarative HTML/XUL/RDF/XML templating
+system.
-Yes. Another one. There are many others like it, but this one is ours.
+Yes. Another one. There are many others like it, but this one is ours.
A few key features and buzzwords:
@@ -57,7 +58,7 @@
=item *
-All templates are 100% pure perl code
+All templates are 100% pure Perl code
=item *
@@ -269,6 +270,7 @@
}
And the output:
+
<h1>Welcome to
<em>my</em> site. It's
<em>great</em>!</h1>
@@ -515,8 +517,6 @@
}
-=head1 FUNCTIONS
-
=head2 alias TEMPLATE_ROOT under PATH
alias Some::Clever::Mixin under '/mixin';
@@ -682,7 +682,6 @@
sub _template_name_to_sub {
return _subname( "_jifty_template_", shift );
-
}
sub _template_name_to_private_sub {
@@ -738,7 +737,7 @@
It's quite common to see tag sub calling statements without trailing
semi-colons right after C<}>. For instance,
- template foo => {
+ template foo => sub {
p {
a { attr { src => '1.png' } }
a { attr { src => '2.png' } }
@@ -748,7 +747,7 @@
is equivalent to
- template foo => {
+ template foo => sub {
p {
a { attr { src => '1.png' } };
a { attr { src => '2.png' } };
@@ -808,8 +807,8 @@
p { outs 'hello'; em { 'world' } }
-Note you can always get rid of the C<outs> crap if the string literal is the
-only element of the containing block:
+Note you can always get rid of C<outs> if the string literal is the only
+element of the containing block:
p { 'hello, world!' }
@@ -828,8 +827,8 @@
<p></p>
-This's because C<0> is the last expression, so it's returned as the value of the
-whole block, which is used as the content of <p> tag.
+This's because C<if ( 0 )> is the last expression, so it's returned as the
+value of the whole block, which is used as the content of <p> tag.
To get rid of this, just put an empty string at the end so it returns empty
string as the content instead of 0:
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 Mon Sep 7 00:11:44 2009
@@ -106,15 +106,18 @@
img { src is 'dog.gif' }
};
- # Produces:
- # <link />
- # <table>
- # <tr>
- # <td>Hello, world!</td>
- # </tr>
- # </table>
- # <img src="cat.gif" />
- # <img src="dog.gif" />
+Produces:
+
+ <link />
+ <table>
+ <tr>
+ <td>Hello, world!</td>
+ </tr>
+ </table>
+ <img src="cat.gif" />
+ <img src="dog.gif" />
+
+Using XUL templates with a namespace:
package MyApp::Templates;
@@ -130,26 +133,28 @@
}
};
- # Produces:
- # <groupbox>
- # <caption label="Colors" />
- # <html:div>
- # <html:p>howdy!</html:p>
- # </html:div>
- # <html:br></html:br>
- # </groupbox>
+Produces:
+
+ <groupbox>
+ <caption label="Colors" />
+ <html:div>
+ <html:p>howdy!</html:p>
+ </html:div>
+ <html:br></html:br>
+ </groupbox>
=head1 DESCRIPTION
C<Template::Declare::Tags> is used to generate and install
-subroutines for tags into the user's namespace.
+subroutines for tags into the calling namespace.
-You can specify the tag sets used by providing a list of
-module list in the C<use> statement:
+You can specify the tag sets to install by providing a list of
+modules in the C<use> statement:
use Template::Declare::Tags qw/ HTML XUL /;
-By default, it uses the tag set provided by L<Template::Declare::TagSet::HTML>. So
+By default, Template::Declare::Tags uses the tag set provided by
+L<Template::Declare::TagSet::HTML>. So
use Template::Declare::Tags;
@@ -158,9 +163,10 @@
use Template::Declare::Tags 'HTML';
Currently L<Template::Declare> bundles the following tag sets:
-L<Template::Declare::TagSet::HTML>, L<Template::Declare::TagSet::XUL>, L<Template::Declare::TagSet::RDF>, and L<Template::Declare::TagSet::RDF::EM>.
+L<Template::Declare::TagSet::HTML>, L<Template::Declare::TagSet::XUL>,
+L<Template::Declare::TagSet::RDF>, and L<Template::Declare::TagSet::RDF::EM>.
-You can certainly specify your own tag set classes, as long
+You can specify your own tag set classes, as long
as they subclass L<Template::Declare::TagSet> and implement
the corresponding methods (e.g. C<get_tag_list>).
@@ -178,13 +184,12 @@
and C<MyTag::Foo> will be loaded instead.
XML namespaces are emulated by Perl packages. For
-example, you can embed HTML tags within XUL using the C<html> namespace:
+example, to embed HTML tags within XUL using the C<html> namespace:
package MyApp::Templates;
use base 'Template::Declare';
- use Template::Declare::Tags
- 'XUL', HTML => { namespace => 'html' };
+ use Template::Declare::Tags 'XUL', HTML => { namespace => 'html' };
template main => sub {
groupbox {
@@ -194,27 +199,33 @@
}
};
-This will give you
+This will output:
- <groupbox>
- <caption label="Colors" />
- <html:div>
- <html:p>howdy!</html:p>
- </html:div>
- <html:br></html:br>
- </groupbox>
-
-Behind the scene, C<Template::Declare::Tags> will generate a Perl package named C<html> and install HTML tag subroutines into that package. On the other hand, XUL tag subroutines are installed into the current package, namely, C<MyApp::Templates> in the previous example.
-
-There are cases when you want to specify a different Perl package for a perticular XML namespace name. For instance, the C<html> Perl package has already been used for other purposes in your application and you don't want to install subs there and mess things up, then the C<package> option can come to rescue:
+ <groupbox>
+ <caption label="Colors" />
+ <html:div>
+ <html:p>howdy!</html:p>
+ </html:div>
+ <html:br></html:br>
+ </groupbox>
+
+Behind the scenes, C<Template::Declare::Tags> generates a Perl package named
+C<html> and installs the HTML tag subroutines into that package. On the other
+hand, XUL tag subroutines are installed into the current package, namely,
+C<MyApp::Templates> in the previous example.
+
+There may be cases when you want to specify a different Perl package for a
+perticular XML namespace. For instance, if the C<html> Perl package has
+already been used for other purposes in your application and you don't want to
+install subs there and mess things up, use the C<package> option to install
+them elsewhere:
package MyApp::Templates;
use base 'Template::Declare';
- use Template::Declare::Tags
- 'XUL', HTML => {
- namespace => 'htm',
- package => 'MyHtml'
- };
+ use Template::Declare::Tags 'XUL', HTML => {
+ namespace => 'htm',
+ package => 'MyHtml'
+ };
template main => sub {
groupbox {
@@ -224,15 +235,15 @@
}
};
-This code snippet will still generate something like the following:
+This code snippet will then generate something like the following:
- <groupbox>
- <caption label="Colors" />
- <htm:div>
- <htm:p>howdy!</htm:p>
- </htm:div>
- <htm:br></htm:br>
- </groupbox>
+ <groupbox>
+ <caption label="Colors" />
+ <htm:div>
+ <htm:p>howdy!</htm:p>
+ </htm:div>
+ <htm:br></htm:br>
+ </groupbox>
=head1 METHODS AND SUBROUTINES
@@ -244,7 +255,7 @@
with C<show()>.
(Did you know that you can have characters like ":" and "/" in your Perl
-subroutine names? The easy way to get at them is with "can").
+subroutine names? The easy way to get at them is with C<can>).
=cut
More information about the Jifty-commit
mailing list