1 package Template::Simple;
11 our $VERSION = '0.01';
16 post_delim => qr/%\]/,
20 include_paths => [ qw( templates ) ],
25 my( $class, %opts ) = @_ ;
27 my $self = bless {}, $class ;
29 # get all the options or defaults into the object
31 while( my( $name, $default ) = each %opt_defaults ) {
33 $self->{$name} = defined( $opts{$name} ) ?
34 $opts{$name} : $default ;
37 # make up the regexes to parse the markup from templates
39 # this matches scalar markups and grabs the name
41 $self->{scalar_re} = qr{
43 \s* # optional leading whitespace
44 (\w+?) # grab scalar name
45 \s* # optional trailing whitespace
47 }xi ; # case insensitive
49 #print "RE <$self->{scalar_re}>\n" ;
51 # this grabs the body of a chunk in either greedy or non-greedy modes
53 my $chunk_body = $self->{greedy_chunk} ? qr/.+/s : qr/.+?/s ;
55 # this matches a marked chunk and grabs its name and text body
57 $self->{chunk_re} = qr{
59 \s* # optional leading whitespace
60 START # required START token
61 \s+ # required whitespace
62 (\w+?) # grab the chunk name
63 \s* # optional trailing whitespace
65 ($chunk_body) # grab the chunk body
67 \s* # optional leading whitespace
68 END # required END token
69 \s+ # required whitespace
70 \1 # match the grabbed chunk name
71 \s* # optional trailing whitespace
73 }xi ; # case insensitive
75 #print "RE <$self->{chunk_re}>\n" ;
77 # this matches a include markup and grabs its template name
79 $self->{include_re} = qr{
81 \s* # optional leading whitespace
82 INCLUDE # required INCLUDE token
83 \s+ # required whitespace
84 (\w+?) # grab the included template name
85 \s* # optional trailing whitespace
87 }xi ; # case insensitive
89 # load in any templates
91 $self->add_templates( $opts{templates} ) ;
100 my( $self, $template, $data ) = @_ ;
102 # make a copy if a scalar ref is passed as the template text is
105 my $tmpl_ref = ref $template eq 'SCALAR' ? $template : \$template ;
107 my $expanded = $self->_expand_includes( $tmpl_ref ) ;
109 #print "INC EXP <$expanded>\n" ;
112 $self->_expand_chunk( $expanded, $data ) ;
115 croak "Template::Simple $@" if $@ ;
120 sub _expand_includes {
122 my( $self, $tmpl_ref ) = @_ ;
124 # make a copy of the initial template so we can expand it.
126 my $expanded = ${$tmpl_ref} ;
128 # loop until we can expand no more include markups
131 s{$self->{include_re}}
132 { ${ $self->_get_template($1) }
140 HASH => \&_expand_hash,
141 ARRAY => \&_expand_array,
142 CODE => \&_expand_code,
143 # if no ref then data is a scalar so replace the template with just the data
144 '' => sub { \$_[2] },
149 my( $self, $tmpl_ref, $data ) = @_ ;
151 #print "T ref [$tmpl_ref] [$$tmpl_ref]\n" ;
152 #print "CHUNK TMPL\n<$$tmpl_ref>\n" ;
154 #print Dumper $data ;
156 return \'' unless defined $data ;
158 # now expand this chunk based on the type of data
160 my $expander = $expanders{ref $data} ;
162 #print "EXP $expander\nREF ", ref $data, "\n" ;
164 die "unknown template data type '$data'\n" unless defined $expander ;
166 return $self->$expander( $tmpl_ref, $data ) ;
171 my( $self, $tmpl_ref, $href ) = @_ ;
173 return $tmpl_ref unless keys %{$href} ;
175 # print "T ref [$tmpl_ref] [$$tmpl_ref]\n" ;
176 # print "HASH TMPL\n$$tmpl_ref\n" ;
178 # we need a local copy of the template to expand
180 my $expanded = ${$tmpl_ref} ;
182 # recursively expand all top level chunks in this chunk
184 $expanded =~ s{$self->{chunk_re}}
186 # print "CHUNK $1\nBODY\n----\n<$2>\n\n------\n" ;
187 ${$self->_expand_chunk( \$2, $href->{$1} ) }}gex ;
191 #print "HASH TMPL\n<$expanded>\n" ;
192 #print Dumper $href ;
194 $expanded =~ s{$self->{scalar_re}}
196 #print "SCALAR $1 VAL $href->{$1}\n" ;
197 defined $href->{$1} ? $href->{$1} : '' }ge ;
199 #print "HASH2 TMPL\n$$expanded\n" ;
206 my( $self, $tmpl_ref, $aref ) = @_ ;
208 # expand this $tmpl_ref for each element of the aref and join them
212 #print Dumper $aref ;
214 $expanded .= ${$self->_expand_chunk( $tmpl_ref, $_ )} for @{$aref} ;
221 my( $self, $tmpl_ref, $cref ) = @_ ;
223 my $expanded = $cref->( $tmpl_ref ) ;
225 croak <<CROAK if ref $expanded ne 'SCALAR' ;
226 code expansion didn't return a scalar or scalar reference
234 my( $self, $tmpls ) = @_ ;
236 #print Dumper $tmpls ;
237 return unless defined $tmpls ;
239 ref $tmpls eq 'HASH' or croak "templates argument is not a hash ref" ;
241 @{ $self->{templates}}{ keys %{$tmpls} } =
242 map ref $_ eq 'SCALAR' ? \"${$_}" : \"$_", values %{$tmpls} ;
244 #print Dumper $self->{templates} ;
249 sub delete_templates {
251 my( $self, @names ) = @_ ;
253 @names = keys %{$self->{templates}} unless @names ;
255 delete @{$self->{templates}}{ @names } ;
257 delete @{$self->{template_paths}}{ @names } ;
264 my( $self, $tmpl_name ) = @_ ;
266 #print "INC $tmpl_name\n" ;
268 my $tmpls = $self->{templates} ;
270 # get the template from the cache and send it back if it was found there
272 my $template = $tmpls->{ $tmpl_name } ;
273 return $template if $template ;
275 # not found, so find, slurp in and cache the template
277 $template = $self->_find_template( $tmpl_name ) ;
278 $tmpls->{ $tmpl_name } = $template ;
285 my( $self, $tmpl_name ) = @_ ;
287 foreach my $dir ( @{$self->{include_paths}} ) {
289 my $tmpl_path = "$dir/$tmpl_name.tmpl" ;
291 print "PATH: $tmpl_path\n" ;
292 next unless -r $tmpl_path ;
294 # cache the path to this template
296 $self->{template_paths}{$tmpl_name} = $tmpl_path ;
298 # slurp in the template file and return it as a scalar ref
300 return scalar read_file( $tmpl_path, scalar_ref => 1 ) ;
304 can't find template '$tmpl_name' in '@{$self->{include_paths}}'
309 1; # End of Template::Simple
315 Template::Simple - A simple and fast template module
323 use Template::Simple;
325 my $tmpl = Template::Simple->new();
327 my $template = <<TMPL ;
330 [%first%] - [%second%]
337 date => 'Jan 1, 2008',
338 author => 'Me, myself and I',
342 first => 'row 1 value 1',
343 second => 'row 1 value 2',
346 first => 'row 2 value 1',
347 second => 'row 2 value 2',
351 modified => 'Aug 31, 2006',
355 my $expanded = $tmpl->expand( $template, $data ) ;
359 Template::Simple has these goals:
363 =item * Support most common template operations
365 It can recursively include other templates, replace tokens (scalars),
366 recursively expand nested chunks of text and expand lists. By using
367 simple idioms you can get conditional expansions.
369 =item * Complete isolation of template from program code
371 This is very important as template design can be done by different
372 people than the program logic. It is rare that one person is well
373 skilled in both template design and also programming.
375 =item * Very simple template markup (only 4 markups)
377 The only markups are C<INCLUDE>, C<START>, C<END> and C<token>. See
380 =item * Easy to follow expansion rules
382 Expansion of templates and chunks is driven from a data tree. The type
383 of the data element used in an expansion controls how the expansion
384 happens. The data element can be a scalar or scalar reference or an
385 array, hash or code reference.
387 =item * Efficient template expansion
389 Expansion is very simple and uses Perl's regular expressions
390 efficiently. Because the markup is so simple less processing is needed
391 than many other templaters. Precompiling templates is not supported
392 yet but that optimization is on the TODO list.
394 =item * Easy user extensions
396 User code can be called during an expansion so you can do custom
397 expansions and plugins. Closures can be used so the code can have its
398 own private data for use in expanding its template chunk.
404 You create a Template::Simple by calling the class method new:
406 my $tmpl = Template::Simple->new() ;
408 All the arguments to C<new()> are key/value options that change how
409 the object will do expansions.
415 This option sets the string or regex that is the starting delimiter
416 for all markups. You can use a plain string or a qr// but you need to
417 escape (with \Q or \) any regex metachars if you want them to be plain
418 chars. The default is qr/\[%/.
420 my $tmpl = Template::Simple->new(
424 my $expanded = $tmpl->expand( '<%FOO%]', 'bar' ) ;
428 This option sets the string or regex that is the ending delimiter
429 for all markups. You can use a plain string or a qr// but you need to
430 escape (with \Q or \) any regex metachars if you want them to be plain
431 chars. The default is qr/%]/.
433 my $tmpl = Template::Simple->new(
437 my $expanded = $tmpl->expand( '[%FOO%>', 'bar' ) ;
441 This boolean option will cause the regex that grabs a chunk of text
442 between the C<START/END> markups to become greedy (.+). The default is
443 a not-greedy grab of the chunk text. (UNTESTED)
447 This option lets you load templates directly into the cache of the
448 Template::Simple object. This cache will be searched by the C<INCLUDE>
449 markup which will be replaced by the template if found. The option
450 value is a hash reference which has template names (the name in the
451 C<INCLUDE> markup) for keys and their template text as their
452 values. You can delete or clear templates from the object cache with
453 the C<delete_template> method.
456 my $tmpl = Template::Simple->new(
460 [%baz%] is a [%quux%]
463 [%user%] is not a [%fool%]
468 my $template = <<TMPL ;
472 my $expanded = $tmpl->expand(
482 Template::Simple can also load C<INCLUDE> templates from files. This
483 option lets you set the directory paths to search for those
484 files. Note that the template name in the C<INCLUDE> markup has the
485 .tmpl suffix appended to it when searched for in one of these
486 paths. The loaded file is cached inside the Template::Simple object
487 along with any loaded by the C<templates> option.
493 =head2 expand( $template, $data )
497 This method adds templates to the object cache. It takes a list of template names and texts just like the C<templates> constructor option.
499 $tmpl->add_templates(
501 foo => \$foo_template,
502 bar => '[%include bar%]',
506 =head2 delete_templates
508 This method takes a list of template names and will delete them from
509 the template cache in the object. If you pass in an empty list then
510 all the templates will be deleted. This can be used when you know a
511 template file has been updated and you want to get it loaded back into
512 the cache. Note that you can delete templates that were loaded
513 directly (via the C<templates> constructor option or the
514 C<add_templates> method) or loaded from a file.
516 # this deletes only the foo and bar templates from the object cache
518 $tmpl->delete_templates( qw( foo bar ) ;
520 # this deletes all of templates from the object cache
522 $tmpl->delete_templates() ;
524 =head2 get_dependencies
526 This method expand the only C<INCLUDE> markups of a template and it
527 returns a list of the file paths that were found and loaded. It is
528 meant to be used to build up a dependency list of included templates
529 for a main template. Typically this can be called from a script (see
530 TODO) that will do this for a set of main templates and will generate
531 Makefile dependencies for them. Then you can regenerate expanded
532 templates only when any of their included templates have changed. It
533 takes a single argument of a template.
535 UNKNOWN: will this require a clearing of the cache or will it do the
536 right thing on its own? or will it use the file path cache?
539 $tmpl->get_dependencies( '[%INCLUDE top_level%]' );
543 All the markups in Template::Simple use the same delimiters which are
544 C<[%> and C<%]>. You can change the delimiters with the C<pre_delim>
545 and C<post_delim> options in the C<new()> constructor.
549 A token is a single markup with a C<\w+> Perl word inside. The token
550 can have optional whitespace before and after it. A token is replaced
551 by a value looked up in a hash with the token as the key. The hash
552 lookup keeps the same case as parsed from the token markup.
556 Those will be replaced by C<$href->{foo}> and C<$href->{BAR}> assuming
557 C<$href> is the current data for this expansion. Tokens are only
558 parsed out during hash data expansion so see Hash Data for more.
562 Chunks are regions of text in a template that are marked off with a
563 start and end markers with the same name. A chunk start marker is
564 C<[%START name%]> and the end marker for that chunk is C<[%END
565 name%]>. C<name> is a C<\w+> Perl word which is the name of this
566 chunk. The whitespace between C<START/END> and C<name> is required and
567 there is optional whitespace before C<START/END> and after the
568 C<name>. C<START/END> are case insensitive but the C<name>'s case is
569 kept. C<name> must match in the C<START/END> pair and it used as a key
570 in a hash data expansion. Chunks are the primary way to markup
571 templates for structures (sets of tokens), nesting (hashes of hashes),
572 repeats (array references) and callbacks to user code. Chunks are only
573 parsed out during hash data expansion so see Hash Data for more.
575 The body of text between the C<START/END> markups is grabbed with a
576 C<.+?> regular expression with the /s option enabled so it will match
577 all characters. By default it will be a non-greedy grab but you can
578 change that in the constructor by enabling the C<greedy_chunk> option.
588 =head1 EXPANSION RULES
590 Template::Simple has a short list of expansion rules and they are easy
591 to understand. There are two types of expansions, include expansion
592 and chunk expansion. In the C<expand> method, the template is an
593 unnamed top level chunk of text and it first gets its C<INCLUDE>
594 markups expanded. The text then undergoes a chunk expansion and a
595 scalar reference to that expanded template is returned to the caller.
597 =head2 Include Expansion
599 Include expansion is performed one time on a top level template. When
600 it is done the template is ready for chunk expansion. Any markup of
601 the form C<[%INCLUDE name]%> will be replaced by the text found in the
602 template C<name>. The template name is looked up in the object's
603 template cache and if it is found there its text is used as the
606 If a template is not found in the cache, it will be searched for in
607 the list of directories in the C<include_paths> option. The file name
608 will be a directory in that list appended with the template name and
609 the C<.tmpl> suffix. The first template file found will be read in and
610 stored in the cache. Its path is also saved and those will be returned
611 in the C<get_dependencies> method. See the C<add_templates> and
612 C<delete_templates> methods and the C<include_paths> option.
614 Expanded include text can contain more C<INCLUDE> markups and they
615 will also be expanded. The include expansion phase ends where there
616 are no more C<INCLUDE> found.
618 =head2 Chunk Expansion
620 A chunk is the text found between C<START> and C<END> markups and it
621 gets its named from the C<START> markup. The top level template is
622 considered an unamed chunk and also gets chunk expanded.
624 The data for a chunk determines how it will be expanded. The data can
625 be a scalar or scalar reference or an array, hash or code
626 reference. Since chunks can contain nested chunks, expansion will
627 recurse down the data tree as it expands the chunks. Each of these
628 expansions are explained below. Also see the IDIOMS and BEST PRACTICES
629 section for examples and used of these expansions.
631 =head2 Scalar Data Expansion
633 If the current data for a chunk is a scalar or scalar reference, the
634 chunk's text in the templated is replaced by the scalar's value. This
635 can be used to overwrite one default section of text with from the
638 =head2 Code Data Expansion
640 If the current data for a chunk is a code reference (also called
641 anonymous sub) then the code reference is called and it is passed a
642 scalar reference to the that chunk's text. The code must return a
643 scalar or a scalar reference and its value replaces the chunk's text
644 in the template. If the code returns any other type of data it is a
645 fatal error. Code expansion is how you can do custom expansions and
646 plugins. A key idiom is to use closures as the data in code expansions
647 and keep the required outside data in the closure.
649 =head2 Array Data Expansion
651 If the current data for a chunk is an array reference do a full chunk
652 expansion for each value in the array. It will replace the original
653 chunk text with the joined list of expanded chunks. This is how you do
654 repeated sections in Template::Simple and why there is no need for any
655 loop markups. Note that this means that expanding a chunk with $data
656 and [ $data ] will do the exact same thing. A value of an empty array
657 C<[]> will cause the chunk to be replaced by the empty string.
659 =head2 Hash Data Expansion
661 If the current data for a chunk is a hash reference then two phases of
662 expansion happen, nested chunk expansion and token expansion. First
663 nested chunks are parsed of of this chunk along with their names. Each
664 parsed out chunk is expanded based on the value in the current hash
665 with the nested chunk's name as the key.
667 If a value is not found (undefined), then the nested chunk is replaced
668 by the empty string. Otherwise the nested chunk is expanded according
669 to the type of its data (see chunk expansion) and it is replaced by
672 Chunk name and token lookup in the hash data is case sensitive (see
673 the TODO for cased lookups).
675 Note that to keep a plain text chunk or to just have the all of its
676 markups (chunks and tokens) be deleted just pass in an empty hash
677 reference C<{}> as the data for the chunk. It will be expanded but all
678 markups will be replaced by the empty string.
680 =head2 Token Expansion
682 The second phase is token expansion. Markups of the form [%token%] are
683 replaced by the value of the hash element with the token as the
684 key. If a token's value is not defined it is replaced by the empty
685 string. This means if a token key is missing in the hash or its value
686 is undefined or its value is the empty string, the [%token%] markup
687 will be deleted in the expansion.
689 =head1 IDIOMS and BEST PRACTICES
691 With all template systems there are better ways to do things and
692 Template::Simple is no different. This section will show some ways to
693 handle typical template needs while using only the 4 markups in this
698 This conditional idiom can be when building a fresh data tree or
699 modifying an existing one.
701 $href->{$chunk_name} = $keep_chunk ? {} : '' ;
703 If you are building a fresh data tree you can use this idiom to do a
706 $href->{$chunk_name} = {} if $keep_chunk ;
708 To handle an if/else conditional use two chunks, with the else chunk's
709 name prefixed with NOT_ (or use any name munging you want). Then you
710 set the data for either the true chunk (just the plain name) or the
711 false trunk with the NOT_ name. You can use a different name for the
712 else chunk if you want but keeping the names of the if/else chunks
713 related is a good idea. Here are two ways to set the if/else data. The
714 first one uses the same data for both the if and else chunks and the
715 second one uses different data so the it uses the full if/else code
718 $href->{ ($boolean ? '' : 'NOT_') . $chunk_name} = $data
721 $href->{ $chunk_name} = $true_data ;
723 $href->{ "NOT_$chunk_name" } = $false_data ;
726 NOTE TO ALPHA USERS: i am also thinking that a non-existing key or
727 undefined hash value should leave the chunk as is. then you would need
728 to explicitly replace a chunk with the empty string if you wanted it
729 deleted. It does affect the list of styles idiom. Any thoughts on
730 this change of behavior? Since this hasn't been released it is the
733 =head2 Chunked Includes
735 One of the benefits of using include templates is the ability to share
736 and reuse existing work. But if an included template has a top level
737 named chunk, then that name would also be the same everywhere where
738 this template is included. If a template included another template in
739 multiple places, its data tree would use the same name for each and
740 not allow unique data to be expanded for each include. A better way is
741 to have the current template wrap an include markup in a named chunk
742 markup. Then the data tree could use unique names for each included
743 template. Here is how it would look:
745 [%START foo_prime%][%INCLUDE foo%][%START foo_prime%]
747 [%START foo_second%][%INCLUDE foo%][%START foo_second%]
749 See the TODO section for some ideas on how to make this even more high level.
751 =head2 Repeated Sections
753 If you looked at the markup of Template::Simple you have noticed that
754 there is no loop or repeat construct. That is because there is no need
755 for one. Any chunk can be expanded in a loop just by having its
756 expansion data be an anonymous array. The expander will loop over each
757 element of the array and do a fresh expansion of the chunk with this
758 data. A join (on '') of the list of expansions replaces the original
759 chunk and you have a repeated chunk.
761 =head2 A List of Mixed Styles
763 One formating style is to have a list of sections each which can have
764 its own style or content. Template::Simple can do this very easily
765 with just a 2 level nested chunk and an array of data for
766 expansion. The outer chunk includes (or contains) each of the desired
767 styles in any order. It looks like this:
769 [%START para_styles%]
771 [%INCLUDE para_style_main%]
774 [%INCLUDE para_style_sub%]
776 [%START footer_style%]
777 [%INCLUDE para_style_footer%]
781 The other part to make this work is in the data tree. The data for
782 para_styles should be a list of hashes. Each hash contains the data
783 for one pargraph style which is keyed by the style's chunk name. Since
784 the other styles's chunk names are not hash they are deleted. Only the
785 style which has its name as a key in the hash is expanded. The data
786 tree would look something like this:
790 main_style => $main_data,
793 sub_style => $sub_data,
796 sub_style => $other_sub_data,
799 footer_style => $footer_data,
805 The test scripts use a common test driver module in t/common.pl. It is
806 passed a list of hashes, each of which has the data for one test. A
807 test can create a ne Template::Simple object or use the one from the
808 previous test. The template source, the data tree and the expected
809 results are also important keys. See the test scripts for examples of
810 how to write tests using this common driver.
816 This is the name of the test and is used by Test::More
820 This is a hash ref of the options passed to the Template::Simple
821 constructor. The object is not built if the C<keep_obj> key is set.
825 If set, this will make this test keep the Template::Simple object from
826 the previous test and not build a new one.
830 This is the template to expand for this test.
834 This is the data tree for the expansion of the template.
838 This is the text that is expected after the expansion.
842 If set, this test is skipped.
848 Even though this template system is simple, that doesn't mean it can't
849 be extended in many ways. Here are some features and designs that
850 would be good extensions which add useful functionality without adding
853 =head2 Compiled Templates
855 A commonly performed optimization in template modules is to precompile
856 (really preparse) templates into a internal form that will expand
857 faster. Precompiling is slower than expansion from the original
858 template which means you won't want to do it for each expansion. This
859 means it has a downside that you lose out when you want to expand
860 using templates which change often. Template::Simple makes it very
861 easy to precompile as it already has the regexes to parse out the
862 markup. So instead of calling subs to do actual expansion, a
863 precompiler would call subs to generate a compiled expansion tree.
864 The expansion tree can then be run or processes with expansion data
865 passed to it. You can think of a precompiled template as having all
866 the nested chunks be replaced by nested code that does the same
867 expansion. It can still do the dynamic expansion of the data but it
868 saves the time of parsing the template souice. There are three
869 possible internal formats for the precompiled template:
875 This precompiler will generate source code that can be stored and/or
876 eval'ed. The eval'ed top level sub can then be called and passed the
879 =item Closure call tree
881 The internal format can be a nested set of closures. Each closure would contain
882 private data such as fixed text parts of the original template, lists
883 of other closures to run, etc. It is trivial to write a basic closure
884 generator which will make build this tree a simple task.
886 =item Code ref call tree
888 This format is a Perl data tree where the nodes have a code reference
889 and its args (which can be nested instances of the same
890 nodes). Instead of executing this directly, you will need a small
891 interpreter to execute all the code refs as it runs through the tree.
893 This would make for a challenging project to any intermediate Perl
894 hacker. It just involves knowing recursion, data trees and code refs.
895 Contact me if you are interested in doing this.
899 =head2 Cased Hash Lookups
901 One possible option is to allow hash expansions to always use upper or
902 lower cased keys in their lookups.
904 =head2 Expand tokens before includes and chunks
906 Currently tokens are expanded after includes and chunks. If tokens
907 were expanded in a pass before the others, the include and chunk names
908 could be dynamically set. This would make it harder to precompile
909 templates as too much would be dynamic, i.e. you won't know what the
910 fixed text to parse out is since anything can be included at expand
911 time. But the extra flexibility of changing the include and chunk
912 names would be interesting. It could be done easily and enabled by an
917 There are two different potential areas in Template::Simple that could
918 use plugins. The first is with the expansion of chunkas and
919 dispatching based on the data type. This dispatch table can easily be
920 replaced by loaded modules which offer a different way to
921 expand. These include the precompiled expanders mentioned above. The
922 other area is with code references as the data type. By defining a
923 closure (or a closure making) API you can create different code refs
924 for the expansion data. The range of plugins is endless some of the
925 major template modules have noticed. One idea is to make a closure
926 which contains a different Template::Simple object than the current
927 one. This will allow expansion of a nested chunk with different rules
928 than the current chunk being expanded.
932 Some templaters have options to properly escape data for some types of
933 text files such as html. this can be done with some variant of the
934 _expand_hash routine which also does the scalar expansion (which is
935 where data is expanded). The expanding scalars code could be factored
936 out into a set of subs one of which is used based on any escaping
939 =head2 Data Tree is an Object
941 This is a concept I don't like but it was requested so it goes into
942 the TODO file. Currently C<expand> can only be passed a regular
943 (unblessed) ref (or a scalar) for its data tree. Passing in an object
944 would break encapsulation and force the object layout to be a hash
945 tree that matches the layout of the template. I doubt that most
946 objects will want to be organized to match a template. I have two
947 ideas, one is that you add a method to that object that builds up a
948 proper (unblessed) data tree to pass to C<expand>. The other is by
949 subclassing C<Template::Simple> and overriding C<expand> with a sub
950 that does take an object hash and it can unbless it or build a proper
951 data tree and then call C<expand> in SUPER::. A quick solution is to
952 use C<reftype> (from Scalar::Utils) instead of C<ref> to allow object
953 hashes to be passed in.
955 =head2 Includes and Closure Synergy
957 By pairing up an include template along with code that can generate
958 the appropriate data tree for its expansion, you can create a higher
959 level template framework (the synergy). Additional code can be
960 associated with them that will handle input processing and
961 verification for the templates (e.g. web forms) that need it. A key to
962 this will be making all the closures for the data tree. This can be
963 greatly simplified by using a closure maker sub that can create all
964 the required closures.
966 =head2 Metafields and UI Generation
968 Taking the synergy up to a much higher level is the concept of meta
969 knowledge of fields which can generate templates, output processing
970 (data tree generation), input processing, DB backing and more. If you
971 want to discuss such grandiose wacky application schemes in a long
972 rambling mind bending conversation, please contact me.
974 =head2 More Examples and Idioms
976 As I convert several scripts over to this module (they all used the
977 hack version), I will add them to an examples section or possibly put
978 them in another (pod only) module. Similarly the Idioms section needs
979 expansion and could be also put into a pod module. One goal requested
980 by an early alpha tester is to keep the primary docs as simple as the
981 markup itself. This means moving all the extra stuff (and plenty of
982 that) into other pod modules. All the pod modules would be in the same
983 cpan tarball so you get all the docs and examples when you install
988 Uri Guttman, C<< <uri at sysarch.com> >>
992 Please report any bugs or feature requests to
993 C<bug-template-simple at rt.cpan.org>, or through the web interface at
994 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template-Simple>.
995 I will be notified, and then you'll automatically be notified of progress on
996 your bug as I make changes.
1000 You can find documentation for this module with the perldoc command.
1002 perldoc Template::Simple
1004 You can also look for information at:
1008 =item * RT: CPAN's request tracker
1010 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Template-Simple>
1014 L<http://search.cpan.org/dist/Template-Simple>
1018 =head1 ACKNOWLEDGEMENTS
1020 I wish to thank Turbo10 for their support in developing this module.
1022 =head1 COPYRIGHT & LICENSE
1024 Copyright 2006 Uri Guttman, all rights reserved.
1026 This program is free software; you can redistribute it and/or modify it
1027 under the same terms as Perl itself.
1032 find templates and tests
1040 delete_templates test
1048 slurp dependency in makefile.pl