#!/usr/bin/perl

use strict ;
use warnings ;
use lib '../lib' ;

use File::Slurp ;

=head1 Template::Simple Cookbook

This cookbook contains examples of idioms and best practices when
using the Template::Simple module. It will illustrate all the the
features of this module and show various combinations of code to get
the job done. Send any requests for more examples to
E<lt>template@stemsystems.comE<gt>. Read the source code to see the
working examples or you can run this script to see all the
output. Each example has its title printed and rendered templates are
printed with a KEY: prefix and delimited with [].

By combining these techniques you can create and built complex
template applications that can do almost any task other templaters can
do. You will be able to share more code logic and templates as they
are totally isolated and independent from each other.

=head2 Use Scalar References

When passing text either as templates or in data tree elements, it is
generally faster to use scalar references than plain scalars. T::S can
accept text either way so you choose the style you like best. Most of
the examples here will use scalar references. Note that passing a
scalar reference to the new() constructor as the template will force
that to be a template and not a template name so no lookup will
occur. T::S always treats all text values as read only and never
modifies incoming data.

=cut

use Template::Simple ;
my $ts = Template::Simple->new() ;
my $template ;


=head1 Token Expansion

The simplest use of templates is replacing single tokens with
values. This is vry similar to interpolation of scalar variables in a
double quoted string. The difference is that the template text can
come from outside the program whereas double quoted strings must be in
the code (eval STRING doesn't count).

To replace tokens all you need is a template with token markups
(e.g. C<[% foo %]>) and a hash with those tokens as keys and the
values with which to replace them. Remember the top level template is
treated as an unnamed chunk so you can pass a hash reference to
render.

=cut

print "\n******************\nToken Expansion\n******************\n\n" ;

$template = <<TMPL ;
This [% token %] will be replaced as will [%foo%] and [% bar %]
TMPL

my $token_expansion = $ts->render( $template,
	{
	token	=> 'markup',
	foo	=> 'this',
	bar	=> 'so will this',
	}
) ;

print "TOKEN EXPANSION: [${$token_expansion}]\n" ;

=head1 Token Deletion

Sometimes you want to delete a token and not replace it with text. All
you need to do is use the null string for its data. Altenatively if
you are rendering a chunk with a hash (see below for more examples)
you can just not have any data for the token and it will also be
deleted. Both styles are shown in this example.

=cut

print "\n******************\nToken Deletion\n******************\n\n" ;

$template = <<TMPL ;
This [% token %]will be deleted as will [%foo%]
TMPL

my $token_deletion = $ts->render( $template,
	{
	token	=> '',
	}
) ;

print "TOKEN DELETION: [${$token_deletion}]\n" ;


=head1 Named Templates

You can pass a template directly to the C<render> method or pass in
its name. A named template will be searched for in the object cache
and then in the C<template_paths> directories. Templates can be loaded
into the cache with in the new() call or added later with the
C<add_templates> method.

=cut

print "\n******************\nNamed Templates\n******************\n\n" ;

$ts = Template::Simple->new(
	templates	=> {
		foo	=> <<FOO,
We have some foo text here with [% data %]
FOO
	}
) ;

my $foo_template = $ts->render( 'foo', { data => 'lots of foo' } ) ;

$ts->add_templates( { bar => <<BAR } ) ;
We have some bar text here with [% data %]
BAR

my $bar_template = $ts->render( 'bar', { data => 'some bar' } ) ;

print "FOO TEMPLATE: [${$foo_template}]\n" ;
print "BAR TEMPLATE: [${$bar_template}]\n" ;

=head1 Include Expansion

You can build up templates by including other templates. This allows a
template to be reused and shared by other templates. What makes this
even better, is that by passing different data to the included
templates in different renderings, you can get different results. If
the logic was embedded in the template you can't change the rendering
as easily. You include a template by using the C<[%include name%]>
markup. The name is used to locate a template by name and its text
replaces the markup. This example shows a single include in the top
level template.

=cut

print "\n******************\nInclude Expansion\n******************\n\n" ;

$ts = Template::Simple->new(
	templates	=> {
		top	=> <<TOP,
This top level template includes this <<[% include other %]>>text
TOP
		other	=> <<OTHER,
This is the included text
OTHER
} ) ;

my $include_template = $ts->render( 'top', {} ) ;

print "INCLUDE TEMPLATE: [${$include_template}]\n" ;

=head1 Template Paths

You can search for templates in files with the C<search_dirs> option
to the constructor. If a named template is not found in the object
cache it will be searched for in the directories listed in the
C<search_dirs> option. If it is found there, it will be loaded into
the object cache so future uses of it by name will be faster. The
default value of C<search_dirs> option is C<templates>. Templates must
have a suffix of C<.tmpl>. This example makes a directory called
'templates' and a template file named C<foo.tmpl>. The second example
makes a directory called C<cookbook> and puts a template in there and
sets. Note that the option value must be an array reference.

=cut

print "\n******************\nSearch Dirs\n******************\n\n" ;

my $tmpl_dir = 'templates' ;
mkdir $tmpl_dir ;
write_file( "$tmpl_dir/foo.tmpl", <<FOO ) ;
This template was loaded from the dir [%dir%]
FOO

$ts = Template::Simple->new() ;
my $foo_file_template = $ts->render( 'foo', { dir => 'templates' } ) ;

print "FOO FILE TEMPLATE: [${$foo_file_template}]\n" ;

unlink "$tmpl_dir/foo.tmpl" ;
rmdir $tmpl_dir ;

######

my $cook_dir = 'cookbook' ;
mkdir $cook_dir ;
write_file( "$cook_dir/bar.tmpl", <<BAR ) ;
This template was loaded from the $cook_dir [%dir%]
BAR

$ts = Template::Simple->new( search_dirs => [$cook_dir] ) ;
my $bar_file_template = $ts->render( 'bar', { dir => 'directory' } ) ;

print "BAR FILE TEMPLATE: [${$bar_file_template}]\n" ;

unlink "$cook_dir/bar.tmpl" ;
rmdir $cook_dir ;

=head1 Named Chunk Expansion

The core markup in T::S is called a chunk. It is delimited by paired
C<start> and C<end> markups and the text in between them is the
chunk. Any chunk can have multiple chunks inside it and they are named
for the name in the C<start> and C<end> markups. That name is used to
match the chunk with the data passed to render. This example uses the
top level template (which is always an unnamed chunk) which contains a
nested chunk which has a name. The data passed in is a hash reference
which has a key with the chunk name and its value is another hash
reference. So the nested chunk match up to the nested hashes.

=cut

print "\n******************\nNested Chunk Expansion\n******************\n\n" ;

$ts = Template::Simple->new(
	templates	=> {
		top	=> <<TOP,
This top level template includes this <<[% include nested %]>> chunk
TOP
		nested	=> <<NESTED,
[%START nested %]This included template just has a [% token %] and another [% one %][%END nested %]
NESTED
	}
) ;

my $nested_template = $ts->render( 'top',
	{
	nested => {
		token	=> 'nested value',
		one	=> 'value from the data',
	}
} ) ;

print "NESTED TEMPLATE: [${$nested_template}]\n" ;

=head2 Boolean Chunk

The simplest template decision is when you want to show some text or
nothing.  This is done with an empty hash reference or a null string
value in the data tree. The empty hash reference will cause the text
to be kept as is with all markups removed (replaced by the null
string). A null string (or a reference to one) will cause the text
chunk to be deleted.

=cut

print "\n******************\nBoolean Text\n******************\n\n" ;

$template = \<<TMPL ;
[% START boolean %]This is text to be left or deleted[% END boolean %]
TMPL

my $boolean_kept = $ts->render( $template, { boolean => {} } ) ;
my $deleted = $ts->render( $template, { default => \'' } ) ;

print "KEPT: [${$boolean_kept}]\n" ;
print "DELETED: [${$deleted}]\n" ;

=head2 Default vs. Overwrite Text

The next step up from boolean text is overwriting a default text with
another when rendering. This is done with an empty hash reference or a
scalar value for the chunk in the data tree. The empty hash reference
will cause the default text to be kept as is with all markups removed
(replaced by the null string). A scalar value (or a scalar reference)
will cause the complete text chunk to be replaced by that value.

=cut

print "\n******************\nDefault vs. Overwrite Text\n******************\n\n" ;

$template = \<<TMPL ;
[% START default %]This is text to be left or replaced[% END default %]
TMPL

my $default_kept = $ts->render( $template, { default => {} } ) ;
my $overwrite = $ts->render( $template, { default => \<<OVER } ) ;
This text will overwrite the default text
OVER

print "DEFAULT: [${$default_kept}]\n" ;
print "OVERWRITE: [${$overwrite}]\n" ;

=head2 Conditional Text

Instead of having the overwrite text in the data tree, it is useful to
have it in the template itself. This is a conditional where one text
or the other is rendered. This is done by wrapping each text in its
own chunk with unique names. The data tree can show either one by
passing an empty hash reference for that data and a null string for
the other one. Also you can just not have a value for the text not to
be rendered and that will also delete it. Both styles are shown here.

=cut

print "\n******************\nConditional Text\n******************\n\n" ;

$template = \<<TMPL ;
[% START yes_text %]This text shown when yes[% END yes_text %]
[% START no_text %]This text shown when no[% END no_text %]
TMPL

my $yes_shown = $ts->render( $template, { yes_text => {} } ) ;
my $no_shown = $ts->render( $template, {
	yes_text => '',
	no_text => {}
} ) ;

print "YES: [${$yes_shown}]\n" ;
print "NO: [${$no_shown}]\n" ;

=head1 List Chunk Expansion

T::S has no list markup because of the unique way it handles data
during rendering. When an array reference is matched to a chunk, the
array is iterated and the chunk is then rendered with each element of
the array. This list of rendered texts is concatenated and replaces
the original chunk in the template. The data and the logic that
creates the data controls when a template chunk is repeated. This
example shows the top level (unnamed) template being rendered with an
array of hashes. Each hash renders the chunk one time. Note that the
different results you get based on the different hashes in the array.

=cut

print "\n******************\nList Chunk Expansion\n******************\n\n" ;

$ts = Template::Simple->new(
	templates => {
		top_array => <<TOP_ARRAY,

This is the [%count%] chunk.
[%start maybe%]This line may be shown[%end maybe%]
This is the end of the chunk line
TOP_ARRAY
} ) ;

my $top_array = $ts->render( 'top_array', [
	{
		count	=> 'first',
		maybe	=> {},
	},
	{
		count	=> 'second',
	},
	{
		count	=> 'third',
		maybe	=> {},
	},
] ) ;

print "TOP_ARRAY: [${$top_array}]\n" ;


=head1 Separated List Expansion

A majorly used variation of data lists are list with a separator but
not one after the last element. This can be done easily with T::S and
here are two techniques. The first one uses a token for the separator
in the chunk and passes in a hash with the delimiter string set in all
but the last element. This requires the code logic to know and set the
delimiter. The other solution lets the template set the delimiter by
enclosing it in a chunk of its own and passing an empty hash ref for
the places to keep it and nothing for the last element. Both examples
use the same sub to do this work for you and all you need to do is
pass it the token for the main value and the seperator key and
optionally its value. You can easily make a variation that puts the
separator before the element and delete it from the first element.  If
your chunk has more tokens or nested chunks, this sub could be
generalized to modify a list of hashes instead of generating one.

=cut

print "\n******************\nSeparated List Expansion\n******************\n\n" ;


sub make_separated_data {
 	my( $token, $data, $delim_key, $delim ) = @_ ;

# make the delim set from the template (in a chunk) if not passed in
# an empty hash ref keeps the chunk text as is.

	$delim ||= {} ;

	my @list = map +{ $token => $_, $delim_key => $delim, }, @{$data} ;

# remove the separator from the last element

	delete $list[-1]{$delim_key} ;

	return \@list ;
}

my @data = qw( one two three four ) ;

$ts = Template::Simple->new(
	templates	=> {
		sep_tmpl	=> <<SEP_TMPL,
Number [%count%][%sep%]
SEP_TMPL
		sep_data	=> <<SEP_DATA,
Number [%count%][%start sep%],[%end sep%]
SEP_DATA
} ) ;

my $sep_tmpl = $ts->render( 'sep_tmpl',
	make_separated_data( 'count', \@data, 'sep', '--' ) ) ;

my $sep_data = $ts->render( 'sep_data',
	make_separated_data( 'count', \@data, 'sep', {} ) ) ;

print "SEP_DATA: [${$sep_data}]\n" ;
print "SEP_DATA: [${$sep_data}]\n" ;

exit ;