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