1NAME
2 Tenjin - Fast templating engine with support for embedded Perl.
3
4VERSION
5 version 0.070001
6
7SYNOPSIS
8 use Tenjin;
9
10 $Tenjin::USE_STRICT = 1; # use strict in the embedded Perl inside
11 # your templates. Recommended, but not used
12 # by default.
13
14 $Tenjin::ENCODING = "UTF-8"; # set the encoding of your template files
15 # to UTF-8. This is the default encoding used
16 # so there's no need to do this if your
17 # templates really are UTF-8.
18
19 my $engine = Tenjin->new(\%options);
20 my $context = { title => 'Tenjin Example', items => [qw/AAA BBB CCC/] };
21 my $filename = 'file.html';
22 my $output = $engine->render($filename, $context);
23 print $output;
24
25DESCRIPTION
26 Tenjin is a very fast and full-featured templating engine, implemented
27 in several programming languages, among them Perl.
28
29 The Perl version of Tenjin supports embedded Perl code, nestable layout
30 template, inclusion of other templates inside a template, capturing
31 parts of or the entire template output, file and memory caching,
32 template arguments and preprocessing.
33
34 The original version of Tenjin is developed by Makoto Kuwata. This CPAN
35 version is developed by Ido Perlmuter and differs from the original in a
36 few key aspects:
37
38 * Code is entirely revised, packages are separated into modules, with
39 a smaller number of packages than the original version. In
40 particular, the Tenjin::Engine module no longer exists, and is now
41 instead just the Tenjin module (i.e. this one).
42
43 * Support for rendering templates from non-file sources (such as a
44 database) is added.
45
46 * Ability to set the encoding of your templates is added (Tenjin will
47 decode template files according to this encoding; by default, Tenjin
48 will decode
49
50 * HTML is encoded and decoded using the HTML::Entities module, instead
51 of internally.
52
53 * The "pltenjin" script is not provided, at least for now.
54
55 To make it clear, the CPAN version of Tenjin might find itself diverting
56 a bit in the future from the original Tenjin's roadmap. Although my aim
57 is to be as compatible as possible (and this version is always updated
58 with features and changes from the original), I cannot guarantee it (but
59 I'll do my best). Please note that version 0.05 (and above) of this
60 module is NOT backwards compatible with previous versions.
61
62 A NOTE ABOUT ENCODING
63 When Tenjin opens template files, it will automatically decode their
64 contents according to the selected encoding (UTF-8 by default), so make
65 sure your template files are properly encoded. Tenjin also writes cache
66 files of compiled template structure. These will be automatically
67 encoded according to the selected encoding.
68
69 When it comes to UTF-8, it might interest you to know how Tenjin
70 behaves:
71
72 1. "UTF-8" is the default encoding used. If for some reason, either
73 before running "Tenjin->new()" or during, you provide an alternate
74 spelling (such as "utf8" or "UTF8"), Tenjin will convert it to UTF-8.
75 2. When reading files, Tenjin uses "<:encoding(UTF-8)", while when
76 writing files, Tenjin uses ">:utf8", as recommended by this article
77 <https://secure.wikimedia.org/wikibooks/en/w/index.php?title=Perl_Progra
78 mming/Unicode_UTF-8&oldid=2020796>.
79
80METHODS
81 new( \%options )
82 This creates a new instant of Tenjin. "\%options" is a hash-ref
83 containing Tenjin's configuration options:
84
85 * path - Array-ref of filesystem paths where templates will be
86 searched
87
88 * prefix - A string that will be automatically prepended to template
89 names when searching for them in the path. Empty by default.
90
91 * postfix - The default extension to be automtically appended to
92 template names when searching for them in the path. Don't forget to
93 include the dot, such as '.html'. Empty by default.
94
95 * cache - If set to 1 (the default), compiled templates will be cached
96 on the filesystem (this means the template's code will be cached,
97 not the completed rendered output).
98
99 * preprocess - Enable template preprocessing (turned off by default).
100 Only use if you're actually using any preprocessed Perl code in your
101 templates.
102
103 * layout - Name of a layout template that can be optionally used. If
104 set, templates will be automatically inserted into the layout
105 template, in the location where you use "[== $_content ==]".
106
107 * strict - Another way to make Tenjin use strict on embedded Perl code
108 (turned off by default).
109
110 * encoding - Another way to set the encoding of your template files
111 (set to "UTF-8" by default).
112
113 render( $tmpl_name, [\%_context, $use_layout] )
114 Renders a template whose name is identified by $tmpl_name. Remember that
115 a prefix and a postfix might be added if they where set when creating
116 the Tenjin instance.
117
118 $_context is a hash-ref containing the variables that will be available
119 for usage inside the templates. So, for example, if your "\%_context" is
120 "{ message => 'Hi there' }", then you can use $message inside your
121 templates.
122
123 $use_layout is a flag denoting whether or not to render this template
124 into a layout template (when doing so, the template will be rendered,
125 then the rendered output will be added to the context hash-ref as
126 '_content', and finally the layout template will be rendered with the
127 revised context and returned.
128
129 If $use_layout is 1 (which is the default in case it is undefined), then
130 Tenjin will use the layout template that was set when creating the
131 Tenjin instance (via the 'layout' configuration option). If you want to
132 use a different layout template (or if you haven't defined a layout
133 template when creating the Tenjin instance), then you must add the
134 layout template's name to the context as '_layout'. You can also just
135 pass the layout template's name as $use_layout, but
136 "$_context->{_layout}" has precedence.
137
138 If $use_layout is 0, then a layout template will not be used, even if
139 "$_context->{_layout}" is defined.
140
141 Note that you can nest layout templates as much as you like, but the
142 only way to do so is by setting the layout template for each template in
143 the nesting chain with "$_context->{_layout}".
144
145 Please note that by default file templates are cached on disk (with a
146 '.cache') extension. Tenjin automatically deprecates these cache files
147 every 10 seconds. If you find this value is too low, you can override
148 the $Tenjin::TIMESTAMP_INTERVAL variable with your preferred value.
149
150 register_template( $template_name, $template )
151 Receives the name of a template and its Tenjin::Template object and
152 stores it in memory for usage by the engine. This is useful if you need
153 to use templates that are not stored on the file system, for example
154 from a database.
155
156 Note, however, that you need to pass a template object who's already
157 been converted and compiled into Perl code, so if you have a template
158 with a certain name and certain text, these are the steps you will need
159 to perform:
160
161 # create a Tenjin instance
162 my $tenjin = Tenjin->new(\%options);
163
164 # create an empty template object
165 my $template = Tenjin::Template->new();
166
167 # compile template content into Perl code
168 $template->convert($tmpl_content);
169 $template->compile();
170
171 # register the template with the Tenjin instance
172 $tenjin->register_template($tmpl_name, $template);
173
174INTERNAL METHODS
175 get_template( $template_name, $_context )
176 Receives the name of a template and the context object and tries to find
177 that template in the engine's memory. If it's not there, it will try to
178 find it in the file system (the cache file might be loaded, if present).
179 Returns the template's Tenjin::Template object.
180
181 to_filename( $template_name )
182 Receives a template name and returns the proper file name to be searched
183 in the file system, which will only be different than $template_name if
184 it begins with ':', in which case the prefix and postfix configuration
185 options will be appended and prepended to the template name (minus the
186 ':'), respectively.
187
188 find_template_file( $filename )
189 Receives a template filename and searches for it in the path defined in
190 the configuration options (or, if a path was not set, in the current
191 working directory). Returns the absolute path to the file.
192
193 read_template_file( $template, $filename, $_context )
194 Receives a template object and its absolute file path and reads that
195 file. If preprocessing is on, preprocessing will take place using the
196 provided context object.
197
198 cachename( $filename )
199 Receives a template filename and returns its standard cache filename
200 (which will simply be $filename with '.cache' appended to it.
201
202 store_cachefile( $cachename, $template )
203 Receives the name of a template cache file and the corrasponding
204 template object, and creates the cache file on disk.
205
206 load_cachefile( $cachename, $template )
207 Receives the name of a template cache file and the corrasponding
208 template object, reads the cache file and stores it in the template
209 object (as 'script').
210
211 create_template( $filename, $_context )
212 Receives an absolute path to a template file and the context object,
213 reads the file, processes it (which may involve loading the template's
214 cache file or creating the template's cache file), compiles it and
215 returns the template object.
216
217SEE ALSO
218 The original Tenjin website is located at
219 <http://www.kuwata-lab.com/tenjin/>. In there check out
220 <http://www.kuwata-lab.com/tenjin/pltenjin-users-guide.html> for
221 detailed usage guide,
222 <http://www.kuwata-lab.com/tenjin/pltenjin-examples.html> for examples,
223 and <http://www.kuwata-lab.com/tenjin/pltenjin-faq.html> for frequently
224 asked questions.
225
226 Note that the Perl version of Tenjin is refered to as plTenjin on the
227 Tenjin website, and that, as opposed to this module, the website
228 suggests using a .plhtml extension for the templates instead of .html
229 (this is entirely your choice).
230
231 Tenjin::Template, Catalyst::View::Tenjin, Dancer::Template::Tenjin.
232
233CHANGES
234 Version 0.05 of this module broke backwards compatibility with previous
235 versions. In particular, the Tenjin::Engine module does not exist any
236 more and is instead integrated into this one. Templates are also
237 rendered entirely different (as per changes in the original tenjin)
238 which provides much faster rendering.
239
240 Upon upgrading to versions 0.05 and above, you MUST perform the
241 following changes for your applications (or, if you're using Catalyst,
242 you must also upgrade Catalyst::View::Tenjin):
243
244 * "use Tenjin" as your normally would, but to get an instance of
245 Tenjin you must call "Tenjin->new()" instead of the old method of
246 calling "Tenjin::Engine->new()".
247
248 * Remove all your templates cache files (they are the '.cache' files
249 in your template directories), they are not compatible with the new
250 templates structure and WILL cause your application to fail if
251 present.
252
253 Version 0.06 (this version) restored the layout template feature which
254 was accidentaly missing in version 0.05, and the ability to call the
255 utility methods of Tenjin::Util natively inside templates. You will want
256 to remove your templates' .cache files when upgrading to 0.6 too.
257
258AUTHOR
259 The CPAN version of Tenjin was forked by Ido Perlmuter <ido at
260 ido50.net> from version 0.0.2 of the original plTenjin, which is
261 developed by Makoto Kuwata at <http://www.kuwata-lab.com/tenjin/>.
262
263 Development of Tenjin is done with github at
264 <http://github.com/ido50/Tenjin>.
265
266ACKNOWLEDGEMENTS
267 I would like to thank the following people for their contributions:
268
269 * Makoto Kuwata
270
271 The original developer of Tenjin.
272
273 * John Beppu <beppu at cpan.org>
274
275 For introducing me to Tenjin and helping me understand the way it's
276 designed.
277
278 * Pedro Melo <melo at cpan.org>
279
280 For helping me understand the logic behind some of the original
281 Tenjin aspects and helping me fix bugs and create tests.
282
283BUGS
284 Please report any bugs or feature requests to "bug-tenjin at
285 rt.cpan.org", or through the web interface at
286 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Tenjin>. I will be
287 notified, and then you'll automatically be notified of progress on your
288 bug as I make changes.
289
290SUPPORT
291 You can find documentation for this module with the perldoc command.
292
293 perldoc Tenjin
294
295 You can also look for information at:
296
297 * RT: CPAN's request tracker
298
299 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Tenjin>
300
301 * AnnoCPAN: Annotated CPAN documentation
302
303 <http://annocpan.org/dist/Tenjin>
304
305 * CPAN Ratings
306
307 <http://cpanratings.perl.org/d/Tenjin>
308
309 * Search CPAN
310
311 <http://search.cpan.org/dist/Tenjin/>
312
313LICENSE AND COPYRIGHT
314 Tenjin is licensed under the MIT license.
315
316 Copyright (c) 2007-2011 the aforementioned authors.
317
318 Permission is hereby granted, free of charge, to any person obtaining
319 a copy of this software and associated documentation files (the
320 "Software"), to deal in the Software without restriction, including
321 without limitation the rights to use, copy, modify, merge, publish,
322 distribute, sublicense, and/or sell copies of the Software, and to
323 permit persons to whom the Software is furnished to do so, subject to
324 the following conditions:
325
326 The above copyright notice and this permission notice shall be
327 included in all copies or substantial portions of the Software.
328
329 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
330 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
331 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
332 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
333 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
334 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
335 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
336
337 See http://dev.perl.org/licenses/ for more information.
338
339