File Coverage

blib/lib/Template/Declare.pm

Criterion	Covered	Total	%
statement	153	168	91.0
branch	36	46	78.2
condition	14	21	66.6
subroutine	37	42	88.1
pod	18	18	100.0
total	258	295	87.4

line	stmt	bran	cond	sub	pod	time	code
1	48			48		560520	use 5.006;
	48					170
	48					5097
2	48			48		764	use warnings;
	48					77
	48					1937
3	48			48		248	use strict;
	48					79
	48					2092
4
5							package Template::Declare;
6	48			48		34645	use Template::Declare::Buffer;
	48					169
	48					1444
7	48			48		56116	use Class::ISA;
	48					197458
	48					1931
8	48			48		75283	use String::BufferStack;
	48					125882
	48					2383
9
10							our $VERSION = '0.46';
11
12	48			48		924	use base 'Class::Data::Inheritable';
	48					476
	48					59031
13							__PACKAGE__->mk_classdata('dispatch_to');
14							__PACKAGE__->mk_classdata('postprocessor');
15							__PACKAGE__->mk_classdata('strict');
16							__PACKAGE__->mk_classdata('templates');
17							__PACKAGE__->mk_classdata('private_templates');
18							__PACKAGE__->mk_classdata('buffer');
19							__PACKAGE__->mk_classdata('imported_into');
20							__PACKAGE__->mk_classdata('around_template');
21
22							__PACKAGE__->dispatch_to( [] );
23							__PACKAGE__->postprocessor( sub { return wantarray ? @_ : $_[0] } );
24							__PACKAGE__->templates( {} );
25							__PACKAGE__->private_templates( {} );
26							__PACKAGE__->buffer( String::BufferStack->new );
27							__PACKAGE__->around_template( undef );
28
29							*String::BufferStack::data = sub {
30	72			72		3461	my $ref = shift;
31	72	50				240	if (@_) {
32	0					0	warn "Template::Declare->buffer->data called with argument; this usage is deprecated";
33	0					0	${$ref->buffer_ref} = join("", @_);
	0					0
34							}
35	72					236	return $ref->buffer;
36							};
37
38							our $TEMPLATE_VARS;
39
40							=head1 NAME
41
42							Template::Declare - Perlish declarative templates
43
44							=head1 SYNOPSIS
45
46							Here's an example of basic HTML usage:
47
48							package MyApp::Templates;
49							use Template::Declare::Tags; # defaults to 'HTML'
50							use base 'Template::Declare';
51
52							template simple => sub {
53							html {
54							head {}
55							body {
56							p { 'Hello, world wide web!' }
57							}
58							}
59							};
60
61							package main;
62							use Template::Declare;
63							Template::Declare->init( dispatch_to => ['MyApp::Templates'] );
64							print Template::Declare->show( 'simple' );
65
66							And here's the output:
67
68
69
70
71							Hello, world wide web!
72
73
74
75
76							=head1 DESCRIPTION
77
78							C is a pure-Perl declarative HTML/XUL/RDF/XML templating
79							system.
80
81							Yes. Another one. There are many others like it, but this one is ours.
82
83							A few key features and buzzwords:
84
85							=over
86
87							=item *
88
89							All templates are 100% pure Perl code
90
91							=item *
92
93							Simple declarative syntax
94
95							=item *
96
97							No angle brackets
98
99							=item *
100
101							"Native" XML namespace and declaration support
102
103							=item *
104
105							Mixins
106
107							=item *
108
109							Inheritance
110
111							=item *
112
113							Delegation
114
115							=item *
116
117							Public and private templates
118
119							=back
120
121							=head1 GLOSSARY
122
123							=over
124
125							=item template class
126
127							A subclass of Template::Declare in which one or more templates are defined
128							using the C
129
130							=item template
131
132							Created with the C
133							C to generate output.
134
135							=item attribute
136
137							An XML element attribute. For example, in C<< >>, C
138							is an attribute of the C element.
139
140							=item tag
141
142							A subroutine that generates XML element-style output. Tag subroutines execute
143							blocks that generate the output, and can call other tags to generate a
144							properly hierarchical structure.
145
146							=item tag set
147
148							A collection of related tags defined in a subclass of
149							L for a particular purpose, and which can be
150							imported into a template class. For example,
151							L defines tags for emitting HTML elements.
152
153							=item wrapper
154
155							A subroutine that wraps the output from a template. Useful for wrapping
156							template output in common headers and footers, for example.
157
158							=item dispatch class
159
160							A template class that has been passed to L\|/init> via the
161							C parameter. When L is called, only
162							templates defined in or mixed into the dispatch classes will be executed.
163
164							=item path
165
166							The name specified for a template when it is created by the C
167							keyword, or when a template is mixed into a template class.
168
169							=item mixin
170
171							A template mixed into a template class via L. Mixed-in templates may be
172							mixed in under prefix paths to distinguish them from the templates defined in
173							the dispatch classes.
174
175							=item alias
176
177							A template aliased into a template class via L. Aliased templates may
178							be added under prefix paths to distinguish them from the templates defined in
179							the dispatch classes.
180
181							=item package variable
182
183							Variables defined when mixing templates into a template class. These variables
184							are available only to the mixed-in templates; they are not even accessible
185							from the template class in which the templates were defined.
186
187							=item helper
188
189							A subroutine used in templates to assist in the generation of output, or in
190							template classes to assist in the mixing-in of templates. Output helpers
191							include C for rending text output and C for rendering XML
192							declarations. Mixin helpers include C for specifying a template class to
193							mix into, and C for specifying a path prefix under which to mix
194							templates.
195
196							=back
197
198							=head1 USAGE
199
200							Like other Perl templating systems, there are two parts to Template::Declare:
201							the templates and the code that loads and executes the templates. Unlike other
202							template systems, the templates are written in Perl classes. A simple HTML
203							example is in the L.
204
205							=head2 A slightly more advanced example
206
207							In this example, we'll show off how to set attributes on HTML tags, how to
208							call other templates, and how to declare a I template that can't be
209							called directly. We'll also show passing arguments to templates. First, the
210							template class:
211
212							package MyApp::Templates;
213							use base 'Template::Declare';
214							use Template::Declare::Tags;
215
216							private template 'util/header' => sub {
217							head {
218							title { 'This is a webpage' };
219							meta {
220							attr { generator => "This is not your father's frontpage" }
221							}
222							}
223							};
224
225							private template 'util/footer' => sub {
226							my $self = shift;
227							my $time = shift \|\| gmtime;
228
229							div {
230							attr { id => "footer"};
231							"Page last generated at $time."
232							}
233							};
234
235							template simple => sub {
236							my $self = shift;
237							my $user = shift \|\| 'world wide web';
238
239							html {
240							show('util/header');
241							body {
242							img { src is 'hello.jpg' }
243							p {
244							attr { class => 'greeting'};
245							"Hello, $user!"
246							};
247							};
248							show('util/footer', 'noon');
249							}
250							};
251
252							A few notes on this example:
253
254							=over
255
256							=item *
257
258							Since no parameter was passed to C, the HTML tags
259							are imported by default.
260
261							=item *
262
263							The C keyword indicates that a template is private. That means that
264							it can only be executed by other templates within the template class in which
265							it's declared. By default, C<< Template::Declare->show >> will not dispatch to
266							it.
267
268							=item *
269
270							The two private templates have longer paths than we've seen before:
271							C and C. They must of course be called by their full
272							path names. You can put any characters you like into template names, but the
273							use of Unix filesystem-style paths is the most common (following on the
274							example of L).
275
276							=item *
277
278							The first argument to a template is a class name. This can be useful for
279							calling methods defined in the class.
280
281							=item *
282
283							The C sub executes another template. In this example, the C
284							template calls C and C in order to
285							execute those private templates in the appropriate places.
286
287							=item *
288
289							Additional arguments to C are passed on to the template being executed.
290							Here, C is passing "noon" to the C
291							template, with the result that the "last generated at" string will display
292							"noon" instead of the default C.
293
294							=item *
295
296							In the same way, note that the C template expects an additional
297							argument, a user name.
298
299							=item *
300
301							In addition to using C to declare attributes for an element, you can
302							use C, as in
303
304							img { src is 'hello.jpg' }
305
306							=back
307
308							Now for executing the template:
309
310							package main;
311							use Template::Declare;
312							Template::Declare->init( dispatch_to => ['MyApp::Templates'] );
313							print Template::Declare->show( '/simple', 'TD user');
314
315							We've told Template::Declare to dispatch to templates defined in our template
316							class. And note how an additional argument is passed to C; that
317							argument, "TD user", will be passed to the C template, where it will
318							be used in the C<$user> variable.
319
320							The output looks like this:
321
322
323
324							This is a webpage
325
326
327
328
329							Hello, TD user!
330
331							Page last generated at Thu Sep 3 20:56:14 2009.
332
333
334							Note that the single quote in C was quoted for you. We sanitize
335							your output for you to help prevent cross-site scripting attacks.
336
337							=head2 XUL
338
339							Template::Declare isn't limited to just HTML. Let's do XUL!
340
341							package MyApp::Templates;
342							use base 'Template::Declare';
343							use Template::Declare::Tags 'XUL';
344
345							template main => sub {
346							xml_decl { 'xml', version => '1.0' };
347							xml_decl {
348							'xml-stylesheet',
349							href => "chrome://global/skin/",
350							type => "text/css"
351							};
352							groupbox {
353							caption { attr { label => 'Colors' } }
354							radiogroup {
355							for my $id ( qw< orange violet yellow > ) {
356							radio {
357							attr {
358							id => $id,
359							label => ucfirst($id),
360							$id eq 'violet' ? (selected => 'true') : ()
361							}
362							}
363							} # for
364							}
365							}
366							};
367
368							The first thing to do in a template class is to subclass Template::Declare
369							itself. This is required so that Template::Declare always knows that it's
370							dealing with templates. The second thing is to C
371							to import the set of tag subroutines you need to generate the output you want.
372							In this case, we've imported tags to support the creation of XUL. Other tag
373							sets include HTML (the default), and RDF.
374
375							Templates are created using the C
376
377							template main => sub { ... };
378
379							The first argument is the name of the template, also known as its I. In
380							this case, the template's path is C (or C , both are allowed (to
381							keep both PHP and L fans happy). The second argument is an
382							anonymous subroutine that uses the tag subs (and any other necessary code) to
383							generate the output for the template.
384
385							The tag subs imported into your class take blocks as arguments, while a
386							number of helper subs take other arguments. For example, the C
387							helper takes as its first argument the name of the XML declaration to be
388							output, and then a hash of the attributes of that declaration:
389
390							xml_decl { 'xml', version => '1.0' };
391
392							Tag subs are used by simply passing a block to them that generates the output.
393							Said block may of course execute other tag subs in order to represent the
394							hierarchy required in your output. Here, the C tag calls the
395							C tag for each of three different colors:
396
397							radiogroup {
398							for my $id ( qw< orange violet yellow > ) {
399							radio {
400							attr {
401							id => $id,
402							label => ucfirst($id),
403							$id eq 'violet' ? (selected => 'true') : ()
404							}
405							}
406							} # for
407							}
408
409							Note the C sub. This helper function is used to add attributes to the
410							element created by the tag in which they appear. In the previous example, the
411							C, C, and C attributes are added to each C
412							output.
413
414							Once you've written your templates, you'll want to execute them. You do so by
415							telling Template::Declare what template classes to dispatch to and then asking
416							it to show you the output from a template:
417
418							package main;
419							Template::Declare->init( dispatch_to => ['MyApp::Templates'] );
420							print Template::Declare->show( 'main' );
421
422							The path passed to C can be either C or , as you prefer. In
423							either event, the output would look like this:
424
425
426
427
428
429
430
431
432
433
434
435
436
437							=head2 Postprocessing
438
439							Sometimes you just want simple syntax for inline elements. The following shows
440							how to use a postprocessor to emphasize text _like this_.
441
442							package MyApp::Templates;
443							use Template::Declare::Tags;
444							use base 'Template::Declare';
445
446							template before => sub {
447							h1 {
448							outs "Welcome to ";
449							em { "my" };
450							outs " site. It's ";
451							em { "great" };
452							outs "!";
453							};
454							};
455
456							template after => sub {
457							h1 { "Welcome to _my_ site. It's _great_!" };
458							h2 { outs_raw "This is _not_ emphasized." };
459							img { src is '/foo/_bar_baz.png' };
460							};
461
462							Here we've defined two templates in our template class, with the paths
463							C and C. The one new thing to note is the use of the C
464							and C subs. C XML-encodes its argument and outputs it. You can
465							also just specify a string to be output within a tag call, but if you need to
466							mix tags and plain text within a tag call, as in the C template here,
467							you'll need to use C to get things to output as you would expect.
468							C is the same, except that it does no XML encoding.
469
470							Now let's have a look at how we use these templates with a post-processor:
471
472							package main;
473							use Template::Declare;
474							Template::Declare->init(
475							dispatch_to => ['MyApp::Templates'],
476							postprocessor => \&emphasize,
477							strict => 1,
478							);
479
480							print Template::Declare->show( 'before' );
481							print Template::Declare->show( 'after' );
482
483							sub emphasize {
484							my $text = shift;
485							$text =~ s{_(.+?)_}{$1}g;
486							return $text;
487							}
488
489							As usual, we've told Template::Declare to dispatch to our template class. A
490							new parameter to C is C, which is a code reference that
491							should expect the template output as an argument. It can then transform that
492							text however it sees fit before returning it for final output. In this
493							example, the C subroutine looks for text that's emphasized using
494							_underscores_ and turns them into C<< emphasis >> HTML elements.
495
496							We then execute both the C and the C templates with the output
497							ending up as:
498
499							Welcome to
500							my site. It's
501							great!
502							Welcome to my site. It's great!
503							This is _not_ emphasized.
504
505
506							The thing to note here is that text passed to C is not passed
507							through the postprocessor, and neither are attribute values (like the C's
508							C).
509
510							=head2 Inheritance
511
512							Templates are really just methods. You can subclass your template packages to
513							override some of those methods:
514
515							package MyApp::Templates::GenericItem;
516							use Template::Declare::Tags;
517							use base 'Template::Declare';
518
519							template 'list' => sub {
520							my ($self, @items) = @_;
521							div {
522							show('item', $_) for @items;
523							}
524							};
525							template 'item' => sub {
526							my ($self, $item) = @_;
527							span { $item }
528							};
529
530							package MyApp::Templates::BlogPost;
531							use Template::Declare::Tags;
532							use base 'MyApp::Templates::GenericItem';
533
534							template 'item' => sub {
535							my ($self, $post) = @_;
536							h1 { $post->title }
537							div { $post->body }
538							};
539
540							Here we have two template classes; the second, C,
541							inherits from the first, C. Note also that
542							C overrides the C template. So execute these
543							templates:
544
545							package main;
546							use Template::Declare;
547
548							Template::Declare->init( dispatch_to => ['MyApp::Templates::GenericItem'] );
549							print Template::Declare->show( 'list', 'foo', 'bar', 'baz' );
550
551							Template::Declare->init( dispatch_to => ['MyApp::Templates::BlogPost'] );
552							my $post = My::Post->new(title => 'Hello', body => 'first post');
553							print Template::Declare->show( 'item', $post );
554
555							First we execute the C template in the base class, passing in some
556							items, and then we re-C Template::Declare and execute I C
557							template with an appropriate argument. Here's the output:
558
559
560							foo
561							bar
562							baz
563
564
565							Hello
566							first post
567
568							So the override of the C template in the subclass works as expected. For
569							another example, see L.
570
571							=head2 Wrappers
572
573							There are two levels of wrappers in Template::Declare: template wrappers and
574							smart tag wrappers.
575
576							=head3 Template Wrappers
577
578							C declares a wrapper subroutine that can be called like a tag
579							sub, but can optionally take arguments to be passed to the wrapper sub. For
580							example, if you wanted to wrap all of the output of a template in the usual
581							HTML headers and footers, you can do something like this:
582
583							package MyApp::Templates;
584							use Template::Declare::Tags;
585							use base 'Template::Declare';
586
587							BEGIN {
588							create_wrapper wrap => sub {
589							my $code = shift;
590							my %params = @_;
591							html {
592							head { title { outs "Hello, $params{user}!"} };
593							body {
594							$code->();
595							div { outs 'This is the end, my friend' };
596							};
597							}
598							};
599							}
600
601							template inner => sub {
602							wrap {
603							h1 { outs "Hello, Jesse, s'up?" };
604							} user => 'Jesse';
605							};
606
607							Note how the C wrapper function is available for calling after it has
608							been declared in a C block. Also note how you can pass arguments to the
609							function after the closing brace (you don't need a comma there!).
610
611							The output from the "inner" template will look something like this:
612
613
614
615							Hello, Jesse!
616
617
618							Hello, Jesse, s'up?
619							This is the end, my friend
620
621
622
623							=head3 Tag Wrappers
624
625							Tag wrappers are similar to template wrappers, but mainly function as syntax
626							sugar for creating subroutines that behave just like tags but are allowed to
627							contain arbitrary Perl code and to dispatch to other tags. To create one,
628							simply create a named subroutine with the prototype C<(&)> so that its
629							interface is the same as tags. Within it, use
630							L\|Template::Declare::Tags/"smart_tag_wrapper"> to do the
631							actual execution, like so:
632
633							package My::Template;
634							use Template::Declare::Tags;
635							use base 'Template::Declare';
636
637							sub myform (&) {
638							my $code = shift;
639
640							smart_tag_wrapper {
641							my %params = @_; # set using 'with'
642							form {
643							attr { %{ $params{attr} } };
644							$code->();
645							input { attr { type => 'submit', value => $params{value} } };
646							};
647							};
648							}
649
650							template edit_prefs => sub {
651							with(
652							attr => { id => 'edit_prefs', action => 'edit.html' },
653							value => 'Save'
654							), myform {
655							label { 'Time Zone' };
656							input { type is 'text'; name is 'tz' };
657							};
658							};
659
660							Note in the C template that we've used
661							L\|Template::Declare::Tags/"with"> to set up parameters to be passed to
662							the smart wrapper. C is the device that allows you to
663							receive those parameters, and also handles the magic of making sure that the
664							tags you execute within it are properly output. Here we've used C
665							similarly to C , only C does something different with the
666							C arguments and outputs a submit element.
667
668							Executing this template:
669
670							Template::Declare->init( dispatch_to => ['My::Template'] );
671							print Template::Declare->show('edit_prefs');
672
673							Yields this output:
674
675
676							Time Zone
677
678
679
680
681							=head2 Class Search Dispatching
682
683							The classes passed via the C parameter to C specify all
684							of the templates that can be executed by subsequent calls to C.
685							Template::Declare searches through these classes in order to find those
686							templates. Thus it can be useful, when you're creating your template classes
687							and determining which to use for particular class to C, to have
688							templates that override other templates. This is similar to how an operating
689							system will search all the paths in the C<$PATH> environment variable for a
690							program to run, and to L component roots or L's
691							C parameter.
692
693							For example, say you have this template class that defines a template that
694							you'll use for displaying images on your Web site.
695
696							package MyApp::UI::Standard;
697							use Template::Declare::Tags;
698							use base 'Template::Declare';
699
700							template image => sub {
701							my ($self, $src, $title) = @_;
702							img {
703							src is $src;
704							title is $title;
705							};
706							};
707
708							As usual, you can use it like so:
709
710							my @template_classes = 'MyApp::UI::Standard';
711							Template::Declare->init( dispatch_to => \@template_classes );
712							print Template::Declare->show('image', 'foo.png', 'Foo');
713
714							We're explicitly using a reference to C<@template_classes> so that we can
715							manage this list ourselves.
716
717							The output of this will be:
718
719
720
721
722
723
724							But say that in some sections of your site you need to have a more formal
725							treatment of your photos. Maybe you publish photos from a wire service and
726							need to provide an appropriate credit. You might write the template class like
727							so:
728
729							package MyApp::UI::Formal;
730							use Template::Declare::Tags;
731							use base 'Template::Declare';
732
733							template image => sub {
734							my ($self, $src, $title, $credit, $caption) = @_;
735							div {
736							class is 'formal';
737							img {
738							src is $src;
739							title is $title;
740							};
741							p {
742							class is 'credit';
743							outs "Photo by $credit";
744							};
745							p {
746							class is 'caption';
747							outs $caption;
748							};
749							};
750							};
751
752
753							This, too, will work as expected, but the useful bit comes in when you're
754							mixing and matching template classes to pass to C before
755							rendering a page. Maybe you always pass C to
756							C because it has all of your standard formatting templates.
757							But when the code realizes that a particular page needs the more formal
758							treatment, you can prepend the formal class to the list:
759
760							unshift @template_classes, 'MyApp::UI::Formal';
761							print Template::Declare->show(
762							'image',
763							'ap.png',
764							'AP Photo',
765							'Clark Kent',
766							'Big news'
767							);
768							shift @template_classes;
769
770							In this way, the formal C template will be found first, yielding
771							this output:
772
773
774
775							Photo by Clark Kent
776							Big news
777
778
779							At the end, we've shifted the formal template class off the C
780							list in order to restore the template classes to the default configuration,
781							ready for the next request.
782
783							=head2 Template Composition
784
785							There are two methods of template composition: mixins and delegation. Their
786							interfaces are very similar, the only difference being the template invocant.
787
788							=head3 Mixins
789
790							Let's start with a mixin.
791
792							package MyApp::UtilTemplates;
793							use Template::Declare::Tags;
794							use base 'Template::Declare';
795
796							template content => sub {
797							my $self = shift;
798							my @paras = @_;
799							h1 { $self->get_title };
800							div {
801							id is 'content';
802							p { $_ } for @paras;
803							};
804							};
805
806							package MyApp::Templates;
807							use Template::Declare::Tags;
808							use base 'Template::Declare';
809							mix MyApp::UtilTemplates under '/util';
810
811							sub get_title { 'Kashmir' }
812
813							template story => sub {
814							my $self = shift;
815							html {
816							head {
817							title { "My Site: " . $self->get_title };
818							};
819							body {
820							show( 'util/content' => 'first paragraph', 'second paragraph' );
821							};
822							};
823							};
824
825							The first template class, C, defines a utility template,
826							called C, for outputting the contents of page. Note its call to
827							C<< $self->get_title >> even though it doesn't have a C method. This
828							is part of the mixin's "contract": it requires that the class it's mixed into
829							have a C method.
830
831							The second template class, C, mixes C
832							into itself under the path C and defines a C method as
833							required by the mixin. Then, its C template calls the mixed-in template
834							as C, because the C template was mixed into the current
835							template under C. Get it?
836
837							Now we can use the usual template invocation:
838
839							package main;
840							Template::Declare->init( dispatch_to => ['MyApp::Templates'] );
841							print Template::Declare->show('story');
842
843							To appreciate our output:
844
845
846
847							My Site: Kashmir
848
849
850							Kashmir
851
852							fist paragraph
853							second paragraph
854
855
856
857
858							Mixins are a very useful tool for template authors to add reusable
859							functionality to their template classes. But it's important to pay attention to
860							the mixin contracts so that you're sure to implement the required API in your
861							template class (here, the C method).
862
863							=head3 Aliases
864
865							Aliases are very similar to mixins, but implement delegation as a composition
866							pattern, rather than mixins. The upshot is that there is no contract provided
867							by an aliased class: it just works. This is because the invocant is the class
868							from which the aliases are imported, and therefore it will dispatch to methods
869							defined in the aliased class.
870
871							For example, say that you wanted to output a sidebar on pages that need one
872							(perhaps your CMS has sidebar things). We can define a template class that
873							has a template for that:
874
875							package MyApp::UI::Stuff;
876							use Template::Declare::Tags;
877							use base 'Template::Declare';
878
879							sub img_path { '/ui/css' }
880
881							template sidebar => sub {
882							my ($self, $thing) = @_;
883							div {
884							class is 'sidebar';
885							img { src is $self->img_path . '/sidebar.png' };
886							p { $_->content } for $thing->get_things;
887							};
888							};
889
890							Note the use of the C method defined in the template class and
891							used by the C template. Now let's use it:
892
893							package MyApp::Render;
894							use Template::Declare::Tags;
895							use base 'Template::Declare';
896							alias MyApp::UI::Stuff under '/stuff';
897
898							template page => sub {
899							my ($self, $page) = @_;
900							h1 { $page->title };
901							for my $thing ($page->get_things) {
902							if ($thing->is('paragraph')) {
903							p { $thing->content };
904							} elsif ($thing->is('sidebar')) {
905							show( '/stuff/sidebar' => $thing );
906							}
907							}
908							};
909
910							Here our rendering template class has aliased C under
911							C. So the C template calls C to invoke
912							the sidebar template. If we run this:
913
914							Template::Declare->init( dispatch_to => ['MyApp::Render'] );
915							print Template::Declare->show( page => $page );
916
917							We get output as you might expect:
918
919							My page title
920							Page paragraph
921
922
923							Sidebar paragraph
924							Another paragraph
925
926
927							Now, let's say that you have political stuff that you want to use a different
928							image for in the sidebar. If that's the only difference, we can subclass
929							C and just override the C method:
930
931							package MyApp::UI::Stuff::Politics;
932							use Template::Declare::Tags;
933							use base 'MyApp::UI::Stuff';
934
935							sub img_path { '/politics/ui/css' }
936
937							Now let's mix that into a politics template class:
938
939							package MyApp::Render::Politics;
940							use Template::Declare::Tags;
941							use base 'Template::Declare';
942							alias MyApp::UI::Stuff::Politics under '/politics';
943
944							template page => sub {
945							my ($self, $page) = @_;
946							h1 { $page->title };
947							for my $thing ($page->get_things) {
948							if ($thing->is('paragraph')) {
949							p { $thing->content };
950							} elsif ($thing->is('sidebar')) {
951							show( '/politics/sidebar' => $thing );
952							}
953							}
954							};
955
956							The only difference between this template class and C is that
957							it aliases C under C, and then calls
958							C in the C template. Running this template:
959
960							Template::Declare->init( dispatch_to => ['MyApp::Render::Politics'] );
961							print Template::Declare->show( page => $page );
962
963							Yields output using the value of the subclass's C method -- that
964							is, the sidebar image is now F instead of
965							F:
966
967							My page title
968							Page paragraph
969
970
971							Sidebar paragraph
972							Another paragraph
973
974
975							=head3 Other Tricks
976
977							The delegation behavior of C actually makes it a decent choice for
978							template authors to mix and match libraries of template classes as
979							appropriate, without worrying about side effects. You can even alias templates
980							in one template class into another template class if you're not the author of
981							that class by using the C keyword:
982
983							alias My::UI::Widgets into Your::UI::View under '/widgets';
984
985							Now the templates defined in C are available in
986							C under C. The C method supports this syntax
987							as well, though it's not necessarily recommended, given that you would not be
988							able to fulfill any contracts unless you re-opened the class into which you
989							mixed the templates. But in any case, authors of framework view classes might
990							find this functionality useful for automatically aliasing template classes
991							into a single dispatch template class.
992
993							Another trick is to alias or mix your templates with package variables
994							specific to the composition. Do so via the C keyword:
995
996							package My::Templates;
997							mix Some::Mixin under '/mymix', setting { name => 'Larry' };
998
999							The templates mixed from C into C have package
1000							variables set for them that are accessible I from their mixed-in paths.
1001							For example, if you define this template in C:
1002
1003							template howdy => sub {
1004							my $self = shift;
1005							outs "Howdy, " . $self->package_variable('name') \|\| 'Jesse';
1006							};
1007
1008							Then C called on C will output "Howdy,
1009							Larry", while the output from C will output "Howdy, Jesse". In
1010							other words, package variables defined for the mixed-in templates are
1011							available only to the mixins and not to the original. The same functionality
1012							exists for C as well.
1013
1014							=begin comment
1015
1016							=head2 Tag Sets
1017
1018							Wherein we will eventually provide a brief tutorial on creating custom tag sets.
1019
1020							=end comment
1021
1022							=head2 Indentation configuration
1023
1024							By default, Template::Declare renders a readable XML adding end of lines and a
1025							one column indentation. This behavior could break a webpage design or add a
1026							significant amount of chars to your XML output. This could be changed by
1027							overwriting the default values. So,
1028
1029							$Template::Declare::Tags::TAG_INDENTATION = 0;
1030							$Template::Declare::Tags::EOL = "";
1031							say Template::Declare->show('main');
1032
1033							will render
1034
1035							hi
1036
1037
1038							=head1 METHODS
1039
1040							=head2 init
1041
1042							This I initializes the C system.
1043
1044							=over
1045
1046							=item dispatch_to
1047
1048							An array reference of classes to search for templates. Template::Declare will
1049							search this list of classes in order to find a template path.
1050
1051							=item roots
1052
1053							B Just like C, only the classes are searched in
1054							reverse order. Maintained for backward compatibility and for the pleasure of
1055							those who want to continue using Template::Declare the way that Jesse's
1056							"crack-addled brain" intended.
1057
1058							=item postprocessor
1059
1060							A coderef called to postprocess the HTML or XML output of your templates. This
1061							is to alleviate using Tags for simple text markup.
1062
1063							=item around_template
1064
1065							A coderef called B of rendering each template. The coderef will
1066							receive four arguments: a coderef to invoke to render the template, the
1067							template's path, an arrayref of the arguments to the template, and the coderef
1068							of the template itself. You can use this for instrumentation. For example:
1069
1070							Template::Declare->init(around_template => sub {
1071							my ($orig, $path, $args, $code) = @_;
1072							my $start = time;
1073							$orig->();
1074							warn "Rendering $path took " . (time - $start) . " seconds.";
1075							});
1076
1077							=item strict
1078
1079							Die in exceptional situations, such as when a template can't be found, rather
1080							than just warn. False by default for backward compatibility. The default may
1081							be changed in the future, so specifying the value explicitly is recommended.
1082
1083							=back
1084
1085							=cut
1086
1087							sub init {
1088	67			67	1	22999	my $class = shift;
1089	67					289	my %args = (@_);
1090
1091	67	100				280	if ( $args{dispatch_to} ) {
		50
1092	66					351	$class->dispatch_to( $args{dispatch_to} );
1093							} elsif ( $args{roots} ) {
1094	1					5	$class->roots( $args{roots} );
1095							}
1096
1097	67	100				770	$class->strict( $args{strict} ) if exists $args{strict};
1098	67	100				297	$class->postprocessor( $args{postprocessor} ) if $args{postprocessor};
1099	67	100				374	$class->around_template( $args{around_template} ) if $args{around_template};
1100							}
1101
1102							=head2 show TEMPLATE_NAME
1103
1104							Template::Declare->show( 'howdy', name => 'Larry' );
1105							my $output = Template::Declare->show('index');
1106
1107							Call C with a C and C will render that
1108							template. Subsequent arguments will be passed to the template. Content
1109							generated by C can be accessed via the C method if the
1110							output method you've chosen returns content instead of outputting it directly.
1111
1112							If called in scalar context, this method will also just return the content
1113							when available.
1114
1115							=cut
1116
1117							sub show {
1118	101			101	1	91510	my $class = shift;
1119	101					177	my $template = shift;
1120	101					276	local %Template::Declare::Tags::ELEMENT_ID_CACHE = ();
1121	101					439	return Template::Declare::Tags::show_page($template => @_);
1122							}
1123
1124							=head2 Template Composition
1125
1126							Sometimes you want to mix templates from one class into another class, or
1127							delegate template execution to a class of templates. C and C
1128							are your keys to doing so.
1129
1130							=head3 mix
1131
1132							mix Some::Clever::Mixin under '/mixin';
1133							mix Some::Other::Mixin under '/otmix', setting { name => 'Larry' };
1134							mix My::Mixin into My::View, under '/mymix';
1135
1136							Mixes templates from one template class into another class. When the mixed-in
1137							template is called, its invocant will be the class into which it was mixed.
1138							This type of composition is known as a "mixin" in object-oriented parlance.
1139							See L
1140							a comparison to C.
1141
1142							The first parameter is the name of the template class to be mixed in. The
1143							C keyword tells C where to put the templates. For example,
1144							a C template in C will be mixed in as C.
1145
1146							The C keyword specifies package variables available only to the
1147							mixed-in copies of templates. These are available to the templates as
1148							C<< $self->package_variable($varname) >>.
1149
1150							The C keyword tells C into what class to mix the templates. Without
1151							this keyword, C will mix them into the calling class.
1152
1153							For those who prefer a direct OO syntax for mixins, just call C as a
1154							method on the class to be mixed in. To replicate the above three examples
1155							without the use of the sugar:
1156
1157							Some::Clever::Mixin->mix( '/mixin' );
1158							Some::Other::Mixin->mix( '/otmix', { name => 'Larry' } );
1159							My::Mixin->mix( 'My::View', '/mymix' );
1160
1161							=cut
1162
1163							sub mix {
1164	11			11	1	16	my $mixin = shift;
1165	11					33	my ($into, @args) = _into(@_);
1166	11					62	$mixin->_import($into, $into, @args);
1167							}
1168
1169							=head3 alias
1170
1171							alias Some::Clever:Templates under '/delegate';
1172							alias Some::Other::Templates under '/send_to', { name => 'Larry' };
1173							alias UI::Stuff into My::View, under '/mystuff';
1174
1175							Aliases templates from one template class into another class. When an alias
1176							called, its invocant will be the class from which it was aliased. This type of
1177							composition is known as "delegation" in object-oriented parlance. See
1178							L
1179							comparison to C.
1180
1181							The first parameter is the name of the template class to alias. The C
1182							keyword tells C where to put the templates. For example, a C
1183							template in C will be aliased as C.
1184
1185							The C keyword specifies package variables available only to the
1186							aliases. These are available to the templates as
1187							C<< $self->package_variable($varname) >>.
1188
1189							The C keyword tells C into what class to alias the templates.
1190							Without this keyword, C will alias them into the calling class.
1191
1192							For those who prefer a direct OO syntax for mixins, just call C as a
1193							method on the class to be mixed in. To replicate the above three examples
1194							without the use of the sugar:
1195
1196							Some::Clever:Templates->alias( '/delegate' );
1197							Some::Other::Templates->alias( '/send_to', { name => 'Larry' } );
1198							UI::Stuff->alias( 'My::View', '/mystuff' );
1199
1200							=cut
1201
1202							sub alias {
1203	15			15	1	27	my $mixin = shift;
1204	15					44	my ($into, @args) = _into(@_);
1205	15					136	$mixin->_import($into, undef, @args);
1206							}
1207
1208							=head3 package_variable( VARIABLE )
1209
1210							$td->package_variable( $varname => $value );
1211							$value = $td->package_variable( $varname );
1212
1213							Returns a value set for a mixed-in template's variable, if any were specified
1214							when the template was mixed-in. See L for details.
1215
1216							=cut
1217
1218							sub package_variable {
1219	10			10	1	71	my $self = shift;
1220	10					15	my $var = shift;
1221	10	50				28	if (@_) {
1222	0					0	$TEMPLATE_VARS->{$self}->{$var} = shift;
1223							}
1224	10					49	return $TEMPLATE_VARS->{$self}->{$var};
1225							}
1226
1227							=head3 package_variables( VARIABLE )
1228
1229							$td->package_variables( $variables );
1230							$variables = $td->package_variables;
1231
1232							Get or set a hash reference of variables for a mixed-in template. See
1233							L for details.
1234
1235							=cut
1236
1237							sub package_variables {
1238	0			0	1	0	my $self = shift;
1239	0	0				0	if (@_) {
1240	0					0	%{ $TEMPLATE_VARS->{$self} } = shift;
	0					0
1241							}
1242	0					0	return $TEMPLATE_VARS->{$self};
1243							}
1244
1245							=head2 Templates registration and lookup
1246
1247							=head3 resolve_template TEMPLATE_PATH INCLUDE_PRIVATE_TEMPLATES
1248
1249							my $code = Template::Declare->resolve_template($template);
1250							my $code = Template::Declare->has_template($template, 1);
1251
1252							Turns a template path (C) into a C. If the
1253							boolean C is true, resolves private templates
1254							in addition to public ones. C is an alias for this method.
1255
1256							First it looks through all the valid Template::Declare classes defined via
1257							C. For each class, it looks to see if it has a template called
1258							$template_name directly (or via a mixin).
1259
1260							=cut
1261
1262							sub resolve_template {
1263	286			286	1	466	my $self = shift;
1264	286					542	my $template_name = shift;
1265	286		100			1399	my $show_private = shift \|\| 0;
1266
1267	286					369	my @search_packages;
1268
1269							# If we're being called as a class method on T::D it means "search in any package"
1270							# Otherwise, it means search only in this specific package"
1271	286	100				692	if ( $self eq __PACKAGE__ ) {
1272	246					332	@search_packages = @{ Template::Declare->dispatch_to };
	246					819
1273							} else {
1274	40					85	@search_packages = ($self);
1275							}
1276
1277	286					2523	foreach my $package (@search_packages) {
1278	291	50	33			6078	next unless ( $package and $package->isa(__PACKAGE__) );
1279	291	100				1376	if ( my $coderef = $package->_has_template( $template_name, $show_private ) ) {
1280	252					1047	return $coderef;
1281							}
1282							}
1283							}
1284
1285							=head3 has_template TEMPLATE_PATH INCLUDE_PRIVATE_TEMPLATES
1286
1287							An alias for C.
1288
1289							=cut
1290
1291	53			53	1	6545	sub has_template { resolve_template(@_) }
1292
1293							=head3 register_template( TEMPLATE_NAME, CODEREF )
1294
1295							MyApp::Templates->register_template( howdy => sub { ... } );
1296
1297							This method registers a template called C in the calling class.
1298							As you might guess, C defines the template's implementation. This
1299							method is mainly intended to be used internally, as you use the C
1300							keyword to create templates, right?
1301
1302							=cut
1303
1304							sub register_template {
1305	196			196	1	315	my $class = shift;
1306	196					277	my $template_name = shift;
1307	196					277	my $code = shift;
1308	196					3337	push @{ __PACKAGE__->templates()->{$class} }, $template_name;
	196					1089
1309	196					2098	_register_template( $class, _template_name_to_sub($template_name), $code )
1310							}
1311
1312							=head3 register_private_template( TEMPLATE_NAME, CODEREF )
1313
1314							MyApp::Templates->register_private_template( howdy => sub { ... } );
1315
1316							This method registers a private template called C in the
1317							calling class. As you might guess, C defines the template's
1318							implementation.
1319
1320							Private templates can't be called directly from user code but only from other
1321							templates.
1322
1323							This method is mainly intended to be used internally, as you use the
1324							C expression to create templates, right?
1325
1326							=cut
1327
1328							sub register_private_template {
1329	21			21	1	35	my $class = shift;
1330	21					38	my $template_name = shift;
1331	21					28	my $code = shift;
1332	21					22	push @{ __PACKAGE__->private_templates()->{$class} }, $template_name;
	21					98
1333	21					190	_register_template( $class, _template_name_to_private_sub($template_name), $code );
1334
1335							}
1336
1337							=head3 buffer
1338
1339							Gets or sets the L object; this is a class method.
1340
1341							You can use it to manipulate the output from tags as they are output. It's used
1342							internally to make the tags nest correctly, and be output to the right place.
1343							We're not sure if there's ever a need for you to frob it by hand, but it does
1344							enable things like the following:
1345
1346							template simple => sub {
1347							html {
1348							head {}
1349							body {
1350							Template::Declare->buffer->set_filter( sub {uc shift} );
1351							p { 'Whee!' }
1352							p { 'Hello, world wide web!' }
1353							Template::Declare->buffer->clear_top if rand() < 0.5;
1354							}
1355							}
1356							};
1357
1358							...which outputs, with equal regularity, either:
1359
1360
1361
1362
1363							WHEE!
1364							HELLO, WORLD WIDE WEB!
1365
1366
1367
1368							...or:
1369
1370
1371
1372
1373
1374
1375							We'll leave it to you to judge whether or not that's actually useful.
1376
1377							=head2 Helpers
1378
1379							You don't need to call any of this directly.
1380
1381							=head3 into
1382
1383							$class = into $class;
1384
1385							C is a helper method providing semantic sugar for the L method.
1386							All it does is return the name of the class on which it was called.
1387
1388							=cut
1389
1390	4			4	1	16	sub into { shift }
1391
1392							=head2 Old, deprecated or just better to avoid
1393
1394							=head3 import_templates
1395
1396							import_templates MyApp::Templates under '/something';
1397
1398							Like C, but without support for the C or C keywords.
1399							That is, it mixes templates into the calling template class and does not
1400							support package variables for those mixins.
1401
1402							B in favor of L. Will be supported for a long time, but
1403							new code should use C.
1404
1405							=cut
1406
1407							sub import_templates {
1408	11			11	1	31	my $caller = scalar caller(0);
1409	11					66	shift->_import($caller, $caller, @_);
1410							}
1411
1412							=head3 new_buffer_frame
1413
1414							$td->new_buffer_frame;
1415							# same as
1416							$td->buffer->push( private => 1 );
1417
1418							Creates a new buffer frame, using L with C.
1419
1420							B in favor of dealing with L directly.
1421
1422							=cut
1423
1424							sub new_buffer_frame {
1425	0			0	1	0	__PACKAGE__->buffer->push( private => 1 );
1426							}
1427
1428							=head3 end_buffer_frame
1429
1430							my $buf = $td->end_buffer_frame;
1431							# same as
1432							my $buf = $td->buffer->pop;
1433
1434							Deletes and returns the topmost buffer, using L.
1435
1436							B in favor of dealing with L directly.
1437
1438							=cut
1439
1440							sub end_buffer_frame {
1441	0			0	1	0	__PACKAGE__->buffer->pop;
1442							}
1443
1444							=head3 path_for $template
1445
1446							my $path = Template::Declare->path_for('index');
1447
1448							Returns the path for the template name to be used for show, adjusted with
1449							paths used in C. Note that this will only work for the last class into
1450							which you imported the template. This method is, therefore, deprecated.
1451
1452							=cut
1453
1454							# Deprecated in favor of dispatch_to().
1455							sub roots {
1456							# warn "roots() has been deprecated; use dispatch_to() instead\n";
1457	1			1	1	2	my $class = shift;
1458	1	50				4	$class->dispatch_to( [ reverse @{ +shift } ] ) if @_;
	1					5
1459	1					7	return [ reverse @{ $class->dispatch_to } ];
	1					5
1460							}
1461
1462							# Removed methods that no longer work (and were never documented anyway).
1463							# Remove these no-ops after a few releases (added for 0.41).
1464
1465							=begin comment
1466
1467							=head3 aliases
1468
1469							=head3 alias_metadata
1470
1471							=end comment
1472
1473							=cut
1474
1475							sub aliases {
1476	0			0	1	0	require Carp;
1477	0					0	Carp::cluck( 'aliases() is a deprecated no-op' );
1478							}
1479
1480							sub alias_metadata {
1481	0			0	1	0	require Carp;
1482	0					0	Carp::cluck( 'alias_metadata() is a deprecated no-op' );
1483							}
1484
1485							sub path_for {
1486	3			3	1	7780	my $class = shift;
1487	3					7	my $template = shift;
1488	3		100			23	return ($class->imported_into \|\|'') . '/' . $template;
1489							}
1490
1491							sub _templates_for {
1492	79	100		79		233	my $tmpl = shift->templates->{+shift} or return;
1493	37	50				322	return wantarray ? @{ $tmpl } : $tmpl;
	37					181
1494							}
1495
1496							sub _private_templates_for {
1497	79	100		79		238	my $tmpl = shift->private_templates->{+shift} or return;
1498	10	50				80	return wantarray ? @{ $tmpl } : $tmpl;
	10					29
1499							}
1500
1501							sub _has_template {
1502							# Otherwise find only in specific package
1503	291			291		439	my $pkg = shift;
1504	291					413	my $template_name = shift;
1505	291					421	my $show_private = 0 \|\| shift;
1506
1507	291	100	100			832	if ( my $coderef = $pkg->_find_template_sub( _template_name_to_sub($template_name) ) ) {
		100
1508	246					1066	return $coderef;
1509							} elsif ( $show_private and $coderef = $pkg->_find_template_sub( _template_name_to_private_sub($template_name))) {
1510	6					21	return $coderef;
1511							}
1512
1513	39					717	return undef;
1514							}
1515
1516							sub _dispatch_template {
1517	214			214		398	my $class = shift;
1518	214					403	my $code = shift;
1519	214					470	unshift @_, $class;
1520	214					685	goto $code;
1521							}
1522
1523							sub _find_template_sub {
1524	355			355		556	my $self = shift;
1525	355					550	my $subname = shift;
1526	355					3468	return $self->can($subname);
1527							}
1528
1529							sub _template_name_to_sub {
1530	534			534		1597	return _subname( "_jifty_template_", shift );
1531							}
1532
1533							sub _template_name_to_private_sub {
1534	38			38		80	return _subname( "_jifty_private_template_", shift );
1535							}
1536
1537							sub _subname {
1538	572			572		735	my $prefix = shift;
1539	572		50			3072	my $template = shift \|\| '';
1540	572					2575	$template =~ s{/+}{/}g;
1541	572					950	$template =~ s{^/}{};
1542	572					8340	return join( '', $prefix, $template );
1543							}
1544
1545							sub _register_template {
1546	217			217		1353	my $self = shift;
1547	217		33			4369	my $class = ref($self) \|\| $self;
1548	217					362	my $subname = shift;
1549	217					274	my $coderef = shift;
1550	48			48		148541	no strict 'refs';
	48					192
	48					1980
1551	48			48		1163	no warnings 'redefine';
	48					94
	48					42190
1552	217					256	*{ $class . '::' . $subname } = $coderef;
	217					2145
1553							}
1554
1555							sub _into {
1556	26			26		35	my ($into, $under);
1557	26	100				38	if ( eval { $_[0]->isa(__PACKAGE__) } ) {
	26	100				237
1558	2					6	($into, $under) = (shift, shift);
1559	24					286	} elsif ( eval { $_[1]->isa(__PACKAGE__) } ) {
1560	2					5	($under, $into) = (shift, shift);
1561							} else {
1562	22					140	$into = caller(1);
1563	22					36	$under = shift;
1564							}
1565	26					133	return $into, $under, @_;
1566							}
1567
1568							sub _import {
1569	37	50		37		121	return undef if $_[0] eq __PACKAGE__;
1570	37					82	my ($mixin, $into, $invocant, $prefix, $vars) = @_;
1571
1572
1573	37					61	$prefix =~ s\|/+/\|/\|g;
1574	37					118	$prefix =~ s\|/$\|\|;
1575	37					224	$mixin->imported_into($prefix);
1576
1577	37					1296	my @packages = reverse grep { $_->isa(__PACKAGE__) }
	116					5612
1578							Class::ISA::self_and_super_path( $mixin );
1579
1580	37					99	foreach my $from (@packages) {
1581	79					611	for my $tname ( __PACKAGE__->_templates_for($from) ) {
1582	47					273	my $sname = _template_name_to_sub($tname);
1583	47		66			359	$into->register_template(
1584							"$prefix/$tname",
1585							_import_code( $sname, $from, $invocant \|\| $mixin, $vars )
1586							);
1587							}
1588	79					593	for my $tname ( __PACKAGE__->_private_templates_for($from) ) {
1589	10					17	my $sname = _template_name_to_private_sub($tname);
1590	10		66			49	$into->register_private_template(
1591							"$prefix/$tname",
1592							_import_code( $sname, $from, $invocant \|\| $mixin, $vars )
1593							);
1594							}
1595							}
1596							}
1597
1598							sub _import_code {
1599	57			57		122	my ($sname, $from, $mixin, $vars) = @_;
1600	57					275	my $code = $from->_find_template_sub( $sname );
1601	30			30		50	return $mixin eq $from ? $code : sub { shift; $code->($mixin, @_) }
	30					157
1602	57	100				13262	unless $vars;
		100
1603							return sub {
1604	2			2		5	shift @_; # Get rid of the passed-in "$self" class.
1605	2					8	local $TEMPLATE_VARS->{$mixin} = $vars;
1606	2					9	$code->($mixin, @_);
1607	4					41	};
1608							}
1609
1610							=head1 PITFALLS
1611
1612							We're reusing the perl interpreter for our templating language, but Perl was
1613							not designed specifically for our purpose here. Here are some known pitfalls
1614							while you're scripting your templates with this module.
1615
1616							=over
1617
1618							=item *
1619
1620							It's quite common to see tag sub calling statements without trailing
1621							semi-colons right after C<}>. For instance,
1622
1623							template foo => sub {
1624							p {
1625							a { attr { src => '1.png' } }
1626							a { attr { src => '2.png' } }
1627							a { attr { src => '3.png' } }
1628							}
1629							};
1630
1631							is equivalent to
1632
1633							template foo => sub {
1634							p {
1635							a { attr { src => '1.png' } };
1636							a { attr { src => '2.png' } };
1637							a { attr { src => '3.png' } };
1638							};
1639							};
1640
1641							But C is a notable exception. Please always put a trailing semicolon
1642							after C, or you'll mess up the order of output.
1643
1644							=item *
1645
1646							Another place that requires trailing semicolon is the statements before a Perl
1647							looping statement, an C statement, or a C call. For example:
1648
1649							p { "My links:" };
1650							for (@links) {
1651							with ( src => $_ ), a {}
1652							}
1653
1654							The C<;> after C< p { ... } > is required here, or Perl will complain about
1655							syntax errors.
1656
1657							Another example is
1658
1659							h1 { 'heading' }; # this trailing semicolon is mandatory
1660							show 'tag_tag'
1661
1662							=item *
1663
1664							The C syntax for declaring tag attributes also requires a trailing
1665							semicolon, unless it is the only statement in a block. For example,
1666
1667							p { class is 'item'; id is 'item1'; outs "This is an item" }
1668							img { src is 'cat.gif' }
1669
1670							=item *
1671
1672							Literal strings that have tag siblings won't be captured. So the following template
1673
1674							p { 'hello'; em { 'world' } }
1675
1676							produces
1677
1678
1679							world
1680
1681
1682							instead of the desired output
1683
1684
1685							hello
1686							world
1687
1688
1689							You can use C here to solve this problem:
1690
1691							p { outs 'hello'; em { 'world' } }
1692
1693							Note you can always get rid of C if the string literal is the only
1694							element of the containing block:
1695
1696							p { 'hello, world!' }
1697
1698							=item *
1699
1700							Look out! If the if block is the last block/statement and the condition part
1701							is evaluated to be 0:
1702
1703							p { if ( 0 ) { } }
1704
1705							produces
1706
1707							0
1708
1709							instead of the more intuitive output:
1710
1711
1712
1713							This is because C is the last expression, so C<0> is returned as the
1714							value of the whole block, which is used as the content of tag.
1715
1716							To get rid of this, just put an empty string at the end so it returns empty
1717							string as the content instead of 0:
1718
1719							p { if ( 0 ) { } '' }
1720
1721							=back
1722
1723							=head1 BUGS
1724
1725							Crawling all over, baby. Be very, very careful. This code is so cutting edge,
1726							it can only be fashioned from carbon nanotubes. But we're already using this
1727							thing in production :) Make sure you have read the L
1728							section above :)
1729
1730							Some specific bugs and design flaws that we'd love to see fixed.
1731
1732							=over
1733
1734							=item Output isn't streamy.
1735
1736							=back
1737
1738							If you run into bugs or misfeatures, please report them to
1739							C.
1740
1741							=head1 SEE ALSO
1742
1743							=over
1744
1745							=item L
1746
1747							=item L
1748
1749							=item L
1750
1751							=item L
1752
1753							=item L
1754
1755							=back
1756
1757							=head1 AUTHOR
1758
1759							Jesse Vincent
1760
1761							=head1 LICENSE
1762
1763							Template::Declare is Copyright 2006-2010 Best Practical Solutions, LLC.
1764
1765							Template::Declare is distributed under the same terms as Perl itself.
1766
1767							=cut
1768
1769							1;

File Coverage

Welcome to

Welcome to my site. It's great!

This is _not_ emphasized.

Hello

Hello, Jesse, s'up?

Kashmir

My page title

My page title