Template::Declare - Perlish declarative templates
Template::Declare is a pure-perl declarative HTML/XUL/RDF/XML templating system.
Template::Declare
Yes. Another one. There are many others like it, but this one is ours.
A few key features and buzzwords:
All templates are 100% pure perl code
Simple declarative syntax
No angle brackets
"Native" XML namespace and declarator support
Mixins
Inheritance
Public and private templates
############################## # Basic HTML usage: ############################### package MyApp::Templates; use Template::Declare::Tags; # defaults to 'HTML' use base 'Template::Declare'; template simple => sub { html { head {} body { p {'Hello, world wide web!'} } } }; package main; use Template::Declare; Template::Declare->init( roots => ['MyApp::Templates']); print Template::Declare->show( 'simple'); # Output: # # # <html> # <head></head> # <body> # <p>Hello, world wide web! # </p> # </body> # </html> ############################### # Let's do XUL! ############################### package MyApp::Templates; use base 'Template::Declare'; use Template::Declare::Tags 'XUL'; template main => sub { xml_decl { 'xml', version => '1.0' }; xml_decl { 'xml-stylesheet', href => "chrome://global/skin/", type => "text/css" }; groupbox { caption { attr { label => 'Colors' } } radiogroup { for my $id ( qw< orange violet yellow > ) { radio { attr { id => $id, label => ucfirst($id), $id eq 'violet' ? (selected => 'true') : () } } } # for } } }; package main; Template::Declare->init( roots => ['MyApp::Templates']); print Template::Declare->show('main') # Output: # # <?xml version="1.0"?> # <?xml-stylesheet href="chrome://global/skin/" type="text/css"?> # # <groupbox> # <caption label="Colors" /> # <radiogroup> # <radio id="orange" label="Orange" /> # <radio id="violet" label="Violet" selected="true" /> # <radio id="yellow" label="Yellow" /> # </radiogroup> # </groupbox>
In this example, we'll show off how to set attributes on HTML tags, how to call other templates and how to declare a private template that can't be called directly. We'll also show passing arguments to templates.
package MyApp::Templates; use Template::Declare::Tags; use base 'Template::Declare'; private template 'header' => sub { head { title { 'This is a webpage'}; meta { attr { generator => "This is not your father's frontpage"}} } }; private template 'footer' => sub { my $self = shift; my $time = shift || gmtime; div { attr { id => "footer"}; "Page last generated at $time." } }; template simple => sub { my $self = shift; my $user = shift || 'world wide web'; html { show('header'); body { img { src is 'hello.jpg' } p { attr { class => 'greeting'}; "Hello, $user!"}; }; show('footer'); } }; package main; use Template::Declare; Template::Declare->init( roots => ['MyApp::Templates']); print Template::Declare->show( 'simple', 'TD user'); # Output: # # <html> # <head> # <title>This is a webpage # </title> # <meta generator="This is not your father's frontpage" /> # </head> # <body> # <img src="hello.jpg" /> # <p class="greeting">Hello, TD user! # </p> # </body> # <div id="footer">Page last generated at Mon Jul 2 17:09:34 2007.</div> # </html>
For more options, especially the "native" XML namespace support, 'is' syntax for attributes, and more samples, see Template::Declare::Tags.
Sometimes you just want simple syntax for inline elements. The following shows how to use a postprocessor to emphasize text _like this_.
package MyApp::Templates; use Template::Declare::Tags; use base 'Template::Declare'; template before => sub { h1 { outs "Welcome to "; em { "my"}; outs " site. It's "; em { "great"}; outs "!"; }; }; template after => sub { h1 { "Welcome to _my_ site. It's _great_!"}; h2 { outs_raw "This is _not_ emphasized."}; }; package main; use Template::Declare; 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; return $text; } # Output: # # <h1>Welcome to # <em>my</em> site. It's # <em>great</em>!</h1> # <h1>Welcome to <em>my</em> site. It's <em>great</em>!</h1> # <h2>This is _not_ emphasized.</h2>
Templates are really just methods. You can subclass your template packages to override some of those methods. See also Jifty::View::Declare::CRUD.
package MyApp::Templates::GenericItem; use Template::Declare::Tags; use base 'Template::Declare'; template 'list' => sub { div { show('item', $_) for @_; } }; template 'item' => sub { span { shift } }; package MyApp::Templates::BlogPost; use Template::Declare::Tags; use base 'MyApp::Templates::GenericItem'; template 'item' => sub { my $post = shift; h1 { $post->title } div { $post->body } };
This class method initializes the Template::Declare system.
An array reference of packages to begin looking for templates.
A coderef called to postprocess the HTML or XML output of your templates. This is to alleviate using Tags for simple text markup.
A coderef called instead of rendering each template. The coderef will receive three arguments: a coderef to invoke to render the template, the template's path, an arrayref of the arguments to the template, and the coderef of the template itself. You can use this for instrumentation. For example:
Template::Declare->init(around_template => sub { my ($orig, $path, $args, $code) = @_; my $start = time; $orig->(); warn "Rendering $path took " . (time - $start) . " seconds."; });
Call show with a template_name and Template::Declare will render that template. Content generated by show can be accessed with the output method if the output method you've chosen returns content instead of outputting it directly.
show
template_name
output
(If called in scalar context, this method will also just return the content when available).
alias Some::Clever::Mixin under '/mixin';
import_templates Wifty::UI::something under '/something';
Returns the path for the template name to be used for show, adjusted with paths used in import_templates.
Takes a package, template name and a boolean. The boolean determines whether to show private templates.
Returns a reference to the template's code if found. Otherwise, returns undef.
This method is an alias for "resolve_template"
Turns a template path (TEMPLATE_PATH) into a CODEREF. If the boolean INCLUDE_PRIVATE_TEMPLATES is true, resolves private template in addition to public ones.
TEMPLATE_PATH
CODEREF
INCLUDE_PRIVATE_TEMPLATES
First it looks through all the valid Template::Declare roots. For each root, it looks to see if the root has a template called $template_name directly (or via an import statement). Then it looks to see if there are any "alias"ed paths for the root with prefixes that match the template we're looking for.
import
This method registers a template called TEMPLATE_NAME in package PACKAGE. As you might guess, CODEREF defines the template's implementation.
TEMPLATE_NAME
PACKAGE
This method registers a private template called TEMPLATE_NAME in package PACKAGE. As you might guess, CODEREF defines the template's implementation.
Private templates can't be called directly from user code but only from other templates.
We're reusing the perl interpreter for our templating langauge, but Perl was not designed specifically for our purpose here. Here are some known pitfalls while you're scripting your templates with this module.
It's quite common to see tag sub calling statements without trailing semi-colons right after }. For instance,
}
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 xml_decl is a notable exception. Please always put a trailing semicolon after xml_decl { ... }, or you'll mess up the outputs.
xml_decl
xml_decl { ... }
Another place that requires trailing semicolon is the statements before a Perl looping statement, an if statement, or a show call. For example:
p { "My links:" }; for (@links) { with( src => $_ ), a {} }
The ; after p { ... } is required here, or Perl will complain about syntax errors.
;
p { ... }
Another example is
h1 { 'heading' }; # this trailing semicolon is mandatory show 'tag_tag'
The is syntax for declaring tag attributes also requires a trailing semicolon, unless it is the only statement in a block. For example,
is
p { class is 'item'; id is 'item1'; outs "This is an item" } img { src is 'cat.gif' }
Literal strings that have tag siblings 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 outs here to solve this problem:
outs
p { outs 'hello'; em { 'world' } }
Note you can always get rid of the outs crap if the string literal is the only element of the containing block:
p { 'hello, world!' }
Look out! If the if block is the last block/statement and the condition part is evaluated to be 0:
p { if ( 0 ) { } }
<p>0</p>
instead of the more intutive output:
<p></p>
This's because 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:
p { if ( 0 ) { } '' }
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 PITFALL section above :)
Some specific bugs and design flaws that we'd love to see fixed.
If you run into bugs or misfeatures, please report them to bug-template-declare@rt.cpan.org.
bug-template-declare@rt.cpan.org
Template::Declare::Tags, Template::Declare::TagSet, Template::Declare::TagSet::HTML, Template::Declare::TagSet::XUL, Jifty.
Jesse Vincent <jesse@bestpractical.com>
Template::Declare is Copyright 2006-2008 Best Practical Solutions, LLC.
Template::Declare is distributed under the same terms as Perl itself.
To install Template::Declare, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Template::Declare
CPAN shell
perl -MCPAN -e shell install Template::Declare
For more information on module installation, please visit the detailed CPAN module installation guide.