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