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