1NAME
2    Template::Toolkit::Simple - A Simple Interface to Template Toolkit
3
4SYNOPSIS
5          use Template::Toolkit::Simple;
6
7          print tt
8              ->path(['./', 'template/'])
9              ->data('values.yaml')
10              ->post_chomp
11              ->render('foo.tt');
12
13    or from the command line:
14
15          tt-render --path=./:template/ --data=values.yaml --post-chomp foo.tt
16
17DESCRIPTION
18    Template Toolkit is the best Perl template framework. The only problem
19    with it is that using it for simple stuff is a little bit cumbersome.
20    Also there is no good utility for using it from the command line.
21
22    This module is a simple wrapper around Template Toolkit. It exports a
23    function called "tt" which returns a new Template::Toolkit::Simple
24    object. The object supports method calls for setting all the Template
25    Toolkit options.
26
27    This module also installs a program called "tt-render" which you can use
28    from the command line to render templates with all the power of the Perl
29    object. All of the object methods become command line arguments in the
30    command line version.
31
32COMMAND LINE USAGE
33    This command renders the named file and prints the output to STDOUT. If
34    an error occurs, it is printed to STDERR.
35
36        tt-render [template-options] file-name
37
38TEMPLATE PATH
39    When using Template::Toolkit::Simple or "tt-render", the most common
40    parameters you will use are the main template file name and the
41    directory of supporting templates. As a convenience, you can specify
42    these together.
43
44    This:
45
46        tt->render('foo//bar/baz.tt');
47        > tt-render foo//bar/baz.tt  # command line version
48
49    is the same as:
50
51        tt->include_path('foo/')->render('bar/baz.tt');
52        > tt-render --include_path=foo/ bar/baz.tt  # command line version
53
54    Just use a double slash to separate the path from the template. This is
55    extra handy on the command line, because (at least in Bash) tab
56    completion still works after you specify the '//'.
57
58EXPORTED SUBROUTINES
59    tt  Simply returns a new Template::Toolkit::Simple object. This is
60        Simple sugar for:
61
62            Template::Toolkit::Simple->new();
63
64        It takes no parameters.
65
66METHODS
67    This section describes the methods that are not option setting methods.
68    Those methods are described below.
69
70    new()
71        Return a new Template::Toolkit::Simple object. Takes no parameters.
72
73    render($template, $data);
74        This is the method that actually renders the template. It is similar
75        to the Template Toolkit "process" method, except that it actually
76        returns the template result as a string. It returns undef if an
77        error occurs.
78
79        The $data field is optional and can be set with the "data" method.
80
81        If you need more control, see the process command below:
82
83    process($template, $data, $output, %options);
84        This command is simply a proxy to the Template Toolkit "process"
85        command. All the parameters you give it are passed to the real
86        "process" command and the result is returned. See Template for more
87        information.
88
89    output($filepath)
90        Specify a filepath to print the template result to.
91
92    error()
93        This method is a proxy to the Template Toolkit "error" method. It
94        returns the error message if there was an error.
95
96OPTION METHODS
97    All of the Template Toolkit options are available as methods to
98    Template::Toolkit::Simple objects, and also as command line options to
99    the "tt- render" command.
100
101    For example, the "POST_CHOMP" options is available in the following
102    ways:
103
104        tt->post_chomp      # turn POST_CHOMP on
105        tt->post_chomp(1)   # turn POST_CHOMP on
106        tt->post_chomp(0)   # turn POST_CHOMP off
107
108        --post_chomp        # turn POST_CHOMP on
109        --post-chomp        # same. use - instead of _
110        --post_chomp=1      # turn POST_CHOMP on
111        --post_chomp=0      # turn POST_CHOMP off
112
113    If the method functionality is not explained below, please refer to
114    Template.
115
116    "config($file_name || $hash)"
117        If you have a common set of Template Toolkit options stored in a
118        file, you can use this method to read and parse the file, and set
119        the appropriate options.
120
121        The currently supported file formats are YAML, JSON and XML. The
122        format is determined by the file extension, so use the appropriate
123        one. Note that XML::Simple is used to parse XML files and JSON::XS
124        is used to parse JSON files.
125
126    "data($file_name || $hash)"
127        Most templates use a hash object of data to access values while
128        rendering. You can specify this data in a file or with a hash
129        reference.
130
131        The currently supported file formats are YAML, JSON and XML. The
132        format is determined by the file extension, so use the appropriate
133        one. Note the XML::Simple is used to parse XML files.
134
135    "include_path($template_directories)"
136        Default is undef
137
138        This method allows you to specify the directories that are searched
139        to find templates. You can specify this as a string containing a
140        single directory, an array ref of strings containing directory
141        names, or as a string containing multiple directories separated by
142        ':'.
143
144    "path()"
145        Default is undef
146
147        This is a shorter name for "include_path". It does the exact same
148        thing.
149
150    "start_tag()"
151        Default is '[%'
152
153    "end_tag()"
154        Default is '%]'
155
156    "tag_style()"
157        Default is 'template'
158
159    "pre_chomp()"
160        Default is 0
161
162    "post_chomp()"
163        Default is 0
164
165    "trim()"
166        Default is 0
167
168    "interpolate()"
169        Default is 0
170
171    "anycase()"
172        Default is 0
173
174    "delimiter()"
175        Default is ':'
176
177    "absolute()"
178        Default is 0
179
180    "relative()"
181        Default is 0
182
183    "strict()"
184        Default is 0
185
186    "default()"
187        Default is undef
188
189    "blocks()"
190        Default is undef
191
192    "auto_reset()"
193        Default is 1
194
195    "recursion()"
196        Default is 0
197
198    "eval_perl()"
199        Default is 0
200
201    "pre_process()"
202        Default is undef
203
204    "post_process()"
205        Default is undef
206
207    "process_template()"
208        Default is undef
209
210        This is a proxy to the Template Toolkit PROCESS option. The
211        "process" method is used to actually process a template.
212
213    "error_template()"
214        Default is undef
215
216        This is a proxy to the Template Toolkit ERROR option. The "error()"
217        method returns the error message on a failure.
218
219    "debug()"
220        Default is 0
221
222    "cache_size()"
223        Default is undef
224
225    "compile_ext()"
226        Default is undef
227
228    "compile_dir()"
229        Default is undef
230
231    "encoding()"
232        Default is 'utf8'
233
234AUTHOR
235    Ingy döt Net <ingy@cpan.org>
236
237COPYRIGHT AND LICENSE
238    Copyright 2008-2014. Ingy döt Net.
239
240    This program is free software; you can redistribute it and/or modify it
241    under the same terms as Perl itself.
242
243    See <http://www.perl.com/perl/misc/Artistic.html>
244
245