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