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