1Jemplate(3) User Contributed Perl Documentation Jemplate(3)
2
6 Jemplate - JavaScript Templating with Template Toolkit
7
9 var data = Ajax.get('url/data.json');
10 var elem = document.getElementById('some-div');
11 elem.innerHTML = Jemplate.process('my-template.html', data);
12 or:
14 var data = Ajax.get('url/data.json');
16 var elem = document.getElementById('some-div');
17 Jemplate.process('my-template.html', data, elem);
18 or simply:
20 Jemplate.process('my-template.html', 'url/data.json', '#some-div');
22 or, with jQuery.js:
24 jQuery.getJSON("url/data.json", function(data) {
26 Jemplate.process('my-template.html', data, '#some-div');
27 });
28
30 Jemplate is a templating framework for JavaScript that is built over
31 Perl's Template Toolkit (TT2).
32 Jemplate parses TT2 templates using the TT2 Perl framework, but with a
34 twist. Instead of compiling the templates into Perl code, it compiles
35 them into JavaScript.
36 Jemplate then provides a JavaScript runtime module for processing the
38 template code. Presto, we have full featured JavaScript templating
39 language!
40 Combined with JSON and xmlHttpRequest, Jemplate provides a really
42 simple and powerful way to do Ajax stuff.
43
45 Jemplate comes with a command line tool call "jemplate" that you use to
46 precompile your templates into a JavaScript file. For example if you
47 have a template directory called "templates" that contains:
48 > ls templates/
50 body.html
51 footer.html
52 header.html
53 You might run this command:
55 > jemplate --compile template/* > js/jemplates.js
57 This will compile all the templates into one JavaScript file.
59 You also need to generate the Jemplate runtime.
61 > jemplate --runtime > js/Jemplate.js
63 Now all you need to do is include these two files in your HTML:
65 <script src="js/Jemplate.js" type="text/javascript"></script>
67 <script src="js/jemplates.js" type="text/javascript"></script>
68 Now you have Jemplate support for these templates in your HTML
70 document.
71
73 The Jemplate.js JavaScript runtime module has the following API method:
74 Jemplate.process(template-name, data, target);
76 The "template-name" is a string like 'body.html' that is the name
77 of the top level template that you wish to process.
78 The optional "data" specififies the data object to be used by the
80 templates. It can be an object, a function or a url. If it is an
81 object, it is used directly. If it is a function, the function is
82 called and the returned object is used. If it is a url, an
83 asynchronous <Ajax.get> is performed. The result is expected to be
84 a JSON string, which gets turned into an object.
85 The optional "target" can be an HTMLElement reference, a function
87 or a string beginning with a "#" char. If the target is omitted,
88 the template result is returned. If it is a function, the function
89 is called with the result. If it is a string, the string is used as
90 an id to find an HTMLElement.
91 If an HTMLElement is used (by id or directly) then the innerHTML
93 property is set to the template processing result.
94 The Jemplate.pm Perl module has the following public class methods,
96 although you won't likely need to use them directly. Normally, you just
97 use the "jemplate" command line tool.
98 Jemplate->compile_template_files(@template_file_paths);
100 Take a list of template file paths and compile them into a module
101 of functions. Returns the text of the module.
102 Jemplate->compile_template_content($content, $template_name);
104 Compile one template whose content is in memory. You must provide a
105 unique template name. Returns the JavaScript text result of the
106 compilation.
107 Jemplate->compile_module($module_path, \@template_file_paths);
109 Similar to `compile_template_files`, but prints to result to the
110 $module_path. Returns 1 if successful, undef if error.
111 Jemplate->compile_module_cached($module_path, \@template_file_paths);
113 Similar to `compile_module`, but only compiles if one of the
114 templates is newer than the module. Returns 1 if sucessful compile,
115 0 if no compile due to cache, undef if error.
116
118 Jemplate comes with builtin Ajax and JSON support.
119 Ajax.get(url, [callback]);
121 Does a GET operation to the url.
122 If a callback is provided, the operation is asynchronous, and the
124 data is passed to the callback. Otherwise, the operation is
125 synchronous and the data is returned.
126 Ajax.post(url, data, [callback]);
128 Does a POST operation to the url.
129 Same callback rules as "get" apply.
131 JSON.stringify(object);
133 Return the JSON serialization of an object.
134 JSON.parse(jsonString);
136 Turns a JSON string into an object and returns the object.
137
139 The goal of Jemplate is to support all of the Template Toolkit features
140 that can possibly be supported.
141 Jemplate now supports almost all the TT directives, including:
143 * Plain text
145 * [% [GET] variable %]
146 * [% CALL variable %]
147 * [% [SET] variable = value %]
148 * [% DEFAULT variable = value ... %]
149 * [% INCLUDE [arguments] %]
150 * [% PROCESS [arguments] %]
151 * [% BLOCK name %]
152 * [% FILTER filter %] text... [% END %]
153 * [% JAVASCRIPT %] code... [% END %]
154 * [% WRAPPER template [variable = value ...] %]
155 * [% IF condition %]
156 * [% ELSIF condition %]
157 * [% ELSE %]
158 * [% SWITCH variable %]
159 * [% CASE [{value|DEFAULT}] %]
160 * [% FOR x = y %]
161 * [% WHILE expression %]
162 * [% RETURN %]
163 * [% THROW type message %]
164 * [% STOP %]
165 * [% NEXT %]
166 * [% LAST %]
167 * [% CLEAR %]
168 * [%# this is a comment %]
169 ALL of the string virtual functions are supported.
171 ALL of the array virtual functions are supported:
173 ALL of the hash virtual functions are supported (except for import):
175 MANY of the standard filters are implemented.
177 The remaining features will be added very soon. See the DESIGN document
179 in the distro for a list of all features and their progress.
180
182 Tested successfully in:
183 * Firefox Mac/Win32/Linux
185 * IE 6.0
186 * Safari
187 * Opera
188 * Konqueror
189 All tests run 100% successful in the above browsers.
191
193 The bleeding edge code is available via Subversion at
194 http://svn.jemplate.net/repo/trunk/
195 You can run the runtime tests directly from
197 http://svn.jemplate.net/repo/trunk/tests/run/index.html or from the
198 corresponding CPAN or JSAN directories.
199 Jemplate development is being discussed at
201 irc://irc.freenode.net/#jemplate
202 If you want a committer bit, just ask ingy on the irc channel.
204
206 This module is only possible because of Andy Wardley's mighty Template
207 Toolkit. Thanks Andy. I will gladly give you half of any beers I
208 receive for this work. (As long as you are in the same room when I'm
209 drinking them ;)
210
212 Ingy dA~Xt Net <ingy@cpan.org>
213 (Note: I had to list myself first so that this line would go into
215 META.yml)
216 Jemplate is truly a community authored project:
218 Ingy dA~Xt Net <ingy@cpan.org>
220 Tatsuhiko Miyagawa <miyagawa@bulknews.net>
222 Yann Kerherve <yannk@cpan.org>
224 David Davis <xantus@xantus.org>
226 Cory Bennett <coryb@corybennett.org>
228 Cees Hek <ceeshek@gmail.com>
230 Christian Hansen
232 David A. Coffey <dacoffey@cogsmith.com>
234 Robert Krimen <robertkrimen@gmail.com>
236
238 Copyright (c) 2006-2008. Ingy dA~Xt Net.
239 This program is free software; you can redistribute it and/or modify it
241 under the same terms as Perl itself.
242 See <http://www.perl.com/perl/misc/Artistic.html>
244perl v5.12.0 2010-05-02 Jemplate(3)