<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Jemplate - JavaScript Templating with Template Toolkit</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@omen.apple.com" />
</head>
<body style="background-color: white">
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#howto">HOWTO</a></li>
<li><a href="#public_api">PUBLIC API</a></li>
<li><a href="#ajax_and_json_methods">AJAX AND JSON METHODS</a></li>
<li><a href="#current_support">CURRENT SUPPORT</a></li>
<li><a href="#browser_support">BROWSER SUPPORT</a></li>
<li><a href="#development">DEVELOPMENT</a></li>
<li><a href="#credit">CREDIT</a></li>
<li><a href="#authors">AUTHORS</a></li>
<li><a href="#copyright">COPYRIGHT</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<hr />
<h1><a name="name">NAME</a></h1>
<p>Jemplate - JavaScript Templating with Template Toolkit</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
var data = Ajax.get('url/data.json');
var elem = document.getElementById('some-div');
elem.innerHTML = Jemplate.process('my-template.html', data);</pre>
<p>or:</p>
<pre>
var data = Ajax.get('url/data.json');
var elem = document.getElementById('some-div');
Jemplate.process('my-template.html', data, elem);</pre>
<p>or simply:</p>
<pre>
Jemplate.process('my-template.html', 'url/data.json', '#some-div');</pre>
<p>or, with jQuery.js:</p>
<pre>
jQuery.getJSON("url/data.json", function(data) {
Jemplate.process('my-template.html', data, '#some-div');
});</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>Jemplate is a templating framework for JavaScript that is built over
Perl's Template Toolkit (TT2).</p>
<p>Jemplate parses TT2 templates using the TT2 Perl framework, but with a
twist. Instead of compiling the templates into Perl code, it compiles
them into JavaScript.</p>
<p>Jemplate then provides a JavaScript runtime module for processing
the template code. Presto, we have full featured JavaScript
templating language!</p>
<p>Combined with JSON and xmlHttpRequest, Jemplate provides a really simple
and powerful way to do Ajax stuff.</p>
<p>
</p>
<hr />
<h1><a name="howto">HOWTO</a></h1>
<p>Jemplate comes with a command line tool call <code>jemplate</code> that you use to
precompile your templates into a JavaScript file. For example if you have
a template directory called <code>templates</code> that contains:</p>
<pre>
> ls templates/
body.html
footer.html
header.html</pre>
<p>You might run this command:</p>
<pre>
> jemplate --compile template/* > js/jemplates.js</pre>
<p>This will compile all the templates into one JavaScript file.</p>
<p>You also need to generate the Jemplate runtime.</p>
<pre>
> jemplate --runtime > js/Jemplate.js</pre>
<p>Now all you need to do is include these two files in your HTML:</p>
<pre>
<script src="js/Jemplate.js" type="text/javascript"></script>
<script src="js/jemplates.js" type="text/javascript"></script></pre>
<p>Now you have Jemplate support for these templates in your HTML document.</p>
<p>
</p>
<hr />
<h1><a name="public_api">PUBLIC API</a></h1>
<p>The Jemplate.js JavaScript runtime module has the following API method:</p>
<dl>
<dt><strong><a name="item_process">Jemplate.process(template-name, data, target);</a></strong>
<dd>
<p>The <code>template-name</code> is a string like <code>'body.html'</code> that is the name of
the top level template that you wish to process.</p>
</dd>
<dd>
<p>The optional <code>data</code> specififies the data object to be used by the
templates. It can be an object, a function or a url. If it is an object,
it is used directly. If it is a function, the function is called and the
returned object is used. If it is a url, an asynchronous <Ajax.get> is
performed. The result is expected to be a JSON string, which gets turned
into an object.</p>
</dd>
<dd>
<p>The optional <code>target</code> can be an HTMLElement reference, a function or a
string beginning with a <code>#</code> char. If the target is omitted, the
template result is returned. If it is a function, the function is called
with the result. If it is a string, the string is used as an id to find
an HTMLElement.</p>
</dd>
<dd>
<p>If an HTMLElement is used (by id or directly) then the innerHTML
property is set to the template processing result.</p>
</dd>
</li>
</dl>
<p>The Jemplate.pm Perl module has the following public class methods,
although you won't likely need to use them directly. Normally, you just
use the <code>jemplate</code> command line tool.</p>
<dl>
<dt><strong><a name="item_compile_template_files">Jemplate->compile_template_files(@template_file_paths);</a></strong>
<dd>
<p>Take a list of template file paths and compile them into a module of
functions. Returns the text of the module.</p>
</dd>
</li>
<dt><strong><a name="item_compile_template_content">Jemplate->compile_template_content($content, $template_name);</a></strong>
<dd>
<p>Compile one template whose content is in memory. You must provide a
unique template name. Returns the JavaScript text result of the
compilation.</p>
</dd>
</li>
<dt><strong><a name="item_compile_module">Jemplate->compile_module($module_path, \@template_file_paths);</a></strong>
<dd>
<p>Similar to `compile_template_files`, but prints to result to the
$module_path. Returns 1 if successful, undef if error.</p>
</dd>
</li>
<dt><strong><a name="item_compile_module_cached">Jemplate->compile_module_cached($module_path, \@template_file_paths);</a></strong>
<dd>
<p>Similar to `compile_module`, but only compiles if one of the templates
is newer than the module. Returns 1 if sucessful compile, 0 if no
compile due to cache, undef if error.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="ajax_and_json_methods">AJAX AND JSON METHODS</a></h1>
<p>Jemplate comes with builtin Ajax and JSON support.</p>
<dl>
<dt><strong><a name="item_get">Ajax.get(url, [callback]);</a></strong>
<dd>
<p>Does a GET operation to the url.</p>
</dd>
<dd>
<p>If a callback is provided, the operation is asynchronous, and the data
is passed to the callback. Otherwise, the operation is synchronous and
the data is returned.</p>
</dd>
</li>
<dt><strong><a name="item_post">Ajax.post(url, data, [callback]);</a></strong>
<dd>
<p>Does a POST operation to the url.</p>
</dd>
<dd>
<p>Same callback rules as <a href="#item_get"><code>get</code></a> apply.</p>
</dd>
</li>
<dt><strong><a name="item_stringify">JSON.stringify(object);</a></strong>
<dd>
<p>Return the JSON serialization of an object.</p>
</dd>
</li>
<dt><strong><a name="item_parse">JSON.parse(jsonString);</a></strong>
<dd>
<p>Turns a JSON string into an object and returns the object.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="current_support">CURRENT SUPPORT</a></h1>
<p>The goal of Jemplate is to support all of the Template Toolkit features
that can possibly be supported.</p>
<p>Jemplate now supports almost all the TT directives, including:</p>
<pre>
* Plain text
* [% [GET] variable %]
* [% CALL variable %]
* [% [SET] variable = value %]
* [% DEFAULT variable = value ... %]
* [% INCLUDE [arguments] %]
* [% PROCESS [arguments] %]
* [% BLOCK name %]
* [% FILTER filter %] text... [% END %]
* [% JAVASCRIPT %] code... [% END %]
* [% WRAPPER template [variable = value ...] %]
* [% IF condition %]
* [% ELSIF condition %]
* [% ELSE %]
* [% SWITCH variable %]
* [% CASE [{value|DEFAULT}] %]
* [% FOR x = y %]
* [% WHILE expression %]
* [% RETURN %]
* [% THROW type message %]
* [% STOP %]
* [% NEXT %]
* [% LAST %]
* [% CLEAR %]
* [%# this is a comment %]</pre>
<p>ALL of the string virtual functions are supported.</p>
<p>ALL of the array virtual functions are supported:</p>
<p>ALL of the hash virtual functions are supported (except for import):</p>
<p>MANY of the standard filters are implemented.</p>
<p>The remaining features will be added very soon. See the DESIGN document
in the distro for a list of all features and their progress.</p>
<p>
</p>
<hr />
<h1><a name="browser_support">BROWSER SUPPORT</a></h1>
<p>Tested successfully in:</p>
<pre>
* Firefox Mac/Win32/Linux
* IE 6.0
* Safari
* Opera
* Konqueror</pre>
<p>All tests run 100% successful in the above browsers.</p>
<p>
</p>
<hr />
<h1><a name="development">DEVELOPMENT</a></h1>
<p>The bleeding edge code is available via Subversion at
<a href="http://svn.jemplate.net/repo/trunk/">http://svn.jemplate.net/repo/trunk/</a></p>
<p>You can run the runtime tests directly from
<a href="http://svn.jemplate.net/repo/trunk/tests/run/index.html">http://svn.jemplate.net/repo/trunk/tests/run/index.html</a> or from the
corresponding CPAN or JSAN directories.</p>
<p>Jemplate development is being discussed at <a href="irc://irc.freenode.net/#jemplate">irc://irc.freenode.net/#jemplate</a></p>
<p>If you want a committer bit, just ask ingy on the irc channel.</p>
<p>
</p>
<hr />
<h1><a name="credit">CREDIT</a></h1>
<p>This module is only possible because of Andy Wardley's mighty Template
Toolkit. Thanks Andy. I will gladly give you half of any beers I
receive for this work. (As long as you are in the same room when I'm
drinking them ;)</p>
<p>
</p>
<hr />
<h1><a name="authors">AUTHORS</a></h1>
<p>Ingy döt Net <<a href="mailto:ingy@cpan.org">ingy@cpan.org</a>></p>
<p>(Note: I had to list myself first so that this line would go into META.yml)</p>
<p>Jemplate is truly a community authored project:</p>
<p>Ingy döt Net <<a href="mailto:ingy@cpan.org">ingy@cpan.org</a>></p>
<p>Tatsuhiko Miyagawa <<a href="mailto:miyagawa@bulknews.net">miyagawa@bulknews.net</a>></p>
<p>Yann Kerherve <<a href="mailto:yannk@cpan.org">yannk@cpan.org</a>></p>
<p>David Davis <<a href="mailto:xantus@xantus.org">xantus@xantus.org</a>></p>
<p>Cory Bennett <<a href="mailto:coryb@corybennett.org">coryb@corybennett.org</a>></p>
<p>Cees Hek <<a href="mailto:ceeshek@gmail.com">ceeshek@gmail.com</a>></p>
<p>Christian Hansen</p>
<p>David A. Coffey <<a href="mailto:dacoffey@cogsmith.com">dacoffey@cogsmith.com</a>></p>
<p>Robert Krimen <<a href="mailto:robertkrimen@gmail.com">robertkrimen@gmail.com</a>></p>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>Copyright (c) 2006-2008. Ingy döt Net.</p>
<p>This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.</p>
<p>See <a href="http://www.perl.com/perl/misc/Artistic.html">http://www.perl.com/perl/misc/Artistic.html</a></p>
</body>
</html>